119 lines
7.4 KiB
Markdown
119 lines
7.4 KiB
Markdown
# 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 отслеживает только `.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](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 из `frontend/.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).
|