67bc2c801b
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EAKRDNzXtRrwmWz9z6PZu3
66 lines
7.1 KiB
Markdown
66 lines
7.1 KiB
Markdown
# 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; линтер — 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/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`, только не в 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` — файлы ЮЛ), `src/components/` — примитивы
|
||
(`GenericTable`, `TableTag`, `PageTitle`), `src/types/` — DTO API.
|
||
|
||
## Команды
|
||
- `make install` — `npm install`.
|
||
- `make test` — vitest (`npm test`).
|
||
- `make check` — install + biome + `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`.
|