DenozordecandCursor
c844874b0a
Docker / build (push) Failing after 27s
Пробы выполняются на роутере через /tool fetch и уходят в те же ingest API. Ежедневный запуск ставит scheduler, который каждый день заново качает .rsc со свежим токеном. Co-authored-by: Cursor <[email protected]>
146 lines
10 KiB
Markdown
146 lines
10 KiB
Markdown
# VPS Tracker — Руководство для ИИ
|
||
|
||
## Описание проекта
|
||
|
||
VPS Tracker — приложение для учёта виртуальных серверов (VPS), провайдеров, аккаунтов, платежей и балансов. Поддерживает синхронизацию с BILLmanager 6 API.
|
||
|
||
## Стек
|
||
|
||
- **Monorepo:** pnpm workspaces (`apps/*`, `packages/*`)
|
||
- **Frontend** (`apps/web`): Vite + React 19 + TypeScript, TanStack Router v1 + Query v5, shadcn/ui (`@cfdm/ui`), **ReUI** (`@reui` → `@/components/reui`), Tailwind v4, lucide-react, Recharts (через shadcn Chart), react-hook-form + Zod
|
||
- **Backend** (`apps/api`): Fastify 5 + TypeScript, `@fastify/*` plugins, контракты через `@cfdm/shared` (Zod)
|
||
- **DB** (`packages/db`): Drizzle ORM + better-sqlite3 (WAL, `foreign_keys=ON`)
|
||
- **Тесты:** Vitest (`app.inject()` для backend, `happy-dom` для frontend)
|
||
|
||
## Структура проекта
|
||
|
||
```
|
||
vps-tracker/
|
||
├── apps/
|
||
│ ├── web/ # Vite SPA (TSX) — TanStack + shadcn/ui + ReUI
|
||
│ │ └── src/
|
||
│ │ ├── routes/ # file-based (TanStack Router)
|
||
│ │ ├── queries/ # queryOptions + key factories
|
||
│ │ ├── components/ # shared + layout + domain
|
||
│ │ │ └── reui/ # ReUI CLI output (@reui/*)
|
||
│ │ └── lib/ # api-client, queryClient, router, schemas
|
||
│ └── api/ # Fastify 5 API (TS)
|
||
│ └── src/
|
||
│ ├── routes/ # тонкие plugins
|
||
│ ├── services/ # бизнес-логика + billmanager/
|
||
│ │ └── billmanager/ # client, parsers, mappers, operations, sync
|
||
│ └── plugins/ # @fastify/* registration
|
||
├── packages/
|
||
│ ├── ui/ # @cfdm/ui — shadcn primitives
|
||
│ │ └── src/
|
||
│ │ ├── components/ # output `shadcn add` (не трогать под кейс)
|
||
│ │ ├── hooks/ # use-mobile и др.
|
||
│ │ ├── lib/utils.ts # cn()
|
||
│ │ └── styles/globals.css # только output `shadcn apply --only theme`
|
||
│ ├── shared/ # @cfdm/shared — Zod-контракты, общие типы
|
||
│ └── db/ # @cfdm/db — Drizzle schema, repositories, миграции
|
||
│ └── src/
|
||
│ ├── schema/ # tables по сущностям
|
||
│ ├── repositories/ # typed queries
|
||
│ └── migrations/ # drizzle-kit
|
||
├── data/ # SQLite база (том Docker, gitignored)
|
||
├── pnpm-workspace.yaml
|
||
└── package.json
|
||
```
|
||
|
||
## Основные сущности
|
||
|
||
| Сущность | Описание |
|
||
|----------|----------|
|
||
| **providers** | Хостинг-провайдеры; для BILLmanager: **apiType**, **apiBaseUrl** (один URL на хостера) |
|
||
| **provider_accounts** | Аккаунты у провайдера; **apiCredentials** (логин:пароль API) для синка с BILLmanager |
|
||
| **vps** | Виртуальные серверы (ip, ram, disk, tariffType, paidUntil) |
|
||
| **payments** | Платежи (пополнение баланса, оплата VPS) |
|
||
| **balance_ledger** | Движения по балансу |
|
||
| **active_tariffs** | Тарифы, загруженные из BILLmanager vds.order |
|
||
| **settings** | Настройки приложения (baseCurrency, ratesUrl, syncEnabled) |
|
||
|
||
## Где искать код по доменам
|
||
|
||
- **Sync (BILLmanager)** — `apps/api/src/services/billmanager/`, `apps/api/src/routes/sync.ts`, scheduler в `apps/api/src/services/`
|
||
- **Тарифы** — `apps/api/src/services/billmanager/operations.ts` (fetchVdsOrderPricelist), `apps/api/src/services/billmanager/sync.ts`
|
||
- **VPS CRUD** — `apps/api/src/routes/vps.ts`, `packages/db/src/repositories/vps.ts`
|
||
- **Платежи/баланс** — `apps/api/src/routes/payments.ts`, `apps/api/src/routes/balance-ledger.ts`
|
||
- **Курсы валют** — `apps/web/src/lib/format.ts` (convertCurrency, formatInBaseCurrency), настройки в `settings.ratesUrl`
|
||
- **UI shared** — `apps/web/src/components/` + **`reui-kit/`** (`ResourcePage`, `KpiStatGrid`, `QuickActionGrid`, `OpsDashboard`, `SettingsShell`, `DetailPanel`; `FrameDataGrid` — internal simple-grid for ResourcePage)
|
||
- **UI primitives** — `packages/ui/src/components/*` (только output `shadcn add`)
|
||
- **ReUI enterprise** — `apps/web/src/components/reui/*` (output `shadcn add @reui/*`); см. [`reui-mcp.mdc`](.cursor/rules/reui-mcp.mdc)
|
||
|
||
## BILLmanager API
|
||
|
||
- [Guide to ISPsystem API](https://www.ispsystem.com/docs/b6c/developer-section/working-with-api/guide-to-ispsystem-software-api)
|
||
- [VDS API](https://www.ispsystem.com/docs/b6c/developer-section/billmanager-api/virtual-private-servers-vds)
|
||
- [Payments API](https://www.ispsystem.com/docs/b6c/developer-section/billmanager-api/payments-payment)
|
||
|
||
Формат запроса: `?authinfo=user:pass&out=bjson&func=vds|payment|dashboard.info|vds.order`
|
||
|
||
**Профили хостеров (overrides):** `apps/api/src/services/billmanager/profiles/` — матч по `apiBaseUrl`, новый хостер = один файл overrides + запись в registry. HOWTO: [`profiles/README.md`](apps/api/src/services/billmanager/profiles/README.md).
|
||
|
||
## Уведомления
|
||
|
||
- **Движок:** `apps/api/src/services/notifications/` — rules, dedup, engine, channels
|
||
- **Планировщик:** `apps/api/src/services/scheduler.ts` — sync отдельно; notify/uptime не зависят от `syncEnabled`; **CFDM pull** (домены → `vps_domains`) каждые **15 мин**, если включена интеграция + URL + токен (и при старте API)
|
||
- **События:** `payment_expiry`, `sync_digest`, `low_balance`, `new_tariffs`, `vps_down`, `vps_up`
|
||
- **Каналы:** Telegram (`telegram.ts`) и webhook (`webhook.ts`); webhook работает без Telegram
|
||
- **Журнал:** таблица `notification_log`, API `GET /api/notifications/log`
|
||
- **Дедупликация:** `notification_state` — daily / fingerprint / state_transition
|
||
|
||
## Статус блокировок (censorcheck)
|
||
|
||
Ручная проверка с VPS: `curl -fsSL https://vt.shnt.top/cc | bash` (тот же контейнер, Traefik dual Host).
|
||
Раз в сутки: `curl -fsSL https://vt.shnt.top/cc | bash -s -- --daily` (cron, свежий HMAC-токен на каждый запуск).
|
||
MikroTik 7.22+: `/tool fetch url="https://vt.shnt.top/cc.rsc" dst-path=vt-cc.rsc; /import file-name=vt-cc.rsc` (ежедневно: `?daily=1`, scheduler качает `.rsc` заново).
|
||
|
||
- **Vendor:** `apps/api/scripts/censorcheck/censorcheck.sh` (pin SHA `12c5839`, MIT)
|
||
- **Launcher:** `GET /cc` минтит HMAC ingest-токен (TTL 20 мин); по `/etc/os-release` ставит `jq`/`dig`/`column` без prompt; прогресс-бар в stderr; `GET /cc/vendor` — скрипт (LF); `--daily` / `--remove-daily`
|
||
- **MikroTik:** `GET /cc.rsc` — RouterOS-скрипт (HTTPS GET, без DPI); `?daily=1` / `?remove=daily`; scheduler `vt-cc`
|
||
- **Ingest:** `POST /api/integrations/censorcheck/runs` (без portal JWT)
|
||
- **UI:** `/blocking` — текущие прогоны и история, группировка VPS / сервис
|
||
- Env: `CENSORCHECK_INGEST_SECRET`, `CENSORCHECK_PUBLIC_URL`, `VPS_LAUNCHER_DOMAIN`
|
||
|
||
## GeoIP (ipregion)
|
||
|
||
Ручная проверка с VPS: `curl -fsSL https://vt.shnt.top/ic | bash`.
|
||
Раз в сутки: `curl -fsSL https://vt.shnt.top/ic | bash -s -- --daily`.
|
||
MikroTik 7.22+: `/tool fetch url="https://vt.shnt.top/ic.rsc" dst-path=vt-ic.rsc; /import file-name=vt-ic.rsc` (`?daily=1`).
|
||
|
||
- **Vendor:** `apps/api/scripts/ipregion/ipregion.sh` (pin SHA `7d1c25c`, MIT, [vernette/ipregion](https://github.com/vernette/ipregion))
|
||
- **Launcher:** `GET /ic` минтит HMAC ingest-токен (тот же `CENSORCHECK_INGEST_SECRET`); `GET /ic/vendor` — pinned скрипт (LF); `--daily` / `--remove-daily`
|
||
- **MikroTik:** `GET /ic.rsc` — primary GeoIP JSON + Cloudflare CDN; scheduler `vt-ic`
|
||
- **Ingest:** `POST /api/integrations/ipregion/runs` (без portal JWT)
|
||
- **UI:** `/geo` — матрица ISO-стран VPS × сервисы (primary / custom / cdn)
|
||
|
||
## Команды
|
||
|
||
```bash
|
||
pnpm install
|
||
pnpm --filter web dev # frontend dev
|
||
pnpm --filter api dev # backend dev
|
||
pnpm --filter web build # production build frontend
|
||
pnpm --filter api test # Vitest backend
|
||
pnpm --filter web test # Vitest frontend
|
||
```
|
||
|
||
## ReUI
|
||
|
||
- Registry: `@reui` в [`apps/web/components.json`](apps/web/components.json)
|
||
- **Design contract:** [`docs/ui-design-contract.md`](docs/ui-design-contract.md) — surface `frame`, kit `reui-kit/`
|
||
- Docs: [Introduction](https://reui.io/docs) · [llms.txt](https://reui.io/llms.txt) · [Get Started](https://reui.io/docs/get-started) · [MCP](https://reui.io/docs/mcp) · [Agent Skills](https://reui.io/docs/agent-skills) · [Cursor](https://reui.io/docs/cursor)
|
||
- Skill (локально): `.claude/skills/reui` / `.cursor/skills/reui` — версия `668fb463eb` (20 free components). Обновление: `curl.exe -fsSL https://mcp.reui.io/install | node -`
|
||
- Установка: `cd apps/web && pnpm dlx shadcn@latest add @reui/<name>`
|
||
- Правила: [`reui-mcp.mdc`](.cursor/rules/reui-mcp.mdc), [`shadcn-mcp.mdc`](.cursor/rules/shadcn-mcp.mdc)
|
||
- Зависимости ReUI в `apps/web`: `@tanstack/react-table`, `@tanstack/react-virtual`, `@dnd-kit/*`, `date-fns`, `react-day-picker`
|
||
|
||
## Соглашения
|
||
|
||
- UI — [ReUI PRO](https://reui.io/docs/get-started) first (MCP `user-reui`) + [shadcn/ui](https://ui.shadcn.com) primitives (MCP `plugin-shadcn-shadcn`)
|
||
- Design contract — [`docs/ui-design-contract.md`](docs/ui-design-contract.md) (Frame, hybrid KPI, QuickActionGrid, NavUser chrome)
|
||
- Коммиты — на русском, см. [`commit-messages-ru.mdc`](.cursor/rules/commit-messages-ru.mdc)
|
||
- Gitflow — см. [`gitflow.mdc`](.cursor/rules/gitflow.mdc)
|
||
- Структура — см. [`project-structure.mdc`](.cursor/rules/project-structure.mdc)
|