arm-scan-gateway/openspec/changes/slice-0-skeleton/proposal.md

Proposal: Срез 0 — скелет scan-gateway

Срез: 0 «Скелет» (../docs/context/09-delivery-plan.md). Репозиторий: scan-gateway. Issue: RSHB/arm-scan-gateway#1. Родительский change: ../docs/openspec/changes/slice-0-skeleton (контракт v1.0, compose, проверки качества). Соседние: ../arm-core/openspec/changes/slice-0-skeleton, ../tabular-parser/openspec/changes/slice-0-skeleton.

Why

Репозиторий — копия каркаса arm-core с фронтом и БД, тогда как по DECISION-4 это stateless-адаптер внешней ИС Сканирование. Самая рискованная часть адаптера — не разбор JSON (Срез 3), а обмен через горячие папки с таймаутом и без доступа к БД: положить файл, дождаться ответа, не потерять задание — причём на NATS без JetStream. Срез 0 строит этот конвейер и эмулятор ИС Сканирование, чтобы он работал в compose без доступа к банковской системе.

What Changes

• Вырезать из шаблона (список — CLAUDE.md, «Соглашения шаблона»): web/, setup/.npmrc и npm-шаги setup/setup.sh; из app.py — mount SPA, CORS, импорт raisa_fastapi_protected_api; db/, models/, repositories/, alembic/, alembic.ini; настройка OPENBAO.DATABASE; зависимости asyncpg, SQLAlchemy, alembic, argon2-cffi, raisa_fastapi_protected_api; шаблонный README.md. SMB остаётся (smbprotocol, OPENBAO.SMB, сессия в lifespan).
• Инструменты: api/pyproject.toml (ruff, mypy), requirements-dev.txt = -r requirements.txt + инструменты, Dockerfile (python:3.11-slim; строка убрана из .gitignore), Makefile с общими целями + venv, emulator, .env.example, .env.test; Settings читает ENV_FILE; SERVICE_NAME = "scan-gateway".
• Контракт: вендоренные схемы api/contracts/ + pydantic-модели src/contract/; тест идентичности с ../docs/contracts.
• Горячие папки src/gateway/: протокол HotFolder (put(name, data), poll(job_id) -> list[AnswerFile] | None, healthy()) с двумя реализациями — LocalHotFolder (каталог; dev и тесты) и SmbHotFolder (smbclient шаблона; прод). Имена подкаталогов настраиваются (SCAN_INPUT_DIR = "Input", SCAN_OUTPUT_DIR = "Output", SCAN_TMP_DIR = "Tmp"); файл кладётся как <job_id>_<original_name>; временный файл атомарной записи (.part) лежит в служебном каталоге <корень>/<SCAN_TMP_DIR>/ рядом с Input/Output (на той же шаре/ФС) и переименовывается в Input, так что в Input недописанных файлов не бывает (OQ-79). ИС кладёт все распознанные документы задания одновременно в <output>/<job_id>/ — по одному *.json на документ (OQ-78); poll возвращает все *.json каталога по возрастанию имени, когда набор готов: есть хотя бы один *.json, а набор имён и размеров не менялся SCAN_SETTLE_SECONDS (2).
• Воркер src/core/worker.py (NATS без JetStream): подписка на recognition.image.request в queue group scan-gateway; по получении — сразу ack processing в recognition.result; до SCAN_MAX_INFLIGHT (4) заданий параллельно: S3 uploads/… → горячая папка → опрос каждые SCAN_POLL_SECONDS (5) до min(reply_deadline, now + SCAN_TIMEOUT_SECONDS=300) → склейка всех *.json ответа в один сырой ответ {"job_id", "files": [{"name", "response", "parse_error"}]} в S3 raw/{job_id}.json → нормализатор → results/{file_id}/{job_id}/result.json → конверт результата (raw_s3_key заполнен). Таймаут → error.code = TIMEOUT. Process-local множество job_id в работе: повторный запрос получает ack и не создаёт второй файл в горячей папке.
• Нормализатор как интерфейс src/normalizer/: протокол Normalizer(merged) -> documents | error, вход — склеенный ответ; в Срезе 0 — NullNormalizer. Успех файла ИС — error.code == "" (поле error не null: у реального успешного ответа error = {"code": "", "message": ""}); ошибка — непустой error.code (FILE_READ_ERROR, INVALID_FORMAT, INVALID_DOCUMENT, RECOGNITION_FAILED, UNKNOWN_ERROR) либо parse_error (файл не разобран как JSON). Если ошибочны все файлы — результат error с кодом первого ошибочного файла по имени (для parse_error — INVALID_FORMAT), каждый ошибочный файл — строка <имя>: <код>: <сообщение> в metrics.warnings. Есть хотя бы один успешный файл → NOT_IMPLEMENTED (Срез 3 реализует §11), ошибочные файлы — в metrics.warnings так же.
• Эмулятор ИС Сканирование src/scan_emulator/ (python -m src.scan_emulator): следит за Input/, через SCAN_EMULATOR_DELAY (2 с) кладёт в Output/<uuid>/ набор ответов: все SCAN_FIXTURES_DIR/<name>.json и <name>_*.json (<name> — имя без uuid и расширения; не префикс <name>*) под именами <uuid>.json и <uuid>_<suffix>.json, с file_uid = <uuid> (aep_3.pdf → <uuid>.json + <uuid>_ofr.json, aep_6.pdf → один файл, aep_8.pdf → <uuid>_form4.json); набор появляется в Output/<uuid>/ атомарно целиком (временный каталог + переименование каталога). Для неизвестных имён — один ответ Content AI с error.code = INVALID_DOCUMENT. Запускается тем же образом в compose (scan-emulator).
• Ошибки транспорта → результат: запрос не по схеме → SCHEMA_MISMATCH; S3 не читается → FILE_READ_ERROR; горячая папка недоступна → RECOGNITION_FAILED; ответ ИС не JSON (после готовности набора) → parse_error файла, при ошибочности всех файлов — INVALID_FORMAT; исключение → UNKNOWN_ERROR.
• Healthcheck дополняется полями nats и hotfolder (ok/down).
• Проверки качества вместо CI: make check и make check-full по ../docs/dev/checks.md.

