# CLAUDE.md — arm-web (фронт АРМ КА)

Общий контекст системы — `../CLAUDE.md` и `../docs/` (workspace). Этот файл — только про этот репозиторий.
Язык общения, коммитов, комментариев и документации — русский; идентификаторы — английские, как в DBML и API.

## Что это
SPA кредитного аналитика АРМ КА: справочники групп, консолидации ГК по периодам, карточка версии с чек-листом
документов, загрузка и проверка первичных файлов (ОСВ, ББ/ОФР из PDF), дальше — сводная ОСВ и шаги консолидации.
Бэкенд — `arm-core` (`/api/v1`, единственный источник данных). Репозиторий выделен из `arm-core/web`
(06.10.2026, автор основы — команда фронта); `arm-core/web` пока не удалён — его судьба не решена.

## Ветки
- `main` — не трогаем до решения владельца.
- `test` — интеграционная ветка прототипа: все PR (`feat/<issue>-<slug>`) вливаются в `test`, не в `main`.

## Источники истины для фронта
1. OpenAPI arm-core и гайд `../docs/dev/frontend-api-guide.md` — эндпоинты, тела, коды ошибок. Типы в `src/types/`
   повторяют схемы бэка (`arm-core/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`.
- `../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-сборка через `widgets/DocumentReview/pdfjs.ts`: обычная падает в Яндекс Браузере,
  #22); линтеры — biome и ESLint (правила повторяют друг друга), форматтер — только Prettier (ширина 140, табы,
  одинарные кавычки; форматтер biome выключен).
- Пакеты `raisa-*` — `optionalDependencies` (вне банка недоступны); `package-lock.json` в git не хранится (как в шаблоне:
  в банке зависимости ставятся через Nexus).
- env только `REACT_APP_*` через `src/conf/config.ts`; `REACT_APP_API_URL` — адрес arm-core, `REACT_APP_ROOT_PATH` =
  `ROOT_PATH` бэка.

## Архитектура
- `src/api/` — единый HTTP-клиент `apiFetch` / `api.get|post|put|patch|del`: префикс `${API_URL}/api/v1`, Bearer-токен,
  `ApiError {status, code, message}` по трём формам `detail`, событие `armka:unauthorized` на 401. **Все запросы — только
  через него** (прямой `fetch` теряет токен и разбор ошибок).
- `src/api/client.ts` также даёт `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`; форма показывается в любой сборке, заглушка «вход через РАИСА» — после 404 «Not Found» от бэкенда, то есть когда dev-эмитент выключен), `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` — файлы ЮЛ (стол консолидации / все файлы ЮЛ, подпись консолидации, селектор `store/slices/consolidations/selectors.ts`)), `src/components/` — примитивы
  (`GenericTable`, `TableTag`, `PageTitle`), `src/types/` — DTO API.

## Команды
- `make install` — `npm install`.
- `make test` — vitest (`npm test`).
- `make format` / `npm run format` — `eslint --fix` → `biome check --write` → `prettier --write` по `src/`; перед PR.
- `make lint` — `biome check src` + `npm run lint` (ESLint + `prettier --check`).
- `make check` — install + lint (biome, ESLint, Prettier) + `tsc --noEmit` + vitest + `rsbuild build`. Зелёным считается только всё вместе; **перед PR**, вывод —
  в описание PR.
- `make start` — dev-сервер (`rsbuild dev`, цель сама задаёт `REACT_APP_ROOT_PATH=/`: без него приложение ждёт префикс
  `/aurora/apps/fastapi-dkb-armka` и открывается белый экран; `qa-guide` §4.3) с proxy `/api` → `ARM_CORE_URL` (по умолчанию `http://localhost:8000`); бэкенд — локальный стенд arm-core по `../docs/dev/qa-guide.md`.

## Тесты
Unit-тесты — vitest на чистых функциях (`src/**/*.test.ts`, `npm test` / `make test`); компоненты не тестируются — ручной демо-сценарий по стенду arm-core с фикстурами из `../fixtures` (README, `scripts/demo-prepare.sh`).

## Для владельца
Пользователь слаб во фронте: на TS/React-изменения агент делает код-ревью сам и объясняет решения простым языком.

## OpenSpec и superpowers
- Вход в любую задачу — superpowers:brainstorming. Skills openspec-propose и openspec-explore сами по себе не запускать.
- Когда brainstorming классифицировал задачу как architectural, структуру change создать через `openspec new change <id>` (или `/opsx:propose <id>`), а содержимое proposal.md, specs/ и design.md написать по итогам brainstorming. tasks.md из OpenSpec не заполнять — задачи живут в плане superpowers.
- `/opsx:apply` не использовать: исполнение идёт через writing-plans и SDD/executing-plans.
- `openspec archive <id>` — после merge PR, как часть чеклиста закрытия.
- Хук require-plan защищает любой каталог `src/` на любой глубине. Если код лежит иначе — перечислить каталоги (префиксы от корня, по одному в строке) в `.claude/code-paths`.