# Документация проекта Qadam

## Паспорт документа

- Статус документа: working reference
- Актуально на: 1 апреля 2026 года
- Владелец: backend/platform-команда
- Пересмотр: при изменении структуры документации, индексов или source-of-truth набора
- Область применения: главный индекс канонической документации проекта в `qadam-core/docs`
- Связанные документы:
  - [Текущее состояние](./project/current-state.md)
  - [Roadmap](./project/roadmap.md)
  - [Стандарт документации](./governance/documentation-standard.md)

Этот каталог содержит каноническую русскоязычную документацию по проекту. Если документы в других папках расходятся с этим разделом, источником истины считаются файлы из `docs/` и актуальные `specs/`.

В roadmap-портале относительные markdown-ссылки между `docs`, `specs` и `docs/Agents` должны оставаться рабочими. Если документ выпадает из этой навигации, это считается документальным дефектом, а не допустимым состоянием.

## Структура каталога

- `project/` — текущее состояние, требования, roadmap, glossary, execution checkpoints и project changelog
- `architecture/` — API, conventions, Prisma, observability, стек и frontend data patterns
- `frontend/` — handoff, change-log и operating model для отдельной frontend-команды
- `operations/` — runbook, environment matrix, backup/restore, incident response и infra migration
- `governance/` — инженерные правила, ownership, change-package process и передаваемость проекта
- `audits/` — security review, contradictions registry и audits historical plans
- `product/` — прикладные требования к крупным backend/API потокам
- `Agents/` — внутренняя инженерная база знаний, rules и feature backlog
- `quality_report.md` и `engineering_log.md` — append-only журналы встроенных агентов

## Основные документы

- [current-state.md](./project/current-state.md) — фактическое состояние проекта, инфраструктуры и доменов
- [requirements.md](./project/requirements.md) — текущие продуктовые и инженерные требования
- [glossary.md](./project/glossary.md) — канонический словарь ролей, сущностей, статусов и deprecated терминов
- [requirements-api-registration.md](./product/requirements-api-registration.md) — целевые требования к registration API и buyer/seller onboarding
- [roadmap.md](./project/roadmap.md) — стратегический roadmap и ближайший план разработки
- [execution-checkpoints.md](./project/execution-checkpoints.md) — поэтапный контроль исполнения roadmap с маркировкой факта выполнения
- [project-change-log.md](./project/project-change-log.md) — хронология change packages уровня платформы, runtime и документации
- [deployment-runbook.md](./operations/deployment-runbook.md) — эксплуатация, деплой, перезапуск, rollback, SSL
- [stage-delivery-model.md](./operations/stage-delivery-model.md) — каноническая модель: локально готовим change packages, stage забирает `main` внешним автодеплоем
- [verification-server-bootstrap.md](./operations/verification-server-bootstrap.md) — быстрый runbook поднятия отдельного проверочного сервера с backend и product web
- [backup-restore-runbook.md](./operations/backup-restore-runbook.md) — автоматизированный backup baseline, off-host retention и канонический restore-процесс
- [incident-response.md](./operations/incident-response.md) — порядок действий при production-инцидентах
- [environment-matrix.md](./operations/environment-matrix.md) — env/secrets/access boundaries по сервисам
- [post-deploy-checklist.md](./operations/post-deploy-checklist.md) — обязательный checklist после production-релиза
- [plans-audit-2026-03-28.md](./audits/plans-audit-2026-03-28.md) — аудит исторических implementation plans из `plans/` и их связь с текущим состоянием
- [documentation-audit-2026-03-28.md](./audits/documentation-audit-2026-03-28.md) — профессиональный аудит текущего документационного слоя: сильные стороны, пробелы и следующий backlog по docs
- [qadam-contradictions-registry.md](./audits/qadam-contradictions-registry.md) — исторический реестр противоречий между ранними спеками и их каноническая нормализация
- [stack-assessment-2026-03-27.md](./architecture/stack-assessment-2026-03-27.md) — заключение по текущему стеку и его пригодности для дальнейшего развития
- [engineering-principles.md](./governance/engineering-principles.md) — канонические инженерные правила проекта: передаваемость, тесты, документация, границы и Definition of Done
- [documentation-standard.md](./governance/documentation-standard.md) — обязательный стандарт оформления, lifecycle и навигации для канонического markdown-слоя
- [change-package-standard.md](./governance/change-package-standard.md) — как выглядит обязательный change package от реализации до changelog и checkpoint update
- [ownership-model.md](./governance/ownership-model.md) — карта владельцев, зон ответственности и правил совместного согласования
- [frontend-separate-repo-plan.md](./frontend/frontend-separate-repo-plan.md) — статус и следующий этап после выделения frontend в отдельный репозиторий
- [frontend-handoff.md](./frontend/frontend-handoff.md) — рабочий handoff для frontend-команды: git, OpenAPI, env, auth и контрактный workflow
- [frontend-change-log.md](./frontend/frontend-change-log.md) — обязательный changelog для frontend-команды по backend endpoint packages и migration notes
- [frontend-adoption-backlog.md](./frontend/frontend-adoption-backlog.md) — текущий remediation backlog `qadam-web`: contract drift, type debt и quality blockers на стороне frontend
- [frontend-mvp-cto-backend-handoff-2026-04-14.md](./frontend/frontend-mvp-cto-backend-handoff-2026-04-14.md) — handoff по MVP-контрактам CTO: buyer profile, children, leads, staff и public seller profile
- [frontend-package-discounts-handoff-2026-04-15.md](./frontend/frontend-package-discounts-handoff-2026-04-15.md) — handoff по пакетным скидкам и promo text через `ItemPriceVariant`
- [frontend-training-type-handoff-2026-04-15.md](./frontend/frontend-training-type-handoff-2026-04-15.md) — handoff по полю `trainingType` для seller items и фильтрации каталога
- [analytics-observability.md](./architecture/analytics-observability.md) — текущий observability-контур: Pino, Axiom, EventLog, tracking и аналитические ограничения
- [prisma-data-layer.md](./architecture/prisma-data-layer.md) — каноническое описание Prisma-пакета, схемы данных, миграций, seed и правил работы с data layer
- [api-conventions.md](./architecture/api-conventions.md) — общие правила поведения API: auth, errors, backward compatibility и frontend contract discipline
- [openapi-gaps.md](./architecture/openapi-gaps.md) — контроль OpenAPI coverage; по состоянию на 30 марта 2026 года активных frontend-значимых response gaps больше нет
- [docker-contour-migration-plan.md](./operations/docker-contour-migration-plan.md) — детальный план перехода проекта на управляемый docker-контур
- [security-review.md](./audits/security-review.md) — закрытое ревью безопасности и принятые hardening-решения
- [api-routes.md](./architecture/api-routes.md) — актуальная карта API-маршрутов и точки входа OpenAPI/Swagger
- [tanstack-query.md](./architecture/tanstack-query.md) — паттерн работы с серверным состоянием во frontend

