docs(web): README, CLAUDE.md и ARCHITECTURE.md фронта — из arm-web в arm-core/web (#148)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

README.md

@@ -360,7 +360,7 @@ curl -s -X POST localhost:8000/api/v1/directories/import -H "Authorization: Bear
 ## Администрирование и экран /admin
 
 Бэкенд — `/api/v1/admin/*`, все маршруты требуют `USERS_ADMIN` (без права — 403 до любых проверок тела и существования
-объектов). Фронтенд — страница `/admin` («Пользователи и роли» в боковом меню; видна только с `USERS_ADMIN`): таблица
+объектов). Фронтенд — страница `/admin` («Пользователи и роли» в боковом меню; пункт пока виден всем ролям): таблица
 пользователей (создание, смена ролей и активности) и вкладка «Матрица прав» (роль × право). Без права экран показывает
 «Нет доступа» и запросов к `/admin/*` не делает (настоящую защиту обеспечивает сервер).
 
@@ -374,7 +374,7 @@ curl -s -X POST localhost:8000/api/v1/directories/import -H "Authorization: Bear
 make migrate && make seed-dev       # схема, справочники и dev-пользователи
 make up                             # если инфраструктура ещё не поднята
 cd api && .venv/bin/python run_server.py   # бэкенд, :8000 (в api/.env — DEBUG=true и AUTH_DEV_ISSUER=true)
