Архитектура HAN Chat

Канонический набор архитектурных документов проекта. Описывает границы системы, интеграции, контракты API, инфраструктуру, настройки и процесс разработки.

Детальная схема таблиц App DB, правила проверки файлов (file_rules и др.) и OpenAPI-файлы — зона ответственности соответствующих модулей; архитектура задаёт только границы, контракты и общие правила.

Состав документов

Документ	Содержание
`arch-00-glossary.md`	Канонические имена: сущности, поля, id, enum, бакеты S3, env
`arch-01-system-architecture.md`	Общая архитектура: компоненты, сценарии, потоки данных, безопасность
`arch-02-api-contracts.md`	Реестр API-контрактов, realtime, гостевая сессия, OpenAPI, аудит
`arch-03-docker-compose-blueprint.md`	Требования к Docker Compose, nginx, сетям, TLS и rate limits
`arch-04-settings-and-content.md`	`.env` (infra), таблица `app_settings`, service tokens, типы файлов
`arch-05-agent-development-process.md`	Правила разработки модулей отдельными агентами

Как читать

Начните с arch-01 — общая картина и зафиксированные решения MVP.
При работе с API — arch-02; при деплое — arch-03; при настройках — arch-04.
Спорные имена полей, id, enum, бакетов — arch-00 (не правила и не лимиты).
Перед разработкой модуля — arch-05 и релевантные разделы arch-01/arch-02.

Приоритет документов

При конфликте требований:

arch-00 — только имена (поля, id, enum, бакеты, env); не правила и не лимиты.
arch-01 — границы сервисов, сценарии, sync, безопасность.
arch-02 — HTTP-контракты и направление вызовов.
arch-03 — инфраструктура и nginx.
arch-04 — env, app_settings, публичные DTO.
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`, п. 9; arch-01 — заглушка UI «Документы»
Интеграция с SMS-провайдерами (отправка OTP, отключение `KEYCLOAK_OTP_MOCK_*`)	`!Backlog.md`, п. 10

Обновление документации

Изменение MVP → arch-01 + arch-02 (+ arch-03/arch-04 при необходимости).
Новый env или ключ app_settings → arch-04.
Новый термин → arch-00, затем поиск по arch-*.

4.4 KiB Raw Blame History Unescape Escape