Проект разделен на два репозитория

architectory/README.md

@@ -11,17 +11,21 @@
 | [`arch-00-glossary.md`](arch-00-glossary.md) | Канонические имена и семантика enum/lifecycle: сущности, поля, id, enum, бакеты S3, env |
 | [`arch-01-system-architecture.md`](arch-01-system-architecture.md) | Общая архитектура: компоненты, сценарии, потоки данных, безопасность |
 | [`arch-02-api-contracts.md`](arch-02-api-contracts.md) | Реестр API-контрактов, realtime, гостевая сессия, OpenAPI, аудит |
-| [`arch-03-docker-compose-blueprint.md`](arch-03-docker-compose-blueprint.md) | Требования к Docker Compose, nginx, сетям, TLS и rate limits |
+| [`arch-03-docker-compose-blueprint.md`](arch-03-docker-compose-blueprint.md) | Требования к Docker Compose, сетям и published ports. Детальный контракт nginx — arch-08 |
 | [`arch-04-settings-and-content.md`](arch-04-settings-and-content.md) | `.env` (infra), таблица `app_settings`, значения service-token переменных, типы файлов |
 | [`arch-05-agent-development-process.md`](arch-05-agent-development-process.md) | Правила разработки модулей отдельными агентами |
 | [`arch-06-service-hosting-security.md`](arch-06-service-hosting-security.md) | Безопасность VM и деплоя: OS-роли, SSH, sudo/systemd, секреты, контейнеры, сеть и lockdown |
+| [`arch-07-observability.md`](arch-07-observability.md) | Контракт наблюдаемости: Collector, JSON-логи, корреляция, redaction, sampling, SLO, SigNoz. Реализация VM — `module-09-observability-vm1.md` / `module-09-observability-vm2.md` |
+| [`arch-08-nginx.md`](arch-08-nginx.md) | Контракт корневого nginx: TLS/ACME, request id, internal 404, access log, reload. Реализация VM — `module-03-nginx-vm1.md` / `module-03-nginx-vm2.md`. Сети и ports — arch-03 |
+| [`arch-09-redis.md`](arch-09-redis.md) | Контракт Redis: не source of truth, формат ключей, TTL, Lua, AOF/ACL. Реализация VM — `module-04-redis-vm1.md` / `module-04-redis-vm2.md` |
+| [`arch-10-deployment.md`](arch-10-deployment.md) | Контракт развёртывания: VPC/SG, PG/S3, роли `deploy`, TLS процедура, cutover. Runbook VM — `module-10-deployment-vm1.md` / `module-10-deployment-vm2.md`. OS-роли — arch-06 |
 
 ## Как читать
 
 1. Начните с **arch-01** — общая картина и зафиксированные решения MVP.
-2. При работе с API — **arch-02**; с Compose/nginx — **arch-03**; с настройками — **arch-04**; с VM, SSH, правами деплоя, секретами и host/container hardening — **arch-06**.
+2. При работе с API — **arch-02**; с Compose/сетями — **arch-03**; с контрактом nginx — **arch-08** и профильная спецификация VM; с Redis — **arch-09** и профильная спецификация VM; с настройками — **arch-04**; с VM, SSH, правами деплоя, секретами и host/container hardening — **arch-06**; с rollout stages/gates — **arch-10** и профильный runbook VM; с telemetry/логами/traces — **arch-07** и профильная спецификация VM.
 3. Спорные **имена** полей, id, enum, бакетов и базовая семантика enum/lifecycle — **arch-00**. Лимиты и правила реализации остаются в профильных arch-*.
-4. Перед разработкой модуля — **arch-05**, релевантные разделы arch-01/arch-02 и arch-06, если меняются deployment, сети, volumes, capabilities или секреты.
+4. Перед разработкой модуля — **arch-05**, релевантные разделы arch-01/arch-02 и arch-06, если меняются deployment, сети, volumes, capabilities или секреты. Наблюдаемость сервиса — arch-07 плюс `module-09-observability-vm1.md` или `module-09-observability-vm2.md`. Nginx — arch-08 плюс `module-03-nginx-vm1.md` или `module-03-nginx-vm2.md`. Redis — arch-09 плюс `module-04-redis-vm1.md` или `module-04-redis-vm2.md`. Раскатка VM — arch-10 плюс `module-10-deployment-vm1.md` или `module-10-deployment-vm2.md`.
 
 ## Приоритет документов
 
@@ -31,9 +35,13 @@
 2. **arch-01** — границы сервисов, сценарии, sync, безопасность.
 3. **arch-02** — HTTP-контракты и направление вызовов.
 4. **arch-06** — безопасность размещения на VM, OS-роли, SSH, secrets delivery, host/container hardening и production-деплой.
