# ZBrain Roadmap

Документ для Claude Code: пошаговый план реализации с критериями готовности каждого спринта. Подходит как для последовательной разработки, так и для параллельной (некоторые спринты независимы).

## Принципы

- Каждый спринт заканчивается **рабочей фичей**, которую можно показать
- Каждый спринт мерж в `develop`, в `main` идут тегированные релизы
- Любой Claude Code инстанс может прочитать этот файл и понять, что делать дальше
- ADR (Architecture Decision Records) пишутся в `docs/DECISIONS/` для нестандартных решений

---

## Sprint 0: Инфраструктура VM (1 вечер)

**Цель**: Готовая VM, на которой работает Postgres и установлен gbrain.

**Задачи:**
- [ ] Создать VM: 4 vCPU / 8 GB RAM / 80 GB SSD / Ubuntu 22.04 LTS
- [ ] Назначить статический IP в сети ZETIT
- [ ] Добавить DNS: `brain.zetit.local` (внутренний) и `brain.zetit.ru` (внешний)
- [ ] Запустить `scripts/bootstrap-vm.sh`
- [ ] Создать Postgres пользователя `brainhub` с паролем
- [ ] Сгенерировать секреты для `.env` (SESSION_SECRET, JWT_SECRET, TOKEN_ENCRYPTION_KEY)
- [ ] Получить API ключи: OPENAI_API_KEY, ANTHROPIC_API_KEY

**Критерии готовности:**
- `systemctl status postgresql` показывает active
- `sudo -u postgres psql -d brainhub -c 'SELECT * FROM pg_extension'` возвращает vector, pg_trgm, pgcrypto
- `sudo -u zbrain bash -c 'PATH=$HOME/.bun/bin:$PATH bun --version'` работает
- `/etc/zbrain/.env` существует, заполнен, права 600

**Документировать:** реальные параметры VM (IP, hostname, дата создания) в `docs/INFRASTRUCTURE.md`

---

## Sprint 1: Первый gbrain instance (1 день)

**Цель**: Один работающий gbrain instance с импортированными тестовыми данными.

**Задачи:**
- [ ] Создать gbrain mirror в `git.zetit.ru/zuevav/gbrain-mirror`
- [ ] Запустить `scripts/create-brain.sh zetit "ZETIT MSP" 3001`
- [ ] Импортировать тестовый корпус (например, какие-то существующие markdown файлы)
- [ ] Проверить `curl http://localhost:3001/health` или эквивалент
- [ ] Прицепить локальный Claude Code напрямую к этому gbrain (без brainhub-прокси)
- [ ] Выполнить пару query и убедиться что работает

**Критерии готовности:**
- `systemctl status zbrain-gbrain-zetit` показывает active
- В БД есть страницы и эмбеддинги: `SELECT count(*) FROM pages, count(*) FROM content_chunks WHERE embedding IS NOT NULL`
- Claude Code успешно делает MCP запросы

**Известные риски:**
- gbrain v0.26 переехал на новый OAuth - возможно поломались CLI флаги. Зафиксировать рабочую версию тегом.
- FNA-прокси может блокировать какие-то OpenAI/Anthropic эндпоинты - проверить `curl --proxy ...` до запуска import.

---

## Sprint 2: Brainhub каркас + локальный auth (3-4 дня)

**Цель**: Работающий веб-интерфейс с login/logout, без функционала брейнов.

**Задачи:**

### apps/api (backend)
- [ ] Express + TypeScript скелет
- [ ] Структура: `routes/`, `services/`, `middleware/`, `db/`, `lib/`
- [ ] ORM выбрать: Drizzle (рекомендую за TS-first) или Prisma
- [ ] Миграции: создать таблицы `users`, `sessions`
- [ ] POST /api/auth/register (только для owner-команды, остальные через UI)
- [ ] POST /api/auth/login (email + password, bcrypt)
- [ ] POST /api/auth/logout
- [ ] GET /api/auth/me (current user)
- [ ] Session middleware (cookie + refresh token rotation)
- [ ] RBAC middleware: `requireRole('admin')`, `requireRole('owner')`

### apps/web (frontend)
- [ ] React + Vite + TypeScript + Tailwind + shadcn/ui
- [ ] Layout: sidebar + header + content
- [ ] Страницы: /login, /dashboard (заглушка), /profile
- [ ] React Router v6
- [ ] React Query для API
- [ ] Auth context + protected routes

