mi
98 lines
6.2 KiB
Markdown
98 lines
6.2 KiB
Markdown
# 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.
|
||
|
||
## Наблюдаемость
|
||
|
||
JSON stdout включён всегда. Если задан стандартный
|
||
`OTEL_EXPORTER_OTLP_ENDPOINT`, traces, metrics и логи дополнительно отправляются
|
||
напрямую по OTLP/gRPC через bounded batch queues. Ошибка инициализации, экспорта
|
||
или остановки телеметрии не меняет readiness и не останавливает API, worker или
|
||
reconciliation. Процессы различаются как `bitrix-sync-api`,
|
||
`bitrix-sync-worker` и `bitrix-sync-reconciliation`; namespace остаётся
|
||
`han-chat`.
|
||
|
||
FastAPI (кроме `/health/live`), SQLAlchemy и HTTPX инструментированы. Перед
|
||
stdout и OTLP выполняется application redaction: query/token/credential URL,
|
||
headers, payload, PII, object keys и SQL не экспортируются. Бизнес-метрики
|
||
используют только закрытые множества labels; UUID и внешние идентификаторы в
|
||
labels/spans не записываются.
|
||
|
||
## Границы безопасности
|
||
|
||
- 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.
|
||
|
||
`value_json` настройки `business_alerts` использует ключи `entity_type_id`,
|
||
`category_id`, `stage_new`, опциональный `responsible_id` и объект `field_ids`.
|
||
В `field_ids` REST-имена пользовательских полей сопоставляются ключам
|
||
`alert_number`, `fingerprint`, `alert_type`, `severity`, `app_user_id`,
|
||
`selected_external_id`, `occurrence_count`,
|
||
`first_occurred_at`, `last_occurred_at`, `workflow_id`.
|
||
Конфликтующие Contact передаются в стандартное поле `contactIds`, а значение
|
||
`BITRIX_SYNC_CONTACT_SOURCE` — в стандартное поле `sourceId`.
|
||
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.
|