WealthLedger
Локальное приложение для портфеля T-Bank, операций, дохода и будущих выплат, а также ручного учёта банковских карт и расходов. Обзор продукта и документация системы.
Структура workspace
Workspace состоит из пяти независимых Git-репозиториев. Root — репозиторий
WealthLedger/main; вложенные checkout не являются submodules.
| Путь от root | Репозиторий Gitea | Назначение |
|---|---|---|
. |
WealthLedger/main |
Вход в workspace, инструкции и правила root tracking |
frontend/ |
WealthLedger/frontend |
React/Vite UI |
backend/ |
WealthLedger/backend |
NestJS API, Prisma и SQLite |
docs/ |
WealthLedger/docs |
Объяснение системы |
specs/ |
WealthLedger/specs |
Требования и OpenSpec |
Получение checkout
Нужны Git и SSH-доступ к Gitea на порту 2222. Из родительского каталога,
где ещё нет WealthLedger, выполните:
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 отслеживает только .gitignore, AGENTS.md, README.md и
test-workspace-tracking.py. Остальные 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).
Root не содержит npm-проекта. В frontend, backend и docs отдельно выполните
nvm install, nvm use --silent, npm ci.
После смены major Node переустановите native dependencies через npm ci.
Разрешения install scripts заданы в package.json соответствующего repo.
Для нового backend создайте .env по backend README,
замените оба placeholder-секрета и проверьте DATABASE_URL.
Существующий .env сохраняйте. Из backend:
nvm use --silent
npm run build
npx prisma migrate deploy
npm run start:dev
Build генерирует Prisma client. Перед миграцией существующей базы сохраните
согласованный backup и ключ шифрования; процедуру и ограничения отката смотрите
в описании хранения.
Известная ошибка fresh migration при RUST_LOG=warn/error устранена в
backend/prisma.config.ts: CLI удаляет унаследованную переменную.
Используйте штатный prisma migrate deploy из backend; прежний Prisma blocker
снят. Подробности и границы проверки.
В другом терминале подготовьте .env по frontend README,
затем из frontend:
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 из frontend/.nvmrc; проверенная версия CLI — 1.10.0.
Store wealth-ledger-specs расположен в specs/openspec/.
Работа с OpenSpec, команды validation.
Проверки
Перед 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 и backend. Для изменения проекта начните с AGENTS.