## Документы для отдельной frontend-команды

- [frontend-handoff.md](./frontend/frontend-handoff.md) — практическая памятка для команды, которая ведёт `qadam-web`
- [frontend-change-log.md](./frontend/frontend-change-log.md) — change-log backend-пакетов, которые frontend должен внедрять по очереди; этот же документ питает frontend-блок на `qadam-roadmap.2fab.app`
- [frontend-adoption-backlog.md](./frontend/frontend-adoption-backlog.md) — текущие красные зоны `qadam-web`, которые фронту нужно закрыть после handoff backend-контрактов
- [frontend-mvp-cto-backend-handoff-2026-04-14.md](./frontend/frontend-mvp-cto-backend-handoff-2026-04-14.md) — точный контрактный handoff по MVP-изменениям CTO на стороне backend
- [frontend-package-discounts-handoff-2026-04-15.md](./frontend/frontend-package-discounts-handoff-2026-04-15.md) — контрактный handoff по скидкам и promo text на пакетах занятий
- [frontend-training-type-handoff-2026-04-15.md](./frontend/frontend-training-type-handoff-2026-04-15.md) — контрактный handoff по полю `trainingType` и фильтру `Тип обучения`
- [frontend-separate-repo-plan.md](./frontend/frontend-separate-repo-plan.md) — operating model и оставшийся post-cutover план по split-репозиториям
- [execution-checkpoints.md](./project/execution-checkpoints.md) — какие этапы backend/platform уже реально закрыл и что ещё ждёт frontend-команду
- [project-change-log.md](./project/project-change-log.md) — общая хронология change packages, которые уже прошли через платформу
- [engineering-principles.md](./governance/engineering-principles.md) — обязательные правила передачи проекта, тестирования и документации
- [api-routes.md](./architecture/api-routes.md) — человекочитаемая карта backend API

## Продуктовые спеки

- [./Agents/README.md](./Agents/README.md) — детализированный инженерный backlog, база знаний и rules-index для команды
- [../specs/qadam-platform/design.md](../specs/qadam-platform/design.md) — продуктовый и архитектурный контур платформы
- [../specs/qadam-platform/implementation.md](../specs/qadam-platform/implementation.md) — статус реализации по ключевым областям
- [../specs/qadam-platform/decisions.md](../specs/qadam-platform/decisions.md) — архитектурные решения
- [../specs/qadam-platform/future-work.md](../specs/qadam-platform/future-work.md) — осознанно отложенные направления
- [./Agents/product-roadmap.md](./Agents/product-roadmap.md) — детализированный feature-checklist по MVP и следующим фазам

## Архив implementation plans

- Каталог [../plans/README.md](../plans/README.md) описывает архивный статус historical implementation plans.
- Обработанные и уже инкорпорированные планы перемещены в [../plans/archived/2026-03-28-integrated/README.md](../plans/archived/2026-03-28-integrated/README.md).
- Эти файлы больше не считаются каноническими сами по себе; текущая интерпретация и статус каждого плана зафиксированы в [plans-audit-2026-03-28.md](./audits/plans-audit-2026-03-28.md).

## Как поддерживать документацию

- Обновляй `project/current-state.md` после заметных изменений в инфраструктуре, деплое, доменах, сервисах и статусе модулей.
- Обновляй `project/requirements.md` при изменении требований к MVP, ролям, качественным воротам и бизнес-приоритетам.
- Обновляй `project/roadmap.md` после завершения этапов, изменения приоритетов и выбора следующего инженерного пакета.
- Обновляй `project/execution-checkpoints.md` всякий раз, когда change package меняет фактический статус этапа.
- Добавляй запись в `project/project-change-log.md` для каждого завершённого change package.
- Новый канонический документ сразу оформляй по [documentation-standard.md](./governance/documentation-standard.md).
- При документальных изменениях прогоняй `pnpm check:docs`.
- Если меняется `architecture/openapi-gaps.md`, синхронно обновляй `project/roadmap.md`, `project/execution-checkpoints.md` и при frontend-влиянии `frontend/frontend-change-log.md`.
- Если фича реализуется по `specs/`, синхронно обновляй `implementation.md` и при необходимости `decisions.md`.
- После переноса выводов из промежуточных планов либо удаляй их, либо явно переводи в архивный статус с фиксацией в audit-документе.