arm-web/CLAUDE.md

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.
• Экран проверки формы (src/widgets/DocumentReview/): вся логика — чистые модули с тестами рядом, компоненты .tsx без юнит-тестов. formLayout — раскладка строк по разделам и статусам; issuePlaces — предупреждения по местам (ячейка / колонка / строка / поле шапки), список для панели и collapseIssues; statementDraft — весь черновик правки и сборка тела PATCH (суммы, подтверждения, коды, даты, шапка); cellView — цвета, подсказки, текст ячейки суммы и кода; codeSuggestions — подсказки кодов по справочнику; lineMenu — меню строки («Это расшифровка», «Назначить код»); editRules — что можно править и какая кнопка подтверждения нужна ячейке/колонке; confirmBlockers — строки без кода, блокирующие подтверждение; focusTarget — к какой строке прокрутить по «Показать»; reviewCounters — счётчики «изменённых» и «требующих проверки» над таблицей (по needs_review, как подсветка). src/widgets/FilesDrawer/fileWarnings и documentRows — предупреждения файла и документа в панели файлов; src/utils/percent — формат уверенности.

Команды

• 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.