zuevav
275 lines
15 KiB
Markdown
275 lines
15 KiB
Markdown
# 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
|