diff --git a/README.md b/README.md index 47f00ed..e4e9f66 100644 --- a/README.md +++ b/README.md @@ -360,7 +360,7 @@ curl -s -X POST localhost:8000/api/v1/directories/import -H "Authorization: Bear ## Администрирование и экран /admin Бэкенд — `/api/v1/admin/*`, все маршруты требуют `USERS_ADMIN` (без права — 403 до любых проверок тела и существования -объектов). Фронтенд — страница `/admin` («Пользователи и роли» в боковом меню; видна только с `USERS_ADMIN`): таблица +объектов). Фронтенд — страница `/admin` («Пользователи и роли» в боковом меню; пункт пока виден всем ролям): таблица пользователей (создание, смена ролей и активности) и вкладка «Матрица прав» (роль × право). Без права экран показывает «Нет доступа» и запросов к `/admin/*` не делает (настоящую защиту обеспечивает сервер). @@ -374,7 +374,7 @@ curl -s -X POST localhost:8000/api/v1/directories/import -H "Authorization: Bear make migrate && make seed-dev # схема, справочники и dev-пользователи make up # если инфраструктура ещё не поднята cd api && .venv/bin/python run_server.py # бэкенд, :8000 (в api/.env — DEBUG=true и AUTH_DEV_ISSUER=true) -cd web && npm install && npm run start # фронтенд (rsbuild dev), откроется браузер +cd web && npm install && REACT_APP_ROOT_PATH=/ npm run start # фронтенд (rsbuild dev, :3000), откроется браузер ``` Вход — dev-форма «Вход для разработки» (`web/src/auth/DevLogin.tsx`): введите `admin@armka.local`; форма вызывает @@ -1155,7 +1155,7 @@ api/ Срез 4 — consolidation_periods (выбор источников, §2), consolidated_osv (свод), checklist (чек-лист), policy (`ensure_version_editable`, §10) tests/ pytest (юнит и integration/fixtures по маркерам) -web/ фронтенд (React 18 + TypeScript, rsbuild, antd): api/ (клиент), auth/ (вход, профиль), layouts/Admin (/admin); сборка web/dist -> api/web/ +web/ фронтенд (React 18 + TypeScript, rsbuild, antd; ведётся здесь с 21.10.2026, см. web/README.md, web/CLAUDE.md): api/ (клиент), auth/, services/api/, store/, layouts/ (страницы), widgets/ (экраны); сборка web/dist -> api/web/ setup/ бутстрап шаблона через Nexus банка (pip.conf, setup.sh) openspec/ спецификации и изменения (OpenSpec) docs/superpowers/ планы реализации diff --git a/web/ARCHITECTURE.md b/web/ARCHITECTURE.md new file mode 100644 index 0000000..e73ada3 --- /dev/null +++ b/web/ARCHITECTURE.md @@ -0,0 +1,27 @@ +# Архитектура фронта arm-core/web + +SPA поверх API arm-core (`/api/v1`). Своих данных и бизнес-вычислений нет: всё производное (чек-лист, сводная ОСВ, +статусы) считает сервер, фронт показывает и отправляет действия пользователя. До 21.10.2026 фронт вёлся в отдельном +репозитории `RSHB/arm-web` и переносился сюда синхронизацией; теперь — только здесь. + +## Модули + +| Модуль | Ответственность | Зависит от | +|---|---|---| +| `src/api/` | HTTP-клиент, токен, разбор ошибок | `conf/`, `auth/token` | +| `src/auth/` | профиль `/me`, dev-вход, права для меню | `api/` | +| `src/services/api/` | вызовы ресурсов arm-core | `api/`, `types/` | +| `src/store/` | состояние экранов (Redux Toolkit) | `services/api/` | +| `src/utils/` | чистые функции: деньги, подписи, скачивание | `types/` | +| `src/types/` | DTO API (повторяют `../api/src/schemas/`) | — | +| `src/components/` | примитивы UI (таблица, теги, заголовок) | antd | +| `src/widgets/` | блоки экранов (`DocumentReview` — проверка документа со сканом, `ConsolidatedOsv` — сводная ОСВ, `FilesDrawer`) | `components/`, `store/`, `services/api/`, `utils/` | +| `src/layouts/` | страницы-маршруты | `widgets/` | + +## Границы +- Сетевые запросы — только через `src/api/client.ts`; `fetch` напрямую не вызывается. +- `components/` не знают про store и API; `types/` ни от чего не зависят. +- `utils/` не импортирует React, store и API. + +## Сборка +`npm run build` → `web/dist`, Dockerfile ядра кладёт его в `api/web/` и FastAPI отдаёт SPA (`../README.md`). diff --git a/web/CLAUDE.md b/web/CLAUDE.md new file mode 100644 index 0000000..d55dcb9 --- /dev/null +++ b/web/CLAUDE.md @@ -0,0 +1,66 @@ +# 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/-`, PR в `main`. Прежний репозиторий `RSHB/arm-web` заморожен на `test` `de4e477` +(= arm-core `3157a15`), в нём остались история, открытые issue (номера вида `arm-web#7` в комментариях кода — оттуда) +и спеки экранов `openspec/specs/*-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`. +- Требования к экранам: действующие — `../../arm-web/openspec/specs/*-ui/spec.md` (пока не перенесены), новые и + изменённые — `../openspec/` arm-core. +- `../../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`). +- Пакеты `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`). +- `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. + +## Команды (из `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-изменения агент делает код-ревью сам и объясняет решения простым языком. diff --git a/web/README.md b/web/README.md index c4e24fe..9c54972 100644 --- a/web/README.md +++ b/web/README.md @@ -1,34 +1,35 @@ -# arm-web — фронт АРМ КА (демо-прототип) +# arm-core/web — фронт АРМ КА -SPA кредитного аналитика поверх API `arm-core` (`/api/v1`). Контекст системы — `../CLAUDE.md`, архитектура — -`ARCHITECTURE.md`, соглашения репозитория — `CLAUDE.md`. +SPA кредитного аналитика поверх API `arm-core` (`/api/v1`). Контекст системы — `../../CLAUDE.md`, ядро — `../README.md`, +архитектура фронта — `ARCHITECTURE.md`, соглашения — `CLAUDE.md`. С 21.10.2026 фронт ведётся здесь (PR в arm-core +`main`); прежний репозиторий `RSHB/arm-web` заморожен. ## Запуск -1. `make install`. -2. Стенд arm-core — по `../docs/dev/qa-guide.md` §4 (ядро на `localhost:8000`, `DEBUG=true`, `make seed-dev`); для +1. `npm install` (из `web/`). +2. Стенд arm-core — по `../../docs/dev/qa-guide.md` §4 (ядро на `localhost:8000`, `DEBUG=true`, `make seed-dev`); для распознавания PDF — профиль `services` (§6.8: tabular-parser, scan-gateway, scan-emulator). -3. `make start` — dev-сервер rsbuild (сам ставит `REACT_APP_ROOT_PATH=/`; без этого приложение ждёт префикс +3. `REACT_APP_ROOT_PATH=/ npm run start` — dev-сервер rsbuild (без `REACT_APP_ROOT_PATH=/` приложение ждёт префикс `/aurora/apps/fastapi-dkb-armka` и показывает белый экран, см. `qa-guide` §4.3). Запросы `/api` проксируются на `ARM_CORE_URL` (по умолчанию `http://localhost:8000`), `REACT_APP_API_URL` в dev не нужен. 4. Вход — через dev-форму (`POST /dev/token`), например `ka_go@armka.local`. ## Форматирование и линтеры -**Перед PR — `npm run format`** (или `make format`): `eslint --fix` → `biome check --write` (импорты, безопасные +**Перед PR — `npm run format`**: `eslint --fix` → `biome check --write` (импорты, безопасные исправления) → `prettier --write`. Команда приводит `src/` к единому виду; повторный запуск ничего не меняет. - Prettier (`.prettierrc.json`) — единственный форматтер: табы, ширина 140, одинарные кавычки (в CSS — двойные), `>` тега JSX на той же строке. Форматтер biome выключен, чтобы два инструмента не спорили о пробелах. -- ESLint (`eslint.config.js`) — правила, повторяющие `biome.json`; biome остаётся линтером в `make lint`/`make check`. +- ESLint (`eslint.config.js`) — правила, повторяющие `biome.json`; biome остаётся линтером в `make web-check` ядра. - `npm run lint` — `eslint` + `prettier --check` без исправлений: ошибки валят команду, предупреждения (`any`, `console`, зависимости хуков) — нет. - В редакторе: расширения Prettier и ESLint, «Format on Save» с Prettier — результат совпадёт с `npm run format`. ## Проверка -`make check` — install, biome + ESLint + Prettier (`make lint`), `tsc --noEmit`, vitest, `rsbuild build`. Зелёным -считается всё вместе. +Из корня arm-core — `make web-check` (install, biome, `tsc --noEmit`, `rsbuild build`; входит в `check-full`), из `web/` — +`npm test` (vitest) и `npm run lint` (ESLint + Prettier). Зелёным считается всё вместе. ## Демо-сценарий @@ -43,9 +44,9 @@ SPA кредитного аналитика поверх API `arm-core` (`/api/v `CONSOLIDATION_EXISTS`) → члены ГСК отмечены → «Создать» → открывается страница группы с новой версией. 2. Дальше работаем на подготовленной версии 2024 Q3 (`/groups/?version=0437f8be-019c-4dbb-9776-08c306aa38cc`): панель «Организации» → ЮЛ → «Файлы» → документы ОСВ в статусе «Загружен». Загрузка ОСВ вручную — - `../fixtures/osv/{rb,schastl}/2024-Q{1,2,3}/*`; для новой версии быстро — `scripts/demo-prepare.sh [email]` - (каталог фикстур — `FIXTURES_DIR`, по умолчанию `../../fixtures` относительно репозитория; в конце печатает сводку). -3. ББ/ОФР: открыть уже загруженный ББ Счастливочной (или загрузить `../fixtures/ocr/aep_6.pdf` РБ) → скан слева, форма справа, + `../../fixtures/osv/{rb,schastl}/2024-Q{1,2,3}/*`; для новой версии быстро — `../../docs/scripts/demo-prepare.sh [email]` + (каталог фикстур — `FIXTURES_DIR`, по умолчанию `fixtures` workspace; в конце печатает сводку). +3. ББ/ОФР: открыть уже загруженный ББ Счастливочной (или загрузить `../../fixtures/ocr/aep_6.pdf` РБ) → скан слева, форма справа, исправить ячейку. ИНН и дата отчёта в aep_6 не распознаются: в шапке ввести дату строго `2024-09-30` (ГГГГ-ММ-ДД) и нажать «Сохранить», иначе «Подтвердить данные» даст 409 `PERIOD_REQUIRED`. Принять нарушения с комментарием (если есть), подтвердить. 4. «К отчётности» → сводная ОСВ; фильтр «Счастливочная» + «бисквит» → строка `60.01` (сальдо нач. Кт 4 454 151.93, @@ -62,13 +63,11 @@ SPA кредитного аналитика поверх API `arm-core` (`/api/v («Показать все»); в режиме правки можно назначить код строке, пометить её расшифровкой и подтвердить значение, код или дату колонки — всё уходит одним `PATCH`; кнопка «Подтвердить данные» заблокирована, пока есть строки без кода (ссылка «Разберите строки без кода: N» ведёт к первой); панель файлов ЮЛ показывает счётчик предупреждений файла и документа. -Карта модулей — в `CLAUDE.md`, раздел «Архитектура». +Карта модулей — `ARCHITECTURE.md`. -## Ограничения прототипа +## Ограничения - Нет блокировки версии («Взять в работу»), сопоставления контрагентов, экрана чек-листа, комментариев, удаления файлов, смены периметра и ручных переходов статусов. - Нет правки строк ОСВ (в API нет), картинок страниц и координат ячеек в скане (в API нет). - Нет генерации типов из OpenAPI и автотестов компонентов (vitest — только чистые функции). -- Нет сборки под контур и переноса в `arm-core/web` — отдельной задачей после демо. -- Изменений arm-core / scan-gateway нет: найденные пробелы — отдельные issue в тех репозиториях.