94846cbd4c
Proposal, design (состав v1.2: DISCLOSURE, statementDocument.checks, границы периода ОСВ; примеры; порядок раскатки потребители → производитель), дельта recognition-contract «Файл результата» v1.2, tasks. Refs #26 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: cedd7915-2efe-41e5-988c-a9117033598b
40 lines
3.9 KiB
Markdown
40 lines
3.9 KiB
Markdown
# Spec Delta: recognition-contract
|
||
|
||
## MODIFIED Requirements
|
||
|
||
### Requirement: Файл результата
|
||
Файл результата SHALL соответствовать `docs/contracts/recognition-result.schema.json` v1.2: один файл (`stored_file`)
|
||
→ один `job_id` → массив `documents` из `osvDocument` и/или `statementDocument`; денежные значения — строки
|
||
`^-?\d+(\.\d{1,2})?$`; `confidence` — 0–100. Пустой массив `documents` допустим только при `status = error`.
|
||
У строки `osvDocument.rows[]` SHALL быть необязательное поле `extra` — объект «заголовок колонки → строка или null» для
|
||
колонок внутри таблицы, не сопоставленных с шестью суммами и ИНН (§1.2 «не терять»). У шапки `osvDocument.header` SHALL
|
||
быть необязательные `period_start`, `period_end` (дата или null — границы периода по шапке; для квартала и года —
|
||
первое и последнее число, для диапазона месяцев — его границы) и `is_from_year_start` (boolean или null; `is_cumulative`
|
||
не переопределяется). `statementDocument.document_type` SHALL допускать `DISCLOSURE` (расшифровка или иная форма
|
||
0710xxx: документ без `columns` и `lines`). У `statementDocument` SHALL быть необязательный объект `checks`:
|
||
`relations_failed` и `soft_relations_failed` — массивы `{column_index, relation, expected, actual}` (нарушенные
|
||
соотношения §7 по колонке; `expected`/`actual` — `money`), `duplicate_line_codes` — массив строк; отсутствие объекта
|
||
означает «не проверялось», пустые массивы — «проверено, сошлось». Потребители, не знающие новых полей и значений,
|
||
игнорируют их (MINOR). Производитель v1.2 пишет `schema_version = "1.2"`; файлы v1.0 и v1.1 остаются валидными.
|
||
|
||
#### Scenario: Результат валидируется примерами
|
||
- **WHEN** CI сервиса запускает тесты контракта
|
||
- **THEN** все файлы `docs/contracts/examples/result-*.json` проходят схему файла результата, а все
|
||
`request-*.json` / `result-message-*.json` — схемы сообщений
|
||
|
||
#### Scenario: Лишняя колонка сохранена
|
||
- **WHEN** в ОСВ между ИНН и суммами есть колонка «КПП»
|
||
- **THEN** у строк контрагентов `extra = {"КПП": "<значение>"}`, файл проходит схему v1.2 и схему v1.0 (поле
|
||
игнорируется)
|
||
|
||
#### Scenario: Форма из Excel с проверками
|
||
- **WHEN** tabular-parser разобрал книгу с балансом на двух листах, ОФР и пояснениями (`examples/result-statement-excel.json`)
|
||
- **THEN** файл проходит схему v1.2: `BALANCE` с `locator` из двух имён листов и `checks` с нарушением в
|
||
`soft_relations_failed`, `INCOME` с пустыми массивами `checks`, `DISCLOSURE` без `columns`/`lines`; тот же файл
|
||
без `checks` и с `document_type = OTHER` вместо `DISCLOSURE` проходит схему v1.1
|
||
|
||
#### Scenario: Границы периода ОСВ
|
||
- **WHEN** в шапке ОСВ период «Октябрь 2024 г. – Сентябрь 2025 г.»
|
||
- **THEN** `period_start = "2024-10-01"`, `period_end = "2025-09-30"`, `is_from_year_start = false`; файл проходит схему
|
||
v1.2, а потребитель v1.1 читает его без ошибок
|