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. Права — данные: меню скрывается по кодам прав из /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; линтер — biome (ширина 140, одинарные кавычки).
• Пакеты 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/services/api/ — функции по ресурсам arm-core (consolidations, files, directories/…); mocks.ts — моки на время разработки, в рабочих путях не импортируются.
• src/auth/ — AuthGate (профиль /me), DevLogin (POST /dev/token, только не в production), token.ts.
• src/store/ — Redux Toolkit: store.ts, слайсы companyGroupsSlice, consolidations, files (+ thunks.ts).
• src/layouts/ — страницы (маршруты в src/App.tsx), src/widgets/ — блоки экранов, src/components/ — примитивы (GenericTable, TableTag, PageTitle), src/types/ — DTO API.

Команды

• make install — npm install.
• make check — biome + tsc --noEmit + rsbuild build. Зелёным считается только всё вместе; перед PR, вывод — в описание PR.
• make start — dev-сервер (rsbuild dev); бэкенд — локальный стенд arm-core по ../docs/dev/qa-guide.md.

Тесты

Автотестов пока нет; проверка — make check и ручной прогон пути по стенду arm-core с фикстурами из ../fixtures.

Для владельца

Пользователь слаб во фронте: на 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.