Реализована интеграция с СМС провайдером

architectory/README.md

@@ -47,7 +47,7 @@
 | Тема | Где зафиксировано |
 |---|---|
 | Доставка документов компании из 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 |
+| Интеграция с SMS-провайдерами (отправка OTP, отключение `KEYCLOAK_OTP_MOCK_*`) | Спецификация: [`module-11-idgtl-sms.md`](../modules/module-11-idgtl-sms.md) (доставка через Direct SMS API; проверка OTP — локально в Keycloak) |
 | Изоляция `bitrix-sync` на отдельную VM | [`!Backlog.md`](../../HAN_chat/!Backlog.md), п. 8 |
 
 

architectory/arch-00-glossary.md

@@ -34,6 +34,9 @@
 | `text_resources` | `han_app` | Тексты UI по мнемоникам |
 | `popular_questions` | `han_app` | Популярные вопросы главного экрана |
 | `dialog_sessions` | `bitrix_local` | Маппинг чата Open Lines |
+| `sms_template` | `sms` | Версионируемый согласованный SMS-шаблон; active-версия уникальна для `code`+`channel`+`locale` |
+| `sms_setting` | `sms` | Технические runtime-настройки `sms-service`, не секреты и не OTP product settings |
+| `sms_outbound_message` | `sms` | Бессрочный журнал заказа, отправки и доставки SMS; источник истины provider status |
 
 ## Идентификаторы
 
@@ -50,6 +53,9 @@
 | `session_id` | ID сессии Open Lines (поле `dialog_sessions`; не путать с `ux_session_id`) |
 | `task_id` | ID async-проверки Message Safety |
 | `request_id` | Корреляция HTTP-запроса (заголовок `X-Request-ID`) |
+| `sms_message_id` | UUID `sms.sms_outbound_message.id`; логическая ссылка из Keycloak challenge/event, межсхемного FK нет |
+| `provider_message_id` | `messageUuid` i-Digital Direct; хранится только в `sms-service` |
+| `provider_external_id` | `externalMessageId`; в v1 равен `sms_message_id` и является корреляцией, а не доказанной идемпотентностью Direct |
 
 Публичные id сущностей — **UUID**.
 
