483ce8523b
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012vJkmBGKKqMoEMzvsXG3y2
88 lines
8.6 KiB
Markdown
88 lines
8.6 KiB
Markdown
# documents-api Specification
|
||
|
||
## Purpose
|
||
Чтение файлов, документов и строк ОСВ для панели «Первичные документы» (подсрез 2d) и подтверждение документа.
|
||
|
||
## Requirements
|
||
|
||
### Requirement: Файлы организации и карточка файла
|
||
`GET /api/v1/legal-entities/{id}/files` (`DOCUMENT_VIEW`, policy; `include_superseded=false` по умолчанию) SHALL
|
||
возвращать `Page` файлов ЮЛ по убыванию `uploaded_at`: поля `stored_file`, текущее задание (`status`, `error_code`,
|
||
`error_message`, `mapping_error` (`metrics.mapping_error`: причина `ERROR` файла после неудачного маппинга, когда у задания
|
||
`error_code` пуст), `metrics.warnings`, `metrics.mapping_warnings`, `finished_at`), документы файла (`id`, `document_type`,
|
||
`osv_account_code`, `period_year`, `period_quarter`, `is_cumulative`, `status`, `period_check`, `counterparty_check`).
|
||
`GET /api/v1/files/{file_id}` SHALL отдавать ту же карточку; чужой или несуществующий файл — 404.
|
||
|
||
#### Scenario: Список после обработки
|
||
- **WHEN** у ЮЛ два файла: `PROCESSED` с документом и `ERROR`
|
||
- **THEN** оба в списке; у первого `documents` непустой, у второго `job.error_code` заполнен
|
||
|
||
### Requirement: Документ и строки
|
||
`GET /api/v1/documents/{document_id}` (`DOCUMENT_VIEW`, policy по ЮЛ владельца) SHALL отдавать документ, статус,
|
||
проверки, `locator`, схему группировок листа из `recognition_job.group_schema` и `file_id`.
|
||
`GET /api/v1/documents/{document_id}/entries` SHALL отдавать `Page` строк по возрастанию `row_number` (`limit` ≤ 2000,
|
||
по умолчанию 500) с полями `osv_entry`, включая `parent_entry_id`, `account_id`, `counterparty_id`.
|
||
|
||
#### Scenario: Строки деревом
|
||
- **WHEN** запрошены строки документа ОСВ 66
|
||
- **THEN** первая строка — счёт `66` уровня 0 без родителя, у строк уровня 2 `parent_entry_id` указывает на субсчёт
|
||
|
||
### Requirement: Подтверждение документа
|
||
`POST /api/v1/documents/{document_id}/confirm` (`DOCUMENT_EDIT`, policy) SHALL переводить документ из `RECOGNIZED`
|
||
или `NEEDS_CHECK` в `CONFIRMED` (`confirmed_by`, `confirmed_at`) с `audit_event(DOCUMENT_CONFIRM, PRIMARY_DOCUMENTS)`;
|
||
из `CONFIRMED` повторно — 409 `ALREADY_CONFIRMED`; документ файла `SUPERSEDED` — 409 `FILE_SUPERSEDED`; документ в любом
|
||
другом статусе (например, `ERROR`) — 409 `DOCUMENT_NOT_CONFIRMABLE`. Если совпали несколько условий, приоритет у
|
||
`FILE_SUPERSEDED`. Подтверждение берёт блокировки в порядке «файл → документ → (advisory-блокировка привязок ГК) → версии консолидации
|
||
(по возрастанию `id`)»: файл — `FOR UPDATE`, документ — `FOR NO KEY UPDATE` (R-3; совместима со вставкой привязки
|
||
`FOR KEY SHARE`), версии — `FOR UPDATE`; состояние перечитывается под этими блокировками; документ или файл, исчезнувшие за время ожидания блокировки, — 404 `NOT_FOUND`.
|
||
В той же транзакции документ SHALL привязываться (`consolidation_document`) ко всем версиям «в работе» (`INITIATED`,
|
||
`DOCUMENTS_PROCESSING`, `DATA_CORRECTION`), которым он подходит: ЮЛ документа ∈ `consolidation_member` версии,
|
||
`period_year` = год версии, `period_quarter` не NULL и (`is_cumulative` true или NULL → `period_quarter` = квартал
|
||
версии; false → `period_quarter` ≤ квартала версии). ОСВ за `Q1` равнозначна нарастающей и квартальной (R-14): она
|
||
подходит любой версии года при любом `is_cumulative`; ББ/ОФР за `Q1` — отчёт на конец квартала и подходят только версии
|
||
за `Q1` (R-14a). Привязанный ранее документ того же ЮЛ с тем же ключом (`document_type`, `osv_account_code`,
|
||
`period_quarter`, признак нарастающего: `is_cumulative` true или NULL; для ОСВ за `Q1` признак не различается) в той же
|
||
версии SHALL отвязываться (R-1). Каждая версия, получившая
|
||
привязку, из `INITIATED` или `DOCUMENTS_PROCESSING` SHALL переходить в `DATA_CORRECTION` (`changed_by` =
|
||
подтвердивший). Блокировка версии (`consolidation_lock`) для подтверждения MUST NOT требоваться.
|
||
|
||
#### Scenario: Причина ошибки маппинга в карточке файла
|
||
- **WHEN** файл в `ERROR` после неудачного маппинга (задание `done`, `error_code` пуст)
|
||
- **THEN** `job.mapping_error` содержит причину, `job.error_code` пуст
|
||
|
||
#### Scenario: Документ не подтверждается
|
||
- **WHEN** подтверждается документ в статусе `ERROR`
|
||
- **THEN** 409 `DOCUMENT_NOT_CONFIRMABLE`, статус не изменился
|
||
|
||
#### Scenario: Подтверждение
|
||
- **WHEN** `ka_rf` подтверждает документ `NEEDS_CHECK` своего филиала
|
||
- **THEN** `status = CONFIRMED`, `confirmed_by` = пользователь, `audit_event(DOCUMENT_CONFIRM)` с `before_value.status = NEEDS_CHECK`
|
||
|
||
#### Scenario: Привязка к версии и переход статуса
|
||
- **WHEN** версия ГК 2024 Q3 в `INITIATED` с ЮЛ в периметре; подтверждается квартальная ОСВ 60 этого ЮЛ за 2024 Q2
|
||
- **THEN** `consolidation_document(version, document)` создан; версия в `DATA_CORRECTION`; запись истории
|
||
`INITIATED → DATA_CORRECTION` с `changed_by` = пользователь
|
||
|
||
#### Scenario: Не подходит по периоду
|
||
- **WHEN** подтверждается нарастающая ОСВ 60 за 2024 Q2 при версии за 2024 Q3
|
||
- **THEN** привязки нет, статус версии не изменился
|
||
|
||
#### Scenario: Версия в CANCELLED
|
||
- **WHEN** подходящий документ подтверждается при версии `CANCELLED`
|
||
- **THEN** привязки нет
|
||
|
||
### Requirement: Подхват документов при создании версии и расширении периметра
|
||
При создании версии и при добавлении ЮЛ в периметр ядро SHALL привязать уже подтверждённые документы этого ЮЛ из
|
||
незаменённых файлов, подходящие версии (условия — как при подтверждении); на один ключ (`document_type`,
|
||
`osv_account_code`, `period_quarter`, признак «нарастающий»; NULL признака — нарастающий; для ОСВ за Q1 признак не
|
||
различается, R-1, R-14) — документ с самым поздним `confirmed_at`. Удаление ЮЛ из периметра SHALL
|
||
снимать привязку всех его документов в этой версии. Подхват и отвязка статус версии MUST NOT менять.
|
||
|
||
#### Scenario: Фикстуры, подтверждённые до консолидации
|
||
- **WHEN** ОСВ 60 РБ за Q1, Q2, Q3 2024 подтверждены, затем создана консолидация ГК за 2024 Q3
|
||
- **THEN** три `consolidation_document` на эти документы; в чек-листе ячейка ОСВ 60 РБ — `CONFIRMED`; версия в `INITIATED`
|
||
|
||
#### Scenario: Две подтверждённые версии одного документа
|
||
- **WHEN** у ЮЛ два незаменённых файла с `CONFIRMED` ОСВ 62 за 2024 Q3 (разные `locator`), создана версия 2024 Q3
|
||
- **THEN** привязан документ с более поздним `confirmed_at`
|