-cd web && npm install && npm run start     # фронтенд (rsbuild dev), откроется браузер
+cd web && npm install && REACT_APP_ROOT_PATH=/ npm run start   # фронтенд (rsbuild dev, :3000), откроется браузер
 ```
 
 Вход — dev-форма «Вход для разработки» (`web/src/auth/DevLogin.tsx`): введите `admin@armka.local`; форма вызывает
@@ -1155,7 +1155,7 @@ api/
                        Срез 4 — consolidation_periods (выбор источников, §2), consolidated_osv (свод), checklist (чек-лист), policy
                        (`ensure_version_editable`, §10)
   tests/               pytest (юнит и integration/fixtures по маркерам)
-web/                   фронтенд (React 18 + TypeScript, rsbuild, antd): api/ (клиент), auth/ (вход, профиль), layouts/Admin (/admin); сборка web/dist -> api/web/
+web/                   фронтенд (React 18 + TypeScript, rsbuild, antd; ведётся здесь с 21.10.2026, см. web/README.md, web/CLAUDE.md): api/ (клиент), auth/, services/api/, store/, layouts/ (страницы), widgets/ (экраны); сборка web/dist -> api/web/
 setup/                 бутстрап шаблона через Nexus банка (pip.conf, setup.sh)
 openspec/              спецификации и изменения (OpenSpec)
 docs/superpowers/      планы реализации

web/ARCHITECTURE.md

@@ -0,0 +1,27 @@
+# Архитектура фронта arm-core/web
+
+SPA поверх API arm-core (`/api/v1`). Своих данных и бизнес-вычислений нет: всё производное (чек-лист, сводная ОСВ,
+статусы) считает сервер, фронт показывает и отправляет действия пользователя. До 21.10.2026 фронт вёлся в отдельном
+репозитории `RSHB/arm-web` и переносился сюда синхронизацией; теперь — только здесь.
+
+## Модули
+
+| Модуль | Ответственность | Зависит от |
+|---|---|---|
+| `src/api/` | HTTP-клиент, токен, разбор ошибок | `conf/`, `auth/token` |
+| `src/auth/` | профиль `/me`, dev-вход, права для меню | `api/` |
+| `src/services/api/` | вызовы ресурсов arm-core | `api/`, `types/` |
+| `src/store/` | состояние экранов (Redux Toolkit) | `services/api/` |
+| `src/utils/` | чистые функции: деньги, подписи, скачивание | `types/` |
+| `src/types/` | DTO API (повторяют `../api/src/schemas/`) | — |
+| `src/components/` | примитивы UI (таблица, теги, заголовок) | antd |
+| `src/widgets/` | блоки экранов (`DocumentReview` — проверка документа со сканом, `ConsolidatedOsv` — сводная ОСВ, `FilesDrawer`) | `components/`, `store/`, `services/api/`, `utils/` |
+| `src/layouts/` | страницы-маршруты | `widgets/` |
+
+## Границы
+- Сетевые запросы — только через `src/api/client.ts`; `fetch` напрямую не вызывается.
+- `components/` не знают про store и API; `types/` ни от чего не зависят.
+- `utils/` не импортирует React, store и API.
+
+## Сборка
+`npm run build` → `web/dist`, Dockerfile ядра кладёт его в `api/web/` и FastAPI отдаёт SPA (`../README.md`).

web/CLAUDE.md

@@ -0,0 +1,66 @@
+# CLAUDE.md — arm-core/web (фронт АРМ КА)
+
+Общий контекст — `../../CLAUDE.md` (workspace) и `../CLAUDE.md` (arm-core). Этот файл — только про фронт.
+Язык общения, коммитов, комментариев и документации — русский; идентификаторы — английские, как в DBML и API.
+
+## Что это
+SPA кредитного аналитика АРМ КА: справочники групп, консолидации ГК по периодам, карточка версии с чек-листом
+документов, загрузка и проверка первичных файлов (ОСВ, ББ/ОФР из PDF), сводная ОСВ и шаги консолидации.
+Бэкенд — `../api` (`/api/v1`, единственный источник данных). С 21.10.2026 фронт ведётся здесь: задачи — worktree arm-core,
+ветка `feat/<issue>-<slug>`, PR в `main`. Прежний репозиторий `RSHB/arm-web` заморожен на `test` `de4e477`
+(= arm-core `3157a15`), в нём остались история, открытые issue (номера вида `arm-web#7` в комментариях кода — оттуда)
+и спеки экранов `openspec/specs/*-ui`.
+
+## Источники истины для фронта
+1. OpenAPI arm-core и гайд `../../docs/dev/frontend-api-guide.md` — эндпоинты, тела, коды ошибок. Типы в `src/types/`
+   повторяют схемы бэка (`../api/src/schemas/`), поля не придумываем.
+2. Пользовательский путь — `../../docs/context/10-user-journey.md`; макет — `../../docs/mockup/` (по одному экрану через
+   `../../docs/mockup/INDEX.md`).
+3. Права — данные: доступ решает сервер (403). Меню пока не скрывается по правам (`Sidebar` не применяет permission);
+   коды прав из `/me` лежат в `src/auth/permissions.ts`.
+- Требования к экранам: действующие — `../../arm-web/openspec/specs/*-ui/spec.md` (пока не перенесены), новые и
+  изменённые — `../openspec/` arm-core.
+- `../../reference-old-arm/` — только чтение: инфраструктурные идеи (PDFResultViewer) можно смотреть, эндпоинты старого
+  АРМ (`/fsl/...`, `/osv/by-file-id`, `POST /files`) в arm-core не существуют.
+
+## Стек и ограничения
+- React 18 + TypeScript strict, rsbuild, antd 6 (основной UI-кит; daisyui/tailwind — из шаблона), react-router 7,
+  Redux Toolkit, pdfjs-dist (legacy-сборка — для Яндекс Браузера, см. `src/widgets/DocumentReview/pdfjs.ts`).
+- Пакеты `raisa-*` — `optionalDependencies` (вне банка недоступны); `package-lock.json` в git не хранится (в банке
+  зависимости ставятся через Nexus). В контуре `package.json` урезается до сборки
+  (`../../docs/dev/contour-transfer-guide.md` §3.2): новые пакеты, нужные сборке, добавлять и в разрешённый список там.
+- env только `REACT_APP_*` через `src/conf/config.ts`; `REACT_APP_API_URL` — адрес arm-core, `REACT_APP_ROOT_PATH` =
+  `ROOT_PATH` бэка.
+
+## Архитектура
+Карта модулей и границы — `ARCHITECTURE.md`. Главное:
+- `src/api/` — единый HTTP-клиент `apiFetch` / `api.get|post|put|patch|del`: префикс `${API_URL}/api/v1`, Bearer-токен,
+  `ApiError {status, code, message}` по трём формам `detail`, событие `armka:unauthorized` на 401. **Все запросы — только
+  через него** (прямой `fetch` теряет токен и разбор ошибок). `apiFetchBlob(path) → {blob, filename}` — бинарные ответы
+  (скан PDF, экспорт xlsx) с той же обработкой токена/401/ошибок.
+- `src/services/api/` — функции по ресурсам arm-core (consolidations, files, documents, osv, directories/…).
+- `src/utils/` — чистые функции без React/store/API: деньги (`money.ts`, суммы — строки), подписи статусов/типов/периодов
+  (`labels.ts`), скачивание и имя файла (`download.ts`).
+- `src/auth/` — `AuthGate` (профиль `/me`), `DevLogin` (`POST /dev/token`, только не в production), `token.ts`.
+- `src/store/` — Redux Toolkit: `store.ts`, слайсы `companyGroupsSlice` и `consolidations` (+ `thunks.ts`).
+- `src/layouts/` — страницы (маршруты в `src/App.tsx`, в т.ч. `/documents/:document_id` и
+  `/groups/:group_id/versions/:version_id/osv`), `src/widgets/` — блоки экранов (`DocumentReview` — проверка ББ/ОФР/ОСВ
+  со сканом, `ConsolidatedOsv` — сводная ОСВ, `FilesDrawer` — файлы ЮЛ), `src/components/` — примитивы
+  (`GenericTable`, `TableTag`, `PageTitle`), `src/types/` — DTO API.
+
+## Команды (из `web/`)
+- `npm install`; `npm test` — vitest; `npm run lint` — ESLint + `prettier --check`; `npm run format` — **перед PR**
+  (`eslint --fix` → `biome check --write` → `prettier --write`).
+- `REACT_APP_ROOT_PATH=/ npm run start` — dev-сервер на :3000 (без переменной приложение ждёт префикс
+  `/aurora/apps/fastapi-dkb-armka` и открывается белый экран) с proxy `/api` → `ARM_CORE_URL` (по умолчанию
+  `http://localhost:8000`); бэкенд — локальный стенд по `../../docs/dev/qa-guide.md` §4.
+- Из корня arm-core: `make web-check` (install + biome + `tsc --noEmit` + build, входит в `check-full`). Перед PR фронта
+  зелёными должны быть `make web-check`, `npm test` и `npm run lint`; вывод — в описание PR.
+
+## Тесты
+Unit-тесты — vitest на чистых функциях (`src/**/*.test.ts`); компоненты не тестируются — ручной сценарий по стенду с
+фикстурами из `../../fixtures` (`../../docs/dev/qa-guide.md` §8, `../../docs/scripts/demo-prepare.sh`). Экран сверять с
+макетом и проходить сценарий в браузере до сдачи.
+
+## Для владельца
+Пользователь слаб во фронте: на TS/React-изменения агент делает код-ревью сам и объясняет решения простым языком.

