frontend/README.md

WealthLedger frontend

React/Vite-клиент WealthLedger. Клиент получает данные только через typed API backend; прямые вызовы T-Bank из frontend не допускаются.

Быстрый старт

Требуется Node 24 (.nvmrc). Создайте .env из примера и установите зависимости строго из lockfile:

cp .env.example .env
nvm use --silent
npm ci
npm run dev

VITE_API_BASE_URL по умолчанию указывает на http://localhost:3000.

Для commits установите Gitleaks 8.30.1 в PATH (macOS: brew install gitleaks). Pre-commit сначала проверяет staged diff с полной редакцией секретов, затем запускает formatting и FSD checks. Находка или отсутствие Gitleaks блокирует commit. Проверка этого поведения: node --test scripts/test-pre-commit.mjs.

Контейнерный image

Dockerfile имеет targets development (Vite HMR и proxy /api/ во внутренний backend) и production (nginx на 8080, SPA fallback и same-origin API proxy). Node соответствует .nvmrc. Build context ограничен .dockerignore; .env, local DB и host node_modules не попадают в image.

docker build --target development -t wealthledger-frontend:development .
docker build --target production -t wealthledger-frontend:production .

Gitea image.yml запускается на защищённом release tag vX.Y.Z, проверяет package/lock version и canonical gates. Runner ubuntu-latest должен иметь Docker/buildx. Образы хранятся в Nexus: nexus.ksv741.keenetic.pro/wealthledger/frontend. Dedicated Nexus writer задаётся Actions secrets NEXUS_USERNAME/NEXUS_PASSWORD; server использует отдельную read-only identity. Docker endpoint и token realm должны использовать HTTPS; в docker-hosted включается запрет redeploy. Прежние Gitea secrets сохраняются на время перехода и не передаются в Nexus. Публикуются semver tags, без latest; существующие release tags не перезаписываются. Production выбирает опубликованный version tag.

Compose topology принадлежит workspace, эксплуатационная последовательность — документация, страница architecture/deployment.md. Проверка публикации требует настроенного registry/runner; локальный build не доказывает package permissions.

Проверка

nvm use --silent
npm run verify

Команда проверяет, что generated OpenAPI types соответствуют committed snapshot, затем запускает strict TypeScript, Biome, один coverage-backed запуск Vitest, Knip, dependency rules приложения и stories, сборки приложения и Storybook. Отдельный CI workflow Frontend security на push, pull request и ежедневно проверяет полную доступную историю Gitleaks 8.30.1 и выполняет npm audit --include=dev --audit-level=low. Любой advisory блокирует security job; исключений frontend нет. Локально можно выполнить те же команды: gitleaks git --log-opts=--all --redact=100 --no-banner и npm audit --include=dev --audit-level=low. Audit требует доступа к npm registry; проверка секретов выполняется локально и не выводит их значения.

TypeScript остаётся на 5.9.3: openapi-typescript@7.13.0 требует peer ^5.x. Обновление до TypeScript 7 из Renovate dashboard откладывается до совместимого релиза генератора; --force/--legacy-peer-deps для обхода этого ограничения не используются. Если backend-контракт изменился, обновите src/shared/api/spec/openapi.json копированием backend OpenAPI document и затем выполните npm run openapi:generate.

SonarQube

Проект wealthledger-frontend использует настройки из sonar-project.properties. Анализируются исходники src; тесты учитываются отдельно, а Storybook fixtures, test helpers, generated API types и OpenAPI snapshot исключены. npm run test:coverage (также входит в npm run verify) создаёт coverage/lcov.info для импорта покрытия.

Для первого анализа установите SonarScanner CLI, совместимый с версией сервера, и выполните из корня frontend:

nvm use --silent
npm ci
npm run test:coverage
# SONAR_TOKEN передайте через окружение; не сохраняйте токен в репозитории.
sonar-scanner

В Gitea откройте frontend → Settings → Actions → Secrets и добавьте SONAR_TOKEN с токеном анализа проекта. Переименовывать основную ветку в SonarQube не требуется; sonar.branch.name не задаётся. Используется Community Edition 9.9.8: CI отправляет только push в develop, после успешного verify, и ожидает результат Quality Gate. PR и остальные ветки проходят обычные проверки без отправки в SonarQube. Отрицательный Quality Gate или ошибка scanner завершает verify с ошибкой.

