arch-05. Правила разработки модулей отдельными агентами

Термины — в arch-00-glossary.md. Настоящий документ описывает процесс разработки и не переопределяет архитектуру. Иерархия приоритета — в README.md, раздел «Разрешение конфликтов».

Цель

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

Общие правила

Каждый агент работает только в границах назначенного модуля.
Перед разработкой агент читает README.md, архитектурные документы и профильный документ назначенного модуля.
Любое изменение публичного API сопровождается обновлением OpenAPI.
Любое изменение структуры данных сопровождается миграцией.
Все бизнес-параметры — в таблице app_settings; infra и секреты — в .env.
Нельзя hardcode-ить телефоны, лимиты, тексты, mime types, feature flags и параметры Битрикс24.
Модули, принимающие пользовательский ввод, должны учитывать rate limits и security/safety проверки.

Правила базы данных

Перечень таблиц, полей, индексов и миграций определяет модуль-владелец (database, api-backend, bitrix-sync, message-safety, bitrix-local-app), а не arch-*.
Архитектура фиксирует разделение схем и общие подходы к ведению баз данных, которые должны соблюдаться при проработке модулей.
У каждой основной прикладной сущности должен быть record_status. Базовые статусы: A — active, D — deleted.
record_status выражает только административное наличие строки. Доменное завершение (например Notification.lifecycle_status='closed') хранится отдельно и не переводит запись в D.
Физическое удаление строк прикладных сущностей запрещено. Если нужно удалить сущность, сервис меняет record_status с A на D.
При смене статуса на D сервис обязан заполнить status_changed_at и status_change_reason.
Все сервисы при чтении бизнес-данных по умолчанию запрашивают только record_status = 'A'.
Исключения допускаются только для аудита, админки, технического восстановления и миграций.
Прикладные сущности, имеют id, created_at, updated_at, updater_user_id.
Системные таблицы (app_settings, text_resources, popular_questions, sync_queue, audit, справочники) могут использовать user_id = NULL или отдельное поле actor_type — по спецификации модуля database.
Для строковых enum из arch-00 (Dialog.status, Message.safety_status, Message.delivery_status, sender_type, scan_status и т.п.) справочник sequence не обязателен: значения фиксированы контрактом API.
Для больших/изменяемых списков (типы документов post-MVP, причины, классификаторы UI) — справочники с ID (sequence) и расшифровкой.
Для часто используемых фильтров добавляются индексы.
Миграции не должны удалять данные без отдельного согласования.
Все юзеры должны иметь ИД, которое указывается в updater_user_id которое они меняют.

API

Правила:

endpoint naming должен следовать arch-02-api-contracts.md;
response schema не должна раскрывать внутренние поля;
ошибки возвращаются в едином формате;
для пользовательских данных всегда используется текущий user context из JWT;
frontend не передает client_profile_id для доступа к своим данным;
профиль в MVP не редактируется через PATCH /me;
сообщения оператора должны приходить в frontend через realtime или polling fallback.

Логирование и OTP

Каждый модуль должен:

использовать общий формат JSON-логов;
добавлять module, event, request_id, trace_id;
для api-backend добавлять ux_session_id в JSON-логи, если передан заголовок X-Ux-Session-Id;
не логировать access token, refresh token, raw OTP, документы, полные PII;
хранить факт отправки OTP через provider_message_id, sent_at, destination_masked, otp_hash, попытки и итог проверки.

Raw OTP запрещено хранить в открытом виде: это временный секрет. Доказательство отправки и проверки строится на аудите, delivery id провайдера и hash-проверке.

Тесты

Минимум для каждого модуля:

happy path;
ошибки авторизации и доступа;
rate limits, если модуль принимает пользовательский ввод;
soft delete и фильтрация record_status = 'A', если модуль работает с БД;
idempotency, если операция может повториться;
отсутствие секретов и PII в логах.

Дополнительно для модулей с async/worker:

идемпотентность обработки задач очереди;
поведение при повторной доставке webhook;
таймауты и retry/backoff.

Для Notification Center обязательны contract tests каталога без ветвления по виду, бессрочной дедупликации (source, external_id), изоляции producer tokens, TTL с сохранением существующего date_expired, первого скачивания любого связанного документа и открытия instruction только в новой вкладке.

Definition of Done

Модуль считается готовым, если:

реализованы сценарии из задачи;
обновлен {service}/openapi.yaml, если менялся HTTP API;
обновлены каталог ошибок в arch-02 и contract tests, если менялась публичная или internal HTTP-семантика;
созданы миграции, если менялась БД;
обновлены seed app_settings и .env.example, если добавлялись настройки, service tokens, лимиты или feature flags;
добавлены тесты;
сервис запускается в Docker Compose;
worker, указанный в Compose/runbook, имеет реально зарегистрированный entrypoint в image; deployment не может заранее выдумывать имя команды;
все изменяемые параметры вынесены из кода;
логи содержат request_id, trace_id и ux_session_id (если передан в запросе);
нет секретов, raw OTP и PII в логах;
soft delete соблюден;
агент указал, какие документы архитектуры были затронуты.

Правила изменения архитектуры

Если агент видит, что текущая архитектура мешает задаче, он должен:

описать проблему;
предложить минимальное изменение;
указать затронутые документы;
не делать широкий рефакторинг без подтверждения.

9.1 KiB Raw Blame History Unescape Escape