Перейти к содержанию

Стратегия документации SKUARO

Статус: ПРИНЯТА

Обновлено: 2026-08-26.

Цель

Документация разделяется по аудитории и не превращает product-репозиторий в хранилище копий одних и тех же сведений.

  • User docs отвечают на вопрос: «Как человеку выполнить задачу в SKUARO?»
  • Developer docs отвечают на вопрос: «Как безопасно понять, изменить, проверить, развернуть и восстановить SKUARO?»
  • Product-репозиторий остаётся источником истины для кода, решений, контрактов, миграций и текущего статуса.

Репозиторий документации

Согласован отдельный приватный webuzateam/SkuAro-Docs:

user-docs/
  mkdocs.yml
  docs/
dev-docs/
  mkdocs.yml
  docs/
shared/
  overrides/
  assets/

Технология — open-source Material for MkDocs 9.x без обязательных Insiders-функций. Точные Python-зависимости и container image фиксируются для воспроизводимой сборки. Русский является исходным языком; английская локализация добавляется позднее отдельными locale-каталогами.

Приватный repository webuzateam/SkuAro-Docs создан 2026-08-26. Developer snapshot собран и установлен в изолированный loopback-only runtime тестового сервера. Защищённый STAGE origin dev-doc.skuaro.top активен: A-record опубликована, HTTPS-сертификат выпущен, а guest/authenticated access, security headers, search и ключевые content routes прошли обязательный external smoke.

Пользовательская документация

STAGE-публикация: публичный для тестов doc.skuaro.top с noindex. Production-публикация: публичный doc.skuaro.com.

Первый состав:

  1. Что такое SKUARO и для каких задач он предназначен.
  2. Самостоятельная регистрация, подтверждение email и первый вход.
  3. Настройка организации и часового пояса.
  4. Экран «Сегодня».
  5. Добавление клиента и обращения.
  6. Назначение и завершение следующего действия.
  7. Карточка клиента и история обращений в доступной MVP-границе.
  8. Профиль, пароль и активные сессии.
  9. Восстановление доступа.
  10. FAQ, обращение в поддержку и известные ограничения.
  11. Release notes по production-версиям продукта.

User docs не содержат internal hostnames, server paths, credentials, схемы секретов, инструкции обхода доступа или необязательные технические детали реализации.

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

Публикация: отдельный публичный для тестов контур на dev-doc.skuaro.top с noindex и без Basic Auth. Контур не имеет доступа к базе данных продукта. Исходники и служебные файлы могут оставаться на тестовом сервере, если они нужны процессу сборки и проверки; секреты в репозиторий и собранную документацию не попадают.

Первый состав:

  1. Onboarding и требования к локальной среде.
  2. Архитектура и индекс ADR.
  3. Доменная модель и инварианты.
  4. Структура монорепозитория и направление зависимостей.
  5. Frontend: router, state, forms, UI-kit, Storybook и visual baselines.
  6. Backend: модули, application services, repositories и contracts.
  7. API и сгенерированный OpenAPI.
  8. PostgreSQL, Drizzle, миграции и tenant isolation.
  9. Авторизация, сессии, роли и аудит.
  10. Outbox, worker, pg-boss, retry и dead-letter.
  11. AI/provider boundary и правила безопасного использования.
  12. Тестирование: unit, integration, migration, E2E и restore.
  13. Среды, runtime config, secrets map без значений.
  14. Deploy, promotion, rollback, backup и monitoring.
  15. Security checklist и работа без реальных данных в DEV/STAGE.
  16. Troubleshooting и release process.
  17. Система AI-агентов: профили и маршрутизация, доказательный handoff, внешний UI-reference workspace, общая память опыта и жизненный цикл project Skills.
  18. Production readiness: отдельная команда, standards applicability matrix, repair loop, независимый GO/NO-GO и граница фактического PROD deploy.

Для каждого реализованного продуктового модуля публикуется раздел «Модули / <название>»: назначение, границы, архитектура, данные, API, permissions, тестирование и диагностика. Связанное с кодом содержимое может исходно жить в product modules/<module-id>/docs и попадать в Docs-сайт как версионированный артефакт.

