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

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

• Статус документа: working reference
• Актуально на: 1 апреля 2026 года
• Владелец: backend/platform-команда
• Пересмотр: при изменении структуры документации, индексов или source-of-truth набора
• Область применения: главный индекс канонической документации проекта в qadam-core/docs
• Связанные документы:
  • Текущее состояние
  • Roadmap
  • Стандарт документации

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

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

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

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

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

Архив implementation plans

• Каталог ../plans/README.md описывает архивный статус historical implementation plans.
• Обработанные и уже инкорпорированные планы перемещены в ../plans/archived/2026-03-28-integrated/README.md.
• Эти файлы больше не считаются каноническими сами по себе; текущая интерпретация и статус каждого плана зафиксированы в 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.
• При документальных изменениях прогоняй 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-документе.