web/README.md

@@ -1,34 +1,35 @@
-# arm-web — фронт АРМ КА (демо-прототип)
+# arm-core/web — фронт АРМ КА
 
-SPA кредитного аналитика поверх API `arm-core` (`/api/v1`). Контекст системы — `../CLAUDE.md`, архитектура —
+SPA кредитного аналитика поверх API `arm-core` (`/api/v1`). Контекст системы — `../../CLAUDE.md`, ядро — `../README.md`,
-`ARCHITECTURE.md`, соглашения репозитория — `CLAUDE.md`.
+архитектура фронта — `ARCHITECTURE.md`, соглашения — `CLAUDE.md`. С 21.10.2026 фронт ведётся здесь (PR в arm-core
+`main`); прежний репозиторий `RSHB/arm-web` заморожен.
 
 ## Запуск
 
-1. `make install`.
+1. `npm install` (из `web/`).
-2. Стенд arm-core — по `../docs/dev/qa-guide.md` §4 (ядро на `localhost:8000`, `DEBUG=true`, `make seed-dev`); для
+2. Стенд arm-core — по `../../docs/dev/qa-guide.md` §4 (ядро на `localhost:8000`, `DEBUG=true`, `make seed-dev`); для
    распознавания PDF — профиль `services` (§6.8: tabular-parser, scan-gateway, scan-emulator).