**Критерии готовности:**
- На свежей БД создаётся initial owner из ENV (INITIAL_OWNER_EMAIL/PASSWORD)
- Можно войти через UI на /login
- /dashboard защищён, без auth редиректит на /login
- Cookie с session token, при logout удаляется
- Refresh token rotation работает (логин не истекает через 15 минут активной сессии)

---

## Sprint 3: MCP Proxy + Tokens (2-3 дня)

**Цель**: Claude Code на любом сервере подключается через brainhub, а не напрямую к gbrain.

**Задачи:**

### packages/mcp-proxy
- [ ] Express router, маунтится на `/mcp/:brain`
- [ ] Извлечение Bearer token из заголовков
- [ ] Кэш токенов в памяти (30s TTL) - не ходить в БД на каждый запрос
- [ ] Проверка: revoked, expired, IP allowlist, scope
- [ ] Резолв `:brain` → `localhost:PORT` через таблицу `brains`
- [ ] Прокси через `http-proxy-middleware` или nativный stream
- [ ] In-memory очередь для audit log + batch insert (раз в секунду)
- [ ] Throttled update `last_used_at` (не чаще раза в минуту на токен)

### apps/api: токены
- [ ] Таблица `access_tokens` (см. docs/SECURITY.md)
- [ ] POST /api/tokens (создание - возвращает plaintext token ОДИН РАЗ)
- [ ] GET /api/tokens (список с prefix, без full token)
- [ ] DELETE /api/tokens/:id (revoke - soft delete с revoked_at)
- [ ] GET /api/tokens/:id/usage (статистика)

### apps/web: UI для токенов
- [ ] /tokens страница со списком
- [ ] Создание токена: имя + scope checkboxes + TTL + IP allowlist
- [ ] После создания - модалка с токеном и кнопкой copy (показывается один раз!)
- [ ] Revoke с подтверждением

**Критерии готовности:**
- Создал токен в UI с scope `mcp:read:zetit`
- Подключил Claude Code: `mcpServers.zbrain.url = http://brain.zetit.local/mcp/zetit`, header `Authorization: Bearer brain_pat_...`
- Запрос идёт через brainhub, в audit log записывается
- Revoke токена через UI → следующий запрос Claude Code получает 401
- При двух токенах одного scope работают оба

---

## Sprint 4: CRUD брейнов + источники + sync (2-3 дня)

**Цель**: Создание новых брейнов через UI, добавление и синхронизация источников.

**Задачи:**

### apps/api
- [ ] Таблицы `brains`, `sources`
- [ ] POST /api/brains - создание (внутренний вызов `scripts/create-brain.sh` или эквивалент на TS)
- [ ] GET /api/brains - список со статистикой (page_count, embed_coverage)
- [ ] GET /api/brains/:id - детали
- [ ] DELETE /api/brains/:id - удаление (с подтверждением, дамп перед удалением)
- [ ] POST /api/brains/:id/sources - добавление источника (git, local_dir)
- [ ] POST /api/brains/:id/sources/:sourceId/sync - запуск sync
- [ ] GET /api/brains/:id/sources/:sourceId/sync/stream - SSE с прогрессом
- [ ] Worker queue для sync (bullmq или нативный setInterval)
- [ ] Планировщик cron-based sync (node-cron)

### apps/web
- [ ] /brains страница со списком
- [ ] /brains/new форма создания
- [ ] /brains/:id - tabs: Overview, Sources, Browse, Query, Activity
- [ ] Sources tab: список с status, кнопки Sync now / Edit / Delete
- [ ] Sync с realtime прогрессом через SSE
- [ ] Подсветка статусов: green/yellow/red

**Критерии готовности:**
- Создать брейн `community` через UI → автоматически создаётся БД, запускается gbrain, регистрируется systemd unit
- Добавить git source → запустить sync → видеть прогресс в реальном времени
- Расписание sync каждые 6 часов работает
- Удаление брейна делает дамп и убирает все артефакты

**Важно:** удаление брейна - irreversible операция, обязательно подтверждение через ввод имени брейна (как в GitHub).

---

## Sprint 5: Dashboard + Projects + Connect (2-3 дня)

**Цель**: Полноценный UI с визуализацией проектов и copy-paste готовыми сниппетами.

**Задачи:**

### apps/api
- [ ] Таблицы `projects`, `project_connections`
- [ ] CRUD endpoints для projects
- [ ] POST /api/projects/:id/connections - привязка проекта к брейну с указанием токена
- [ ] GET /api/connect/snippets/:brainId?client=claude-code|cursor|cli - генерация сниппетов

