# WealthLedger

Локальное приложение для портфеля T-Bank, операций, дохода и будущих выплат,
а также ручного учёта банковских карт и расходов.
[Обзор продукта](docs/overview.md) и [документация системы](docs/README.md).

## Структура workspace

Workspace состоит из пяти независимых Git-репозиториев. Root — репозиторий
`WealthLedger/main`; вложенные checkout не являются submodules.

| Путь от root | Репозиторий Gitea | Назначение |
| --- | --- | --- |
| `.` | `WealthLedger/main` | Вход в workspace, инструкции и правила root tracking |
| `frontend/` | `WealthLedger/frontend` | [React/Vite UI](frontend/README.md) |
| `backend/` | `WealthLedger/backend` | [NestJS API, Prisma и SQLite](backend/README.md) |
| `docs/` | `WealthLedger/docs` | [Объяснение системы](docs/README.md) |
| `specs/` | `WealthLedger/specs` | [Требования и OpenSpec](specs/README.md) |

### Получение checkout

Нужны Git и SSH-доступ к Gitea на порту 2222. Из родительского каталога,
где ещё нет `WealthLedger`, выполните:

```bash
git clone ssh://git@git.personal.ksv741.ru:2222/WealthLedger/main.git WealthLedger
cd WealthLedger
git clone ssh://git@git.personal.ksv741.ru:2222/WealthLedger/frontend.git frontend
git clone ssh://git@git.personal.ksv741.ru:2222/WealthLedger/backend.git backend
git clone ssh://git@git.personal.ksv741.ru:2222/WealthLedger/docs.git docs
git clone ssh://git@git.personal.ksv741.ru:2222/WealthLedger/specs.git specs
```

Для существующего workspace клонируйте только отсутствующие checkout в пустые
каталоги. Проверяйте состояние каждого repo отдельно, например
`git -C frontend status`. Обновление main не обновляет соседние repos;
общего lockfile revisions нет. Относительные ссылки требуют указанных имён каталогов.

### Что хранится в main

Root отслеживает входные документы, общие engineering conventions и их migration
inventory в `.ai/`, npm/release-конфигурацию, changelog,
проверки tracking/release и три CI workflow. Точный allowlist — в `.gitignore`.
Остальные root-пути игнорируются по умолчанию:
вложенные repos, `.env`, базы и WAL, импорты выписок, PDF, `references/`,
`design/`, `todo/` и локальные настройки инструментов.
Новый общий файл включается отдельной правкой allowlist после проверки содержимого.

Перед commit смотрите `git diff --cached --name-status` в нужном repo.
Не используйте `git add -f` для обхода границ root. Ignore не защищает уже
отслеживаемые файлы и не меняет правила внутри вложенных repos.
Не запускайте очистку workspace через `git clean -fdx`: ignored-пути содержат
локальные данные. Правила tracking не удаляют файлы и вложенные `.git`.

## Подготовка и запуск

Нужны nvm и Node из `.nvmrc` каждого npm-repo (сейчас 24.21.0, npm 11.19).
Во всех пяти репозиториях отдельно выполните
`nvm install`, `nvm use --silent`, `npm ci`. В root и specs npm нужен для release-it
и проверки сообщений коммитов.
После смены major Node переустановите native dependencies через `npm ci`.
Разрешения install scripts заданы в `package.json` соответствующего repo.

Для нового backend создайте `.env` по [backend README](backend/README.md),
замените оба placeholder-секрета и проверьте `DATABASE_URL`.
Существующий `.env` сохраняйте. Из backend:

```bash
nvm use --silent
npm run build
npx prisma migrate deploy
npm run start:dev
```

