dev: гайд фронта — формы ББ/ОФР после единой нормализации (после реализации, #116)

- §5.6.1: новые поля StatementOut (статусы строк, повторы кода, reference_name, needs_review, text,
  issues[], period_kind, form_variant), PATCH values[].confirmed / columns / lines, порядок 409
  подтверждения с LINES_UNRESOLVED и DUPLICATE_FORM, crm_id ГСК/ГСЗ
- §9: новые коды ошибок с пометкой «после #116»; §11: строка о предстоящем изменении

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BJKMLHdxMwSUeYcdkwqX4W

dev/frontend-api-guide.md

@@ -411,6 +411,67 @@ UI прячет элементы по `GET /me → permissions` (объедин
 - `cross_form` зависит от второго документа ЮЛ за тот же период: появилась ОФР отдельным файлом — перечитайте ББ.
 - Документ формы появляется после того, как файл стал `PROCESSED`; до этого `…/statement` — 404.
 
+### 5.6.1 Формы ББ/ОФР после единой нормализации — **после реализации**
+
+> **Пока не работает на `main`.** Раздел описывает API после change `unified-statement-normalization`
+> (RSHB/arm-ka-docs#116; контракт распознавания v2.0, DBML v5.19; дочерние PR arm-core и arm-web ещё не созданы).
+> Правила — `context/05-domain-rules.md` §7, §9.3, §9.5 пп. 2, 4, 9, §11; экран — спека `arm-web` того же change.
+> Поля добавляются, старые не удаляются: клиент, написанный по §5.6, продолжит читать ответ. После слияния PR раздел
+> переедет в §5.6 и §1.
+
+**`GET /documents/{id}/statement` — новые поля `StatementOut`:**
+
+- `document.form_variant` — `full` | `simplified` | `null` (упрощённая форма — свой набор проверок §7).
+- `header.needs_review_fields[]` — поля шапки, требующие проверки (сейчас бывает только `report_date`); сырые тексты полей.
+- `columns[].period_kind` — `absolute` | `relative:current` | `relative:prev_year_end` | `relative:prev_prev_year_end` |
+  `relative:prev_period` | `none`; `columns[].label_confidence`. Колонка с `period_kind = none` и `period_date = null` —
+  нужна дата от аналитика (ввод даты у колонки).
+- `lines[]` — **все строки источника**, а не только строки с кодом: `row_index` (порядок в файле; `null` у шаблонных и
+  созданных правкой), `source_ref`, `line_status` (`ok` | `unreadable` | `missing` | `detail`), `line_code` (`null` у
+  статусов кроме `ok`), `line_code_text` (сырой текст ячейки кода — показывать серым у `unreadable` / `missing`),
+  `line_name` (наименование **из файла**), `reference_name` (справочное имя по коду или `null` — его показывать основным,
+  файловое рядом, если отличается), `parent_row_index` (родитель расшифровки `detail`), `needs_review` (подсветить строку),
+  `is_confirmed`, `line_code_modified`. **Один код может стоять у нескольких строк** (повтор кода законен): не строить
+  словарь «код → строка», ключ строки — `id` (у достроенных шаблонных — `line_code`, их у кода с реальной строкой `ok` нет).
+- `values[]` — `text` (сырой текст источника; в подсказку ячейки вместе с `confidence`), `needs_review`, `is_confirmed`.
+  **Подсветка ячейки — только по `needs_review`**; по `confidence < 100` и `is_recognized = false` больше не подсвечивать
+  (сервис уже свёл их с проверками §7: догадка, подтверждённая сошедшимся соотношением, не подсвечивается).
+- `issues[]` — предупреждения и нарушения документа: `{id, kind: "warning" | "relation" | "soft", code, severity: "error" |
+  "info", message, line_ids[], column_id?, field?, source: "service" | "core", relation?, expected?, actual?}`; показывать у
+  места (строки, ячейки, поле шапки) или у документа; `error` отличать от `info`.
+- `checks.failed[]` / `soft_failed[]` — у нарушения ещё `codes[]` и `line_ids[]` (все строки кодов соотношения).
+- Порядок `lines` — уже «как на бумаге»: строки `ok` по коду (одинаковые коды по `row_index`), `unreadable` / `missing` —
+  после ближайшей предыдущей по `row_index` строки с кодом (без такой — в начале), `detail` — сразу после родителя.
+  Расшифровки (`detail`) по умолчанию скрывать за переключателем «Показать расшифровки (N)».
+
+**`PATCH /documents/{id}/statement` — новые части тела** (можно вместе в одном запросе; один запрос — один пересчёт):
+
+| Часть | Тело | Эффект | Ошибки |
+|---|---|---|---|
+| подтвердить ячейку | `values: [{line_id, column_id, confirmed: true}]` | `is_confirmed`, `needs_review = false`, сумма не меняется | 422 `UNKNOWN_CELL` |
+| дата колонки | `columns: [{column_id, period_date}]` | дата колонки, `is_current`, период документа; снимает `COLUMN_WITHOUT_DATE` / `COLUMN_DATE_UNCERTAIN` | 422 `UNKNOWN_COLUMN` |
+| назначить / сменить код | `lines: [{line_id, line_code}]` | `unreadable` / `missing` / `detail` / `ok` → `ok` с этим кодом, `line_code_confidence = 100` | 422 `INVALID_LINE_CODE` (не 4–5 цифр), 409 `LINE_EXISTS` (код занят строкой, созданной правкой, с суммами — сначала очистить её) |
+| отметить расшифровкой | `lines: [{line_id, line_status: "detail"}]` | строка выходит из сумм и не блокирует подтверждение | 422 `LINE_CODE_REQUIRED` (`line_status: "ok"` без кода) |
+| подтвердить код | `lines: [{line_id, confirmed: true}]` | `is_confirmed`, `needs_review` строки = `false` | — |
+
+Общие ошибки `lines`: 422 `UNKNOWN_LINE` (строка не этого документа), 422 `INVALID_LINE_PATCH` (в элементе нет действия или
+их несколько). Правка суммы по `line_code` (достроенная строка) для кода, у которого уже есть строка `ok`, — 422
+`UNKNOWN_CELL`: передайте `line_id`. Правка `header.report_date` пересчитывает даты колонок с `period_kind = relative:*`.
+Удалять строки нельзя — для этого «Сделать расшифровкой». Ответ — `StatementOut` после пересчёта.
+
+**`POST /documents/{id}/confirm` для формы — порядок 409:** `FILE_SUPERSEDED` → `ALREADY_CONFIRMED` →
+`DOCUMENT_NOT_CONFIRMABLE` → `PERIOD_REQUIRED` → **`LINES_UNRESOLVED`** (`detail.lines[] {line_id, row_index,
+line_code_text}` — строки `unreadable` / `missing` с суммами; кнопку «Подтвердить данные» отключать заранее с подсказкой
+«Разберите строки без кода: N») → **`DUPLICATE_FORM`** (`detail.document_id` — в этом файле уже подтверждена форма того
+же типа и периода) → `CHECKS_NOT_PASSED`.
+
+**Статус документа.** Форма из OCR теперь бывает `RECOGNIZED` (и сразу автоподтверждается), если сервис всё подтвердил
+проверками; `NEEDS_CHECK` — когда есть что смотреть: подсвеченные ячейки и строки, `issues` уровня `error`, неразобранные
+строки. Две формы одного типа в одном файле приходят двумя документами; ни одна не автоподтверждается.
+
+**ГСК/ГСЗ.** `crm_id` в `POST …/related-groups` и `PATCH /directories/related-groups/{id}` сохраняется и возвращается в
+`RelatedGroupOut` / `RelatedGroupDetail`; повтор — 409 `CRM_ID_EXISTS` (arm-core#112, DBML v5.19).
+
 ### 5.7 Консолидации
 
 | Метод и путь | Право | Запрос | Ответ | Ошибки |
@@ -606,6 +667,10 @@ async function download(path: string, fallbackName: string): Promise<void> {
 | `ALREADY_CONFIRMED`, `FILE_SUPERSEDED`, `DOCUMENT_NOT_CONFIRMABLE` | 409 | подтверждение, правка формы | — | перечитать документ |
 | `PERIOD_REQUIRED` | 409 | подтверждение формы | — | «Укажите дату отчёта» → режим правки шапки |
 | `CHECKS_NOT_PASSED` | 409 | подтверждение формы | `failures[] {column_index, relation, expected, actual}` | показать нарушения, предложить акцепт |
+| `LINES_UNRESOLVED` | 409 | подтверждение формы (после #116, §5.6.1) | `lines[] {line_id, row_index, line_code_text}` | перейти к первой строке без кода, предложить назначить код или «Это расшифровка» |
+| `DUPLICATE_FORM` | 409 | подтверждение формы (после #116) | `document_id` | ссылка на уже подтверждённую форму того же типа и периода в файле |
+| `LINE_EXISTS` | 409 | правка формы, назначение кода (после #116) | — | ошибка поля кода: код занят строкой, созданной правкой, с суммами |
+| `INVALID_LINE_CODE`, `LINE_CODE_REQUIRED`, `INVALID_LINE_PATCH`, `UNKNOWN_LINE`, `UNKNOWN_COLUMN` | 422 | правка формы `lines` / `columns` (после #116) | — | ошибка поля / ошибка клиента (перечитать форму) |
 | `DOCUMENT_NOT_STATEMENT` | 409 | `…/statement` не по форме ББ/ОФР | — | не открывать экран [41] для такого документа |
 | `DOCUMENT_READONLY` | 409 | правка/акцепт подтверждённой формы | — | перевести экран в просмотр |
 | `UNKNOWN_CELL`, `DUPLICATE_CELL` | 422 | правка формы | — | ошибка клиента (перечитать форму); `UNKNOWN_CELL` также: `line_code` уже есть в форме (слать `line_id`), код вне справочника редакции, нет редакции |
@@ -657,6 +722,7 @@ async function download(path: string, fallbackName: string): Promise<void> {
 | Задача | Что поменяется для фронта | Как подготовиться |
 |---|---|---|
 | OQ-54 — SSO РАИСА | Меняется только получение токена (вместо dev-формы) | держать слой получения токена изолированным (`frontend-auth-guide.md` §9) |
+| arm-ka-docs#116 — единая нормализация ББ/ОФР (контракт v2.0, DBML v5.19) | `GET/PATCH …/statement`: строки со статусами и повторами кода, `needs_review`, `issues[]`, `lines`/`columns`/`confirmed` в PATCH; подтверждение — 409 `LINES_UNRESOLVED`, `DUPLICATE_FORM`; `crm_id` ГСК/ГСЗ сохраняется | §5.6.1; не держать словарь «код → строка», подсветку строить по `needs_review` |
 
 Состояние этих задач — в Gitea (`RSHB/arm-core`, `RSHB/arm-ka-docs`); после слияния каждой этот раздел переезжает в §1.