arm-core/web/CLAUDE.md

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), правила экранов консолидаций (consolidations.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-изменения агент делает код-ревью сам и объясняет решения простым языком.