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

Гайд тестировщика: фронт arm-web — запуск и UI-чек-лист (#66)

Browse Source 
- §1–§4: что есть в UI arm-web, клонирование (ветка test, tabular-parser и
  scan-gateway для сборки сервисов), запуск make start с dev-proxy /api, вход.
- Новый §8 «Сквозной сценарий в UI»: W1–W35 по экранам макета [03], [34], [42],
  [39], [40], [41], [30]; контрольные цифры §7.2 в формате экрана; что в UI не баг.
- §6.1: дефект уведомлений /admin (arm-web#7) и обход через arm-core/web.
- §6.6, §6.9, §7: какие сценарии есть в UI; §9, §11, §12 — ограничения, куда
  заводить баги UI, проблемы запуска фронта. Разделы 8–11 стали 9–12.

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-08 11:16:37 +04:00
parent 55b79bb535
commit 8be9a20825
1 changed files with 210 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

249
dev/qa-guide.md
View File

@ -1,7 +1,11 @@
# Гайд тестировщика: локальный стенд АРМ КА (Срезы 0–2c, 3b, 4)
# Гайд тестировщика: локальный стенд АРМ КА (Срезы 0–2c, 3b, 4 и фронт arm-web)
Документ для ручного тестирования текущего `main`. Путь проверен 05.10.2026 на macOS (Docker 28, compose 2.34,
Node 24, uv 0.10): от пустого каталога до экрана администратора — около 15 минут, из них 10 — скачивание образов.
Документ для ручного тестирования текущего `main` бэкенда и ветки `test` фронта `arm-web`. Путь проверен 05.10.2026 на
macOS (Docker 28, compose 2.34, Node 24, uv 0.10): от пустого каталога до экрана администратора — около 15 минут, из них
10 — скачивание образов. Сценарий в UI (раздел 8) проверен 08.10.2026 в Chrome 1600×1000 на данных РБ 2024 Q3.
Как читать: раздел 4 — поднять стенд, раздел 8 — пройти основной путь аналитика в браузере, разделы 6–7 — то же и
глубже через API (Swagger/curl): там проверяются права, коды ошибок и граничные случаи, до которых UI не доходит.
## 1. Что сейчас есть и чего нет
@ -13,7 +17,10 @@ Node 24, uv 0.10): от пустого каталога до экрана адм
офис видит всё, филиал — только свои ГК.
- Импорт справочников из выгрузки ЕЦП CRM (xlsx/csv) с пробным прогоном и отчётом.
- Администрирование: пользователи, роли, матрица «роль × право», защита последнего администратора.
- Фронтенд: страница `/admin` («Пользователи и роли»). Другого UI нет.
- Фронтенд **arm-web** (демо-прототип, раздел 8): группы компаний, консолидации и создание консолидации, панель
«Организации» с чек-листом CSV, загрузка файлов ЮЛ с опросом статуса, просмотр ОСВ-документа с подтверждением, проверка
форм ББ/ОФР рядом со сканом PDF (правка, акцепт нарушений, подтверждение), сводная ОСВ с фильтрами, пробелами и
экспортом xlsx; администрирование `/admin` («Пользователи и роли»).
- Журнал аудита в БД (`dkb.audit_event`).
- Загрузка файлов ОСВ через API (`POST /legal-entities/{id}/files`), распознавание реальным `tabular-parser`, разбор
результата в документы и строки ОСВ, статусы файла и документа, автозамена версий, подтверждение документа, удаление
@ -22,7 +29,7 @@ Node 24, uv 0.10): от пустого каталога до экрана адм
`aep_3.pdf` / `aep_6.pdf` из `fixtures/ocr`.
- Консолидация через API (Срез 4): версии за период, периметр, блокировка «взять в работу», статусы, привязка подтверждённых
документов, чек-лист, сводная ОСВ, ручное сопоставление контрагента, экспорт xlsx (раздел 7; полный прогон на данных РБ и
контрольные цифры — 7.1–7.3). UI консолидации — другой исполнитель.
контрольные цифры — 7.1–7.3). Основной путь консолидации есть и в UI arm-web — раздел 8.
- План счетов — полная выгрузка 1С заказчика, 488 строк (arm-core #25): субсчета реальных ОСВ (66.01, 76.07.x, забалансовые,
буквенные `01.К`) резолвятся в `account_id`. Границы входов консолидации: периметр ≤ 500 ЮЛ, комментарий статуса ≤ 1000, поиск
`q` ≤ 500 символов (arm-core #26, раздел 6.5).
@ -32,8 +39,12 @@ Node 24, uv 0.10): от пустого каталога до экрана адм
**Нет (это не баги):**
- Экранов справочников ГК/ЮЛ/ГСК — проверяются только через Swagger (`/docs`) или curl.
- Экрана загрузки и таблицы ОСВ (подсрез 2d), экранов консолидации (API есть, раздел 7), экрана «Проверка распознавания» ББ/ОФР (API есть, раздел 6.9), экрана распознавания PDF, шахматки, КФО — следующие срезы.
- Экранов справочников ГК/ЮЛ/ГСК (пункты меню «ГК и организации», «ЮЛ вне ГК» — заглушки) — проверяются только через
Swagger (`/docs`) или curl.
- В UI нет: блокировки версии («Взять в работу»), смены периметра и ручных переходов статусов, сопоставления
контрагентов в сводной ОСВ, экрана чек-листа (только CSV), комментариев к документам, удаления файлов, правки строк
ОСВ. Это проверяется через API (разделы 6.6, 6.9, 7). Шахматка, КФО, «Единое хранилище», «Журнал действий» —
следующие срезы (в UI — заглушки или неактивные вкладки).
- Настоящего входа через SSO банка. Вход — dev-форма по email без пароля.
## 2. Что установить и проверить из ПО
@ -46,25 +57,38 @@ Node 24, uv 0.10): от пустого каталога до экрана адм
| `uv` | ≥ 0.4 (проверено 0.10) | `uv --version` | `curl -LsSf https://astral.sh/uv/install.sh \| sh`; Python 3.11 `uv` скачает сам |
| Node.js + npm | Node ≥ 20 LTS (проверено 24.7) | `node --version && npm --version` | nodejs.org или `nvm install --lts` |
| `make`, `curl` | любые | `make --version`, `curl --version` | macOS: Xcode Command Line Tools (`xcode-select --install`); Linux: `build-essential` |
| Свободные порты | 5432, 4222, 8222, 9000, 9001 (compose), 8000 (бэкенд), 3000 (фронт) | `lsof -i :5432` и т. д. пусто | закрыть локальный PostgreSQL/MinIO или сменить порты в `docs/dev/.env` и `arm-core/api/.env` |
| Свободные порты | 5432, 4222, 8222, 9000, 9001 (compose), 8000 (бэкенд), 8001 (tabular-parser), 3000 (фронт) | `lsof -i :5432` и т. д. пусто | закрыть локальный PostgreSQL/MinIO или сменить порты в `docs/dev/.env` и `arm-core/api/.env` |
| Ресурсы | Docker: ≥ 4 ГБ RAM, ≥ 3 ГБ диска под образы и тома | — | — |
| Доступ в интернет | нужен один раз: образы Docker Hub, PyPI, npm | — | Nexus банка не требуется |
Необязательно, но удобно: клиент PostgreSQL (DBeaver или `psql`) для просмотра аудита; Postman или аналог — Swagger
на `/docs` достаточно.
Браузер — любой современный (Chrome, Firefox, Safari, Edge).
Браузер — свежий Chrome, Firefox, Safari или Edge (просмотр PDF использует современный pdf.js; в старых браузерах скан
не откроется). Удобный размер окна — от 1600×1000: на нём сверялся макет.
## 3. Клонирование
Три репозитория должны лежать **рядом**, в одном каталоге, под именами `docs`, `arm-core`, `fixtures` (в коде пути
вида `../docs/...`):
Репозитории должны лежать **рядом**, в одном каталоге, под именами `docs`, `arm-core`, `fixtures`, `arm-web` (в коде пути
вида `../docs/...`, `../fixtures/...`):
```bash
mkdir arm-ka && cd arm-ka
git clone ssh://git@git.aepif.ru:2222/RSHB/arm-ka-docs.git docs
git clone ssh://git@git.aepif.ru:2222/RSHB/arm-core.git arm-core
git clone ssh://git@git.aepif.ru:2222/RSHB/arm-ka-fixtures.git fixtures
git clone -b test ssh://git@git.aepif.ru:2222/RSHB/arm-web.git arm-web
```
Фронт тестируется с ветки **`test`** репозитория `arm-web` (интеграционная ветка прототипа; `main` там — исходная копия
без экранов консолидации). Обновление: `git -C arm-web pull`.
Сервисы распознавания собираются из исходников, поэтому для загрузки файлов (6.6–7, раздел 8) рядом нужен ещё
`tabular-parser`, для PDF (6.8, 8.5) — `scan-gateway`:
```bash
git clone ssh://git@git.aepif.ru:2222/RSHB/arm-tabular-parser.git tabular-parser
git clone ssh://git@git.aepif.ru:2222/RSHB/arm-scan-gateway.git scan-gateway
```
Без SSH-ключа можно клонировать по HTTPS с логином и паролем Gitea: `https://git.aepif.ru/RSHB/arm-core.git` и т. д.
@ -109,19 +133,28 @@ docker compose -f ../docs/dev/docker-compose.yml --profile services up -d --buil
curl -s localhost:8001/healthcheck # nats: ok
```
### 4.3 Фронтенд (второй терминал)
### 4.3 Фронтенд arm-web (второй терминал, из корня `arm-ka`)
```bash
cd arm-core/web
npm install
REACT_APP_API_URL=http://localhost:8000 REACT_APP_ROOT_PATH=/ npm run start
cd arm-web
make install # npm install; первый раз — несколько минут
make start # dev-сервер rsbuild на :3000, браузер откроется сам
```
Откроется <http://localhost:3000/> с формой «Вход для разработки». Две переменные окружения обязательны: без них
фронт ищет API на своём порту и путь приложения как на платформе банка.
Откроется <http://localhost:3000/> с формой «Вход для разработки». Запросы `/api` dev-сервер проксирует на ядро
(`ARM_CORE_URL`, по умолчанию `http://localhost:8000`), поэтому `REACT_APP_API_URL` задавать не нужно, а CORS не мешает
скачиванию файлов. Ядро на другом адресе: `ARM_CORE_URL=http://host:port make start`.
Не используйте `npm run build` для тестирования: в production-сборке dev-формы входа нет, страница показывает
«Вход выполняется через РАИСА».
Запускайте именно `make start`: он задаёт `REACT_APP_ROOT_PATH=/`. Голый `npm run start` ждёт путь приложения как на
платформе банка (`/aurora/apps/fastapi-dkb-armka`) и показывает белый экран. Не используйте и `make build`/`npm run build`
для тестирования: в production-сборке dev-формы входа нет, страница показывает «Вход выполняется через РАИСА».
Проверка сборки фронта (линтер, типы, юнит-тесты, сборка) — `make check` в `arm-web`; ручному тестированию она не нужна.
Старый фронт `arm-core/web` (только `/admin`) по-прежнему запускается
`cd arm-core/web && npm install && REACT_APP_API_URL=http://localhost:8000 REACT_APP_ROOT_PATH=/ npm run start` — на том же
порту 3000, поэтому одновременно с arm-web не поднимайте. Он нужен, пока в arm-web не исправлены уведомления
администрирования (arm-web#7, раздел 6.1).
Настройки из `api/.env.example` (`DEBUG=true`, `AUTH_DEV_ISSUER=true`, `CORS_ORIGINS=`, `FORWARDED_ALLOW_IPS=127.0.0.1`)
для локального стенда менять не нужно: `DEBUG=true` включает документацию API на `/docs`, dev-вход и разрешает `make seed-dev`.
@ -137,7 +170,9 @@ REACT_APP_API_URL=http://localhost:8000 REACT_APP_ROOT_PATH=/ npm run start
В форме введите **email** dev-пользователя (не имя и не логин) и нажмите «Войти (dev)». Пароля нет. Это единственная форма
входа АРМ: страница с полями «Имя пользователя / пароль» — это Gitea, а не стенд. Токен живёт в текущей вкладке
(`sessionStorage`), новая вкладка — новый вход. Токен действует 8 часов.
(`sessionStorage`), новая вкладка — новый вход. Токен действует 8 часов; после истечения форма входа появится снова с
сообщением «Сессия истекла». Кнопки «Выйти» нет: чтобы сменить пользователя, откройте новую вкладку (или закройте текущую).
Главная `/` после входа показывает ФИО dev-пользователя («Dev: Аналитик ГО») и его роли («Роли: KA_GO»).
| Email | Роль | Филиал | Что видит |
|---|---|---|---|
@ -182,6 +217,11 @@ curl -s localhost:8000/api/v1/me -H "Authorization: Bearer $TOKEN"
### 6.1 Администрирование (UI `/admin`, вход `admin@armka.local`)
Пункт меню «Система → Пользователи и роли». **Известный дефект arm-web#7:** в arm-web на этом экране не появляются
уведомления (ни об успехе, ни об ошибке), в консоли браузера — `message.error is not a function`, модалка создания при ошибке
остаётся открытой без текста. Пока он не исправлен, сценарии с ожиданием «уведомлением» (A3, A6, A8, A10) проходите на старом
фронте `arm-core/web` (раздел 4.3) или проверяйте код ответа во вкладке Network.
| № | Шаги | Ожидание |
|---|---|---|
| A1 | Открыть «Система → Пользователи и роли» | таблица из 7 пользователей, вкладки «Пользователи» и «Матрица прав» |
@ -194,7 +234,7 @@ curl -s localhost:8000/api/v1/me -H "Authorization: Bearer $TOKEN"
| A8 | Деактивировать единственного активного админа | 409 `LAST_ADMIN` |
| A9 | Матрица прав: роли EXPERT добавить `EXPORT`, сохранить | `/me` эксперта содержит `EXPORT` |
| A10 | Матрица прав: снять `USERS_ADMIN` у ADMIN, когда других админов нет | 409 `LAST_ADMIN` |
| A11 | Войти `expert@armka.local`, открыть `/admin` напрямую | «Нет доступа», пункт меню скрыт, запросов к `/admin/*` нет (вкладка Network) |
| A11 | Войти `expert@armka.local`, открыть `/admin` напрямую | «Нет доступа» / «Раздел доступен пользователям с правом администрирования», запросов к `/admin/*` нет (вкладка Network). Пункт меню в arm-web виден всем ролям — так в прототипе, в `arm-core/web` он скрыт |
| A12 | После правки своих ролей обновить страницу | профиль в шапке обновился только после перезагрузки (известное ограничение) |
### 6.2 Справочники (Swagger `/docs`)
@ -229,7 +269,7 @@ curl -s localhost:8000/api/v1/me -H "Authorization: Bearer $TOKEN"
### 6.3 Импорт из ЕЦП CRM (пользователь `admin`, curl или Swagger)
Файл: `fixtures/directories/ecp-export-russkiy-biskvit.xlsx` (21 строка). Выполняйте на стенде **без dev-ГК**: после сброса
(раздел 9) засейте `python -m scripts.seed --dev --no-dev-groups` вместо `make seed-dev`, иначе ГК «Русский Бисквит» и её ЮЛ уже
(раздел 10) засейте `python -m scripts.seed --dev --no-dev-groups` вместо `make seed-dev`, иначе ГК «Русский Бисквит» и её ЮЛ уже
есть и счётчики будут другими (I2 даст `GK_EXISTS`/`LE_EXISTS`, `offices_created` 0).
| № | Шаги | Ожидание |
@ -280,8 +320,9 @@ docker compose -f ../docs/dev/docker-compose.yml exec postgres \
### 6.6 Загрузка ОСВ и просмотр строк через API (Срез 2c)
Предусловия: раздел 4.2 (ядро с `NATS_ENABLED=true`, tabular-parser на `:8001`), файлы из `../fixtures/osv/`. Выполняйте на
свежем стенде (раздел 9) или с другим ЮЛ: дедуп и автозамена зависят от уже загруженного. Ожидаемое время от загрузки до
`PROCESSED` — до 15 секунд (опрос публикатора и цикла маппинга по 5 с, парсер — доли секунды).
свежем стенде (раздел 10) или с другим ЮЛ: дедуп и автозамена зависят от уже загруженного. Ожидаемое время от загрузки до
`PROCESSED` — до 15 секунд (опрос публикатора и цикла маппинга по 5 с, парсер — доли секунды). В UI загрузка, опрос статуса,
дубликат и подтверждение ОСВ — W12–W17 (раздел 8); удаления файлов и автозамены в UI нет.
Подготовка: пользователь `ka_go` (права `DOCUMENT_EDIT`, `DOCUMENT_VIEW`, видит все ЮЛ). ЮЛ должно называться как в шапке ОСВ —
`АО "Русский бисквит"`, ИНН `3528052718`. После `make seed-dev` оно уже есть («РУССКИЙ БИСКВИТ, АО» с алиасом под шапку):
@ -465,7 +506,8 @@ PDF и изображения обрабатывает `scan-gateway`; ядро
Предусловия: раздел 4.2 (ядро с `NATS_ENABLED=true`, tabular-parser на `:8001`), `make seed-dev` (dev-ГК «Агрофирма Межениновская»,
ЮЛ с ИНН `7016006635`, Ростовский РФ — ИНН совпадает с ИНН шапок форм), пользователь `ka_go` (`DOCUMENT_EDIT`, `DOCUMENT_VIEW`,
видит всё) и для негатива `expert` (только `DOCUMENT_VIEW`), `client_manager` (чужой филиал). Файлы — книги Excel
видит всё) и для негатива `expert` (только `DOCUMENT_VIEW`), `client_manager` (чужой филиал). В UI правка, акцепт и подтверждение
формы из PDF — W19–W28 (раздел 8); комментариев и CSV чек-листа по ЮЛ там нет. Файлы — книги Excel
`../fixtures/statements-xlsx/mezheninovskaya/2025-Q3/1_Форма1_бух_09.xlsx` (ББ, 3 колонки: 30.09.2025, 31.12.2024, 31.12.2023, 37 строк
с кодом) и `1_Форма2_бух_09.xlsx` (ОФР, 2 колонки). Подробные схемы и коды ошибок — `dev/api-contract-slice-3b.md`; правила —
`context/05-domain-rules.md` §7, §9.3, §9.5. Новый ЮЛ с чужим ИНН для сценария «не совпал контрагент» — создайте через API
@ -512,7 +554,7 @@ curl -s "localhost:8000/api/v1/documents/$DOC/statement" -H "$H" | python3 -m js
(`aep_3.pdf`, `aep_6.pdf`, раздел 6.8), аналитик правит значения и подтверждает; у форм без колонки кодов документ создаётся без
строк (OQ-139); повтор одной формы в одном файле — вторая не создаётся, первая `NEEDS_CHECK`; страницы одной формы из разных файлов
не склеиваются (OQ-140); строк без кода в ответе нет (OQ-36); скачивание файла и CSV в журнал не пишутся (OQ-153); формулы §7 одни
для редакций `66n` и `fsbu4` (OQ-146); уже смапленные до Среза 3b файлы форм не получают — загрузите файл заново (раздел 9 — сброс
для редакций `66n` и `fsbu4` (OQ-146); уже смапленные до Среза 3b файлы форм не получают — загрузите файл заново (раздел 10 — сброс
стенда).
## 7. Консолидация через API (Срез 4)
@ -521,7 +563,9 @@ curl -s "localhost:8000/api/v1/documents/$DOC/statement" -H "$H" | python3 -m js
(раздел 6.6); данные — в `../fixtures/osv/`. Токены: `ka_go` (`CONSOLIDATION_VIEW/EDIT`, видит всё), `ka_rf`
(`CONSOLIDATION_VIEW/EDIT`, только ГК Ростовского РФ), `expert` (только `CONSOLIDATION_VIEW`), `client_manager`
(`CONSOLIDATION_VIEW`, Краснодарский РФ), `admin` (прав на консолидации нет). Подробные схемы запросов и ответов, коды ошибок и
нюансы для фронта — `dev/api-contract-slice-4.md`; Swagger — `/docs`.
нюансы для фронта — `dev/api-contract-slice-4.md`; Swagger — `/docs`. В UI arm-web (раздел 8) есть K1 (W5–W8), загрузка в
версию (K8, W13), чек-лист CSV (W11), свод, пробелы и экспорт (K11, K12 частично, K17 — W29–W35); блокировки, периметра,
статусов и сопоставления (K4–K7, K13–K16, K18–K20) в UI нет.
**Подготовка.** Нужна ГК с ГСК не менее чем из двух ЮЛ (ГК — в Ростовском РФ, чтобы её видел `ka_rf`): создайте через API
справочников (раздел 6.2; ГСК — `POST /directories/company-groups/{id}/related-groups`, участники — `POST
@ -667,19 +711,138 @@ Q3-only — `missing_quarters = ["Q1","Q2"]`.
6. Текст контрагента, начинающийся с `=`, `+`, `-`, `@` (сделайте такой в своём файле), в Excel показывается как текст, а не
вычисляется как формула.
## 8. Известные ограничения (не заводить как баги)
## 8. Сквозной сценарий в UI (arm-web)
- UI только для администрирования; справочники — через API.
Основной путь аналитика по макету: группа компаний → новая консолидация → файлы ЮЛ → проверка ОСВ и форм ББ/ОФР →
сводная ОСВ. Номера в квадратных скобках — экраны макета `docs/mockup/screens/<nn>-*.png` (открывать по одному через
`docs/mockup/INDEX.md`): если не ясно, «так ли должно выглядеть», сравнивайте с ними при окне 1600×1000. Права, коды
ошибок и граничные случаи, которых нет в UI, — в разделах 6–7.
**Предусловия.** Стенд по разделу 4: ядро с `NATS_ENABLED=true`, tabular-parser на `:8001`, `make seed-dev` (ГК «Русский
Бисквит» с ГСК из РБ и Счастливочной), фронт — `make start`. Для 8.5 (PDF) — ещё шлюз и эмулятор ИС Сканирование (из
каталога `arm-core`, как в 4.2):
```bash
docker compose -f ../docs/dev/docker-compose.yml --profile services up -d --build --no-deps scan-gateway scan-emulator
```
Пользователь — `ka_go@armka.local`. Начинайте со свежего стенда (раздел 10): тогда цифры совпадут с 7.2 без поправок.
Подписи кнопок, колонок и сообщений ниже — дословно как в UI.
### 8.1 Навигация и группы компаний [03]
| № | Шаги | Ожидание |
|---|---|---|
| W1 | Войти `ka_go`, посмотреть боковое меню | логотип «АРМ КА», кнопка «+ Новая консолидация»; разделы «Отчётность» (Группы компаний, Монозаемщики), «Справочники» (ГК и организации, ЮЛ вне ГК), «Документы» (Единое хранилище), «Система» (Журнал действий, Пользователи и роли); кнопка «‹» сворачивает меню до иконок. Всё, кроме «Группы компаний» и «Пользователи и роли», — заглушки |
| W2 | «Группы компаний» | крошки «Отчётность › Группы компаний», подзаголовок «4 групп компаний» (после `make seed-dev`: Русский Бисквит, Унагранде, Новороссийский прокатный завод, Агрофирма Межениновская); колонки «Группа компаний», «CRM ID», «Основной РФ», «Организаций» |
| W3 | Поиск «бисквит»; затем фильтр в заголовке «Группа компаний» (сортировка, отметки, «OK») | остаётся «Русский Бисквит»; появляется «Сбросить фильтры»; «Настройка таблицы» скрывает и показывает колонки |
| W4 | В строке «Русский Бисквит» — кнопка «→ Консолидации» | страница группы [34]: «Русский Бисквит», «20 организаций», блок «Консолидации 0 шт.»; блок «Организации» пуст, пока версия не выбрана; «← Назад» возвращает к списку |
### 8.2 Новая консолидация [42]
| № | Шаги | Ожидание |
|---|---|---|
| W5 | «+ Новая консолидация» в меню | модалка «Новая консолидация»: «Группа компаний», «ГСК» (неактивна до выбора ГК), «Год» (текущий и три предыдущих), «Квартал»; «Создать» неактивна |
| W6 | ГК «Русский Бисквит», ГСК «ГСК Русский Бисквит», 2024, «3 квартал» | блок «ЮЛ консолидации»: все открытые ЮЛ ГК, РБ (3528052718) и Счастливочная (3528104476) отмечены и стоят первыми, счётчик «Выбрано: 2 / 20»; поиск «Поиск ЮЛ...» фильтрует список |
| W7 | «Создать» | уведомление «Создана консолидация 2024, 3 квартал»; открывается страница группы с выбранной версией (`?version=<id>` в адресе): строка «2024 · К3 · 1 · Инициация», «Дата создания» — сегодня по Москве, «ГСК» и «Дата верификации» — «—» (так в прототипе); в «Организации» — 2 строки, «Бух.баланс» и «ОФР» — «Отсутствует», «Ответственный: Dev: Аналитик ГО» |
| W8 | Повторить W5–W7 с тем же периодом | уведомление «Консолидация ГК за этот период уже создана» (409 `CONSOLIDATION_EXISTS`), модалка остаётся открытой |
| W9 | В модалке оставить отмеченным одно ЮЛ; снять все | одно ЮЛ — уведомление с текстом сервера (422 `PERIMETER_TOO_SMALL`, K2); ни одного — «Создать» неактивна |
### 8.3 Организации, чек-лист, загрузка файлов [34], [39], [40]
| № | Шаги | Ожидание |
|---|---|---|
| W10 | Кликнуть строку версии в «Консолидации» | строка подсвечена зелёным, адрес `?version=<id>`; блок «Организации»: колонки «Наименование», «Документы», «ОФР», «Бух.баланс», «ОСВ», «ИНН», «Тип»; меню «⋮» строки версии: «Добавить версию» → «Будет позже», «История изменений» → заглушка журнала |
| W11 | «Скачать чек-лист» | файл `checklist-Русский Бисквит-2024-Q3.csv`; содержимое — как в F17 (BOM, разделитель `;`, открывается в Excel) |
| W12 | Клик по строке «ПЕКАРНЯ СЧАСТЛИВОЧНАЯ, ООО» (или по кнопке «Документы») | справа панель «ПЕРВИЧНЫЕ ДОКУМЕНТЫ» [39]: имя ЮЛ, ИНН 3528104476, кнопка «Загрузить документы», «Документов нет»; крестик справа закрывает панель |
| W13 | «Загрузить документы» → «Выбрать документы» → пять файлов `../fixtures/osv/schastl/2024-Q3/*` → «Загрузить» | модалка «Загрузка документов» [40]: зелёный блок «Принято: 5» с именами, кнопка «Загрузить» сменилась на «Готово». В панели файлы сначала «Обработка», через 5–15 с у каждого документ: «ОСВ 60 · XLS · <дата загрузки>», период «2024 К3», проверка «Период —», «Контрагент ✓», статус «Требуется проверка». Панель опрашивает сервер раз в 5 с, пока есть файлы в обработке |
| W14 | Загрузить ещё раз любой из этих файлов | красный блок «Отклонено: 1» со строкой «<имя> — файл «<имя>» уже загружен для этого ЮЛ» (`DUPLICATE_FILE`), уведомление «Ни один файл не принят» |
| W15 | Закрыть панель, обновить страницу (F5) | статус версии в таблице — «Обработка документов» (K8) |
### 8.4 Просмотр ОСВ-документа
| № | Шаги | Ожидание |
|---|---|---|
| W16 | В панели Счастливочной клик по «ОСВ 60» | экран «Просмотр ОСВ»: крошки «Отчётность › ПЕКАРНЯ СЧАСТЛИВОЧНАЯ, ООО › Проверка документа», подзаголовок «<имя файла> · XLS · <дата>», справа статус «Требуется проверка»; надпись «Суммы в рублях; строки ОСВ только для чтения»; дерево счёт → субсчёт → контрагент, колонки «Счёт / контрагент», «ИНН» и шесть сумм. Корневая строка `60`: «—», «27 923 002,09», «107 554 149,33», «99 188 100,32», «—», «19 556 953,08» (сальдо нач. Кт + обороты Кт − обороты Дт = сальдо кон. Кт) |
| W17 | «✓ Подтвердить» | уведомление «Документ подтверждён», статус «Загружен», кнопка неактивна; в панели документ — «Загружен» |
| W18 | Остальные файлы РБ и Счастливочной 2024 Q1–Q3 (всего 22, список — 7.1): через «Загрузить документы» у каждого ЮЛ и подтверждение каждого ОСВ, либо скриптом из каталога `arm-web`: `scripts/demo-prepare.sh <version_id>` (id — из адреса `?version=`) | скрипт печатает строку на каждый файл (пять файлов из W13 — «уже загружен», это нормально), ждёт распознавания (до 5 мин), подтверждает все ОСВ и в конце печатает `строк: 1385 документов: 22 несопоставленных: 1381 пробелов: 7`. После F5 статус версии — «Коррекция данных» (K9), в «Организации» в колонке «ОСВ» — счета ЮЛ |
`demo-prepare.sh` берёт пользователя вторым аргументом (по умолчанию `ka_go@armka.local`), адрес ядра — из `API`
(по умолчанию `localhost:8000/api/v1`), каталог фикстур — из `FIXTURES_DIR` (по умолчанию `fixtures` рядом с `arm-web`).
### 8.5 Проверка формы ББ/ОФР из PDF [41], [41-02]
PDF из `fixtures/ocr` — отчётность других компаний (`aep_6.pdf` — ООО «Дорстроймонтаж», на 30.06.2025), поэтому ячейки
ББ/ОФР чек-листа версии 2024 Q3 они не заполняют; для проверки экрана подойдёт любое ЮЛ версии. Распознаются только PDF,
для которых в эмуляторе есть ответ (раздел 6.8).
| № | Шаги | Ожидание |
|---|---|---|
| W19 | В панели Счастливочной загрузить `../fixtures/ocr/aep_6.pdf` | через 10–60 с два документа: «Бух. баланс · PDF» и «ОФР · PDF», статус «Требуется проверка», «Контрагент ✗» (в скане другая организация) |
| W20 | Открыть «Бух. баланс» | экран «Проверка распознавания»: слева «ИСХОДНЫЙ ДОКУМЕНТ» — страницы PDF «Страница 1…8», масштаб «−», «100%», «+» и сброс; справа «РЕЗУЛЬТАТ РАСПОЗНАВАНИЯ»: шапка «ИНН —», «Дата отчёта —» (оранжевый фон — не распознано), «Единица измерения тыс. руб.»; заголовок «Бухгалтерский баланс»; колонки «На 30 июня 2025 г», «На 31 декабря 2024 г.», «На 31 декабря 2023 г.»; разделы «АКТИВ», «I. Внеоборотные активы» … «ПАССИВ»; итоги разделов жирным; суммы без копеек, пустые — «-»; строка 1600 «БАЛАНС» — 293 709 / 179 791 / 189 847. Ячейки с уверенностью распознавания ниже 100 % — оранжевые, подсказка «Уверенность: N%» |
| W21 | «✎ Редактировать» → в строке 1600 первой колонки прибавить 100 → «✓ Сохранить» | уведомление «Изменения сохранены»; ячейка голубая, подсказка «Исходное: 293 709»; блок «Нарушения (N)» со строками «Колонка N: <соотношение> — ожидалось X, получено Y» (F3) |
| W22 | «✓ Подтвердить данные» | красный блок в правой части с текстом сервера и списком нарушений (409 `CHECKS_NOT_PASSED`, F4); документ не подтверждён |
| W23 | «Принять с комментарием» → в окне «Принять нарушения» сначала пустой комментарий, затем «округление в форме клиента» → «Принять» | с пустым комментарием «Принять» неактивна; после — синий блок «Нарушения приняты» с датой и комментарием (F5) |
| W24 | «✎ Редактировать», ввести в ячейку `abc` или `1.234` → «✓ Сохранить» | ячейка в красной рамке, подсказка «Неверный формат суммы»; уведомление «Исправьте суммы с неверным форматом», запрос не уходит. «Отменить» сбрасывает правки |
| W25 | Вернуть в 1600 исходную сумму, сохранить | «Проверки пройдены», принятие нарушений сброшено правкой (F6) |
| W26 | В шапке «Дата отчёта» ввести `2025-09-15` → «✓ Сохранить» → «✓ Подтвердить данные» | красный блок «<текст сервера>. Исправьте дату отчёта в шапке и сохраните.» (409 `PERIOD_REQUIRED`: дата не на конец квартала, F9). Дата вводится строго `ГГГГ-ММ-ДД` |
| W27 | Дата `2025-06-30` → «✓ Сохранить» → «✓ Подтвердить данные» | уведомление «Документ подтверждён», статус «Загружен», «Редактировать» и «Подтвердить данные» неактивны |
| W28 | Открыть «ОФР» того же файла [41-02] | заголовок «Отчёт о финансовых результатах», колонки периодов ОФР; остальное — как W20 |
Формы из Excel (`fixtures/statements-xlsx`, раздел 6.9) открываются тем же экраном, но слева вместо скана — «Превью
недоступно для этого формата» и кнопка «Скачать исходник». Документы «Прочий документ» (расшифровки) в панели не
открываются.
### 8.6 Сводная ОСВ [30]
Предусловие — W18: все 22 ОСВ загружены и подтверждены.
| № | Шаги | Ожидание |
|---|---|---|
| W29 | В строке версии «К отчётности →» | экран «Русский Бисквит — 2024 К3», крошки «Отчётность › Русский Бисквит › 2024 · К3», справа «Статус отчёта» «Коррекция данных»; активна вкладка «ОСВ»; «Шахматка», «Таблица корректировки», «Гудвилл», «КФО», «КФО Общий», «Подтверждение КФО клиента» неактивны (подсказка «Будет в следующих срезах») |
| W30 | Сводка | под таблицей «Строк: 1385» (= `rows_total`, 7.2); жёлтый баннер «Требуется указать соответствия … Осталось: 1381.» (= `unmapped_total`); свёрнутый блок «Пробелы: 7 — по этим счетам нет ОСВ за часть кварталов, их строк в своде нет», раскрыть — 7 строк «<ЮЛ> — счёт <код> — нет кварталов: Q1, Q2»: РБ 01, 58.03, 66, 67, 76; Счастливочная 01, 02 |
| W31 | Колонка «Период», суммы | у всех строк «9 мес. 2024 г.»; суммы с запятой и пробелами, ноль — «—»; по 500 строк на страницу |
| W32 | Фильтр «Компания ГК» (воронка в заголовке) = «ПЕКАРНЯ СЧАСТЛИВОЧНАЯ, ООО» → «Применить»; фильтр «Контрагенты» = `бисквит` → «Применить» | «Строк: 6» — `60.01`, `60.02`, `62.01`, `62.02`, `76.06`, `76.АВ`, контрагент «РУССКИЙ БИСКВИТ, АО», ИНН 3528052718. Суммы — как в 7.2, на экране с запятой: `60.01` — «—», «4 454 151,93», «128 058 143,65», «125 950 450,77», «—», «2 346 459,05»; `60.02` — «—» везде, кроме оборотов «9 745 019,62» / «9 745 019,62»; `62.01` — «40 211 938,00», «—», «398 018 012,46», «330 517 504,00», «107 712 446,46», «—»; `62.02` — «—», «24 100 000,00», «9 900 000,00», «—», «—», «14 200 000,00». Иконка активного фильтра зелёная |
| W33 | Сбросить фильтры; «Счёт» = `62` | «Строк: 387»; `60.01` — 0 строк (фильтр принимает только корень счёта, ограничение прототипа) |
| W34 | «Показать ЮЛ без ИНН» | только несопоставленные строки, «Строк» = «Осталось»; кнопка сменилась на «Показать все строки» |
| W35 | «Экспорт» (с фильтрами и без) | файл `svod-osv_Русский Бисквит_2024-Q3_v1.xlsx` по текущим фильтрам; содержимое — по 7.3 |
Если на стенде раньше делали ручное сопоставление контрагентов (K14), «Осталось» меньше 1381: алиасы переживают версии.
Остальные цифры от этого не меняются.
### 8.7 Что в UI не считать багом (прототип)
- Нет «Взять в работу», смены периметра, ручных переходов статусов, сопоставления контрагентов, экрана чек-листа,
комментариев, удаления файлов, «Добавить версию» — это проверяется через API (разделы 6.6, 6.9, 7).
- В своде не показываются «документов: 22», колонки «Признак контрагента» и «Способ сопоставления» (признак — только
внутри фильтра «Контрагенты»: ГСК / ГК / Внешний); фильтр «Счёт» принимает только корень (`60`, не `60.01`).
- Таблица консолидаций и статус версии обновляются по F5: после создания консолидации на странице той же ГК новой строки
может не быть до обновления. Панель «Организации» перечитывается при закрытии панели документов.
- «Распознан» и «Требуется проверка» в панели документов выглядят одинаково — «Требуется проверка».
- «ГСК» и «Дата верификации» в таблице консолидаций, «Утверждён в РФ» и «Верифицирован в ГО» — всегда «—».
- Панель документов показывает первые 100 файлов ЮЛ; загрузка — только из панели ЮЛ внутри версии.
- Шапку формы (ИНН, дату, единицу) нельзя очистить, только заменить; время принятия нарушений — в часовом поясе
браузера, остальные даты — по Москве.
- Ссылка `?version=` с несуществующим id «выбирает» пустую версию; при 404 на своде может прийти до трёх сообщений;
после истечения токена кроме «Сессия истекла» бывают лишние уведомления.
- Предупреждения antd в консоли браузера («Static function can not consume context…», deprecated) ни на что не влияют.
- Уведомления в `/admin` не появляются — дефект arm-web#7 (раздел 6.1).
Баг UI — issue в `RSHB/arm-web` (раздел 11): номер сценария W, скриншот, вкладка Network с запросом и ответом.
## 9. Известные ограничения (не заводить как баги)
- Справочники — только через API; в UI arm-web — администрирование и путь консолидации (раздел 8, ограничения прототипа — 8.7).
- Вход без пароля, открытый `/docs`, CORS `*` — dev-режим.
- Email `*.local` через API/UI отклоняется, при этом dev-пользователи именно такие (созданы seed напрямую).
- Удалять алиасы и пустые ГСК/ГСЗ может только ADMIN (право `DIRECTORY_DELETE`).
- Граница «дата перевода не раньше сегодня» считается по UTC: до 03:00 МСК «сегодня» ещё вчера. Будет исправлено.
- Повторный `make seed-dev` возвращает права, снятые администратором в матрице.
- Профиль в шапке не перечитывается после правки собственных ролей.
- В консоли браузера сообщение `Store does not have a valid reducer` — каркас, не влияет.
- В консоли браузера сообщение `Store does not have a valid reducer` и предупреждения antd — каркас, не влияют.
- Таблица пользователей показывает первые 200.
- При импорте ИНН, записанный в Excel числом с ведущим нулём, теряет ноль и даёт `INVALID_INN`.
- Консолидация (Срез 4): только API; маршрут согласования (`CONSOLIDATION_RF` и далее), «Добавить версию», гудвилл, шахматка — следующие
- Консолидация (Срез 4): блокировка, периметр, статусы и сопоставление — только API (раздел 8.7); маршрут согласования (`CONSOLIDATION_RF` и далее), «Добавить версию», гудвилл, шахматка — следующие
срезы; формы ББ/ОФР в сводной ОСВ не участвуют (только в чек-листе); блокировка версии не истекает по времени; `period_check` документов остаётся `UNKNOWN`;
`PROCESSING` в чек-листе ставится по всем недостающим столбцам ЮЛ, пока файл не смаплен (OQ-119, OQ-120, OQ-122).
- Ручное сопоставление контрагента меняет строку ОСВ для всех версий, куда входит документ (OQ-123); рекомендация кандидата — только
@ -694,7 +857,7 @@ Q3-only — `missing_quarters = ["Q1","Q2"]`.
Полный список отложенных находок — Gitea: `RSHB/arm-core` issues «Follow-ups from #5», «Follow-ups from #18» (#21), #28;
`RSHB/arm-tabular-parser` #18.
## 9. Сброс стенда
## 10. Сброс стенда
```bash
docker compose -f ../docs/dev/docker-compose.yml down -v # БД и бакет с нуля
@ -707,9 +870,11 @@ make migrate && make seed-dev
Файлы, загруженные в 6.6, удаляются из БД командой `DELETE /files/{id}`, но объекты в MinIO остаются (им ставится только
`expires_at`) — `down -v` стирает и их.
## 10. Как заводить баги
## 11. Как заводить баги
Gitea, репозиторий `RSHB/arm-core` (для документации — `RSHB/arm-ka-docs`). Один дефект — одна issue.
Gitea: бэкенд и API — `RSHB/arm-core`, экраны — `RSHB/arm-web`, документация — `RSHB/arm-ka-docs`. Один дефект — одна issue.
Не уверены, чей баг, — откройте вкладку Network: ответ сервера не тот, что в гайде, — arm-core; ответ верный, а экран
показывает другое — arm-web.
Шаблон:
@ -722,12 +887,13 @@ Gitea, репозиторий `RSHB/arm-core` (для документации
Запрос: метод, путь, тело (без токена)
Ответ: статус и тело
Лог бэкенда: строки с трейсбэком, если есть
Окружение: ОС, версии docker/node, коммит arm-core (`git rev-parse --short HEAD`)
Окружение: ОС, браузер, версии docker/node, коммиты arm-core и arm-web (`git -C arm-core rev-parse --short HEAD`)
Скриншот: для багов UI — экран и вкладка Network с запросом
```
Вопросы по ожидаемому поведению (не ясно, баг ли) — тоже issue, с пометкой «вопрос» в заголовке.
## 11. Типичные проблемы при запуске
## 12. Типичные проблемы при запуске
| Симптом | Причина и решение |
|---|---|
@ -735,10 +901,15 @@ Gitea, репозиторий `RSHB/arm-core` (для документации
| `docker compose up --wait` без списка сервисов возвращает 1 | нормально из-за `minio-init`; используйте команду со списком из 4.1 |
| `make migrate` → connection refused | PostgreSQL ещё не `healthy`; подождать и повторить |
| `make venv` не находит Python 3.11 | `uv` скачает его сам при наличии интернета; проверьте `uv python list` |
| Фронт открылся, но после входа пусто или ошибки сети | забыты `REACT_APP_API_URL`/`REACT_APP_ROOT_PATH` при `npm run start` |
| Страница «Вход выполняется через РАИСА» | это production-сборка; запускайте `npm run start`, а не `build` |
| Белый экран на `localhost:3000` | фронт запущен `npm run start` без `REACT_APP_ROOT_PATH=/`; запускайте `make start` (4.3) |
| После входа «Нет связи с сервером» или ошибки сети | ядро не запущено на `:8000`; если на другом адресе — `ARM_CORE_URL=… make start`. Для старого `arm-core/web` — забыты `REACT_APP_API_URL`/`REACT_APP_ROOT_PATH` |
| Страница «Вход выполняется через РАИСА» | это production-сборка; запускайте `make start`, а не `make build` |
| `make start`: порт 3000 занят | запущен второй фронт (например, старый `arm-core/web`); остановите его |
| Скан PDF не отображается («Не удалось открыть PDF») | старый браузер — обновите его |
| PDF завис в «Обработка» | не запущены `scan-gateway`/`scan-emulator` (раздел 8, предусловия) |
| PDF в статусе «Ошибка» (подсказка `INVALID_DOCUMENT`) | эмулятор знает только PDF из `fixtures/ocr` с JSON-ответом (6.8); свой PDF так и должен падать |
| Импорт падает на записи файла в S3 | MinIO не поднят или не создан бакет: `docker compose logs minio-init` |
| `/healthcheck` показывает `nats: down` | NATS не поднят; на сценарии Среза 1 не влияет, но загрузка ОСВ (6.6) без NATS не дойдёт до парсера |
| Файл завис в `UPLOADED`/`PROCESSING` | не запущен tabular-parser (`curl localhost:8001/healthcheck`) или ядро запущено без `NATS_ENABLED=true`; без ack файл через ~2 мин станет `ERROR` |
Подробнее об инфраструктуре — `docs/dev/README.md`, о бэкенде — `arm-core/README.md`.
Подробнее об инфраструктуре — `docs/dev/README.md`, о бэкенде — `arm-core/README.md`, о фронте — `arm-web/README.md`.