-3. `make start` — dev-сервер rsbuild (сам ставит `REACT_APP_ROOT_PATH=/`; без этого приложение ждёт префикс
+3. `REACT_APP_ROOT_PATH=/ npm run start` — dev-сервер rsbuild (без `REACT_APP_ROOT_PATH=/` приложение ждёт префикс
    `/aurora/apps/fastapi-dkb-armka` и показывает белый экран, см. `qa-guide` §4.3). Запросы `/api` проксируются на
    `ARM_CORE_URL` (по умолчанию `http://localhost:8000`), `REACT_APP_API_URL` в dev не нужен.
 4. Вход — через dev-форму (`POST /dev/token`), например `ka_go@armka.local`.
 
 ## Форматирование и линтеры
 
-**Перед PR — `npm run format`** (или `make format`): `eslint --fix` → `biome check --write` (импорты, безопасные
+**Перед PR — `npm run format`**: `eslint --fix` → `biome check --write` (импорты, безопасные
 исправления) → `prettier --write`. Команда приводит `src/` к единому виду; повторный запуск ничего не меняет.
 
 - Prettier (`.prettierrc.json`) — единственный форматтер: табы, ширина 140, одинарные кавычки (в CSS — двойные),
   `>` тега JSX на той же строке. Форматтер biome выключен, чтобы два инструмента не спорили о пробелах.
-- ESLint (`eslint.config.js`) — правила, повторяющие `biome.json`; biome остаётся линтером в `make lint`/`make check`.
+- ESLint (`eslint.config.js`) — правила, повторяющие `biome.json`; biome остаётся линтером в `make web-check` ядра.
 - `npm run lint` — `eslint` + `prettier --check` без исправлений: ошибки валят команду, предупреждения (`any`,
   `console`, зависимости хуков) — нет.
 - В редакторе: расширения Prettier и ESLint, «Format on Save» с Prettier — результат совпадёт с `npm run format`.
 
 ## Проверка
 
-`make check` — install, biome + ESLint + Prettier (`make lint`), `tsc --noEmit`, vitest, `rsbuild build`. Зелёным
+Из корня arm-core — `make web-check` (install, biome, `tsc --noEmit`, `rsbuild build`; входит в `check-full`), из `web/` —
-считается всё вместе.
+`npm test` (vitest) и `npm run lint` (ESLint + Prettier). Зелёным считается всё вместе.
 
 ## Демо-сценарий
 
@@ -43,9 +44,9 @@ SPA кредитного аналитика поверх API `arm-core` (`/api/v
    `CONSOLIDATION_EXISTS`) → члены ГСК отмечены → «Создать» → открывается страница группы с новой версией.
 2. Дальше работаем на подготовленной версии 2024 Q3 (`/groups/<id>?version=0437f8be-019c-4dbb-9776-08c306aa38cc`):
    панель «Организации» → ЮЛ → «Файлы» → документы ОСВ в статусе «Загружен». Загрузка ОСВ вручную —
-   `../fixtures/osv/{rb,schastl}/2024-Q{1,2,3}/*`; для новой версии быстро — `scripts/demo-prepare.sh <version_id> [email]`
+   `../../fixtures/osv/{rb,schastl}/2024-Q{1,2,3}/*`; для новой версии быстро — `../../docs/scripts/demo-prepare.sh <version_id> [email]`
-   (каталог фикстур — `FIXTURES_DIR`, по умолчанию `../../fixtures` относительно репозитория; в конце печатает сводку).
+   (каталог фикстур — `FIXTURES_DIR`, по умолчанию `fixtures` workspace; в конце печатает сводку).
-3. ББ/ОФР: открыть уже загруженный ББ Счастливочной (или загрузить `../fixtures/ocr/aep_6.pdf` РБ) → скан слева, форма справа,
+3. ББ/ОФР: открыть уже загруженный ББ Счастливочной (или загрузить `../../fixtures/ocr/aep_6.pdf` РБ) → скан слева, форма справа,
    исправить ячейку. ИНН и дата отчёта в aep_6 не распознаются: в шапке ввести дату строго `2024-09-30` (ГГГГ-ММ-ДД) и
    нажать «Сохранить», иначе «Подтвердить данные» даст 409 `PERIOD_REQUIRED`. Принять нарушения с комментарием (если есть), подтвердить.
 4. «К отчётности» → сводная ОСВ; фильтр «Счастливочная» + «бисквит» → строка `60.01` (сальдо нач. Кт 4 454 151.93,
@@ -62,13 +63,11 @@ SPA кредитного аналитика поверх API `arm-core` (`/api/v
 («Показать все»); в режиме правки можно назначить код строке, пометить её расшифровкой и подтвердить значение, код или дату
 колонки — всё уходит одним `PATCH`; кнопка «Подтвердить данные» заблокирована, пока есть строки без кода (ссылка
 «Разберите строки без кода: N» ведёт к первой); панель файлов ЮЛ показывает счётчик предупреждений файла и документа.
-Карта модулей — в `CLAUDE.md`, раздел «Архитектура».
+Карта модулей — `ARCHITECTURE.md`.
 
-## Ограничения прототипа
+## Ограничения
 
 - Нет блокировки версии («Взять в работу»), сопоставления контрагентов, экрана чек-листа, комментариев, удаления файлов,
   смены периметра и ручных переходов статусов.
 - Нет правки строк ОСВ (в API нет), картинок страниц и координат ячеек в скане (в API нет).
 - Нет генерации типов из OpenAPI и автотестов компонентов (vitest — только чистые функции).
-- Нет сборки под контур и переноса в `arm-core/web` — отдельной задачей после демо.
-- Изменений arm-core / scan-gateway нет: найденные пробелы — отдельные issue в тех репозиториях.