diff --git a/dev/frontend-api-guide.md b/dev/frontend-api-guide.md index 08d4f98..54bba59 100644 --- a/dev/frontend-api-guide.md +++ b/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 { | `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 { | Задача | Что поменяется для фронта | Как подготовиться | |---|---|---| | 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.