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

VM1_app/codebase/backend/api-backend/.dockerignore

@@ -0,0 +1,8 @@
+.env
+.git
+.mypy_cache
+.pytest_cache
+.ruff_cache
+__pycache__
+*.py[cod]
+tests

VM1_app/codebase/backend/api-backend/Dockerfile

@@ -0,0 +1,20 @@
+FROM python:3.12-slim AS builder
+WORKDIR /build
+RUN pip install --no-cache-dir --upgrade pip build
+COPY pyproject.toml ./
+COPY app ./app
+RUN python -m build --wheel
+
+FROM python:3.12-slim
+ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1
+RUN addgroup --system --gid 10001 han && adduser --system --uid 10001 --ingroup han han
+WORKDIR /app
+COPY --from=builder /build/dist/*.whl /tmp/
+RUN pip install --no-cache-dir /tmp/*.whl && rm -f /tmp/*.whl
+COPY alembic.ini ./
+COPY alembic ./alembic
+COPY --chmod=0555 container-entrypoint.sh /usr/local/bin/han-container-entrypoint
+USER 10001:10001
+EXPOSE 8000
+ENTRYPOINT ["/usr/local/bin/han-container-entrypoint"]
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--no-proxy-headers"]

VM1_app/codebase/backend/api-backend/README.md

@@ -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 недоступна.

VM1_app/codebase/backend/api-backend/alembic.ini

@@ -0,0 +1,37 @@
+[alembic]
+script_location = alembic
+prepend_sys_path = .
+path_separator = os
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

VM1_app/codebase/backend/api-backend/alembic/env.py

@@ -0,0 +1,49 @@
+import asyncio
+import os
+from logging.config import fileConfig
+
+from sqlalchemy import pool
+
+from alembic import context
+from app.db import Base
+from app.postgres import create_postgres_engine
+
+config = context.config
+if config.config_file_name:
+    fileConfig(config.config_file_name)
+database_url = os.environ["DATABASE_URL"]
+config.set_main_option("sqlalchemy.url", database_url.replace("%", "%%"))
+target_metadata = Base.metadata
+
+
+def do_run_migrations(connection) -> None:
+    context.configure(
+        connection=connection,
+        target_metadata=target_metadata,
+        include_schemas=True,
+        version_table_schema="han_app",
+        compare_type=True,
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def run_async_migrations() -> None:
+    connectable = create_postgres_engine(database_url, poolclass=pool.NullPool)
+    async with connectable.connect() as connection:
+        await connection.run_sync(do_run_migrations)
+    await connectable.dispose()
+
+
+if context.is_offline_mode():
+    context.configure(
+        url=config.get_main_option("sqlalchemy.url"),
+        target_metadata=target_metadata,
+        literal_binds=True,
+        include_schemas=True,
+        version_table_schema="han_app",
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+else:
+    asyncio.run(run_async_migrations())

VM1_app/codebase/backend/api-backend/alembic/versions/0001_initial_han_app.py

@@ -0,0 +1,182 @@
+"""Initial han_app schema, seed and CRM sync triggers.
+
+Revision ID: 0001_initial
+Revises:
+Create Date: 2026-07-10
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+from app.db import Base
+
+revision: str = "0001_initial"
+down_revision: str | None = None
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+SEED = {
+    "auth.phone.enabled": ("true", "boolean", True),
+    "auth.password.enabled": ("false", "boolean", True),
+    "otp.phone.max_send_attempts_per_24h": ("3", "integer", False),
+    "otp.phone.min_seconds_between_attempts": ("30", "integer", False),
+    "operator.call.phone": ("+74999591007", "string", True),
+    "consent.personal_data.required": ("true", "boolean", True),
+    "consent.personal_data.document_url": (
+        "https://www.han0107.ru/privacy/persdata-agree-mobile",
+        "string",
+        True,
+    ),
+    "consent.personal_data.version": ("2026-06-10", "string", True),
+    "consent.privacy_policy.document_url": (
+        "https://www.han0107.ru/privacy",
+        "string",
+        True,
+    ),
+    "consent.user_agreement.required": ("true", "boolean", True),
+    "consent.user_agreement.document_url": (
+        "https://www.han0107.ru/user-agreement",
+        "string",
+        True,
+    ),
+    "consent.user_agreement.version": ("2026-06-10", "string", True),
+    "consent.marketing.required": ("false", "boolean", True),
+    "consent.marketing.document_url": (
+        "https://www.han0107.ru/privacy/ads-agree",
+        "string",
+        True,
+    ),
+    "consent.marketing.version": ("2026-06-10", "string", True),
+    "chat.attachments.allowed_extensions": (
+        "jpg,jpeg,png,webp,heic,heif,pdf",
+        "string_list",
+        True,
+    ),
+    "chat.attachments.allowed_mime_types": (
+        "image/jpeg,image/png,image/webp,image/heic,image/heif,application/pdf",
+        "string_list",
+        True,
+    ),
+    "chat.attachments.disallowed_extensions": ("svg,doc,docx,xls,xlsx,csv", "string_list", False),
+    "chat.attachments.max_size_mb": ("5", "integer", True),
+    "chat.attachments.storage": ("selectel_s3", "string", False),
+    "chat.attachments.upload_mode": ("presigned_put", "string", False),
+    "chat.attachments.safety_scan_required": ("true", "boolean", False),
+    "chat.attachments.presigned_upload_ttl_seconds": ("600", "integer", False),
+    "rate_limit.message_send.per_user": ("30/minute", "string", False),
+    "rate_limit.message_send.per_dialog": ("20/minute", "string", False),
+    "rate_limit.download_url.per_user": ("60/hour", "string", False),
+    "rate_limit.public_endpoints.per_ip": ("60/minute", "string", False),
+    "rate_limit.login.per_ip": ("10/minute", "string", False),
+    "ux.session.idle_timeout_minutes": ("30", "integer", True),
+    "security.cors.allowed_origins": ("https://tohin.ru", "string_list", False),
+    "security.public_cache.max_age_seconds": ("3600", "integer", False),
+}
+
+
+def upgrade() -> None:
+    bind = op.get_bind()
+    op.execute("CREATE EXTENSION IF NOT EXISTS pgcrypto")
+    op.execute("CREATE SCHEMA IF NOT EXISTS han_app")
+    Base.metadata.create_all(bind=bind, checkfirst=True)
+    op.execute(
+        """
+        CREATE UNIQUE INDEX IF NOT EXISTS uq_dialog_one_active_per_user
+        ON han_app.dialogs(user_id)
+        WHERE record_status='A'
+          AND status IN ('open','waiting_for_company','waiting_for_client')
+        """
+    )
+    op.execute(
+        """
+        CREATE UNIQUE INDEX IF NOT EXISTS uq_profiles_active_bitrix_contact
+        ON han_app.client_profiles(bitrix_contact_id)
+        WHERE bitrix_contact_id IS NOT NULL AND record_status='A'
+        """
+    )
+    op.execute(
+        """
+        CREATE OR REPLACE FUNCTION han_app.enqueue_contact_sync()
+        RETURNS trigger
+        LANGUAGE plpgsql
+        SECURITY INVOKER
+        SET search_path = han_app, pg_temp
+        AS $$
+        DECLARE
+            v_entity_id uuid;
+            v_task_type text;
+            v_dedup text;
+        BEGIN
+            IF current_setting('han.sync_suppress', true) = 'true' THEN
+                RETURN NEW;
+            END IF;
+            IF TG_TABLE_NAME = 'user_identities' THEN
+                v_entity_id := NEW.id;
+                v_task_type := CASE WHEN TG_OP = 'INSERT'
+                    THEN 'contact.map_or_create' ELSE 'contact.update' END;
+            ELSE
+                v_entity_id := NEW.user_id;
+                v_task_type := CASE WHEN TG_OP = 'INSERT'
+                    THEN 'contact.map_or_create' ELSE 'contact.update' END;
+            END IF;
+            v_dedup := v_task_type || ':' || v_entity_id::text || ':' ||
+                encode(public.digest(row_to_json(NEW)::text, 'sha256'), 'hex');
+            INSERT INTO han_app.sync_queue
+                (id, task_type, entity_type, entity_id, dedup_key, payload_json,
+                 status, attempt_count, next_attempt_at, created_at, updated_at)
+            VALUES
+                (gen_random_uuid(), v_task_type, 'contact', v_entity_id, v_dedup,
+                 jsonb_build_object('entity_id', v_entity_id), 'pending', 0,
+                 now(), now(), now())
+            ON CONFLICT (dedup_key) DO NOTHING;
+            RETURN NEW;
+        END;
+        $$
+        """
+    )
+    op.execute(
+        "DROP TRIGGER IF EXISTS trg_identity_contact_sync ON han_app.user_identities"
+    )
+    op.execute(
+        """
+        CREATE TRIGGER trg_identity_contact_sync
+        AFTER INSERT OR UPDATE OF phone_number, record_status
+        ON han_app.user_identities
+        FOR EACH ROW EXECUTE FUNCTION han_app.enqueue_contact_sync()
+        """
+    )
+    op.execute(
+        "DROP TRIGGER IF EXISTS trg_profile_contact_sync ON han_app.client_profiles"
+    )
+    op.execute(
+        """
+        CREATE TRIGGER trg_profile_contact_sync
+        AFTER INSERT OR UPDATE OF full_name, citizenship, russian_phone,
+          foreign_phone, email, record_status
+        ON han_app.client_profiles
+        FOR EACH ROW EXECUTE FUNCTION han_app.enqueue_contact_sync()
+        """
+    )
+    for key, (value, value_type, public) in SEED.items():
+        bind.execute(
+            sa.text(
+                """
+            INSERT INTO han_app.app_settings
+                (setting_key, setting_value, value_type, is_public, record_status, updated_at)
+            VALUES (:key, :value, :value_type, :public, 'A', now())
+            ON CONFLICT (setting_key) DO UPDATE SET
+                setting_value = EXCLUDED.setting_value,
+                value_type = EXCLUDED.value_type,
+                is_public = EXCLUDED.is_public,
+                record_status = 'A',
+                updated_at = now()
+            """
+            ),
+            {"key": key, "value": value, "value_type": value_type, "public": public},
+        )
+
+
+def downgrade() -> None:
+    raise RuntimeError("Initial data migration is forward-only")

VM1_app/codebase/backend/api-backend/alembic/versions/0002_qualify_pgcrypto_digest.py

@@ -0,0 +1,62 @@
+"""Qualify pgcrypto digest in the contact sync trigger.
+
+Revision ID: 0002_pgcrypto_digest
+Revises: 0001_initial
+Create Date: 2026-07-16
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "0002_pgcrypto_digest"
+down_revision: str | None = "0001_initial"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.execute(
+        """
+        CREATE OR REPLACE FUNCTION han_app.enqueue_contact_sync()
+        RETURNS trigger
+        LANGUAGE plpgsql
+        SECURITY INVOKER
+        SET search_path = han_app, pg_temp
+        AS $$
+        DECLARE
+            v_entity_id uuid;
+            v_task_type text;
+            v_dedup text;
+        BEGIN
+            IF current_setting('han.sync_suppress', true) = 'true' THEN
+                RETURN NEW;
+            END IF;
+            IF TG_TABLE_NAME = 'user_identities' THEN
+                v_entity_id := NEW.id;
+                v_task_type := CASE WHEN TG_OP = 'INSERT'
+                    THEN 'contact.map_or_create' ELSE 'contact.update' END;
+            ELSE
+                v_entity_id := NEW.user_id;
+                v_task_type := CASE WHEN TG_OP = 'INSERT'
+                    THEN 'contact.map_or_create' ELSE 'contact.update' END;
+            END IF;
+            v_dedup := v_task_type || ':' || v_entity_id::text || ':' ||
+                encode(public.digest(row_to_json(NEW)::text, 'sha256'), 'hex');
+            INSERT INTO han_app.sync_queue
+                (id, task_type, entity_type, entity_id, dedup_key, payload_json,
+                 status, attempt_count, next_attempt_at, created_at, updated_at)
+            VALUES
+                (gen_random_uuid(), v_task_type, 'contact', v_entity_id, v_dedup,
+                 jsonb_build_object('entity_id', v_entity_id), 'pending', 0,
+                 now(), now(), now())
+            ON CONFLICT (dedup_key) DO NOTHING;
+            RETURN NEW;
+        END;
+        $$
+        """
+    )
+
+
+def downgrade() -> None:
+    raise RuntimeError("Contact sync trigger migration is forward-only")

VM1_app/codebase/backend/api-backend/alembic/versions/0003_consent_device_audit_context.py

@@ -0,0 +1,33 @@
+"""Store consent device snapshots and remove audit IP.
+
+Revision ID: 0003_consent_audit
+Revises: 0002_pgcrypto_digest
+Create Date: 2026-07-16
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+revision: str = "0003_consent_audit"
+down_revision: str | None = "0002_pgcrypto_digest"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.execute(
+        """
+        ALTER TABLE han_app.user_consents
+        ADD COLUMN IF NOT EXISTS device_json jsonb NOT NULL DEFAULT '{}'::jsonb
+        """
+    )
+    op.execute(
+        """
+        ALTER TABLE han_app.audit_events
+        DROP COLUMN IF EXISTS ip
+        """
+    )
+
+
+def downgrade() -> None:
+    raise RuntimeError("Consent and audit context migration is forward-only")

VM1_app/codebase/backend/api-backend/alembic/versions/0004_device_and_otp_limits.py

@@ -0,0 +1,40 @@
+"""Store raw device identifiers and add OTP verification limit.
+
+Revision ID: 0004_device_otp
+Revises: 0003_consent_audit
+Create Date: 2026-07-21
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "0004_device_otp"
+down_revision: str | None = "0003_consent_audit"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.execute(
+        """
+        ALTER TABLE han_app.ux_sessions
+        ADD COLUMN IF NOT EXISTS device_id varchar(255)
+        """
+    )
+    op.execute(
+        """
+        INSERT INTO han_app.app_settings
+            (setting_key, setting_value, value_type, is_public, description,
+             record_status, updated_at)
+        VALUES
+            ('otp.phone.max_verify_attempts', '5', 'integer', false,
+             'Maximum failed verification attempts for one OTP challenge',
+             'A', now())
+        ON CONFLICT (setting_key) DO NOTHING
+        """
+    )
+
+
+def downgrade() -> None:
+    raise RuntimeError("Device and OTP limits migration is forward-only")

VM1_app/codebase/backend/api-backend/alembic/versions/0005_otp_runtime_settings.py

@@ -0,0 +1,37 @@
+"""Seed runtime OTP settings.
+
+Revision ID: 0005_otp_settings
+Revises: 0004_device_otp
+Create Date: 2026-07-22
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "0005_otp_settings"
+down_revision: str | None = "0004_device_otp"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.execute(
+        """
+        INSERT INTO han_app.app_settings
+            (setting_key, setting_value, value_type, is_public, description,
+             record_status, updated_at)
+        VALUES
+            ('otp.phone.code_length', '6', 'integer', false,
+             'Length of the numeric phone OTP', 'A', now()),
+            ('otp.phone.ttl_seconds', '60', 'integer', false,
+             'Phone OTP lifetime from durable order time', 'A', now()),
+            ('otp.phone.sms_order_timeout_ms', '3000', 'integer', false,
+             'Keycloak timeout for durable SMS order creation', 'A', now())
+        ON CONFLICT (setting_key) DO NOTHING
+        """
+    )
+
+
+def downgrade() -> None:
+    raise RuntimeError("OTP runtime settings migration is forward-only")

VM1_app/codebase/backend/api-backend/alembic/versions/0006_consent_privacy_policy_url.py

@@ -0,0 +1,34 @@
+"""Seed consent.privacy_policy.document_url for personal_data consent UI.
+
+Revision ID: 0006_privacy_policy
+Revises: 0005_otp_settings
+Create Date: 2026-07-23
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "0006_privacy_policy"
+down_revision: str | None = "0005_otp_settings"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.execute(
+        """
+        INSERT INTO han_app.app_settings
+            (setting_key, setting_value, value_type, is_public, description,
+             record_status, updated_at)
+        VALUES
+            ('consent.privacy_policy.document_url',
+             'https://www.han0107.ru/privacy', 'string', true,
+             'Privacy policy URL shown next to personal_data consent', 'A', now())
+        ON CONFLICT (setting_key) DO NOTHING
+        """
+    )
+
+
+def downgrade() -> None:
+    raise RuntimeError("Privacy policy consent URL migration is forward-only")

VM1_app/codebase/backend/api-backend/alembic/versions/0007_consent_marketing_document_url.py

@@ -0,0 +1,34 @@
+"""Seed consent.marketing.document_url for marketing consent UI link.
+
+Revision ID: 0007_marketing_doc
+Revises: 0006_privacy_policy
+Create Date: 2026-07-23
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "0007_marketing_doc"
+down_revision: str | None = "0006_privacy_policy"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.execute(
+        """
+        INSERT INTO han_app.app_settings
+            (setting_key, setting_value, value_type, is_public, description,
+             record_status, updated_at)
+        VALUES
+            ('consent.marketing.document_url',
+             'https://www.han0107.ru/privacy/ads-agree', 'string', true,
+             'Marketing communications consent document URL', 'A', now())
+        ON CONFLICT (setting_key) DO NOTHING
+        """
+    )
+
+
+def downgrade() -> None:
+    raise RuntimeError("Marketing consent document URL migration is forward-only")

VM1_app/codebase/backend/api-backend/alembic/versions/0008_notification_center_v1.py

@@ -0,0 +1,651 @@
+"""Notification Center v1 schema, catalog and settings.
+
+Revision ID: 0008_notifications_v1
+Revises: 0007_marketing_doc
+Create Date: 2026-07-27
+"""
+
+import hashlib
+import os
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = "0008_notifications_v1"
+down_revision: str | None = "0007_marketing_doc"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+COMMON = """
+    record_status varchar(1) NOT NULL DEFAULT 'A',
+    status_changed_at timestamptz NULL,
+    status_change_reason varchar(255) NULL,
+    created_at timestamptz NOT NULL DEFAULT now(),
+    updated_at timestamptz NOT NULL DEFAULT now(),
+    updater_user_id uuid NULL
+"""
+
+
+def _execute_batch(sql: str) -> None:
+    """Execute one statement at a time for the asyncpg prepared-statement dialect."""
+    statement: list[str] = []
+    in_dollar_quote = False
+    index = 0
+    while index < len(sql):
+        if sql[index : index + 2] == "$$":
+            in_dollar_quote = not in_dollar_quote
+            statement.append("$$")
+            index += 2
+            continue
+        character = sql[index]
+        if character == ";" and not in_dollar_quote:
+            value = "".join(statement).strip()
+            if value:
+                op.execute(value)
+            statement.clear()
+        else:
+            statement.append(character)
+        index += 1
+    value = "".join(statement).strip()
+    if value:
+        op.execute(value)
+
+
+def upgrade() -> None:
+    bind = op.get_bind()
+    _execute_batch(
+        f"""
+        CREATE TABLE han_app.notification_cta_actions (
+            id uuid PRIMARY KEY, code varchar(32) NOT NULL UNIQUE,
+            description varchar(255) NOT NULL, requires_auth boolean NOT NULL,
+            required_instance_fields varchar(64)[] NOT NULL DEFAULT '{{}}', {COMMON}
+        );
+        CREATE TABLE han_app.notification_buttons (
+            id uuid PRIMARY KEY, code varchar(32) NOT NULL UNIQUE,
+            label varchar(64) NOT NULL, sets_hidden boolean NOT NULL DEFAULT false,
+            applies_hidden_ttl boolean NOT NULL DEFAULT false,
+            close_reason varchar(32), submits_documents boolean NOT NULL DEFAULT false,
+            {COMMON},
+            CHECK (NOT applies_hidden_ttl OR sets_hidden),
+            CHECK (NOT submits_documents OR close_reason IS NOT NULL)
+        );
+        CREATE TABLE han_app.notification_color_tokens (
+            id uuid PRIMARY KEY, code varchar(32) NOT NULL UNIQUE,
+            description varchar(255) NOT NULL, sort_order smallint NOT NULL, {COMMON}
+        );
+        CREATE TABLE han_app.notification_types (
+            id uuid PRIMARY KEY, code varchar(32) NOT NULL UNIQUE,
+            contour varchar(1) NOT NULL CHECK (contour IN ('G','P')),
+            priority smallint NOT NULL, countable boolean NOT NULL,
+            label varchar(64) NOT NULL,
+            color_token varchar(32) NOT NULL REFERENCES han_app.notification_color_tokens(code)
+                ON DELETE RESTRICT,
+            icon_code varchar(32), cta_text varchar(64) NOT NULL,
+            cta_action varchar(32) NOT NULL REFERENCES han_app.notification_cta_actions(code)
+                ON DELETE RESTRICT,
+            cta_sets_hidden boolean NOT NULL DEFAULT false,
+            cta_close_reason varchar(32),
+            button_primary_code varchar(32) REFERENCES han_app.notification_buttons(code)
+                ON DELETE RESTRICT,
+            button_secondary_code varchar(32) REFERENCES han_app.notification_buttons(code)
+                ON DELETE RESTRICT,
+            hidden_ttl_days smallint,
+            documents_allowed boolean NOT NULL DEFAULT false,
+            hide_on_document_download boolean NOT NULL DEFAULT false,
+            required_detail_blocks varchar(64)[] NOT NULL DEFAULT '{{}}',
+            {COMMON},
+            CHECK (contour <> 'G' OR countable = false),
+            CHECK (contour <> 'G' OR cta_action <> 'open_detail'),
+            CHECK (cta_action <> 'open_detail' OR
+                (cta_sets_hidden = false AND cta_close_reason IS NULL)),
+            CHECK (cta_action = 'open_detail' OR
+                (documents_allowed = false AND hide_on_document_download = false
+                 AND required_detail_blocks = '{{}}')),
+            CHECK (NOT hide_on_document_download OR documents_allowed),
+            CHECK (cta_action <> 'open_detail' OR button_primary_code IS NOT NULL),
+            CHECK (cta_action = 'open_detail' OR
+                (button_primary_code IS NULL AND button_secondary_code IS NULL)),
+            CHECK (button_secondary_code IS NULL OR button_primary_code IS NOT NULL),
+            CHECK (button_secondary_code IS NULL OR
+                button_secondary_code <> button_primary_code)
+        );
+        CREATE TABLE han_app.notification_sources (
+            id uuid PRIMARY KEY, code varchar(32) NOT NULL UNIQUE,
+            description text, token_hash varchar(128) NOT NULL UNIQUE,
+            token_rotated_at timestamptz, {COMMON}
+        );
+        CREATE TABLE han_app.notifications (
+            id uuid PRIMARY KEY,
+            user_id uuid NOT NULL REFERENCES han_app.user_identities(id) ON DELETE RESTRICT,
+            notification_type varchar(32) NOT NULL
+                REFERENCES han_app.notification_types(code) ON DELETE RESTRICT,
+            source varchar(32) NOT NULL
+                REFERENCES han_app.notification_sources(code) ON DELETE RESTRICT,
+            external_id varchar(128) NOT NULL,
+            request_fingerprint varchar(64) NOT NULL,
+            notification_datetime timestamptz NOT NULL,
+            header varchar(255) NOT NULL, text varchar(1024),
+            priority_override smallint, date_expired timestamptz,
+            price numeric(12,2), old_price numeric(12,2), payment_url text,
+            details jsonb, details_schema_version smallint NOT NULL DEFAULT 1,
+            chat_message_text varchar(1024),
+            lifecycle_status varchar(16) NOT NULL DEFAULT 'active'
+                CHECK (lifecycle_status IN ('active','closed')),
+            visibility varchar(16) NOT NULL DEFAULT 'visible'
+                CHECK (visibility IN ('visible','hidden')),
+            is_read boolean NOT NULL DEFAULT false,
+            close_reason varchar(32) CHECK (close_reason IS NULL OR close_reason IN
+                ('user_done','docs_submitted','offer_accepted','paid','expired','cancelled')),
+            closed_at timestamptz, {COMMON},
+            CONSTRAINT uq_notifications_source_key UNIQUE (source, external_id),
+            CHECK (old_price IS NULL OR price IS NOT NULL),
+            CHECK (lifecycle_status <> 'closed' OR
+                (close_reason IS NOT NULL AND closed_at IS NOT NULL))
+        );
+        CREATE INDEX ix_notifications_user_active
+            ON han_app.notifications
+            (user_id, lifecycle_status, visibility, notification_datetime DESC, id DESC)
+            WHERE record_status='A';
+        CREATE INDEX ix_notifications_expire ON han_app.notifications(date_expired)
+            WHERE record_status='A' AND lifecycle_status='active'
+              AND date_expired IS NOT NULL;
+        CREATE TABLE han_app.guest_notifications (
+            id uuid PRIMARY KEY,
+            notification_type varchar(32) NOT NULL
+                REFERENCES han_app.notification_types(code) ON DELETE RESTRICT,
+            notification_datetime timestamptz NOT NULL,
+            header varchar(255) NOT NULL, text varchar(1024),
+            priority_override smallint, date_expired timestamptz,
+            price numeric(12,2), old_price numeric(12,2),
+            instruction_url text, chat_message_text varchar(1024),
+            lifecycle_status varchar(16) NOT NULL DEFAULT 'active'
+                CHECK (lifecycle_status IN ('active','closed')),
+            closed_at timestamptz, {COMMON},
+            CHECK (old_price IS NULL OR price IS NOT NULL),
+            CHECK (instruction_url IS NULL OR instruction_url LIKE 'https://%')
+        );
+        CREATE INDEX ix_guest_notifications_active
+            ON han_app.guest_notifications(lifecycle_status, notification_datetime DESC, id DESC)
+            WHERE record_status='A';
+        CREATE INDEX ix_guest_notifications_expire
+            ON han_app.guest_notifications(date_expired)
+            WHERE record_status='A' AND lifecycle_status='active'
+              AND date_expired IS NOT NULL;
+        CREATE TABLE han_app.notification_documents (
+            id uuid PRIMARY KEY,
+            notification_id uuid NOT NULL
+                REFERENCES han_app.notifications(id) ON DELETE RESTRICT,
+            document_id uuid NOT NULL REFERENCES han_app.documents(id) ON DELETE RESTRICT,
+            sort_order smallint NOT NULL DEFAULT 0,
+            download_url_issued_at timestamptz, {COMMON},
+            UNIQUE (notification_id, document_id)
+        );
+        CREATE TABLE han_app.client_upload_drafts (
+            id uuid PRIMARY KEY,
+            user_id uuid NOT NULL REFERENCES han_app.user_identities(id) ON DELETE RESTRICT,
+            context_type varchar(32) NOT NULL CHECK (context_type IN ('notification')),
+            context_id uuid NOT NULL,
+            original_file_name varchar(255) NOT NULL,
+            safe_file_name varchar(255) NOT NULL,
+            mime_type varchar(128) NOT NULL,
+            size_bytes bigint NOT NULL CHECK (size_bytes > 0),
+            checksum_sha256 char(64),
+            scan_status varchar(16) NOT NULL DEFAULT 'pending'
+                CHECK (scan_status IN ('pending','clean','infected','failed')),
+            storage_bucket varchar(255) NOT NULL,
+            object_key varchar(1024) NOT NULL,
+            quarantine_object_key varchar(1024),
+            upload_expires_at timestamptz, completed_at timestamptz,
+            state varchar(16) NOT NULL DEFAULT 'draft'
+                CHECK (state IN ('draft','submitted','discarded')),
+            submission_id uuid,
+            created_at timestamptz NOT NULL DEFAULT now(),
+            updated_at timestamptz NOT NULL DEFAULT now()
+        );
+        CREATE INDEX ix_client_upload_drafts_context
+            ON han_app.client_upload_drafts(user_id, context_type, context_id)
+            WHERE state='draft';
+        CREATE INDEX ix_client_upload_drafts_scan
+            ON han_app.client_upload_drafts(scan_status, updated_at);
+        CREATE INDEX ix_client_upload_drafts_created
+            ON han_app.client_upload_drafts(created_at);
+        CREATE TABLE han_app.client_documents (
+            id uuid PRIMARY KEY,
+            user_id uuid NOT NULL REFERENCES han_app.user_identities(id) ON DELETE RESTRICT,
+            context_type varchar(32) NOT NULL, context_id uuid NOT NULL,
+            submission_id uuid NOT NULL, source_draft_id uuid NOT NULL UNIQUE,
+            original_file_name varchar(255) NOT NULL, safe_file_name varchar(255) NOT NULL,
+            mime_type varchar(128) NOT NULL, size_bytes bigint NOT NULL,
+            checksum_sha256 char(64) NOT NULL, storage_bucket varchar(255) NOT NULL,
+            object_key varchar(1024) NOT NULL, submitted_at timestamptz NOT NULL,
+            {COMMON}, UNIQUE (storage_bucket, object_key)
+        );
+        CREATE INDEX ix_client_documents_context
+            ON han_app.client_documents(context_type, context_id);
+        CREATE INDEX ix_client_documents_user_submitted
+            ON han_app.client_documents(user_id, submitted_at DESC);
+        """
+    )
+
+    _execute_batch(
+        """
+        CREATE OR REPLACE FUNCTION han_app.validate_guest_notification()
+        RETURNS trigger LANGUAGE plpgsql SECURITY INVOKER
+        SET search_path = han_app, pg_temp AS $$
+        DECLARE v_contour varchar(1); v_action varchar(32); v_required varchar(64)[];
+        BEGIN
+            SELECT nt.contour, nt.cta_action, ca.required_instance_fields
+              INTO v_contour, v_action, v_required
+              FROM han_app.notification_types nt
+              JOIN han_app.notification_cta_actions ca ON ca.code=nt.cta_action
+             WHERE nt.code=NEW.notification_type AND nt.record_status='A';
+            IF v_contour IS DISTINCT FROM 'G' THEN
+                RAISE EXCEPTION 'notification type must use guest contour';
+            END IF;
+            IF ('instruction_url'=ANY(v_required)) <> (NEW.instruction_url IS NOT NULL)
+               OR ('chat_message_text'=ANY(v_required)) <>
+                  (NEW.chat_message_text IS NOT NULL) THEN
+                RAISE EXCEPTION 'guest notification fields do not match CTA';
+            END IF;
+            RETURN NEW;
+        END $$;
+        CREATE TRIGGER trg_validate_guest_notification
+        BEFORE INSERT OR UPDATE ON han_app.guest_notifications
+        FOR EACH ROW EXECUTE FUNCTION han_app.validate_guest_notification();
+
+        CREATE OR REPLACE FUNCTION han_app.enqueue_client_document_sync()
+        RETURNS trigger LANGUAGE plpgsql SECURITY INVOKER
+        SET search_path = han_app, pg_temp AS $$
+        BEGIN
+            IF current_setting('han.sync_suppress', true) = 'true' THEN RETURN NEW; END IF;
+            INSERT INTO han_app.sync_queue
+                (id, task_type, entity_type, entity_id, dedup_key, payload_json,
+                 status, attempt_count, next_attempt_at, created_at, updated_at)
+            VALUES (
+                gen_random_uuid(), 'document.client_uploaded', 'client_document', NEW.id,
+                'document.client_uploaded:' || NEW.id::text,
+                jsonb_build_object(
+                    'client_document_id', NEW.id, 'user_id', NEW.user_id,
+                    'context_type', NEW.context_type, 'context_id', NEW.context_id,
+                    'submission_id', NEW.submission_id, 'storage_bucket', NEW.storage_bucket,
+                    'object_key', NEW.object_key, 'original_file_name', NEW.original_file_name,
+                    'mime_type', NEW.mime_type, 'size_bytes', NEW.size_bytes,
+                    'checksum_sha256', NEW.checksum_sha256),
+                'pending', 0, now(), now(), now())
+            ON CONFLICT (dedup_key) DO NOTHING;
+            RETURN NEW;
+        END $$;
+        CREATE TRIGGER trg_client_document_sync
+        AFTER INSERT ON han_app.client_documents
+        FOR EACH ROW WHEN (NEW.record_status='A')
+        EXECUTE FUNCTION han_app.enqueue_client_document_sync();
+        """
+    )
+
+    _seed_catalog(bind)
+    _seed_settings(bind)
+
+
+def _seed_catalog(bind: sa.Connection) -> None:
+    # asyncpg rejects multiple SQL commands in one prepared statement.
+    _execute_batch(
+        """
+        INSERT INTO han_app.notification_cta_actions
+          (id,code,description,requires_auth,required_instance_fields)
+        VALUES
+          (gen_random_uuid(),'open_detail','Open notification detail',true,ARRAY['details']),
+          (gen_random_uuid(),'open_payment_url','Open payment URL',true,ARRAY['payment_url']),
+          (gen_random_uuid(),'send_chat_message','Send prepared chat message',true,
+           ARRAY['chat_message_text']),
+          (gen_random_uuid(),'start_auth','Start authentication',false,ARRAY[]::varchar[]),
+          (gen_random_uuid(),'install_app_prompt','Install application or open instruction',
+           false,ARRAY['instruction_url']);
+        INSERT INTO han_app.notification_buttons
+          (id,code,label,sets_hidden,applies_hidden_ttl,close_reason,submits_documents)
+        VALUES
+          (gen_random_uuid(),'done','Готово',false,false,'user_done',false),
+          (gen_random_uuid(),'later','Сделаю позже',false,false,NULL,false),
+          (gen_random_uuid(),'gotit','Понятно',true,true,NULL,false),
+          (gen_random_uuid(),'send_docs','Отправить документы',false,false,
+           'docs_submitted',true);
+        INSERT INTO han_app.notification_color_tokens
+          (id,code,description,sort_order)
+        VALUES
+          (gen_random_uuid(),'critical','Requires immediate attention',1),
+          (gen_random_uuid(),'warning','Waiting for a client action',2),
+          (gen_random_uuid(),'success','Successful result',3),
+          (gen_random_uuid(),'info','Informational notification',4),
+          (gen_random_uuid(),'promo','Marketing offer',5),
+          (gen_random_uuid(),'neutral','Neutral interface hint',6);
+        """
+    )
+    types = [
+        (
+            "authorize",
+            "G",
+            1,
+            False,
+            "Гостевой режим",
+            "neutral",
+            "login",
+            "Войти →",
+            "start_auth",
+            False,
+            None,
+            None,
+            None,
+            False,
+            False,
+            [],
+        ),
+        (
+            "install_app",
+            "G",
+            2,
+            False,
+            "Приложение",
+            "neutral",
+            "install",
+            "Установить →",
+            "install_app_prompt",
+            False,
+            None,
+            None,
+            None,
+            False,
+            False,
+            [],
+        ),
+        (
+            "promo_global",
+            "G",
+            3,
+            False,
+            "Акция",
+            "promo",
+            "promo",
+            "Узнать подробнее →",
+            "send_chat_message",
+            False,
+            None,
+            None,
+            None,
+            False,
+            False,
+            [],
+        ),
+        (
+            "ads_global",
+            "G",
+            4,
+            False,
+            "Предложение",
+            "promo",
+            "offer",
+            "Узнать подробнее →",
+            "send_chat_message",
+            False,
+            None,
+            None,
+            None,
+            False,
+            False,
+            [],
+        ),
+        (
+            "urgent",
+            "P",
+            1,
+            True,
+            "Срочно",
+            "critical",
+            "urgent",
+            "Подробнее →",
+            "open_detail",
+            False,
+            None,
+            "done",
+            "later",
+            False,
+            False,
+            [],
+        ),
+        (
+            "payment_pending",
+            "P",
+            2,
+            True,
+            "Оплата",
+            "warning",
+            "payment",
+            "Оплатить →",
+            "open_payment_url",
+            False,
+            None,
+            None,
+            None,
+            False,
+            False,
+            [],
+        ),
+        (
+            "docs_required",
+            "P",
+            2,
+            True,
+            "Требуются документы",
+            "warning",
+            "upload",
+            "Загрузить документы →",
+            "open_detail",
+            False,
+            None,
+            "send_docs",
+            "later",
+            False,
+            False,
+            [],
+        ),
+        (
+            "docs_ready",
+            "P",
+            3,
+            True,
+            "Документы готовы",
+            "success",
+            "download",
+            "Скачать →",
+            "open_detail",
+            False,
+            None,
+            "gotit",
+            None,
+            True,
+            True,
+            ["documents"],
+        ),
+        (
+            "status_changed",
+            "P",
+            3,
+            True,
+            "Статус",
+            "info",
+            "status",
+            "Подробнее →",
+            "open_detail",
+            False,
+            None,
+            "gotit",
+            None,
+            False,
+            False,
+            [],
+        ),
+        (
+            "reminder",
+            "P",
+            3,
+            True,
+            "Напоминание",
+            "info",
+            "reminder",
+            "Подробнее →",
+            "open_detail",
+            False,
+            None,
+            "done",
+            "later",
+            False,
+            False,
+            [],
+        ),
+        (
+            "news",
+            "P",
+            4,
+            True,
+            "Новость",
+            "info",
+            "news",
+            "Подробнее →",
+            "open_detail",
+            False,
+            None,
+            "gotit",
+            None,
+            False,
+            False,
+            [],
+        ),
+        (
+            "promo_personal",
+            "P",
+            5,
+            True,
+            "Акция",
+            "promo",
+            "promo",
+            "Узнать подробнее →",
+            "send_chat_message",
+            True,
+            "offer_accepted",
+            None,
+            None,
+            False,
+            False,
+            [],
+        ),
+        (
+            "ads_personal",
+            "P",
+            5,
+            True,
+            "Предложение",
+            "promo",
+            "offer",
+            "Узнать подробнее →",
+            "send_chat_message",
+            True,
+            "offer_accepted",
+            None,
+            None,
+            False,
+            False,
+            [],
+        ),
+    ]
+    statement = sa.text(
+        """
+        INSERT INTO han_app.notification_types
+          (id,code,contour,priority,countable,label,color_token,icon_code,cta_text,cta_action,
+           cta_sets_hidden,cta_close_reason,button_primary_code,button_secondary_code,
+           documents_allowed,hide_on_document_download,required_detail_blocks)
+        VALUES
+          (gen_random_uuid(),:code,:contour,:priority,:countable,:label,:color,:icon,:cta_text,
+           :action,:sets_hidden,:close_reason,:primary,:secondary,:documents_allowed,
+           :hide_download,:required)
+        """
+    )
+    for row in types:
+        bind.execute(
+            statement,
+            dict(
+                zip(
+                    (
+                        "code",
+                        "contour",
+                        "priority",
+                        "countable",
+                        "label",
+                        "color",
+                        "icon",
+                        "cta_text",
+                        "action",
+                        "sets_hidden",
+                        "close_reason",
+                        "primary",
+                        "secondary",
+                        "documents_allowed",
+                        "hide_download",
+                        "required",
+                    ),
+                    row,
+                    strict=True,
+                )
+            ),
+        )
+    token = os.getenv("NOTIFICATIONS_TOKEN_PRODUCER_TEST", "")
+    token_hash = (
+        hashlib.sha256(token.encode()).hexdigest()
+        if token
+        else hashlib.sha256(b"disabled:producer_test").hexdigest()
+    )
+    bind.execute(
+        sa.text(
+            """
+            INSERT INTO han_app.notification_sources
+              (id,code,description,token_hash,token_rotated_at)
+            VALUES (gen_random_uuid(),'producer_test','Notification Center smoke producer',
+                    :token_hash,now())
+            """
+        ),
+        {"token_hash": token_hash},
+    )
+
+
+def _seed_settings(bind: sa.Connection) -> None:
+    settings = [
+        ("notification.home.max_items", "7", "integer", False),
+        ("notification.center.max_items", "15", "integer", False),
+        ("notification.carousel.autoplay_enabled", "false", "boolean", True),
+        ("notification.carousel.autoplay_interval_ms", "5000", "integer", True),
+        ("notification.hidden.default_ttl_days", "3", "integer", False),
+        ("notification.documents.max_files", "10", "integer", False),
+        ("notification.instruction.allowed_hosts", "chat.example.ru", "string_list", False),
+        ("notification.expire_job.run_at", "00:01", "string", False),
+        ("notification.upload_draft.ttl_days", "7", "integer", False),
+        ("rate_limit.notifications_read.per_user", "120/minute", "string", False),
+        ("rate_limit.notifications_action.per_user", "60/minute", "string", False),
+        ("rate_limit.notification_upload.per_user", "20/minute", "string", False),
+        ("rate_limit.notifications_public.per_ip", "60/minute", "string", False),
+    ]
+    statement = sa.text(
+        """
+        INSERT INTO han_app.app_settings
+          (setting_key,setting_value,value_type,is_public,record_status,updated_at)
+        VALUES (:key,:value,:kind,:public,'A',now())
+        ON CONFLICT (setting_key) DO UPDATE SET setting_value=EXCLUDED.setting_value,
+          value_type=EXCLUDED.value_type,is_public=EXCLUDED.is_public,
+          record_status='A',updated_at=now()
+        """
+    )
+    for key, value, kind, public in settings:
+        bind.execute(statement, {"key": key, "value": value, "kind": kind, "public": public})
+
+
+def downgrade() -> None:
+    raise RuntimeError("Notification Center migration is forward-only")

VM1_app/codebase/backend/api-backend/alembic/versions/0009_chat_message_max_length.py

@@ -0,0 +1,33 @@
+"""Seed configurable maximum chat message length.
+
+Revision ID: 0009_chat_message_max
+Revises: 0008_notifications_v1
+Create Date: 2026-07-29
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "0009_chat_message_max"
+down_revision: str | None = "0008_notifications_v1"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.execute(
+        """
+        INSERT INTO han_app.app_settings
+            (setting_key, setting_value, value_type, is_public, description,
+             record_status, updated_at)
+        VALUES
+            ('chat.message.max_length', '4000', 'integer', true,
+             'Maximum normalized client chat message length', 'A', now())
+        ON CONFLICT (setting_key) DO NOTHING
+        """
+    )
+
+
+def downgrade() -> None:
+    raise RuntimeError("Chat message maximum length migration is forward-only")

VM1_app/codebase/backend/api-backend/alembic/versions/0010_contact_map_dedup.py

@@ -0,0 +1,75 @@
+"""Deduplicate contact mapping and skip no-op identity updates.
+
+Revision ID: 0010_contact_map_dedup
+Revises: 0009_chat_message_max
+Create Date: 2026-08-05
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "0010_contact_map_dedup"
+down_revision: str | None = "0009_chat_message_max"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.execute(
+        """
+        CREATE OR REPLACE FUNCTION han_app.enqueue_contact_sync()
+        RETURNS trigger
+        LANGUAGE plpgsql
+        SECURITY INVOKER
+        SET search_path = han_app, pg_temp
+        AS $$
+        DECLARE
+            v_entity_id uuid;
+            v_task_type text;
+            v_dedup text;
+        BEGIN
+            IF current_setting('han.sync_suppress', true) = 'true' THEN
+                RETURN NEW;
+            END IF;
+            IF TG_TABLE_NAME = 'user_identities' THEN
+                IF TG_OP = 'UPDATE'
+                   AND NEW.phone_number IS NOT DISTINCT FROM OLD.phone_number
+                   AND NEW.record_status IS NOT DISTINCT FROM OLD.record_status THEN
+                    RETURN NEW;
+                END IF;
+                v_entity_id := NEW.id;
+                v_task_type := CASE WHEN TG_OP = 'INSERT'
+                    THEN 'contact.map_or_create' ELSE 'contact.update' END;
+            ELSE
+                v_entity_id := NEW.user_id;
+                v_task_type := CASE WHEN TG_OP = 'INSERT'
+                    THEN 'contact.map_or_create' ELSE 'contact.update' END;
+            END IF;
+
+            IF v_task_type = 'contact.map_or_create' THEN
+                -- Identity and profile are inserted during the same bootstrap.
+                -- A stable key collapses both triggers into one logical task.
+                v_dedup := v_task_type || ':' || v_entity_id::text;
+            ELSE
+                v_dedup := v_task_type || ':' || v_entity_id::text || ':' ||
+                    encode(public.digest(row_to_json(NEW)::text, 'sha256'), 'hex');
+            END IF;
+
+            INSERT INTO han_app.sync_queue
+                (id, task_type, entity_type, entity_id, dedup_key, payload_json,
+                 status, attempt_count, next_attempt_at, created_at, updated_at)
+            VALUES
+                (gen_random_uuid(), v_task_type, 'contact', v_entity_id, v_dedup,
+                 jsonb_build_object('entity_id', v_entity_id), 'pending', 0,
+                 now(), now(), now())
+            ON CONFLICT (dedup_key) DO NOTHING;
+            RETURN NEW;
+        END;
+        $$
+        """
+    )
+
+
+def downgrade() -> None:
+    raise RuntimeError("Contact map-or-create deduplication migration is forward-only")

VM1_app/codebase/backend/api-backend/alembic/versions/0011_module07_contract.py

@@ -0,0 +1,188 @@
+"""Expand module-07 queue and stage canonical Bitrix mapping.
+
+Revision ID: 0011_module07_contract
+Revises: 0010_contact_map_dedup
+Create Date: 2026-08-06
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "0011_module07_contract"
+down_revision: str | None = "0010_contact_map_dedup"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    # Expand first. Existing rows remain readable throughout the migration.
+    op.execute(
+        """
+        ALTER TABLE han_app.sync_queue
+          ADD COLUMN IF NOT EXISTS locked_by varchar(128),
+          ADD COLUMN IF NOT EXISTS locked_until timestamptz,
+          ADD COLUMN IF NOT EXISTS lease_token uuid,
+          ADD COLUMN IF NOT EXISTS last_error_code varchar(64),
+          ADD COLUMN IF NOT EXISTS last_error_at timestamptz,
+          ADD COLUMN IF NOT EXISTS completed_at timestamptz,
+          ADD COLUMN IF NOT EXISTS cancel_reason varchar(255);
+
+        UPDATE han_app.sync_queue
+        SET status = CASE status
+          WHEN 'processing' THEN 'pending'
+          WHEN 'failed' THEN 'retry_wait'
+          ELSE status
+        END
+        WHERE status IN ('processing', 'failed');
+
+        ALTER TABLE han_app.sync_queue
+          DROP CONSTRAINT IF EXISTS sync_queue_status_check;
+        ALTER TABLE han_app.sync_queue
+          ADD CONSTRAINT sync_queue_status_check CHECK (
+            status IN ('pending','leased','processed','retry_wait','dead_letter','cancelled')
+          ) NOT VALID;
+        ALTER TABLE han_app.sync_queue
+          VALIDATE CONSTRAINT sync_queue_status_check;
+
+        ALTER TABLE han_app.sync_queue
+          DROP CONSTRAINT IF EXISTS sync_queue_dedup_key_key;
+        DROP INDEX IF EXISTS han_app.ix_sync_queue_status_next;
+        CREATE INDEX IF NOT EXISTS ix_sync_queue_claim
+          ON han_app.sync_queue(status, next_attempt_at, created_at);
+        CREATE INDEX IF NOT EXISTS ix_sync_queue_expired_lease
+          ON han_app.sync_queue(locked_until) WHERE status = 'leased';
+        CREATE INDEX IF NOT EXISTS ix_sync_queue_entity_history
+          ON han_app.sync_queue(entity_type, entity_id, created_at DESC);
+        CREATE UNIQUE INDEX IF NOT EXISTS uq_sync_queue_active_dedup
+          ON han_app.sync_queue(dedup_key)
+          WHERE status IN ('pending','leased','retry_wait');
+        """
+    )
+
+    # The bitrix-sync migration owns the canonical schema. If that migration
+    # already ran, copy and verify legacy rows here; otherwise its follow-up
+    # migration performs the same copy. The legacy table remains until the
+    # readers have switched and the contract migration is explicitly approved.
+    op.execute(
+        """
+        DO $$
+        BEGIN
+          IF to_regclass('bitrix_sync.entity_external_mapping') IS NOT NULL THEN
+            INSERT INTO bitrix_sync.entity_external_mapping (
+              id, entity_type, entity_id, external_system, external_entity_type,
+              external_id, status, opened_at, created_at, updated_at
+            )
+            SELECT id, entity_type, entity_id, 'bitrix24', 'contact',
+                   external_id, 'active', created_at, created_at, created_at
+            FROM han_app.entity_external_mapping
+            ON CONFLICT DO NOTHING;
+
+            IF EXISTS (
+              SELECT 1
+              FROM han_app.entity_external_mapping legacy
+              LEFT JOIN bitrix_sync.entity_external_mapping canonical
+                ON canonical.id = legacy.id
+               AND canonical.entity_type = legacy.entity_type
+               AND canonical.entity_id = legacy.entity_id
+               AND canonical.external_id = legacy.external_id
+              WHERE canonical.id IS NULL
+            ) THEN
+              RAISE EXCEPTION 'canonical mapping verification failed';
+            END IF;
+          END IF;
+        END $$;
+        """
+    )
+
+    op.execute(
+        """
+        CREATE OR REPLACE FUNCTION han_app.enqueue_contact_sync()
+        RETURNS trigger
+        LANGUAGE plpgsql
+        SECURITY INVOKER
+        SET search_path = han_app, pg_temp
+        AS $$
+        DECLARE
+          v_user_id uuid;
+          v_task_type varchar(64);
+          v_reason varchar(64);
+          v_dedup varchar(255);
+          v_source_updated_at timestamptz;
+        BEGIN
+          IF current_setting('han.sync_suppress', true) = 'true' THEN
+            RETURN NEW;
+          END IF;
+
+          IF TG_TABLE_NAME = 'user_identities' THEN
+            v_user_id := NEW.id;
+            v_source_updated_at := NEW.updated_at;
+            IF TG_OP = 'INSERT' THEN
+              IF NEW.record_status <> 'A' THEN RETURN NEW; END IF;
+              v_task_type := 'contact.map_or_create';
+              v_reason := 'identity_created';
+            ELSIF OLD.record_status = 'A' AND NEW.record_status <> 'A' THEN
+              v_task_type := 'contact.deactivate';
+              v_reason := 'identity_deactivated';
+            ELSIF OLD.record_status <> 'A' AND NEW.record_status = 'A' THEN
+              v_task_type := 'contact.map_or_create';
+              v_reason := 'identity_reactivated';
+            ELSIF NEW.record_status = 'A'
+              AND NEW.phone_number IS DISTINCT FROM OLD.phone_number THEN
+              v_task_type := 'contact.update';
+              v_reason := 'identity_phone_changed';
+            ELSE
+              RETURN NEW;
+            END IF;
+          ELSE
+            v_user_id := NEW.user_id;
+            v_source_updated_at := NEW.updated_at;
+            IF TG_OP = 'INSERT' THEN
+              IF NEW.record_status <> 'A' THEN RETURN NEW; END IF;
+              v_task_type := 'contact.map_or_create';
+              v_reason := 'profile_created';
+            ELSIF OLD.record_status = 'A' AND NEW.record_status <> 'A' THEN
+              v_task_type := 'contact.deactivate';
+              v_reason := 'profile_deactivated';
+            ELSIF OLD.record_status <> 'A' AND NEW.record_status = 'A' THEN
+              v_task_type := 'contact.map_or_create';
+              v_reason := 'profile_reactivated';
+            ELSE
+              RETURN NEW;
+            END IF;
+          END IF;
+
+          v_dedup := v_task_type || ':' || v_user_id::text;
+          INSERT INTO han_app.sync_queue (
+            id, task_type, entity_type, entity_id, dedup_key, payload_json,
+            status, attempt_count, next_attempt_at, created_at, updated_at
+          ) VALUES (
+            gen_random_uuid(), v_task_type, 'contact', v_user_id, v_dedup,
+            jsonb_build_object(
+              'schema_version', 1,
+              'user_id', v_user_id,
+              'reason', v_reason,
+              'source_updated_at', v_source_updated_at
+            ),
+            'pending', 0, now(), now(), now()
+          )
+          ON CONFLICT (dedup_key)
+            WHERE status IN ('pending','leased','retry_wait')
+          DO UPDATE SET
+            payload_json = EXCLUDED.payload_json,
+            updated_at = now();
+          RETURN NEW;
+        END;
+        $$;
+
+        DROP TRIGGER IF EXISTS trg_profile_contact_sync ON han_app.client_profiles;
+        CREATE TRIGGER trg_profile_contact_sync
+          AFTER INSERT OR UPDATE OF record_status
+          ON han_app.client_profiles
+          FOR EACH ROW EXECUTE FUNCTION han_app.enqueue_contact_sync();
+        """
+    )
+
+
+def downgrade() -> None:
+    raise RuntimeError("Module-07 staged contract migration is forward-only")

VM1_app/codebase/backend/api-backend/alembic/versions/0012_safety_v2_checkpoint.py

@@ -0,0 +1,74 @@
+"""Persist Message Safety v2 evidence and recovery locations.
+
+Revision ID: 0012_safety_v2_checkpoint
+Revises: 0011_module07_contract
+Create Date: 2026-08-06
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "0012_safety_v2_checkpoint"
+down_revision: str | None = "0011_module07_contract"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.execute(
+        """
+        ALTER TABLE han_app.messages
+          ADD COLUMN IF NOT EXISTS safety_processing_mode varchar(16),
+          ADD COLUMN IF NOT EXISTS safety_config_version bigint,
+          ADD COLUMN IF NOT EXISTS safety_rules_version varchar(128);
+
+        ALTER TABLE han_app.message_attachments
+          ADD COLUMN IF NOT EXISTS quarantine_version_id varchar(1024),
+          ADD COLUMN IF NOT EXISTS quarantine_etag varchar(1024);
+        ALTER TABLE han_app.message_attachments
+          DROP CONSTRAINT IF EXISTS message_attachments_scan_status_check;
+        ALTER TABLE han_app.message_attachments
+          ADD CONSTRAINT message_attachments_scan_status_check
+          CHECK (scan_status IN ('pending','clean','bypassed','infected','failed')) NOT VALID;
+        ALTER TABLE han_app.message_attachments
+          VALIDATE CONSTRAINT message_attachments_scan_status_check;
+
+        ALTER TABLE han_app.safety_tasks
+          ADD COLUMN IF NOT EXISTS poll_location varchar(1024),
+          ADD COLUMN IF NOT EXISTS processing_mode varchar(16),
+          ADD COLUMN IF NOT EXISTS config_version bigint,
+          ADD COLUMN IF NOT EXISTS rules_version varchar(128),
+          ADD COLUMN IF NOT EXISTS expires_at timestamptz;
+        UPDATE han_app.safety_tasks
+          SET poll_location = '/internal/safety/v2/messages/tasks/' || task_id,
+              expires_at = deadline_at
+          WHERE poll_location IS NULL OR expires_at IS NULL;
+        ALTER TABLE han_app.safety_tasks
+          ALTER COLUMN poll_location SET NOT NULL,
+          ALTER COLUMN expires_at SET NOT NULL;
+        """
+    )
+
+    # Notification uploads use the same safety contract.
+    op.execute(
+        """
+        ALTER TABLE han_app.client_upload_drafts
+          ADD COLUMN IF NOT EXISTS quarantine_version_id varchar(1024),
+          ADD COLUMN IF NOT EXISTS quarantine_etag varchar(1024),
+          ADD COLUMN IF NOT EXISTS safety_processing_mode varchar(16),
+          ADD COLUMN IF NOT EXISTS safety_config_version bigint,
+          ADD COLUMN IF NOT EXISTS safety_rules_version varchar(128);
+        ALTER TABLE han_app.client_upload_drafts
+          DROP CONSTRAINT IF EXISTS client_upload_drafts_scan_status_check;
+        ALTER TABLE han_app.client_upload_drafts
+          ADD CONSTRAINT client_upload_drafts_scan_status_check
+          CHECK (scan_status IN ('pending','clean','bypassed','infected','failed')) NOT VALID;
+        ALTER TABLE han_app.client_upload_drafts
+          VALIDATE CONSTRAINT client_upload_drafts_scan_status_check;
+        """
+    )
+
+
+def downgrade() -> None:
+    raise RuntimeError("Safety v2 checkpoint migration is forward-only")

VM1_app/codebase/backend/api-backend/app/__init__.py

@@ -0,0 +1 @@
+"""HAN Chat API backend."""

VM1_app/codebase/backend/api-backend/app/auth.py

@@ -0,0 +1,110 @@
+import asyncio
+import time
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+import jwt
+import phonenumbers
+from jwt import ExpiredSignatureError, InvalidTokenError, PyJWK
+
+from app.settings import Settings
+
+
+class AuthError(Exception):
+    def __init__(self, code: str = "unauthorized") -> None:
+        self.code = code
+
+
+@dataclass(frozen=True, slots=True)
+class Principal:
+    subject: str
+    phone_number: str | None
+    claims: dict[str, Any]
+
+
+class JWKSValidator:
+    def __init__(self, settings: Settings, http: httpx.AsyncClient) -> None:
+        self.settings = settings
+        self.http = http
+        self._keys: dict[str, PyJWK] = {}
+        self._loaded_at = 0.0
+        self._lock = asyncio.Lock()
+
+    @property
+    def has_keys(self) -> bool:
+        return bool(self._keys)
+
+    async def refresh(self) -> None:
+        async with self._lock:
+            discovery_url = (
+                f"{str(self.settings.keycloak_internal_url).rstrip('/')}"
+                f"/realms/{self.settings.keycloak_realm}/.well-known/openid-configuration"
+            )
+            discovery = (await self.http.get(discovery_url, timeout=3)).raise_for_status().json()
+            jwks_uri = discovery["jwks_uri"]
+            public_prefix = str(self.settings.keycloak_public_url).rstrip("/")
+            internal_prefix = str(self.settings.keycloak_internal_url).rstrip("/")
+            if jwks_uri.startswith(public_prefix):
+                jwks_uri = internal_prefix + jwks_uri[len(public_prefix) :]
+            payload = (await self.http.get(jwks_uri, timeout=3)).raise_for_status().json()
+            self._keys = {
+                key["kid"]: PyJWK.from_dict(key)
+                for key in payload.get("keys", [])
+                if key.get("kid") and key.get("kty") == "RSA"
+            }
+            self._loaded_at = time.monotonic()
+
+    async def validate(self, token: str) -> Principal:
+        try:
+            header = jwt.get_unverified_header(token)
+        except InvalidTokenError as exc:
+            raise AuthError() from exc
+        if header.get("alg") != "RS256" or not header.get("kid"):
+            raise AuthError()
+        kid = str(header["kid"])
+        stale = time.monotonic() - self._loaded_at > self.settings.jwks_cache_ttl_seconds
+        if stale or kid not in self._keys:
+            try:
+                await self.refresh()
+            except (httpx.HTTPError, KeyError, ValueError):
+                if (
+                    kid not in self._keys
+                    or time.monotonic() - self._loaded_at > self.settings.jwks_stale_grace_seconds
+                ):
+                    raise AuthError() from None
+        key = self._keys.get(kid)
+        if key is None:
+            raise AuthError()
+        try:
+            claims = jwt.decode(
+                token,
+                key.key,
+                algorithms=["RS256"],
+                audience=self.settings.keycloak_audience,
+                issuer=self.settings.issuer,
+                options={"require": ["exp", "sub"]},
+                leeway=30,
+            )
+        except ExpiredSignatureError as exc:
+            raise AuthError("token_expired") from exc
+        except InvalidTokenError as exc:
+            raise AuthError() from exc
+        subject = claims.get("sub")
+        if not isinstance(subject, str) or not subject:
+            raise AuthError()
+        return Principal(subject, canonical_phone(claims), claims)
+
+
+def canonical_phone(claims: dict[str, Any]) -> str | None:
+    for name in ("phone_number", "preferred_username"):
+        value = claims.get(name)
+        if not isinstance(value, str):
+            continue
+        try:
+            number = phonenumbers.parse(value, None)
+        except phonenumbers.NumberParseException:
+            continue
+        if phonenumbers.is_valid_number(number) and value.startswith("+"):
+            return phonenumbers.format_number(number, phonenumbers.PhoneNumberFormat.E164)
+    return None

VM1_app/codebase/backend/api-backend/app/chat_settings.py

@@ -0,0 +1,21 @@
+from collections.abc import Mapping
+
+CHAT_MESSAGE_MAX_LENGTH_KEY = "chat.message.max_length"
+CHAT_MESSAGE_TRANSPORT_MAX_LENGTH = 10_000
+
+
+def validate_chat_settings(values: Mapping[str, str]) -> None:
+    raw = values.get(CHAT_MESSAGE_MAX_LENGTH_KEY)
+    if raw is None:
+        return
+    try:
+        value = int(raw)
+    except (TypeError, ValueError) as error:
+        raise ValueError(f"{CHAT_MESSAGE_MAX_LENGTH_KEY}: integer value expected") from error
+    if str(value) != raw:
+        raise ValueError(f"{CHAT_MESSAGE_MAX_LENGTH_KEY}: canonical integer value expected")
+    if not 1 <= value <= CHAT_MESSAGE_TRANSPORT_MAX_LENGTH:
+        raise ValueError(
+            f"{CHAT_MESSAGE_MAX_LENGTH_KEY}: value must be between 1 "
+            f"and {CHAT_MESSAGE_TRANSPORT_MAX_LENGTH}"
+        )

VM1_app/codebase/backend/api-backend/app/cli/__init__.py

@@ -0,0 +1 @@
+"""Operational command-line entry points."""

VM1_app/codebase/backend/api-backend/app/cli/seed_settings.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+from pathlib import Path
+from typing import Any
+
+import yaml
+from sqlalchemy import func, or_
+from sqlalchemy.dialects.postgresql import insert
+
+from app.chat_settings import CHAT_MESSAGE_MAX_LENGTH_KEY, validate_chat_settings
+from app.db import AppSetting, Database
+from app.otp_settings import OTP_SETTING_KEYS, validate_otp_settings
+from app.settings import get_settings
+
+VALUE_TYPES = {"boolean", "integer", "string", "string_list"}
+
+
+def load_seed(path: Path) -> list[dict[str, Any]]:
+    document = yaml.safe_load(path.read_text(encoding="utf-8"))
+    if not isinstance(document, dict) or document.get("schema_version") != 1:
+        raise ValueError("settings file must have schema_version: 1")
+    settings = document.get("settings")
+    if not isinstance(settings, dict) or not settings:
+        raise ValueError("settings file must contain a non-empty settings mapping")
+
+    rows: list[dict[str, Any]] = []
+    for key, raw in settings.items():
+        if not isinstance(key, str) or not key.strip():
+            raise ValueError("setting keys must be non-empty strings")
+        if not isinstance(raw, dict):
+            raise ValueError(f"{key}: setting must be a mapping")
+        value_type = raw.get("type")
+        if value_type not in VALUE_TYPES:
+            raise ValueError(f"{key}: unsupported type {value_type!r}")
+        if key in OTP_SETTING_KEYS and value_type != "integer":
+            raise ValueError(f"{key}: type must be integer")
+        if key == CHAT_MESSAGE_MAX_LENGTH_KEY and value_type != "integer":
+            raise ValueError(f"{key}: type must be integer")
+        if not isinstance(raw.get("public"), bool):
+            raise ValueError(f"{key}: public must be a boolean")
+        if key in OTP_SETTING_KEYS and raw["public"]:
+            raise ValueError(f"{key}: OTP setting must not be public")
+        if key == CHAT_MESSAGE_MAX_LENGTH_KEY and not raw["public"]:
+            raise ValueError(f"{key}: setting must be public")
+        description = raw.get("description")
+        if description is not None and not isinstance(description, str):
+            raise ValueError(f"{key}: description must be a string")
+        rows.append(
+            {
+                "setting_key": key,
+                "setting_value": serialize_value(key, value_type, raw.get("value")),
+                "value_type": value_type,
+                "is_public": raw["public"],
+                "description": description,
+                "record_status": "A",
+            }
+        )
+    validate_otp_settings({row["setting_key"]: row["setting_value"] for row in rows})
+    validate_chat_settings({row["setting_key"]: row["setting_value"] for row in rows})
+    return rows
+
+
+def serialize_value(key: str, value_type: str, value: Any) -> str:
+    if value_type == "boolean":
+        if not isinstance(value, bool):
+            raise ValueError(f"{key}: boolean value expected")
+        return str(value).lower()
+    if value_type == "integer":
+        if not isinstance(value, int) or isinstance(value, bool):
+            raise ValueError(f"{key}: integer value expected")
+        return str(value)
+    if value_type == "string_list":
+        if isinstance(value, list) and all(isinstance(item, str) for item in value):
+            return ",".join(value)
+        if isinstance(value, str):
+            return value
+        raise ValueError(f"{key}: string or list of strings expected")
+    if not isinstance(value, str):
+        raise ValueError(f"{key}: string value expected")
+    return value
+
+
+async def seed(path: Path) -> int:
+    rows = load_seed(path)
+    database = Database(get_settings().database_url)
+    try:
+        async with database.sessions() as session:
+            for row in rows:
+                statement = insert(AppSetting).values(**row)
+                excluded = statement.excluded
+                statement = statement.on_conflict_do_update(
+                    index_elements=[AppSetting.setting_key],
+                    set_={
+                        "setting_value": excluded.setting_value,
+                        "value_type": excluded.value_type,
+                        "is_public": excluded.is_public,
+                        "description": excluded.description,
+                        "record_status": "A",
+                        "updated_at": func.now(),
+                    },
+                    where=or_(
+                        AppSetting.setting_value.is_distinct_from(excluded.setting_value),
+                        AppSetting.value_type.is_distinct_from(excluded.value_type),
+                        AppSetting.is_public.is_distinct_from(excluded.is_public),
+                        AppSetting.description.is_distinct_from(excluded.description),
+                        AppSetting.record_status != "A",
+                    ),
+                )
+                await session.execute(statement)
+            await session.commit()
+    finally:
+        await database.close()
+    return len(rows)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Idempotently seed application settings")
+    parser.add_argument("--file", required=True, type=Path)
+    args = parser.parse_args()
+    count = asyncio.run(seed(args.file))
+    print(f"Application settings seeded: {count}")
+
+
+if __name__ == "__main__":
+    main()

VM1_app/codebase/backend/api-backend/app/cli/validate_settings.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import asyncio
+
+from sqlalchemy import select
+
+from app.db import AppSetting, Database
+from app.services import REQUIRED_SETTINGS
+from app.settings import get_settings
+
+
+async def validate() -> int:
+    database = Database(get_settings().database_url)
+    try:
+        async with database.sessions() as session:
+            active_keys = set(
+                (
+                    await session.execute(
+                        select(AppSetting.setting_key).where(AppSetting.record_status == "A")
+                    )
+                )
+                .scalars()
+                .all()
+            )
+    finally:
+        await database.close()
+
+    missing = sorted(REQUIRED_SETTINGS - active_keys)
+    if missing:
+        raise RuntimeError(f"Mandatory application settings are missing: {', '.join(missing)}")
+    return len(REQUIRED_SETTINGS)
+
+
+def main() -> None:
+    count = asyncio.run(validate())
+    print(f"Mandatory application settings validated: {count}")
+
+
+if __name__ == "__main__":
+    main()

VM1_app/codebase/backend/api-backend/app/db.py

@@ -0,0 +1,435 @@
+import uuid
+from collections.abc import AsyncIterator
+from datetime import datetime
+from typing import Any
+
+from sqlalchemy import (
+    JSON,
+    BigInteger,
+    Boolean,
+    CheckConstraint,
+    DateTime,
+    ForeignKey,
+    Index,
+    Integer,
+    String,
+    Text,
+    UniqueConstraint,
+    func,
+)
+from sqlalchemy.dialects.postgresql import INET, JSONB, UUID
+from sqlalchemy.ext.asyncio import (
+    AsyncEngine,
+    AsyncSession,
+    async_sessionmaker,
+)
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+from app.postgres import create_postgres_engine
+
+SCHEMA = "han_app"
+
+
+class Base(DeclarativeBase):
+    type_annotation_map = {dict[str, Any]: JSON}
+
+
+class BitrixBase(DeclarativeBase):
+    """Models owned by bitrix-sync, excluded from han_app create_all."""
+
+
+class Common:
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    record_status: Mapped[str] = mapped_column(String(1), default="A", server_default="A")
+    status_changed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    status_change_reason: Mapped[str | None] = mapped_column(String(255))
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), onupdate=func.now()
+    )
+    updater_user_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True))
+
+
+class UserIdentity(Common, Base):
+    __tablename__ = "user_identities"
+    __table_args__ = (Index("ix_user_identities_phone", "phone_number"), {"schema": SCHEMA})
+    keycloak_sub: Mapped[str] = mapped_column(String(255), unique=True)
+    phone_number: Mapped[str] = mapped_column(String(32))
+    last_login_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+
+
+class ClientProfile(Common, Base):
+    __tablename__ = "client_profiles"
+    __table_args__ = ({"schema": SCHEMA},)
+    user_id: Mapped[uuid.UUID] = mapped_column(
+        ForeignKey(f"{SCHEMA}.user_identities.id", ondelete="RESTRICT"), unique=True
+    )
+    bitrix_contact_id: Mapped[str | None] = mapped_column(String(64))
+    full_name: Mapped[str | None] = mapped_column(String(255))
+    citizenship: Mapped[str | None] = mapped_column(String(128))
+    russian_phone: Mapped[str | None] = mapped_column(String(32))
+    foreign_phone: Mapped[str | None] = mapped_column(String(32))
+    email: Mapped[str | None] = mapped_column(String(320))
+    source_updated_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+
+
+class UserConsent(Common, Base):
+    __tablename__ = "user_consents"
+    __table_args__ = (
+        UniqueConstraint("user_id", "consent_type", "document_version"),
+        CheckConstraint("consent_type IN ('personal_data','user_agreement','marketing')"),
+        {"schema": SCHEMA},
+    )
+    user_id: Mapped[uuid.UUID] = mapped_column(
+        ForeignKey(f"{SCHEMA}.user_identities.id", ondelete="RESTRICT")
+    )
+    ux_session_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True))
+    consent_type: Mapped[str] = mapped_column(String(32))
+    document_version: Mapped[str] = mapped_column(String(64))
+    accepted: Mapped[bool] = mapped_column(Boolean)
+    accepted_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+    client_ip: Mapped[str | None] = mapped_column(INET)
+    user_agent_hash: Mapped[str | None] = mapped_column(String(64))
+    device_json: Mapped[dict[str, Any]] = mapped_column(JSONB, default=dict)
+
+
+class UxSession(Common, Base):
+    __tablename__ = "ux_sessions"
+    __table_args__ = (
+        CheckConstraint("start_reason IN ('first_launch','cold_start','idle_timeout')"),
+        Index("ix_ux_sessions_user_started", "user_id", "started_at"),
+        {"schema": SCHEMA},
+    )
+    user_id: Mapped[uuid.UUID] = mapped_column(
+        ForeignKey(f"{SCHEMA}.user_identities.id", ondelete="RESTRICT")
+    )
+    start_reason: Mapped[str] = mapped_column(String(32))
+    platform: Mapped[str] = mapped_column(String(32))
+    app_version: Mapped[str] = mapped_column(String(64))
+    device_id_hash: Mapped[str | None] = mapped_column(String(64))
+    device_id: Mapped[str | None] = mapped_column(String(255))
+    started_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+
+
+class Dialog(Common, Base):
+    __tablename__ = "dialogs"
+    __table_args__ = (
+        CheckConstraint("status IN ('open','waiting_for_company','waiting_for_client','closed')"),
+        Index("ix_dialogs_user_updated", "user_id", "updated_at", "id"),
+        {"schema": SCHEMA},
+    )
+    user_id: Mapped[uuid.UUID] = mapped_column(
+        ForeignKey(f"{SCHEMA}.user_identities.id", ondelete="RESTRICT")
+    )
+    status: Mapped[str] = mapped_column(String(32), default="open")
+    last_message_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    closed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+
+
+class Message(Common, Base):
+    __tablename__ = "messages"
+    __table_args__ = (
+        CheckConstraint("sender_type IN ('client','company')"),
+        CheckConstraint("content_kind IN ('text','file')"),
+        CheckConstraint("safety_status IN ('pending','allowed','blocked','needs_review')"),
+        CheckConstraint(
+            "delivery_status IN ('accepted','processing','delivered','rejected','failed')"
+        ),
+        Index("ix_messages_dialog_created", "dialog_id", "created_at", "id"),
+        UniqueConstraint("dialog_id", "client_idempotency_key"),
+        {"schema": SCHEMA},
+    )
+    dialog_id: Mapped[uuid.UUID] = mapped_column(
+        ForeignKey(f"{SCHEMA}.dialogs.id", ondelete="RESTRICT")
+    )
+    sender_type: Mapped[str] = mapped_column(String(16))
+    content_kind: Mapped[str] = mapped_column(String(16))
+    text: Mapped[str] = mapped_column(Text, default="")
+    safety_status: Mapped[str] = mapped_column(String(16))
+    safety_processing_mode: Mapped[str | None] = mapped_column(String(16))
+    safety_config_version: Mapped[int | None] = mapped_column(BigInteger)
+    safety_rules_version: Mapped[str | None] = mapped_column(String(128))
+    delivery_status: Mapped[str] = mapped_column(String(16))
+    external_message_id: Mapped[str | None] = mapped_column(String(255))
+    client_idempotency_key: Mapped[str | None] = mapped_column(String(128))
+    occurred_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+
+
+class MessageAttachment(Common, Base):
+    __tablename__ = "message_attachments"
+    __table_args__ = (
+        CheckConstraint("direction IN ('client_upload','company_inbound')"),
+        CheckConstraint("scan_status IN ('pending','clean','bypassed','infected','failed')"),
+        CheckConstraint("size_bytes > 0"),
+        {"schema": SCHEMA},
+    )
+    dialog_id: Mapped[uuid.UUID] = mapped_column(ForeignKey(f"{SCHEMA}.dialogs.id"))
+    message_id: Mapped[uuid.UUID | None] = mapped_column(
+        ForeignKey(f"{SCHEMA}.messages.id"), unique=True
+    )
+    owner_user_id: Mapped[uuid.UUID] = mapped_column(ForeignKey(f"{SCHEMA}.user_identities.id"))
+    direction: Mapped[str] = mapped_column(String(32))
+    original_file_name: Mapped[str] = mapped_column(String(255))
+    safe_file_name: Mapped[str] = mapped_column(String(255))
+    mime_type: Mapped[str] = mapped_column(String(128))
+    size_bytes: Mapped[int] = mapped_column(BigInteger)
+    checksum_sha256: Mapped[str | None] = mapped_column(String(64))
+    scan_status: Mapped[str] = mapped_column(String(16), default="pending")
+    storage_bucket: Mapped[str] = mapped_column(String(255))
+    object_key: Mapped[str] = mapped_column(String(1024))
+    quarantine_object_key: Mapped[str | None] = mapped_column(String(1024))
+    quarantine_version_id: Mapped[str | None] = mapped_column(String(1024))
+    quarantine_etag: Mapped[str | None] = mapped_column(String(1024))
+    upload_expires_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    completed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+
+
+class Document(Common, Base):
+    __tablename__ = "documents"
+    __table_args__ = (UniqueConstraint("storage_bucket", "object_key"), {"schema": SCHEMA})
+    user_id: Mapped[uuid.UUID] = mapped_column(ForeignKey(f"{SCHEMA}.user_identities.id"))
+    name: Mapped[str] = mapped_column(String(255))
+    mime_type: Mapped[str] = mapped_column(String(128))
+    size_bytes: Mapped[int] = mapped_column(BigInteger)
+    checksum_sha256: Mapped[str] = mapped_column(String(64))
+    storage_bucket: Mapped[str] = mapped_column(String(255))
+    object_key: Mapped[str] = mapped_column(String(1024))
+    sent_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+
+
+class SafetyTask(Base):
+    __tablename__ = "safety_tasks"
+    __table_args__ = ({"schema": SCHEMA},)
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    task_id: Mapped[str] = mapped_column(String(255), unique=True)
+    poll_location: Mapped[str] = mapped_column(String(1024))
+    message_id: Mapped[uuid.UUID] = mapped_column(ForeignKey(f"{SCHEMA}.messages.id"), unique=True)
+    attachment_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True))
+    quarantine_object_key: Mapped[str | None] = mapped_column(String(1024))
+    status: Mapped[str] = mapped_column(String(16))
+    processing_mode: Mapped[str | None] = mapped_column(String(16))
+    config_version: Mapped[int | None] = mapped_column(BigInteger)
+    rules_version: Mapped[str | None] = mapped_column(String(128))
+    expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+    deadline_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+    next_poll_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+    attempt_count: Mapped[int] = mapped_column(Integer, default=0)
+    last_error_code: Mapped[str | None] = mapped_column(String(64))
+    locked_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    locked_by: Mapped[str | None] = mapped_column(String(128))
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+
+
+class DeliveryOutbox(Base):
+    __tablename__ = "delivery_outbox"
+    __table_args__ = ({"schema": SCHEMA},)
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    message_id: Mapped[uuid.UUID] = mapped_column(ForeignKey(f"{SCHEMA}.messages.id"), unique=True)
+    external_chat_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True))
+    payload_json: Mapped[dict[str, Any]] = mapped_column(JSON)
+    status: Mapped[str] = mapped_column(String(16), default="pending")
+    attempt_count: Mapped[int] = mapped_column(Integer, default=0)
+    next_attempt_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+    last_error_code: Mapped[str | None] = mapped_column(String(64))
+    locked_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    locked_by: Mapped[str | None] = mapped_column(String(128))
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+
+
+class IdempotencyRecord(Base):
+    __tablename__ = "idempotency_records"
+    __table_args__ = (
+        UniqueConstraint("scope", "user_id", "idempotency_key"),
+        {"schema": SCHEMA},
+    )
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    scope: Mapped[str] = mapped_column(String(128))
+    user_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True))
+    idempotency_key: Mapped[str] = mapped_column(String(128))
+    request_fingerprint: Mapped[str] = mapped_column(String(64))
+    status: Mapped[str] = mapped_column(String(16))
+    response_status: Mapped[int | None] = mapped_column(Integer)
+    response_body_json: Mapped[dict[str, Any] | None] = mapped_column(JSON)
+    resource_type: Mapped[str | None] = mapped_column(String(64))
+    resource_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True))
+    expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+
+
+class OpenLinesInboxReceipt(Base):
+    __tablename__ = "openlines_inbox_receipts"
+    __table_args__ = (
+        UniqueConstraint("event_id"),
+        UniqueConstraint("external_chat_id", "bitrix_message_id"),
+        {"schema": SCHEMA},
+    )
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    event_id: Mapped[str] = mapped_column(String(255))
+    external_chat_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True))
+    bitrix_message_id: Mapped[str | None] = mapped_column(String(255))
+    event_type: Mapped[str] = mapped_column(String(32))
+    payload_fingerprint: Mapped[str] = mapped_column(String(64))
+    status: Mapped[str] = mapped_column(String(16))
+    message_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True))
+    last_error_code: Mapped[str | None] = mapped_column(String(64))
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+
+
+class AuditEvent(Base):
+    __tablename__ = "audit_events"
+    __table_args__ = ({"schema": SCHEMA},)
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    event_type: Mapped[str] = mapped_column(String(128))
+    actor_type: Mapped[str] = mapped_column(String(32))
+    user_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True))
+    ux_session_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True))
+    request_id: Mapped[str] = mapped_column(String(64))
+    trace_id: Mapped[str | None] = mapped_column(String(64))
+    resource_type: Mapped[str | None] = mapped_column(String(64))
+    resource_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True))
+    user_agent_hash: Mapped[str | None] = mapped_column(String(64))
+    outcome: Mapped[str] = mapped_column(String(32))
+    metadata_json: Mapped[dict[str, Any]] = mapped_column(JSON, default=dict)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+
+
+class AppSetting(Base):
+    __tablename__ = "app_settings"
+    __table_args__ = ({"schema": SCHEMA},)
+    setting_key: Mapped[str] = mapped_column(String(255), primary_key=True)
+    setting_value: Mapped[str] = mapped_column(Text)
+    value_type: Mapped[str] = mapped_column(String(32))
+    is_public: Mapped[bool] = mapped_column(Boolean, default=False)
+    description: Mapped[str | None] = mapped_column(Text)
+    record_status: Mapped[str] = mapped_column(String(1), default="A")
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+
+
+class TextResource(Common, Base):
+    __tablename__ = "text_resources"
+    __table_args__ = (
+        UniqueConstraint("mnemonic", "locale"),
+        {"schema": SCHEMA},
+    )
+    mnemonic: Mapped[str] = mapped_column(String(255))
+    locale: Mapped[str] = mapped_column(String(16), default="ru")
+    text_value: Mapped[str] = mapped_column(Text)
+    sort_order: Mapped[int] = mapped_column(Integer, default=0)
+
+
+class PopularQuestion(Common, Base):
+    __tablename__ = "popular_questions"
+    __table_args__ = (
+        UniqueConstraint("mnemonic", "locale"),
+        {"schema": SCHEMA},
+    )
+    mnemonic: Mapped[str] = mapped_column(String(255))
+    locale: Mapped[str] = mapped_column(String(16), default="ru")
+    question_text: Mapped[str] = mapped_column(Text)
+    sort_order: Mapped[int] = mapped_column(Integer, default=0)
+
+
+class SyncQueue(Base):
+    __tablename__ = "sync_queue"
+    __table_args__ = (
+        CheckConstraint(
+            "status IN ('pending','leased','processed','retry_wait','dead_letter','cancelled')"
+        ),
+        Index("ix_sync_queue_claim", "status", "next_attempt_at", "created_at"),
+        Index("ix_sync_queue_entity_history", "entity_type", "entity_id", "created_at"),
+        {"schema": SCHEMA},
+    )
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    task_type: Mapped[str] = mapped_column(String(64))
+    entity_type: Mapped[str] = mapped_column(String(64))
+    entity_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True))
+    dedup_key: Mapped[str] = mapped_column(String(255))
+    payload_json: Mapped[dict[str, Any]] = mapped_column(JSON)
+    status: Mapped[str] = mapped_column(String(16), default="pending")
+    attempt_count: Mapped[int] = mapped_column(Integer, default=0)
+    next_attempt_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now()
+    )
+    locked_by: Mapped[str | None] = mapped_column(String(128))
+    locked_until: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    lease_token: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True))
+    last_error_code: Mapped[str | None] = mapped_column(String(64))
+    last_error_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    completed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    cancel_reason: Mapped[str | None] = mapped_column(String(255))
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+
+
+class EntityExternalMapping(Base):
+    __tablename__ = "entity_external_mapping"
+    __table_args__ = (UniqueConstraint("entity_type", "entity_id"), {"schema": SCHEMA})
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    entity_type: Mapped[str] = mapped_column(String(64))
+    entity_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True))
+    external_id: Mapped[str] = mapped_column(String(128))
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+
+
+class BitrixEntityExternalMapping(BitrixBase):
+    __tablename__ = "entity_external_mapping"
+    __table_args__ = ({"schema": "bitrix_sync"},)
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    entity_type: Mapped[str] = mapped_column(String(64))
+    entity_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True))
+    external_system: Mapped[str] = mapped_column(String(32), default="bitrix24")
+    external_entity_type: Mapped[str] = mapped_column(String(32), default="contact")
+    external_id: Mapped[str] = mapped_column(String(128))
+    status: Mapped[str] = mapped_column(String(16), default="active")
+    opened_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+    closed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    close_reason: Mapped[str | None] = mapped_column(String(64))
+    workflow_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True))
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+
+
+Index(
+    "uq_sync_queue_active_dedup",
+    SyncQueue.dedup_key,
+    unique=True,
+    postgresql_where=SyncQueue.status.in_(["pending", "leased", "retry_wait"]),
+)
+Index(
+    "ix_sync_queue_expired_lease",
+    SyncQueue.locked_until,
+    postgresql_where=SyncQueue.status == "leased",
+)
+Index(
+    "uq_external_mapping_active_entity",
+    BitrixEntityExternalMapping.external_system,
+    BitrixEntityExternalMapping.entity_type,
+    BitrixEntityExternalMapping.entity_id,
+    unique=True,
+    postgresql_where=BitrixEntityExternalMapping.status == "active",
+)
+Index(
+    "uq_external_mapping_active_external",
+    BitrixEntityExternalMapping.external_system,
+    BitrixEntityExternalMapping.external_entity_type,
+    BitrixEntityExternalMapping.external_id,
+    unique=True,
+    postgresql_where=BitrixEntityExternalMapping.status == "active",
+)
+
+
+class Database:
+    def __init__(self, url: str) -> None:
+        self.engine: AsyncEngine = create_postgres_engine(url, pool_pre_ping=True)
+        self.sessions = async_sessionmaker(self.engine, expire_on_commit=False)
+
+    async def session(self) -> AsyncIterator[AsyncSession]:
+        async with self.sessions() as session:
+            yield session
+
+    async def close(self) -> None:
+        await self.engine.dispose()

VM1_app/codebase/backend/api-backend/app/integrations.py

@@ -0,0 +1,460 @@
+import asyncio
+import hashlib
+import ipaddress
+import json
+import socket
+import time
+import uuid
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+from urllib.parse import urlparse
+
+import boto3
+import httpx
+from botocore.config import Config
+from redis.asyncio import Redis
+
+from app.settings import Settings
+
+RATE_LIMIT_LUA = """
+local current = redis.call('INCR', KEYS[1])
+if current == 1 then redis.call('EXPIRE', KEYS[1], ARGV[1]) end
+local ttl = redis.call('TTL', KEYS[1])
+return {current, ttl}
+"""
+
+
+class DependencyFailure(Exception):
+    def __init__(
+        self,
+        code: str = "dependency_unavailable",
+        timeout: bool = False,
+        *,
+        terminal: bool = False,
+        retryable: bool = True,
+    ) -> None:
+        super().__init__(code)
+        self.code = code
+        self.timeout = timeout
+        self.terminal = terminal
+        self.retryable = retryable
+
+
+@dataclass(slots=True)
+class CircuitBreaker:
+    threshold: int
+    open_seconds: float
+    failures: int = 0
+    opened_at: float | None = None
+
+    def allow(self) -> bool:
+        if self.opened_at is None:
+            return True
+        if time.monotonic() - self.opened_at >= self.open_seconds:
+            self.opened_at = None
+            self.failures = max(0, self.threshold - 1)
+            return True
+        return False
+
+    def success(self) -> None:
+        self.failures = 0
+        self.opened_at = None
+
+    def failure(self) -> None:
+        self.failures += 1
+        if self.failures >= self.threshold:
+            self.opened_at = time.monotonic()
+
+
+class RateLimiter:
+    def __init__(self, redis: Redis) -> None:
+        self.redis = redis
+
+    async def consume(self, key: str, limit: int, window: int) -> int:
+        try:
+            count, ttl = await self.redis.eval(RATE_LIMIT_LUA, 1, key, window)
+        except Exception as exc:
+            raise DependencyFailure() from exc
+        if int(count) > limit:
+            return max(1, int(ttl))
+        return 0
+
+    @staticmethod
+    def key(identity_type: str, identity: str, route: str, window: int) -> str:
+        safe_identity = hashlib.sha256(identity.encode()).hexdigest()[:32]
+        bucket = int(time.time()) // window
+        return f"han:api:rl:{identity_type}:{safe_identity}:{route}:{bucket}"
+
+
+class RedisIdempotency:
+    def __init__(self, redis: Redis) -> None:
+        self.redis = redis
+
+    async def get(self, scope: str, user_id: uuid.UUID, key: str) -> dict[str, Any] | None:
+        key_hash = hashlib.sha256(key.encode()).hexdigest()
+        raw = await self.redis.get(f"han:api:idem:{scope}:{user_id}:{key_hash}")
+        return json.loads(raw) if raw else None
+
+    async def put(self, scope: str, user_id: uuid.UUID, key: str, value: dict[str, Any]) -> None:
+        key_hash = hashlib.sha256(key.encode()).hexdigest()
+        await self.redis.set(
+            f"han:api:idem:{scope}:{user_id}:{key_hash}",
+            json.dumps(value, separators=(",", ":"), default=str),
+            ex=86400,
+        )
+
+
+class SafetyClient:
+    def __init__(self, settings: Settings, http: httpx.AsyncClient) -> None:
+        self.settings = settings
+        self.http = http
+        self.breaker = CircuitBreaker(
+            settings.message_safety_circuit_failure_threshold,
+            settings.message_safety_circuit_open_sec,
+        )
+
+    async def check(self, payload: dict[str, Any], request_id: str) -> dict[str, Any]:
+        return await self._call(
+            "POST",
+            f"{self.settings.message_safety_api_prefix}/messages/check",
+            request_id,
+            json=payload,
+            timeout=self.settings.message_safety_post_timeout_sec,
+        )
+
+    async def poll(self, location: str, request_id: str) -> dict[str, Any]:
+        path = self._poll_path(location)
+        return await self._call(
+            "GET",
+            path,
+            request_id,
+            timeout=2,
+        )
+
+    def _poll_path(self, location: str) -> str:
+        expected_prefix = f"{self.settings.message_safety_api_prefix}/messages/tasks/"
+        parsed = urlparse(location)
+        if parsed.scheme or parsed.netloc or parsed.query or parsed.fragment:
+            raise DependencyFailure("invalid_safety_location", terminal=True, retryable=False)
+        if not parsed.path.startswith(expected_prefix):
+            raise DependencyFailure("invalid_safety_location", terminal=True, retryable=False)
+        task_id = parsed.path.removeprefix(expected_prefix)
+        try:
+            uuid.UUID(task_id)
+        except ValueError as exc:
+            raise DependencyFailure(
+                "invalid_safety_location", terminal=True, retryable=False
+            ) from exc
+        return parsed.path
+
+    async def _call(self, method: str, path: str, request_id: str, **kwargs: Any) -> dict[str, Any]:
+        if not self.breaker.allow():
+            raise DependencyFailure()
+        headers = {
+            "X-Service-Token": self.settings.message_safety_service_token.get_secret_value(),
+            "X-Request-ID": request_id,
+        }
+        try:
+            response = await self.http.request(
+                method,
+                f"{str(self.settings.message_safety_url).rstrip('/')}{path}",
+                headers=headers,
+                **kwargs,
+            )
+        except httpx.TimeoutException as exc:
+            self.breaker.failure()
+            raise DependencyFailure(timeout=True) from exc
+        except httpx.HTTPError as exc:
+            self.breaker.failure()
+            raise DependencyFailure() from exc
+        if response.status_code >= 500:
+            self.breaker.failure()
+            code, terminal, retryable = "dependency_unavailable", False, True
+            try:
+                details = response.json().get("error", {}).get("details", {})
+                code = response.json().get("error", {}).get("code", code)
+                terminal = details.get("terminal") is True
+                retryable = details.get("retryable") is not False
+            except (AttributeError, ValueError):
+                pass
+            raise DependencyFailure(code, terminal=terminal, retryable=retryable)
+        if response.status_code not in (200, 202, 403):
+            if response.status_code == 401:
+                self.breaker.failure()
+            code = "safety_request_rejected"
+            try:
+                code = response.json().get("error", {}).get("code", code)
+            except (AttributeError, ValueError):
+                pass
+            retryable = response.status_code in (404, 429)
+            raise DependencyFailure(
+                code,
+                terminal=not retryable,
+                retryable=retryable,
+            )
+        try:
+            body = response.json()
+        except ValueError as exc:
+            self.breaker.failure()
+            raise DependencyFailure() from exc
+        if not isinstance(body, dict):
+            self.breaker.failure()
+            raise DependencyFailure()
+        status = response.status_code
+        expected_verdict = {200: "allow", 202: "pending", 403: "deny"}[status]
+        if (
+            body.get("verdict") != expected_verdict
+            or body.get("processing_mode") not in ("standard", "mock")
+            or type(body.get("config_version")) is not int
+            or not body.get("rules_version")
+        ):
+            self.breaker.failure()
+            raise DependencyFailure("invalid_safety_response")
+        if status == 202:
+            location = response.headers.get("Location")
+            retry_after = response.headers.get("Retry-After")
+            if (
+                body["processing_mode"] != "standard"
+                or not location
+                or not retry_after
+                or not body.get("task_id")
+                or not body.get("expires_at")
+                or type(body.get("poll_after_ms")) is not int
+            ):
+                self.breaker.failure()
+                raise DependencyFailure("invalid_safety_response")
+            try:
+                location_task_id = self._poll_path(location).rsplit("/", 1)[-1]
+            except DependencyFailure as exc:
+                self.breaker.failure()
+                raise DependencyFailure("invalid_safety_response") from exc
+            if body["task_id"] != location_task_id:
+                self.breaker.failure()
+                raise DependencyFailure("invalid_safety_response")
+            try:
+                if int(retry_after) <= 0 or body["poll_after_ms"] <= 0:
+                    raise ValueError
+                datetime_value = body["expires_at"].replace("Z", "+00:00")
+                datetime.fromisoformat(datetime_value)
+            except (AttributeError, TypeError, ValueError) as exc:
+                self.breaker.failure()
+                raise DependencyFailure("invalid_safety_response") from exc
+            body["_location"] = location
+            body["_retry_after"] = retry_after
+        elif not body.get("rule_id") or (
+            status == 403 and body.get("reason_code") != "message_blocked"
+        ):
+            self.breaker.failure()
+            raise DependencyFailure("invalid_safety_response")
+        self.breaker.success()
+        body["_status"] = response.status_code
+        return body
+
+    async def ready(self) -> bool:
+        try:
+            response = await self.http.get(
+                f"{str(self.settings.message_safety_url).rstrip('/')}/health/ready",
+                timeout=2,
+            )
+            return response.status_code == 200
+        except httpx.HTTPError:
+            return False
+
+
+class OpenLinesClient:
+    def __init__(self, settings: Settings, http: httpx.AsyncClient) -> None:
+        self.settings = settings
+        self.http = http
+        self.breaker = CircuitBreaker(
+            settings.bitrix_local_app_circuit_failure_threshold,
+            settings.bitrix_local_app_circuit_open_sec,
+        )
+
+    async def send(
+        self, message_id: uuid.UUID, payload: dict[str, Any], request_id: str
+    ) -> dict[str, Any]:
+        if not self.breaker.allow():
+            raise DependencyFailure()
+        try:
+            response = await self.http.post(
+                f"{str(self.settings.bitrix_local_app_base_url).rstrip('/')}"
+                "/internal/openlines/v1/messages",
+                json=payload,
+                headers={
+                    "Authorization": "Bearer "
+                    + self.settings.bitrix_local_app_internal_token.get_secret_value(),
+                    "Idempotency-Key": str(message_id),
+                    "X-Request-ID": request_id,
+                },
+                timeout=self.settings.bitrix_local_app_http_timeout_sec,
+            )
+            response.raise_for_status()
+        except httpx.TimeoutException as exc:
+            self.breaker.failure()
+            raise DependencyFailure(timeout=True) from exc
+        except httpx.HTTPError as exc:
+            self.breaker.failure()
+            raise DependencyFailure() from exc
+        self.breaker.success()
+        return response.json()
+
+    async def ready(self) -> bool:
+        try:
+            response = await self.http.get(
+                f"{str(self.settings.bitrix_local_app_base_url).rstrip('/')}"
+                "/internal/openlines/v1/status",
+                headers={
+                    "Authorization": "Bearer "
+                    + self.settings.bitrix_local_app_internal_token.get_secret_value()
+                },
+                timeout=2,
+            )
+            return response.is_success
+        except httpx.HTTPError:
+            return False
+
+
+async def fresh_openlines_payload(
+    payload: dict[str, Any], s3: "S3Client"
+) -> dict[str, Any]:
+    result = json.loads(json.dumps(payload, default=str))
+    for file in result.get("message", {}).get("files", []):
+        bucket = file.pop("_storage_bucket")
+        key = file.pop("_object_key")
+        file["download_url"] = await s3.presign_get(bucket, key)
+    return result
+
+
+class S3Client:
+    def __init__(self, settings: Settings) -> None:
+        self.settings = settings
+        self.client = boto3.client(
+            "s3",
+            endpoint_url=str(settings.selectel_s3_endpoint_url),
+            aws_access_key_id=settings.selectel_s3_access_key.get_secret_value(),
+            aws_secret_access_key=settings.selectel_s3_secret_key.get_secret_value(),
+            config=Config(
+                signature_version="s3v4",
+                connect_timeout=3,
+                read_timeout=10,
+                retries={"max_attempts": 2},
+                s3={"addressing_style": "virtual"},
+            ),
+        )
+
+    async def ready(self) -> bool:
+        try:
+            for bucket in (
+                self.settings.selectel_s3_bucket_quarantine,
+                self.settings.selectel_s3_bucket_attachments,
+                self.settings.selectel_s3_bucket_documents,
+            ):
+                await asyncio.to_thread(self.client.head_bucket, Bucket=bucket)
+            return True
+        except Exception:
+            return False
+
+    async def presign_put(self, key: str, mime: str, ttl: int) -> str:
+        return await asyncio.to_thread(
+            self.client.generate_presigned_url,
+            "put_object",
+            Params={
+                "Bucket": self.settings.selectel_s3_bucket_quarantine,
+                "Key": key,
+                "ContentType": mime,
+            },
+            ExpiresIn=ttl,
+        )
+
+    async def presign_get(self, bucket: str, key: str, ttl: int = 300) -> str:
+        return await asyncio.to_thread(
+            self.client.generate_presigned_url,
+            "get_object",
+            Params={"Bucket": bucket, "Key": key},
+            ExpiresIn=ttl,
+        )
+
+    async def head(self, bucket: str, key: str) -> dict[str, Any]:
+        return await asyncio.to_thread(self.client.head_object, Bucket=bucket, Key=key)
+
+    async def promote(
+        self,
+        source_key: str,
+        destination_key: str,
+        *,
+        version_id: str,
+        etag: str,
+    ) -> None:
+        await asyncio.to_thread(
+            self.client.copy_object,
+            Bucket=self.settings.selectel_s3_bucket_attachments,
+            Key=destination_key,
+            CopySource={
+                "Bucket": self.settings.selectel_s3_bucket_quarantine,
+                "Key": source_key,
+                "VersionId": version_id,
+            },
+            CopySourceIfMatch=etag,
+        )
+        # Keep the immutable source version until quarantine lifecycle expiry.
+        # A crash after copy but before the DB checkpoint can then safely retry
+        # the same conditional copy without losing its source.
+
+    async def delete_quarantine(self, key: str) -> None:
+        await asyncio.to_thread(
+            self.client.delete_object,
+            Bucket=self.settings.selectel_s3_bucket_quarantine,
+            Key=key,
+        )
+
+    async def delete(self, bucket: str, key: str) -> None:
+        await asyncio.to_thread(self.client.delete_object, Bucket=bucket, Key=key)
+
+    async def upload_inbound(
+        self,
+        http: httpx.AsyncClient,
+        download_url: str,
+        destination_key: str,
+        mime_type: str,
+        max_bytes: int,
+    ) -> tuple[int, str]:
+        parsed = urlparse(download_url)
+        if parsed.scheme != "https" or not parsed.hostname:
+            raise DependencyFailure("unsafe_inbound_url")
+        try:
+            addresses = await asyncio.to_thread(
+                socket.getaddrinfo, parsed.hostname, parsed.port or 443, type=socket.SOCK_STREAM
+            )
+        except OSError as exc:
+            raise DependencyFailure("unsafe_inbound_url") from exc
+        if any(
+            ipaddress.ip_address(address[4][0]).is_private
+            or ipaddress.ip_address(address[4][0]).is_loopback
+            or ipaddress.ip_address(address[4][0]).is_link_local
+            or ipaddress.ip_address(address[4][0]).is_reserved
+            for address in addresses
+        ):
+            raise DependencyFailure("unsafe_inbound_url")
+        data = bytearray()
+        try:
+            async with http.stream(
+                "GET", download_url, timeout=10, follow_redirects=False
+            ) as response:
+                response.raise_for_status()
+                if response.headers.get("content-type", "").split(";")[0] != mime_type:
+                    raise DependencyFailure("inbound_mime_mismatch")
+                async for chunk in response.aiter_bytes():
+                    data.extend(chunk)
+                    if len(data) > max_bytes:
+                        raise DependencyFailure("inbound_file_too_large")
+        except httpx.HTTPError as exc:
+            raise DependencyFailure() from exc
+        await asyncio.to_thread(
+            self.client.put_object,
+            Bucket=self.settings.selectel_s3_bucket_attachments,
+            Key=destination_key,
+            Body=bytes(data),
+            ContentType=mime_type,
+        )
+        return len(data), hashlib.sha256(data).hexdigest()

VM1_app/codebase/backend/api-backend/app/logging_security.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from typing import Any
+
+REDACTED = "[REDACTED]"
+_SENSITIVE_KEY = re.compile(
+    r"(authorization|cookie|password|passwd|secret|token|api[_-]?key|"
+    r"database[_-]?url|redis[_-]?url|dsn|callback[_-]?url)",
+    re.IGNORECASE,
+)
+_URI_USERINFO = re.compile(r"(?P<scheme>[a-z][a-z0-9+.-]*://)[^/@\s]+@", re.IGNORECASE)
+_QUERY_SECRET = re.compile(
+    r"(?P<prefix>[?&](?:token|access_token|api_key|key|secret|password)=)[^&#\s]+",
+    re.IGNORECASE,
+)
+_AUTH_VALUE = re.compile(r"\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+", re.IGNORECASE)
+
+
+def sanitize_text(value: str) -> str:
+    value = _URI_USERINFO.sub(r"\g<scheme>[REDACTED]@", value)
+    value = _QUERY_SECRET.sub(r"\g<prefix>[REDACTED]", value)
+    return _AUTH_VALUE.sub(r"\1 [REDACTED]", value)
+
+
+def sanitize_value(value: Any) -> Any:
+    if isinstance(value, str):
+        return sanitize_text(value)
+    if isinstance(value, Mapping):
+        return {
+            str(key): REDACTED if _SENSITIVE_KEY.search(str(key)) else sanitize_value(item)
+            for key, item in value.items()
+        }
+    if isinstance(value, list):
+        return [sanitize_value(item) for item in value]
+    if isinstance(value, tuple):
+        return tuple(sanitize_value(item) for item in value)
+    return value
+
+
+def redact_event(
+    _logger: Any,
+    _method_name: str,
+    event_dict: dict[str, Any],
+) -> dict[str, Any]:
+    return sanitize_value(event_dict)

VM1_app/codebase/backend/api-backend/app/metrics.py

@@ -0,0 +1,21 @@
+from opentelemetry import metrics
+
+meter = metrics.get_meter("han.api")
+
+HTTP_REQUESTS = meter.create_counter(
+    "han_http_requests_total",
+    description="Completed HTTP requests",
+)
+HTTP_DURATION = meter.create_histogram(
+    "han_http_request_duration_seconds",
+    unit="s",
+    description="HTTP request duration",
+)
+AUTH_BOOTSTRAP = meter.create_counter(
+    "han_auth_bootstrap_total",
+    description="Authentication bootstrap outcomes",
+)
+RATE_LIMIT_DECISIONS = meter.create_counter(
+    "han_rate_limit_decisions_total",
+    description="Rate-limit decisions",
+)

VM1_app/codebase/backend/api-backend/app/notification_models.py

@@ -0,0 +1,303 @@
+import secrets
+import time
+import uuid
+from datetime import datetime
+from decimal import Decimal
+from typing import Any
+
+from sqlalchemy import (
+    ARRAY,
+    BigInteger,
+    Boolean,
+    CheckConstraint,
+    DateTime,
+    ForeignKey,
+    Index,
+    Numeric,
+    SmallInteger,
+    String,
+    Text,
+    UniqueConstraint,
+    func,
+)
+from sqlalchemy.dialects.postgresql import JSONB, UUID
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db import SCHEMA, Base, Common
+
+
+def uuid7() -> uuid.UUID:
+    """Generate an RFC 9562 UUIDv7 without relying on Python 3.14."""
+    timestamp_ms = int(time.time_ns() // 1_000_000) & ((1 << 48) - 1)
+    value = timestamp_ms << 80
+    value |= 0x7 << 76
+    value |= secrets.randbits(12) << 64
+    value |= 0b10 << 62
+    value |= secrets.randbits(62)
+    return uuid.UUID(int=value)
+
+
+class NotificationCtaAction(Common, Base):
+    __tablename__ = "notification_cta_actions"
+    __table_args__ = (UniqueConstraint("code"), {"schema": SCHEMA})
+    code: Mapped[str] = mapped_column(String(32))
+    description: Mapped[str] = mapped_column(String(255))
+    requires_auth: Mapped[bool] = mapped_column(Boolean, default=False)
+    required_instance_fields: Mapped[list[str]] = mapped_column(
+        ARRAY(String(64)), default=list, server_default="{}"
+    )
+
+
+class NotificationButton(Common, Base):
+    __tablename__ = "notification_buttons"
+    __table_args__ = (
+        UniqueConstraint("code"),
+        CheckConstraint("NOT applies_hidden_ttl OR sets_hidden"),
+        CheckConstraint("NOT submits_documents OR close_reason IS NOT NULL"),
+        {"schema": SCHEMA},
+    )
+    code: Mapped[str] = mapped_column(String(32))
+    label: Mapped[str] = mapped_column(String(64))
+    sets_hidden: Mapped[bool] = mapped_column(Boolean, default=False)
+    applies_hidden_ttl: Mapped[bool] = mapped_column(Boolean, default=False)
+    close_reason: Mapped[str | None] = mapped_column(String(32))
+    submits_documents: Mapped[bool] = mapped_column(Boolean, default=False)
+
+
+class NotificationColorToken(Common, Base):
+    __tablename__ = "notification_color_tokens"
+    __table_args__ = (UniqueConstraint("code"), {"schema": SCHEMA})
+    code: Mapped[str] = mapped_column(String(32))
+    description: Mapped[str] = mapped_column(String(255))
+    sort_order: Mapped[int] = mapped_column(SmallInteger)
+
+
+class NotificationType(Common, Base):
+    __tablename__ = "notification_types"
+    __table_args__ = (
+        UniqueConstraint("code"),
+        CheckConstraint("contour IN ('G','P')"),
+        CheckConstraint("contour <> 'G' OR countable = false"),
+        CheckConstraint("contour <> 'G' OR cta_action <> 'open_detail'"),
+        CheckConstraint(
+            "cta_action <> 'open_detail' OR (cta_sets_hidden = false AND cta_close_reason IS NULL)"
+        ),
+        CheckConstraint(
+            "cta_action = 'open_detail' OR "
+            "(documents_allowed = false AND hide_on_document_download = false "
+            "AND required_detail_blocks = '{}')"
+        ),
+        CheckConstraint("NOT hide_on_document_download OR documents_allowed"),
+        CheckConstraint("cta_action <> 'open_detail' OR button_primary_code IS NOT NULL"),
+        CheckConstraint(
+            "cta_action = 'open_detail' OR "
+            "(button_primary_code IS NULL AND button_secondary_code IS NULL)"
+        ),
+        CheckConstraint("button_secondary_code IS NULL OR button_primary_code IS NOT NULL"),
+        CheckConstraint(
+            "button_secondary_code IS NULL OR button_secondary_code <> button_primary_code"
+        ),
+        {"schema": SCHEMA},
+    )
+    code: Mapped[str] = mapped_column(String(32))
+    contour: Mapped[str] = mapped_column(String(1))
+    priority: Mapped[int] = mapped_column(SmallInteger)
+    countable: Mapped[bool] = mapped_column(Boolean)
+    label: Mapped[str] = mapped_column(String(64))
+    color_token: Mapped[str] = mapped_column(
+        ForeignKey(f"{SCHEMA}.notification_color_tokens.code", ondelete="RESTRICT")
+    )
+    icon_code: Mapped[str | None] = mapped_column(String(32))
+    cta_text: Mapped[str] = mapped_column(String(64))
+    cta_action: Mapped[str] = mapped_column(
+        ForeignKey(f"{SCHEMA}.notification_cta_actions.code", ondelete="RESTRICT")
+    )
+    cta_sets_hidden: Mapped[bool] = mapped_column(Boolean, default=False)
+    cta_close_reason: Mapped[str | None] = mapped_column(String(32))
+    button_primary_code: Mapped[str | None] = mapped_column(
+        ForeignKey(f"{SCHEMA}.notification_buttons.code", ondelete="RESTRICT")
+    )
+    button_secondary_code: Mapped[str | None] = mapped_column(
+        ForeignKey(f"{SCHEMA}.notification_buttons.code", ondelete="RESTRICT")
+    )
+    hidden_ttl_days: Mapped[int | None] = mapped_column(SmallInteger)
+    documents_allowed: Mapped[bool] = mapped_column(Boolean, default=False)
+    hide_on_document_download: Mapped[bool] = mapped_column(Boolean, default=False)
+    required_detail_blocks: Mapped[list[str]] = mapped_column(
+        ARRAY(String(64)), default=list, server_default="{}"
+    )
+
+
+class NotificationSource(Common, Base):
+    __tablename__ = "notification_sources"
+    __table_args__ = (UniqueConstraint("code"), UniqueConstraint("token_hash"), {"schema": SCHEMA})
+    code: Mapped[str] = mapped_column(String(32))
+    description: Mapped[str | None] = mapped_column(Text)
+    token_hash: Mapped[str] = mapped_column(String(128))
+    token_rotated_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+
+
+class Notification(Common, Base):
+    __tablename__ = "notifications"
+    __table_args__ = (
+        UniqueConstraint("source", "external_id", name="uq_notifications_source_key"),
+        CheckConstraint("lifecycle_status IN ('active','closed')"),
+        CheckConstraint("visibility IN ('visible','hidden')"),
+        CheckConstraint(
+            "close_reason IS NULL OR close_reason IN "
+            "('user_done','docs_submitted','offer_accepted','paid','expired','cancelled')"
+        ),
+        CheckConstraint(
+            "lifecycle_status <> 'closed' OR (close_reason IS NOT NULL AND closed_at IS NOT NULL)"
+        ),
+        CheckConstraint("old_price IS NULL OR price IS NOT NULL"),
+        Index(
+            "ix_notifications_user_active",
+            "user_id",
+            "lifecycle_status",
+            "visibility",
+            "notification_datetime",
+            "id",
+        ),
+        Index("ix_notifications_expire", "date_expired"),
+        {"schema": SCHEMA},
+    )
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid7)
+    user_id: Mapped[uuid.UUID] = mapped_column(
+        ForeignKey(f"{SCHEMA}.user_identities.id", ondelete="RESTRICT")
+    )
+    notification_type: Mapped[str] = mapped_column(
+        ForeignKey(f"{SCHEMA}.notification_types.code", ondelete="RESTRICT")
+    )
+    source: Mapped[str] = mapped_column(
+        ForeignKey(f"{SCHEMA}.notification_sources.code", ondelete="RESTRICT")
+    )
+    external_id: Mapped[str] = mapped_column(String(128))
+    request_fingerprint: Mapped[str] = mapped_column(String(64))
+    notification_datetime: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+    header: Mapped[str] = mapped_column(String(255))
+    text: Mapped[str | None] = mapped_column(String(1024))
+    priority_override: Mapped[int | None] = mapped_column(SmallInteger)
+    date_expired: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    price: Mapped[Decimal | None] = mapped_column(Numeric(12, 2))
+    old_price: Mapped[Decimal | None] = mapped_column(Numeric(12, 2))
+    payment_url: Mapped[str | None] = mapped_column(Text)
+    details: Mapped[dict[str, Any] | None] = mapped_column(JSONB)
+    details_schema_version: Mapped[int] = mapped_column(SmallInteger, default=1)
+    chat_message_text: Mapped[str | None] = mapped_column(String(1024))
+    lifecycle_status: Mapped[str] = mapped_column(String(16), default="active")
+    visibility: Mapped[str] = mapped_column(String(16), default="visible")
+    is_read: Mapped[bool] = mapped_column(Boolean, default=False)
+    close_reason: Mapped[str | None] = mapped_column(String(32))
+    closed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+
+
+class GuestNotification(Common, Base):
+    __tablename__ = "guest_notifications"
+    __table_args__ = (
+        CheckConstraint("lifecycle_status IN ('active','closed')"),
+        CheckConstraint("old_price IS NULL OR price IS NOT NULL"),
+        CheckConstraint("instruction_url IS NULL OR instruction_url LIKE 'https://%'"),
+        Index("ix_guest_notifications_active", "lifecycle_status", "notification_datetime", "id"),
+        Index("ix_guest_notifications_expire", "date_expired"),
+        {"schema": SCHEMA},
+    )
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid7)
+    notification_type: Mapped[str] = mapped_column(
+        ForeignKey(f"{SCHEMA}.notification_types.code", ondelete="RESTRICT")
+    )
+    notification_datetime: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+    header: Mapped[str] = mapped_column(String(255))
+    text: Mapped[str | None] = mapped_column(String(1024))
+    priority_override: Mapped[int | None] = mapped_column(SmallInteger)
+    date_expired: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    price: Mapped[Decimal | None] = mapped_column(Numeric(12, 2))
+    old_price: Mapped[Decimal | None] = mapped_column(Numeric(12, 2))
+    instruction_url: Mapped[str | None] = mapped_column(Text)
+    chat_message_text: Mapped[str | None] = mapped_column(String(1024))
+    lifecycle_status: Mapped[str] = mapped_column(String(16), default="active")
+    closed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+
+
+class NotificationDocument(Common, Base):
+    __tablename__ = "notification_documents"
+    __table_args__ = (
+        UniqueConstraint("notification_id", "document_id"),
+        {"schema": SCHEMA},
+    )
+    notification_id: Mapped[uuid.UUID] = mapped_column(
+        ForeignKey(f"{SCHEMA}.notifications.id", ondelete="RESTRICT")
+    )
+    document_id: Mapped[uuid.UUID] = mapped_column(
+        ForeignKey(f"{SCHEMA}.documents.id", ondelete="RESTRICT")
+    )
+    sort_order: Mapped[int] = mapped_column(SmallInteger, default=0)
+    download_url_issued_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+
+
+class ClientUploadDraft(Base):
+    __tablename__ = "client_upload_drafts"
+    __table_args__ = (
+        CheckConstraint("context_type IN ('notification')"),
+        CheckConstraint("size_bytes > 0"),
+        CheckConstraint("scan_status IN ('pending','clean','bypassed','infected','failed')"),
+        CheckConstraint("state IN ('draft','submitted','discarded')"),
+        Index("ix_client_upload_drafts_context", "user_id", "context_type", "context_id"),
+        Index("ix_client_upload_drafts_scan", "scan_status", "updated_at"),
+        Index("ix_client_upload_drafts_created", "created_at"),
+        {"schema": SCHEMA},
+    )
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid7)
+    user_id: Mapped[uuid.UUID] = mapped_column(
+        ForeignKey(f"{SCHEMA}.user_identities.id", ondelete="RESTRICT")
+    )
+    context_type: Mapped[str] = mapped_column(String(32))
+    context_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True))
+    original_file_name: Mapped[str] = mapped_column(String(255))
+    safe_file_name: Mapped[str] = mapped_column(String(255))
+    mime_type: Mapped[str] = mapped_column(String(128))
+    size_bytes: Mapped[int] = mapped_column(BigInteger)
+    checksum_sha256: Mapped[str | None] = mapped_column(String(64))
+    scan_status: Mapped[str] = mapped_column(String(16), default="pending")
+    storage_bucket: Mapped[str] = mapped_column(String(255))
+    object_key: Mapped[str] = mapped_column(String(1024))
+    quarantine_object_key: Mapped[str | None] = mapped_column(String(1024))
+    quarantine_version_id: Mapped[str | None] = mapped_column(String(1024))
+    quarantine_etag: Mapped[str | None] = mapped_column(String(1024))
+    safety_processing_mode: Mapped[str | None] = mapped_column(String(16))
+    safety_config_version: Mapped[int | None] = mapped_column(BigInteger)
+    safety_rules_version: Mapped[str | None] = mapped_column(String(128))
+    upload_expires_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    completed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    state: Mapped[str] = mapped_column(String(16), default="draft")
+    submission_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True))
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), onupdate=func.now()
+    )
+
+
+class ClientDocument(Common, Base):
+    __tablename__ = "client_documents"
+    __table_args__ = (
+        UniqueConstraint("storage_bucket", "object_key"),
+        UniqueConstraint("source_draft_id"),
+        Index("ix_client_documents_context", "context_type", "context_id"),
+        Index("ix_client_documents_user_submitted", "user_id", "submitted_at"),
+        {"schema": SCHEMA},
+    )
+    user_id: Mapped[uuid.UUID] = mapped_column(
+        ForeignKey(f"{SCHEMA}.user_identities.id", ondelete="RESTRICT")
+    )
+    context_type: Mapped[str] = mapped_column(String(32))
+    context_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True))
+    submission_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True))
+    source_draft_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True))
+    original_file_name: Mapped[str] = mapped_column(String(255))
+    safe_file_name: Mapped[str] = mapped_column(String(255))
+    mime_type: Mapped[str] = mapped_column(String(128))
+    size_bytes: Mapped[int] = mapped_column(BigInteger)
+    checksum_sha256: Mapped[str] = mapped_column(String(64))
+    storage_bucket: Mapped[str] = mapped_column(String(255))
+    object_key: Mapped[str] = mapped_column(String(1024))
+    submitted_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))

VM1_app/codebase/backend/api-backend/app/notification_routes.py

@@ -0,0 +1,505 @@
+import hashlib
+import json
+import uuid
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, Header, Query, Request, Response
+from fastapi.responses import JSONResponse
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.auth import AuthError
+from app.db import UserIdentity
+from app.notification_models import NotificationSource
+from app.notification_schemas import (
+    NotificationCancelRequest,
+    NotificationCreateRequest,
+    UploadCompleteRequest,
+    UploadInitRequest,
+)
+from app.notification_service import (
+    apply_read_or_hide,
+    authenticate_source,
+    cancel_notification,
+    catalog,
+    complete_upload,
+    create_notification,
+    discard_upload,
+    document_download,
+    init_upload,
+    invoke_cta_state,
+    list_notifications,
+    list_uploads,
+    notification_dto,
+    owned_notification,
+    press_button,
+    public_notifications,
+    unread_count,
+)
+from app.schemas import TextMessageRequest
+from app.services import (
+    AuditContext,
+    DomainError,
+    SettingsSnapshot,
+    create_dialog,
+    load_settings,
+    resolve_user,
+    send_message,
+)
+
+router = APIRouter()
+
+
+async def db_session(request: Request):
+    async for value in request.app.state.db.session():
+        yield value
+
+
+Session = Annotated[AsyncSession, Depends(db_session)]
+
+
+async def user_dependency(
+    request: Request,
+    db: Session,
+    authorization: Annotated[str | None, Header()] = None,
+) -> UserIdentity:
+    if not authorization or not authorization.startswith("Bearer "):
+        raise AuthError()
+    principal = await request.app.state.jwks.validate(authorization.removeprefix("Bearer ").strip())
+    return await resolve_user(db, principal)
+
+
+User = Annotated[UserIdentity, Depends(user_dependency)]
+
+
+async def snapshot_dependency(db: Session) -> SettingsSnapshot:
+    return await load_settings(db)
+
+
+Snapshot = Annotated[SettingsSnapshot, Depends(snapshot_dependency)]
+
+
+async def source_dependency(
+    db: Session, authorization: Annotated[str | None, Header()] = None
+) -> NotificationSource:
+    return await authenticate_source(db, authorization)
+
+
+Source = Annotated[NotificationSource, Depends(source_dependency)]
+
+
+def context(request: Request, ux_session: str | None = None) -> AuditContext:
+    try:
+        ux_id = uuid.UUID(ux_session) if ux_session else None
+    except ValueError:
+        raise DomainError("validation_error", 400, "X-Ux-Session-Id must be UUID") from None
+    return AuditContext(
+        request_id=request.state.request_id,
+        trace_id=request.state.trace_id,
+        ux_session_id=ux_id,
+        user_agent_hash=request.state.user_agent_hash,
+        client_ip=None,
+    )
+
+
+async def rate_limit(
+    request: Request,
+    identity: str,
+    route: str,
+    limit: tuple[int, int],
+    *,
+    fail_closed: bool,
+) -> None:
+    key = request.app.state.rate_limiter.key("notification", identity, route, limit[1])
+    try:
+        retry_after = await request.app.state.rate_limiter.consume(key, *limit)
+    except Exception:
+        if fail_closed:
+            raise DomainError(
+                "dependency_unavailable", 503, "Rate limit service is unavailable"
+            ) from None
+        return
+    if retry_after:
+        raise DomainError(
+            "rate_limit_exceeded",
+            429,
+            "Rate limit exceeded",
+            {"retry_after": retry_after},
+        )
+
+
+@router.get("/api/v1/public/notifications", tags=["notifications"])
+async def public_list(request: Request, db: Session, settings: Snapshot):
+    await rate_limit(
+        request,
+        request.client.host if request.client else "unknown",
+        "public",
+        settings.limit("rate_limit.notifications_public.per_ip"),
+        fail_closed=False,
+    )
+    return {
+        "items": await public_notifications(db, settings.integer("notification.home.max_items"))
+    }
+
+
+@router.get("/api/v1/public/notification-types", tags=["notifications"])
+async def type_catalog(
+    request: Request,
+    response: Response,
+    db: Session,
+    settings: Snapshot,
+    if_none_match: Annotated[str | None, Header()] = None,
+):
+    await rate_limit(
+        request,
+        request.client.host if request.client else "unknown",
+        "public",
+        settings.limit("rate_limit.notifications_public.per_ip"),
+        fail_closed=False,
+    )
+    items = await catalog(db)
+    digest = hashlib.sha256(
+        json.dumps(items, default=str, sort_keys=True, separators=(",", ":")).encode()
+    ).hexdigest()
+    etag = f'"{digest}"'
+    if if_none_match == etag:
+        return Response(status_code=304, headers={"ETag": etag})
+    response.headers["ETag"] = etag
+    response.headers["Cache-Control"] = "public, max-age=3600"
+    return {"items": items}
+
+
+@router.get("/api/v1/notifications", tags=["notifications"])
+async def personal_list(
+    request: Request,
+    db: Session,
+    user: User,
+    settings: Snapshot,
+    place: str = Query(pattern="^(home|center)$"),
+):
+    await rate_limit(
+        request,
+        str(user.id),
+        "read",
+        settings.limit("rate_limit.notifications_read.per_user"),
+        fail_closed=False,
+    )
+    limit = settings.integer(
+        "notification.home.max_items" if place == "home" else "notification.center.max_items"
+    )
+    return {"items": await list_notifications(db, user.id, place, limit)}
+
+
+@router.get("/api/v1/notifications/counter", tags=["notifications"])
+async def counter(request: Request, db: Session, user: User, settings: Snapshot):
+    await rate_limit(
+        request,
+        str(user.id),
+        "read",
+        settings.limit("rate_limit.notifications_read.per_user"),
+        fail_closed=False,
+    )
+    return {
+        "unread_count": await unread_count(
+            db, user.id, settings.integer("notification.center.max_items")
+        )
+    }
+
+
+@router.get("/api/v1/notifications/{notification_id}", tags=["notifications"])
+async def detail(
+    notification_id: uuid.UUID,
+    request: Request,
+    db: Session,
+    user: User,
+    settings: Snapshot,
+):
+    await rate_limit(
+        request,
+        str(user.id),
+        "read",
+        settings.limit("rate_limit.notifications_read.per_user"),
+        fail_closed=False,
+    )
+    item, kind = await owned_notification(db, user.id, notification_id)
+    if kind.cta_action != "open_detail":
+        raise DomainError("not_found", 404, "Resource was not found")
+    return await notification_dto(db, item, kind)
+
+
+@router.post("/api/v1/notifications/{notification_id}/read", tags=["notifications"])
+async def mark_read(
+    notification_id: uuid.UUID,
+    request: Request,
+    db: Session,
+    user: User,
+    settings: Snapshot,
+    x_ux_session_id: Annotated[str | None, Header(alias="X-Ux-Session-Id")] = None,
+):
+    await rate_limit(
+        request,
+        str(user.id),
+        "action",
+        settings.limit("rate_limit.notifications_action.per_user"),
+        fail_closed=False,
+    )
+    return await apply_read_or_hide(
+        db,
+        user.id,
+        notification_id,
+        "read",
+        settings,
+        request.app.state.realtime,
+        context(request, x_ux_session_id),
+    )
+
+
+@router.post("/api/v1/notifications/{notification_id}/hide", tags=["notifications"])
+async def hide(
+    notification_id: uuid.UUID,
+    request: Request,
+    db: Session,
+    user: User,
+    settings: Snapshot,
+    x_ux_session_id: Annotated[str | None, Header(alias="X-Ux-Session-Id")] = None,
+):
+    await rate_limit(
+        request,
+        str(user.id),
+        "action",
+        settings.limit("rate_limit.notifications_action.per_user"),
+        fail_closed=False,
+    )
+    return await apply_read_or_hide(
+        db,
+        user.id,
+        notification_id,
+        "hide",
+        settings,
+        request.app.state.realtime,
+        context(request, x_ux_session_id),
+    )
+
+
+@router.post(
+    "/api/v1/notifications/{notification_id}/buttons/{button_code}",
+    tags=["notifications"],
+)
+async def button(
+    notification_id: uuid.UUID,
+    button_code: str,
+    request: Request,
+    db: Session,
+    user: User,
+    settings: Snapshot,
+    x_ux_session_id: Annotated[str | None, Header(alias="X-Ux-Session-Id")] = None,
+):
+    await rate_limit(
+        request,
+        str(user.id),
+        "action",
+        settings.limit("rate_limit.notifications_action.per_user"),
+        fail_closed=False,
+    )
+    return await press_button(
+        db,
+        user.id,
+        notification_id,
+        button_code,
+        settings,
+        request.app.state.realtime,
+        context(request, x_ux_session_id),
+    )
+
+
+@router.post("/api/v1/notifications/{notification_id}/cta", tags=["notifications"])
+async def cta(
+    notification_id: uuid.UUID,
+    request: Request,
+    db: Session,
+    user: User,
+    settings: Snapshot,
+    x_ux_session_id: Annotated[str | None, Header(alias="X-Ux-Session-Id")] = None,
+):
+    await rate_limit(
+        request,
+        str(user.id),
+        "action",
+        settings.limit("rate_limit.notifications_action.per_user"),
+        fail_closed=False,
+    )
+    audit_context = context(request, x_ux_session_id)
+    item, kind = await owned_notification(db, user.id, notification_id, action=True)
+    chat_result = None
+    if kind.cta_action == "send_chat_message":
+        dialog, _status = await create_dialog(
+            db, user, audit_context, f"notification-dialog:{item.id}"
+        )
+        chat_result = await send_message(
+            db,
+            user,
+            uuid.UUID(str(dialog["dialog_id"])),
+            TextMessageRequest(content_kind="text", text=item.chat_message_text or ""),
+            f"notification-message:{item.id}",
+            audit_context,
+            settings,
+            request.app.state.settings,
+            request.app.state.safety,
+            request.app.state.openlines,
+            request.app.state.s3,
+            request.app.state.realtime,
+        )
+    _item, _kind, result = await invoke_cta_state(
+        db,
+        user.id,
+        notification_id,
+        settings,
+        request.app.state.realtime,
+        audit_context,
+        chat_result=chat_result,
+    )
+    return result
+
+
+@router.get(
+    "/api/v1/notifications/{notification_id}/documents/{document_id}/download-url",
+    tags=["notifications"],
+)
+async def download(
+    notification_id: uuid.UUID,
+    document_id: uuid.UUID,
+    request: Request,
+    db: Session,
+    user: User,
+    settings: Snapshot,
+    x_ux_session_id: Annotated[str | None, Header(alias="X-Ux-Session-Id")] = None,
+):
+    await rate_limit(
+        request,
+        str(user.id),
+        "download",
+        settings.limit("rate_limit.download_url.per_user"),
+        fail_closed=True,
+    )
+    return await document_download(
+        db,
+        user.id,
+        notification_id,
+        document_id,
+        settings,
+        request.app.state.s3,
+        request.app.state.realtime,
+        context(request, x_ux_session_id),
+    )
+
+
+@router.post("/api/v1/uploads/init", status_code=201, tags=["uploads"])
+async def upload_init(
+    body: UploadInitRequest,
+    request: Request,
+    db: Session,
+    user: User,
+    settings: Snapshot,
+):
+    await rate_limit(
+        request,
+        str(user.id),
+        "upload",
+        settings.limit("rate_limit.notification_upload.per_user"),
+        fail_closed=True,
+    )
+    return await init_upload(db, user.id, body, settings, request.app.state.s3)
+
+
+@router.post("/api/v1/uploads/{draft_id}/complete", tags=["uploads"])
+async def upload_complete(
+    draft_id: uuid.UUID,
+    body: UploadCompleteRequest,
+    request: Request,
+    db: Session,
+    user: User,
+    settings: Snapshot,
+):
+    await rate_limit(
+        request,
+        str(user.id),
+        "upload",
+        settings.limit("rate_limit.notification_upload.per_user"),
+        fail_closed=True,
+    )
+    return await complete_upload(
+        db,
+        user.id,
+        draft_id,
+        body,
+        request.app.state.s3,
+        request.app.state.safety,
+        request.state.request_id,
+    )
+
+
+@router.get("/api/v1/uploads", tags=["uploads"])
+async def uploads(
+    request: Request,
+    db: Session,
+    user: User,
+    settings: Snapshot,
+    context_type: str,
+    context_id: uuid.UUID,
+):
+    await rate_limit(
+        request,
+        str(user.id),
+        "upload",
+        settings.limit("rate_limit.notification_upload.per_user"),
+        fail_closed=True,
+    )
+    if context_type != "notification":
+        raise DomainError("validation_error", 400, "Unsupported upload context")
+    return {"items": await list_uploads(db, user.id, context_type, context_id)}
+
+
+@router.delete("/api/v1/uploads/{draft_id}", status_code=204, tags=["uploads"])
+async def upload_delete(
+    draft_id: uuid.UUID,
+    request: Request,
+    db: Session,
+    user: User,
+    settings: Snapshot,
+):
+    await rate_limit(
+        request,
+        str(user.id),
+        "upload",
+        settings.limit("rate_limit.notification_upload.per_user"),
+        fail_closed=True,
+    )
+    await discard_upload(db, user.id, draft_id, request.app.state.s3)
+    return Response(status_code=204)
+
+
+@router.post("/internal/notifications/v1/notifications", tags=["internal"])
+async def internal_create(
+    body: NotificationCreateRequest,
+    request: Request,
+    db: Session,
+    source: Source,
+):
+    result, status = await create_notification(
+        db,
+        body,
+        source,
+        request.app.state.s3,
+        request.app.state.realtime,
+        context(request),
+    )
+    return JSONResponse(json.loads(json.dumps(result, default=str)), status_code=status)
+
+
+@router.post("/internal/notifications/v1/notifications/cancel", tags=["internal"])
+async def internal_cancel(
+    body: NotificationCancelRequest,
+    request: Request,
+    db: Session,
+    source: Source,
+):
+    return await cancel_notification(db, body, source, request.app.state.realtime, context(request))

VM1_app/codebase/backend/api-backend/app/notification_schemas.py

@@ -0,0 +1,72 @@
+import uuid
+from datetime import datetime
+from decimal import Decimal
+from typing import Literal
+
+from pydantic import Field, HttpUrl, model_validator
+
+from app.schemas import StrictModel
+
+
+class TodoItem(StrictModel):
+    number: int
+    text: str = Field(min_length=1, max_length=1024)
+
+
+class CompanyDocumentInput(StrictModel):
+    object_key: str = Field(min_length=1, max_length=1024)
+    title: str = Field(min_length=1, max_length=255)
+    mime_type: str = Field(min_length=1, max_length=128)
+    size_bytes: int = Field(gt=0)
+    checksum_sha256: str = Field(pattern=r"^[0-9a-f]{64}$")
+
+
+class NotificationDetailsInput(StrictModel):
+    deadline: datetime | None = None
+    details_header: str | None = Field(default=None, max_length=255)
+    details_text: str | None = Field(default=None, max_length=4000)
+    todo_header: str | None = Field(default=None, max_length=255)
+    todo_plan: list[TodoItem] | None = Field(default=None, min_length=1)
+    send_documents: bool = False
+    documents: list[CompanyDocumentInput] | None = Field(default=None, min_length=1)
+
+
+class NotificationCreateRequest(StrictModel):
+    user_id: uuid.UUID
+    notification_type: str = Field(min_length=1, max_length=32)
+    source: str = Field(min_length=1, max_length=32)
+    external_id: str = Field(min_length=1, max_length=128)
+    notification_datetime: datetime
+    header: str = Field(min_length=1, max_length=255)
+    text: str | None = Field(default=None, max_length=1024)
+    priority_override: int | None = None
+    date_expired: datetime | None = None
+    price: Decimal | None = Field(default=None, ge=0, max_digits=12, decimal_places=2)
+    old_price: Decimal | None = Field(default=None, ge=0, max_digits=12, decimal_places=2)
+    payment_url: HttpUrl | None = None
+    chat_message_text: str | None = Field(default=None, max_length=1024)
+    details: NotificationDetailsInput | None = None
+
+    @model_validator(mode="after")
+    def prices(self) -> "NotificationCreateRequest":
+        if self.old_price is not None and self.price is None:
+            raise ValueError("old_price requires price")
+        return self
+
+
+class NotificationCancelRequest(StrictModel):
+    source: str = Field(min_length=1, max_length=32)
+    external_id: str = Field(min_length=1, max_length=128)
+    close_reason: Literal["cancelled", "paid"]
+
+
+class UploadInitRequest(StrictModel):
+    context_type: Literal["notification"]
+    context_id: uuid.UUID
+    file_name: str = Field(min_length=1, max_length=255)
+    mime_type: str = Field(min_length=1, max_length=128)
+    size_bytes: int = Field(gt=0)
+
+
+class UploadCompleteRequest(StrictModel):
+    checksum: str = Field(pattern=r"^sha256:[0-9a-f]{64}$")

VM1_app/codebase/backend/api-backend/app/otp_settings.py

@@ -0,0 +1,44 @@
+from collections.abc import Mapping
+
+OTP_SETTING_KEYS = {
+    "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",
+}
+
+
+def validate_otp_settings(values: Mapping[str, str]) -> None:
+    parsed: dict[str, int] = {}
+    for key in OTP_SETTING_KEYS:
+        raw = values.get(key)
+        if raw is None:
+            continue
+        try:
+            value = int(raw)
+        except (TypeError, ValueError) as error:
+            raise ValueError(f"{key}: integer value expected") from error
+        if str(value) != raw:
+            raise ValueError(f"{key}: canonical integer value expected")
+        parsed[key] = value
+
+    positive = OTP_SETTING_KEYS - {"otp.phone.min_seconds_between_attempts"}
+    for key in positive:
+        if key in parsed and parsed[key] <= 0:
+            raise ValueError(f"{key}: value must be positive")
+    if parsed.get("otp.phone.min_seconds_between_attempts", 0) < 0:
+        raise ValueError("otp.phone.min_seconds_between_attempts: value must be non-negative")
+
+    code_length = parsed.get("otp.phone.code_length")
+    if code_length is not None and not 4 <= code_length <= 10:
+        raise ValueError("otp.phone.code_length: value must be between 4 and 10")
+
+    ttl_seconds = parsed.get("otp.phone.ttl_seconds")
+    if ttl_seconds is not None and (
+        not 60 <= ttl_seconds <= 900 or ttl_seconds % 60 != 0
+    ):
+        raise ValueError(
+            "otp.phone.ttl_seconds: value must be between 60 and 900 and divisible by 60"
+        )

VM1_app/codebase/backend/api-backend/app/postgres.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import Any
+
+import asyncpg
+from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
+
+
+def asyncpg_dsn(url: str) -> str:
+    if url.startswith("postgresql+asyncpg://"):
+        return url.replace("postgresql+asyncpg://", "postgresql://", 1)
+    return url
+
+
+def create_postgres_engine(url: str, **engine_options: Any) -> AsyncEngine:
+    dsn = asyncpg_dsn(url)
+
+    async def connect():
+        return await asyncpg.connect(dsn=dsn)
+
+    return create_async_engine(
+        "postgresql+asyncpg://",
+        async_creator=connect,
+        **engine_options,
+    )

VM1_app/codebase/backend/api-backend/app/realtime.py

@@ -0,0 +1,98 @@
+import asyncio
+import json
+import uuid
+from collections.abc import AsyncIterator
+from contextlib import suppress
+from typing import Any
+
+from redis.asyncio import Redis
+
+DIALOG_CHANNEL_PREFIX = "han:rt:dialog:"
+USER_CHANNEL_PREFIX = "han:rt:user:"
+# Backward-compatible name used by existing chat integrations.
+CHANNEL_PREFIX = DIALOG_CHANNEL_PREFIX
+
+
+class LocalFanout:
+    def __init__(self) -> None:
+        self._queues: set[asyncio.Queue[dict[str, Any]]] = set()
+
+    async def publish(self, event: dict[str, Any]) -> None:
+        for queue in tuple(self._queues):
+            with suppress(asyncio.QueueFull):
+                queue.put_nowait(event)
+
+    async def subscribe(self) -> AsyncIterator[dict[str, Any]]:
+        queue: asyncio.Queue[dict[str, Any]] = asyncio.Queue(maxsize=256)
+        self._queues.add(queue)
+        try:
+            while True:
+                yield await queue.get()
+        finally:
+            self._queues.discard(queue)
+
+
+class RealtimeFanout:
+    def __init__(self, redis: Redis, local: LocalFanout | None = None) -> None:
+        self.redis = redis
+        self.local = local or LocalFanout()
+
+    async def publish(self, event: dict[str, Any]) -> None:
+        event = {"event_id": str(uuid.uuid4()), **event}
+        channel = DIALOG_CHANNEL_PREFIX + str(event["dialog_id"])
+        try:
+            await self.redis.publish(channel, json.dumps(event, default=str, separators=(",", ":")))
+        except Exception:
+            await self.local.publish(event)
+
+    async def publish_user(self, user_id: uuid.UUID, event: dict[str, Any]) -> None:
+        event = {"event_id": str(uuid.uuid4()), "_user_id": str(user_id), **event}
+        channel = USER_CHANNEL_PREFIX + str(user_id)
+        try:
+            await self.redis.publish(channel, json.dumps(event, default=str, separators=(",", ":")))
+        except Exception:
+            await self.local.publish(event)
+
+    async def events(
+        self,
+        dialog_ids: set[uuid.UUID],
+        user_id: uuid.UUID | None = None,
+        notifications: bool = False,
+    ) -> AsyncIterator[dict[str, Any]]:
+        channels = [DIALOG_CHANNEL_PREFIX + str(dialog_id) for dialog_id in dialog_ids]
+        if notifications and user_id is not None:
+            channels.append(USER_CHANNEL_PREFIX + str(user_id))
+        if not channels:
+            await asyncio.Event().wait()
+            return
+        pubsub = self.redis.pubsub()
+        try:
+            await pubsub.subscribe(*channels)
+        except Exception:
+            await pubsub.aclose()
+            async for event in self.local.subscribe():
+                dialog_match = event.get("dialog_id") and uuid.UUID(
+                    str(event["dialog_id"])
+                ) in dialog_ids
+                user_match = (
+                    notifications
+                    and user_id is not None
+                    and event.get("_user_id") == str(user_id)
+                )
+                if dialog_match or user_match:
+                    payload = dict(event)
+                    payload.pop("_user_id", None)
+                    yield payload
+            return
+        try:
+            while True:
+                message = await pubsub.get_message(ignore_subscribe_messages=True, timeout=1)
+                if message:
+                    payload = json.loads(message["data"])
+                    payload.pop("_user_id", None)
+                    yield payload
+                else:
+                    await asyncio.sleep(0)
+        finally:
+            await pubsub.unsubscribe(*channels)
+            await pubsub.aclose()

VM1_app/codebase/backend/api-backend/app/schemas.py

@@ -0,0 +1,161 @@
+import hashlib
+import hmac
+import json
+import uuid
+from base64 import urlsafe_b64decode, urlsafe_b64encode
+from datetime import datetime
+from enum import StrEnum
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, HttpUrl, model_validator
+
+from app.chat_settings import CHAT_MESSAGE_TRANSPORT_MAX_LENGTH
+
+
+class StrictModel(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class OtpSettingsResponse(StrictModel):
+    max_send_attempts_per_24h: int = Field(strict=True, gt=0)
+    min_seconds_between_attempts: int = Field(strict=True, ge=0)
+    max_verify_attempts: int = Field(strict=True, gt=0)
+    code_length: int = Field(strict=True, ge=4, le=10)
+    ttl_seconds: int = Field(strict=True, ge=60, le=900, multiple_of=60)
+    sms_order_timeout_ms: int = Field(strict=True, gt=0)
+    version: str = Field(min_length=1, max_length=64)
+    cache_ttl_seconds: int = Field(strict=True, gt=0)
+
+
+class Device(StrictModel):
+    platform: Literal["ios", "android", "web"]
+    app_version: str = Field(min_length=1, max_length=64)
+    device_id: str | None = Field(default=None, max_length=255)
+
+
+class ConsentChoice(StrictModel):
+    accepted: bool
+    version: str = Field(min_length=1, max_length=64)
+
+
+class ConsentSet(StrictModel):
+    personal_data: ConsentChoice
+    user_agreement: ConsentChoice
+    marketing: ConsentChoice
+
+
+class BootstrapRequest(StrictModel):
+    consents: ConsentSet
+    device: Device
+
+
+class ConsentsRequest(StrictModel):
+    consents: ConsentSet
+
+
+class SessionStartRequest(StrictModel):
+    start_reason: Literal["first_launch", "cold_start", "idle_timeout"]
+    device: Device
+
+
+class TextMessageRequest(StrictModel):
+    content_kind: Literal["text"]
+    text: str = Field(min_length=1, max_length=CHAT_MESSAGE_TRANSPORT_MAX_LENGTH)
+
+
+class FileMessageRequest(StrictModel):
+    content_kind: Literal["file"]
+    attachment_id: uuid.UUID
+    checksum: str = Field(pattern=r"^sha256:[0-9a-f]{64}$")
+
+
+MessageRequest = Annotated[
+    TextMessageRequest | FileMessageRequest, Field(discriminator="content_kind")
+]
+
+
+class AttachmentInitRequest(StrictModel):
+    file_name: str = Field(min_length=1, max_length=255)
+    mime_type: str = Field(min_length=1, max_length=128)
+    size_bytes: int = Field(gt=0)
+
+
+class AttachmentCompleteRequest(StrictModel):
+    checksum: str = Field(pattern=r"^sha256:[0-9a-f]{64}$")
+
+
+class OpenLinesFile(StrictModel):
+    name: str = Field(min_length=1, max_length=255)
+    mime_type: str = Field(min_length=1, max_length=128)
+    size_bytes: int = Field(gt=0)
+    download_url: HttpUrl
+
+
+class OpenLinesMessage(StrictModel):
+    text: str = Field(default="", max_length=4000)
+    files: list[OpenLinesFile] = Field(default_factory=list, max_length=1)
+
+    @model_validator(mode="after")
+    def non_empty(self) -> "OpenLinesMessage":
+        if not self.text.strip() and not self.files:
+            raise ValueError("message must contain text or file")
+        return self
+
+
+class OpenLinesInbox(StrictModel):
+    event_id: str = Field(min_length=1, max_length=255)
+    event_type: Literal["message.new", "dialog.closed"]
+    external_chat_id: uuid.UUID
+    bitrix_message_id: str | None = Field(default=None, max_length=255)
+    occurred_at: datetime
+    message: OpenLinesMessage | None = None
+
+    @model_validator(mode="after")
+    def event_shape(self) -> "OpenLinesInbox":
+        if self.event_type == "message.new" and (
+            not self.bitrix_message_id or self.message is None
+        ):
+            raise ValueError("message.new requires bitrix_message_id and message")
+        return self
+
+
+class DialogStatus(StrEnum):
+    OPEN = "open"
+    WAITING_COMPANY = "waiting_for_company"
+    WAITING_CLIENT = "waiting_for_client"
+    CLOSED = "closed"
+
+
+def canonical_fingerprint(
+    method: str, route: str, path_params: dict[str, str], body: object, user_id: uuid.UUID
+) -> str:
+    value = {
+        "method": method.upper(),
+        "route": route,
+        "path": dict(sorted(path_params.items())),
+        "body": body,
+        "user_id": str(user_id),
+    }
+    return hashlib.sha256(
+        json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode()
+    ).hexdigest()
+
+
+def encode_cursor(data: dict[str, str], secret: bytes) -> str:
+    payload = json.dumps({"v": 1, **data}, sort_keys=True, separators=(",", ":")).encode()
+    signature = hmac.digest(secret, payload, "sha256")
+    return urlsafe_b64encode(payload + signature).decode().rstrip("=")
+
+
+def decode_cursor(value: str, secret: bytes) -> dict[str, str]:
+    try:
+        raw = urlsafe_b64decode(value + "=" * (-len(value) % 4))
+        payload, signature = raw[:-32], raw[-32:]
+        if not hmac.compare_digest(signature, hmac.digest(secret, payload, "sha256")):
+            raise ValueError("invalid cursor")
+        decoded = json.loads(payload)
+        if decoded.pop("v") != 1:
+            raise ValueError("unsupported cursor")
+        return decoded
+    except (ValueError, KeyError, json.JSONDecodeError) as exc:
+        raise ValueError("invalid cursor") from exc

VM1_app/codebase/backend/api-backend/app/settings.py

@@ -0,0 +1,95 @@
+from functools import lru_cache
+from typing import Literal
+
+from pydantic import AnyHttpUrl, Field, SecretStr, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env", env_file_encoding="utf-8", case_sensitive=True, extra="ignore"
+    )
+
+    app_env: str = Field(alias="APP_ENV")
+    api_port: int = Field(default=8000, alias="API_PORT")
+    log_level: str = Field(default="INFO", alias="LOG_LEVEL")
+    database_url: str = Field(alias="DATABASE_URL")
+    redis_url: str = Field(alias="REDIS_URL")
+    redis_realtime_url: str = Field(alias="REDIS_REALTIME_URL")
+
+    keycloak_public_url: AnyHttpUrl = Field(alias="KEYCLOAK_PUBLIC_URL")
+    keycloak_internal_url: AnyHttpUrl = Field(alias="KEYCLOAK_INTERNAL_URL")
+    keycloak_realm: str = Field(alias="KEYCLOAK_REALM")
+    keycloak_audience: str = Field(alias="KEYCLOAK_AUDIENCE")
+    jwks_cache_ttl_seconds: int = 300
+    jwks_stale_grace_seconds: int = 900
+
+    message_safety_url: AnyHttpUrl = Field(alias="MESSAGE_SAFETY_URL")
+    message_safety_service_token: SecretStr = Field(alias="MESSAGE_SAFETY_SERVICE_TOKEN")
+    message_safety_ca_file: str | None = Field(default=None, alias="MESSAGE_SAFETY_CA_FILE")
+    message_safety_api_prefix: Literal["/internal/safety/v2"] = Field(
+        default="/internal/safety/v2", alias="MESSAGE_SAFETY_API_PREFIX"
+    )
+    message_safety_post_timeout_sec: float = Field(
+        default=5, alias="MESSAGE_SAFETY_POST_TIMEOUT_SEC"
+    )
+    message_safety_task_poll_interval_sec: float = Field(
+        default=2, alias="MESSAGE_SAFETY_TASK_POLL_INTERVAL_SEC"
+    )
+    message_safety_task_poll_max_sec: float = Field(
+        default=300, alias="MESSAGE_SAFETY_TASK_POLL_MAX_SEC"
+    )
+    message_safety_circuit_failure_threshold: int = Field(
+        default=5, alias="MESSAGE_SAFETY_CIRCUIT_FAILURE_THRESHOLD"
+    )
+    message_safety_circuit_open_sec: int = Field(
+        default=30, alias="MESSAGE_SAFETY_CIRCUIT_OPEN_SEC"
+    )
+
+    bitrix_local_app_base_url: AnyHttpUrl = Field(alias="BITRIX_LOCAL_APP_BASE_URL")
+    bitrix_local_app_internal_token: SecretStr = Field(alias="BITRIX_LOCAL_APP_INTERNAL_TOKEN")
+    bitrix_api_inbox_token: SecretStr = Field(alias="BITRIX_API_INBOX_TOKEN")
+    bitrix_local_app_http_timeout_sec: float = Field(
+        default=20, alias="BITRIX_LOCAL_APP_HTTP_TIMEOUT_SEC"
+    )
+    bitrix_local_app_circuit_failure_threshold: int = Field(
+        default=5, alias="BITRIX_LOCAL_APP_CIRCUIT_FAILURE_THRESHOLD"
+    )
+    bitrix_local_app_circuit_open_sec: int = Field(
+        default=30, alias="BITRIX_LOCAL_APP_CIRCUIT_OPEN_SEC"
+    )
+    keycloak_settings_bridge_token: SecretStr = Field(alias="KEYCLOAK_SETTINGS_BRIDGE_TOKEN")
+
+    selectel_s3_endpoint_url: AnyHttpUrl = Field(alias="SELECTEL_S3_ENDPOINT_URL")
+    selectel_s3_bucket_documents: str = Field(alias="SELECTEL_S3_BUCKET_DOCUMENTS")
+    selectel_s3_bucket_attachments: str = Field(alias="SELECTEL_S3_BUCKET_ATTACHMENTS")
+    selectel_s3_bucket_quarantine: str = Field(alias="SELECTEL_S3_BUCKET_QUARANTINE")
+    selectel_s3_access_key: SecretStr = Field(alias="SELECTEL_S3_ACCESS_KEY")
+    selectel_s3_secret_key: SecretStr = Field(alias="SELECTEL_S3_SECRET_KEY")
+    otel_exporter_otlp_endpoint: str | None = Field(
+        default=None, alias="OTEL_EXPORTER_OTLP_ENDPOINT"
+    )
+    cursor_hmac_secret: SecretStr = Field(alias="CURSOR_HMAC_SECRET")
+    trusted_proxy_cidrs: str = Field(default="127.0.0.1/32", alias="TRUSTED_PROXY_CIDRS")
+    worker_poll_interval_sec: float = Field(default=2, alias="WORKER_POLL_INTERVAL_SEC")
+    notifications_token_producer_test: SecretStr | None = Field(
+        default=None, alias="NOTIFICATIONS_TOKEN_PRODUCER_TEST"
+    )
+
+    @model_validator(mode="after")
+    def require_safety_tls_in_deployed_environments(self) -> "Settings":
+        if self.app_env not in {"local", "test"}:
+            if str(self.message_safety_url).split(":", 1)[0] != "https":
+                raise ValueError("MESSAGE_SAFETY_URL must use HTTPS")
+            if not self.message_safety_ca_file:
+                raise ValueError("MESSAGE_SAFETY_CA_FILE is required")
+        return self
+
+    @property
+    def issuer(self) -> str:
+        return f"{str(self.keycloak_public_url).rstrip('/')}/realms/{self.keycloak_realm}"
+
+
+@lru_cache
+def get_settings() -> Settings:
+    return Settings()

VM1_app/codebase/backend/api-backend/app/telemetry.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Any
+
+from fastapi import FastAPI
+from opentelemetry import metrics, trace
+from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import OTLPMetricExporter
+from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
+from opentelemetry.instrumentation.botocore import BotocoreInstrumentor
+from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
+from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor
+from opentelemetry.instrumentation.redis import RedisInstrumentor
+from opentelemetry.instrumentation.sqlalchemy import SQLAlchemyInstrumentor
+from opentelemetry.propagate import set_global_textmap
+from opentelemetry.sdk.metrics import MeterProvider
+from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.sdk.trace.sampling import ALWAYS_ON
+from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+
+
+@dataclass(slots=True)
+class TelemetryRuntime:
+    tracer_provider: TracerProvider
+    meter_provider: MeterProvider
+
+    def shutdown(self) -> None:
+        self.meter_provider.shutdown()
+        self.tracer_provider.shutdown()
+
+
+_runtime: TelemetryRuntime | None = None
+
+
+def _resource(service_name: str) -> Resource:
+    return Resource.create(
+        {
+            "service.name": service_name,
+            "service.namespace": "han-chat",
+            "service.version": os.getenv("RELEASE_VERSION", "unknown"),
+            "deployment.environment": os.getenv("APP_ENV", "production-like"),
+        }
+    )
+
+
+def init_telemetry(service_name: str | None = None) -> TelemetryRuntime | None:
+    global _runtime
+    if _runtime is not None:
+        return _runtime
+    endpoint = os.getenv("OTEL_EXPORTER_OTLP_ENDPOINT", "").strip()
+    if not endpoint:
+        return None
+
+    resource = _resource(service_name or os.getenv("OTEL_SERVICE_NAME", "api-backend"))
+    insecure = endpoint.startswith("http://")
+    set_global_textmap(TraceContextTextMapPropagator())
+
+    tracer_provider = TracerProvider(resource=resource, sampler=ALWAYS_ON)
+    tracer_provider.add_span_processor(
+        BatchSpanProcessor(
+            OTLPSpanExporter(endpoint=endpoint, insecure=insecure, timeout=3),
+            max_queue_size=2048,
+            schedule_delay_millis=5000,
+            max_export_batch_size=512,
+            export_timeout_millis=3000,
+        )
+    )
+    trace.set_tracer_provider(tracer_provider)
+
+    metric_reader = PeriodicExportingMetricReader(
+        OTLPMetricExporter(endpoint=endpoint, insecure=insecure, timeout=3),
+        export_interval_millis=30000,
+        export_timeout_millis=3000,
+    )
+    meter_provider = MeterProvider(resource=resource, metric_readers=[metric_reader])
+    metrics.set_meter_provider(meter_provider)
+
+    HTTPXClientInstrumentor().instrument()
+    SQLAlchemyInstrumentor().instrument(enable_commenter=False)
+    RedisInstrumentor().instrument()
+    BotocoreInstrumentor().instrument()
+    _runtime = TelemetryRuntime(tracer_provider, meter_provider)
+    return _runtime
+
+
+def instrument_fastapi(app: FastAPI) -> None:
+    FastAPIInstrumentor.instrument_app(
+        app,
+        excluded_urls="/health/live,/health/ready,/nginx-health/live",
+    )
+
+
+def add_trace_context(
+    _logger: Any,
+    _method_name: str,
+    event_dict: dict[str, Any],
+) -> dict[str, Any]:
+    context = trace.get_current_span().get_span_context()
+    if context.is_valid:
+        event_dict["trace_id"] = format(context.trace_id, "032x")
+        event_dict["span_id"] = format(context.span_id, "016x")
+    return event_dict
+
+
+def current_trace_id() -> str | None:
+    context = trace.get_current_span().get_span_context()
+    return format(context.trace_id, "032x") if context.is_valid else None

VM1_app/codebase/backend/api-backend/app/workers.py

@@ -0,0 +1,383 @@
+import asyncio
+import uuid
+from datetime import UTC, datetime, timedelta
+
+import httpx
+import redis.asyncio as redis
+import structlog
+from sqlalchemy import delete, select
+
+from app.db import (
+    Database,
+    DeliveryOutbox,
+    Dialog,
+    Message,
+    MessageAttachment,
+    SafetyTask,
+    UserIdentity,
+)
+from app.integrations import (
+    DependencyFailure,
+    OpenLinesClient,
+    S3Client,
+    SafetyClient,
+    fresh_openlines_payload,
+)
+from app.notification_models import ClientUploadDraft
+from app.notification_service import expire_notifications
+from app.realtime import RealtimeFanout
+from app.services import load_settings, publish_dialog_status, publish_message_status
+from app.settings import Settings, get_settings
+
+log = structlog.get_logger()
+
+
+async def delivery_once(
+    db: Database,
+    client: OpenLinesClient,
+    s3: S3Client,
+    fanout: RealtimeFanout,
+    settings: Settings,
+    worker_id: str,
+    batch_size: int = 20,
+) -> int:
+    async with db.sessions() as session:
+        rows = (
+            (
+                await session.execute(
+                    select(DeliveryOutbox)
+                    .where(
+                        DeliveryOutbox.status.in_(["pending", "retry"]),
+                        DeliveryOutbox.next_attempt_at <= datetime.now(UTC),
+                    )
+                    .with_for_update(skip_locked=True)
+                    .limit(batch_size)
+                )
+            )
+            .scalars()
+            .all()
+        )
+        ids = [row.id for row in rows]
+        for row in rows:
+            row.status = "processing"
+            row.locked_at = datetime.now(UTC)
+            row.locked_by = worker_id
+        await session.commit()
+    for row_id in ids:
+        async with db.sessions() as session:
+            row = await session.get(DeliveryOutbox, row_id, with_for_update=True)
+            if row is None:
+                continue
+            message = None
+            dialog = None
+            try:
+                payload = await fresh_openlines_payload(row.payload_json, s3)
+                await client.send(row.message_id, payload, f"worker-{worker_id}")
+                row.status = "delivered"
+                message = await session.get(Message, row.message_id)
+                if message:
+                    message.delivery_status = "delivered"
+                    dialog = await session.get(Dialog, message.dialog_id)
+                    if dialog:
+                        dialog.status = "waiting_for_company"
+                        dialog.last_message_at = datetime.now(UTC)
+            except DependencyFailure:
+                row.attempt_count += 1
+                row.status = "dead_letter" if row.attempt_count >= 12 else "retry"
+                row.next_attempt_at = datetime.now(UTC) + timedelta(
+                    seconds=min(3600, 2**row.attempt_count)
+                )
+                row.last_error_code = "dependency_unavailable"
+            row.locked_at = None
+            row.locked_by = None
+            await session.commit()
+            if message:
+                await publish_message_status(fanout, message, settings)
+            if dialog:
+                await publish_dialog_status(fanout, dialog)
+    return len(ids)
+
+
+async def safety_once(
+    db: Database,
+    safety: SafetyClient,
+    s3: S3Client,
+    fanout: RealtimeFanout,
+    settings: Settings,
+    worker_id: str,
+    batch_size: int = 20,
+) -> int:
+    async with db.sessions() as session:
+        rows = (
+            (
+                await session.execute(
+                    select(SafetyTask)
+                    .where(
+                        SafetyTask.status.in_(["polling", "failed"]),
+                        SafetyTask.next_poll_at <= datetime.now(UTC),
+                        SafetyTask.expires_at > datetime.now(UTC),
+                    )
+                    .with_for_update(skip_locked=True)
+                    .limit(batch_size)
+                )
+            )
+            .scalars()
+            .all()
+        )
+        ids = [row.id for row in rows]
+        for row in rows:
+            row.locked_at, row.locked_by = datetime.now(UTC), worker_id
+        await session.commit()
+    for task_id in ids:
+        async with db.sessions() as session:
+            task = await session.get(SafetyTask, task_id, with_for_update=True)
+            if task is None:
+                continue
+            message = None
+            try:
+                verdict = await safety.poll(task.poll_location, f"worker-{worker_id}")
+                message = await session.get(Message, task.message_id)
+                attachment = (
+                    await session.get(MessageAttachment, task.attachment_id)
+                    if task.attachment_id
+                    else None
+                )
+                if verdict["_status"] == 200 and message:
+                    message.safety_processing_mode = verdict["processing_mode"]
+                    message.safety_config_version = verdict["config_version"]
+                    message.safety_rules_version = verdict["rules_version"]
+                    if attachment and attachment.quarantine_object_key:
+                        destination = f"attachments/dialogs/{message.dialog_id}/{attachment.id}"
+                        await s3.promote(
+                            attachment.quarantine_object_key,
+                            destination,
+                            version_id=attachment.quarantine_version_id or "",
+                            etag=attachment.quarantine_etag or "",
+                        )
+                        attachment.storage_bucket = s3.settings.selectel_s3_bucket_attachments
+                        attachment.object_key = destination
+                        attachment.quarantine_object_key = None
+                        attachment.scan_status = (
+                            "bypassed"
+                            if verdict["processing_mode"] == "mock"
+                            else "clean"
+                        )
+                    message.safety_status = "allowed"
+                    task.status = "completed"
+                    dialog = await session.get(Dialog, message.dialog_id)
+                    user = (
+                        await session.get(UserIdentity, dialog.user_id)
+                        if dialog
+                        else None
+                    )
+                    if dialog and user:
+                        session.add(
+                            DeliveryOutbox(
+                                message_id=message.id,
+                                external_chat_id=dialog.id,
+                                payload_json={
+                                    "message_id": str(message.id),
+                                    "external_chat_id": str(dialog.id),
+                                    "occurred_at": message.occurred_at.isoformat(),
+                                    "user": {
+                                        "id": str(user.id),
+                                        "display_name": user.phone_number,
+                                    },
+                                    "message": {
+                                        "content_kind": message.content_kind,
+                                        "text": message.text,
+                                        "files": (
+                                            [{
+                                                "attachment_id": str(attachment.id),
+                                                "name": attachment.safe_file_name,
+                                                "mime_type": attachment.mime_type,
+                                                "size_bytes": attachment.size_bytes,
+                                                "_storage_bucket": attachment.storage_bucket,
+                                                "_object_key": attachment.object_key,
+                                            }]
+                                            if attachment
+                                            else []
+                                        ),
+                                    },
+                                },
+                                next_attempt_at=datetime.now(UTC),
+                            )
+                        )
+                elif verdict["_status"] == 403 and message:
+                    message.safety_processing_mode = verdict["processing_mode"]
+                    message.safety_config_version = verdict["config_version"]
+                    message.safety_rules_version = verdict["rules_version"]
+                    message.text = ""
+                    message.safety_status = "blocked"
+                    message.delivery_status = "rejected"
+                    if attachment and attachment.quarantine_object_key:
+                        await s3.delete_quarantine(attachment.quarantine_object_key)
+                        attachment.scan_status = "infected"
+                    task.status = "completed"
+                else:
+                    if verdict["_status"] == 202:
+                        task.poll_location = verdict["_location"]
+                    task.next_poll_at = datetime.now(UTC) + timedelta(seconds=2)
+            except DependencyFailure as exc:
+                task.attempt_count += 1
+                terminal = exc.terminal or (
+                    exc.code == "task_not_found" and task.attempt_count >= 2
+                )
+                task.status = "terminal_failed" if terminal else "failed"
+                task.last_error_code = exc.code
+                if terminal and message:
+                    message.delivery_status = "failed"
+                task.next_poll_at = datetime.now(UTC) + timedelta(
+                    seconds=min(300, 2**task.attempt_count)
+                )
+            task.locked_at = None
+            task.locked_by = None
+            await session.commit()
+            if message:
+                await publish_message_status(fanout, message, settings)
+    return len(ids)
+
+
+async def cleanup_once(db: Database, s3: S3Client, batch_size: int = 100) -> int:
+    async with db.sessions() as session:
+        rows = (
+            (
+                await session.execute(
+                    select(MessageAttachment)
+                    .where(
+                        MessageAttachment.record_status == "A",
+                        MessageAttachment.quarantine_object_key.is_not(None),
+                        MessageAttachment.upload_expires_at < datetime.now(UTC),
+                        MessageAttachment.message_id.is_(None),
+                    )
+                    .with_for_update(skip_locked=True)
+                    .limit(batch_size)
+                )
+            )
+            .scalars()
+            .all()
+        )
+        for row in rows:
+            if row.quarantine_object_key:
+                await s3.delete_quarantine(row.quarantine_object_key)
+            row.record_status = "D"
+            row.status_changed_at = datetime.now(UTC)
+            row.status_change_reason = "expired_quarantine_cleanup"
+        await session.commit()
+        return len(rows)
+
+
+async def loop(kind: str) -> None:
+    settings = get_settings()
+    db = Database(settings.database_url)
+    http = httpx.AsyncClient()
+    safety = SafetyClient(settings, http)
+    openlines = OpenLinesClient(settings, http)
+    s3 = S3Client(settings)
+    redis_rt = redis.from_url(settings.redis_realtime_url, decode_responses=True)
+    fanout = RealtimeFanout(redis_rt)
+    worker_id = f"{kind}-{uuid.uuid4()}"
+    try:
+        while True:
+            count = 0
+            if kind == "delivery":
+                count = await delivery_once(db, openlines, s3, fanout, settings, worker_id)
+            elif kind == "safety":
+                count = await safety_once(db, safety, s3, fanout, settings, worker_id)
+            else:
+                count = await cleanup_once(db, s3)
+            if not count:
+                await asyncio.sleep(settings.worker_poll_interval_sec)
+    finally:
+        await http.aclose()
+        await redis_rt.aclose()
+        await db.close()
+
+
+async def notification_expire_loop() -> None:
+    settings = get_settings()
+    db = Database(settings.database_url)
+    try:
+        while True:
+            async with db.sessions() as session:
+                snapshot = await load_settings(session)
+                run_at = snapshot.values["notification.expire_job.run_at"]
+            hour, minute = (int(value) for value in run_at.split(":", 1))
+            now = datetime.now(UTC)
+            target = now.replace(hour=hour, minute=minute, second=0, microsecond=0)
+            if target <= now:
+                target += timedelta(days=1)
+            await asyncio.sleep((target - now).total_seconds())
+            async with db.sessions() as session:
+                personal, guest = await expire_notifications(session)
+                log.info(
+                    "notification.expired_batch",
+                    personal_count=personal,
+                    guest_count=guest,
+                )
+    finally:
+        await db.close()
+
+
+async def notification_draft_cleanup_once(db: Database, s3: S3Client) -> int:
+    async with db.sessions() as session:
+        snapshot = await load_settings(session)
+        cutoff = datetime.now(UTC) - timedelta(
+            days=snapshot.integer("notification.upload_draft.ttl_days")
+        )
+        rows = (
+            (
+                await session.execute(
+                    select(ClientUploadDraft)
+                    .where(ClientUploadDraft.created_at < cutoff)
+                    .with_for_update(skip_locked=True)
+                    .limit(100)
+                )
+            )
+            .scalars()
+            .all()
+        )
+        for row in rows:
+            if row.state != "submitted":
+                if row.quarantine_object_key:
+                    await s3.delete_quarantine(row.quarantine_object_key)
+                elif row.object_key:
+                    await s3.delete(row.storage_bucket, row.object_key)
+            await session.execute(
+                delete(ClientUploadDraft).where(ClientUploadDraft.id == row.id)
+            )
+        await session.commit()
+        return len(rows)
+
+
+async def notification_draft_cleanup_loop() -> None:
+    settings = get_settings()
+    db = Database(settings.database_url)
+    s3 = S3Client(settings)
+    try:
+        while True:
+            count = await notification_draft_cleanup_once(db, s3)
+            if count < 100:
+                await asyncio.sleep(86400)
+    finally:
+        await db.close()
+
+
+def delivery_main() -> None:
+    asyncio.run(loop("delivery"))
+
+
+def safety_main() -> None:
+    asyncio.run(loop("safety"))
+
+
+def cleanup_main() -> None:
+    asyncio.run(loop("cleanup"))
+
+
+def notification_expire_main() -> None:
+    asyncio.run(notification_expire_loop())
+
+
+def notification_draft_cleanup_main() -> None:
+    asyncio.run(notification_draft_cleanup_loop())

VM1_app/codebase/backend/api-backend/container-entrypoint.sh

@@ -0,0 +1,23 @@
+#!/bin/sh
+set -eu
+
+for name in ${HAN_SECRET_VARS:-}; do
+  case "$name" in
+    ""|[0-9]*|*[!A-Z0-9_]*)
+      echo "container secrets: invalid variable name" >&2
+      exit 64
+      ;;
+    *) ;;
+  esac
+  eval "file=\${${name}_FILE:-}"
+  if [ -z "$file" ] || [ ! -r "$file" ]; then
+    echo "container secrets: missing file for $name" >&2
+    exit 66
+  fi
+  value=$(cat "$file")
+  export "$name=$value"
+  unset "${name}_FILE"
+done
+
+unset HAN_SECRET_VARS
+exec "$@"

VM1_app/codebase/backend/api-backend/docker-compose.yml

@@ -0,0 +1,103 @@
+services:
+  api-backend:
+    build: .
+    image: han-chat/api-backend:local
+    expose:
+      - "8000"
+    environment:
+      HAN_SECRET_VARS: >-
+        DATABASE_URL REDIS_URL REDIS_REALTIME_URL MESSAGE_SAFETY_SERVICE_TOKEN
+        BITRIX_LOCAL_APP_INTERNAL_TOKEN BITRIX_API_INBOX_TOKEN
+        KEYCLOAK_SETTINGS_BRIDGE_TOKEN SELECTEL_S3_ACCESS_KEY SELECTEL_S3_SECRET_KEY
+        CURSOR_HMAC_SECRET
+      DATABASE_URL_FILE: /run/secrets/api_database_url
+      REDIS_URL_FILE: /run/secrets/api_redis_url
+      REDIS_REALTIME_URL_FILE: /run/secrets/api_redis_realtime_url
+      MESSAGE_SAFETY_SERVICE_TOKEN_FILE: /run/secrets/message_safety_service_token
+      BITRIX_LOCAL_APP_INTERNAL_TOKEN_FILE: /run/secrets/bitrix_local_app_internal_token
+      BITRIX_API_INBOX_TOKEN_FILE: /run/secrets/bitrix_api_inbox_token
+      KEYCLOAK_SETTINGS_BRIDGE_TOKEN_FILE: /run/secrets/keycloak_settings_bridge_token
+      SELECTEL_S3_ACCESS_KEY_FILE: /run/secrets/selectel_s3_access_key
+      SELECTEL_S3_SECRET_KEY_FILE: /run/secrets/selectel_s3_secret_key
+      CURSOR_HMAC_SECRET_FILE: /run/secrets/cursor_hmac_secret
+      APP_ENV: ${APP_ENV}
+      API_PORT: ${API_PORT:-8000}
+      LOG_LEVEL: ${LOG_LEVEL:-INFO}
+      KEYCLOAK_PUBLIC_URL: ${KEYCLOAK_PUBLIC_URL}
+      KEYCLOAK_INTERNAL_URL: ${KEYCLOAK_INTERNAL_URL}
+      KEYCLOAK_REALM: ${KEYCLOAK_REALM}
+      KEYCLOAK_AUDIENCE: ${KEYCLOAK_AUDIENCE}
+      MESSAGE_SAFETY_URL: ${MESSAGE_SAFETY_URL}
+      MESSAGE_SAFETY_API_PREFIX: /internal/safety/v2
+      MESSAGE_SAFETY_CA_FILE: /run/config/message-safety-internal-ca.pem
+      MESSAGE_SAFETY_POST_TIMEOUT_SEC: ${MESSAGE_SAFETY_POST_TIMEOUT_SEC:-5}
+      MESSAGE_SAFETY_TASK_POLL_INTERVAL_SEC: ${MESSAGE_SAFETY_TASK_POLL_INTERVAL_SEC:-2}
+      MESSAGE_SAFETY_TASK_POLL_MAX_SEC: ${MESSAGE_SAFETY_TASK_POLL_MAX_SEC:-300}
+      MESSAGE_SAFETY_CIRCUIT_FAILURE_THRESHOLD: ${MESSAGE_SAFETY_CIRCUIT_FAILURE_THRESHOLD:-5}
+      MESSAGE_SAFETY_CIRCUIT_OPEN_SEC: ${MESSAGE_SAFETY_CIRCUIT_OPEN_SEC:-30}
+      BITRIX_LOCAL_APP_BASE_URL: ${BITRIX_LOCAL_APP_BASE_URL}
+      BITRIX_LOCAL_APP_HTTP_TIMEOUT_SEC: ${BITRIX_LOCAL_APP_HTTP_TIMEOUT_SEC:-20}
+      BITRIX_LOCAL_APP_CIRCUIT_FAILURE_THRESHOLD: ${BITRIX_LOCAL_APP_CIRCUIT_FAILURE_THRESHOLD:-5}
+      BITRIX_LOCAL_APP_CIRCUIT_OPEN_SEC: ${BITRIX_LOCAL_APP_CIRCUIT_OPEN_SEC:-30}
+      SELECTEL_S3_ENDPOINT_URL: ${SELECTEL_S3_ENDPOINT_URL}
+      SELECTEL_S3_BUCKET_DOCUMENTS: ${SELECTEL_S3_BUCKET_DOCUMENTS}
+      SELECTEL_S3_BUCKET_ATTACHMENTS: ${SELECTEL_S3_BUCKET_ATTACHMENTS}
+      SELECTEL_S3_BUCKET_QUARANTINE: ${SELECTEL_S3_BUCKET_QUARANTINE}
+      OTEL_EXPORTER_OTLP_ENDPOINT: ${OTEL_EXPORTER_OTLP_ENDPOINT}
+    secrets:
+      - api_database_url
+      - api_redis_url
+      - api_redis_realtime_url
+      - message_safety_service_token
+      - bitrix_local_app_internal_token
+      - bitrix_api_inbox_token
+      - keycloak_settings_bridge_token
+      - selectel_s3_access_key
+      - selectel_s3_secret_key
+      - cursor_hmac_secret
+    volumes:
+      - type: bind
+        source: ${MESSAGE_SAFETY_CA_HOST_PATH}
+        target: /run/config/message-safety-internal-ca.pem
+        read_only: true
+    healthcheck:
+      test:
+        - CMD
+        - python
+        - -c
+        - "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health/live', timeout=2)"
+      interval: 10s
+      timeout: 3s
+      retries: 5
+    restart: unless-stopped
+    ulimits:
+      core: {soft: 0, hard: 0}
+    networks:
+      - backend
+      - observability
+
+networks:
+  backend:
+  observability:
+
+secrets:
+  api_database_url:
+    file: ${HAN_SECRETS_DIR:-/run/han-chat/secrets}/DATABASE_URL
+  api_redis_url:
+    file: ${HAN_SECRETS_DIR:-/run/han-chat/secrets}/REDIS_URL
+  api_redis_realtime_url:
+    file: ${HAN_SECRETS_DIR:-/run/han-chat/secrets}/REDIS_REALTIME_URL
+  message_safety_service_token:
+    file: ${HAN_SECRETS_DIR:-/run/han-chat/secrets}/MESSAGE_SAFETY_SERVICE_TOKEN
+  bitrix_local_app_internal_token:
+    file: ${HAN_SECRETS_DIR:-/run/han-chat/secrets}/BITRIX_LOCAL_APP_INTERNAL_TOKEN
+  bitrix_api_inbox_token:
+    file: ${HAN_SECRETS_DIR:-/run/han-chat/secrets}/BITRIX_API_INBOX_TOKEN
+  keycloak_settings_bridge_token:
+    file: ${HAN_SECRETS_DIR:-/run/han-chat/secrets}/KEYCLOAK_SETTINGS_BRIDGE_TOKEN
+  selectel_s3_access_key:
+    file: ${HAN_SECRETS_DIR:-/run/han-chat/secrets}/SELECTEL_S3_ACCESS_KEY
+  selectel_s3_secret_key:
+    file: ${HAN_SECRETS_DIR:-/run/han-chat/secrets}/SELECTEL_S3_SECRET_KEY
+  cursor_hmac_secret:
+    file: ${HAN_SECRETS_DIR:-/run/han-chat/secrets}/CURSOR_HMAC_SECRET

VM1_app/codebase/backend/api-backend/openapi.yaml

@@ -0,0 +1,588 @@
+openapi: 3.1.0
+info:
+  title: HAN Chat API
+  version: 1.0.0
+servers:
+  - url: /
+paths:
+  /health/live:
+    get:
+      operationId: healthLive
+      responses:
+        "200": {description: Process is live}
+  /health/ready:
+    get:
+      operationId: healthReady
+      responses:
+        "200": {description: Ready or partially degraded}
+        "503": {$ref: "#/components/responses/DependencyUnavailable"}
+  /api/v1/public/app-config:
+    get:
+      operationId: getPublicAppConfig
+      responses:
+        "200":
+          description: Public application configuration
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [messages]
+                properties:
+                  messages:
+                    type: object
+                    required: [max_text_length]
+                    properties:
+                      max_text_length: {type: integer, minimum: 1, maximum: 10000}
+  /api/v1/public/content:
+    get:
+      operationId: getPublicContent
+      parameters:
+        - {name: locale, in: query, schema: {type: string, default: ru}}
+      responses:
+        "200": {description: Active UI content}
+  /api/v1/auth/bootstrap:
+    post:
+      operationId: bootstrap
+      security: [{bearerAuth: []}]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: "#/components/schemas/BootstrapRequest"}
+      responses:
+        "200": {description: Local user resolved}
+        "401": {$ref: "#/components/responses/Unauthorized"}
+  /api/v1/consents:
+    post:
+      operationId: recordConsents
+      security: [{bearerAuth: []}]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: "#/components/schemas/ConsentsRequest"}
+      responses:
+        "201": {description: Immutable consent records saved}
+  /api/v1/analytics/session-start:
+    post:
+      operationId: startUxSession
+      security: [{bearerAuth: []}]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: "#/components/schemas/SessionStartRequest"}
+      responses:
+        "201": {description: UX session created}
+  /api/v1/me:
+    get:
+      operationId: getCurrentProfile
+      security: [{bearerAuth: []}]
+      responses:
+        "200": {description: Block profile}
+  /api/v1/me/documents:
+    get:
+      operationId: listDocuments
+      security: [{bearerAuth: []}]
+      responses:
+        "200": {description: Cursor-paginated documents}
+  /api/v1/documents/{document_id}:
+    parameters:
+      - {$ref: "#/components/parameters/DocumentId"}
+    get:
+      operationId: getDocument
+      security: [{bearerAuth: []}]
+      responses:
+        "200": {description: Document metadata}
+        "404": {$ref: "#/components/responses/NotFound"}
+  /api/v1/documents/{document_id}/download-url:
+    parameters:
+      - {$ref: "#/components/parameters/DocumentId"}
+    get:
+      operationId: getDocumentDownloadUrl
+      security: [{bearerAuth: []}]
+      responses:
+        "200": {description: Short-lived presigned GET}
+  /api/v1/dialogs:
+    post:
+      operationId: createDialog
+      security: [{bearerAuth: []}]
+      parameters:
+        - {$ref: "#/components/parameters/IdempotencyKey"}
+      responses:
+        "200": {description: Existing active dialog}
+        "201": {description: New active dialog}
+    get:
+      operationId: listDialogs
+      security: [{bearerAuth: []}]
+      responses:
+        "200": {description: Cursor-paginated dialogs}
+  /api/v1/dialogs/{dialog_id}:
+    parameters:
+      - {$ref: "#/components/parameters/DialogId"}
+    get:
+      operationId: getDialog
+      security: [{bearerAuth: []}]
+      responses:
+        "200": {description: Dialog summary}
+        "404": {$ref: "#/components/responses/NotFound"}
+  /api/v1/dialogs/{dialog_id}/messages:
+    parameters:
+      - {$ref: "#/components/parameters/DialogId"}
+    get:
+      operationId: listMessages
+      security: [{bearerAuth: []}]
+      parameters:
+        - {name: after, in: query, schema: {type: string}}
+        - {name: limit, in: query, schema: {type: integer, minimum: 1, maximum: 100, default: 50}}
+      responses:
+        "200": {description: Message history or polling delta}
+    post:
+      operationId: sendMessage
+      security: [{bearerAuth: []}]
+      parameters:
+        - {$ref: "#/components/parameters/IdempotencyKey"}
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              oneOf:
+                - {$ref: "#/components/schemas/TextMessageRequest"}
+                - {$ref: "#/components/schemas/FileMessageRequest"}
+              discriminator: {propertyName: content_kind}
+      responses:
+        "201": {description: Safety-allowed and delivered message}
+        "422": {description: Message blocked, content redacted}
+        "503": {$ref: "#/components/responses/DependencyUnavailable"}
+  /api/v1/dialogs/{dialog_id}/attachments/init:
+    parameters:
+      - {$ref: "#/components/parameters/DialogId"}
+    post:
+      operationId: initAttachment
+      security: [{bearerAuth: []}]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: "#/components/schemas/AttachmentInitRequest"}
+      responses:
+        "201": {description: Upload metadata and presigned PUT}
+  /api/v1/dialogs/{dialog_id}/attachments/{attachment_id}/complete:
+    parameters:
+      - {$ref: "#/components/parameters/DialogId"}
+      - {$ref: "#/components/parameters/AttachmentId"}
+    post:
+      operationId: completeAttachment
+      security: [{bearerAuth: []}]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: "#/components/schemas/ChecksumRequest"}
+      responses:
+        "200": {description: Upload metadata verified}
+  /api/v1/dialogs/{dialog_id}/attachments/{attachment_id}/download-url:
+    parameters:
+      - {$ref: "#/components/parameters/DialogId"}
+      - {$ref: "#/components/parameters/AttachmentId"}
+    get:
+      operationId: getAttachmentDownloadUrl
+      security: [{bearerAuth: []}]
+      responses:
+        "200": {description: Audited short-lived presigned GET}
+  /api/v1/public/notifications:
+    get:
+      operationId: listGuestNotifications
+      responses:
+        "200":
+          description: Server-sorted active guest campaigns
+          content:
+            application/json:
+              schema: {$ref: "#/components/schemas/NotificationList"}
+  /api/v1/public/notification-types:
+    get:
+      operationId: getNotificationCatalog
+      parameters:
+        - {name: If-None-Match, in: header, schema: {type: string}}
+      responses:
+        "200": {description: Public catalog with ETag}
+        "304": {description: Catalog is unchanged}
+  /api/v1/notifications:
+    get:
+      operationId: listNotifications
+      security: [{bearerAuth: []}]
+      parameters:
+        - {name: place, in: query, required: true, schema: {type: string, enum: [home, center]}}
+      responses:
+        "200":
+          description: Server-sorted personal notifications
+          content:
+            application/json:
+              schema: {$ref: "#/components/schemas/NotificationList"}
+  /api/v1/notifications/counter:
+    get:
+      operationId: getNotificationCounter
+      security: [{bearerAuth: []}]
+      responses:
+        "200":
+          description: Unread count in the center window
+          content:
+            application/json:
+              schema: {$ref: "#/components/schemas/NotificationCounter"}
+  /api/v1/notifications/{notification_id}:
+    parameters:
+      - {$ref: "#/components/parameters/NotificationId"}
+    get:
+      operationId: getNotification
+      security: [{bearerAuth: []}]
+      responses:
+        "200": {description: Active notification detail}
+        "404": {$ref: "#/components/responses/NotFound"}
+  /api/v1/notifications/{notification_id}/read:
+    parameters:
+      - {$ref: "#/components/parameters/NotificationId"}
+    post:
+      operationId: readNotification
+      security: [{bearerAuth: []}]
+      responses:
+        "200": {description: Current notification state}
+        "409": {$ref: "#/components/responses/Conflict"}
+  /api/v1/notifications/{notification_id}/hide:
+    parameters:
+      - {$ref: "#/components/parameters/NotificationId"}
+    post:
+      operationId: hideNotification
+      security: [{bearerAuth: []}]
+      responses:
+        "200": {description: Current notification state}
+        "409": {$ref: "#/components/responses/Conflict"}
+  /api/v1/notifications/{notification_id}/buttons/{button_code}:
+    parameters:
+      - {$ref: "#/components/parameters/NotificationId"}
+      - {name: button_code, in: path, required: true, schema: {type: string}}
+    post:
+      operationId: pressNotificationButton
+      security: [{bearerAuth: []}]
+      responses:
+        "200": {description: Current notification state}
+        "409": {$ref: "#/components/responses/Conflict"}
+        "422": {$ref: "#/components/responses/Unprocessable"}
+  /api/v1/notifications/{notification_id}/cta:
+    parameters:
+      - {$ref: "#/components/parameters/NotificationId"}
+    post:
+      operationId: invokeNotificationCta
+      security: [{bearerAuth: []}]
+      responses:
+        "200": {description: CTA result and current state}
+        "409": {$ref: "#/components/responses/Conflict"}
+  /api/v1/notifications/{notification_id}/documents/{document_id}/download-url:
+    parameters:
+      - {$ref: "#/components/parameters/NotificationId"}
+      - {$ref: "#/components/parameters/DocumentId"}
+    get:
+      operationId: getNotificationDocumentDownloadUrl
+      security: [{bearerAuth: []}]
+      responses:
+        "200": {description: Audited short-lived presigned GET}
+        "404": {$ref: "#/components/responses/NotFound"}
+  /api/v1/uploads/init:
+    post:
+      operationId: initClientUpload
+      security: [{bearerAuth: []}]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: "#/components/schemas/UploadInitRequest"}
+      responses:
+        "201": {description: Upload draft and presigned PUT}
+  /api/v1/uploads/{draft_id}/complete:
+    parameters:
+      - {$ref: "#/components/parameters/DraftId"}
+    post:
+      operationId: completeClientUpload
+      security: [{bearerAuth: []}]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: "#/components/schemas/ChecksumRequest"}
+      responses:
+        "200": {description: Current scan state}
+  /api/v1/uploads:
+    get:
+      operationId: listClientUploads
+      security: [{bearerAuth: []}]
+      parameters:
+        - {name: context_type, in: query, required: true, schema: {type: string, enum: [notification]}}
+        - {name: context_id, in: query, required: true, schema: {type: string, format: uuid}}
+      responses:
+        "200": {description: Upload drafts for context}
+  /api/v1/uploads/{draft_id}:
+    parameters:
+      - {$ref: "#/components/parameters/DraftId"}
+    delete:
+      operationId: deleteClientUpload
+      security: [{bearerAuth: []}]
+      responses:
+        "204": {description: Draft discarded}
+  /internal/notifications/v1/notifications:
+    post:
+      operationId: createNotification
+      security: [{serviceBearer: []}]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: "#/components/schemas/NotificationCreateRequest"}
+      responses:
+        "200": {description: Idempotent duplicate}
+        "201": {description: Notification created}
+        "409": {$ref: "#/components/responses/Conflict"}
+  /internal/notifications/v1/notifications/cancel:
+    post:
+      operationId: cancelNotification
+      security: [{serviceBearer: []}]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: "#/components/schemas/NotificationCancelRequest"}
+      responses:
+        "200": {description: Notification closed or already closed}
+        "404": {$ref: "#/components/responses/NotFound"}
+  /internal/openlines/v1/inbox:
+    post:
+      operationId: applyOpenLinesInbox
+      security: [{serviceBearer: []}]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: "#/components/schemas/OpenLinesInbox"}
+      responses:
+        "200": {description: Duplicate acknowledged}
+        "201": {description: Event applied}
+  /internal/settings/v1/otp:
+    get:
+      operationId: getOtpSettings
+      security: [{serviceBearer: []}]
+      responses:
+        "200":
+          description: Product OTP limits and cache metadata
+          content:
+            application/json:
+              schema: {$ref: "#/components/schemas/OtpSettingsResponse"}
+        "304": {description: Cached settings are still current}
+        "503": {$ref: "#/components/responses/DependencyUnavailable"}
+components:
+  securitySchemes:
+    bearerAuth: {type: http, scheme: bearer, bearerFormat: JWT}
+    serviceBearer: {type: http, scheme: bearer}
+  parameters:
+    DialogId: {name: dialog_id, in: path, required: true, schema: {type: string, format: uuid}}
+    AttachmentId: {name: attachment_id, in: path, required: true, schema: {type: string, format: uuid}}
+    DocumentId: {name: document_id, in: path, required: true, schema: {type: string, format: uuid}}
+    NotificationId: {name: notification_id, in: path, required: true, schema: {type: string, format: uuid}}
+    DraftId: {name: draft_id, in: path, required: true, schema: {type: string, format: uuid}}
+    IdempotencyKey: {name: Idempotency-Key, in: header, required: true, schema: {type: string, minLength: 1, maxLength: 128}}
+  responses:
+    Unauthorized:
+      description: JWT is absent, invalid or expired
+      content: {application/json: {schema: {$ref: "#/components/schemas/ErrorEnvelope"}}}
+    NotFound:
+      description: Resource absent or owned by another user
+      content: {application/json: {schema: {$ref: "#/components/schemas/ErrorEnvelope"}}}
+    DependencyUnavailable:
+      description: Required dependency is unavailable
+      content: {application/json: {schema: {$ref: "#/components/schemas/ErrorEnvelope"}}}
+    Conflict:
+      description: Notification state or idempotency conflict
+      content: {application/json: {schema: {$ref: "#/components/schemas/ErrorEnvelope"}}}
+    Unprocessable:
+      description: Catalog action is not allowed
+      content: {application/json: {schema: {$ref: "#/components/schemas/ErrorEnvelope"}}}
+  schemas:
+    OtpSettingsResponse:
+      type: object
+      additionalProperties: false
+      required:
+        - max_send_attempts_per_24h
+        - min_seconds_between_attempts
+        - max_verify_attempts
+        - code_length
+        - ttl_seconds
+        - sms_order_timeout_ms
+        - version
+        - cache_ttl_seconds
+      properties:
+        max_send_attempts_per_24h: {type: integer, minimum: 1}
+        min_seconds_between_attempts: {type: integer, minimum: 0}
+        max_verify_attempts: {type: integer, minimum: 1}
+        code_length: {type: integer, minimum: 4, maximum: 10}
+        ttl_seconds: {type: integer, minimum: 60, maximum: 900, multipleOf: 60}
+        sms_order_timeout_ms: {type: integer, minimum: 1}
+        version: {type: string, minLength: 1, maxLength: 64}
+        cache_ttl_seconds: {type: integer, minimum: 1}
+    ErrorEnvelope:
+      type: object
+      required: [error]
+      properties:
+        error:
+          type: object
+          required: [code, message, request_id, details]
+          properties:
+            code: {type: string}
+            message: {type: string}
+            request_id: {type: string}
+            details: {type: object}
+    NotificationCounter:
+      type: object
+      additionalProperties: false
+      required: [unread_count]
+      properties:
+        unread_count: {type: integer, minimum: 0}
+    NotificationList:
+      type: object
+      additionalProperties: false
+      required: [items]
+      properties:
+        items:
+          type: array
+          items: {$ref: "#/components/schemas/Notification"}
+    Notification:
+      type: object
+      required: [id, notification_type, notification_datetime, header]
+      properties:
+        id: {type: string, format: uuid}
+        notification_type: {type: string}
+        notification_datetime: {type: string, format: date-time}
+        header: {type: string}
+        text: {type: [string, "null"]}
+        instruction_url: {type: [string, "null"], format: uri}
+        instruction_open_mode: {type: [string, "null"], enum: [new_tab, null]}
+        lifecycle_status: {type: string, enum: [active, closed]}
+        visibility: {type: string, enum: [visible, hidden]}
+        is_read: {type: boolean}
+        details: {type: [object, "null"]}
+    NotificationCreateRequest:
+      type: object
+      additionalProperties: false
+      required: [user_id, notification_type, source, external_id, notification_datetime, header]
+      properties:
+        user_id: {type: string, format: uuid}
+        notification_type: {type: string, maxLength: 32}
+        source: {type: string, maxLength: 32}
+        external_id: {type: string, maxLength: 128}
+        notification_datetime: {type: string, format: date-time}
+        header: {type: string, maxLength: 255}
+        text: {type: [string, "null"], maxLength: 1024}
+        priority_override: {type: [integer, "null"]}
+        date_expired: {type: [string, "null"], format: date-time}
+        price: {type: [number, "null"]}
+        old_price: {type: [number, "null"]}
+        payment_url: {type: [string, "null"], format: uri}
+        chat_message_text: {type: [string, "null"], maxLength: 1024}
+        details: {type: [object, "null"]}
+    NotificationCancelRequest:
+      type: object
+      additionalProperties: false
+      required: [source, external_id, close_reason]
+      properties:
+        source: {type: string}
+        external_id: {type: string}
+        close_reason: {type: string, enum: [cancelled, paid]}
+    UploadInitRequest:
+      type: object
+      additionalProperties: false
+      required: [context_type, context_id, file_name, mime_type, size_bytes]
+      properties:
+        context_type: {const: notification}
+        context_id: {type: string, format: uuid}
+        file_name: {type: string, maxLength: 255}
+        mime_type: {type: string, maxLength: 128}
+        size_bytes: {type: integer, minimum: 1}
+    ConsentChoice:
+      type: object
+      additionalProperties: false
+      required: [accepted, version]
+      properties:
+        accepted: {type: boolean}
+        version: {type: string, maxLength: 64}
+    ConsentSet:
+      type: object
+      additionalProperties: false
+      required: [personal_data, user_agreement, marketing]
+      properties:
+        personal_data: {$ref: "#/components/schemas/ConsentChoice"}
+        user_agreement: {$ref: "#/components/schemas/ConsentChoice"}
+        marketing: {$ref: "#/components/schemas/ConsentChoice"}
+    Device:
+      type: object
+      additionalProperties: false
+      required: [platform, app_version]
+      properties:
+        platform: {type: string, enum: [ios, android, web]}
+        app_version: {type: string, maxLength: 64}
+        device_id: {type: [string, "null"], maxLength: 255}
+    BootstrapRequest:
+      type: object
+      additionalProperties: false
+      required: [consents, device]
+      properties:
+        consents: {$ref: "#/components/schemas/ConsentSet"}
+        device: {$ref: "#/components/schemas/Device"}
+    ConsentsRequest:
+      type: object
+      additionalProperties: false
+      required: [consents]
+      properties: {consents: {$ref: "#/components/schemas/ConsentSet"}}
+    SessionStartRequest:
+      type: object
+      additionalProperties: false
+      required: [start_reason, device]
+      properties:
+        start_reason: {type: string, enum: [first_launch, cold_start, idle_timeout]}
+        device: {$ref: "#/components/schemas/Device"}
+    TextMessageRequest:
+      type: object
+      additionalProperties: false
+      required: [content_kind, text]
+      properties:
+        content_kind: {const: text}
+        text: {type: string, minLength: 1, maxLength: 10000}
+    FileMessageRequest:
+      type: object
+      additionalProperties: false
+      required: [content_kind, attachment_id, checksum]
+      properties:
+        content_kind: {const: file}
+        attachment_id: {type: string, format: uuid}
+        checksum: {type: string, pattern: "^sha256:[0-9a-f]{64}$"}
+    AttachmentInitRequest:
+      type: object
+      additionalProperties: false
+      required: [file_name, mime_type, size_bytes]
+      properties:
+        file_name: {type: string, minLength: 1, maxLength: 255}
+        mime_type: {type: string, minLength: 1, maxLength: 128}
+        size_bytes: {type: integer, minimum: 1}
+    ChecksumRequest:
+      type: object
+      additionalProperties: false
+      required: [checksum]
+      properties:
+        checksum: {type: string, pattern: "^sha256:[0-9a-f]{64}$"}
+    OpenLinesInbox:
+      type: object
+      additionalProperties: false
+      required: [event_id, event_type, external_chat_id, occurred_at]
+      properties:
+        event_id: {type: string, minLength: 1, maxLength: 255}
+        event_type: {type: string, enum: [message.new, dialog.closed]}
+        external_chat_id: {type: string, format: uuid}
+        bitrix_message_id: {type: [string, "null"], maxLength: 255}
+        occurred_at: {type: string, format: date-time}
+        message: {type: [object, "null"]}

VM1_app/codebase/backend/api-backend/pyproject.toml

@@ -0,0 +1,77 @@
+[project]
+name = "han-api-backend"
+version = "0.1.0"
+description = "HAN Chat FastAPI backend"
+requires-python = ">=3.12"
+dependencies = [
+  "alembic>=1.16,<2",
+  "asyncpg>=0.30,<1",
+  "boto3>=1.39,<2",
+  "fastapi>=0.116,<1",
+  "httpx>=0.28,<1",
+  "opentelemetry-api>=1.44,<2",
+  "opentelemetry-exporter-otlp-proto-grpc>=1.44,<2",
+  "opentelemetry-instrumentation-botocore>=0.65b0,<1",
+  "opentelemetry-instrumentation-fastapi>=0.65b0,<1",
+  "opentelemetry-instrumentation-httpx>=0.65b0,<1",
+  "opentelemetry-instrumentation-redis>=0.65b0,<1",
+  "opentelemetry-instrumentation-sqlalchemy>=0.65b0,<1",
+  "opentelemetry-sdk>=1.44,<2",
+  "phonenumbers>=9,<10",
+  "prometheus-client>=0.22,<1",
+  "pydantic-settings>=2.10,<3",
+  "pyyaml>=6,<7",
+  "pyjwt[crypto]>=2.10,<3",
+  "redis>=6,<7",
+  "sqlalchemy[asyncio]>=2.0.41,<3",
+  "structlog>=25,<26",
+  "uvicorn[standard]>=0.35,<1",
+]
+
+[project.optional-dependencies]
+dev = [
+  "aiosqlite>=0.21,<1",
+  "mypy>=1.16,<2",
+  "pytest>=8.4,<9",
+  "pytest-asyncio>=1.0,<2",
+  "ruff>=0.12,<1",
+  "types-boto3-s3>=1.39,<2",
+  "types-PyYAML>=6,<7",
+]
+
+[project.scripts]
+han-api = "app.main:run"
+han-delivery-worker = "app.workers:delivery_main"
+han-safety-worker = "app.workers:safety_main"
+han-cleanup-worker = "app.workers:cleanup_main"
+han-notification-expire-worker = "app.workers:notification_expire_main"
+han-notification-draft-cleanup-worker = "app.workers:notification_draft_cleanup_main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["app"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "ASYNC", "S"]
+ignore = ["S101"]
+
+[tool.mypy]
+python_version = "3.12"
+check_untyped_defs = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+ignore_missing_imports = true
+disable_error_code = ["no-untyped-def", "misc", "arg-type", "assignment"]
+plugins = ["pydantic.mypy", "sqlalchemy.ext.mypy.plugin"]
+exclude = ["alembic/"]

VM1_app/codebase/backend/api-backend/tests/contract/test_clients.py

@@ -0,0 +1,249 @@
+import uuid
+from urllib.parse import parse_qs, urlsplit
+
+import httpx
+import pytest
+
+from app.integrations import (
+    DependencyFailure,
+    OpenLinesClient,
+    S3Client,
+    SafetyClient,
+    fresh_openlines_payload,
+)
+from app.realtime import CHANNEL_PREFIX
+from app.settings import Settings
+
+
+def settings() -> Settings:
+    common = {
+        "APP_ENV": "test",
+        "DATABASE_URL": "postgresql+asyncpg://u:p@localhost/db",
+        "REDIS_URL": "redis://localhost/0",
+        "REDIS_REALTIME_URL": "redis://localhost/1",
+        "KEYCLOAK_PUBLIC_URL": "https://auth.example",
+        "KEYCLOAK_INTERNAL_URL": "http://keycloak:8080",
+        "KEYCLOAK_REALM": "han",
+        "KEYCLOAK_AUDIENCE": "api",
+        "MESSAGE_SAFETY_URL": "http://safety:8080",
+        "MESSAGE_SAFETY_SERVICE_TOKEN": "safety-token",
+        "BITRIX_LOCAL_APP_BASE_URL": "http://bitrix:8080",
+        "BITRIX_LOCAL_APP_INTERNAL_TOKEN": "bitrix-token",
+        "BITRIX_API_INBOX_TOKEN": "inbox-token",
+        "KEYCLOAK_SETTINGS_BRIDGE_TOKEN": "settings-token",
+        "SELECTEL_S3_ENDPOINT_URL": "https://s3.example",
+        "SELECTEL_S3_BUCKET_DOCUMENTS": "documents",
+        "SELECTEL_S3_BUCKET_ATTACHMENTS": "attachments",
+        "SELECTEL_S3_BUCKET_QUARANTINE": "quarantine",
+        "SELECTEL_S3_ACCESS_KEY": "access",
+        "SELECTEL_S3_SECRET_KEY": "secret",
+        "CURSOR_HMAC_SECRET": "x" * 32,
+    }
+    return Settings.model_validate(common)
+
+
+def test_realtime_channel_matches_redis_acl_namespace() -> None:
+    assert CHANNEL_PREFIX == "han:rt:dialog:"
+
+
+@pytest.mark.asyncio
+async def test_s3_presigned_urls_use_virtual_hosted_addressing() -> None:
+    s3 = S3Client(settings())
+
+    put_url = await s3.presign_put("quarantine/users/u/file.pdf", "application/pdf", 600)
+    get_url = await s3.presign_get("attachments", "dialogs/d/file.pdf")
+
+    assert urlsplit(put_url).netloc == "quarantine.s3.example"
+    assert urlsplit(put_url).path == "/quarantine/users/u/file.pdf"
+    assert urlsplit(get_url).netloc == "attachments.s3.example"
+    assert urlsplit(get_url).path == "/dialogs/d/file.pdf"
+    assert parse_qs(urlsplit(put_url).query)["X-Amz-Algorithm"] == ["AWS4-HMAC-SHA256"]
+    assert parse_qs(urlsplit(get_url).query)["X-Amz-Algorithm"] == ["AWS4-HMAC-SHA256"]
+
+
+@pytest.mark.asyncio
+async def test_safety_contract_status_and_service_token() -> None:
+    task_id = str(uuid.uuid4())
+
+    async def handler(request: httpx.Request) -> httpx.Response:
+        assert request.headers["X-Service-Token"] == "safety-token"
+        assert request.url.path == "/internal/safety/v2/messages/check"
+        return httpx.Response(
+            202,
+            headers={
+                "Location": f"/internal/safety/v2/messages/tasks/{task_id}",
+                "Retry-After": "2",
+            },
+            json={
+                "verdict": "pending",
+                "processing_mode": "standard",
+                "config_version": 1,
+                "rules_version": "2026-01-01",
+                "task_id": task_id,
+                "poll_after_ms": 2000,
+                "expires_at": "2026-08-06T12:00:00Z",
+            },
+        )
+
+    async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+        result = await SafetyClient(settings(), http).check(
+            {"message_id": str(uuid.uuid4()), "content_kind": "text", "text": "hello"},
+            "request-1",
+        )
+    assert result["_status"] == 202
+    assert result["_location"] == f"/internal/safety/v2/messages/tasks/{task_id}"
+
+
+@pytest.mark.asyncio
+async def test_safety_file_body_uses_exact_attachment_schema() -> None:
+    attachment_id = uuid.uuid4()
+
+    async def handler(request: httpx.Request) -> httpx.Response:
+        body = __import__("json").loads(request.content)
+        assert body["attachment"] == {
+            "attachment_id": str(attachment_id),
+            "quarantine_object_key": "quarantine/users/u/file",
+            "quarantine_version_id": "version-1",
+            "quarantine_etag": '"etag-1"',
+            "mime_type": "application/pdf",
+            "size_bytes": 42,
+            "checksum": "sha256:" + "a" * 64,
+        }
+        assert "file" not in body
+        return httpx.Response(
+            200,
+            json={
+                "verdict": "allow",
+                "processing_mode": "standard",
+                "config_version": 1,
+                "rules_version": "2026-01-01",
+                "rule_id": "safety.all_checks_passed",
+            },
+        )
+
+    payload = {
+        "message_id": str(uuid.uuid4()),
+        "content_kind": "file",
+        "text": "",
+        "attachment": {
+            "attachment_id": str(attachment_id),
+            "quarantine_object_key": "quarantine/users/u/file",
+            "quarantine_version_id": "version-1",
+            "quarantine_etag": '"etag-1"',
+            "mime_type": "application/pdf",
+            "size_bytes": 42,
+            "checksum": "sha256:" + "a" * 64,
+        },
+    }
+    async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+        await SafetyClient(settings(), http).check(payload, "request-1")
+
+
+@pytest.mark.asyncio
+async def test_safety_auth_failure_is_dependency_failure() -> None:
+    async def handler(_: httpx.Request) -> httpx.Response:
+        return httpx.Response(401, json={"error": {"code": "service_unauthorized"}})
+
+    async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+        with pytest.raises(DependencyFailure):
+            await SafetyClient(settings(), http).check(
+                {"message_id": str(uuid.uuid4()), "content_kind": "text", "text": "hello"},
+                "request-1",
+            )
+
+
+@pytest.mark.asyncio
+async def test_safety_poll_uses_location_and_rejects_untrusted_location() -> None:
+    task_id = str(uuid.uuid4())
+
+    async def handler(request: httpx.Request) -> httpx.Response:
+        assert request.url.path == f"/internal/safety/v2/messages/tasks/{task_id}"
+        return httpx.Response(
+            403,
+            json={
+                "verdict": "deny",
+                "processing_mode": "standard",
+                "config_version": 2,
+                "rules_version": "2026-08-06",
+                "rule_id": "file.malware_detected",
+                "reason_code": "message_blocked",
+            },
+        )
+
+    async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+        client = SafetyClient(settings(), http)
+        result = await client.poll(
+            f"/internal/safety/v2/messages/tasks/{task_id}", "request-1"
+        )
+        assert result["_status"] == 403
+        with pytest.raises(DependencyFailure, match="invalid_safety_location"):
+            await client.poll("https://attacker.example/task-1", "request-1")
+
+
+@pytest.mark.asyncio
+async def test_safety_fails_closed_on_malformed_success() -> None:
+    async def handler(_: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, json={"verdict": "allow"})
+
+    async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+        with pytest.raises(DependencyFailure, match="invalid_safety_response"):
+            await SafetyClient(settings(), http).check(
+                {"message_id": str(uuid.uuid4()), "content_kind": "text", "text": "hello"},
+                "request-1",
+            )
+
+
+@pytest.mark.asyncio
+async def test_openlines_contract_uses_bearer_and_idempotency() -> None:
+    message_id = uuid.uuid4()
+
+    async def handler(request: httpx.Request) -> httpx.Response:
+        assert request.headers["Authorization"] == "Bearer bitrix-token"
+        assert request.headers["Idempotency-Key"] == str(message_id)
+        assert request.url.path == "/internal/openlines/v1/messages"
+        return httpx.Response(201, json={"status": "accepted"})
+
+    async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+        result = await OpenLinesClient(settings(), http).send(
+            message_id, {"message_id": str(message_id)}, "request-1"
+        )
+    assert result["status"] == "accepted"
+
+
+@pytest.mark.asyncio
+async def test_openlines_payload_gets_fresh_download_url_without_storage_fields() -> None:
+    class FakeS3:
+        calls = 0
+
+        async def presign_get(self, bucket: str, key: str, ttl: int = 300) -> str:
+            self.calls += 1
+            return f"https://download.example/{bucket}/{key}?generation={self.calls}"
+
+    payload = {
+        "message_id": str(uuid.uuid4()),
+        "external_chat_id": str(uuid.uuid4()),
+        "occurred_at": "2026-07-10T12:00:00+00:00",
+        "user": {"id": str(uuid.uuid4()), "display_name": "+79990000000"},
+        "message": {
+            "content_kind": "file",
+            "text": "",
+            "files": [{
+                "attachment_id": str(uuid.uuid4()),
+                "name": "file.pdf",
+                "mime_type": "application/pdf",
+                "size_bytes": 42,
+                "_storage_bucket": "attachments",
+                "_object_key": "dialogs/d/file",
+            }],
+        },
+    }
+    s3 = FakeS3()
+    first = await fresh_openlines_payload(payload, s3)  # type: ignore[arg-type]
+    second = await fresh_openlines_payload(payload, s3)  # type: ignore[arg-type]
+    assert first["occurred_at"] and first["user"]["id"]
+    assert first["message"]["content_kind"] == "file"
+    assert (
+        first["message"]["files"][0]["download_url"]
+        != second["message"]["files"][0]["download_url"]
+    )
+    assert all(not key.startswith("_") for key in first["message"]["files"][0])

VM1_app/codebase/backend/api-backend/tests/contract/test_openapi.py

@@ -0,0 +1,226 @@
+import asyncio
+import base64
+import json
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+import yaml
+from alembic.config import Config
+from alembic.script import ScriptDirectory
+from pydantic import SecretStr
+
+from app.main import (
+    EXPECTED_API_DB_REVISION,
+    app,
+    otp_settings,
+    refresh_jwks_cache,
+    websocket_token,
+)
+from app.services import SettingsSnapshot
+
+EXPECTED_PATHS = {
+    "/health/live",
+    "/health/ready",
+    "/api/v1/public/app-config",
+    "/api/v1/public/content",
+    "/api/v1/public/notifications",
+    "/api/v1/public/notification-types",
+    "/api/v1/auth/bootstrap",
+    "/api/v1/consents",
+    "/api/v1/analytics/session-start",
+    "/api/v1/me",
+    "/api/v1/me/documents",
+    "/api/v1/notifications",
+    "/api/v1/notifications/counter",
+    "/api/v1/notifications/{notification_id}",
+    "/api/v1/notifications/{notification_id}/read",
+    "/api/v1/notifications/{notification_id}/hide",
+    "/api/v1/notifications/{notification_id}/buttons/{button_code}",
+    "/api/v1/notifications/{notification_id}/cta",
+    "/api/v1/notifications/{notification_id}/documents/{document_id}/download-url",
+    "/api/v1/uploads/init",
+    "/api/v1/uploads/{draft_id}/complete",
+    "/api/v1/uploads",
+    "/api/v1/uploads/{draft_id}",
+    "/api/v1/documents/{document_id}",
+    "/api/v1/documents/{document_id}/download-url",
+    "/api/v1/dialogs",
+    "/api/v1/dialogs/{dialog_id}",
+    "/api/v1/dialogs/{dialog_id}/messages",
+    "/api/v1/dialogs/{dialog_id}/attachments/init",
+    "/api/v1/dialogs/{dialog_id}/attachments/{attachment_id}/complete",
+    "/api/v1/dialogs/{dialog_id}/attachments/{attachment_id}/download-url",
+    "/internal/openlines/v1/inbox",
+    "/internal/notifications/v1/notifications",
+    "/internal/notifications/v1/notifications/cancel",
+    "/internal/settings/v1/otp",
+}
+
+
+def test_openapi_31_contains_all_http_contracts() -> None:
+    schema = app.openapi()
+    assert schema["openapi"].startswith("3.1.")
+    assert EXPECTED_PATHS <= schema["paths"].keys()
+    assert all(not path.startswith("/internal/safety") for path in schema["paths"])
+    committed = yaml.safe_load(Path("openapi.yaml").read_text(encoding="utf-8"))
+    assert committed["openapi"] == "3.1.0"
+    assert committed["paths"].keys() == schema["paths"].keys()
+
+
+def test_readiness_expected_revision_matches_alembic_head() -> None:
+    scripts = ScriptDirectory.from_config(Config("alembic.ini"))
+    assert EXPECTED_API_DB_REVISION == scripts.get_current_head()
+
+
+@pytest.mark.asyncio
+async def test_jwks_refresh_loop_recovers_after_startup_race(monkeypatch) -> None:
+    class FakeJWKS:
+        has_keys = False
+        refresh_calls = 0
+
+        async def refresh(self) -> None:
+            self.refresh_calls += 1
+            self.has_keys = True
+
+    jwks = FakeJWKS()
+    test_app = SimpleNamespace(
+        state=SimpleNamespace(
+            jwks=jwks,
+            settings=SimpleNamespace(jwks_cache_ttl_seconds=300),
+        )
+    )
+    delays: list[int] = []
+
+    async def fake_sleep(delay: int) -> None:
+        delays.append(delay)
+        if len(delays) > 1:
+            raise asyncio.CancelledError
+
+    monkeypatch.setattr("app.main.asyncio.sleep", fake_sleep)
+
+    with pytest.raises(asyncio.CancelledError):
+        await refresh_jwks_cache(test_app)
+
+    assert jwks.refresh_calls == 1
+    assert delays == [5, 300]
+
+
+def test_websocket_route_is_registered() -> None:
+    assert any(getattr(route, "path", None) == "/api/v1/realtime" for route in app.routes)
+
+
+def test_notification_http_methods_match_contract() -> None:
+    paths = app.openapi()["paths"]
+    expected = {
+        "/api/v1/public/notifications": {"get"},
+        "/api/v1/public/notification-types": {"get"},
+        "/api/v1/notifications": {"get"},
+        "/api/v1/notifications/counter": {"get"},
+        "/api/v1/notifications/{notification_id}": {"get"},
+        "/api/v1/notifications/{notification_id}/read": {"post"},
+        "/api/v1/notifications/{notification_id}/hide": {"post"},
+        "/api/v1/notifications/{notification_id}/buttons/{button_code}": {"post"},
+        "/api/v1/notifications/{notification_id}/cta": {"post"},
+        (
+            "/api/v1/notifications/{notification_id}/documents/"
+            "{document_id}/download-url"
+        ): {"get"},
+        "/api/v1/uploads/init": {"post"},
+        "/api/v1/uploads/{draft_id}/complete": {"post"},
+        "/api/v1/uploads": {"get"},
+        "/api/v1/uploads/{draft_id}": {"delete"},
+        "/internal/notifications/v1/notifications": {"post"},
+        "/internal/notifications/v1/notifications/cancel": {"post"},
+    }
+    for path, methods in expected.items():
+        assert methods <= paths[path].keys()
+
+
+def test_websocket_accepts_canonical_base64url_jwt_protocol() -> None:
+    jwt = "header.payload.signature"
+    encoded = base64.urlsafe_b64encode(jwt.encode()).decode().rstrip("=")
+    websocket = SimpleNamespace(
+        headers={"sec-websocket-protocol": f"han-chat-v1, han.jwt.{encoded}"},
+        query_params={},
+    )
+    assert websocket_token(websocket) == (jwt, f"han.jwt.{encoded}")
+
+
+def test_committed_openapi_server_does_not_double_api_prefix() -> None:
+    committed = yaml.safe_load(Path("openapi.yaml").read_text(encoding="utf-8"))
+    assert committed["servers"] == [{"url": "/"}]
+
+
+def test_public_config_contract_exposes_message_length() -> None:
+    committed = yaml.safe_load(Path("openapi.yaml").read_text(encoding="utf-8"))
+    response = committed["paths"]["/api/v1/public/app-config"]["get"]["responses"]["200"]
+    messages = response["content"]["application/json"]["schema"]["properties"]["messages"]
+
+    assert messages["required"] == ["max_text_length"]
+    assert messages["properties"]["max_text_length"]["maximum"] == 10_000
+
+
+def test_otp_settings_contract_is_strict_and_complete() -> None:
+    generated = app.openapi()
+    response = generated["paths"]["/internal/settings/v1/otp"]["get"]["responses"]["200"]
+    schema_ref = response["content"]["application/json"]["schema"]["$ref"]
+    schema = generated["components"]["schemas"][schema_ref.rsplit("/", 1)[-1]]
+
+    assert set(schema["required"]) == {
+        "max_send_attempts_per_24h",
+        "min_seconds_between_attempts",
+        "max_verify_attempts",
+        "code_length",
+        "ttl_seconds",
+        "sms_order_timeout_ms",
+        "version",
+        "cache_ttl_seconds",
+    }
+    assert schema["additionalProperties"] is False
+    assert schema["properties"]["code_length"] == {
+        "type": "integer",
+        "maximum": 10.0,
+        "minimum": 4.0,
+        "title": "Code Length",
+    }
+    assert schema["properties"]["ttl_seconds"]["multipleOf"] == 60
+
+
+async def test_otp_settings_returns_runtime_values_and_supports_etag() -> None:
+    request = SimpleNamespace(
+        headers={"Authorization": "Bearer bridge-token"},
+        app=SimpleNamespace(
+            state=SimpleNamespace(
+                settings=SimpleNamespace(
+                    keycloak_settings_bridge_token=SecretStr("bridge-token")
+                )
+            )
+        ),
+    )
+    settings = SettingsSnapshot(
+        {
+            "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",
+        },
+        "settings-version",
+    )
+
+    response = await otp_settings(request, settings)
+    assert json.loads(response.body) == {
+        "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": "settings-version",
+        "cache_ttl_seconds": 60,
+    }
+
+    cached = await otp_settings(request, settings, response.headers["etag"])
+    assert cached.status_code == 304

VM1_app/codebase/backend/api-backend/tests/unit/test_audit_context.py

@@ -0,0 +1,153 @@
+import hashlib
+import uuid
+from types import SimpleNamespace
+
+import pytest
+from starlette.requests import Request
+
+from app.main import (
+    app,
+    client_ip,
+    request_trace_id,
+    required_user_audit_context,
+    user_agent_hash,
+)
+from app.schemas import Device
+from app.services import AuditContext, DomainError, audit, device_snapshot
+
+
+def request(
+    *,
+    peer: str = "172.18.0.5",
+    forwarded: str | None = None,
+    traceparent: str | None = None,
+    user_agent: str | None = None,
+    ux_session_id: str | None = None,
+    trusted: str = "172.16.0.0/12",
+) -> Request:
+    headers: list[tuple[bytes, bytes]] = []
+    for name, value in (
+        ("x-forwarded-for", forwarded),
+        ("traceparent", traceparent),
+        ("user-agent", user_agent),
+        ("x-ux-session-id", ux_session_id),
+    ):
+        if value is not None:
+            headers.append((name.encode(), value.encode()))
+    settings = SimpleNamespace(trusted_proxy_cidrs=trusted)
+    app = SimpleNamespace(state=SimpleNamespace(settings=settings))
+    return Request(
+        {
+            "type": "http",
+            "method": "GET",
+            "path": "/",
+            "headers": headers,
+            "client": (peer, 12345),
+            "server": ("test", 443),
+            "scheme": "https",
+            "query_string": b"",
+            "app": app,
+        }
+    )
+
+
+def test_client_ip_only_trusts_forwarded_header_from_configured_proxy() -> None:
+    assert client_ip(request(forwarded="203.0.113.10")) == "203.0.113.10"
+    assert (
+        client_ip(request(peer="198.51.100.7", forwarded="203.0.113.10"))
+        == "198.51.100.7"
+    )
+    assert client_ip(request(peer="not-an-ip")) is None
+
+
+def test_trace_id_uses_valid_w3c_header_and_generates_fallback() -> None:
+    trace_id = "1" * 32
+    assert request_trace_id(request(traceparent=f"00-{trace_id}-{'2' * 16}-01")) == trace_id
+    fallback = request_trace_id(request(traceparent="invalid"))
+    assert len(fallback) == 32
+    int(fallback, 16)
+
+
+def test_user_agent_is_hashed_and_device_parameters_are_preserved() -> None:
+    agent = "Example Browser/1.0"
+    assert user_agent_hash(request(user_agent=agent)) == hashlib.sha256(agent.encode()).hexdigest()
+    snapshot = device_snapshot(
+        Device(platform="web", app_version="1.2.3", device_id="raw-device-id")
+    )
+    assert snapshot == {
+        "platform": "web",
+        "app_version": "1.2.3",
+        "device_id": "raw-device-id",
+    }
+
+
+def test_audit_copies_request_context_and_bounded_metadata() -> None:
+    session_id = uuid.uuid4()
+    user_id = uuid.uuid4()
+    context = AuditContext(
+        request_id=str(uuid.uuid4()),
+        trace_id="a" * 32,
+        ux_session_id=session_id,
+        user_agent_hash="b" * 64,
+        client_ip="203.0.113.10",
+    )
+
+    event = audit(
+        "dialog.created",
+        context,
+        user_id,
+        "dialog",
+        uuid.uuid4(),
+        metadata={"status": "open"},
+    )
+
+    assert event.user_id == user_id
+    assert event.ux_session_id == session_id
+    assert event.trace_id == "a" * 32
+    assert event.user_agent_hash == "b" * 64
+    assert event.metadata_json == {"status": "open"}
+    assert event.outcome == "success"
+    assert not hasattr(event, "ip")
+
+    failed = audit("message.failed", context, user_id, outcome="failed")
+    assert failed.outcome == "failed"
+
+
+def test_post_session_routes_publish_required_ux_header_in_openapi() -> None:
+    operation = app.openapi()["paths"]["/api/v1/dialogs"]["post"]
+    ux_header = next(
+        parameter
+        for parameter in operation["parameters"]
+        if parameter["name"] == "X-Ux-Session-Id"
+    )
+    assert ux_header["in"] == "header"
+    assert ux_header["required"] is True
+
+
+@pytest.mark.asyncio
+async def test_user_audit_context_requires_existing_owned_session() -> None:
+    session_id = uuid.uuid4()
+    user = SimpleNamespace(id=uuid.uuid4())
+    incoming = request(
+        forwarded="203.0.113.10",
+        ux_session_id=str(session_id),
+        user_agent="Example Browser/1.0",
+    )
+    incoming.state.request_id = str(uuid.uuid4())
+    incoming.state.trace_id = "c" * 32
+    incoming.state.user_agent_hash = user_agent_hash(incoming)
+
+    class Db:
+        async def scalar(self, _query):
+            return session_id
+
+    context = await required_user_audit_context(incoming, Db(), user, str(session_id))
+    assert context.ux_session_id == session_id
+    assert context.client_ip == "203.0.113.10"
+
+    missing = request(forwarded="203.0.113.10")
+    missing.state.request_id = str(uuid.uuid4())
+    missing.state.trace_id = "d" * 32
+    missing.state.user_agent_hash = None
+    with pytest.raises(DomainError, match="X-Ux-Session-Id is required"):
+        await required_user_audit_context(missing, Db(), user, "")

VM1_app/codebase/backend/api-backend/tests/unit/test_cli_settings.py

@@ -0,0 +1,78 @@
+from pathlib import Path
+
+import pytest
+
+from app.cli.seed_settings import load_seed
+from app.services import REQUIRED_SETTINGS
+
+
+def test_production_like_seed_contains_all_mandatory_settings() -> None:
+    path = Path(__file__).resolve().parents[3] / "deployment/app-settings.production-like.yaml"
+    rows = load_seed(path)
+
+    assert REQUIRED_SETTINGS <= {row["setting_key"] for row in rows}
+    assert all(row["record_status"] == "A" for row in rows)
+    values = {row["setting_key"]: row["setting_value"] for row in rows}
+    assert values["otp.phone.code_length"] == "6"
+    assert values["otp.phone.ttl_seconds"] == "60"
+    assert values["otp.phone.sms_order_timeout_ms"] == "3000"
+    assert values["chat.message.max_length"] == "4000"
+
+
+def test_seed_rejects_invalid_typed_value(tmp_path: Path) -> None:
+    path = tmp_path / "settings.yaml"
+    path.write_text(
+        "schema_version: 1\nsettings:\n"
+        "  bad.integer: {type: integer, value: nope, public: false}\n",
+        encoding="utf-8",
+    )
+
+    with pytest.raises(ValueError, match="integer value expected"):
+        load_seed(path)
+
+
+@pytest.mark.parametrize(
+    ("key", "value", "message"),
+    [
+        ("otp.phone.code_length", 3, "between 4 and 10"),
+        ("otp.phone.ttl_seconds", 61, "divisible by 60"),
+        ("otp.phone.sms_order_timeout_ms", 0, "must be positive"),
+    ],
+)
+def test_seed_rejects_invalid_otp_settings(
+    tmp_path: Path, key: str, value: int, message: str
+) -> None:
+    path = tmp_path / "settings.yaml"
+    path.write_text(
+        "schema_version: 1\nsettings:\n"
+        f"  {key}: {{type: integer, value: {value}, public: false}}\n",
+        encoding="utf-8",
+    )
+
+    with pytest.raises(ValueError, match=message):
+        load_seed(path)
+
+
+def test_seed_rejects_public_otp_setting(tmp_path: Path) -> None:
+    path = tmp_path / "settings.yaml"
+    path.write_text(
+        "schema_version: 1\nsettings:\n"
+        "  otp.phone.code_length: {type: integer, value: 6, public: true}\n",
+        encoding="utf-8",
+    )
+
+    with pytest.raises(ValueError, match="must not be public"):
+        load_seed(path)
+
+
+@pytest.mark.parametrize("value", [0, 10001])
+def test_seed_rejects_invalid_chat_message_max_length(tmp_path: Path, value: int) -> None:
+    path = tmp_path / "settings.yaml"
+    path.write_text(
+        "schema_version: 1\nsettings:\n"
+        f"  chat.message.max_length: {{type: integer, value: {value}, public: true}}\n",
+        encoding="utf-8",
+    )
+
+    with pytest.raises(ValueError, match="value must be between 1 and 10000"):
+        load_seed(path)

VM1_app/codebase/backend/api-backend/tests/unit/test_domain.py

@@ -0,0 +1,104 @@
+import uuid
+
+import pytest
+from pydantic import TypeAdapter, ValidationError
+
+from app.auth import canonical_phone
+from app.integrations import CircuitBreaker, RateLimiter
+from app.postgres import asyncpg_dsn
+from app.schemas import (
+    FileMessageRequest,
+    MessageRequest,
+    TextMessageRequest,
+    canonical_fingerprint,
+    decode_cursor,
+    encode_cursor,
+)
+from app.services import MESSAGE_SAFETY_REPLIES, safety_reply_message
+
+
+def test_asyncpg_receives_libpq_dsn_without_sqlalchemy_driver() -> None:
+    url = (
+        "postgresql+asyncpg://user:password@db:5433/han_chat"
+        "?sslmode=verify-full&sslrootcert=/run/secrets/pg-ca.pem"
+    )
+
+    assert asyncpg_dsn(url) == url.replace("postgresql+asyncpg://", "postgresql://", 1)
+
+
+def test_phone_claim_priority_and_e164_validation() -> None:
+    claims = {"phone_number": "+74999591007", "preferred_username": "+12025550123"}
+    assert canonical_phone(claims) == "+74999591007"
+    assert canonical_phone({"phone_number": "89999999999"}) is None
+
+
+def test_message_discriminated_union() -> None:
+    adapter = TypeAdapter(MessageRequest)
+    assert isinstance(
+        adapter.validate_python({"content_kind": "text", "text": "Здравствуйте"}),
+        TextMessageRequest,
+    )
+    assert isinstance(
+        adapter.validate_python(
+            {
+                "content_kind": "file",
+                "attachment_id": str(uuid.uuid4()),
+                "checksum": "sha256:" + "a" * 64,
+            }
+        ),
+        FileMessageRequest,
+    )
+    with pytest.raises(ValidationError):
+        adapter.validate_python(
+            {"content_kind": "text", "text": "", "attachment_id": str(uuid.uuid4())}
+        )
+    longest = adapter.validate_python({"content_kind": "text", "text": "а" * 10_000})
+    assert len(longest.text) == 10_000
+    with pytest.raises(ValidationError):
+        adapter.validate_python({"content_kind": "text", "text": "а" * 10_001})
+
+
+def test_message_safety_business_replies_are_content_specific() -> None:
+    assert "переформулировать" in MESSAGE_SAFETY_REPLIES["text"]
+    assert "документ" in MESSAGE_SAFETY_REPLIES["file"]
+    reply = safety_reply_message(uuid.uuid4(), "text")
+    assert reply.sender_type == "company"
+    assert reply.safety_status == "allowed"
+    assert reply.delivery_status == "delivered"
+
+
+def test_fingerprint_is_canonical_and_user_scoped() -> None:
+    user = uuid.uuid4()
+    first = canonical_fingerprint("post", "/dialogs/{id}", {"id": "1"}, {"b": 2, "a": 1}, user)
+    second = canonical_fingerprint("POST", "/dialogs/{id}", {"id": "1"}, {"a": 1, "b": 2}, user)
+    assert first == second
+    assert first != canonical_fingerprint(
+        "POST", "/dialogs/{id}", {"id": "1"}, {"a": 1, "b": 2}, uuid.uuid4()
+    )
+
+
+def test_cursor_roundtrip_and_tamper_rejection() -> None:
+    secret = b"test-secret" * 4
+    cursor = encode_cursor({"id": str(uuid.uuid4()), "created_at": "2026-01-01"}, secret)
+    assert decode_cursor(cursor, secret)["created_at"] == "2026-01-01"
+    with pytest.raises(ValueError, match="invalid cursor"):
+        decode_cursor(cursor[:-2] + "aa", secret)
+
+
+def test_rate_limit_keys_do_not_expose_identity() -> None:
+    key = RateLimiter.key("ip", "203.0.113.7", "public", 60)
+    assert "203.0.113.7" not in key
+    assert key.startswith("han:api:rl:ip:")
+
+
+def test_circuit_breaker_opens_and_half_opens(monkeypatch: pytest.MonkeyPatch) -> None:
+    clock = [10.0]
+    monkeypatch.setattr("app.integrations.time.monotonic", lambda: clock[0])
+    breaker = CircuitBreaker(2, 30)
+    breaker.failure()
+    breaker.failure()
+    assert not breaker.allow()
+    clock[0] = 41.0
+    assert breaker.allow()
+    breaker.success()
+    assert breaker.allow()

VM1_app/codebase/backend/api-backend/tests/unit/test_logging_security.py

@@ -0,0 +1,31 @@
+from app.logging_security import REDACTED, redact_event, sanitize_text
+
+
+def test_redacts_sensitive_fields_recursively() -> None:
+    event = {
+        "authorization": "Bearer top-secret",
+        "nested": {
+            "database_url": "postgresql://user:password@db/app",
+            "safe": "kept",
+        },
+    }
+
+    redacted = redact_event(None, "info", event)
+
+    assert redacted["authorization"] == REDACTED
+    assert redacted["nested"]["database_url"] == REDACTED
+    assert redacted["nested"]["safe"] == "kept"
+
+
+def test_redacts_credentials_embedded_in_text() -> None:
+    value = (
+        "POST https://callback-user:callback-password@example.test/cb"
+        "?token=query-secret Authorization=Bearer header-secret"
+    )
+
+    redacted = sanitize_text(value)
+
+    assert "callback-password" not in redacted
+    assert "query-secret" not in redacted
+    assert "header-secret" not in redacted
+    assert redacted.count(REDACTED) == 3

VM1_app/codebase/backend/api-backend/tests/unit/test_notifications.py

@@ -0,0 +1,589 @@
+import ast
+import json
+import uuid
+from collections.abc import AsyncGenerator
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any, cast
+from unittest.mock import AsyncMock, Mock
+
+import pytest
+from pydantic import ValidationError
+
+from app.db import Document
+from app.notification_models import (
+    ClientUploadDraft,
+    Notification,
+    NotificationButton,
+    NotificationDocument,
+    NotificationSource,
+    NotificationType,
+    uuid7,
+)
+from app.notification_schemas import NotificationCreateRequest
+from app.notification_service import (
+    _apply_hidden_ttl,
+    apply_read_or_hide,
+    authenticate_source,
+    catalog,
+    create_notification,
+    document_download,
+    expire_notifications,
+    fingerprint,
+    invoke_cta_state,
+    press_button,
+    source_token_hash,
+    validate_create,
+)
+from app.realtime import USER_CHANNEL_PREFIX, RealtimeFanout
+from app.services import AuditContext, DomainError, SettingsSnapshot
+from app.workers import notification_draft_cleanup_once
+
+
+def test_notification_migration_does_not_prepare_multiple_sql_commands() -> None:
+    migration = Path("alembic/versions/0008_notification_center_v1.py")
+    tree = ast.parse(migration.read_text(encoding="utf-8"))
+    for call in (node for node in ast.walk(tree) if isinstance(node, ast.Call)):
+        if (
+            isinstance(call.func, ast.Attribute)
+            and call.func.attr == "execute"
+            and call.args
+            and isinstance(call.args[0], ast.Call)
+            and isinstance(call.args[0].func, ast.Attribute)
+            and call.args[0].func.attr == "text"
+            and call.args[0].args
+            and isinstance(call.args[0].args[0], ast.Constant)
+            and isinstance(call.args[0].args[0].value, str)
+        ):
+            assert call.args[0].args[0].value.count(";") <= 1
+
+
+def create_body(**changes: object) -> NotificationCreateRequest:
+    values: dict[str, object] = {
+        "user_id": uuid.uuid4(),
+        "notification_type": "news",
+        "source": "producer_test",
+        "external_id": "event-1",
+        "notification_datetime": "2026-07-27T12:00:00Z",
+        "header": "Новость",
+        "details": {"details_text": "Текст"},
+    }
+    values.update(changes)
+    return NotificationCreateRequest.model_validate(values)
+
+
+def context() -> AuditContext:
+    return AuditContext("request-1", "trace-1", None, None, None)
+
+
+def snapshot(default_ttl: int = 3) -> SettingsSnapshot:
+    return SettingsSnapshot(
+        {
+            "notification.hidden.default_ttl_days": str(default_ttl),
+            "notification.center.max_items": "15",
+        },
+        "v1",
+    )
+
+
+def notification(**changes: object) -> Notification:
+    values: dict[str, object] = {
+        "id": uuid.uuid4(),
+        "user_id": uuid.uuid4(),
+        "notification_type": "news",
+        "source": "producer_test",
+        "external_id": "event-1",
+        "request_fingerprint": "a" * 64,
+        "notification_datetime": datetime.now(UTC),
+        "header": "Header",
+        "lifecycle_status": "active",
+        "visibility": "visible",
+        "is_read": False,
+        "date_expired": None,
+        "close_reason": None,
+        "closed_at": None,
+    }
+    values.update(changes)
+    return Notification(**values)
+
+
+def kind(**changes: object) -> NotificationType:
+    values: dict[str, object] = {
+        "id": uuid.uuid4(),
+        "code": "news",
+        "contour": "P",
+        "priority": 4,
+        "countable": True,
+        "label": "Новость",
+        "color_token": "info",
+        "icon_code": "news",
+        "cta_text": "Подробнее",
+        "cta_action": "open_detail",
+        "cta_sets_hidden": False,
+        "cta_close_reason": None,
+        "button_primary_code": "gotit",
+        "button_secondary_code": None,
+        "hidden_ttl_days": None,
+        "documents_allowed": False,
+        "hide_on_document_download": False,
+        "required_detail_blocks": [],
+    }
+    values.update(changes)
+    return NotificationType(**values)
+
+
+class ScalarRows:
+    def __init__(self, rows: list[object]) -> None:
+        self.rows = rows
+
+    def scalars(self) -> "ScalarRows":
+        return self
+
+    def all(self) -> list[object]:
+        return self.rows
+
+
+def test_uuid7_has_rfc_version_variant_and_embedded_timestamp(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    timestamp_ns = 1_722_340_800_123_000_000
+    monkeypatch.setattr("app.notification_models.time.time_ns", lambda: timestamp_ns)
+    monkeypatch.setattr("app.notification_models.secrets.randbits", lambda bits: (1 << bits) - 1)
+
+    value = uuid7()
+
+    assert value.version == 7
+    assert value.variant == uuid.RFC_4122
+    assert value.int >> 80 == timestamp_ns // 1_000_000
+
+
+def test_fingerprint_is_canonical_stable_and_sensitive_to_body() -> None:
+    first = create_body()
+    same = NotificationCreateRequest.model_validate(first.model_dump(mode="json"))
+    changed = create_body(header="Другая новость")
+
+    assert fingerprint(first) == fingerprint(same)
+    assert fingerprint(first) != fingerprint(changed)
+    assert len(fingerprint(first)) == 64
+
+
+def test_create_schema_rejects_read_only_or_unknown_detail_blocks() -> None:
+    with pytest.raises(ValidationError) as pending:
+        create_body(details={"details_text": "Text", "pending_documents": []})
+    with pytest.raises(ValidationError) as unknown:
+        create_body(details={"details_text": "Text", "invented": True})
+
+    assert "pending_documents" in str(pending.value)
+    assert "invented" in str(unknown.value)
+
+
+def test_catalog_driven_create_validation_covers_required_and_forbidden_fields() -> None:
+    action = SimpleNamespace(required_instance_fields=["details"])
+    docs_kind = kind(
+        required_detail_blocks=["documents"],
+        documents_allowed=True,
+        button_primary_code="gotit",
+    )
+
+    with pytest.raises(DomainError) as error:
+        validate_create(create_body(details={"details_text": "No documents"}), docs_kind, action)
+
+    assert error.value.code == "validation_error"
+    assert error.value.details["fields"] == ["details.documents"]
+
+    with pytest.raises(DomainError) as forbidden:
+        validate_create(
+            create_body(
+                details={"details_text": "Text"},
+                payment_url="https://pay.example/order",
+            ),
+            kind(),
+            action,
+        )
+    assert forbidden.value.details["fields"] == ["payment_url"]
+
+
+@pytest.mark.asyncio
+async def test_duplicate_create_returns_existing_only_for_matching_fingerprint(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    body = create_body()
+    existing = notification(request_fingerprint=fingerprint(body))
+    session = SimpleNamespace(
+        scalar=AsyncMock(return_value=existing),
+        add=Mock(),
+        commit=AsyncMock(),
+    )
+    dto = {"id": str(existing.id)}
+    monkeypatch.setattr(
+        "app.notification_service.notification_dto", AsyncMock(return_value=dto)
+    )
+
+    result, status = await create_notification(
+        session,
+        body,
+        SimpleNamespace(code="producer_test"),
+        SimpleNamespace(),
+        SimpleNamespace(),
+        context(),
+    )
+    assert (result, status) == (dto, 200)
+
+    existing.request_fingerprint = "0" * 64
+    with pytest.raises(DomainError) as conflict:
+        await create_notification(
+            session,
+            body,
+            SimpleNamespace(code="producer_test"),
+            SimpleNamespace(),
+            SimpleNamespace(),
+            context(),
+        )
+    assert conflict.value.code == "notification_conflict"
+    assert conflict.value.status == 409
+    assert conflict.value.details == {"notification_id": str(existing.id)}
+
+
+def test_hidden_ttl_preserves_existing_expiry_and_uses_type_or_default(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    now = datetime(2026, 7, 27, 12, tzinfo=UTC)
+    monkeypatch.setattr("app.notification_service.datetime", SimpleNamespace(now=lambda tz: now))
+    existing = now + timedelta(hours=2)
+    with_expiry = notification(date_expired=existing)
+    type_specific = notification()
+    defaulted = notification()
+
+    _apply_hidden_ttl(with_expiry, kind(hidden_ttl_days=9), snapshot())
+    _apply_hidden_ttl(type_specific, kind(hidden_ttl_days=5), snapshot())
+    _apply_hidden_ttl(defaulted, kind(hidden_ttl_days=None), snapshot(3))
+
+    assert with_expiry.date_expired == existing
+    assert type_specific.date_expired == now + timedelta(days=5)
+    assert defaulted.date_expired == now + timedelta(days=3)
+    assert {with_expiry.visibility, type_specific.visibility, defaulted.visibility} == {"hidden"}
+
+
+@pytest.mark.asyncio
+async def test_hide_applies_ttl_without_marking_read(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    item = notification()
+    monkeypatch.setattr(
+        "app.notification_service.owned_notification",
+        AsyncMock(return_value=(item, kind(hidden_ttl_days=2))),
+    )
+    monkeypatch.setattr("app.notification_service.unread_count", AsyncMock(return_value=1))
+    session = SimpleNamespace(add=Mock(), commit=AsyncMock())
+    fanout = SimpleNamespace(publish_user=AsyncMock())
+
+    result = await apply_read_or_hide(
+        session,
+        item.user_id,
+        item.id,
+        "hide",
+        snapshot(),
+        fanout,
+        context(),
+    )
+
+    assert result["visibility"] == "hidden"
+    assert result["is_read"] is False
+    assert item.date_expired is not None
+    event = fanout.publish_user.await_args.args[1]
+    assert event["date_expired"] == item.date_expired
+
+
+@pytest.mark.asyncio
+async def test_cta_and_buttons_follow_catalog_lifecycle(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    item = notification()
+    cta_kind = kind(cta_action="open_detail")
+    monkeypatch.setattr(
+        "app.notification_service.owned_notification",
+        AsyncMock(return_value=(item, cta_kind)),
+    )
+    monkeypatch.setattr("app.notification_service.unread_count", AsyncMock(return_value=0))
+    session = SimpleNamespace(add=Mock(), commit=AsyncMock(), scalar=AsyncMock())
+    fanout = SimpleNamespace(publish_user=AsyncMock())
+
+    _, _, cta_result = await invoke_cta_state(
+        session, item.user_id, item.id, snapshot(), fanout, context()
+    )
+    assert item.is_read is True
+    assert item.visibility == "visible"
+    assert item.lifecycle_status == "active"
+    assert cta_result["result"]["action"] == "open_detail"
+
+    button = NotificationButton(
+        id=uuid.uuid4(),
+        code="done",
+        label="Готово",
+        sets_hidden=False,
+        applies_hidden_ttl=False,
+        close_reason="user_done",
+        submits_documents=False,
+    )
+    session.scalar.return_value = button
+    cta_kind.button_primary_code = "done"
+    result = await press_button(
+        session, item.user_id, item.id, "done", snapshot(), fanout, context()
+    )
+    assert result["lifecycle_status"] == "closed"
+    assert result["close_reason"] == "user_done"
+    assert item.closed_at is not None
+
+
+@pytest.mark.asyncio
+async def test_first_download_of_any_document_hides_once_and_preserves_expiry(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    expires = datetime.now(UTC) + timedelta(hours=1)
+    item = notification(date_expired=expires)
+    download_kind = kind(
+        code="docs_ready",
+        documents_allowed=True,
+        hide_on_document_download=True,
+    )
+    link = NotificationDocument(
+        id=uuid.uuid4(),
+        notification_id=item.id,
+        document_id=uuid.uuid4(),
+        sort_order=0,
+        download_url_issued_at=None,
+    )
+    document = Document(
+        id=link.document_id,
+        user_id=item.user_id,
+        name="result.pdf",
+        mime_type="application/pdf",
+        size_bytes=42,
+        checksum_sha256="a" * 64,
+        storage_bucket="documents",
+        object_key="documents/result.pdf",
+        sent_at=datetime.now(UTC),
+    )
+    row_result = SimpleNamespace(one_or_none=lambda: (link, document))
+    session = SimpleNamespace(
+        execute=AsyncMock(return_value=row_result),
+        scalar=AsyncMock(return_value=0),
+        add=Mock(),
+        commit=AsyncMock(),
+    )
+    monkeypatch.setattr(
+        "app.notification_service.owned_notification",
+        AsyncMock(return_value=(item, download_kind)),
+    )
+    monkeypatch.setattr("app.notification_service.unread_count", AsyncMock(return_value=0))
+    fanout = SimpleNamespace(publish_user=AsyncMock())
+    s3 = SimpleNamespace(presign_get=AsyncMock(return_value="https://download.example/file"))
+
+    result = await document_download(
+        session,
+        item.user_id,
+        item.id,
+        document.id,
+        snapshot(),
+        s3,
+        fanout,
+        context(),
+    )
+
+    assert result["download_url"] == "https://download.example/file"
+    assert item.is_read is True
+    assert item.visibility == "hidden"
+    assert item.date_expired == expires
+    assert link.download_url_issued_at is not None
+    fanout.publish_user.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_source_token_hash_and_producer_authentication() -> None:
+    value = "producer-secret"
+    source = NotificationSource(
+        id=uuid.uuid4(),
+        code="producer_test",
+        description="test",
+        token_hash=source_token_hash(value),
+        token_rotated_at=None,
+        record_status="A",
+    )
+    session = SimpleNamespace(execute=AsyncMock(return_value=ScalarRows([source])))
+
+    assert await authenticate_source(session, f"Bearer {value}") is source
+    assert source.token_hash != value
+    with pytest.raises(DomainError) as invalid:
+        await authenticate_source(session, "Bearer wrong")
+    assert (invalid.value.code, invalid.value.status) == ("unauthorized", 401)
+
+
+@pytest.mark.asyncio
+async def test_catalog_dto_is_sorted_and_contains_only_public_behavior() -> None:
+    types = [
+        kind(code="news", contour="P", priority=4, button_primary_code="gotit"),
+        kind(
+            code="urgent",
+            contour="P",
+            priority=1,
+            label="Срочно",
+            button_primary_code="done",
+            button_secondary_code="later",
+        ),
+    ]
+    buttons = [
+        NotificationButton(id=uuid.uuid4(), code="done", label="Готово"),
+        NotificationButton(id=uuid.uuid4(), code="later", label="Позже"),
+        NotificationButton(id=uuid.uuid4(), code="gotit", label="Понятно"),
+    ]
+    session = SimpleNamespace(
+        execute=AsyncMock(side_effect=[ScalarRows(types), ScalarRows(buttons)])
+    )
+
+    result = await catalog(session)
+
+    assert [item["code"] for item in result] == ["urgent", "news"]
+    assert result[0]["button_primary"] == {"code": "done", "label": "Готово"}
+    assert result[0]["button_secondary"] == {"code": "later", "label": "Позже"}
+    assert not {
+        "hidden_ttl_days",
+        "cta_sets_hidden",
+        "cta_close_reason",
+        "required_detail_blocks",
+    } & result[0].keys()
+    button_statement = session.execute.await_args_list[1].args[0]
+    assert "notification_buttons.record_status" in str(button_statement)
+
+
+@pytest.mark.asyncio
+async def test_realtime_uses_per_user_channel_and_strips_internal_identity() -> None:
+    user_id = uuid.uuid4()
+
+    class PubSub:
+        def __init__(self) -> None:
+            self.channels: tuple[str, ...] = ()
+
+        async def subscribe(self, *channels: str) -> None:
+            self.channels = channels
+
+        async def get_message(self, **_kwargs: object) -> dict[str, str]:
+            return {
+                "data": json.dumps(
+                    {
+                        "type": "notification.updated",
+                        "_user_id": str(user_id),
+                        "notification_id": str(uuid.uuid4()),
+                    }
+                )
+            }
+
+        async def unsubscribe(self, *_channels: str) -> None:
+            return None
+
+        async def aclose(self) -> None:
+            return None
+
+    pubsub = PubSub()
+    redis = SimpleNamespace(publish=AsyncMock(), pubsub=lambda: pubsub)
+    fanout = RealtimeFanout(redis)
+
+    await fanout.publish_user(user_id, {"type": "notification.created"})
+    channel, payload = redis.publish.await_args.args
+    assert channel == USER_CHANNEL_PREFIX + str(user_id)
+    assert json.loads(payload)["_user_id"] == str(user_id)
+
+    stream = cast(
+        AsyncGenerator[dict[str, Any], None],
+        fanout.events(set(), user_id, notifications=True),
+    )
+    event = await anext(stream)
+    await stream.aclose()
+    assert pubsub.channels == (USER_CHANNEL_PREFIX + str(user_id),)
+    assert event["type"] == "notification.updated"
+    assert "_user_id" not in event
+
+
+@pytest.mark.asyncio
+async def test_expire_job_is_locked_set_based_and_commits() -> None:
+    session = SimpleNamespace(
+        scalar=AsyncMock(return_value=True),
+        execute=AsyncMock(
+            side_effect=[
+                SimpleNamespace(rowcount=3),
+                SimpleNamespace(rowcount=2),
+            ]
+        ),
+        add=Mock(),
+        commit=AsyncMock(),
+    )
+
+    assert await expire_notifications(session) == (3, 2)
+    assert session.execute.await_count == 2
+    personal_sql = str(session.execute.await_args_list[0].args[0])
+    guest_sql = str(session.execute.await_args_list[1].args[0])
+    assert "lifecycle_status" in personal_sql and "date_expired" in personal_sql
+    assert "lifecycle_status" in guest_sql and "date_expired" in guest_sql
+    session.commit.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_draft_cleanup_deletes_objects_but_keeps_submitted_object(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    abandoned = ClientUploadDraft(
+        id=uuid.uuid4(),
+        user_id=uuid.uuid4(),
+        context_type="notification",
+        context_id=uuid.uuid4(),
+        original_file_name="a.pdf",
+        safe_file_name="a.pdf",
+        mime_type="application/pdf",
+        size_bytes=1,
+        storage_bucket="quarantine",
+        object_key="q/a",
+        quarantine_object_key="q/a",
+        state="draft",
+    )
+    submitted = ClientUploadDraft(
+        id=uuid.uuid4(),
+        user_id=abandoned.user_id,
+        context_type="notification",
+        context_id=abandoned.context_id,
+        original_file_name="b.pdf",
+        safe_file_name="b.pdf",
+        mime_type="application/pdf",
+        size_bytes=1,
+        storage_bucket="attachments",
+        object_key="a/b",
+        quarantine_object_key=None,
+        state="submitted",
+    )
+    session = SimpleNamespace(
+        execute=AsyncMock(side_effect=[ScalarRows([abandoned, submitted]), None, None]),
+        commit=AsyncMock(),
+    )
+
+    class Sessions:
+        async def __aenter__(self) -> object:
+            return session
+
+        async def __aexit__(self, *_args: object) -> None:
+            return None
+
+    db = SimpleNamespace(sessions=lambda: Sessions())
+    s3 = SimpleNamespace(delete_quarantine=AsyncMock(), delete=AsyncMock())
+    monkeypatch.setattr(
+        "app.workers.load_settings",
+        AsyncMock(
+            return_value=SettingsSnapshot(
+                {"notification.upload_draft.ttl_days": "7"}, "v1"
+            )
+        ),
+    )
+
+    assert await notification_draft_cleanup_once(db, s3) == 2
+    s3.delete_quarantine.assert_awaited_once_with("q/a")
+    s3.delete.assert_not_awaited()
+    assert session.execute.await_count == 3
+    session.commit.assert_awaited_once()

VM1_app/codebase/backend/api-backend/tests/unit/test_telemetry.py

@@ -0,0 +1,25 @@
+from opentelemetry.sdk.trace import TracerProvider
+
+from app import telemetry
+
+
+def test_telemetry_is_fail_open_without_endpoint(monkeypatch) -> None:
+    monkeypatch.delenv("OTEL_EXPORTER_OTLP_ENDPOINT", raising=False)
+    monkeypatch.setattr(telemetry, "_runtime", None)
+
+    assert telemetry.init_telemetry("test-service") is None
+
+
+def test_structlog_processor_adds_active_trace_context_only() -> None:
+    provider = TracerProvider()
+    tracer = provider.get_tracer("test")
+    event = {"event": "safe", "request_id": "request-1"}
+
+    with tracer.start_as_current_span("operation"):
+        result = telemetry.add_trace_context(None, "info", event)
+
+    assert result["event"] == "safe"
+    assert result["request_id"] == "request-1"
+    assert len(result["trace_id"]) == 32
+    assert len(result["span_id"]) == 16
+    assert set(result) == {"event", "request_id", "trace_id", "span_id"}