docs: change retry-recognition-and-edit-osv-header, README и CLAUDE.md — DBML v5.21 (ревью #161)

Дельта data-model переименована на v5.21, пакет — только файлы в ERROR,
tasks — ссылки на docs PR #157 и задачи ревью; config.yaml — DBML v5.21.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

CLAUDE.md

@@ -175,7 +175,7 @@
 - NATS subjects и схема ключей S3 — `../docs/context/03-architecture.md`.
 
 ## Правила репозитория
-- ORM 1:1 с `../docs/model/data-model-v5.19.dbml` (текущая версия; миграции `0001_dbml_v5_13` + `0002_dbml_v5_14` + `0003_dbml_v5_15` + `0004_dbml_v5_16` + `0005_dbml_v5_17` + `0006_dbml_v5_18` + `0007_dbml_v5_19`); `api/scripts/check_dbml_vs_orm.py` (`make dbml-check`, входит в `check-full`) — обязательная проверка.
+- ORM 1:1 с `../docs/model/data-model-v5.21.dbml` (текущая версия; миграции `0001_dbml_v5_13` + `0002_dbml_v5_14` + `0003_dbml_v5_15` + `0004_dbml_v5_16` + `0005_dbml_v5_17` + `0006_dbml_v5_18` + `0007_dbml_v5_19` + `0008_dbml_v5_20` + `0009_dbml_v5_21`); `api/scripts/check_dbml_vs_orm.py` (`make dbml-check`, входит в `check-full`) — обязательная проверка.
 - Алгоритмы — только из `../docs/context/05-domain-rules.md`; номер § — в docstring.
 - Вычисляемые объекты консолидации — `api/src/domain/`, без ORM-таблиц.
 - Фронт: пользователь слаб во фронте — для TS/React изменений делай ревью сам и объясняй решения в PR.

README.md

@@ -1115,7 +1115,7 @@ email без учёта регистра проверяет только сер
 | `make test` | юнит-тесты: `pytest -m "not integration"`, Docker не нужен |
 | `make test-integration` | интеграционные тесты: `pytest -m "integration and not e2e"`, нужны PostgreSQL (и NATS) |
 | `make e2e` | сквозной прогон загрузки ОСВ: `pytest -m e2e`, нужны compose и tabular-parser из профиля `services` (без него — skip) |
-| `make dbml-check` | сверка ORM с `../docs/model/data-model-v5.19.dbml` |
+| `make dbml-check` | сверка ORM с `../docs/model/data-model-v5.21.dbml` |
 | `make migration-cycle` | миграции на временной БД: `upgrade head` → `downgrade base` → `upgrade head`, пустой autogenerate |
 | `make check` | быстрая проверка без Docker: `lint` + `test` |
 | `make docker-build` | сборка образа: `docker build -t arm-core .` |
@@ -1167,7 +1167,7 @@ queue group `arm-core`, подписчики группы получают со
 
 ### Проверка ORM и DBML
 
-Модель данных — `../docs/model/data-model-v5.19.dbml`. ORM обязана совпадать с ней один в один:
+Модель данных — `../docs/model/data-model-v5.21.dbml`. ORM обязана совпадать с ней один в один:
 
 ```bash
 make dbml-check     # пустой вывод и код 0 — совпадение; расхождения печатаются построчно
@@ -1190,7 +1190,7 @@ make migration-cycle                          # проверить цикл upgr
 ```
 api/
   run_server.py        точка входа (uvicorn; хост и порт — из настроек)
-  alembic/             миграции (0001_dbml_v5_13.py — модель v5.13, 0002_dbml_v5_14.py — v5.14, 0003_dbml_v5_15.py — v5.15, 0004_dbml_v5_16.py — v5.16, 0005_dbml_v5_17.py — v5.17, 0006_dbml_v5_18.py — v5.18, 0007_dbml_v5_19.py — v5.19)
+  alembic/             миграции (0001_dbml_v5_13.py — модель v5.13, 0002_dbml_v5_14.py — v5.14, 0003_dbml_v5_15.py — v5.15, 0004_dbml_v5_16.py — v5.16, 0005_dbml_v5_17.py — v5.17, 0006_dbml_v5_18.py — v5.18, 0007_dbml_v5_19.py — v5.19, 0008_dbml_v5_20.py — v5.20, 0009_dbml_v5_21.py — v5.21)
   rules/               statement_lines.yaml — справочник имён строк форм ББ/ОФР по редакциям (словарь проверок §7 — в пакете arm_statements)
   seed/core/           справочники продукта (роли, права, филиалы, план счетов, правила элиминации, чек-лист)
   seed/dev/            dev-данные: филиалы и пользователи по ролям
@@ -1274,7 +1274,7 @@ Dockerfile             только для локального compose
 - [`../docs/dev/README.md`](../docs/dev/README.md) — окружение разработки (compose), порты, типичные проблемы;
 - [`../docs/context/03-architecture.md`](../docs/context/03-architecture.md) — архитектура, соглашения шаблона, NATS и S3;
 - [`../docs/context/04-data-model-guide.md`](../docs/context/04-data-model-guide.md) и
-  [`../docs/model/data-model-v5.19.dbml`](../docs/model/data-model-v5.19.dbml) — модель данных;
+  [`../docs/model/data-model-v5.21.dbml`](../docs/model/data-model-v5.21.dbml) — модель данных;
 - [`../docs/context/05-domain-rules.md`](../docs/context/05-domain-rules.md) — алгоритмы предметной области;
 - [`../docs/context/07-open-questions.md`](../docs/context/07-open-questions.md) — открытые вопросы;
 - [`../docs/context/09-delivery-plan.md`](../docs/context/09-delivery-plan.md) — план срезов;

openspec/changes/retry-recognition-and-edit-osv-header/proposal.md

@@ -2,7 +2,7 @@
 
 ## Why
 
-AURORA-1442 (`some.xml`): после TIMEOUT/NO_ACK аналитик не может повторить обработку уже загруженного файла;
+AURORA-1442: после TIMEOUT/NO_ACK аналитик не может повторить обработку уже загруженного файла;
 ошибочный период или счёт ОСВ нельзя уточнить через API. DBML v5.20 и решение OQ-161 от 21.10.2026 уже задают
 хранение исходных значений рядом с исправленными и правила снятия подтверждения.
 

openspec/changes/retry-recognition-and-edit-osv-header/specs/data-model/spec.md

@@ -1,6 +1,10 @@
+## RENAMED Requirements
+- FROM: `### Requirement: Схема БД равна DBML v5.19`
+- TO: `### Requirement: Схема БД равна DBML v5.21`
+
 ## MODIFIED Requirements
 
-### Requirement: Схема БД равна DBML v5.19
+### Requirement: Схема БД равна DBML v5.21
 ORM-метаданные SHALL содержать ровно 44 таблицы и 33 enum'а из `../docs/model/data-model-v5.21.dbml` в схеме PostgreSQL
 из настройки `DB_SCHEMA` (по умолчанию `dkb`; в контуре — `OPENBAO__APP__DB_SCHEMA`; простой идентификатор
 `[a-z_][a-z0-9_]{0,62}`, не начинающийся с `pg_`, иначе приложение не стартует); сверка с DBML идёт в эталонной схеме `dkb`;
@@ -25,6 +29,9 @@ SHALL добавлять обе колонки (существующие зап
 (год, затем квартал); файлы без привязок остаются `NULL`; откат SHALL удалять индекс и колонку. Поля, отсутствующие в
 DBML, MUST NOT существовать.
 Схема v5.19 (RSHB/arm-ka-docs#116) SHALL добавлять: таблицу `document_issue` и enum'ы `statement_line_status`, `statement_form_variant`, `document_issue_kind` и прочие enum'ы DBML v5.19; колонки `document.file_ordinal` (уникальна в паре `(stored_file_id, file_ordinal)`), `recognition_job.statements_version`, `related_group.crm_id` (`varchar`, nullable, уникальна), в `financial_statement_meta` — `form_variant`, `needs_review_fields`, `header_source`, `organization_name_original_value`, `organization_name_modified`; в `financial_statement_column` — `period_kind`, `label_confidence`; в `financial_statement_line` — `row_index`, `source_ref`, `line_status`, `line_code_text`, `parent_row_index`, `needs_review`, `is_confirmed`; в `financial_statement_value` — `source_text`, `needs_review`, `is_confirmed` (с `confirmed_by/at`). Уникальность `(meta_id, line_code)` снимается, добавляется частичная уникальность `(meta_id, source_ref)` WHERE `source_ref IS NOT NULL`; уникальность документа `(stored_file_id, document_type, osv_account_code)` становится частичной (только для типов, кроме `BALANCE` / `INCOME`). Состав и порядок колонок — буквально по DBML v5.19.
+Схема v5.20 SHALL добавлять в конец `document` колонки `is_modified` (`boolean NOT NULL DEFAULT false`), `original_values`
+(`jsonb`, nullable), `modified_by` (`uuid`, nullable, FK → `app_user.id`) и `modified_at` (`timestamptz`, nullable); схема v5.21 SHALL
+добавлять значение `FILE_REPROCESS` в enum `audit_action`. Состав и порядок колонок — буквально по DBML v5.21.
 
 #### Scenario: Сверка ORM с DBML
 - **WHEN** выполняется `python scripts/check_dbml_vs_orm.py ../../docs/model/data-model-v5.21.dbml` (`make dbml-check`)
@@ -61,14 +68,12 @@ DBML, MUST NOT существовать.
 - **WHEN** выполняется `make dbml-check` по `../docs/model/data-model-v5.21.dbml`
 - **THEN** таблицы, колонки, enum'ы, ключи и индексы ORM совпадают с DBML без расхождений
 
-Схема v5.20 SHALL дополнительно содержать document.is_modified (boolean NOT NULL DEFAULT false), original_values (jsonb NULL), modified_by (uuid NULL FK app_user.id), modified_at (timestamptz NULL); порядок колонок — по DBML v5.20.
-
 ### Requirement: Версия DBML зафиксирована в коде
 Пакет моделей SHALL объявлять константу версии DBML (`DBML_VERSION = "5.21"`); скрипт сверки SHALL сравнивать её с версией в шапке файла
 DBML и падать при расхождении — смена модели без осознанного обновления ORM невозможна.
 
 #### Scenario: Новая версия DBML без обновления ORM
-- **WHEN** в `docs/model/` появляется `data-model-v5.21.dbml`, а константа в ORM — `5.19`
+- **WHEN** в `docs/model/` появляется `data-model-v5.22.dbml`, а константа в ORM — `5.21`
 - **THEN** сверка против нового файла падает с сообщением о версии до сравнения таблиц
 
 ## ADDED Requirements

openspec/changes/retry-recognition-and-edit-osv-header/specs/primary-files/spec.md

@@ -18,15 +18,16 @@
 - **THEN** 409 MAX_ATTEMPTS_REACHED, состояние не меняется
 
 ### Requirement: Пакет повторной обработки версии
-`POST /api/v1/consolidations/versions/{version_id}/files/retry` SHALL выбирать видимые файлы с
+`POST /api/v1/consolidations/versions/{version_id}/files/retry` SHALL рассматривать видимые файлы в статусе `ERROR` с
-consolidation_id консолидации версии и ЮЛ из периметра версии. Для каждого допустимого файла SHALL
+consolidation_id консолидации версии и ЮЛ из периметра версии; файлы других статусов в пакет не входят и не блокируются.
-создаваться новая попытка. Успех — 202 с accepted[{file_id, job_id, attempt}] и skipped[{file_id, code}].
+Для каждого допустимого файла SHALL создаваться новая попытка. Успех — 202 с accepted[{file_id, job_id, attempt}] и
-Файлы без контекста консолидации MUST NOT включаться по одному лишь совпадению ЮЛ.
+skipped[{file_id, code}], где skipped — рассмотренные файлы, которые повторить нельзя (`FILE_NOT_RETRYABLE`,
+`MAX_ATTEMPTS_REACHED`). Файлы без контекста консолидации MUST NOT включаться по одному лишь совпадению ЮЛ.
 
 #### Scenario: Смешанный пакет
 - **WHEN** у версии есть файл timeout/TIMEOUT, OCR, успешный файл и файл с исчерпанным лимитом
-- **THEN** новый job создаётся только для первого; остальные перечислены в skipped с причинами;
+- **THEN** новый job создаётся только для первого; OCR-файл в skipped с `FILE_NOT_RETRYABLE`, файл с исчерпанным
-  rejected-файлы не препятствуют повтору допустимых
+  лимитом — с `MAX_ATTEMPTS_REACHED`; успешный (`PROCESSED`) файл не попадает ни в accepted, ни в skipped
 
 #### Scenario: Периметр и контекст
 - **WHEN** файл загружен в другую консолидацию либо его ЮЛ не входит в выбранную версию
@@ -38,7 +39,8 @@ consolidation_id консолидации версии и ЮЛ из периме
 
 #### Scenario: Пустой пакет
 - **WHEN** подходящих файлов нет
-- **THEN** 202 с пустым accepted и списком skipped для рассмотренных неподходящих файлов; аудита повторов нет
+- **THEN** 202 с пустым accepted; в skipped — только файлы в `ERROR`, которые повторить нельзя (без них список пуст);
+  аудита повторов нет
 
 ### Requirement: Ограничения версии при повторе
 Повтор в контексте версии SHALL разрешаться только для версий «в работе» (INITIATED, DOCUMENTS_PROCESSING,

openspec/changes/retry-recognition-and-edit-osv-header/tasks.md

@@ -23,7 +23,7 @@
 - [x] 3.2 arm-core: services/file_retry.py, file_status.py и audit.py — атомарное переключение current job, UPLOADED и FILE_REPROCESS; проверить откат всей операции и отсутствие копирования ошибок, метрик, результата и времён.
 - [x] 3.3 arm-core: schemas/files.py, api/dependencies/files.py и новый endpoints/files/retry.py, регистрация router — POST /files/{id}/retry, 202 FileOut и коды ошибок; проверить api/tests/test_api_file_retry.py, права, одинаковый 404, OpenAPI и единственную транзакцию запроса.
 - [x] 3.4 arm-core: api/tests/test_recognition_exchange.py — новый job проходит существующий outbox/inbox, поздние ack/done прежнего job игнорируются; проверить свежие deadline/message-id и восстановление после недоступности NATS.
-- [x] 3.5 arm-core и arm-ka-docs: README и dev/frontend-api-guide.md — одиночный retry, разделение ручной попытки и republish; проверить примеры запросов, ответы 202/409 и описание FILE_REPROCESS по OpenAPI.
+- [x] 3.5 arm-core и arm-ka-docs (docs — ревьюер, RSHB/arm-ka-docs#157): README и dev/frontend-api-guide.md — одиночный retry, разделение ручной попытки и republish; проверить примеры запросов, ответы 202/409 и описание FILE_REPROCESS по OpenAPI.
 
 ## 4. Пакет версии
 
@@ -31,7 +31,7 @@
 - [x] 4.2 arm-core: repositories/files.py и services/file_retry.py — пакетный отбор, общие проверки версии, повторная проверка периметра под блокировкой, accepted/skipped; проверить отсутствие повторного запуска и аудита skipped, откат на неожиданной ошибке БД.
 - [x] 4.3 arm-core: schemas/files.py и endpoints/files/retry.py — POST /consolidations/versions/{id}/files/retry, 202 RetryBatchOut без consolidation_lock; проверить OpenAPI, стабильный порядок file_id и VERSION_NOT_EDITABLE без мутаций.
 - [x] 4.4 arm-core: api/tests/test_api_constraint_races.py — две сессии для одиночного/пакетного retry и смены статуса/периметра; проверить ровно одну новую попытку, отсутствие дедлока и запрещённых операций после смены статуса.
-- [x] 4.5 arm-core и arm-ka-docs: README и dev/frontend-api-guide.md — состав пакета, частичные пропуски и правила версий; проверить примеры смешанного и пустого ответа по интеграционным тестам.
+- [x] 4.5 arm-core и arm-ka-docs (docs — ревьюер, RSHB/arm-ka-docs#157): README и dev/frontend-api-guide.md — состав пакета, частичные пропуски и правила версий; проверить примеры смешанного и пустого ответа по интеграционным тестам.
 
 ## 5. Уточнение шапки ОСВ
 
@@ -41,12 +41,12 @@
 - [x] 5.4 arm-core: services/osv_header.py и consolidation_documents.py — проверка привязанных версий, сброс подтверждения, выборочная отвязка и аудит; проверить CONFIRMED/автоподтверждённый/CANCELLED/VERIFIED, rollback, no-op и отсутствие автоподтверждения.
 - [x] 5.5 arm-core: endpoints/files/documents.py и api/dependencies/files.py — PATCH /documents/{id}/osv-header, 200 DocumentOut, доменные 409/422 в требуемом порядке; проверить OpenAPI, права, policy и ограничения тела без изменения отсутствующих полей.
 - [x] 5.6 arm-core: api/tests/test_api_osv_header.py, test_api_constraint_races.py и test_api_consolidation_checklist.py — конкурентные PATCH/confirm, коллизия счёта, новое подтверждение и производные данные; проверить колонку ОСВ/чек-лист с флагом периода false/true и отсутствие автозамены файлов.
-- [x] 5.7 arm-core и arm-ka-docs: README и dev/frontend-api-guide.md — PATCH, original_values, no-op, снятие подтверждения и флаг периода; проверить примеры по сценариям тестов и OpenAPI, UI оставить отдельной задачей.
+- [x] 5.7 arm-core и arm-ka-docs (docs — ревьюер, RSHB/arm-ka-docs#157): README и dev/frontend-api-guide.md — PATCH, original_values, no-op, снятие подтверждения и флаг периода; проверить примеры по сценариям тестов и OpenAPI, UI оставить отдельной задачей.
 
 ## 6. Общая проверка и документация поставки
 
 - [ ] 6.1 arm-core: выполнить make check, make dbml-check, make test-integration, затем make check-full по требованиям репозитория; сохранить результаты и явно указать skips/недоступность инфраструктуры, проверить git diff на отсутствие посторонних изменений.
-- [x] 6.2 arm-core и arm-ka-docs: сверить README, context/03-architecture.md, context/07-open-questions.md и dev/frontend-api-guide.md с реализацией, закрытым OQ-161 и согласованными решениями FILE_REPROCESS/пакета; проверить ссылки, порядок выкладки и согласованность core/docs PR. Это финальная задача документации среза, основные API-документы обновлены в своих группах.
+- [x] 6.2 arm-core и arm-ka-docs (ревьюер: README/CLAUDE.md v5.21, 05-domain-rules §9.4–9.5 и гайд фронта — RSHB/arm-ka-docs#157): сверить README, context/03-architecture.md, context/07-open-questions.md и dev/frontend-api-guide.md с реализацией, закрытым OQ-161 и согласованными решениями FILE_REPROCESS/пакета; проверить ссылки, порядок выкладки и согласованность core/docs PR. Это финальная задача документации среза, основные API-документы обновлены в своих группах.
 
 ## Workflow follow-up
 
@@ -73,3 +73,10 @@
   ошибок действует после проверки типов. Схема/домен/OpenAPI — 105 passed; API шапки и карточка — 8 passed;
   mypy — без ошибок. Глобальный format-check отдельно указывает на пользовательский комментарий
   в services/file_retry.py, не относящийся к этой правке; комментарий оставлен без изменений.
+
+## Ревью (RSHB/arm-core#161)
+
+- [x] 7.1 Ревьюер: `api/.env.test` — порт PostgreSQL 5432 по compose (свой порт — переменной `OPENBAO__DATABASE__DATABASE_URL`).
+- [x] 7.2 Ревьюер: дельта data-model переименована на v5.21, `openspec/config.yaml` — DBML v5.21, README/CLAUDE.md — миграции 0008/0009.
+- [x] 7.3 Ревьюер: синтетические тесты PATCH шапки ОСВ без `fixtures`, смешанный пакет и NO_ACK на пределе.
+- [ ] 7.4 Автор: замечания комментария ревью (пакет — только файлы в `ERROR`, блокировки версий, `CONTRACT_VERSION`, репозиторий, OpenAPI).

openspec/config.yaml

@@ -3,7 +3,7 @@ schema: spec-driven
 context: |
   Репозиторий arm-core — часть системы АРМ КА (ДКБ, Россельхозбанк): ядро (FastAPI + React), единственный писатель в PostgreSQL: справочники, файлы/документы, маппинг результатов распознавания, вычисления консолидации, согласование, ЕХ, аудит, права.
   Workspace из нескольких репозиториев; общий контекст — ../CLAUDE.md и ../docs/ (репозиторий arm-ka-docs).
-  Источники истины по приоритету: ../docs/model/data-model-v5.17.dbml → ../docs/model/entities-v5.17.md →
+  Источники истины по приоритету: ../docs/model/data-model-v5.21.dbml → ../docs/model/entities-v5.21.md →
   ../docs/context/05-domain-rules.md → страницы ТЗ в ../docs/source/tz (черновик, старые имена v4).
   Открытые вопросы — ../docs/context/07-open-questions.md; план срезов — ../docs/context/09-delivery-plan.md.
   Фикстуры — ../fixtures (реальные данные, не спецификация формата).
@@ -14,7 +14,7 @@ context: |
 rules:
   proposal:
     - Указывать номер среза из 09-delivery-plan.md и затронутые репозитории; сквозные изменения — отдельный change в ../docs
-    - Перечислять таблицы DBML v5.17, которые затрагиваются; поля вне DBML не вводить — сначала новая версия DBML
+    - Перечислять таблицы текущей DBML (сейчас v5.21), которые затрагиваются; поля вне DBML не вводить — сначала новая версия DBML
     - Ссылаться на параграфы 05-domain-rules.md для каждого алгоритма; правило, которого там нет, — в 07-open-questions.md
     - Раздел «Non-goals» обязателен
     - Любое допущение по открытому вопросу помечать ASSUMPTION(OQ-nn)