RSHB/arm-ka-docs
9
0
Fork 0
Code Issues 12 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: контракт — статусы задания timeout/dlq, поле multipart files, подписи статусов как в чек-листе, entity_type nullable (ревью arm-core#42)

Browse Source 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012vJkmBGKKqMoEMzvsXG3y2
This commit is contained in:
Andrey Epifancev 2026-10-07 18:17:36 +04:00
parent d8af9579aa
commit 2851e30345
2 changed files with 8 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
dev/api-contract-files-directories.md
View File

@ -14,7 +14,8 @@
1…2000 (по умолчанию 500); `offset ≥ 0`; вне предела — 422 (pydantic-массив).
- ЮЛ, файл или документ вне видимости пользователя неотличимы от несуществующих: 404 `NOT_FOUND`.
- Перечисления: `FileType` — `XLS`, `XLSX`, `XLSB`, `PDF`, `PNG`, `JPG`; `FileStatus` — `UPLOADED`, `PROCESSING`, `PROCESSED`, `ERROR`,
`SUPERSEDED`; `RecognitionStatus` (задание) — `queued`, `published`, `processing`, `done`, `needs_check`, `error`; `DocumentType` —
`SUPERSEDED`; `RecognitionStatus` (задание) — `queued`, `published`, `processing`, `done`, `needs_check`, `error`, `timeout` (нет ответа к сроку),
`dlq` (сервис не подтвердил приём после повторов); `DocumentType` —
`BALANCE`, `INCOME`, `OSV`, `DISCLOSURE`, `OTHER`; `DocumentStatus` — `RECOGNIZED`, `NEEDS_CHECK`, `CONFIRMED`, `ERROR`;
`DocumentCheckResult` — `MATCH`, `MISMATCH`, `UNKNOWN`; `EntityType` — `ЮЛ`, `ИП`; `RelatedGroupKind` — `gsk`, `gsz`.
@ -23,7 +24,7 @@
| Метод и путь | Право | Запрос | Ответ | Ошибки | Экран |
|---|---|---|---|---|---|
| `GET /legal-entities/{legal_entity_id}/files` | VIEW | query `limit`, `offset`, `include_superseded` (bool, по умолчанию `false` — заменённые скрыты) | `Page[FileOut]`, новые первыми (по убыванию `uploaded_at`) | 404 | [39] drawer «Первичные документы» |
| `POST /legal-entities/{legal_entity_id}/files` | EDIT | multipart `files[]`; query `consolidation_version_id?` | 201 `UploadResult` (принят хотя бы один файл) / 422 `UploadResult` (ни один) | 404 (ЮЛ; версия — `VERSION_NOT_FOUND`), 409 `VERSION_NOT_EDITABLE`, 422 `ENTITY_NOT_IN_PERIMETER`, 503 `STORAGE_UNAVAILABLE` | [40] |
| `POST /legal-entities/{legal_entity_id}/files` | EDIT | multipart, поле `files` (повторяется для каждого файла, не `files[]`); query `consolidation_version_id?` | 201 `UploadResult` (принят хотя бы один файл) / 422 `UploadResult` (ни один) | 404 (ЮЛ; версия — `VERSION_NOT_FOUND`), 409 `VERSION_NOT_EDITABLE`, 422 `ENTITY_NOT_IN_PERIMETER`, 503 `STORAGE_UNAVAILABLE` | [40] |
| `GET /files/{file_id}` | VIEW | — | `FileOut` | 404 | опрос строки файла |
| `DELETE /files/{file_id}` | EDIT | — | 204 | 404, 409 `FILE_HAS_CONFIRMED_DOCUMENTS`, 409 `FILE_SUPERSEDES_OTHERS` | [39] иконка «удалить» |
| `GET /files/{file_id}/content` | VIEW | query `disposition` (`attachment` по умолчанию / `inline`) | поток исходного файла | 404 (`FILE_CONTENT_NOT_FOUND` — объекта нет в хранилище), 503 | [41] «Исходный документ» (см. контракт 3b) |
@ -63,9 +64,10 @@ opening_debit?, opening_credit?, turnover_debit?, turnover_credit?, closing_debi
нюанс 17).
- «Проверка»: «Контрагент» — `counterparty_check` (`MATCH` ✓, `MISMATCH` ✗, `UNKNOWN`/`null` —); «Период» — `period_check` сейчас
всегда `UNKNOWN` → показывайте «—» (OQ-120).
- «Статус» (подписи — `context/10-user-journey.md`, «Словарь UI»): файл `UPLOADED`/`PROCESSING` — «Обработка»; файл `ERROR` —
«Ошибка» (причина — `job.error_message` / `job.mapping_error`); иначе по документу: `NEEDS_CHECK` — «Требуется проверка»,
`RECOGNIZED`/`CONFIRMED` — «Загружен» (подтверждённый можно пометить отдельно).
- «Статус» (подписи — как в чек-листе и его CSV, `context/10-user-journey.md` «Словарь UI»): файл `UPLOADED`/`PROCESSING` —
«Обработка»; файл `ERROR` — «Ошибка» (причина — `job.error_message` / `job.mapping_error`; задание `timeout`/`dlq` — тоже
ошибка, причина в `job.error_message`); иначе по документу: `RECOGNIZED` и `NEEDS_CHECK` — «Требуется проверка», `CONFIRMED` —
«Загружен», `ERROR` — «Ошибка».
- Комментарий — у **документа** (`comments_count`, `GET/POST /documents/{id}/comments`, контракт 3b); у файла без документов
комментария нет.
- Опрос во время распознавания: перечитывайте `GET /legal-entities/{id}/files` (или `GET /files/{id}` для одного файла), пока

2
dev/api-contract-slice-4.md
View File

@ -62,7 +62,7 @@
**`LockOut`** `{locked_by, locked_by_name, locked_at, taken_over_from (uuid | null), takeover_reason (string | null)}`.
**`VersionCard`** = `VersionBrief` + `{consolidation_id, year, quarter, reporting_date, company_group (Ref), initiator (Ref),
initiator_office (Ref), goodwill_enabled, is_in_work, previous_version_id, members[], history[]}`:
- `members[]` — `{id, name, inn, entity_type ("ЮЛ" | "ИП"), is_head_entity, checklist[], osv_accounts[]}` (arm-core #42):
- `members[]` — `{id, name, inn, entity_type ("ЮЛ" | "ИП" | null — поле `legal_entity` nullable в DBML), is_head_entity, checklist[], osv_accounts[]}` (arm-core #42):
- `checklist[]` — ячейки `ChecklistCellOut` по правилам комплекта (тот же порядок, что `ChecklistOut.rules`); ячейка
**самоописывающая** — ищите нужную по `document_type`/`account` («Бух. баланс» — `BALANCE`, «ОФР» — `INCOME`, «ОСВ 60» —
`OSV` + `"60"`), а не по индексу;