-5. **arch-03** — Compose, сети контейнеров, nginx и TLS.
-6. **arch-04** — non-secret env, secret references, `app_settings`, публичные DTO.
-7. **arch-05** — процесс разработки.
+5. **arch-03** — Compose, сети контейнеров и published ports.
+6. **arch-08** — контракт nginx: TLS/ACME, request id, internal 404, access log, reload. Routing matrix — профильный module-03 VM spec.
+7. **arch-04** — non-secret env, secret references, `app_settings`, публичные DTO.
+8. **arch-09** — контракт Redis: не source of truth, ключи, TTL, Lua, AOF/ACL. Карта ключей — профильный module-04 VM spec.
+9. **arch-07** — контракт telemetry: JSON-поля, resource attributes, redaction, sampling, Collector, SigNoz. Не бизнес-лимиты сервисов.
+10. **arch-10** — контракт развёртывания: VPC/SG, PG/S3, stages/gates, cutover. Не ослабляет arch-06. Процедуры VM — профильный module-10 runbook.
+11. **arch-05** — процесс разработки.
 
 Профильные спецификации модулей уточняют реализацию внутри этих границ. Если границы не позволяют эффективно реализовать модуль, то агент, разрабатывающий модуль, может предложить внести изменения в архитектуру.
 
@@ -42,15 +50,19 @@
 - Имена полей, бакетов, статусов → **arch-00**, затем синхронизация arch-*.
 - Endpoint или auth → **arch-02**, при необходимости arch-01/arch-03.
 - Новая интеграция → сначала **arch-02**.
-- Compose, nginx, TLS → **arch-03**.
+- Compose, сети контейнеров, published ports → **arch-03**.
+- TLS/ACME nginx, request id, internal 404, access log → **arch-08**, затем профильный `module-03-nginx-vm1.md` или `module-03-nginx-vm2.md`.
+- Redis ключи/TTL/ACL/AOF, запрет очереди и OTP store → **arch-09**, затем профильный `module-04-redis-vm1.md` или `module-04-redis-vm2.md`.
 - VM, SSH, sudo, systemd-деплой, secret delivery, container/host hardening → **arch-06**, затем синхронизация arch-03/arch-04 и runbook.
+- Rollout stages, SG/DNS, PG/S3 gates, Safety cutover порядок → **arch-10**, затем профильный `module-10-deployment-vm1.md` или `module-10-deployment-vm2.md`.
+- JSON-лог, `request_id`/`trace_id`, redaction, sampling, Collector, SigNoz → **arch-07**, затем профильный `module-09-observability-vm1.md` или `module-09-observability-vm2.md`.
 
 ## В бэклоге (не MVP)
 
 | Тема | Где зафиксировано |
 |---|---|
 | Доставка документов компании из Bitrix24 в приложение (`bitrix-sync` → `api-backend`, уведомление клиента) | [`!Backlog.md`](../../HAN_chat/!Backlog.md), п. 9; arch-01 — заглушка UI «Документы» |
-| Интеграция с SMS-провайдерами (отправка OTP, отключение `KEYCLOAK_OTP_MOCK_*`) | Спецификация: [`module-11-idgtl-sms.md`](../modules/module-11-idgtl-sms.md) (доставка через Direct SMS API; проверка OTP — локально в Keycloak) |
+| Интеграция с SMS-провайдерами (отправка OTP, отключение `KEYCLOAK_OTP_MOCK_*`) | Спецификация: [`module-11-idgtl-sms.md`](../VM1_app/documentation/module-11-idgtl-sms.md) (доставка через Direct SMS API; проверка OTP — локально в Keycloak) |
 
 ## Каноническое размещение production-контуров
 
@@ -66,7 +78,6 @@
 | # | Пробел | Статус |
 |---|---|---|
 | G8 | Явный список `is_public=true` для ключей `app_settings` | Отложить до оформления сервисов; seed в модуле `database` |
-| G9 | GRANT-модель `bitrix_sync_user` на `han_app`: таблицы, колонки, read/write границы | Закрыто в `module-07-bitrix-sync.md` §13; точный SQL реализуется migrations и проходит negative permission tests |
 | G10 | Полный DTO `GET /api/v1/public/app-config` и мэппинг `setting_key → response field` | Уточнить при оформлении OpenAPI `api-backend` |
 | G11 | Версионирование API/WS: deprecation policy, срок поддержки v1, `ws_protocol_version` | Уточнить перед публичным релизом API |
 | G12 | Масштабирование realtime: Redis Pub/Sub, sticky sessions, backpressure при нескольких репликах `api-backend` | Post-MVP / перед горизонтальным масштабированием |
@@ -83,6 +94,10 @@
   runbook.
 - Изменение service seed/schema/embedded artifact или feature flag, влияющего
   на edge route/allow-list → arch-04 + профильный module + rollout/rollback
-  gates в module-10.
+  gates в arch-10 и профильном `module-10-deployment-vm1.md` / `module-10-deployment-vm2.md`.
 - Новый термин / enum → arch-00, затем поиск по arch-*.
+- Изменение JSON-лога, resource attributes, redaction, sampling, Collector pipeline или SigNoz endpoint → arch-07 (+ профильный module-09 VM spec, если меняется состав сервисов/алертов этой машины).
+- Изменение общего контракта nginx (TLS/ACME, request id, internal 404, reload) → arch-08 (+ профильный module-03 VM spec, если меняется routing/allow-list этой машины).
+- Изменение общего контракта Redis (формат ключей, TTL, Lua, AOF/ACL, запрет очереди) → arch-09 (+ профильный module-04 VM spec, если меняется карта ключей этой машины).
+- Изменение общего rollout (SG/DNS, PG/S3 gates, cutover порядок) → arch-10 (+ профильный module-10 VM runbook).
 - Закрытие пробела → убрать из «Открытые пробелы» и отразить решение в arch-*.