From 190458c8bc4942e9b3fedbdfcde0e6685dc515d2 Mon Sep 17 00:00:00 2001 From: Andrey Epifancev Date: Thu, 8 Oct 2026 00:13:42 +0400 Subject: [PATCH] =?UTF-8?q?chore:=20CLAUDE.md,=20ARCHITECTURE.md,=20OpenSp?= =?UTF-8?q?ec=20=D0=B8=20Makefile=20=D0=B4=D0=BB=D1=8F=20arm-web=20(#1)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Обвязка из adopt-project.sh дополнена описанием репозитория по коду: источники истины для фронта, ветка test как интеграционная, правило «запросы только через api/client». .gitignore: исправлена склейка строк (package-lock.json.superpowers/), добавлен dist/. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01EAKRDNzXtRrwmWz9z6PZu3 --- .gitignore | 4 +++- ARCHITECTURE.md | 20 ++++++++++++---- CLAUDE.md | 57 +++++++++++++++++++++++++++++++++----------- Makefile | 19 +++++++++++++++ openspec/config.yaml | 52 +++++++++++++++++++--------------------- 5 files changed, 104 insertions(+), 48 deletions(-) create mode 100644 Makefile diff --git a/.gitignore b/.gitignore index 16f4310..6cdb7c9 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,7 @@ node_modules/ +dist/ .env -package-lock.json.superpowers/ +package-lock.json +.superpowers/ .bounded .DS_Store diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 4a85988..7453842 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -1,15 +1,25 @@ -# Архитектура +# Архитектура arm-web -{{Карта модулей на одну страницу: что где лежит, границы, потоки данных. Читается агентом перед architectural brainstorming. Обновляется вместе со спеками.}} +SPA поверх API arm-core (`/api/v1`). Своих данных и бизнес-вычислений нет: всё производное (чек-лист, сводная ОСВ, +статусы) считает сервер, фронт показывает и отправляет действия пользователя. ## Модули | Модуль | Ответственность | Зависит от | |---|---|---| -| | | | +| `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/types/` | DTO API (повторяют `arm-core/api/src/schemas/`) | — | +| `src/components/` | примитивы UI (таблица, теги, заголовок) | antd | +| `src/widgets/` | блоки экранов | `components/`, `store/`, `services/api/` | +| `src/layouts/` | страницы-маршруты | `widgets/` | ## Границы -- Что не должно импортировать что. +- Сетевые запросы — только через `src/api/client.ts`; `fetch` напрямую не вызывается. +- `components/` не знают про store и API; `types/` ни от чего не зависят. +- `services/api/mocks.ts` не импортируется из рабочих путей. ## Открытые вопросы -- +- Судьба `arm-core/web` (дубль основы этого репозитория) — решает владелец. diff --git a/CLAUDE.md b/CLAUDE.md index 0ca61ba..58cfad6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,28 +1,57 @@ -# arm-web +# 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/-`) вливаются в `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 не существуют. ## Стек и ограничения -- {{Язык, сборка, тесты — например: Python 3.12, uv, pytest.}} -- {{Жёсткие ограничения среды исполнения — без чего код не должен собираться.}} +- 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/core/` (или {{ваш путь}}) — чистая логика без зависимостей от фреймворка/платформы. Покрывается тестами полностью. -- `src/{{adapter}}/` — тонкая обёртка над платформой. Тестируется руками или интеграционно. -- {{Ключевые интерфейсы/порты между ними, если есть.}} +- `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. ## Команды -- `{{npm test / pytest}}` — весь набор тестов. Зелёным считается только весь набор. -- `{{npm run build / ...}}` — сборка. -- `{{npm run dev / ...}}` — локальный запуск. +- `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`. ## Тесты -- Golden-тесты: `tests/fixtures/.*` + эталон `.expected.*`. Внешние сервисы в тестах мокаются. -- {{Где лежит тестовое окружение (vault, БД, песочница).}} +Автотестов пока нет; проверка — `make check` и ручной прогон пути по стенду arm-core с фикстурами из `../fixtures`. -## Первая подсистема -{{Что делается первым и почему. Тестовая инфраструктура — Task 1 первого плана.}} +## Для владельца +Пользователь слаб во фронте: на TS/React-изменения агент делает код-ревью сам и объясняет решения простым языком. ## OpenSpec и superpowers - Вход в любую задачу — superpowers:brainstorming. Skills openspec-propose и openspec-explore сами по себе не запускать. diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..745629f --- /dev/null +++ b/Makefile @@ -0,0 +1,19 @@ +.PHONY: install lint typecheck build check start + +install: + npm install + +lint: + npx biome check src + +typecheck: + npx tsc --noEmit + +build: + npm run build + +# Перед PR: всё вместе, вывод — в описание PR +check: install lint typecheck build + +start: + npm run start diff --git a/openspec/config.yaml b/openspec/config.yaml index c4d34ac..959377d 100644 --- a/openspec/config.yaml +++ b/openspec/config.yaml @@ -1,32 +1,28 @@ schema: spec-driven -# Project context (optional) -# This is shown to AI when creating artifacts. -# Add your tech stack, conventions, style guides, domain knowledge, etc. -# Example: -# context: | -# Tech stack: TypeScript, React, Node.js -# We use conventional commits -# Domain: e-commerce platform +context: | + Репозиторий arm-web — фронт системы АРМ КА (ДКБ, Россельхозбанк): SPA кредитного аналитика поверх API arm-core (/api/v1). + Workspace из нескольких репозиториев; общий контекст — ../CLAUDE.md и ../docs/ (репозиторий arm-ka-docs). + Источники истины: OpenAPI arm-core и ../docs/dev/frontend-api-guide.md (контракт), ../docs/context/10-user-journey.md + (путь пользователя), ../docs/mockup/ (макет, по одному экрану через INDEX.md), ../docs/context/05-domain-rules.md (правила). + Стек: React 18 + TypeScript strict, rsbuild, antd 6, Redux Toolkit, react-router 7, pdfjs-dist, biome. + Интеграционная ветка — test (PR вливаются в неё, main не трогаем). Язык документов и коммитов — русский. -# Per-artifact rules (optional) -# Add custom rules for specific artifacts. -# Example: -# rules: -# proposal: -# - Keep proposals under 500 words -# - Always include a "Non-goals" section -# tasks: -# - Break tasks into chunks of max 2 hours +rules: + proposal: + - Перечислять экраны (номера макета) и эндпоинты arm-core, которые затрагиваются + - Чего нет в API arm-core — не придумывать на фронте; пробел API — отдельный change/issue в arm-core + - Раздел «Non-goals» обязателен + specs: + - Сценарии — по шагам пользовательского пути на локальном стенде arm-core с фикстурами ../fixtures + design: + - Производные консолидации считает сервер; фронт не дублирует вычисления + - Все запросы — через src/api/client.ts + tasks: + - Задачи не больше половины дня, с указанием файлов -# Per-operation guidance (optional) -# Add advisory guidance for how apply and archive work should be conducted. -# This is separate from artifact rules above. -# Example: -# operations: -# apply: -# guidance: -# - Keep test summaries concise -# archive: -# guidance: -# - Summarize the archive outcome before finishing +operations: + apply: + guidance: + - Работать в ветке feat/- от test; PR в test + - После изменений — make check (biome, tsc, build)