Доступ внешнего UI/UX-агента

После публикации владелец предоставляет внешнему UI/UX-агенту доступ ко всему developer-сайту как к контексту проекта. Отдельная урезанная версия документации не создаётся. До публикации сайта задача может быть запущена по решению 0028, если TASK.md перечисляет точный снимок и нужные материалы product-репозитория. В обоих случаях действуют общие ограничения: секреты, реальные данные и значения credentials агенту не передаются.

Текущая задача агенту хранится в product docs/ui-agent/TASK.md; результаты — в docs/ui-agent/results/, а явно принятая владельцем визуальная память — в docs/ui-agent/memory/ACCEPTED.md. При публикации developer docs эти материалы могут передаваться как versioned artifacts. Внешний агент предлагает изменения памяти через MEMORY_DELTA.md, а task state, принятую memory и Product-код меняет внутренняя команда.

Шаблон developer-страницы

Каждая практическая инструкция содержит:

  1. Цель и область действия.
  2. Когда инструкция применима и когда неприменима.
  3. Предварительные условия и необходимые разрешения.
  4. Точные команды или последовательность действий.
  5. Ожидаемый проверяемый результат.
  6. Безопасность и недопустимые данные.
  7. Откат или восстановление.
  8. Типовые ошибки и диагностику.
  9. Версию продукта/инструмента и дату последней фактической проверки.

Предложения агента, выбранные defaults и подтверждённые пользователем решения помечаются раздельно. Непроверенная команда не описывается как рабочая.

Источники истины

Информация Канонический источник
Текущий этап и следующий шаг product docs/STATUS.md
Текущая UI/UX-reference задача и результаты product docs/ui-agent/
Архитектурное решение и причины product docs/decisions/
Общая техническая схема product docs/ARCHITECTURE.md
API product contracts и сгенерированный OpenAPI
База данных Drizzle schema и сохранённые SQL-миграции
Runtime и deploy product infra/ и runbooks
Пользовательская инструкция Docs user-docs/docs
Руководство разработчика Docs dev-docs/docs и сгенерированные product-артефакты
Публичное описание продукта Site-репозиторий
Версия продукта Git tag и release metadata product-репозитория

Данные не переписываются вручную в нескольких источниках. Developer docs ссылаются на ADR, а OpenAPI публикуется как сгенерированный артефакт.

Ветви и публикация

В каждом репозитории используется модель DEV -> STAGE -> PROD, но продвижение выполняется независимо.

  • Developer docs из подтверждённой ветки публикуются на dev-doc.skuaro.top.
  • User docs проходят build и link checks в DEV и публикуются из STAGE на защищённый doc.skuaro.top.
  • Публичная публикация user docs выполняется только из PROD на doc.skuaro.com.
  • Landing из Site/PROD публикуется на skuaro.com.

Связь с релизами

Изменение поведения продукта не продвигается в production, пока:

  • обновлена затронутая пользовательская инструкция;
  • добавлена понятная release note;
  • user docs успешно собраны и проверены;
  • указана поддерживаемая production-версия продукта.

Техническая release record хранится в product-репозитории, например docs/releases/26.08.21.01.md. Понятная пользователю запись хранится в Docs-репозитории, например release-notes/26.08.21.01.md.

Изменения только лендинга или документации не повышают CalVer продукта.

Проверки документации

До публикации обязательны:

  • успешная сборка Material for MkDocs;
  • проверка внутренних и внешних ссылок;
  • secret scan без вывода значений;
  • отсутствие внутренних URL и server paths в user docs;
  • mobile layout и keyboard navigation;
  • корректный поиск;
  • корректные noindex и access headers для developer docs;
  • указание актуальной версии и даты проверки для эксплуатационных инструкций.

Граница текущего product-репозитория

До создания Docs-репозитория здесь сохраняются архитектура, ADR, policy, status и план документации. Полный сайт документации не создаётся временно внутри product-репозитория, чтобы потом не переносить историю и deploy-конфигурацию.