Initial commit

2026-07-09 11:03:44 +03:00
commit ea8bb6181a
8 changed files with 2003 additions and 0 deletions
@@ -0,0 +1,96 @@
+# arch-05. Правила разработки модулей отдельными агентами
+
+> Термины — в [`arch-00-glossary.md`](arch-00-glossary.md). Настоящий документ описывает процесс разработки и не переопределяет архитектуру. Иерархия приоритета — в [`README.md`](README.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` с `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`.
+- Для списков использовать справочники. Если значения в столбце могут принимать определенный набор значений, записывать их через ИД (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 в логах.
+
+Дополнительно:
+
+
+
+## Definition of Done
+
+Модуль считается готовым, если:
+
+- реализованы сценарии из задачи;
+- обновлен `{service}/openapi.yaml`, если менялся HTTP API;
+- созданы миграции, если менялась БД;
+- добавлены тесты;
+- сервис запускается в Docker Compose;
+- все изменяемые параметры вынесены из кода;
+- логи содержат `request_id`, `trace_id` и **`ux_session_id`** (если передан в запросе);
+- нет секретов, raw OTP и PII в логах;
+- soft delete соблюден;
+- агент указал, какие документы архитектуры были затронуты.
+
+## Правила изменения архитектуры
+
+Если агент видит, что текущая архитектура мешает задаче, он должен:
+
+1. описать проблему;
+2. предложить минимальное изменение;
+3. указать затронутые документы;
+4. не делать широкий рефакторинг без подтверждения.