From 9b03b0f51c55e8138e368f83aa6fed72bdc8846f Mon Sep 17 00:00:00 2001 From: Andrey Epifancev Date: Thu, 8 Oct 2026 00:24:23 +0400 Subject: [PATCH] =?UTF-8?q?docs(openspec):=20change=20demo-prototype=20?= =?UTF-8?q?=E2=80=94=20=D0=BF=D1=80=D0=BE=D1=82=D0=BE=D1=82=D0=B8=D0=BF=20?= =?UTF-8?q?=D0=BF=D1=83=D1=82=D0=B8=20=D0=B4=D0=BE=20=D1=81=D0=B2=D0=BE?= =?UTF-8?q?=D0=B4=D0=BD=D0=BE=D0=B9=20=D0=9E=D0=A1=D0=92=20(#3)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01EAKRDNzXtRrwmWz9z6PZu3 --- .../changes/demo-prototype/.openspec.yaml | 2 + openspec/changes/demo-prototype/design.md | 124 ++++++++++++++++++ openspec/changes/demo-prototype/proposal.md | 57 ++++++++ .../specs/consolidated-osv-ui/spec.md | 39 ++++++ .../specs/consolidation-setup/spec.md | 39 ++++++ .../specs/document-review-ui/spec.md | 64 +++++++++ .../specs/primary-files-ui/spec.md | 38 ++++++ 7 files changed, 363 insertions(+) create mode 100644 openspec/changes/demo-prototype/.openspec.yaml create mode 100644 openspec/changes/demo-prototype/design.md create mode 100644 openspec/changes/demo-prototype/proposal.md create mode 100644 openspec/changes/demo-prototype/specs/consolidated-osv-ui/spec.md create mode 100644 openspec/changes/demo-prototype/specs/consolidation-setup/spec.md create mode 100644 openspec/changes/demo-prototype/specs/document-review-ui/spec.md create mode 100644 openspec/changes/demo-prototype/specs/primary-files-ui/spec.md diff --git a/openspec/changes/demo-prototype/.openspec.yaml b/openspec/changes/demo-prototype/.openspec.yaml new file mode 100644 index 0000000..01660ba --- /dev/null +++ b/openspec/changes/demo-prototype/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-10-08 diff --git a/openspec/changes/demo-prototype/design.md b/openspec/changes/demo-prototype/design.md new file mode 100644 index 0000000..1332ea7 --- /dev/null +++ b/openspec/changes/demo-prototype/design.md @@ -0,0 +1,124 @@ +## Context + +arm-web выделен из `arm-core/web` командой фронта (3 коммита 06–07.10.2026) и дополнен экранами групп, консолидаций и +загрузки. Обзор 08.10.2026: список консолидаций и карточка версии работают с arm-core; загрузка теряет ошибки (нет +`await`, лишние поля формы); проверка документов (`PDFResultViewer`, `FileViewer`, `FileUploaderModel`) скопирована из +старого АРМ и ходит в `/fsl/...`, `/osv/by-file-id`, `POST /files` мимо клиента API; сводной ОСВ нет; `tsc` — 185 ошибок, +biome — 276. + +Демо — 09.10.2026 на локальном стенде; затем прототип уходит в контур на тестирование заказчику и переезжает в +`arm-core/web`, где развивается дальше. Поэтому код держится соглашений шаблона `arm-core/web`. + +Источник контракта — `../docs/dev/frontend-api-guide.md` (§5.5–§5.7) и схемы `arm-core/api/src/schemas/`. + +## Goals / Non-Goals + +**Goals:** аналитик на стенде проходит путь «создание консолидации → загрузка ОСВ и PDF → проверка и подтверждение → +сводная ОСВ» без сбоев и консоли разработчика; `make check` зелёный; все запросы — к API arm-core. + +**Non-Goals:** см. proposal.md («Non-goals»). + +## Decisions + +### D-1. Чинить на месте, новое — по образцу arm-core/web (согласовано 08.10.2026) +Оставляем `api/client.ts`, `auth/*`, список консолидаций, карточку версии, модалку создания (с правками), Redux-слайсы +(типизируем). Новые экраны держат состояние в локальных хуках (`useStatement`, `useDocumentEntries`, +`useConsolidatedOsv`) как `arm-core/web/src/widgets/Admin/hooks.ts`. Альтернативы — генерация типов из OpenAPI (новая +dev-зависимость, доступность в Nexus не проверена) и переписывание с нуля (не успеть) — отклонены владельцем. + +### D-2. Типы DTO руками +`src/types/` повторяют схемы arm-core только для используемых эндпоинтов: `Page`, `UploadResult`, `FileOut`, +`DocumentBrief`, `DocumentOut`, `StatementOut` (`HeaderOut`, `ColumnOut`, `LineOut`, `ValueOut`, `ChecksOut`), +`EntryOut`, `ConsolidatedRowOut`, `OsvSummaryOut`, `VersionCard` (исправления: `is_head_entity: boolean`, +`entity_type: 'ЮЛ' | 'ИП' | null`, `osv_accounts: string[]`, `changed_by` — UUID). `Decimal` и даты приходят строками — +в типах `string`. + +### D-3. Деньги — строки +Суммы не превращаются в `number`. Чистые функции `src/utils/money.ts`: `formatAmount(s)` — разделители разрядов и два +знака без арифметики над float; `parseAmountInput(s)` — нормализация ввода (пробелы, запятая → точка) и проверка +`^-?\d+(\.\d{1,2})?$`, пустое — `null`. Единицы ББ/ОФР — из `header.units`, ОСВ — рубли. + +### D-4. Бинарные ответы — `apiFetchBlob` +`src/api/client.ts` получает `apiFetchBlob(path) → {blob, filename | null}` с той же обработкой токена, 401 и ошибок +(тело ошибки — JSON). Используется для скана (`blob.arrayBuffer()` → pdf.js) и экспорта (сохранение через +`URL.createObjectURL` + ``). Имя экспорта — из `Content-Disposition` (`filename*=UTF-8''…` или `filename=`), +иначе `exportFilename(group, year, quarter)`. + +### D-5. Dev-proxy вместо CORS +`rsbuild.config.ts`: `server.proxy['/api'] → process.env.ARM_CORE_URL ?? 'http://localhost:8000'`; в dev +`REACT_APP_API_URL` пустой. Запросы идут с того же источника: нет CORS и читается `Content-Disposition` (follow-up +docs#58 O-1 на фронте обходится). В контуре SPA отдаёт сам arm-core — тот же источник, код не меняется. Гайд фронта §2 +(где `REACT_APP_API_URL=http://localhost:8000`) остаётся верным для варианта без proxy. + +### D-6. Просмотр PDF +Из `widgets/PDFResultViewer/IFrameBlock.tsx` сохраняется только постраничный рендер pdf.js (canvas, масштаб, листание); +загрузка — `apiFetchBlob('/files/{id}/content?disposition=inline')` → `arrayBuffer`. Компонент переименовывается в +`widgets/DocumentReview/PdfPages.tsx`. Worker pdf.js подключается из пакета `pdfjs-dist` сборкой (без CDN — в контуре +внешнего интернета нет). `PDFDataViewer.tsx`, `types.ts`, `styles.module.css` старого АРМ удаляются. + +### D-7. Экран документа +`layouts/DocumentPage.tsx` (`/documents/:document_id`) → `GET /documents/{id}` → `widgets/DocumentReview/StatementReview` +(BALANCE/INCOME) или `widgets/DocumentReview/OsvDocument` (OSV). Чистые функции: `buildStatementGrid(statement)` — +матрица строк × колонок по `column_id` (не по индексу), `buildEntryTree(entries)` — дерево по `parent_entry_id` с +сохранением `row_number`. Правка ячейки — локальный черновик ячеек и «Сохранить» одним `PATCH` со всеми изменёнными +ячейками; ответ сервера заменяет состояние (сервер пересчитывает проверки и сбрасывает акцепт). + +### D-8. Панель файлов +`widgets/FilesDrawer` переписывается: `UploadDocumentsModal` → один запрос со всеми файлами, итог из +`summarizeUpload(result)`; список — `FilesList` с вложенными документами; подписи — `fileStatusLabel`, +`documentTypeLabel`, `periodLabel`, `documentStatusLabel` (чистые функции). Опрос — `useDocumentsPolling` с остановкой, +когда нет `UPLOADED`/`PROCESSING`. Слайс `files` типизируется или заменяется локальным хуком (решает исполнитель по +месту, без смены поведения). + +### D-9. Сводная ОСВ +`layouts/ConsolidatedOsvPage.tsx` + `widgets/ConsolidatedOsv/` (`useConsolidatedOsv`, `OsvFilters`, `OsvTable`, +`OsvGaps`). Таблица — antd `Table` с серверной пагинацией (`limit` 500). Фильтры — query-параметры как в API; ЮЛ — +из `VersionCard.members`. + +### D-10. Тесты — vitest на чистых функциях +`vitest` (devDependency), `npm test` → `vitest run`, цель `make test` входит в `make check`. Покрытие по TDD: money, +`summarizeUpload`, подписи статусов/типов/периодов, `normalizeData` карточки версии, `exportFilename` и разбор +`Content-Disposition`, `buildStatementGrid`, `buildEntryTree`. Компоненты — ручной демо-сценарий. + +## Демо-сценарий (приёмка) + +Стенд по `../docs/dev/qa-guide.md` §4 и §6.8 (профиль `services`: tabular-parser, scan-gateway, scan-emulator), +`make seed-dev`, вход `ka_rf@armka.local` (или пользователь из гайда с правами EDIT на ГК «Русский бисквит»). + +1. Группы → «Русский бисквит» → «Новая консолидация»: ГСК, 2024, Q3 → члены ГСК отмечены → «Создать» → открыта версия №1. +2. Панель «Организации» → РБ → «Файлы»: загрузить `fixtures/osv/rb/2024-Q{1,2,3}/*`; то же для Счастливочной + (`fixtures/osv/schastl/2024-Q{1,2,3}/*`). Дождаться «Требуется проверка», подтвердить ОСВ-документы (экран ОСВ). +3. Загрузить `fixtures/ocr/…/aep_6.pdf` одному из ЮЛ → ББ и ОФР «Требуется проверка» → открыть ББ: скан слева, форма + справа, исправить ячейку, принять нарушения с комментарием (если есть), подтвердить. +4. «К отчётности» → сводная ОСВ: 1385 строк, 22 документа, 7 пробелов; фильтр Счастливочная + «бисквит» → строка `60.01` + по `qa-guide` §7.2; «Скачать xlsx». + +Шаги API (2–4) перед браузерным прогоном проверяются curl-скриптом; браузерный прогон — владелец. + +## Risks / Trade-offs + +- [Круг «ядро + scan-gateway + эмулятор» на стенде целиком не прогонялся (`qa-guide` §6.8: «сервис проверяется + отдельно»)] → Задача 1 плана — прогон до кода. Если сломан: issue в arm-core/scan-gateway, а форма ББ/ОФР на демо — + из xlsx (`fixtures/statements-xlsx/mezheninovskaya`, `qa-guide` §6.9), скан — заглушка «превью недоступно». +- [Объём к завтра] → порядок задач от критичного к желательному; экспорт и пробелы — последними. +- [Ручные типы расходятся с API] → типы только по используемым полям, сверка со схемами при ревью. +- [Подтверждение 22 ОСВ кликами долго на демо] → в README — скрипт подтверждения из `qa-guide` §7.1; на демо можно + показать подтверждение одного документа, остальные подготовить заранее. + +## Migration Plan + +Один PR `feat/3-demo-prototype` → `test`. Откат — revert PR. Перенос в `arm-core/web` — отдельная задача после демо. + +## Open Questions + +- Какой ЮЛ «владеет» `aep_6.pdf` в фикстурах (ИНН в шапке) — влияет только на `counterparty_check` (не блокирует + подтверждение); выясняется в задаче 1. + +## Decisions made without discussion + +- 08.10.2026 — D-5 dev-proxy `/api` вместо `REACT_APP_API_URL=http://localhost:8000`. Обоснование: снимает CORS и + нечитаемый `Content-Disposition` без правок arm-core. Цена ошибки: низкая — переменная `REACT_APP_API_URL` продолжает + работать, proxy только в dev. +- 08.10.2026 — D-6 worker pdf.js из пакета, без CDN. Обоснование: в контуре нет внешнего интернета. Цена ошибки: низкая. +- 08.10.2026 — D-7 правка ячеек пакетом по «Сохранить», а не по каждой ячейке. Обоснование: меньше запросов, сервер + принимает до 5000 ячеек и пересчитывает проверки один раз. Цена ошибки: низкая — поведение меняется в одном хуке. diff --git a/openspec/changes/demo-prototype/proposal.md b/openspec/changes/demo-prototype/proposal.md new file mode 100644 index 0000000..7e2033d --- /dev/null +++ b/openspec/changes/demo-prototype/proposal.md @@ -0,0 +1,57 @@ +## Why + +В пятницу 09.10.2026 — демо владельцу и бизнесу, затем прототип уходит в контур банка на тестирование заказчику +(и переезжает внутрь `arm-core/web`). Сейчас arm-web не проводит аналитика по пути «консолидация → первичка → +проверка → сводная ОСВ»: загрузка теряет ошибки, проверка документов ходит в эндпоинты старого АРМ, экрана сводной ОСВ +нет, `make check` красный (tsc — 185 ошибок, biome — 276). + +## What Changes + +- Модалка «Новая консолидация» [42]: предотметка членов ГСК, догрузка всех ЮЛ ГК, ошибки API, переход к новой версии. +- Панель «Файлы ЮЛ» [39]/[40] переписана: загрузка в контексте версии с итогом «принято / отклонено», файлы со + вложенными документами, переход к документу, опрос до окончания распознавания. +- Новый экран документа `/documents/:document_id`: для ББ/ОФР [41]/[41-02] — скан PDF рядом с формой, правка ячеек, + проверки и их акцепт, подтверждение; для ОСВ — дерево строк только для чтения и подтверждение. +- Новый экран «Сводная ОСВ» [30] `/groups/:group_id/versions/:version_id/osv`: таблица, фильтры, пробелы, счётчик + несопоставленных, экспорт xlsx. +- `api/client.ts`: `apiFetchBlob` для бинарных ответов (скан, xlsx); dev-proxy `/api` в `rsbuild.config.ts`. +- **BREAKING (внутреннее):** удалены `layouts/FileViewer.tsx`, `components/FileUploaderModel.tsx`, + `widgets/PDFResultViewer/PDFDataViewer.tsx`, `services/api/mocks.ts`; маршрут `/files/:file_id` заменён на + `/documents/:document_id`. +- `make check` зелёный: biome + tsc + vitest + build; добавлен `vitest` (dev) для чистых функций. + +## Capabilities + +### New Capabilities +- `consolidation-setup`: создание консолидации ГК за период из модалки и переход к её версии. +- `primary-files-ui`: загрузка первичных файлов ЮЛ в контексте версии и список файлов/документов со статусами. +- `document-review-ui`: проверка и подтверждение документа — форма ББ/ОФР со сканом PDF, ОСВ-документ. +- `consolidated-osv-ui`: сводная ОСВ версии — просмотр, фильтры, пробелы, экспорт. + +### Modified Capabilities +(нет — `openspec/specs/` пуст) + +## Impact + +- Экраны макета: [03], [34], [39], [40], [41], [41-02], [42], [30]. +- Эндпоинты arm-core (`/api/v1`), только существующие: + `GET /directories/company-groups`, `GET /directories/company-groups/{id}/related-groups`, + `GET /directories/related-groups/{id}`, `GET /directories/legal-entities`, `POST /consolidations`, + `GET /company-groups/{id}/consolidations`, `GET /consolidations/versions/{id}`, + `POST /legal-entities/{id}/files`, `GET /legal-entities/{id}/files`, `GET /files/{id}/content`, + `GET /documents/{id}`, `GET /documents/{id}/entries`, `POST /documents/{id}/confirm`, + `GET|PATCH /documents/{id}/statement`, `POST /documents/{id}/statement/checks/accept`, + `GET /consolidations/versions/{id}/osv`, `GET …/osv/summary`, `GET …/osv/export`. +- Зависимости: `vitest` (devDependency). +- Код: `src/api/`, `src/services/api/`, `src/types/`, `src/widgets/{NewConsoleModal,FilesDrawer,ConsoleTable,…}`, + новые `src/widgets/DocumentReview/`, `src/widgets/ConsolidatedOsv/`, `src/layouts/`, `src/App.tsx`, `rsbuild.config.ts`, + `Makefile`, `README.md`. + +## Non-goals + +- Блокировка версии («Взять в работу»), сопоставление контрагентов [32-*], экран чек-листа [37], комментарии, + удаление файлов, смена периметра и ручные переходы статусов. +- Правка строк ОСВ (в API нет), картинки страниц и координаты ячеек в скане (в API нет). +- Генерация типов из OpenAPI; автотесты компонентов. +- Перенос в `arm-core/web` и сборка под контур — отдельной задачей после демо. +- Изменения arm-core / scan-gateway: найденный пробел — отдельная issue в том репозитории. diff --git a/openspec/changes/demo-prototype/specs/consolidated-osv-ui/spec.md b/openspec/changes/demo-prototype/specs/consolidated-osv-ui/spec.md new file mode 100644 index 0000000..9c52797 --- /dev/null +++ b/openspec/changes/demo-prototype/specs/consolidated-osv-ui/spec.md @@ -0,0 +1,39 @@ +## ADDED 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, а ошибка сервера показывается текстом, а не скачивается diff --git a/openspec/changes/demo-prototype/specs/consolidation-setup/spec.md b/openspec/changes/demo-prototype/specs/consolidation-setup/spec.md new file mode 100644 index 0000000..37df316 --- /dev/null +++ b/openspec/changes/demo-prototype/specs/consolidation-setup/spec.md @@ -0,0 +1,39 @@ +## ADDED 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** открывается экран сводной ОСВ этой версии diff --git a/openspec/changes/demo-prototype/specs/document-review-ui/spec.md b/openspec/changes/demo-prototype/specs/document-review-ui/spec.md new file mode 100644 index 0000000..98ca25f --- /dev/null +++ b/openspec/changes/demo-prototype/specs/document-review-ui/spec.md @@ -0,0 +1,64 @@ +## ADDED 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 с токеном (не через `