# Proposal: Срез 0 — сквозной скелет (контракт v1.0, окружение разработки, CI-шаблон)

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

## Why

Три сервисных репозитория развёрнуты из шаблона команды, но между ними ещё нет ничего общего: контракт результата
распознавания помечен «черновик», сообщения NATS описаны только таблицей в `03-architecture.md`, локально поднять
PostgreSQL + NATS + MinIO + ИС Сканирование нечем, CI-конфигурации у шаблона нет. Без этого Срез 1 (справочники) и
Срез 2 (парсер) нельзя начать параллельно в трёх репозиториях: каждый сервис придумает свой формат сообщений и своё
окружение. Срез 0 фиксирует общие точки один раз и проверяет их end-to-end на пустых обработчиках.

## What Changes

- **Контракт распознавания v1.0** (`docs/contracts/`):
  - `recognition-result.schema.json` — снять пометку «черновик», `schema_version` = `"1.0"`, добавить код ошибки
    `NOT_IMPLEMENTED` (сервис не поддерживает тип документа в текущей версии); структура документов (`osvDocument`,
    `statementDocument`) не меняется — она уточняется в Срезе 2/3 версией 1.x (additive) или 2.0 (breaking).
  - **Новое:** `recognition-request.schema.json` — тело сообщения `recognition.{tabular|image}.request`
    (`job_id`, `file_id`, `pipeline`, `file_type`, `original_name`, `s3 {bucket, key}`, `reply_deadline`, `attempt`).
  - **Новое:** `recognition-result-message.schema.json` — тело сообщения `recognition.result` (конверт: `job_id`,
    `file_id`, `status`, `error`, `service`, `result_s3 {bucket, key}`, `result_schema_version`, `raw_s3_key`, `metrics`).
    Поле `group_schema` в конверт **не входит** — ядро берёт его из `documents[].group_schema` файла результата
    (правка таблицы в `03-architecture.md`).
  - Правила заголовков NATS: `Nats-Msg-Id` запроса = `<job_id>:<attempt>`, результата = `result:<job_id>:<attempt>`.
  - Примеры сообщений и результата — `docs/contracts/examples/` (валидируются в CI сервисов).
- **Окружение разработки** `docs/dev/`:
  - `docker-compose.yml` workspace-уровня: PostgreSQL 15, NATS 2.10 с JetStream, MinIO (+ init-контейнер: бакет
    `arm-ka`), эмулятор ИС Сканирование (образ `scan-gateway`, команда эмулятора, общая папка горячих каталогов),
    сервисы `arm-core`, `tabular-parser`, `scan-gateway` (профиль `services`; сборка из соседних каталогов workspace).
  - `.env.example` c переменными шаблона (`OPENBAO__*`, `DEBUG`) и флагами разработки (`AUTH_DEV_ISSUER`, `SCAN_EMULATOR`).
  - `README.md`: как поднять инфраструктуру, как запустить сервисы из venv против compose, как прогнать интеграционные тесты.
- **CI-шаблон** `docs/dev/ci/`: workflow Gitea Actions для Python-сервиса (ruff, mypy, pytest с сервисами PostgreSQL/NATS/MinIO,
  проверка идентичности вендоренного контракта с `docs/contracts`, сборка образа; для arm-core — плюс миграции с нуля и
  назад, `check_dbml_vs_orm.py`, job для `web/`: biome, tsc, rsbuild build). Checkout `arm-ka-fixtures` в `../fixtures`
  (или `ARM_KA_FIXTURES`) — через секрет с правом чтения.
- **Документы контекста:** `03-architecture.md` — раздел «Соглашения шаблона команды», раскладка `api/src/`, схема `dkb`,
  один бакет S3, конверт результата без `group_schema`; `00-workspace-layout.md` — worktree-workspace `.wt/<срез>/`;
  `06-test-data.md` §6 — справочники для seed продукта (план счетов, правила элиминации, права) живут в `arm-core/api/seed/`,
  в `fixtures/directories/` остаются только тестовые справочники (ЮЛ и ГК группы «Русский бисквит», Срез 1);
  `09-delivery-plan.md` — решение по пакету контрактов (без общего пакета, см. design); `07-open-questions.md` — новые OQ.
- **Сверка макета** (задача B kickoff): `10-user-journey.md`, `mockup/INDEX.md`, новые снимки `mockup/screens/`,
  `scripts/mockup_crawl_extra.py`; расхождения — в `07-open-questions.md`.

## Capabilities

### New Capabilities
- `recognition-contract`: контракт обмена между ядром и сервисами распознавания — тела сообщений NATS, файл результата
  в S3, правила версионирования и идемпотентности.
- `dev-environment`: воспроизводимое локальное окружение workspace (PostgreSQL, NATS JetStream, MinIO, эмулятор ИС
  Сканирование, три сервиса) с одним `docker compose up`.
- `ci-template`: обязательный набор проверок CI для сервисных репозиториев и порядок их выполнения.

### Modified Capabilities
<!-- openspec/specs пуст — изменяемых capability нет -->

## Impact

- Читают контракт: `arm-core` (outbox публикует запрос, consumer читает конверт результата и файл результата),
  `tabular-parser` и `scan-gateway` (читают запрос, пишут результат и конверт). Каждый сервис вендорит копию схем в
  `api/contracts/` и проверяет идентичность с `docs/contracts` в CI.
- Таблицы DBML v5.13, которые опираются на контракт: `recognition_job` (`request_msg_id`, `result_msg_id`,
  `schema_version`, `result_schema_version`, `service_name/version`, `result_s3_object_id`, `metrics`, `group_schema`,
  `error_code`), `s3_object` (`bucket_role`, `bucket`, `key`, `created_by`), `stored_file` (`file_type`). Новых полей нет.
- Внешние зависимости: Docker/Compose у разработчика; Gitea Actions с раннером, умеющим `services:` и `docker build`
  (вопрос к человеку — см. design «Open Questions»).

## Non-goals

- Финальная структура `osvDocument`/`statementDocument` (уточняется в Срезах 2–3 по реальным файлам; здесь только
  фиксируется версия и правила эволюции).
- Контракт `ex-payload-v1.schema.json` (Срез 7).
- Production-значения инфраструктуры банка (адреса NATS/S3/OpenBao, nkeys) — compose только для разработки.
- Публикация общего python-пакета контрактов (решено: не делать, см. design D-1).
- Какие-либо экраны фронта.