init: M1 scaffolding + M2 organization/clients/services CRUD

- 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>
2026-04-30 21:24:26 +03:00
commit 4553f63deb
52 changed files with 7110 additions and 0 deletions
@@ -0,0 +1,106 @@
+# 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
+```