Capabilities

New Capabilities

• image-recognition-gateway: адаптер ИС Сканирование — приём и подтверждение задания из NATS без JetStream, обмен файлами через горячие папки с таймаутом, сохранение сырого ответа, результат по контракту v1.0.
• scan-emulator: эмулятор ИС Сканирование для разработки и тестов, воспроизводящий протокол горячих папок на фикстурах ../fixtures/ocr.

Modified Capabilities

Impact

• Таблицы DBML: сервис не пишет в БД. Косвенно: recognition_job ядра получает status = processing (started_at), затем status, error_code (TIMEOUT, NOT_IMPLEMENTED, коды Content AI), service_name = scan-gateway; external_task_id не передаётся (у ИС Сканирование идентификатор = наш job_id в имени файла). Сырой ответ raw/{job_id}.json в БД не регистрируется (v5.13 п. 5).
• Правила: §11 — только как контракт нормализатора; §9.4 — статусы задания; OQ-13/14/15 — допущения в коде нормализатора (Срез 3).
• Зависимости: удаляются БД/фронт; остаётся smbprotocol; добавляются ruff, mypy, pytest*, jsonschema.
• Внешние системы: NATS без JetStream, MinIO/S3, SMB-шара ИС Сканирование (прод) / локальный каталог (dev).

Non-goals

• Нормализация ответа Content AI в statementDocument (§11, OQ-13, OQ-14) — Срез 3.
• PNG/JPG — транспорт не различает типы, но проверяется только PDF (пары в fixtures/ocr).
• Повторы OCR (max_attempts = 1 по OQ-15), периодический heartbeat processing.
• Реальная SMB-шара в тестах — SmbHotFolder покрыт только unit-тестами с подменой smbclient.
• Конфигурации CI.