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

Master-документация проекта Konstructorium

1. Статус и назначение документа

Этот документ является единым верхнеуровневым источником правил и ограничений проекта Konstructorium. Цель: обеспечить синхронизацию архитектуры, разработки, тестирования, релизов и операционного сопровождения.

Документ обязателен для всех изменений в:

  • backend-сервисах;
  • web-клиенте;
  • инфраструктурном контуре;
  • тестовом контуре;
  • эксплуатационных регламентах и документации.

2. Контекст платформы и продуктовые границы

Konstructorium - микросервисная платформа для каталога, заказов, коммуникаций и административного управления.

Границы платформы:

  • Внутри: frontend, сервисы домена, БД, Redis/Celery, docker-compose контур, документы docs/.
  • Снаружи: пользовательские клиенты, операторы админ-панели, внешние интеграции (если подключаются), devops/tooling окружение.

Целевые бизнес-сценарии:

  1. Поиск и выбор моделей/товаров с фильтрацией.
  2. Заказ и сопровождение статусов оплаты/исполнения.
  3. Коммуникация между пользователем и администрацией.
  4. Управление ролями, заявками продавцов и административными действиями.

3. Карта модулей и интерфейсов

3.1 Реестр модулей

Модуль Роль Основные интерфейсы
frontend UI и orchestration клиентского сценария HTTP API вызовы в сервисы, route/query-state
auth_service Аутентификация и профиль пользователя /api/register, /api/login, /api/logout, /api/profile
user_service Пользовательские профили и ролевые переходы endpoints профиля и seller-request
product_service Каталог, модели, фильтрация и публикация /api/models/*
order_service Управление заказами /api/orders/*
review_service Отзывы и модерация отзывов /reviews/*
chat_service Диалоги и сообщения /api/chat/*
analytics_service Ingest веб-аналитики (cookie consent) /api/analytics/*
admin_service Административный контроль + отчёты web/business /api/admin/*
telegram_bot_service Интеграция уведомлений/бот-сценариев API/очереди уведомлений (по сервисному контракту)

3.2 Ссылки на подробные спецификации

3.3 Системный поток поставки изменения

flowchart TD
  businessNeed[BusinessNeed] --> analysis[AnalysisAndScope]
  analysis --> implementation[Implementation]
  implementation --> ciChecks[CIQualityGates]
  ciChecks --> releaseDecision[ReleaseDecision]
  releaseDecision --> cdDeploy[CDDeploy]
  cdDeploy --> smokeChecks[PostDeployChecks]
  smokeChecks --> monitor[MonitoringAndFeedback]
  monitor --> backlog[BacklogUpdate]
  backlog --> analysis

4. Архитектурные инварианты и ограничения

  1. Межсервисные контракты изменяются только с синхронным обновлением docs и тестов.
  2. Breaking changes без ADR и миграционного плана запрещены.
  3. Политики доступа фиксируются явно в endpoint-документации.
  4. Схема данных и инварианты не расходятся с фактическими миграциями.
  5. Обход проверки ролей и ownership в критичных операциях запрещен.

Формальный контроль:

Требование Причина Проверка Артефакт
Явные API-контракты Снижение интеграционных регрессий ревью + контрактные проверки docs/services/* + тесты
Изменение схемы только с документацией Снижение стоимости сопровождения PR checklist migration + docs update
Явная auth-политика endpoint-ов Контроль security-рисков API review сервисные страницы

5. Политика интерфейсов (API и внутренние контракты)

Обязательные правила:

  1. Каждый endpoint имеет: метод, путь, auth, request, response, errors, side-effects.
  2. Коды ошибок указываются в формате код -> условие -> действие оператора.
  3. Любая фильтрация/сортировка в UI должна иметь server-side эквивалент для корректной пагинации.
  4. Изменение payload формата требует обновления клиентского контракта и release note.

Реестр контрольных документов:

6. Безопасность, права и комплаенс

Требования:

  1. Правила доступа endpoint-ов не могут оставаться неявными.
  2. Секреты и персональные данные запрещено логировать.
  3. Значения из .env не попадают в docs/логи/PR-тексты.
  4. Роль и ownership проверяются на стороне API, не только в UI.

Операционный минимум:

  • ротация секретов по регламенту окружения;
  • запрет hardcoded credentials;
  • фиксирование security-risk в risk register при любом временном компромиссе.

7. Формальная модель CI/CD

7.1 CI (непрерывная интеграция)

Quality gates для merge:

  1. Линтеры и статический контроль.
  2. Тестовый контур (unit/integration/smoke где применимо).
  3. Консистентность документации (включая MkDocs strict).
  4. Проверка, что нет несогласованных API/DB изменений.

7.2 CD (непрерывная поставка)

Release controls:

  1. Версионирование изменений и rollback-стратегия.
  2. Проверка health endpoints после деплоя.
  3. Post-release smoke на критичном пользовательском пути.
  4. Фиксация release-risk и мониторинговых триггеров.

7.3 Формальный контроль CI/CD

Требование Причина Проверка Артефакт
Green CI обязателен Непредсказуемый релиз без green CI pipeline status CI run
Strict docs build обязателен Документация = часть DoD mkdocs strict build build log
Rollback plan обязателен Сокращение MTTR release checklist release record

8. Политика использования нейросетей в разработке

Цель: ускорение типовых задач без снижения безопасности и качества.

Разрешено:

  1. Черновая генерация текста документации.
  2. Подготовка шаблонов тест-кейсов и чеклистов.
  3. Помощь в рефакторинге, если итог проверен разработчиком.

Запрещено:

  1. Передача секретов, приватных ключей, production-данных.
  2. Слепое принятие сгенерированного кода без ревью и проверок.
  3. Автоматическое изменение критичных контрактов без человека-владельца.

Контроль:

  • любой AI-assisted change должен быть верифицирован владельцем зоны;
  • итоговый артефакт оценивается по тем же quality gates, что и ручной код;
  • при спорных решениях фиксируются ограничения и риски в PR/docs.

9. Риск-реестр разработки (расширенный)

ID Риск Тип Вероятность Влияние Митигация Владелец
DEV-R001 Рассинхронизация API и UI контракта technical Medium High контрактные проверки + docs update в DoD Главный разработчик
DEV-R002 Нарушение role/ownership в endpoint security Medium High обязательный review permission logic + негативные тесты Архитектор
DEV-R003 Неполный регресс перед релизом process Medium High smoke + QA checklist + release gate QA
DEV-R004 Рост техдолга через временные обходы process High Medium фиксация timebox, владелец, дата снятия Тимлид
DEV-R005 Непрозрачное применение AI-инструментов governance Medium Medium AI policy + traceability изменений Тимлид
DEV-R006 Падение docs build из-за неучтенных страниц delivery Medium Medium strict nav control + doc owner review Главный разработчик

10. MVP path и критерии перехода

Этап 1. Foundation MVP

Состав:

  • базовая авторизация;
  • каталог и карточка модели;
  • базовый заказ;
  • минимальная админ-панель.

Критерии перехода:

  1. Критические пользовательские сценарии закрыты end-to-end.
  2. Нет блокирующих P1 дефектов.
  3. Документация синхронизирована с фактическим API.

Этап 2. Operational MVP

Состав:

  • стабилизация фильтров/пагинации;
  • операционные регламенты backup/restore и incident response;
  • расширенный контроль release-risk.

Критерии перехода:

  1. CI/CD контроль стабилен.
  2. Наблюдаемость и инцидентный контур проверены.
  3. Снижен процент регрессий на критичных сценариях.

Этап 3. Scale MVP

Состав:

  • усиление модульных границ;
  • оптимизация производительности и очередей;
  • формализация SLA/SLO по ключевым сценариям.

Критерии перехода:

  1. Приоритетные performance-risk снижены до приемлемого уровня.
  2. RACI и зона владения инцидентами формализованы.
  3. Документы архитектуры и операций покрывают все критичные зависимости.

11. Ответственность команды и RACI

11.1 Роли и персональная ответственность

Участник Роль Основная зона решений Обязательные артефакты
Михаил Тимлид и главный разработчик Приоритизация, интеграция сервисов, release-go/no-go roadmap, release decision, cross-service review
Арсений Архитектор и разработчик Архитектурная целостность, контракты, технические ограничения ADR, архитектурные требования, boundary review
Станислав Тестировщик и разработчик QA-стратегия, регрессии, quality gates в релизе test strategy, regression report, release QA sign-off

11.2 RACI по критичным потокам

Процесс R A C I
Изменение API-контракта Арсений Михаил Станислав Команда
Решение по релизу Михаил Михаил Арсений, Станислав Команда
QA-регресс и блокировка релиза Станислав Михаил Арсений Команда
Фиксация архитектурного компромисса Арсений Михаил Станислав Команда

11.3 Диаграмма ответственности

flowchart TD
  mikhail[Mikhail_TeamLead] --> roadmap[RoadmapAndReleaseDecision]
  arseniy[Arseniy_Architect] --> architecture[ArchitectureAndContracts]
  stanislav[Stanislav_QADev] --> quality[QualityAndRegressionControl]
  roadmap --> sharedArtifacts[SharedProjectArtifacts]
  architecture --> sharedArtifacts
  quality --> sharedArtifacts

12. Чеклисты обязательного контроля

12.1 Readiness к разработке

  • scope и критерии готовности задачи определены;
  • зона влияния на API/DB/UI зафиксирована;
  • риски и ограничения перечислены до старта;
  • владелец изменения и ревьюеры назначены.

12.2 Readiness к релизу

  • green CI;
  • выполнен регресс критичных сценариев;
  • обновлены затронутые docs страницы;
  • release notes и rollback-план готовы.

12.3 Post-release verification

  • health endpoints в норме;
  • ключевые бизнес-сценарии проходят smoke;
  • нет новых P1/P2 инцидентов;
  • отклонения зафиксированы и назначены владельцы corrective actions.

12.4 Incident/postmortem follow-up

  • определена первопричина;
  • зафиксированы технические и процессные меры;
  • обновлены docs/чеклисты при необходимости;
  • назначены сроки и владельцы закрытия действий.

13. Связанные регламенты

14. Политика сопровождения master-страницы

  1. Любое изменение архитектурных ограничений обновляется здесь и в профильном разделе.
  2. Любое изменение ролей/процессов релиза обновляется здесь до merge.
  3. Несогласованность между этой страницей и сервисными/операционными страницами считается дефектом документации.