docs(openspec): архив demo-prototype — спеки consolidation-setup, primary-files-ui, document-review-ui, consolidated-osv-ui (#3)

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

openspec/specs/consolidated-osv-ui/spec.md

@@ -0,0 +1,44 @@
+# consolidated-osv-ui Specification
+
+## Purpose
+TBD - created by archiving change demo-prototype. Update Purpose after archive.
+
+## Requirements
+
+### Requirement: Сводка версии
+Экран «Сводная ОСВ» [30] SHALL показывать шапку версии (ГК, период, номер, статус) и сводку
+`GET /consolidations/versions/{id}/osv/summary`: строк всего, документов, несопоставленных (`unmapped_total` — счётчик
+«Осталось N» без перехода к сопоставлению), автоматически сопоставленных.
+
+#### Scenario: Контрольные цифры РБ 2024 Q3
+- **WHEN** открыт свод версии РБ 2024 Q3 после подтверждения 22 ОСВ из `fixtures/osv/{rb,schastl}/2024-Q{1,2,3}`
+- **THEN** «строк» = 1385, «документов» = 22, «несопоставленных» = 1381
+
+### Requirement: Таблица свода и фильтры
+Экран SHALL показывать строки `GET /consolidations/versions/{id}/osv` постранично (размер страницы ≤ 2000): ЮЛ, счёт,
+контрагент, ИНН контрагента, признак контрагента (ГСК/ГК/Внешний), способ сопоставления, сальдо на начало Дт/Кт,
+обороты Дт/Кт, сальдо на конец Дт/Кт (суммы — строками с разделителями разрядов). Фильтры: ЮЛ (`legal_entity_id`),
+корень счёта (`account_root`), признак контрагента (`counterparty_type`), только несопоставленные (`unmapped`), поиск по
+контрагенту (`q`, ≤ 500 символов). Смена фильтра SHALL перечитывать первую страницу.
+
+#### Scenario: Строка из контрольных цифр
+- **WHEN** фильтр ЮЛ «Пекарня Счастливочная» и поиск «бисквит»
+- **THEN** строка `60.01` показывает сальдо нач. Кт 4 454 151.93, обороты Дт 128 058 143.65, Кт 125 950 450.77,
+  сальдо кон. Кт 2 346 459.05, признак «ГСК»
+
+### Requirement: Пробелы
+Экран SHALL показывать `gaps[]` сводки списком «ЮЛ — счёт — недостающие кварталы» с пояснением, что строки этих пар в
+своде отсутствуют.
+
+#### Scenario: Пробелы РБ 2024 Q3
+- **WHEN** открыт свод версии РБ 2024 Q3
+- **THEN** показано 7 пробелов, у каждого недостающие кварталы «Q1, Q2»
+
+### Requirement: Экспорт
+Кнопка «Скачать xlsx» SHALL получать `GET /consolidations/versions/{id}/osv/export` с текущими фильтрами через клиент API
+с токеном и сохранять файл; имя — из `Content-Disposition`, а если заголовок недоступен —
+`Сводная_ОСВ_<ГК>_<год>_<квартал>.xlsx`.
+
+#### Scenario: Экспорт с фильтром
+- **WHEN** аналитик скачивает свод с фильтром по ЮЛ
+- **THEN** сохраняется xlsx, а ошибка сервера показывается текстом, а не скачивается

openspec/specs/consolidation-setup/spec.md

@@ -0,0 +1,44 @@
+# consolidation-setup Specification
+
+## Purpose
+TBD - created by archiving change demo-prototype. Update Purpose after archive.
+
+## Requirements
+
+### Requirement: Состав модалки «Новая консолидация»
+Модалка [42] SHALL предлагать выбор ГК (`GET /directories/company-groups`), ГСК этой ГК с `kind = gsk`
+(`GET /directories/company-groups/{id}/related-groups`), года и квартала, и показывать **все** незакрытые ЮЛ ГК
+(`GET /directories/legal-entities?company_group_id=&closed=false`, страницы дочитываются по `offset`, пока не получены
+все `total`). Члены выбранной ГСК (`GET /directories/related-groups/{id}` → `members[]`) SHALL быть отмечены
+автоматически; пользователь может снять или добавить отметки.
+
+#### Scenario: Выбор ГСК отмечает её членов
+- **WHEN** аналитик выбирает ГК «Русский бисквит» и её ГСК
+- **THEN** в списке ЮЛ видны все ЮЛ ГК, а члены ГСК («АО "Русский бисквит"», «ООО "Пекарня Счастливочная"») отмечены
+
+#### Scenario: ЮЛ больше одной страницы
+- **WHEN** у ГК больше ЮЛ, чем `limit` одной страницы
+- **THEN** модалка показывает все ЮЛ ГК, а не первую страницу
+
+### Requirement: Создание и переход к версии
+По «Создать» модалка SHALL отправить `POST /consolidations {company_group_id, related_group_id, year, quarter,
+legal_entity_ids}` с отмеченными ЮЛ. При 201 модалка SHALL закрыться, список консолидаций ГК — перечитаться, а созданная
+версия (`VersionCard.id`) — открыться в карточке. При ошибке модалка SHALL остаться открытой и показать `message` из
+`ApiError` (коды `CONSOLIDATION_EXISTS`, `RELATED_GROUP_MISMATCH`, `ENTITY_NOT_IN_GROUP`, `PERIMETER_TOO_SMALL` и 422
+валидации).
+
+#### Scenario: Успешное создание
+- **WHEN** аналитик создаёт консолидацию 2024 Q3 с периметром из ГСК
+- **THEN** открыта карточка версии №1 со статусом «Инициация» и двумя ЮЛ в панели «Организации»
+
+#### Scenario: Консолидация за период уже есть
+- **WHEN** сервер отвечает 409 `CONSOLIDATION_EXISTS`
+- **THEN** модалка не закрывается и показывает текст ошибки сервера
+
+### Requirement: Переход к сводной ОСВ из карточки
+Кнопка «К отчётности» карточки версии SHALL вести на `/groups/:group_id/versions/:version_id/osv` и быть доступна в
+любом статусе версии.
+
+#### Scenario: Переход к своду
+- **WHEN** аналитик нажимает «К отчётности» у версии
+- **THEN** открывается экран сводной ОСВ этой версии

openspec/specs/document-review-ui/spec.md

@@ -0,0 +1,69 @@
+# document-review-ui Specification
+
+## Purpose
+TBD - created by archiving change demo-prototype. Update Purpose after archive.
+
+## Requirements
+
+### Requirement: Экран документа
+Маршрут `/documents/:document_id` SHALL загрузить `GET /documents/{id}` и показать вид по `document_type`: `BALANCE` и
+`INCOME` — проверка формы, `OSV` — просмотр ОСВ; для прочих типов — карточку документа без данных. Шапка экрана SHALL
+показывать тип, ЮЛ-владельца, период и статус документа, кнопку «Назад».
+
+#### Scenario: Открытие формы баланса
+- **WHEN** аналитик открывает документ `BALANCE`
+- **THEN** показан экран проверки формы
+
+### Requirement: Скан рядом с формой
+Для ББ/ОФР экран SHALL показывать исходный файл документа: PDF — постранично через pdf.js из байт
+`GET /files/{file_id}/content?disposition=inline`, полученных клиентом API с токеном (не через `<iframe>` и не прямой
+ссылкой); изображение (png/jpg) — тегом `<img>` из blob; xlsx — без превью, с кнопкой «Скачать исходник».
+
+#### Scenario: PDF под CSP sandbox
+- **WHEN** сервер отдаёт PDF с `Content-Security-Policy: sandbox`
+- **THEN** страницы PDF отрисованы на canvas и листаются
+
+### Requirement: Форма ББ/ОФР — просмотр и правка
+Экран SHALL показывать `GET /documents/{id}/statement`: шапку (ИНН, дата отчёта, единицы — значение и исходное при
+правке; наименование, ОКУД/ОКПО) и таблицу «строка (код, наименование) × колонки» с суммами из `values[]`. Ячейки с
+`confidence < 100` или `is_recognized = false` SHALL подсвечиваться как «требует внимания», с `is_modified = true` — как
+«исправлено» с исходным значением `original_amount` в подсказке. Единицы (`header.units`) SHALL выводиться над таблицей.
+Пока документ не `CONFIRMED`, ячейка SHALL быть редактируемой: ввод проверяется по формату суммы (до 2 знаков после
+точки, знак минус допустим, пустое — `null`), сохранение отправляет `PATCH /documents/{id}/statement {values:
+[{line_id, column_id, amount}]}` суммой-строкой, ответ заменяет состояние экрана. Правка шапки (ИНН, дата отчёта,
+единицы) SHALL отправляться тем же `PATCH` в `header`; `inn: null` не отправляется.
+
+#### Scenario: Исправление ячейки
+- **WHEN** аналитик меняет значение ячейки и сохраняет
+- **THEN** ячейка помечена «исправлено», проверки пересчитаны по ответу сервера, акцепт снят
+
+#### Scenario: Неверный формат суммы
+- **WHEN** аналитик вводит «12,3,4»
+- **THEN** запрос не отправляется, поле показывает ошибку формата
+
+### Requirement: Проверки и их акцепт
+Экран SHALL показывать `checks`: жёсткие (`failed`), мягкие (`soft_failed`), межформенную (`cross_form`) и акцепт
+(`accepted`: кто, когда, комментарий). При непустом `failed` и `accepted = null` SHALL быть доступно «Принять с
+комментарием»: комментарий 1–2000 символов → `POST /documents/{id}/statement/checks/accept {comment}`.
+
+#### Scenario: Акцепт нарушений
+- **WHEN** есть жёсткие нарушения и аналитик принимает их с комментарием
+- **THEN** блок проверок показывает акцепт, нарушения остаются видимыми
+
+### Requirement: Подтверждение документа
+Кнопка «Подтвердить» SHALL отправлять `POST /documents/{id}/confirm` и быть недоступна для `CONFIRMED` и `ERROR`. При 409
+`CHECKS_NOT_PASSED` экран SHALL показать `detail.failures[]` и предложить акцепт; при 409 `PERIOD_REQUIRED` — подсказать
+исправить дату отчёта; прочие ошибки — `message`. После успеха экран SHALL перейти в режим только чтения.
+
+#### Scenario: Подтверждение с неакцептованными нарушениями
+- **WHEN** аналитик подтверждает форму с жёсткими нарушениями без акцепта
+- **THEN** показан список нарушений из ответа и кнопка «Принять с комментарием»
+
+### Requirement: ОСВ-документ
+Для `OSV` экран SHALL показывать строки `GET /documents/{id}/entries` (все страницы, `limit` ≤ 2000) деревом по
+`parent_entry_id` с колонками: счёт/субсчёт, контрагент, ИНН, сальдо на начало Дт/Кт, обороты Дт/Кт, сальдо на конец
+Дт/Кт (суммы — строками с разделителями разрядов, рубли), только чтение. Кнопка «Подтвердить» — как для форм.
+
+#### Scenario: Подтверждение ОСВ
+- **WHEN** аналитик подтверждает ОСВ-документ `NEEDS_CHECK`
+- **THEN** документ становится «Загружен», версия, к которой он подходит, переходит в `DATA_CORRECTION`

openspec/specs/primary-files-ui/spec.md

@@ -0,0 +1,43 @@
+# primary-files-ui Specification
+
+## Purpose
+TBD - created by archiving change demo-prototype. Update Purpose after archive.
+
+## Requirements
+
+### Requirement: Загрузка файлов ЮЛ в контексте версии
+Панель «Файлы ЮЛ» [39]/[40], открытая из строки ЮЛ карточки версии, SHALL загружать выбранные файлы одним запросом
+`POST /legal-entities/{id}/files?consolidation_version_id={version_id}` (multipart, поле `files` повторяется), без
+других полей формы. Тип и период документа не спрашиваются. После ответа панель SHALL показать итог: принятые файлы
+(`accepted[].name`) и отклонённые с причиной (`rejected[].name` + `message`). Ответ 422 с телом `UploadResult` SHALL
+трактоваться как «ни один файл не принят» с тем же показом `rejected[]`; ответ 422 с `detail` (`ENTITY_NOT_IN_PERIMETER`)
+и прочие ошибки — показом `message`.
+
+#### Scenario: Часть файлов отклонена
+- **WHEN** аналитик загружает ОСВ-файл и файл, уже загруженный ранее у этого ЮЛ
+- **THEN** первый показан принятым, второй — отклонённым с текстом причины `DUPLICATE_FILE` от сервера
+
+#### Scenario: Все файлы отклонены
+- **WHEN** сервер отвечает 422 с телом `UploadResult`
+- **THEN** панель показывает каждый отклонённый файл с причиной, а не общую ошибку
+
+### Requirement: Список файлов и документов ЮЛ
+Панель SHALL показывать файлы ЮЛ из `GET /legal-entities/{id}/files` (новые первыми): имя, статус файла по-русски
+(«Обработка» для `UPLOADED`/`PROCESSING`, «Ошибка» с причиной из `job` для `ERROR`) и вложенные `documents[]` — тип
+(«ОСВ <счёт>», «Бух. баланс», «ОФР», «Расшифровка», «Прочее»), период («2024 К1», «2024 · 9 мес.», «период не
+определён»), статус документа («Требуется проверка», «Загружен» для `CONFIRMED`, «Ошибка»). Документы `OSV`, `BALANCE`,
+`INCOME` SHALL быть ссылками на `/documents/:document_id`.
+
+#### Scenario: PDF с двумя формами
+- **WHEN** файл `aep_6.pdf` распознан
+- **THEN** под файлом видны два документа — «Бух. баланс» и «ОФР» со статусом «Требуется проверка», каждый открывает
+  экран проверки
+
+### Requirement: Опрос до окончания распознавания
+Пока панель открыта и среди файлов есть `UPLOADED` или `PROCESSING`, панель SHALL перечитывать список раз в 5 секунд и
+SHALL прекратить опрос, когда таких файлов нет или панель закрыта. При закрытии панели карточка версии SHALL
+перечитываться (обновить ячейки чек-листа).
+
+#### Scenario: Опрос останавливается
+- **WHEN** все файлы ЮЛ перешли в `PROCESSED` или `ERROR`
+- **THEN** запросы списка файлов прекращаются