admin
4553f63deb
- monorepo (npm workspaces): apps/api (Fastify+Prisma+TS), apps/web (Vite+React+TS), packages/shared (zod schemas) - SSO via auth.queo.ru: jose+JWKS plugin, requireDocPermission(viewer|user|admin) - DEV_BYPASS_AUTH for local development (hard-checked off in production) - M2: organization upsert, clients CRUD with search, services catalog with soft-delete - BigInt -> Number serializer for Prisma money columns - Embedded Postgres + npm run dev:demo for one-command local boot - Docker compose for queoserver: postgres + api + web (nginx as ingress proxying /api -> api:3030) - First migration 0_init committed (prisma migrate diff) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
107 lines
4.7 KiB
Markdown
107 lines
4.7 KiB
Markdown
# Doc_manager
|
||
|
||
Сервис создания договоров, счетов и актов/УПД с интеграцией банка Точка. Часть экосистемы Queo.
|
||
|
||
## Стек
|
||
|
||
- **Backend** — Node.js 20+ / Fastify / Prisma / PostgreSQL (TypeScript, ESM).
|
||
- **Frontend** — React + Vite + TipTap (TypeScript).
|
||
- **Auth** — SSO через `auth.queo.ru` (RS256 JWT в cookie `q_at`, JWKS-валидация).
|
||
- **Bank** — Точка API: счета и акты/УПД создаются на стороне банка, договоры — наши.
|
||
|
||
## Структура
|
||
|
||
```
|
||
apps/
|
||
api/ # Fastify + Prisma
|
||
web/ # React + Vite
|
||
packages/
|
||
shared/ # zod-схемы и типы (DocBody, Tochka DTOs)
|
||
docker/
|
||
docker-compose.yml
|
||
Caddyfile
|
||
```
|
||
|
||
## Подготовка перед разработкой
|
||
|
||
1. **Node.js ≥ 20** — установлен.
|
||
2. **PostgreSQL** — локально или через Docker (`docker compose up postgres`).
|
||
3. **Auth_server** должен принимать редиректы на `doc.queo.ru` — добавить в `C:\project\Auth_server\.env`:
|
||
```
|
||
ALLOWED_RETURN_TO_HOSTS=auth.queo.ru,hall.queo.ru,cloud.queo.ru,doc.queo.ru
|
||
```
|
||
|
||
## Быстрый старт «пощупать прямо сейчас»
|
||
|
||
Нет Postgres / Docker / доступа к auth.queo.ru — всё равно работает:
|
||
|
||
```bash
|
||
npm install
|
||
npm run dev:demo
|
||
```
|
||
|
||
Что делает `dev:demo`:
|
||
- Запускает встроенный Postgres из `node_modules` (первый раз скачает ~80MB binaries в `data/embedded-pg/`).
|
||
- Накатывает схему через `prisma db push`.
|
||
- Сидит организацию `DEFAULT_ORGANIZATION_ID`.
|
||
- Поднимает API на `:3030` и web на `:5173` параллельно.
|
||
- В API включает `DEV_BYPASS_AUTH=1` — фейковый admin без auth.queo.ru.
|
||
|
||
Открыть `http://localhost:5173/` — попадаешь сразу в шелл (без логина), можно ходить:
|
||
- `/organization` — реквизиты компании,
|
||
- `/clients` — клиенты,
|
||
- `/services` — каталог услуг,
|
||
- остальное — заглушки до M3+.
|
||
|
||
Данные между перезапусками **сохраняются** в `data/embedded-pg/`. Чтобы начать с нуля — удалить эту папку.
|
||
|
||
⚠️ **Безопасность:** `DEV_BYPASS_AUTH=1` обходит JWT. API hard-checks: при `NODE_ENV=production` с этим флагом процесс отказывается стартовать.
|
||
|
||
## Полная установка (с реальным auth.queo.ru)
|
||
|
||
```bash
|
||
npm install
|
||
cp apps/api/.env.example apps/api/.env
|
||
# отредактировать DATABASE_URL, оставить DEV_BYPASS_AUTH=0
|
||
npm run prisma:migrate
|
||
npm run -w @doc-manager/api prisma:seed
|
||
npm run dev # api+web с настоящей SSO-авторизацией
|
||
```
|
||
|
||
API на `http://localhost:3030`, web — на `http://localhost:5173`. Перед этим добавить `doc.queo.ru` в `ALLOWED_RETURN_TO_HOSTS` в `C:\project\Auth_server\.env`.
|
||
|
||
## Тесты M1 (smoke)
|
||
|
||
- `GET http://localhost:3030/health` → `{ ok: true }`
|
||
- Открыть `http://localhost:5173` без cookie `q_at` → редирект на `https://auth.queo.ru/auth/login?return_to=...`.
|
||
- С валидной cookie от auth.queo.ru — `/api/me` отдаёт payload JWT.
|
||
|
||
## Тесты M2 (организация, клиенты, услуги)
|
||
|
||
С Postgres и применённой миграцией:
|
||
|
||
1. Поднять БД и применить миграцию:
|
||
```bash
|
||
docker compose -f docker/docker-compose.yml up -d postgres
|
||
npm run prisma:migrate # создаст первую миграцию
|
||
npm run -w @doc-manager/api prisma:seed # сидит DEFAULT_ORGANIZATION_ID
|
||
```
|
||
2. `GET /api/organization` → возвращает запись организации (после сида).
|
||
3. `GET /api/clients?q=...` — поиск по name/inn/email.
|
||
4. `GET /api/services?includeArchived=1` — каталог + архив.
|
||
5. В UI: `/organization` — заполнить реквизиты; `/clients` — добавить клиента; `/services` — добавить услугу с ценой и НДС.
|
||
|
||
SQL-предпросмотр миграции без БД: `apps/api/prisma/init.sql.preview` (генерируется через `prisma migrate diff`).
|
||
|
||
## План реализации
|
||
|
||
См. `C:\Users\VVMedia\.claude\plans\floofy-baking-jellyfish.md`. Этапы M1–M7.
|
||
|
||
## Деплой (домашний сервер)
|
||
|
||
```
|
||
ssh -i ~/.ssh/id_sat vmv@192.168.0.158
|
||
cd ~/Doc-manager
|
||
git pull && docker compose build && docker compose up -d
|
||
```
|