# Инженерные принципы и правила ведения разработки ## Паспорт документа - Статус документа: living standard - Актуально на: 30 марта 2026 года - Владелец: backend/platform-команда - Пересмотр: при изменении правил разработки, ownership-модели или документационного процесса - Область применения: нормативный слой инженерных и документационных правил проекта - Связанные документы: - [Индекс документации](../README.md) - [Roadmap](../project/roadmap.md) - [Аудит документации](../audits/documentation-audit-2026-03-28.md) ## Цель документа Этот документ фиксирует обязательные инженерные правила Qadam. Проект должен развиваться так, чтобы его можно было без болезненной потери контекста передать другой команде, масштабировать и сопровождать без зависимости от отдельных людей. Это не рекомендательный текст, а канонический набор принципов, по которым принимаются архитектурные, процессные и эксплуатационные решения. ## Главный принцип Qadam должен строиться как **передаваемая система**, а не как проект, который держится на памяти текущей команды. Это означает: - знания должны жить в коде, тестах, контрактах и документации; - production не должен зависеть от ручных действий “только этот человек знает как”; - новая команда должна иметь возможность понять архитектуру, запустить проект, проверить изменения и безопасно продолжить разработку. ## 1. Принцип передаваемости Любое важное решение должно быть воспроизводимо и объяснимо без устных договорённостей. ### Обязательные следствия - нет скрытых серверных правок, которые не отражены в документации; - нет критичных процессов, завязанных на локальную память одного разработчика; - нет неописанных env-переменных, доменов, секретных зависимостей и обходных путей; - новая команда должна получить проект вместе с runbook, roadmap, требованиями, контрактами и тестовым контуром. ## 2. Один источник истины У проекта должен быть понятный слой канонической документации. ### Канонические документы - `docs/project/current-state.md` — реальное состояние платформы и инфраструктуры; - `docs/project/requirements.md` — текущие продуктовые и инженерные требования; - `docs/project/roadmap.md` — стратегический и ближайший план; - `docs/project/execution-checkpoints.md` — поэтапный фактический статус реализации; - `docs/project/project-change-log.md` — отдельный changelog завершённых change packages; - `docs/operations/deployment-runbook.md` — текущая эксплуатационная модель; - `docs/architecture/api-routes.md` и далее OpenAPI/Swagger — канонический API-контракт; - `docs/governance/documentation-standard.md` — обязательный стандарт структуры и lifecycle канонических markdown-документов; - `docs/governance/change-package-standard.md` — обязательный процесс упаковки, проверки и документирования change package; - `docs/frontend/frontend-change-log.md` — обязательный change-log для frontend-команды по backend API changes; - `specs/` — детальные решения по конкретным направлениям. ### Правило Если код, инфраструктура и документация расходятся, это считается дефектом проекта, а не “нормальной ситуацией”. ## 3. Русский язык как канонический язык документации Вся каноническая проектная документация должна вестись на русском языке. Это касается: - roadmap; - runbook; - текущего состояния; - инженерных требований; - правил разработки; - проектных планов migration; - продуктовых и архитектурных документов в каноническом слое. ### Допустимые исключения - технические термины, если русская замена ухудшает точность; - имена технологий, библиотек, паттернов и API; - код, команды, имена переменных, типов и интерфейсов. ### Недопустимо - держать канонический документ наполовину на русском, наполовину на английском; - создавать новый важный документ вне `docs/`, если он претендует на роль источника истины; - сохранять устаревшие англоязычные черновики как “равноправные” версии канонического документа. ### Дополнительное правило по change management Commit messages и итоговые squash merge messages для канонических репозиториев проекта должны формулироваться на русском языке. Допускается сохранять технические префиксы и scope в conventional commit-стиле, например `feat(api): ...`, но смысловая часть сообщения должна оставаться русскоязычной и описывать уже достигнутый результат, а не намерение. Предпочтительная форма: `добавлен`, `исправлен`, `стабилизирован`, `синхронизированы`, `вынесен`, `переведён`. ## 4. Контрактность и явные границы Проект должен быть разделён на части с явными границами, а не на “удобные на сегодня” импорты между внутренними слоями. ### Обязательные правила - frontend и backend взаимодействуют через явный API-контракт; - DTO, response shape и auth-flow должны быть формализованы; - переход к OpenAPI/Swagger обязателен для дальнейшего роста команды; - нельзя плодить ручные frontend-типы, если уже есть канонический backend-контракт; - нельзя усиливать связанность frontend с внутренними backend/workspace-исходниками, если проект должен быть готов к repo split. ## 5. Тесты обязательны, а не желательны Проект должен покрываться тестами детально. Отсутствие тестов на критичные участки считается техническим долгом высокого приоритета. ### Обязательная модель покрытия #### Unit Unit-тесты обязательны для: - бизнес-логики сервисов; - auth-flow; - статусных моделей; - критичных преобразований данных; - доменных инвариантов; - багфиксов, которые уже однажды ломались. #### Integration Интеграционные тесты обязательны для: - ключевых HTTP endpoint; - auth refresh и logout; - buyer/seller/admin критичных сценариев; - модулей с нетривиальной работой с БД; - миграционных и контрактных сценариев, где unit-тест недостаточен. #### E2E / Smoke E2E или минимальный smoke-контур обязателен для: - публичного каталога; - карточки айтема; - login / refresh / logout; - buyer profile flow; - seller item flow; - admin moderation; - production health-проверок после деплоя. ### Жёсткое правило Каждый исправленный production-баг должен сопровождаться регрессионной проверкой того уровня, на котором этот баг реально проявлялся. ## 6. Документация обновляется вместе с кодом Если изменение влияет на архитектуру, контракты, инфраструктуру, эксплуатацию или roadmap, документация обновляется в том же пакете работ. ### Обязательно обновлять - `current-state.md` — если поменялась реальная инфраструктура, домены, сервисы, контур деплоя; - `requirements.md` — если поменялись инженерные или продуктовые требования; - `roadmap.md` — если меняется последовательность больших пакетов разработки; - `execution-checkpoints.md` — если change package меняет фактический статус этапа; - `project-change-log.md` — если завершён значимый change package; - `deployment-runbook.md` — если меняется эксплуатационная модель; - `api-routes.md` и OpenAPI — если меняется API-контракт; - `frontend-change-log.md` — если меняются endpoint'ы, response shape, auth-поведение или другой frontend-значимый API-контракт; - frontend feedback loop на `qadam-roadmap.2fab.app` — если backend-пакет требует действий от frontend-команды и должен попасть в живой operational board; - `documentation-standard.md` — если меняется обязательная структура, lifecycle или quality gate документационного слоя; - `specs/` — если реализация изменила согласованное проектное решение. ### Недопустимо - “сделаем потом” для документации на изменениях, которые уже повлияли на систему; - держать актуальное состояние только в сообщениях чата или в голове команды; - вносить infra/API change без синхронного обновления канонических docs. ## 7. Definition of Done для каждой значимой задачи Задача считается завершённой только если одновременно выполнены условия: 1. Код написан и проходит релевантную сборку. 2. Добавлены или обновлены тесты нужного уровня. 3. Обновлена каноническая документация на русском языке. 4. Если затронут API, обновлён контракт. 5. Если API-изменение затрагивает frontend-команду, обновлён `frontend-change-log.md`. 6. Если frontend должен выполнить действия по этому пакету, пакет опубликован в frontend-блоке на `qadam-roadmap.2fab.app`, а не остаётся только текстом в changelog. 7. Если затронута инфраструктура, обновлён runbook и текущее состояние. 8. Обновлён `project-change-log.md`, а если этап сдвинулся — `execution-checkpoints.md`. 9. Репозиторный quality gate пройден там, где он существует. 10. Есть понятный rollback или хотя бы оценка риска отката. 11. Изменение может понять другой разработчик без устного сопровождения автора. ## 8. Принципы архитектуры и кода ### Архитектура - предпочитать явные модули и вертикальные срезы вместо хаотичных cross-import; - избегать скрытой связанности через общие внутренние пакеты без долгосрочного плана; - проектировать систему с учётом будущего frontend repo split и docker-контура; - делать transport contract независимым от внутренней структуры репозитория. ### Код - код должен быть читаемым без археологии по пяти файлам; - сложные решения должны сопровождаться кратким объяснением, если без него контекст теряется; - нельзя тащить legacy-паттерны в новый слой просто потому, что “так уже было”; - багфикс без понимания причины считается незавершённой работой. ## 9. Инфраструктурные принципы - production не должен зависеть от ручной сборки “как получится”; - целевая модель — воспроизводимый image-based delivery и управляемый docker-контур; - rollout и rollback должны быть описаны явно; - домены, TLS, ingress, env и service topology должны быть документированы; - server state должен быть минимально “снежинкой” и максимально воспроизводимым. ## 10. Правила code review и change management Каждый нетривиальный change оценивается не только по “работает у меня”, но и по следующим критериям: - не усиливает ли он связанность; - не создаёт ли новый неописанный контур; - не ломает ли передаваемость проекта; - достаточно ли покрыт тестами; - обновлены ли docs; - не создал ли он новый drift между кодом и документацией. Repo-side automation не заменяет review. Машинный quality gate и human review считаются двумя разными обязательными слоями. ### Обязательный security review Для следующих зон security review обязателен даже если unit-тесты и build зелёные: - auth, JWT, refresh/logout, cookies и session delivery; - permissions, roles, guards и access boundaries; - uploads, file storage и публичная раздача файлов; - secrets, env, proxy trust, rate limiting и ingress behavior; - Prisma migrations, которые трогают PII, auth-данные или статусные модели аккаунтов. Минимальный operational baseline такого review фиксируется в `.gitea/PULL_REQUEST_TEMPLATE.md` и не должен обходиться устными комментариями. ### Обязательные вопросы к любому большому change 1. Как это будет поддерживать другая команда через 6 месяцев? 2. Как это проверить автоматически? 3. Что нужно обновить в документации? 4. Что будет точкой отказа при handover? 5. Как это откатывается? ## 11. Что запрещено - Хранить критичное знание только в головах команды. - Держать production-процесс в виде “ручной магии”. - Добавлять новый критичный flow без тестового покрытия. - Менять API без обновления контракта. - Менять или добавлять endpoint'ы без записи в `frontend-change-log.md`, если эти изменения важны для frontend-команды. - Закрывать значимый change package без записи в `project-change-log.md`. - Мержить нетривиальный change без прохождения repo-side quality gate, если он уже заведен для репозитория. - Обходить PR review/security checklist для auth, permissions, uploads, proxy, secrets и migration-sensitive изменений. - Добавлять новые env/domain/infra зависимости без документирования. - Оставлять устаревшие документы как будто они всё ещё канонические. - Считать отсутствие документации нормальным состоянием для важных решений. ## 12. Критерии готовности проекта к передаче другой команде Проект можно считать реально передаваемым, только если: - есть актуальный roadmap и текущее состояние; - есть runbook эксплуатации и деплоя; - API-контракт формализован; - ключевые сценарии покрыты тестами; - окружение и зависимости воспроизводимы; - frontend и backend можно развивать без скрытых связей; - новая команда может поднять проект и продолжить разработку без постоянных устных пояснений. ## 13. Практический приоритет на ближайшие этапы Эти принципы прямо означают следующие инженерные приоритеты: 1. Довести документацию до полностью канонического состояния. 2. Укрепить тестовый контур, особенно для web. 3. Формализовать API через OpenAPI/Swagger. 4. Подготовить frontend к repo split без скрытой связанности. 5. Перевести delivery в управляемый docker-контур. ## 14. Как использовать этот документ Этот документ должен использоваться как baseline при: - планировании roadmap; - review архитектурных решений; - определении Definition of Done; - оценке технического долга; - подготовке handover другой команде; - принятии решений по frontend repo split и docker migration.