Правки от GPT

2026-07-10 12:23:18 +03:00
parent 50fc053979
commit aa8761d1b3
11 changed files with 6188 additions and 1 deletions
@@ -0,0 +1,643 @@
+# module-06. Проектная спецификация `bitrix-local-app`
+
+> Статус: целевая production-спецификация MVP.  
+> Портал: `han0107.bitrix24.ru`; connector: `han_mobile_app`; Open Line: `8`.  
+> Источники: [`README.md`](README.md), [`arch-00-glossary.md`](arch-00-glossary.md), [`arch-01-system-architecture.md`](arch-01-system-architecture.md), [`arch-02-api-contracts.md`](arch-02-api-contracts.md), [`arch-03-docker-compose-blueprint.md`](arch-03-docker-compose-blueprint.md), [`arch-04-settings-and-content.md`](arch-04-settings-and-content.md), [`arch-05-agent-development-process.md`](arch-05-agent-development-process.md), [`module-01-api-backend.md`](module-01-api-backend.md), прототип [`../../HAN_chat/bitrix-local-app/README.md`](../../HAN_chat/bitrix-local-app/README.md) и [`../../HAN_chat/deploy/init-managed-postgres.py`](../../HAN_chat/deploy/init-managed-postgres.py).
+
+## 1. Назначение и приоритет
+
+Сервис является локальным серверным приложением Bitrix24 и адаптером Open Lines. Он изолирует OAuth и протокол `imconnector` от `api-backend`, надёжно доставляет разрешённые сообщения клиента оператору и события оператора обратно в HAN.
+
+При конфликте действуют приоритеты `README.md`. Настоящий документ детализирует существующие контракты, но не меняет их. Любой новый внешний/internal endpoint сначала фиксируется в `arch-02`.
+
+Канонический URL канала:
+
+```text
+https://han0107.bitrix24.ru/contact_center/connector/?ID=han_mobile_app&LINE=8
+```
+
+## 2. Ответственность и границы
+
+Сервис отвечает за:
+
+- install/lifecycle локального приложения и OAuth Bitrix24;
+- шифрованное хранение и безопасное обновление portal tokens;
+- `imconnector.register`, `imconnector.activate`, `event.bind`, status/retry setup;
+- публичный приём `ONAPP*` и `ONIMCONNECTOR*`;
+- tolerant parsing JSON/form/multipart и PHP-style массивов;
+- проверку callback, нормализацию, durable inbox, retry и DLQ;
+- `dialog_sessions`: `external_chat_id` (= `dialog_id`) ↔ `bitrix_chat_id` ↔ `session_id`;
+- идемпотентный outbound `api-backend` → `imconnector.send.messages`;
+- forward входящих сообщений/файлов и `dialog.closed` в `api-backend`;
+- `imconnector.send.status.delivery` только после durable ack API;
+- health, telemetry, audit технических переходов.
+
+Сервис не отвечает за:
+
+- JWT/пользовательскую авторизацию, Message Safety и App DB;
+- хранение истории HAN, realtime и S3;
+- CRM Contact/profile sync — это будущая зона `bitrix-sync`;
+- изменение `Dialog.status` в `han_app`;
+- публикацию internal API на edge.
+
+## 3. Технологический профиль и структура
+
+- Python 3.12+, FastAPI, Pydantic v2, Uvicorn.
+- SQLAlchemy 2 async + `asyncpg`; Alembic.
+- Один долгоживущий `httpx.AsyncClient` с bounded pool.
+- PostgreSQL managed, только схема `bitrix_local`.
+- OpenTelemetry и JSON logging.
+
+```text
+bitrix-local-app/
+  app/
+    main.py
+    settings.py
+    api/{public_bitrix,internal_openlines,health,schemas,errors,auth}.py
+    application/{install,setup,outbound,inbound,forward,delivery_ack}.py
+    domain/{entities,enums,policies}.py
+    infrastructure/
+      bitrix/{client,oauth,connector,parser,normalizer}.py
+      db/{models,repositories,uow}.py
+      crypto/{token_cipher,keyring}.py
+      resilience/{retry,circuit,rate_limit}.py
+      observability/{logging,metrics,tracing}.py
+    workers/{inbox_forward,outbox_delivery,setup_reconcile}.py
+  alembic/
+  tests/{unit,integration,contract,e2e}/
+  openapi.yaml
+  Dockerfile
+  docker-compose.yml
+```
+
+Router только валидирует/аутентифицирует; use case задаёт транзакцию; Bitrix adapter скрывает внешний payload.
+
+## 4. Публичные endpoint
+
+Сервис предоставляет следующие endpoint. Корневой nginx публикует первые три; health остаются internal по умолчанию и открываются exact-route только при явно выбранной ops/monitoring policy:
+
+| Method | Path | Назначение |
+|---|---|---|
+| GET/POST | `/bitrix/handler` | probe и callbacks `ONAPP*`/`ONIMCONNECTOR*` |
+| GET/POST | `/bitrix/install` | install callback/probe |
+| GET | `/bitrix/placement` | минимальный HTML placement |
+| GET | `/health/live` | liveness; internal по умолчанию |
+| GET | `/health/ready` | readiness; internal по умолчанию |
+
+`GET handler/install` возвращает безопасный `200`, не раскрывая OAuth/setup. POST принимает только bounded body и разрешённые content types. Placement имеет отдельный CSP `frame-ancestors` с точным allow-list Bitrix24.
+
+Internal `/internal/openlines/v1/*` доступны только по Docker/VPC network и **не маршрутизируются nginx наружу**.
+
+## 5. Internal Open Lines API
+
+Все вызовы требуют:
+
+```text
+Authorization: Bearer ${BITRIX_INTERNAL_API_TOKEN}
+X-Request-ID: UUID/ULID
+traceparent: optional W3C
+```
+
+Caller `api-backend` передаёт `BITRIX_LOCAL_APP_INTERNAL_TOKEN`, значение которого равно `BITRIX_INTERNAL_API_TOKEN`. Сравнение constant-time.
+
+### 5.1. `POST /internal/openlines/v1/messages`
+
+Одна операция — одно сообщение MVP. `Idempotency-Key` обязателен и равен `message_id`.
+
+```json
+{
+  "message_id": "uuid",
+  "external_chat_id": "uuid",
+  "occurred_at": "2026-07-10T09:00:00Z",
+  "user": {
+    "id": "uuid",
+    "display_name": "Клиент HAN"
+  },
+  "message": {
+    "content_kind": "text",
+    "text": "Здравствуйте",
+    "files": []
+  }
+}
+```
+
+Файловый вариант:
+
+```json
+{
+  "message_id": "uuid",
+  "external_chat_id": "uuid",
+  "occurred_at": "2026-07-10T09:00:00Z",
+  "user": {"id": "uuid", "display_name": "Клиент HAN"},
+  "message": {
+    "content_kind": "file",
+    "text": "",
+    "files": [{
+      "attachment_id": "uuid",
+      "name": "document.pdf",
+      "mime_type": "application/pdf",
+      "size_bytes": 12345,
+      "download_url": "https://short-lived-signed-url"
+    }]
+  }
+}
+```
+
+Правила:
+
+- `external_chat_id` строго UUID и равен App `dialog_id`;
+- `text` xor один file; unknown fields запрещены;
+- signed URL не сохраняется в обычные логи и редактируется в durable payload по истечении необходимости;
+- PII профиля не требуется; телефон/email не передаются;
+- fingerprint строится по стабильным полям без signed query;
+- тот же key/fingerprint возвращает прежний результат;
+- тот же key с иным fingerprint → `409 idempotency_key_reused`.
+
+Успех `200/201`:
+
+```json
+{
+  "status": "delivered",
+  "message_id": "uuid",
+  "external_chat_id": "uuid",
+  "bitrix_message_id": "string-or-null",
+  "dialog_session": {
+    "bitrix_chat_id": 1807,
+    "session_id": "sess-42"
+  }
+}
+```
+
+`api-backend` выставляет `delivery_status=delivered` только после этого ответа/duplicate result. `202` не считается финальной доставкой в основном синхронном flow.
+
+### 5.2. `GET /internal/openlines/v1/dialogs/{external_chat_id}`
+
+Возвращает active mapping:
+
+```json
+{
+  "external_chat_id": "uuid",
+  "bitrix_chat_id": 1807,
+  "session_id": "sess-42",
+  "status": "open",
+  "updated_at": "2026-07-10T09:00:00Z"
+}
+```
+
+`404` — mapping отсутствует/soft-deleted. Пользовательская PII не возвращается.
+
+### 5.3. `GET /internal/openlines/v1/status`
+
+Возвращает безопасный статус portal OAuth, connector registration/activation, event bindings, worker backlog и circuit state; токены и raw Bitrix response исключены. `200` может иметь `status=degraded`; `503` — нет usable OAuth/БД.
+
+### 5.4. `POST /internal/openlines/v1/setup/retry`
+
+Идемпотентно запускает reconcile `register → activate line 8 → event.bind`. Одновременно разрешён один run по portal advisory lock/DB lease. Ответ содержит per-step status. Endpoint ops-only с тем же Bearer и дополнительным service rate limit.
+
+## 6. Outbound: HAN → Open Lines
+
+1. Аутентифицировать caller и зарезервировать `outbound_messages` по `message_id`.
+2. При completed вернуть сохранённый sanitized result.
+3. Собрать `MESSAGES` Bitrix: `user.id`, `message.id/date/text/files`, `chat.id`.
+4. Вызвать `imconnector.send.messages` с `CONNECTOR=han_mobile_app`, `LINE=8`.
+5. Извлечь `CHAT_ID`, session `ID`, Bitrix message id из допускаемых вариантов ответа.
+6. В одной транзакции upsert `dialog_sessions`, записать result, status `delivered`.
+7. Вернуть ack API.
+
+Ambiguous timeout не разрешает слепой повтор без idempotency/reconciliation. Worker сверяет локальный state/session и повторяет только если метод/Bitrix semantics не создадут дубль; иначе `manual_review`/DLQ. Automatic retry допустим для connect failure до отправки, explicit rate-limit и известных transient ошибок.
+
+## 7. Install, OAuth и setup
+
+### 7.1. Install
+
+POST install/handler с `ONAPPINSTALL`:
+
+1. parse и strict validate `auth`;
+2. проверить expected portal domain `han0107.bitrix24.ru`, HTTPS `client_endpoint`, `member_id`;
+3. сохранить tokens до внешнего setup;
+4. создать `install_runs`;
+5. выполнить setup идемпотентно;
+6. вернуть `installed` либо `installed_with_errors`; partial setup не теряет OAuth.
+
+`ONAPPUNINSTALL` помечает portal installation `uninstalled`, запрещает outbound и планирует revocation/retention. В отличие от прототипа, usable tokens не остаются active.
+
+### 7.2. Token storage и encryption
+
+- `access_token`, `refresh_token`, `application_token` шифруются application-level envelope encryption (AES-256-GCM или эквивалент AEAD).
+- Master key только secret env/mount: `BITRIX_TOKEN_ENCRYPTION_KEY`; в БД — `ciphertext`, `nonce`, `key_version`.
+- AAD связывает ciphertext с `member_id`, portal domain и token type.
+- Поддерживается keyring current+previous для rolling rotation и re-encryption job.
+- Токены никогда не логируются, не экспортируются в metrics/traces и не возвращаются API.
+- DB/TLS и backup encryption остаются дополнительными слоями.
+
+### 7.3. Refresh
+
+- refresh заранее, когда `expires_at - now <= skew` (ориентир 60 с);
+- single-flight на portal через DB advisory lock/lease;
+- POST только на allow-listed `https://oauth.bitrix.info/oauth/token/`;
+- refresh token rotation сохраняется атомарно;
+- при `expired_token` — максимум один refresh+replay;
+- `invalid_grant` переводит installation в `reauth_required`, readiness degraded, outbound fail-closed;
+- timeout/retry bounded; secret/client credentials не попадают в exception text.
+
+### 7.4. Connector setup
+
+Используемые методы:
+
+- `imconnector.register`: `ID=han_mobile_app`, name/icon, `{BITRIX_PUBLIC_BASE_URL}/placement`;
+- `imconnector.activate`: connector, `LINE=8`, `ACTIVE=1`;
+- `event.bind`: `OnImConnectorMessageAdd`, `OnImConnectorDialogStart`, `OnImConnectorDialogFinish`;
+- `imconnector.status` для reconcile/readiness;
+- `imconnector.send.messages`;
+- `imconnector.send.status.delivery`.
+
+Каждый setup step хранит desired/observed state, attempts и safe error. Повтор не создаёт duplicate binding; если API Bitrix не гарантирует это, сначала проверяется status/list binding.
+
+## 8. Webhook parsing и безопасность
+
+Поддерживаются JSON, form-urlencoded, multipart и PHP-style keys/числовые dict. Parser:
+
+- ограничивает body/header/field count, nesting, array/message count и строковые длины;
+- NFKC не применяется к opaque ids/tokens;
+- не сохраняет неизвестный raw body без redaction;
+- принимает только известные events; прочие безопасно `ignored` с metric;
+- проверяет connector `han_mobile_app`, line `8`, expected member/domain;
+- проверяет `auth.application_token` constant-time против расшифрованного portal token и/или `BITRIX_APPLICATION_TOKEN`;
+- не доверяет IP как единственной аутентификации, но nginx edge limit/allow policy дополняет token;
+- всегда отвечает достаточно быстро после durable insert, чтобы Bitrix retry не создал storm.
+
+Невалидный security token не маскируется как успешная обработка в telemetry: внешний ответ может быть нейтральным, но audit/metric фиксируют reject. Callback secret и payload не логируются.
+
+## 9. Нормализация и inbox-контракт API
+
+Owned receiver находится в `api-backend`:
+
+```text
+POST http://api-backend:8000/internal/openlines/v1/inbox
+Authorization: Bearer ${BITRIX_API_FORWARD_TOKEN}
+```
+
+Значение равно `BITRIX_API_INBOX_TOKEN` на API.
+
+`message.new`:
+
+```json
+{
+  "event_id": "stable-opaque",
+  "event_type": "message.new",
+  "external_chat_id": "uuid",
+  "bitrix_message_id": "string",
+  "occurred_at": "2026-07-10T09:00:00Z",
+  "message": {
+    "text": "Ответ оператора или пустая строка",
+    "files": [{
+      "name": "scan.pdf",
+      "mime_type": "application/pdf",
+      "size_bytes": 12345,
+      "download_url": "https://..."
+    }]
+  }
+}
+```
+
+`dialog.closed`:
+
+```json
+{
+  "event_id": "stable-opaque",
+  "event_type": "dialog.closed",
+  "external_chat_id": "uuid",
+  "bitrix_message_id": null,
+  "occurred_at": "2026-07-10T09:00:00Z",
+  "message": null
+}
+```
+
+`event_id` обязателен согласно допущению module-01 A2; предпочтительно используется Bitrix event/message/session id, иначе versioned SHA-256 стабильных полей. `message.new` дополнительно unique по `(external_chat_id, bitrix_message_id)`.
+
+Пустые text+files отклоняются. URL файла передаётся только API; API защищается от SSRF, скачивает с лимитами и сохраняет в S3-data. Local app не скачивает/не хранит файл.
+
+## 10. Delivery ack входящего события
+
+Критический инвариант:
+
+```text
+Bitrix webhook → durable inbox → API 201/duplicate 200/204
+→ только затем imconnector.send.status.delivery
+```
+
+Ack запрещён при timeout/5xx/неприменённом `404` API. Если API commit успешен, но HTTP response потерян, повтор forward получает duplicate ack, после чего delivery status безопасно отправляется. Ack имеет собственный outbox/retry. Ошибка ack не повторяет application события в API.
+
+## 11. Inbox, outbox, DLQ и backoff
+
+### Inbox
+
+Webhook transaction сохраняет event, normalized payload/fingerprint и initial status. Worker использует `FOR UPDATE SKIP LOCKED`, lease и heartbeat.
+
+States:
+
+```text
+received → forwarding → api_acked → ack_pending → completed
+                   ↘ retry
+received/forwarding/retry → dead_letter
+```
+
+### Outbound messages
+
+States: `received | sending | delivered | retry | ambiguous | dead_letter`. Unique `message_id`; payload versioned; signed URLs не должны переживать TTL — при retry API обязан дать актуальный URL по согласованному recovery контракту либо операция уходит в reconciliation.
+
+### Backoff
+
+- exponential full jitter, ориентир 1, 2, 4, 8… max 300 с;
+- учитывать `Retry-After` Bitrix/API;
+- max attempts и max age — infra env;
+- permanent 4xx/schema/auth не повторяются автоматически;
+- DLQ содержит safe error code, не token/raw PII;
+- replay — ops runbook/CLI с audit, не публичный endpoint MVP.
+
+## 12. PostgreSQL `bitrix_local`
+
+Общие правила: UUID/timestamptz, schema-qualified DDL, soft delete для прикладных records, технические queue rows архивируются/удаляются по retention. Runtime role `bitrix_local_app`; отдельная migration role. Прямого доступа к `han_app` нет.
+
+### 12.1. `portal_installations`
+
+`id`, `member_id` unique, `domain`, `client_endpoint`, encrypted token columns, `expires_at`, `scope`, `key_version`, `install_status`, `setup_status`, `last_refresh_at`, `last_error_code`, common fields.
+
+Indexes: unique active `member_id`; unique active normalized domain. MVP разрешает только один active expected portal.
+
+### 12.2. `connector_setup`
+
+`id`, `portal_id`, `connector_id`, `line_id`, `registered`, `activated`, `bindings_json`, `desired_version`, `observed_at`, `next_retry_at`, `attempt_count`, lease/error fields. Unique `(portal_id, connector_id, line_id)`.
+
+### 12.3. `dialog_sessions`
+
+`id`, `external_chat_id uuid`, `bitrix_chat_id bigint NULL`, `session_id varchar NULL`, `portal_id`, `status open|closed`, common fields.
+
+Indexes:
+
+- unique active `external_chat_id`;
+- index `(bitrix_chat_id) WHERE record_status='A'`;
+- index `(session_id)`;
+- `(status, updated_at)`.
+
+Связь с user_id не нужна: идентичность принадлежит App DB.
+
+### 12.4. `inbox_events`
+
+`id`, `event_id`, `event_type`, `external_chat_id`, `bitrix_message_id`, `payload_fingerprint`, `normalized_json`, `status`, attempts/next/lease, `api_ack_status`, `delivery_ack_status`, safe error, timestamps.
+
+Unique `event_id`; unique partial `(external_chat_id, bitrix_message_id)`; worker index `(status,next_attempt_at)`.
+
+Raw payload хранится только если необходим для forensic, зашифрован/редактирован и с коротким retention; preferred — минимальный normalized payload.
+
+### 12.5. `outbound_messages`
+
+`id`, `message_id uuid unique`, `external_chat_id uuid`, `request_fingerprint`, `payload_json`, `status`, `bitrix_message_id`, `response_json`, attempts/lease/error/timestamps. Index worker `(status,next_attempt_at)`.
+
+### 12.6. `delivery_ack_outbox`
+
+Unique inbox event; status/attempt/next/lease, minimal Bitrix delivery DTO. Не содержит API token.
+
+### 12.7. `install_runs` и `audit_events`
+
+Append-only setup step/results и security/ops actions без tokens/raw payload. BRIN/date indexes при росте.
+
+## 13. Alembic и транзакции
+
+- Никакого `CREATE TABLE IF NOT EXISTS` при startup.
+- `alembic upgrade head` — отдельный deploy step.
+- Expand/migrate/contract, forward-fix; destructive migration только после backup/согласования.
+- Smoke upgrade пустой и предыдущей версии.
+- Внешний HTTP не выполняется внутри DB transaction.
+- Claim → commit lease → external call → finalize under row lock.
+- Setup/refresh используют portal-scoped lock.
+
+## 14. Bitrix rate limits и resilience
+
+- Ограничить concurrency (начально 2 на portal) и локальный token bucket.
+- Разделить quotas setup, outbound, ack/status.
+- На Bitrix rate-limit учитывать headers/body code и `Retry-After`.
+- Circuit breakers отдельно: OAuth endpoint, portal REST, API forward.
+- Timeout: connect 3 с, обычный REST/read 10–15 с, OAuth 10 с; значения infra env.
+- 4xx domain/schema не открывает circuit; 429/transient/timeout учитываются по policy.
+- Half-open имеет один probe; retry storms предотвращаются jitter/queue concurrency.
+- Один `httpx` pool; TLS verify обязателен; redirects для token/REST запрещены либо allow-listed.
+
+## 15. Health
+
+`GET /health/live`: только процесс/event loop, `200`.
+
+`GET /health/ready` с коротким timeout проверяет:
+
+- PostgreSQL `SELECT 1`, expected Alembic revision;
+- usable active portal OAuth либо сообщает `portal_not_installed`;
+- connector desired state register+line 8+bindings;
+- workers heartbeat/lease;
+- backlog age/DLQ thresholds;
+- forward URL/token configured;
+- circuit state.
+
+DB/schema failure → `503`. До install сервис может быть `200 degraded` или `503 portal_not_installed` согласно ops policy; для production traffic выбран `503`, liveness остаётся 200. Ответ не делает внешних Bitrix calls на каждый probe — использует свежий cached observed state.
+
+## 16. Observability
+
+JSON fields: timestamp, level, `service.name=bitrix-local-app`, module, event, request_id, trace/span id, route, event_type, portal hash/member hash, message/event id hash, attempt, queue age, dependency, status/error code, duration.
+
+Не логируются OAuth/application/service tokens, Authorization, raw callback, message text, phone/email/name, filenames с PII, file/download URL, response body Bitrix.
+
+Metrics:
+
+- HTTP latency/status;
+- callback accepted/rejected/duplicate;
+- parser variants/errors;
+- OAuth refresh success/failure/time-to-expiry;
+- connector setup desired/observed;
+- outbound success/retry/ambiguous/DLQ;
+- inbox depth/oldest age/retry/DLQ;
+- API forward and delivery ack;
+- Bitrix REST latency/rate-limit/circuit;
+- DB pool/lease/readiness.
+
+IDs не metric labels. Trace context передаётся в API; внешний Bitrix call — child span без token/query.
+
+## 17. Security
+
+- TLS boundary — root nginx; internal HTTP только backend network.
+- Internal endpoints не edge-routed, Bearer token обязателен.
+- Exact host/domain/connector/line allow-list.
+- `client_endpoint` из callback валидируется против portal allow-list для защиты SSRF.
+- Strict DTO/body limits; parameterized SQL.
+- OAuth encryption+key rotation; secrets только env/secret mount.
+- Non-root, read-only root fs, tmpfs, dropped capabilities.
+- OpenAPI UI off production; committed OpenAPI 3.1 обязателен.
+- CORS не нужен; placement не получает secrets.
+- Error envelope не раскрывает host/stack/raw dependency response.
+- Dependency/image scanning и pinned lock/image.
+
+## 18. Env
+
+Канонические из arch-04:
+
+```text
+BITRIX_DATABASE_URL
+BITRIX_CLIENT_ID
+BITRIX_CLIENT_SECRET
+BITRIX_CONNECTOR_ID=han_mobile_app
+BITRIX_CONNECTOR_NAME=HAN Mobile App
+BITRIX_OPEN_LINE_ID=8
+BITRIX_PUBLIC_BASE_URL=https://tohin.ru/bitrix
+BITRIX_APPLICATION_TOKEN
+BITRIX_INTERNAL_API_TOKEN
+BITRIX_API_FORWARD_URL=http://api-backend:8000/internal/openlines/v1/inbox
+BITRIX_API_FORWARD_TOKEN
+OTEL_EXPORTER_OTLP_ENDPOINT
+APP_ENV
+LOG_LEVEL
+```
+
+Предлагаемые infra env, которые до реализации нужно добавить в arch-04:
+
+```text
+BITRIX_TOKEN_ENCRYPTION_KEY
+BITRIX_TOKEN_ENCRYPTION_KEY_VERSION
+BITRIX_HTTP_TIMEOUT_SEC=15
+BITRIX_HTTP_MAX_CONCURRENCY=2
+BITRIX_RETRY_MAX_ATTEMPTS=10
+BITRIX_RETRY_MAX_DELAY_SEC=300
+BITRIX_INBOX_RETENTION_DAYS
+BITRIX_DLQ_ALERT_AGE_SEC
+```
+
+Business settings здесь не хранятся. Legacy `BITRIX_SYNC_FORWARD_*` удаляются после migration window и не являются каноническими.
+
+## 19. Docker и deployment
+
+- service `bitrix-local-app`, `expose: 8080`, без `ports`;
+- networks `backend`,`observability`; root nginx отдельно;
+- managed PostgreSQL вне compose, TLS обязательно;
+- нет SQLite volume production;
+- healthcheck `/health/live`; readiness — orchestration/monitoring;
+- migration one-shot job до rollout;
+- graceful shutdown: stop claims, finish in-flight до grace, release leases, close pools;
+- stateless filesystem.
+
+Прототипные `deploy/nginx/*`, certbot/SSL scripts и отдельный compose-stack не переносятся: сертификат и routing принадлежат корневому nginx/compose.
+
+## 20. Что переиспользуется из прототипа
+
+Концептуально переиспользуются и покрываются новыми тестами:
+
+- tolerant parser JSON/form/multipart и `auth[...]`;
+- преобразование PHP-style `MESSAGES` list/dict;
+- разделение client/connector/handler/normalizer/session store;
+- setup `register → activate → bind`;
+- refresh до expiry и один replay `expired_token`;
+- extraction session `CHAT_ID`/`ID`;
+- `application_token` и Bearer constant-time compare;
+- deterministic idempotency event key как основа fingerprint;
+- `dialog_sessions` и enrichment;
+- отключение docs production;
+- различение Open Lines и CRM sync.
+
+Обязательно меняется:
+
+- `/internal/v1/*` → только `/internal/openlines/v1/*`;
+- forward envelope → канонический `POST /internal/openlines/v1/inbox`;
+- immediate delivery ack до API запрещён;
+- single-attempt forward → durable worker/backoff/DLQ;
+- plaintext tokens → AEAD encryption/key rotation;
+- sync psycopg2/thread lock → async pool/transactions/leases;
+- SQLite и DDL-on-start не используются production;
+- отдельный nginx/certbot/compose удаляются из production topology;
+- `/bitrix-internal/` edge alias не нужен: internal API не публикуется;
+- raw payload/error storage/logging минимизируется;
+- uninstall деактивирует installation;
+- Alembic и OpenAPI 3.1 обязательны.
+
+## 21. Тестовая матрица
+
+### Unit
+
+- parser variants/nesting/limits;
+- normalizer message/file/start/finish;
+- token encryption/decryption/AAD/rotation;
+- fingerprint/idempotency;
+- session extraction variants;
+- retry classification/backoff/jitter;
+- URL/portal validation and redaction.
+
+### Integration
+
+- Alembic empty/upgrade;
+- concurrent duplicate webhook;
+- outbound same/different fingerprint;
+- `SKIP LOCKED`, lease expiry, crash recovery;
+- refresh single-flight;
+- setup reconcile;
+- DB constraints/soft delete;
+- no DDL at startup.
+
+### Contract
+
+- all public/internal schemas in committed OpenAPI;
+- tokens and paired names with module-01;
+- `message.new`/`dialog.closed` inbox;
+- API 201/duplicate before delivery ack;
+- request-id/trace propagation;
+- Bitrix fixture payloads and response variants.
+
+### E2E/failure
+
+- install portal → connector visible on line 8;
+- text/file send and mapping;
+- operator text/file → API → ack;
+- duplicate/reordered callbacks;
+- API outage, Bitrix 429/5xx/timeout, OAuth expiry/invalid_grant;
+- crash at every checkpoint;
+- DLQ/replay;
+- circuit half-open;
+- logs contain no secrets/PII/URLs.
+
+## 22. Definition of Done
+
+- portal/connector/line fixed and validated;
+- public and internal paths exactly match arch-02;
+- internal API is unreachable from public edge;
+- install/OAuth encryption/refresh/setup reconciliation complete;
+- outbound idempotency survives crash/ambiguous response;
+- inbox retry/DLQ and ack-after-API invariant proven;
+- operator text/files and `dialog.closed` contract-tested;
+- `bitrix_local` schema, indexes and Alembic migrations tested;
+- rate-limit/circuit/timeout/graceful shutdown implemented;
+- health/metrics/traces/JSON logs secure;
+- OpenAPI 3.1 committed and parity checked;
+- root Compose starts non-root container without published port;
+- runbooks: reinstall, key rotation, OAuth failure, setup retry, backlog/DLQ, migration/rollback;
+- no SQLite, startup DDL or separate production nginx.
+
+## 23. Решения, допущения и TBD
+
+**Решения:**
+
+- B1: canonical internal prefix только `/internal/openlines/v1`.
+- B2: delivery ack только после API commit/duplicate ack.
+- B3: OAuth tokens шифруются application-level AEAD.
+- B4: durable PostgreSQL inbox/outbox/DLQ; Redis не требуется.
+- B5: `external_chat_id=dialog_id`; local app не хранит user profile.
+- B6: production только managed PostgreSQL + Alembic.
+
+**Допущения:**
+
+- A1: один active portal `han0107.bitrix24.ru` в MVP.
+- A2: Bitrix fixtures позволят стабильно извлечь event/message/session ids; иначе versioned fingerprint.
+- A3: API может повторно выдать актуальный signed file URL при delayed outbound recovery; exact handshake требуется в contract test.
+
+**TBD:**
+
+- B-TBD1: точные Bitrix REST quotas/headers и safe retry матрица по официальной документации/portal tests.
+- B-TBD2: окончательный outbound DTO user display name и file fields в OpenAPI.
+- B-TBD3: exact stable `event_id` для dialog events (согласовать с module-01 TBD-3).
+- B-TBD4: retention/RPO/RTO и DLQ replay authorization.
+- B-TBD5: encryption key source/rotation runbook до production.
+- B-TBD6: точный CSP `frame-ancestors` placement.
+- B-TBD7: antivirus policy operator files остаётся у `api-backend`.