Build генерирует Prisma client. Перед миграцией существующей базы сохраните
согласованный backup и ключ шифрования; процедуру и ограничения отката смотрите
в [описании хранения](docs/architecture/containers.md#сохранение-и-восстановление-данных).
Известная ошибка fresh migration при `RUST_LOG=warn/error` устранена в
`backend/prisma.config.ts`: CLI удаляет унаследованную переменную.
Используйте штатный `prisma migrate deploy` из backend; прежний Prisma blocker
снят. [Подробности и границы проверки](backend/README.md#реальная-sqlite-и-сохранность-данных).

В другом терминале подготовьте `.env` по [frontend README](frontend/README.md),
затем из frontend:

```bash
nvm use --silent
npm run dev
```

Стандартные адреса: frontend `http://localhost:5173`, API
`http://localhost:3000`. Origin backend и адрес API frontend должны совпадать
с выбранными адресами. T-Bank token вводится через настройки приложения;
без него доступны вход и ручной банковский учёт.
Для вымышленных UI-примеров выполните `npm run dev:catalog` из frontend.

### OpenSpec

OpenSpec не нужен для запуска приложения и применяется по явному запросу.
Specs использует Node из своей `.nvmrc`; проверенная версия CLI — 1.10.0.
Store `wealth-ledger-specs` расположен в `specs/openspec/`.
[Работа с OpenSpec](specs/AGENTS.md), [команды validation](specs/README.md#проверка).

## Проверки

Перед npm-командами активируйте `.nvmrc` соответствующего repo.

| Где | Команда | Что проверяет |
| --- | --- | --- |
| root | `python3 test-workspace-tracking.py` | Массовый add на вымышленных данных; сохранность файлов и вложенных Git |
| root | `git diff --check` | Whitespace в изменениях root |
| frontend | `npm run verify` | Типы, lint, тесты, зависимости, OpenAPI snapshot и сборки |
| backend | `npm run verify` | Lint, типы, unit tests и build |
| backend | `npm run test:e2e` | HTTP/SQLite suites и контракт с соседним frontend |
| docs | `npm run verify` | Markdown, относительные ссылки и diff |

Python 3 нужен только для проверки root tracking. Backend e2e использует
временные базы; verify отдельно не доказывает HTTP/DB-сценарии или доступность
T-Bank. Полные команды и ограничения принадлежат README
[frontend](frontend/README.md#проверка) и [backend](backend/README.md#проверка).
Для изменения проекта начните с [AGENTS](AGENTS.md).

## Релизы и ветки

Все пять репозиториев выпускаются независимо. Первый релиз — `0.1.0`;
версия в `package.json` и lockfile соответствует последнему принятому тегу
`vX.Y.Z`. Root-репозиторий называется `main`, его ветки — `main` и `develop`.

`main` хранит принятые релизы, `develop` — интеграцию разработки. Новая задача:
отдельная ветка от свежего `develop`, затем PR в `develop`. Для веток агента
используется `codex/<task>`; также допустимы `feature/<task>` и `fix/<task>`.
В `main` напрямую не пушить. Обычные PR можно squash-merge; релизные PR и
обратную синхронизацию `main` с `develop` сливать с сохранением истории.

Commits и заголовки PR — Conventional Commits. `feat:` повышает minor,
`fix:`/`perf:` — patch, `!` или `BREAKING CHANGE:` — major, в том числе до 1.0.
`docs:`, `spec:`, `chore:`, `build:`, `ci:`, `refactor:`, `test:`, `style:` и
`revert:` дают patch при выпуске. `chore(release):` — служебная запись,
исключённая из changelog и рекомендации версии. Release-it не запускается
автоматически после каждого commit. Номер связанной issue можно добавить в заголовок.

### Подготовка релиза

1. Обновить `main`, `develop` и теги командой `git fetch origin --tags`.
   Проверить, что текущий `develop` содержит последний релиз из `main`.
   Создать `release/<name>` от проверенного `develop` и выполнить `npm ci`.
2. Для backend и docs обновить `.ci/refs.json`: полные SHA совместимых соседних
   репозиториев. Эти revisions должны быть доступны в Gitea. Проверить именно
   их совместимость; движущиеся ветки не являются фиксацией состава релиза.
   Закоммитить обновлённые pins до подготовки версии.
3. Выполнить `npm run release:preview`. Проверить номер и changelog, затем
   `npm run release:prepare`. Команда создаёт `chore(release): X.Y.Z`, обновляет
   `package.json`, lockfile и `CHANGELOG.md`; теги и push не выполняет.
   Не использовать обход branch/clean/tag guards. Незакоммиченные файлы,
   неподходящая ветка, отсутствие изменений и уже подготовленная версия блокируют выпуск.
4. Проверить diff релизного коммита и штатные gates. Отправить только релизную
   ветку: `git push -u origin HEAD`. Открыть PR в `main` с заголовком
   `chore(release): X.Y.Z`. После зелёных `verify`, `security`, `commits`
   выполнить **fast-forward-only merge**. Если `main` изменился, сначала
   согласовать историю и повторить проверку кандидата; не обходить защиту.
5. После merge получить `main` и убедиться, что его HEAD — проверенный релизный
   коммит, версия и lockfile совпадают. На этом 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` не запускать: он уже подготовил версию.
6. Через PR `main → develop` вернуть релизный коммит в разработку без squash
   и rebase. Убедиться, что `develop` содержит тег. После первого выпуска
   `develop` создаётся непосредственно от релизного SHA.

Перед публикацией тегов сравнить local SHA с удалённым `main`; PR и проверки
должны относиться к этому кандидату. Опубликованные теги не перемещать.
При сбое после merge продолжить с создания отсутствующего тега, без нового bump.
При сбое до merge исправить релизную ветку и заново проверить кандидат;
подготовленную версию и changelog не повышать второй раз. Пять репозиториев
не имеют общей атомарной публикации: завершённость проверяется отдельно по каждому.

Первый выпуск задаётся явно: `npm run release:prepare -- 0.1.0` из
`release/0.1.0`. Начальные `0.0.0` — bootstrap-состояние до первого тега.
Исторические неконвенциональные commits не переписываются; первый changelog
требует просмотра человеком. Дальнейшие версии выбираются по commits.

### Hotfix, проверки и защита

Срочный fix начинается от `main`, проходит проверки и релизный PR из
`release/hotfix-<name>` в `main`, затем обязательно возвращается в `develop`.
Если ломается публичный контракт, major сохраняется и для hotfix.

Backend CI проверяет runtime OpenAPI с frontend; docs CI — межрепозиторные
ссылки. Для `main`, PR в `main` и `release/*` соседи берутся из `.ci/refs.json`;
для разработки — из `develop`. SHA записываются в логи. Для изменения сразу
нескольких репозиториев сначала согласовать их revisions, затем проверять
релизный набор; порядок публикации сам по себе не доказывает совместимость.

В Gitea для `main` и `develop` нужны запрет прямого push и force-push,
обязательные проверки `verify`, `security`, `commits` и запрет обхода правил
администратором. Требование отдельного одобрения review не вводится для
разработки одним владельцем. Ветка по умолчанию — `develop`; Renovate тоже
отправляет PR в `develop`. Теги `v*` защищены, создание разрешается владельцу
релиза; их удаление или перенос не входит в обычный процесс.

`node test-release.cjs` из root проверяет настоящий release-it во временном Git.
Для проверки конфигурации соседа после установки его dependencies:
`node test-release.cjs frontend` (аналогично backend, docs, specs).
Тест не публикует refs и не использует рабочие базы. Root `npm run verify`
включает tracking и этот тест; frontend/backend/docs сохраняют свои gates,
backend дополнительно требует `npm run test:e2e`.

Npm publishing, автоматический deploy и карточки Gitea Releases не включены.
Граница выпуска — принятый коммит, changelog и Git-тег.