### apps/web
- [ ] /dashboard - сводка: количество брейнов, total pages, active sync jobs, recent activity
- [ ] /dashboard карточки брейнов с цифрами
- [ ] /projects - таблица проектов с привязкой к брейнам
- [ ] /projects/:id - детали + кнопка "Connect new brain"
- [ ] /brains/:id/connect - страница с готовыми сниппетами:
    - Claude Code JSON (для `~/.claude/mcp.json` или `.claude/mcp.json` в проекте)
    - Cursor конфиг
    - Bash one-liner для CLI
    - QR код с готовой строкой подключения
- [ ] Copy-to-clipboard на каждом блоке
- [ ] Глобальный поиск по всем брейнам (с уважением scope)

**Критерии готовности:**
- Dashboard загружается за <500ms
- В Projects вижу таблицу: ZetitConnect → [zetit (write), personal (read)]
- На странице Connect - готовая JSON структура с реальным URL и токеном, копируется одним кликом
- QR-код корректно сканируется и содержит JSON

---

## Sprint 6: OAuth + публичный контур (2-3 дня)

**Цель**: Авторизация через Yandex/GitHub OAuth, публичный endpoint для MCP.

**Задачи:**

### apps/api
- [ ] Зарегистрировать OAuth приложения у Yandex и GitHub
- [ ] passport.js + passport-yandex + passport-github2
- [ ] OAuth flow: /oauth/yandex, /oauth/yandex/callback (аналогично GitHub)
- [ ] Привязка к existing user по email match (с подтверждением)
- [ ] Поддержка регистрации нового пользователя через OAuth (опционально, по INVITE_ONLY флагу)
- [ ] Отдельный Express app на 3010 порту, монтирует только /mcp и /oauth

### deploy
- [ ] Получить TLS сертификат от Let's Encrypt для brain.zetit.ru
- [ ] Включить nginx public server-блок
- [ ] Проверить, что внутренний и публичный API не пересекаются (нет утечки UI на публичный)

**Критерии готовности:**
- Залогиниться через "Sign in with Yandex" - работает
- На публичном endpoint `https://brain.zetit.ru/api/brains` → 404
- На публичном endpoint `https://brain.zetit.ru/mcp/zetit` → работает с токеном
- TLS A+ rating на SSL Labs

---

## Sprint 7: Hardening (2-3 дня)

**Цель**: Production-ready: бэкапы, мониторинг, 2FA, документация.

**Задачи:**
- [ ] /audit страница в UI с фильтрами (actor, action, resource, date range)
- [ ] CSV export audit log
- [ ] 2FA (TOTP) опционально для каждого пользователя
- [ ] Проверить и настроить `scripts/backup.sh`, добавить в cron
- [ ] Тестовое восстановление из бэкапа на отдельной VM
- [ ] Prometheus endpoint /metrics: request rate, error rate, db connections, queue depth
- [ ] Health endpoint с глубокой проверкой (DB connectivity, gbrain instances)
- [ ] Alerts на падение sync, на error rate > N
- [ ] Documentation: docs/API.md, docs/SECURITY.md, docs/OPERATIONS.md
- [ ] Load test: 100 RPS на /mcp, что выдерживает

**Критерии готовности:**
- Восстановление из бэкапа прошло успешно
- Включил 2FA на owner аккаунте, работает
- /metrics возвращает prometheus formatted text
- Audit log имеет все важные события: brain.create, brain.delete, token.create, token.revoke, user.login, user.logout, mcp.call

---

## После Sprint 7: миграция данных

**Цель**: Перенести всё что нужно в соответствующие брейны.

- [ ] Создать брейны: zetit, telerapharma, personal, community (если ещё не созданы)
- [ ] Источники для zetit: ZetitConnect docs repo, ZETIT internal wiki
- [ ] Источники для telerapharma: runbook'и Exchange/MikroTik/1C
- [ ] Источники для personal: личный markdown garden, "Хлеб и молоко" docs
- [ ] Источники для community: документы Смоленская 10
- [ ] Переключить Claude Code на всех серверах с локального чтения на gbrain через brainhub
- [ ] Удалить дублированную документацию из локальных копий (оставить только в источниках)

---

## Дальнейшее развитие

- Импорт из Notion, Obsidian, Confluence через gbrain skills
- Webhook'и: уведомления в Slack/Telegram при критичных событиях
- API для интеграций с другими системами (1С, FortiGate logs)
- Mobile-friendly UI (адаптив или отдельная PWA)
- Multi-user collaboration на одном брейне (комментарии, suggestions)
- Версионирование промптов и skills через gbrain