@@ -127,9 +133,16 @@ Realtime-событие `message.status` передаёт актуальные `
 
 ## Строковые enum vs справочники
 
-- **Строковые enum** (значения в API/контрактах): `Dialog.status`, `Message.sender_type`, `Message.safety_status`, `Message.delivery_status`, `MessageAttachment.scan_status`, `content_kind`, `start_reason`.
+- **Строковые enum** (значения в API/контрактах): `Dialog.status`, `Message.sender_type`, `Message.safety_status`, `Message.delivery_status`, `MessageAttachment.scan_status`, `content_kind`, `start_reason`, SMS `send_status`, SMS `delivery_status`, OTP `challenge_status`.
 - **Справочники (sequence ID)** — для больших/изменяемых списков UI и доменных классификаторов (типы документов post-MVP, причины и т.п.); правило — [`arch-05-agent-development-process.md`](arch-05-agent-development-process.md).
 
+### SMS и OTP статусы
+
+- `sms_outbound_message.send_status`: `pending`, `accepted`, `rejected`, `failed`, `uncertain`, `skipped`.
+- `sms_outbound_message.delivery_status`: `unknown`, `sent`, `delivered`, `undelivered`, `unsent`.
+- `han_otp_challenge.challenge_status`: `ordering`, `active`, `consumed`, `superseded`, `expired`, `limited`, `order_failed`.
+- Provider statuses принадлежат только `sms-service`: Keycloak не читает их и не использует для verify.
+
 ## Мнемоники internal API
 
 Префикс: **`/internal/{service_mnemonic}/v1/`**. Health: **`/health/*`**.
@@ -140,6 +153,14 @@ Realtime-событие `message.status` передаёт актуальные `
 | `openlines` | `bitrix-local-app`, приёмник inbox на `api-backend` |
 | `sync` | `bitrix-sync` |
 | `settings` | internal settings bridge на `api-backend` для Keycloak SPI |
+| `sms` | `sms-service`; durable order/read API во внутренней сети |
+
+## SMS-конфигурация
+
+- Product OTP settings: `otp.phone.code_length`, `otp.phone.ttl_seconds`, `otp.phone.sms_order_timeout_ms` и лимиты — `han_app.app_settings`, выдаются Keycloak через settings bridge.
+- Runtime SMS settings: `provider.idgtl.*` и `worker.*` — `sms.sms_setting`.
+- Infra/secrets env: `KEYCLOAK_SMS_SERVICE_URL`, `SMS_DATABASE_URL`, парные `KEYCLOAK_SMS_SERVICE_TOKEN`/`SMS_SERVICE_TOKEN`, `IDGTL_SMS_BASE_URL`, `IDGTL_SMS_API_KEY`, `IDGTL_SMS_CALLBACK_PUBLIC_URL`, `IDGTL_SMS_CALLBACK_USERNAME`, `IDGTL_SMS_CALLBACK_PASSWORD`.
+- Текст, placeholders и sender template не хранятся в env: они принадлежат `sms_template`; default sender — `sms_setting`.
 
 ## Bitrix24 Open Lines
 

architectory/arch-01-system-architecture.md

@@ -19,7 +19,7 @@ HAN Chat - приложение для мигрантов, где стартов
 - Мультиязычность в первом релизе не нужна, но тексты должны храниться по мнемоникам для будущих переводов.
 - Среда на первом этапе одна и проектируется как боевая.
 - Вложения чата MVP: **только изображения и PDF** — см. [`arch-04-settings-and-content.md`](arch-04-settings-and-content.md), «Разрешённые типы файлов чата».
-- SMS OTP на старте: **заглушка** — пользователь вводит фиксированный код из `.env` (`KEYCLOAK_OTP_MOCK_CODE`); SMS не отправляется. Интеграция с SMS-провайдерами — в бэклоге (см. [`!Backlog.md`](../../HAN_chat/!Backlog.md)).
+- SMS OTP вводится поэтапно: до production rollout действует явный mock (`KEYCLOAK_OTP_MOCK_ENABLED=true`); целевой real mode — Keycloak генерирует/локально проверяет OTP и создаёт durable order в `sms-service`, а worker асинхронно вызывает i-Digital Direct. Контракт и gates — [`module-11-idgtl-sms.md`](../modules/module-11-idgtl-sms.md).
 - Популярный вопрос при выборе **автоматически отправляется как сообщение**; если пользователь не авторизован — сначала согласия и OTP, затем отправка.
 - Перечень таблиц и миграций App DB проектирует модуль `database` (и владельцы схем других сервисов); arch фиксирует только **разделение схем** PostgreSQL и контракты между сервисами.
 
@@ -42,12 +42,13 @@ HAN Chat - приложение для мигрантов, где стартов
 
 - Expo App: единая frontend-кодовая база для iOS, Android и web.
 - Keycloak: identity provider, OTP-only авторизация по номеру телефона.
+- SMS Service: internal durable order API, шаблоны и бессрочный журнал SMS; отдельный worker вызывает i-Digital Direct, callback обновляет только журнал.
 - api-backend: Python-приложение с REST API, realtime-доставкой сообщений и бизнес-логикой.
 - Nginx Reverse Proxy: единая публичная точка входа, HTTPS termination и маршрутизация на Keycloak/API/frontend web/Bitrix24.
 - Message Safety Service: отдельный сервис проверки входящих сообщений; вызов из API → `200 allow` | `403 deny` | `203 pending` + `task_id` (при `203` api-backend синхронно поллит task до финального вердикта, без очереди анализа на api-backend).
 - Bitrix24 Local App: локальное приложение, custom connector `han_mobile_app` для Bitrix24 Open Lines: чат, OAuth, webhook-события, маппинг `dialog_id` ↔ `bitrix_chat_id`.
 - Bitrix24 sync service: двусторонняя синхронизация App DB ↔ Битрикс24 CRM (Contact на MVP; маппинг ID, очередь через триггеры, webhook от роботов Bitrix24).
-- Managed PostgreSQL (приватная сеть, одна база): схемы `han_app`, `bitrix_sync`, `bitrix_local`, `keycloak`, `message_safety` — отдельный DB-user на схему.
+- Managed PostgreSQL (приватная сеть, одна база): схемы `han_app`, `bitrix_sync`, `bitrix_local`, `keycloak`, `message_safety`, `sms` — отдельный DB-user на схему.
 - Redis: rate limits API и realtime/service coordination (**не** OTP counters — они в Keycloak/SPI);
 - S3-data: production-хранилище проверенных файлов чата (`han-chat-attachments`) и документов компании (`han-chat-documents`).
 - S3-quarantine: временное хранилище загруженных файлов до вердикта Message Safety Service (`han-chat-quarantine`); read-only для `message-safety`.
@@ -57,7 +58,7 @@ HAN Chat - приложение для мигрантов, где стартов
 
 На первом этапе весь backend-контур работает на **одной VM** в облаке провайдера:
 
-- `nginx`, `api-backend`, `message-safety`, `keycloak`, `bitrix-sync`, `bitrix-local-app`, `redis`, `otel-collector` — в Docker Compose на VM;
+- `nginx`, `api-backend`, `message-safety`, `keycloak`, `sms-service`/worker, `bitrix-sync`, `bitrix-local-app`, `redis`, `otel-collector` — в Docker Compose на VM;
 - публичный доступ из интернета только через `nginx` (порты 80/443);
 - внутренние сервисы общаются по Docker-сети на localhost VM.
 
@@ -72,6 +73,7 @@ HAN Chat - приложение для мигрантов, где стартов
 | одна база / `message_safety` | `message-safety` | verdict cache, safety_task, rule config |
 | одна база / `bitrix_local` | `bitrix-local-app` | OAuth, inbox, `dialog_sessions` |
 | одна база / `keycloak` | Keycloak | учётные записи, realm, сессии IdP |
+| одна база / `sms` | `sms-service`, `sms-worker` | шаблоны, runtime settings, бессрочный журнал отправки/доставки SMS |
 
 Redis на первом этапе остаётся на VM в Docker (ephemeral/coordination). Selectel S3 — внешнее object storage: три бакета (`han-chat-quarantine`, `han-chat-attachments`, `han-chat-documents`); см. [`arch-00-glossary.md`](arch-00-glossary.md).
 
@@ -82,6 +84,9 @@ flowchart LR
     Client[Expo Mobile/Web App]
     Nginx[Nginx Reverse Proxy]
     Keycloak[Keycloak OTP]
+    SMS[SMS Service]
+    SMSWorker[SMS Worker]
+    Direct[i-Digital Direct]
     API[Python api-backend]
     Safety[Message Safety Service]
     DB[(PostgreSQL)]
@@ -95,8 +100,14 @@ flowchart LR
 
     Client -->|HTTPS REST + Realtime| Nginx
     Nginx -->|/auth| Keycloak
+    Nginx -->|exact POST /callbacks/idgtl/sms| SMS
     Nginx -->|"/api REST + WS realtime"| API
     Keycloak --> DB
+    Keycloak -->|durable SMS order| SMS
+    SMS --> DB
+    SMSWorker --> DB
+    SMSWorker -->|HTTPS POST /api/v1/message| Direct
+    Direct -->|delivery callback| Nginx
     API --> DB
     API --> Redis
     Client -->|presigned PUT| S3Q
@@ -222,8 +233,9 @@ Frontend не должен:
 Отвечает за:
 
 - OTP-only регистрацию и вход;
-- OTP по номеру телефона; проверка кода — в Keycloak (заглушка `KEYCLOAK_OTP_MOCK_*` или SMS-провайдер, см. arch-04 и «Поток авторизации»);
-- продуктовые лимиты OTP (`otp.phone.*` из `app_settings`) через authenticator/SPI и settings bridge `api-backend` (см. arch-04); счётчики попыток — в зоне Keycloak (Redis DB Keycloak/SPI или in-memory Keycloak), **не** в `api-backend`;
+- OTP по номеру телефона; генерация и локальная проверка кода, challenge lifecycle, limits и verify audit — в Keycloak;
+- в real mode — заказ в `sms-service` по закрытому `POST /internal/sms/v1/send`; Keycloak ждёт только `200/202` + `sms_message_id`, не вызывает Direct и не читает provider statuses;
+- продуктовые лимиты OTP (`otp.phone.*` из `app_settings`) через authenticator/SPI и settings bridge `api-backend` (см. arch-04); durable counters/challenges/events — в provider-owned таблицах schema `keycloak`, **не** в Redis и не в `api-backend`;
 - хранение учетных записей;
 - выдачу и обновление токенов (access + refresh);
 - настройку realm, clients, roles, policies;
@@ -238,7 +250,7 @@ Frontend не должен:
 | Expo frontend | Frontend → Keycloak (`/auth/*` через nginx) | OTP login (Authorization Code + PKCE), Refresh Token Grant, logout |
 | `api-backend` | api-backend → Keycloak JWKS/discovery | Валидация access token (issuer, audience, подпись); **не** вызывает Admin API в hot path |
 | Managed PostgreSQL | Keycloak → схема `keycloak` | Пользователи IdP, сессии, realm |
-| SMS-провайдер | Keycloak → SMS (post-MVP) | Доставка OTP; на MVP — mock code из `.env` |
+| `sms-service` | Keycloak → `sms-service` (real mode) | Durable order; service token, idempotency key и `sms_message_id` |
 
 Confidential **backend client** Keycloak (client credentials) в MVP **не обязателен**: S2S между нашими сервисами идёт по service tokens, не через Keycloak. Client можно завести заранее в realm как optional для будущих admin/ops сценариев.
 
@@ -253,6 +265,7 @@ Confidential **backend client** Keycloak (client credentials) в MVP **не об
 - маршрутизацию `/auth/*` или выделенного auth-домена в Keycloak;
 - маршрутизацию публичных `/bitrix/*` endpoint в `bitrix-local-app`;
 - маршрутизацию `/bitrix/sync/*` webhook endpoint в `bitrix-sync`;
+- маршрутизацию только exact `POST /callbacks/idgtl/sms` в `sms-service` по HTTPS, с allowlist актуального IP Direct и без логирования Basic Authorization;
 - защиту internal endpoint `bitrix-local-app` через private network или `nginx allowlist`;
 - отсутствие публичной маршрутизации к `message-safety` — сервис доступен только из внутренней Docker-сети;
 - передачу `X-Forwarded-For`, `X-Forwarded-Proto`, `X-Forwarded-Host`, `X-Request-ID` (если клиент не прислал `X-Request-ID` — nginx **генерирует** UUID и прокидывает upstream);
@@ -381,12 +394,12 @@ api-backend не решает, sync или async нужна проверка в
 5. Клиент может опционально согласиться на рекламные коммуникации.
 6. Если обязательные согласия не даны, отправка блокируется.
 7. Frontend запрашивает публичные настройки и показывает форму ввода номера телефона (единственный канал MVP).
-8. Keycloak запускает OTP-flow по телефону: клиент вводит номер, инициируется «отправка» OTP (при заглушке SMS фактически не уходит — см. arch-04).
-9. Лимиты OTP на **edge** — `nginx` (`NGINX_RATE_LIMIT_AUTH`); продуктовые лимиты `otp.phone.*` из `app_settings` применяются на стороне **Keycloak authenticator / SPI** (или обёртки OTP), не в `api-backend`. До интеграции SMS (mock OTP) достаточно edge + mock code.
+8. Keycloak запускает OTP-flow: в mock mode challenge сразу активен без SMS; в real mode Keycloak создаёт `ordering`, генерирует OTP, заказывает SMS в `sms-service` и активирует challenge только после durable order.
+9. Лимиты OTP на **edge** — `nginx`; продуктовые `otp.phone.*` применяет Keycloak. HTTP retry одного durable order использует прежние challenge/idempotency key и не увеличивает send counter.
 10. Клиент вводит OTP и отправляет его в Keycloak.
 11. **Keycloak проверяет корректность введённого OTP**:
     - при **`KEYCLOAK_OTP_MOCK_ENABLED=true`** (MVP и любой режим с включённой заглушкой): введённое значение должно **совпадать** с `KEYCLOAK_OTP_MOCK_CODE` из `.env`;
-    - при **`KEYCLOAK_OTP_MOCK_ENABLED=false`** (после интеграции с SMS-провайдером, см. бэклог): введённое значение должно **совпадать** с одноразовым OTP, сгенерированным Keycloak и отправленным провайдером на телефон клиента (с учётом TTL и лимита попыток).
+    - при **`KEYCLOAK_OTP_MOCK_ENABLED=false`**: значение сверяется локально с HMAC OTP, сгенерированного Keycloak и переданного в закрытом заказе `sms-service`; статусы Direct и callback на verify не влияют.
     - при неверном коде Keycloak возвращает ошибку; frontend не получает tokens, шаг 12 не выполняется.
 12. При успешной проверке frontend получает tokens через OIDC Authorization Code Flow with PKCE.
 13. Frontend с JWT вызывает **`POST /api/v1/auth/bootstrap`** — в теле передаёт локально принятые согласия и device metadata (см. arch-02). api-backend атомарно: `find-or-create` по JWT `sub` (`keycloak_sub`), телефон из JWT claims (не из body) → сохранение `UserConsent` на `user_id` → минимальный профиль.
@@ -539,7 +552,7 @@ App DB — **локальный кэш** для UI. Двусторонний syn
 
 ### Состав backend-контура
 
-Минимальный production-like контур на одной VM: `nginx`, `api-backend`, `message-safety`, `keycloak`, `bitrix-sync`, `bitrix-local-app`, `redis`, `otel-collector`. Managed PostgreSQL и Selectel S3 находятся вне Docker Compose.
+Минимальный целевой real-SMS контур на одной VM: `nginx`, `api-backend`, `message-safety`, `keycloak`, `sms-service`/worker, `bitrix-sync`, `bitrix-local-app`, `redis`, `otel-collector`. До SMS rollout сервисы SMS могут отсутствовать, но Keycloak обязан оставаться в mock mode.
 
 ### Предлагаемая структура backend-репозитория
 
@@ -583,6 +596,11 @@ backend/
     realm/
     themes/
     providers/
+  sms-service/
+    app/
+    migrations/
+    openapi.yaml
+    Dockerfile
   redis/
     docker-compose.yml
   observability/

architectory/arch-02-api-contracts.md

@@ -29,11 +29,13 @@
 | `BITRIX_API_FORWARD_TOKEN` | — | `bitrix-local-app` (исходящий) | то же | `Authorization: Bearer` |
 | `BITRIX_SYNC_SERVICE_TOKEN` | `bitrix-sync` | ops / мониторинг | `GET /internal/sync/v1/*` | `Authorization: Bearer` или `X-Service-Token` |
 | `KEYCLOAK_SETTINGS_BRIDGE_TOKEN` | `api-backend` | Keycloak SPI | `GET /internal/settings/v1/otp` | `Authorization: Bearer` |
+| `SMS_SERVICE_TOKEN` | `sms-service` | Keycloak SPI | `POST/GET /internal/sms/v1/*` | `Authorization: Bearer` |
 
 Пары значений (должны совпадать):
 
 - `BITRIX_LOCAL_APP_INTERNAL_TOKEN` (api-backend) = `BITRIX_INTERNAL_API_TOKEN` (bitrix-local-app)
 - `BITRIX_API_FORWARD_TOKEN` (bitrix-local-app) = `BITRIX_API_INBOX_TOKEN` (api-backend)
+- `KEYCLOAK_SMS_SERVICE_TOKEN` (Keycloak) = `SMS_SERVICE_TOKEN` (`sms-service`)
 
 Генерация: `openssl rand -hex 32`. Секреты не коммитить.
 
@@ -340,6 +342,7 @@ Transport: **WebSocket** over HTTPS (`wss://`), JWT в query `?access_token=` и
 | `message-safety` | `message-safety/openapi.yaml` | нет (internal) |
 | `bitrix-local-app` | `bitrix-local-app/openapi.yaml` | частично (`/bitrix/*`, health) |
 | `bitrix-sync` | `bitrix-sync/openapi.yaml` | нет (internal + webhook) |
+| `sms-service` | `sms-service/openapi.yaml` + callback JSON Schema | internal send/read; публичен только exact callback |
 
 Правила:
 
@@ -353,9 +356,58 @@ Keycloak SPI получает product limits OTP из `app_settings` через
 
 | Контракт | Владелец | Потребитель | Назначение | Защита |
 |---|---|---|---|---|
-| `GET /internal/settings/v1/otp` | `api-backend` | Keycloak SPI | `otp.phone.max_send_attempts_per_24h`, `otp.phone.min_seconds_between_attempts`, `otp.phone.max_verify_attempts`, cache metadata | internal network + Bearer `KEYCLOAK_SETTINGS_BRIDGE_TOKEN` |
+| `GET /internal/settings/v1/otp` | `api-backend` | Keycloak SPI | OTP limits + `code_length`, `ttl_seconds`, `sms_order_timeout_ms`, cache metadata | internal network + Bearer `KEYCLOAK_SETTINGS_BRIDGE_TOKEN` |
 
-Ответ не содержит секретов и PII. При недоступности endpoint Keycloak SPI использует последнее валидное cached value; если cache пустой — fail-closed для выдачи OTP.
+Ответ:
+
+```json
+{
+  "max_send_attempts_per_24h": 3,
+  "min_seconds_between_attempts": 30,
+  "max_verify_attempts": 5,
+  "code_length": 6,
+  "ttl_seconds": 60,
+  "sms_order_timeout_ms": 3000,
+  "version": "2026-07-22T14:00:00Z",
+  "cache_ttl_seconds": 60
+}
+```
+
+Ответ не содержит секретов и PII. Challenge сохраняет snapshot `code_length`, `ttl_seconds` и `version`. При недоступности endpoint Keycloak SPI использует последнее валидное cached value; если cache пустой — fail-closed для выдачи нового OTP.
+
+## Keycloak SPI ↔ `sms-service`
+
+Контракт действует в real mode; в mock mode Keycloak не вызывает `sms-service`. API доступен только в закрытой сети `backend`, Bearer token — парные `KEYCLOAK_SMS_SERVICE_TOKEN`/`SMS_SERVICE_TOKEN`. Caller v1 фиксирован как `keycloak`, process/template — `auth_otp`, channel — `SMS`, provider — `idgtl`; эти поля не доверяются request body.
+
+### `POST /internal/sms/v1/send`
+
+```json
+{
+  "idempotency_key": "keycloak:challenge:<CHALLENGE_ID>",
+  "template_code": "auth_otp",
+  "locale": "ru",
+  "phone_e164": "+79001234567",
+  "substitutions": {"code": "<OTP>", "ttl_min": "<TTL_MIN>"},
+  "customer_ref": "<CHALLENGE_ID>",
+  "message_ttl_sec": 60
+}
+```
+
+- Строгая проверка E.164, TTL Direct `60..86400`, locale и точного набора placeholders; неизвестный/пропущенный placeholder → `422 sms_request_invalid`.
+- В одной transaction рендерится active approved `sms_template` и создаётся `sms_outbound_message` (`pending`/`unknown`); внешний Direct API в request handler не вызывается.
+- Новый durable order → `202` с `sms_message_id`, `ordered_at`; идемпотентный повтор с тем же fingerprint → `200` и тот же id; тот же key с другим payload → `409 idempotency_key_reused`.
+- Остальные коды: `401 unauthorized`, `429 rate_limit_exceeded`, `503 sms_service_unavailable`; envelope общий для arch-02.
+- Keycloak считает заказ успешным только при `200/202` и валидном `sms_message_id`, сохраняет его в challenge/event и не запрашивает provider status.
+
+### `GET /internal/sms/v1/messages/{sms_message_id}`
+
+Диагностический read для Keycloak только по собственному `requester_service`. Телефон всегда masked; OTP, substitutions и `body_rendered` не возвращаются.
+
+### `POST /callbacks/idgtl/sms`
+
+Единственный публичный SMS endpoint. Только HTTPS и POST через root nginx; source IP `185.203.96.7` повторно сверяется перед production, применяется allowlist. Direct передаёт Basic auth, проверяемый `sms-service` по `IDGTL_SMS_CALLBACK_USERNAME`/`IDGTL_SMS_CALLBACK_PASSWORD`; credentials/Authorization не логируются.
+
+Callback body — массив; items валидируются и дедуплицируются по `(message_uuid, callback_event, status, status_time)`. Повторы и out-of-order события ожидаемы. Callback обновляет только delivery fields журнала после DB commit, не уведомляет Keycloak и не влияет на OTP verify. Transient DB failure → 5xx для повтора Direct.
 
 ## Frontend ↔ Keycloak
 
@@ -368,14 +420,14 @@ Keycloak **обязателен** в production-like контуре с перв
 | OIDC logout | Keycloak | Expo frontend | Завершение сессии Keycloak, очистка tokens |
 | OIDC Discovery (`/.well-known/openid-configuration`) | Keycloak | Expo frontend, `api-backend` | issuer, token/jwks endpoints |
 | JWKS | Keycloak | `api-backend` | Проверка подписи access token (issuer, audience, exp) |
-| OTP authenticator / SPI | Keycloak | — | Проверка OTP; product limits `otp.phone.*`; mock или SMS |
+| OTP authenticator / SPI | Keycloak | — | Генерация/локальная проверка OTP, product limits, challenge lifecycle и вызов `sms-service` в real mode |
 | PostgreSQL schema `keycloak` | Keycloak | Managed PostgreSQL | Учётные записи IdP |
 
 Frontend не обращается напрямую к Keycloak DB и не хранит парольные credentials. Парольная авторизация в MVP отключена.
 
 **`api-backend` ↔ Keycloak:** только **валидация JWT** по JWKS/discovery (кэш ключей). Admin REST / User API Keycloak в hot path **не** используются. Телефон и `sub` для `bootstrap` берутся из claims access token.
 
-**OTP (Keycloak):** единственный канал первичной авторизации — телефон. OTP-flow нужен, когда refresh token отсутствует или истёк. При действующем refresh token frontend использует **Refresh Token Grant** и не показывает OTP. После ввода кода **Keycloak проверяет OTP**: при `KEYCLOAK_OTP_MOCK_ENABLED=true` — сверка с `KEYCLOAK_OTP_MOCK_CODE` (`.env`); при `false` — сверка с OTP от SMS-провайдера (post-MVP, [`!Backlog.md`](../../HAN_chat/!Backlog.md)). Счётчики и product limits OTP — **только** Keycloak/SPI (+ nginx edge); `api-backend` OTP **не** проверяет и **не** ведёт OTP counters в Redis.
+**OTP (Keycloak):** единственный канал первичной авторизации — телефон. При действующем refresh token OTP не показывается. Keycloak всегда является источником истины verify: mock сравнивает secret-код, real mode — локальный HMAC случайного OTP. `sms-service` только принимает durable order, рендерит шаблон, отправляет через Direct worker и ведёт provider journal. API верификации Direct `/verifier/send` и `/verifier/check` запрещён. Счётчики и product limits — только Keycloak/SPI (+ nginx edge).
 
 **Clients в realm (MVP):**
 

architectory/arch-03-docker-compose-blueprint.md

@@ -21,8 +21,9 @@
   - `/auth/*` → `keycloak`;
   - `/bitrix/*` (public: `/bitrix/handler`, `/bitrix/install`, `/bitrix/placement`, `/health/*` для `bitrix-local-app`) → `bitrix-local-app`;
   - `/bitrix/sync/*` (public: webhook CRM sync для `bitrix-sync`) → `bitrix-sync`;
+  - exact `POST /callbacks/idgtl/sms` → `sms-service`; остальные методы и SMS paths не публикуются;
   - web-сборка frontend или прокси на dev-сервер;
-  - `/internal/openlines/*`, `/internal/safety/*`, `/internal/sync/*` **не публикуются** наружу — доступны только из внутренней Docker-сети.
+  - `/internal/openlines/*`, `/internal/safety/*`, `/internal/sync/*`, `/internal/sms/*` **не публикуются** наружу — доступны только из внутренней Docker-сети.
 - Никакой другой `nginx` (ни в контейнере сервиса, ни на хосте) не терминирует внешний HTTPS для backend-контура. Site-конфиг `tohin.ru` на хосте, если используется, должен проксировать весь трафик на корневой `nginx` контейнера, а не на порты отдельных сервисов напрямую.
 
 ### Структура compose через `include`
@@ -65,12 +66,14 @@ include:
   - bitrix-sync/docker-compose.yml
   - bitrix-local-app/docker-compose.yml
   - keycloak/docker-compose.yml
+  - sms-service/docker-compose.yml
   - redis/docker-compose.yml
   - observability/docker-compose.yml
 
 networks:
   public:
   backend:
+  egress:
   observability:
 
 volumes:
@@ -122,6 +125,7 @@ Reverse proxy и единственная публичная точка вход
 - маршрутизирует `/auth/*` в `keycloak` или проксирует отдельный auth-домен;
 - маршрутизирует публичные `/bitrix/*` endpoint в `bitrix-local-app`;
 - маршрутизирует `/bitrix/sync/*` webhook endpoint в `bitrix-sync`;
+- маршрутизирует только exact `POST /callbacks/idgtl/sms` в `sms-service:8080`; применяет HTTPS, подтверждённый allowlist source IP Direct, body/rate limits и redaction Basic Authorization;
 - закрывает `/internal/*` (в т.ч. `bitrix-local-app`, `message-safety`, `bitrix-sync` ops) от публичного доступа — только private network Docker/VPC;
 - **не публикует** `message-safety` наружу;
 - **production-like / production**: отдаёт **статическую сборку Expo web** из volume или каталога (`/usr/share/nginx/html` или аналог); `index.html` + assets, SPA fallback `try_files $uri /index.html`;
@@ -217,7 +221,7 @@ Python worker/service **двусторонней** синхронизации Ap
 Требования:
 
 - подключение только из приватной сети VPC (VM → managed PostgreSQL);
-- одна managed база: схемы `han_app`, `bitrix_sync`, `message_safety`, `bitrix_local`, `keycloak`;
+- одна managed база: схемы `han_app`, `bitrix_sync`, `message_safety`, `bitrix_local`, `keycloak`, `sms`;
 - отдельные DB-пользователи с доступом только к своей схеме; исключение: `bitrix_sync_user` дополнительно имеет ограниченный GRANT на `han_app` (`sync_queue`, `entity_external_mapping`, tracked columns профиля — детали схемы TBD в спецификации database);
 - TLS к managed PostgreSQL обязателен;
 - миграции Alembic выполняются отдельной командой при деплое;
@@ -236,10 +240,19 @@ Identity provider. **Обязателен** в compose-контуре с пер
 - включены proxy settings для работы за `nginx`;
 - импорт realm в local/dev;
 - использует managed PostgreSQL, схема `keycloak` (см. раздел «Managed PostgreSQL» выше);
-- OTP mock / SMS SPI — см. arch-04;
+- OTP mock / SMS SPI — см. arch-04; real mode вызывает только `sms-service` по сети `backend`, сам Keycloak к Direct/`egress` не подключён;
 - healthcheck;
 - взаимодействия — [`arch-02-api-contracts.md`](arch-02-api-contracts.md), «Frontend ↔ Keycloak», и [`arch-01-system-architecture.md`](arch-01-system-architecture.md), «Keycloak».
 
+### sms-service и sms-worker
+
+- `sms-service`: networks `backend`, `observability` и `egress` только если тот же process принимает callback и выполняет worker; `expose: 8080`, без host `ports`.
+- При отдельном `sms-worker`: networks только `egress`, `observability` и доступ к managed PG; HTTP port не exposed/published.
+- Оба используют `SMS_DATABASE_URL` к schema `sms`; только worker получает `IDGTL_SMS_API_KEY`.
+- Callback credentials получает receiver для проверки и worker для формирования callback URL; Keycloak получает только `KEYCLOAK_SMS_SERVICE_TOKEN`.
+- `sms-service` применяет собственные versioned migrations/seed; DDL-on-start запрещён. Readiness проверяет DB/schema, active approved `auth_otp` template, sender и API-key configuration.
+- Ожидание Direct до 70 секунд происходит только в worker. `uncertain` не retry-ится автоматически; provider outage не создаёт restart loop и не отменяет active Keycloak challenge.
+
 ### redis
 
 Кэш, rate limiting, coordination (не единственное хранилище бизнес-событий).
@@ -269,6 +282,7 @@ Identity provider. **Обязателен** в compose-контуре с пер
 
 - `public`: `nginx`, `keycloak` (для прокси `/auth/*`), frontend static/dev access, внешний HTTPS entrypoint.
 - `backend`: `api-backend`, `message-safety`, `bitrix-sync`, `bitrix-local-app`, `keycloak`, `redis` (managed PostgreSQL — вне compose, в VPC).
+- `egress`: только сервисы с утверждёнными исходящими интеграциями; для SMS — `sms-worker`, но не Keycloak. Production real mode требует фактический статический egress IP/NAT, записанный в inventory и переданный Direct для allowlist.
 - `observability`: `otel-collector` + сервисы, экспортирующие telemetry.
 
 Базы данных, Redis, Keycloak internal port и API internal port не должны публиковаться наружу. `message-safety` доступен только внутри сети `backend`. Основной пользовательский путь должен идти через `nginx` и HTTPS.
@@ -406,6 +420,7 @@ WAF не заменяет обязательные лимиты, валидац
 - `bitrix-sync`: `/health/live` проверяет процесс; `/health/ready` проверяет PostgreSQL, доступ к `sync_queue`, worker state и CRM webhook config; при `BITRIX_SYNC_ENABLED=false` ready возвращает degraded/not-ready с причиной `sync_disabled`;
 - `bitrix-local-app`: `/health/live` проверяет процесс; `/health/ready` показывает PostgreSQL, OAuth-токены после установки приложения, connector activation и возможность forward в API при включённом `BITRIX_API_FORWARD_URL`;
 - `keycloak`: health endpoint Keycloak; readiness — подключение к managed PostgreSQL;
+- `sms-service`: live — процесс; ready — schema/migrations, active approved template, sender/API key; Direct доступность — отдельный dependency status, не причина restart loop;
 - `redis`: `redis-cli ping`;
 
 Наружу через `nginx` публикуются только health endpoint, которые нужны Bitrix24 install/callback validation или внешнему мониторингу. Internal services (`message-safety`, internal `bitrix-sync`, Redis, otel) проверяются только из Docker/VPC-сети.
@@ -413,13 +428,16 @@ WAF не заменяет обязательные лимиты, валидац
 ## Порядок запуска
 
 1. `redis` (managed PostgreSQL должна быть доступна до старта зависимых сервисов).
-2. `keycloak`.
-3. `otel-collector`.
-4. `message-safety`.
-5. `api-backend`.
-6. `bitrix-local-app`.
-7. `bitrix-sync`.
-8. `nginx`.
+2. `otel-collector`.
+3. `api-backend` и seed OTP settings.
+4. `sms-service`/worker после migrations/seed (Keycloak пока mock).
+5. `keycloak`.
+6. `message-safety`.
+7. `bitrix-local-app`.
+8. `bitrix-sync`.
+9. `nginx`.
+
+Порядок rollout SMS подробнее задаёт module-11/module-10. Зависимости запуска не образуют цикл: Keycloak стартует при недоступном `sms-service`; это блокирует только новые real-mode orders, а verify уже active challenges продолжается по snapshot.
 
 `depends_on` не заменяет проверку готовности. Сервисы должны уметь ждать зависимости или корректно завершаться с понятной ошибкой. `api-backend` должен ждать готовности `message-safety` (healthcheck), т.к. отправка сообщения синхронно зависит от `POST /internal/safety/v1/messages/check`.
 

architectory/arch-04-settings-and-content.md

@@ -10,6 +10,7 @@
 |---|---|---|
 | **Инфраструктура** | `.env` | подключения, URL, секреты, nginx/TLS, service tokens |
 | **Бизнес-логика** | таблица **`app_settings`** | лимиты, флаги, телефоны, типы файлов, CORS, consent URLs |
+| **Настройки SMS runtime** | таблица **`sms.sms_setting`** | sender default, provider timeouts, callback flag, worker intervals |
 | **Контент** | `text_resources`, `popular_questions` | тексты UI |
 
 Managed PostgreSQL **поднимается до** развёртывания приложения. Бизнес-настройки **не дублируются** в `.env`: seed в `app_settings` выполняется миграцией/скриптом модуля `database` **до** первого запуска `api-backend`.
@@ -27,8 +28,8 @@ Managed PostgreSQL **поднимается до** развёртывания п
 - секреты: S3, Bitrix OAuth, service tokens, webhook-тokens;
 - параметры **nginx/TLS** и edge rate limits (`NGINX_RATE_LIMIT_*`);
 - идентификация Keycloak: realm, audience, public/internal URL;
-- **OTP-заглушка MVP** (`KEYCLOAK_OTP_MOCK_*`) — infra/dev-секрет, не бизнес-настройка;
-- технические таймауты worker-ов (`MESSAGE_SAFETY_*`, интервалы `bitrix-sync`).
+- переключатель и секрет временного OTP mock (`KEYCLOAK_OTP_MOCK_*`); mock обязателен до прохождения real-SMS rollout gates и запрещён как незаявленный fallback;
+- технические параметры сервисов, пока профильная спецификация не определила service-owned settings; для `sms-service` runtime-параметры уже вынесены в `sms.sms_setting`.
 
 **Запрещено в `.env` (→ только `app_settings`):**
 
@@ -85,7 +86,7 @@ Managed PostgreSQL **поднимается до** развёртывания п
 | Группа | Ключи |
 |---|---|
 | Auth | `auth.phone.enabled`, `auth.password.enabled` |
-| OTP (продукт; потребитель — Keycloak SPI через settings bridge api-backend) | `otp.phone.max_send_attempts_per_24h`, `otp.phone.min_seconds_between_attempts`, `otp.phone.max_verify_attempts` |
+| OTP (продукт; потребитель — Keycloak SPI через settings bridge api-backend) | `otp.phone.max_send_attempts_per_24h`, `otp.phone.min_seconds_between_attempts`, `otp.phone.max_verify_attempts`, `otp.phone.code_length`, `otp.phone.ttl_seconds`, `otp.phone.sms_order_timeout_ms` |
 | Оператор | `operator.call.phone` |
 | Consent | `consent.personal_data.*`, `consent.user_agreement.*`, `consent.marketing.*` |
 | Файлы чата | `chat.attachments.*` |
@@ -102,6 +103,9 @@ auth.password.enabled=false
 otp.phone.max_send_attempts_per_24h=3
 otp.phone.min_seconds_between_attempts=30
 otp.phone.max_verify_attempts=5
+otp.phone.code_length=6
+otp.phone.ttl_seconds=60
+otp.phone.sms_order_timeout_ms=3000
 
 operator.call.phone=+74999591007
 
@@ -137,6 +141,27 @@ security.public_cache.max_age_seconds=3600
 
 ---
 
+## Service-owned настройки `sms-service`
+
+Параметры, изменение которых не меняет Compose, секреты, URL или сетевую топологию, хранятся в `sms.sms_setting`, а не в `.env`.
+
+Ключи и seed:
+
+```text
+provider.idgtl.default_sender_name=<approved>
+provider.idgtl.connect_timeout_ms=3000
+provider.idgtl.request_timeout_ms=70000
+provider.idgtl.callback_enabled=true
+worker.poll_interval_ms=500
+worker.lease_seconds=90
+```
+
+В `.env` остаются только `SMS_DATABASE_URL`, URL внутренних/внешних сервисов, service tokens, Direct API key и callback credentials. Детальный контракт — `module-11-idgtl-sms.md`.
+
+`<approved>` — обязательный deployment placeholder, а не допустимое production-значение. Перед real mode должны существовать active approved template `auth_otp` с точными placeholders `code`/`ttl_min` и согласованный `senderName`. Отсутствие template/sender делает readiness false.
+
+---
+
 ## Пример `.env.example`
 
 Только инфраструктура. Бизнес-параметры — в seed `app_settings`.
@@ -161,6 +186,7 @@ BITRIX_DATABASE_URL=postgresql://bitrix_local_app:change-me@<HAN_PG_HOST>:<HAN_P
 BITRIX_SYNC_APP_DATABASE_URL=postgresql://bitrix_sync_user:change-me@<HAN_PG_HOST>:<HAN_PG_PORT>/<HAN_PG_DATABASE>
 BITRIX_SYNC_DATABASE_URL=postgresql://bitrix_sync_user:change-me@<HAN_PG_HOST>:<HAN_PG_PORT>/<HAN_PG_DATABASE>
 MESSAGE_SAFETY_DATABASE_URL=postgresql://message_safety_app:change-me@<HAN_PG_HOST>:<HAN_PG_PORT>/<HAN_PG_DATABASE>
+SMS_DATABASE_URL=postgresql://sms_user:change-me@<HAN_PG_HOST>:<HAN_PG_PORT>/<HAN_PG_DATABASE>
 KEYCLOAK_DB_URL=jdbc:postgresql://<HAN_PG_HOST>:<HAN_PG_PORT>/<HAN_PG_DATABASE>?user=keycloak_user&password=change-me&currentSchema=keycloak
 KC_DB_URL_PROPERTIES=currentSchema=keycloak
 # Selectel PgBouncer 5433: pool_mode=session; search_path задаётся на уровне ролей.
@@ -190,7 +216,7 @@ NGINX_RATE_LIMIT_PUBLIC=60r/m
 NGINX_RATE_LIMIT_POLLING=60r/m
 
 # =============================================================================
-# Keycloak (infra; OTP-заглушка — dev/MVP)
+# Keycloak (mock остаётся true до controlled SMS cutover)
 # =============================================================================
 KEYCLOAK_PUBLIC_URL=https://tohin.ru/auth
 KEYCLOAK_INTERNAL_URL=http://keycloak:8080
@@ -198,6 +224,7 @@ KEYCLOAK_REALM=han-chat
 KEYCLOAK_AUDIENCE=han-chat-api
 KEYCLOAK_OTP_MOCK_ENABLED=true
 KEYCLOAK_OTP_MOCK_CODE=1234
+KEYCLOAK_SMS_SERVICE_URL=http://sms-service:8080
 
 # =============================================================================
 # Redis (I4: раздельные DB index)
@@ -219,6 +246,17 @@ BITRIX_INTERNAL_API_TOKEN=change-me
 BITRIX_API_FORWARD_TOKEN=change-me
 BITRIX_SYNC_SERVICE_TOKEN=change-me
 KEYCLOAK_SETTINGS_BRIDGE_TOKEN=change-me
+SMS_SERVICE_TOKEN=change-me
+KEYCLOAK_SMS_SERVICE_TOKEN=change-me
+
+# =============================================================================
+# SMS provider (URL и секреты; runtime-параметры — sms.sms_setting)
+# =============================================================================
+IDGTL_SMS_BASE_URL=https://direct.i-dgtl.ru
+IDGTL_SMS_API_KEY=change-me
+IDGTL_SMS_CALLBACK_PUBLIC_URL=https://tohin.ru/callbacks/idgtl/sms
+IDGTL_SMS_CALLBACK_USERNAME=change-me
+IDGTL_SMS_CALLBACK_PASSWORD=change-me
 
 # =============================================================================
 # api-backend (интеграции + resilience I2)
@@ -297,6 +335,8 @@ presigned URL и CORS Selectel; path-style адресация не поддер
 
 Все переменные — **только** в `backend/.env`. Отдельного хранилища нет.
 
+Для production `change-me`, `<...>`, примерные sender/template/API key/callback credentials отклоняются `validate-env`. `IDGTL_SMS_API_KEY` — выданный Direct готовый `TOKEN_1` для Basic, без повторного Base64. Реальный статический egress IP хранится в deployment inventory, а не env; если он не обеспечен NAT/сетевой конфигурацией, `KEYCLOAK_OTP_MOCK_ENABLED=false` запрещён.
+
 **Webhook-токены** (публичные callback, не service API): `BITRIX_APPLICATION_TOKEN`, `BITRIX_SYNC_WEBHOOK_TOKEN`.
 
 ## Namespace переменных Bitrix
@@ -317,16 +357,16 @@ presigned URL и CORS Selectel; path-style адресация не поддер
 
 ## Keycloak settings bridge для OTP
 
-Product limits OTP (`otp.phone.*`) хранятся в `app_settings`, но Keycloak не получает прямой доступ к схеме `han_app`.
+OTP settings (`otp.phone.*`) хранятся в `app_settings`, но Keycloak не получает прямой доступ к схеме `han_app`.
 
 MVP-механизм:
 
 1. `api-backend` читает публичные/служебные настройки из `app_settings` и кэширует их.
 2. Для Keycloak SPI доступен internal endpoint `GET /internal/settings/v1/otp` в Docker/VPC-сети, защищённый service token.
-3. Keycloak SPI читает `otp.phone.max_send_attempts_per_24h`, `otp.phone.min_seconds_between_attempts` и `otp.phone.max_verify_attempts` через этот endpoint с локальным cache TTL.
+3. Keycloak SPI читает limits, `otp.phone.code_length`, `otp.phone.ttl_seconds` и `otp.phone.sms_order_timeout_ms` через этот endpoint с локальным cache.
 4. При недоступности settings bridge SPI использует последнее валидное cache-значение; если cache пустой — fail-closed и не выдаёт OTP.
 
-Счётчики попыток OTP остаются в зоне Keycloak/SPI, не в `api-backend`.
+Challenge сохраняет snapshot TTL, длины кода и `settings_version`; изменение settings влияет только на новые challenges. Счётчики попыток OTP остаются в зоне Keycloak/SPI, не в `api-backend`.
 
 ## Разрешённые типы файлов чата (MVP)