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

2026-08-14 15:42:45 +03:00
parent e06a77ee1d
commit bbef7a30c9
521 changed files with 2597 additions and 2302 deletions
@@ -0,0 +1,72 @@
+# bitrix-sync
+
+Изолированный Python 3.12 сервис durable-синхронизации Contact между `han_app` и
+Битрикс24. Сервис не участвует в Open Lines и не имеет HTTP-зависимости от
+`api-backend`.
+
+## Entrypoints
+
+- `han-bitrix-sync-api` — health, internal status и два bounded robot receiver;
+- `han-bitrix-sync-worker` — queue/webhook/rebind workflows с lease fencing;
+- `han-bitrix-sync-reconciliation` — один advisory-lock incremental run;
+- `alembic upgrade head` — отдельная контролируемая миграция, не startup DDL.
+
+Disabled mode требует только `BITRIX_SYNC_ENABLED=false` и
+`BITRIX_SYNC_MODE=disabled`, не читает БД и не принимает webhook. Full mode
+валидирует весь каталог secret files, portal identity, custom fields, HTTPS host
+lock и непустой CIDR allow-list до startup.
+
+## Границы безопасности
+
+- CRM credential URL используется как единый секрет; redirect выключен, TLS
+  проверяется, REST method выбирается только из закрытого allow-list.
+- Receiver принимает только `application/x-www-form-urlencoded` с bounded
+  content length, числом и длиной полей. Query token сравнивается constant-time.
+- nginx должен перезаписывать `X-Real-IP` из TCP peer, проверять CIDR до proxy и
+  не логировать `$request_uri`, args или body. Контейнер receiver недоступен
+  напрямую.
+- DB хранит только hash CRM-master значений в snapshot; safe command projection
+  не содержит PII. URL credential, form body и token не логируются.
+- Запись CRM-master полей выполняется в одной транзакции после
+  `SET LOCAL han.sync_suppress='true'`.
+
+## Локальные проверки
+
+Лёгкие проверки, не требующие Docker, сервиса или реального PostgreSQL:
+
+```text
+python -m pytest
+python -m ruff check app tests
+```
+
+PostgreSQL integration и Bitrix contract suites намеренно являются внешними
+gates: локальный managed PostgreSQL не поднимается Compose-файлом.
+
+## External gates до `BITRIX_SYNC_ENABLED=true`
+
+1. Применить migrations migration-role и проверить grants runtime-role.
+2. На disposable managed PostgreSQL проверить concurrent `SKIP LOCKED`,
+   lease expiry/fencing, active mapping uniqueness, rebind partial failure,
+   transaction-local GUC без утечки и crash после CRM success.
+3. Подтвердить на целевом портале wire-контракты `duplicate.findbycomm`,
+   Contact add/get/update, mixed `batch`, custom fields, enum dictionary и
+   `crm.item.list` с `opened=1`, registration REST field `=1`.
+4. Заполнить и активировать валидную `business_alerts` settings version:
+   entity/category/stage/field IDs и responsible party. Placeholder `null`
+   запрещает alert receiver.
+5. Проверить least-privilege credential negative tests; credential администратора
+   запрещён.
+6. Валидировать nginx exact routes, no-redirect HTTP policy, body/rate limits,
+   version-controlled CIDR и отсутствие query/body в access/error/traces.
+7. Запустить synthetic webhook с реальным robot form contract, затем убедиться,
+   что durable inbox commit предшествует `202`.
+8. Выполнить 10k incremental reconciliation/load gate, webhook-loss recovery,
+   429/5xx/TLS/DNS/timeout/uncertain-create и restart-at-each-step tests.
+9. Проверить container image digest, dependency/SBOM/vulnerability scan и
+   compose hardening; root Compose ВМ2 подключает этот fragment отдельно.
+10. Зафиксировать cutover watermark, отменить только pre-cutover active tasks,
+    выполнить disabled preflight и затем controlled enablement.
+
+`compose.fragment.yaml` — сервисный фрагмент, не root Compose и не команда
+развёртывания. Reconciliation entrypoint выполняет один run; расписание задаёт
+root-owned scheduler/deployment layer.