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

2026-08-14 15:42:45 +03:00
parent e06a77ee1d
commit bbef7a30c9
521 changed files with 2597 additions and 2302 deletions
@@ -0,0 +1,84 @@
+# HAN Chat API backend
+
+FastAPI-сервис публичного API, internal Open Lines/settings API, WebSocket realtime,
+Message Safety orchestration, S3 lifecycle и PostgreSQL workers.
+
+## Запуск
+
+Python 3.12+:
+
+```bash
+python -m venv .venv
+.venv/Scripts/pip install -e ".[dev]"
+alembic upgrade head
+uvicorn app.main:app --host 0.0.0.0 --port 8000
+```
+
+Миграции выполняются отдельным deployment step. Приложение не применяет DDL при старте.
+
+Workers запускаются независимо:
+
+```bash
+han-delivery-worker
+han-safety-worker
+han-cleanup-worker
+han-notification-expire-worker
+han-notification-draft-cleanup-worker
+```
+
+## Переменные окружения
+
+Сервис читает только инфраструктурные параметры и секреты из корневого `backend/.env`.
+Локальный `.env` не коммитится. Business settings создаются миграцией в
+`han_app.app_settings`.
+
+Обязательны:
+
+- `APP_ENV`, `API_PORT`, `LOG_LEVEL`, `DATABASE_URL`;
+- `REDIS_URL`, `REDIS_REALTIME_URL`;
+- `KEYCLOAK_PUBLIC_URL`, `KEYCLOAK_INTERNAL_URL`, `KEYCLOAK_REALM`,
+  `KEYCLOAK_AUDIENCE`;
+- `MESSAGE_SAFETY_URL`, `MESSAGE_SAFETY_SERVICE_TOKEN`,
+  `MESSAGE_SAFETY_CA_FILE`, `MESSAGE_SAFETY_API_PREFIX=/internal/safety/v2`,
+  `MESSAGE_SAFETY_POST_TIMEOUT_SEC`, `MESSAGE_SAFETY_TASK_POLL_INTERVAL_SEC`,
+  `MESSAGE_SAFETY_TASK_POLL_MAX_SEC`,
+  `MESSAGE_SAFETY_CIRCUIT_FAILURE_THRESHOLD`, `MESSAGE_SAFETY_CIRCUIT_OPEN_SEC`;
+- `BITRIX_LOCAL_APP_BASE_URL`, `BITRIX_LOCAL_APP_INTERNAL_TOKEN`,
+  `BITRIX_API_INBOX_TOKEN`, `BITRIX_LOCAL_APP_HTTP_TIMEOUT_SEC`,
+  `BITRIX_LOCAL_APP_CIRCUIT_FAILURE_THRESHOLD`,
+  `BITRIX_LOCAL_APP_CIRCUIT_OPEN_SEC`;
+- `KEYCLOAK_SETTINGS_BRIDGE_TOKEN`;
+- `SELECTEL_S3_ENDPOINT_URL`, `SELECTEL_S3_BUCKET_DOCUMENTS`,
+  `SELECTEL_S3_BUCKET_ATTACHMENTS`, `SELECTEL_S3_BUCKET_QUARANTINE`,
+  `SELECTEL_S3_ACCESS_KEY`, `SELECTEL_S3_SECRET_KEY`;
+- `CURSOR_HMAC_SECRET` — случайный секрет не короче 32 байт;
+- `NOTIFICATIONS_TOKEN_PRODUCER_TEST` — отдельный bearer token тестового
+  продюсера Notification Center; в БД синхронизируется только SHA-256 hash;
+- `OTEL_EXPORTER_OTLP_ENDPOINT` — опциональный endpoint collector.
+
+Токены генерируются `openssl rand -hex 32`. S3 read-only credentials Message Safety
+не передаются этому контейнеру. В production подключение PostgreSQL должно использовать
+TLS. Target `MESSAGE_SAFETY_URL=https://processing.internal:8443`; certificate
+проверяется по internal CA, plaintext HTTP запрещён. Текущий Docker hostname
+`message-safety` относится только к legacy stub до cutover.
+
+Smoke-сценарий `producer_test`: отправить `POST
+/internal/notifications/v1/notifications` с `Authorization: Bearer
+$NOTIFICATIONS_TOKEN_PRODUCER_TEST`, `source=producer_test` и уникальным
+`external_id`; повтор того же тела вернёт `200`. Затем передать ту же пару
+`source`/`external_id` в `POST /internal/notifications/v1/notifications/cancel`
+с `close_reason=cancelled`; повторная отмена также вернёт `200`.
+
+## Проверки
+
+```bash
+ruff check .
+ruff format --check .
+mypy app
+pytest
+```
+
+`/health/live` проверяет процесс. `/health/ready` проверяет критические
+зависимости read API. Remote Message Safety не выключает чтение/общую readiness:
+send endpoint отдельно проверяет требуемую capability и fail-closed возвращает
+`503`, если ВМ2 недоступна.