main

2026-05-20 19:33:02 +03:00
commit f4bca8449e
30 changed files with 4152 additions and 0 deletions
@@ -0,0 +1,178 @@
+# ZBrain — Claude Code Context
+
+Этот файл читается Claude Code при работе в репозитории ZBrain. Описывает контекст проекта, конвенции, и где что искать.
+
+## Что это за проект
+
+ZBrain — централизованная база знаний для AI-агентов ZETIT. Это:
+- **Веб-админка** для управления несколькими gbrain instance'ами
+- **MCP-прокси** между Claude Code и gbrain с auth, rate limit, audit
+- **Многотенантная архитектура** с изоляцией БД на каждый брейн
+
+Полное описание — в [README.md](README.md), архитектура — в [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+
+## Контекст пользователя
+
+Этот проект разрабатывается **Зуевым Алексеем (ZETIT, ИП)**. Окружение:
+- **Продакшен серверы** работают на Ubuntu 22.04
+- **Сеть** — за FNA-прокси (`fna.zetit.ru:3128`, логин `client_001`)
+- **Git** — на git.zetit.ru (внутренний). Этот репо: `git@git.zetit.ru:zuevav/ZBrain.git`
+- **gbrain** — vendored mirror на `git@git.zetit.ru:zuevav/gbrain-mirror.git`
+- **Параллельные проекты** — ZetitConnect (тоже Node/React/Postgres), TeleraPharma инфра, личные проекты
+- **Стиль работы** — детальные spec'и + поэтапная реализация через Claude Code
+
+## Технологический стек
+
+| Слой | Технология |
+|------|-----------|
+| Backend runtime | Node.js 22 LTS + TypeScript 5.6 |
+| Backend framework | Express 4 |
+| ORM | Drizzle ORM |
+| Frontend | React 18 + Vite + TypeScript |
+| Styling | Tailwind CSS + shadcn/ui |
+| State | React Query + Zustand |
+| Forms | React Hook Form + Zod |
+| DB | PostgreSQL 16 + pgvector |
+| Auth | passport.js (local + yandex + github) |
+| Package manager | bun (workspaces) |
+| Testing | Vitest |
+| Deployment | Docker Compose + systemd для gbrain instances |
+
+## Структура репозитория
+
+```
+ZBrain/
+├── apps/
+│   ├── api/                # Backend Express app
+│   │   └── src/
+│   │       ├── routes/     # HTTP routes
+│   │       ├── services/   # бизнес-логика
+│   │       ├── middleware/ # auth, RBAC, rate limit
+│   │       ├── db/         # Drizzle schema и миграции
+│   │       └── lib/        # утилиты
+│   └── web/                # Frontend React app
+│       └── src/
+│           ├── pages/      # страницы (роуты)
+│           ├── components/ # переиспользуемые компоненты
+│           ├── hooks/      # React hooks
+│           └── api/        # клиент к /api
+├── packages/
+│   ├── shared/             # типы и схемы общие для api+web
+│   └── mcp-proxy/          # MCP proxy (валидация токенов, rate limit, audit)
+├── deploy/                 # Docker, systemd, nginx конфиги
+├── docs/                   # документация
+└── scripts/                # bash скрипты для VM
+```
+
+## Конвенции кода
+
+### TypeScript
+
+- `strict: true`, `noUncheckedIndexedAccess: true`
+- Все API ответы типизированы через `@zbrain/shared` types
+- Все request bodies валидируются через Zod schemas из `@zbrain/shared`
+- Никаких `any` без `// FIXME` комментария
+
+### Express routes
+
+```typescript
+// apps/api/src/routes/brains.ts
+import { Router } from 'express';
+import { requireAuth, requireRole } from '../middleware/auth.js';
+import { CreateBrainSchema } from '@zbrain/shared';
+
+export const brainsRouter = Router();
+
+brainsRouter.get('/', requireAuth, async (req, res) => {
+  const brains = await brainService.list(req.user);
+  res.json({ items: brains });
+});
+
+brainsRouter.post('/', requireAuth, requireRole(['owner', 'admin']), async (req, res) => {
+  const body = CreateBrainSchema.parse(req.body);
+  const brain = await brainService.create(body, req.user);
+  res.status(201).json(brain);
+});
+```
+
+### React components
+
+- Functional components с hooks (без class components)
+- Props типизированы через interface
+- Используем shadcn/ui компоненты, не пишем свои базовые (Button, Input)
+- React Query для всех server-state, Zustand только для UI state
+
+### Стиль ошибок
+
+```typescript
+// API возвращает структуру ApiError из @zbrain/shared
+res.status(400).json({
+  error: 'Validation failed',
+  code: 'VALIDATION_ERROR',
+  details: zodError.flatten(),
+});
+```
+
+## Что точно делать НЕ надо
+
+- **НЕ обращаться к gbrain напрямую из Claude Code** — только через brainhub-proxy
+- **НЕ хранить токены в plain text** — всегда хеш SHA-256
+- **НЕ логировать секреты** — пароли, токены, API ключи никогда не в logs
+- **НЕ создавать прямые SQL запросы** — только через Drizzle ORM
+- **НЕ забывать про audit log** для любых мутаций
+- **НЕ забывать про RBAC** — каждый mutate endpoint проверяет роль
+- **НЕ выставлять admin API на публичный порт 3010** — только /mcp и /oauth
+
+## Что делать ВСЕГДА
+
+- Перед началом нового спринта читать [docs/ROADMAP.md](docs/ROADMAP.md)
+- Перед написанием нового API endpoint смотреть в [packages/shared/src/types.ts](packages/shared/src/types.ts) — может тип уже есть
+- При изменении схемы БД — миграция через Drizzle, не вручную в Postgres
+- При добавлении нового permission/role — обновлять [docs/SECURITY.md](docs/SECURITY.md)
+- При нестандартном архитектурном решении — создавать ADR в [docs/DECISIONS/](docs/DECISIONS/)
+- Закоммитить миграции и schema файлы вместе с кодом, который их использует
+- Тесты для критичной логики (auth, MCP proxy, RBAC). UI можно без unit тестов в первой версии.
+
+## Полезные команды
+
+```bash
+# Установка
+bun install
+
+# Локальная разработка (запустить Postgres сначала)
+docker compose -f deploy/docker/docker-compose.dev.yml up -d
+bun run db:migrate
+bun run dev
+
+# Миграции
+bun run --cwd apps/api drizzle-kit generate
+bun run db:migrate
+
+# Запуск API + Web в watch mode
+bun run dev
+
+# Production build
+bun run build
+
+# Тесты
+bun run test
+```
+
+## Текущее состояние
+
+> Обновляй этот раздел после каждого закрытого спринта.
+
+- [x] **S0**: Инфраструктура VM (bootstrap скрипт готов)
+- [ ] **S1**: Первый gbrain instance (create-brain.sh готов, нужно тестирование)
+- [ ] **S2**: Brainhub каркас + локальный auth
+- [ ] **S3**: MCP Proxy + Tokens
+- [ ] **S4**: CRUD брейнов + источники + sync
+- [ ] **S5**: Dashboard + Projects + Connect
+- [ ] **S6**: OAuth + публичный контур
+- [ ] **S7**: Hardening
+
+## Связанные проекты
+
+- **gbrain** (vendored) — https://github.com/garrytan/gbrain (mirror в git.zetit.ru/zuevav/gbrain-mirror)
+- **ZetitConnect** — паттерны переиспользуем (Node/Express/React/Postgres стек)
+- **ZetitClaude Code setup** — FNA proxy конфигурация, tmux/zsh wrappers