# 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`), в нём осталась история (номера вида `arm-web#7` в комментариях кода — оттуда). Открытые issue
arm-web перенесены в arm-core #150–#157 (arm-web#7 → #151), спеки экранов и архив их изменений — в `../openspec/`
(архивы с суффиксом `-web` — 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`.
- Требования к экранам: действующие — `../openspec/specs/*-ui/spec.md` (перенесены из arm-web@de4e477), новые и
  изменённые — `../openspec/changes/` этого репозитория.
- `../../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`).
- Иконки: основная библиотека — `@ant-design/icons`; вторая — `lucide-react` (зафиксированная версия), только для иконок
  макета, которых в antd нет (боковое меню, «Взять в работу», «К отчётности», меню «⋯» консолидации). Новую иконку сначала
  ищем в `@ant-design/icons`.
- Пакеты `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` — файлы ЮЛ, `ConsoleTable` — список консолидаций ГК и
  «Взять в работу», `StatusChangeModal` — «Изменить статус» версии), `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-изменения агент делает код-ревью сам и объясняет решения простым языком.