Документация разработчика SKUARO¶

Статус: ДЕЙСТВУЕТ КАК НАВИГАЦИЯ ПО PRODUCT-РЕПОЗИТОРИЮ

Последняя фактическая проверка: 2026-08-23.

Эта страница — единая точка входа для разработчика до создания отдельного приватного webuzateam/SkuAro-Docs и сайта dev-doc.skuaro.top. Полный сайт документации временно не дублируется внутри product-репозитория.

С чего начать¶

Прочитать AGENTS.md и PROJECT_POLICY.md.
Проверить текущий этап и следующий шаг в STATUS.md.
Перед продвижением в STAGE проверить STAGE_TESTING_STRATEGY.md.
Сверить границы продукта в PROJECT_CONTEXT.md.
Для изменения кода, данных или runtime прочитать ARCHITECTURE.md и IMPLEMENTATION_PLAN.md.
Для межагентной задачи проверить доказательный workflow.
Для делегирования проверить роли AI-агентов.
Для повторяемой задачи проверить память агентов и Skills.
Для существенного решения проверить актуальные ADR.

Техническая карта¶

Область	Источник истины
Frontend composition и маршруты	`apps/web`, `UI_SYSTEM.md`
Product module «Сегодня»	`modules/today/README.md`, `modules/today/module.yaml`
Platform Auth	`platform/auth/web`, `platform/auth/server`
Platform Admin, Account и Organizations	`platform/admin`, `platform/account`, `platform/organizations/README.md`
API composition	`apps/api`, сгенерированный OpenAPI
Gmail integration	`integrations/email/README.md`
Контракты	`packages/contracts`
PostgreSQL и миграции	`packages/database/src/schema.ts`, `packages/database/drizzle`
Worker и pg-boss	`apps/worker`
Локальная PostgreSQL	`infra/compose/README.md`
DEV/STAGE deploy	`infra/deploy/README.md`
Резервирование	`BACKUP.md`
Секреты без значений	`SECRETS.md`
Расширения и восстановление	`INTEGRATIONS.md`
Память агентов и Skills	`AGENT_MEMORY_AND_SKILLS.md`, `.agents/skills`
Доказательная приёмка и handoff	`AGENT_WORKFLOW.md`, `.agents/skills/task-verification`
Профили и маршрутизация subagents	`AGENT_ROLES.md`, `.codex/agents`
Правила документации	`DOCUMENTATION_STRATEGY.md`

Локальный запуск¶

Минимально поддерживаются Node.js >=24 и npm >=11; точная patch-версия не закреплена.

npm install
npm run toolchain:check
npm run compose:up
npm run dev:api
npm run dev:worker
npm run dev

Локальная PostgreSQL требует игнорируемый .env по инструкции infra/compose/README.md. Реальные клиентские данные в DEV и тестах запрещены.

Основные проверки¶

npm run lint
npm run boundaries:check
npm run typecheck
npm run test:unit
npm run test:integration
npm run test:coverage
npm run build
npm run build:storybook
npm run openapi:verify
npm run test:e2e
npm run test:visual
npm audit --omit=dev --omit=optional

npm run check выполняет основной локальный набор без обязательного запуска PostgreSQL integration. Эталонные скриншоты обновляются только после осознанного UI-изменения.

Playwright использует отдельные loopback-порты: E2E 4273, visual 4274. Их можно переопределить через SKUARO_E2E_PORT и SKUARO_VISUAL_PORT; готовый чужой процесс не переиспользуется.

Правило модульных границ¶

apps/* подключают только публичные index модулей, platform capabilities и integrations.
Продуктовый код «Сегодня» изменяется внутри modules/today; общие UI-примитивы остаются в packages/ui.
Общая авторизация не зависит от конкретного продукта и живёт в platform/auth; Gmail реализует её email-контракт через integrations/email.
Перед новой функцией определяется её класс, данные, permissions, зависимости и точки интеграции. Необязательные папки заранее не создаются.
После изменения структуры обязательно выполнить npm run boundaries:check, typecheck, unit, build, Storybook, E2E и visual checks.

DEV API¶

Фактический product DEV: https://dev.skuaro.top публично открывает /, Auth-страницы и необходимые Auth API; /settings, /today, /admin/* проверяют SKUARO session и backend access contract.
Swagger UI: https://dev.skuaro.top/api/docs/ доступен для тестов без Basic Auth; добавлять серверный пароль можно только по отдельному запросу владельца.
Liveness: /api/health/live.
Readiness: /api/health/ready.
Auth: /api/v1/auth/*; внутренний Fastify-путь после proxy — /v1/auth/*.

OpenAPI генерируется из контрактов и не редактируется вручную. Проверка drift выполняется командой npm run openapi:verify.

DEV deploy и миграции¶

DEV и STAGE являются разными Compose projects, базами, volumes, credentials и runtime config. Во время текущей разработки владелец отдельно запретил обновлять STAGE.

Решение 0019 разрешает сохранять в ветке и на сервере STAGE исходники, checkout, .git, тесты, миграции, внутреннюю документацию и инструменты, когда они нужны выбранному процессу сборки, проверки или диагностики. Секреты и реальные клиентские данные по-прежнему запрещены.

Решение 0020 определяет будущий trigger: после активации pipeline разрешённый merge DEV -> STAGE автоматически запускает deploy и gates. На 2026-08-23 pipeline не активирован, поэтому этот документ не разрешает самостоятельно создавать ветку, менять GitHub или обновлять сервер.

Порядок DEV-изменения:

Создать проверяемый logical dump до миграции.
Собрать новый content-addressed worktree artifact и images.
Проверить Compose и Caddy до переключения.
Применить журналируемые Drizzle-миграции одноразовым сервисом migrate.
Дождаться health checks API и web, проверить worker и PostgreSQL.
Выполнить внутренний и внешний HTTPS smoke.
Сохранить rollback-конфигурацию; не удалять volume автоматически.

Фактический DEV release на 2026-08-22: worktree-9f9113f60287. STAGE остаётся на worktree-3d10591aed41 и не изменялся.

Auth и Gmail DEV¶

Auth runtime, PostgreSQL-схема и Gmail credentials настроены в DEV. Значения находятся только во внешнем хранилище владельца и root-only server .env; в Git и документацию они не копируются.

Исходящие соединения тестового сервера к smtp.gmail.com:587 и :465 сейчас завершаются таймаутом. До ответа хостинга нельзя считать проверенными SMTP AUTH, доставку письма и реальный sign-up → email verify → login. Повторный тест выполняется только после подтверждения открытия исходящего порта 587.

Первый SuperAdmin пустого контура создаётся только операторской командой bootstrap:super-admin по решению 0017. Она получает email и пароль из отдельного внешнего secret-файла, отказывается от коллизий и не является штатным интерфейсом управления ролями. Значения credential и временный server-файл не сохраняются в product runtime.

Первая DEV-учётная запись создана этим способом и проверена через login/access/revoke. /admin/organizations показывает три синтетические организации только для визуальной оценки; это не PostgreSQL-данные и не замена будущим Organization/Membership.

Документирование изменения¶

Текущее состояние обновляется в docs/STATUS.md.
Причина существенного выбора фиксируется ADR.
Заметное пользователю изменение добавляется в docs/CHANGELOG.md.
Содержательная сессия получает краткий log в logs/sessions.
Документ описывает только фактически проверенный результат и отдельно помечает отложенные действия.