Initial commit

2026-07-09 11:03:44 +03:00
commit ea8bb6181a
8 changed files with 2003 additions and 0 deletions
@@ -0,0 +1,56 @@
+# Архитектура HAN Chat
+
+Канонический набор архитектурных документов проекта. Описывает границы системы, интеграции, контракты API, инфраструктуру, настройки и процесс разработки.
+
+Детальная **схема таблиц App DB**, **правила проверки файлов** (`file_rules` и др.) и **OpenAPI-файлы** — зона ответственности соответствующих модулей; архитектура задаёт только границы, контракты и общие правила.
+
+## Состав документов
+
+| Документ | Содержание |
+|---|---|
+| [`arch-00-glossary.md`](arch-00-glossary.md) | Канонические имена: сущности, поля, 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-04-settings-and-content.md`](arch-04-settings-and-content.md) | `.env` (infra), таблица `app_settings`, service tokens, типы файлов |
+| [`arch-05-agent-development-process.md`](arch-05-agent-development-process.md) | Правила разработки модулей отдельными агентами |
+
+## Как читать
+
+1. Начните с **arch-01** — общая картина и зафиксированные решения MVP.
+2. При работе с API — **arch-02**; при деплое — **arch-03**; при настройках — **arch-04**.
+3. Спорные **имена** полей, id, enum, бакетов — **arch-00** (не правила и не лимиты).
+4. Перед разработкой модуля — **arch-05** и релевантные разделы arch-01/arch-02.
+
+## Приоритет документов
+
+При конфликте требований:
+
+1. **arch-00** — только **имена** (поля, id, enum, бакеты, env); не правила и не лимиты.
+2. **arch-01** — границы сервисов, сценарии, sync, безопасность.
+3. **arch-02** — HTTP-контракты и направление вызовов.
+4. **arch-03** — инфраструктура и nginx.
+5. **arch-04** — env, `app_settings`, публичные DTO.
+6. **arch-05** — процесс разработки.
+
+Профильные спецификации модулей уточняют реализацию внутри этих границ. Если границы не позволяют эффективно реализовать модуль, то агент, разрабатывающий модуль, может предложить внести изменения в архитектуру.
+
+## Разрешение конфликтов
+
+- Имена полей, бакетов, статусов → **arch-00**, затем синхронизация arch-*.
+- Endpoint или auth → **arch-02**, при необходимости arch-01/arch-03.
+- Новая интеграция → сначала **arch-02**.
+- Compose, nginx, TLS → **arch-03**.
+
+## В бэклоге (не MVP)
+
+| Тема | Где зафиксировано |
+|---|---|
+| Доставка документов компании из Bitrix24 в приложение (`bitrix-sync` → `api-backend`, уведомление клиента) | [`!Backlog.md`](../../HAN_chat/!Backlog.md), п. 9; arch-01 — заглушка UI «Документы» |
+| Интеграция с SMS-провайдерами (отправка OTP, отключение `KEYCLOAK_OTP_MOCK_*`) | [`!Backlog.md`](../../HAN_chat/!Backlog.md), п. 10 |
+
+## Обновление документации
+
+- Изменение MVP → arch-01 + arch-02 (+ arch-03/arch-04 при необходимости).
+- Новый env или ключ `app_settings` → arch-04.
+- Новый термин → arch-00, затем поиск по arch-*.