Runner должен поддерживать Docker actions и иметь HTTPS-доступ к https://sonarqube.ksv741.keenetic.pro, GitHub и Docker Hub. Docker action SonarSource закреплён на commit версии 2.3.0; scanner запускается отдельно от Node 24, используемого для сборки. tsconfig.sonar.json содержит совместимые со старым анализатором TS настройки; приложение проверяется штатным TypeScript 5.9 через npm run verify. После обновления сервера пересмотрите scanner и возможность использовать основной tsconfig. Успешный локальный verify не доказывает доступность сервера и успешность анализа в CI.

UI-каталог Storybook

После nvm use --silent выполните npm run dev:catalog; статическая сборка — npm run build:catalog. Каталог использует общую тему приложения, вымышленные данные и локальные действия без application API. Примеры не доказывают восстановление реального запроса. Визуальные роли описаны в UI convention.

Документация

• AGENTS: правила и источники
• Выбор owner/FSD
• UI, state, формы и компоненты
• Data/API/cache
• Testing
• UI-каталог Storybook

Checkout frontend содержит все входы сборки и проверок. Публичная схема API поступает как отдельный artifact; команды frontend используют только её локальную копию и не обращаются к исходникам или CI сервера. Доставка новой схемы — явное обновление snapshot с review и npm run openapi:generate. Runtime URL API задаётся окружением, а не расположением другого репозитория. Разработка идёт напрямую по задаче пользователя; OpenSpec/SDD — по явному запросу.

Knip исключает conventional-changelog-conventionalcommits: release-it загружает preset по имени из .release-it.json. Версия preset закреплена напрямую.

Релизы

Репозиторий выпускается независимо. develop — интеграция, main — принятые релизы. Работа: codex/<task> от актуального develop, PR в develop. Обычные PR допускают squash; release и обратная синхронизация сохраняют историю. Commits и PR titles — Conventional Commits, включая spec:. Версии вручную не повышай.

1. Получи main, develop и теги: git fetch origin --tags. Убедись, что develop содержит последний релиз. Создай release/<name> от проверенного develop; nvm use --silent, npm ci. Hotfix начинается от main в release/hotfix-<name> и проходит тот же процесс.
2. На чистой ветке выполни npm run release:preview, просмотри версию/changelog, затем npm run release:prepare. Команда создаёт chore(release): X.Y.Z, обновляет manifest/lockfile/CHANGELOG; тег и push не выполняет. Не обходи guards ветки, чистого дерева, отсутствующих тегов или уже подготовленной версии.
3. Проверь diff и штатные gates этого репозитория. Отправь только release-ветку, открой PR в main с заголовком chore(release): X.Y.Z. После зелёных verify, security, commits выполни fast-forward-only merge. Если main изменился, согласуй историю и повтори проверки кандидата.
4. Получи удалённый main, сравни его HEAD с проверенным release SHA и версией manifest/lockfile. Создай аннотированный vX.Y.Z именно на этом SHA: git tag -a vX.Y.Z <release-sha> -m "Release X.Y.Z", затем отправь только git push origin refs/tags/vX.Y.Z. Не запускай release-it повторно на main.
5. Верни release-коммит через PR main → develop без squash/rebase; проверь, что develop содержит тег. Опубликованные теги не перемещай. При сбое после merge создай отсутствующий тег без нового bump; до merge исправь и проверь существующий кандидат без повторного повышения версии.

feat: повышает minor, fix:/perf: и прочие разрешённые типы — patch; !/BREAKING CHANGE: — major, включая версии до 1.0. chore(release): исключён из рекомендации и changelog. Конфигурация — .release-it.json. В Gitea для main/develop должны быть запрещены прямой/force push и обход администратором, обязательны verify, security, commits; теги v* защищены. Workflow сам не включает эти настройки. Отдельное review approval для одного владельца не требуется. Npm publishing, deploy и Gitea Releases не включены.