Initial commit: VoIdeaAI - voice-first AI idea assistant

SESSION_CONTEXT.md

@@ -0,0 +1,453 @@
+# VoIdea - Session Context
+# Этот файл самопополняется при каждом общении
+# Структурирован для понимания AI-агентами и разработчиками
+
+Last Updated: 2026-05-12T22:45:00.000000+00:00
+================================================================================
+# ИНСТРУКЦИЯ ДЛЯ AI (OpenCode)
+Last Updated: 2026-05-10T21:00:00.000000+00:00
+================================================================================
+
+ПЕРЕД НАЧАЛОМ РАБОТЫ ОБЯЗАТЕЛЬНО ПРОЧТИ ЭТОТ ФАЙЛ!
+
+Этот файл — единая точка входа для понимания проекта и контекста общения.
+Обновляется автоматически после каждой сессии.
+
+Last Updated: 2026-05-10T15:41:04.073549+00:00
+================================================================================
+# ПРОЕКТ: VoIdea
+Last Updated: 2026-05-10T15:41:04.073549+00:00
+================================================================================
+
+## Описание
+VoIdea ("Голос Идей") — гибридное приложение (мобильное + веб) для фиксации 
+и проработки идей с помощью группового ИИ-анализа.
+
+## Ключевые требования
+- Работа в условиях нестабильного интернета или оффлайн
+- Максимальная защита данных пользователя
+- Гибкий выбор ИИ-моделей (локальных и облачных)
+- Синхронизация данных между устройствами через VPS
+
+## Технологический стек
+- Backend: Python FastAPI, Port 8020
+- Database: PostgreSQL
+- Cache/Queue: Redis + Celery
+- Frontend: React + TypeScript + Tailwind CSS (PWA)
+- Mobile: iOS/Android (параллельно с вебом)
+- AI: Yandex GPT, GigaChat
+
+## Лицензия
+AGPL-3.0
+
+Last Updated: 2026-05-10T15:41:04.073549+00:00
+================================================================================
+# ДОГОВОРЁННОСТИ И ПРАВИЛА
+Last Updated: 2026-05-10T15:41:04.073549+00:00
+================================================================================
+
+## ОБЯЗАТЕЛЬНЫЕ ПРАВИЛА
+
+1. **ЯЗЫК**: Все вопросы — на русском языке
+2. **РЕКОМЕНДАЦИИ**: Всегда даю рекомендации с пояснениями
+   - Объясняю почему рекомендую именно это
+   - Учитываю правильность кодирования и перспективу проекта
+3. **КАЧЕСТВО КОДА**: Кривой код = переписать сразу
+   - Не тянем "как-нибудь" дальше
+   - Лучше потратить время сейчас чем потом переписывать
+4. **ПРИОРИТЕТ ПРАВИЛ**: docs/blocks/00-rules.md — основа всего
+   - Если что-то не описано в блоке — смотрим 00-rules.md
+   - Только потом задаём вопрос пользователю
+
+## АРХИТЕКТУРНЫЕ РЕШЕНИЯ (ADR)
+
+### ADR-001: PostgreSQL как БД
+- Выбрана PostgreSQL для всех данных
+- ACID транзакции, JSONB для гибкости
+- Масштабируемость до тысяч пользователей
+
+### ADR-002: 11 системных агентов
+- DocAgent, AuditAgent, SecurityAgent, SpecAgent, ObserverAgent
+- QATesterAgent, FixAgent, UITestAgent, RolloutAgent
+- EvolutionAgent, BacklogAgent
+
+### ADR-003: OAuth схема — один пользователь = один провайдер
+- НЕЛЬЗЯ привязать Google к аккаунту зарегистрированному через Яндекс
+- Нельзя добавить второй OAuth провайдер
+- Провайдеры: Email, Яндекс, Google, Apple (отложен)
+
+### ADR-004: Постепенное развёртывание (Rollout)
+- Stage 0: Development (тесты агентов)
+- Stage 1: 3 пользователя
+- Stage 2: 1%
+- Stage 3: 5%
+- Stage 4: 15%
+- Stage 5: 100% (Production)
+- Решение принимает RolloutAgent + человек
+
+### ADR-005: Design Tokens (JSON)
+- Единый источник истины: docs/design-system/tokens.json
+- Генераторы для CSS, Swift, Kotlin
+- 3 темы: system (auto), dark, light
+
+### ADR-006: Agent Versioning
+- Каждый агент версионируется независимо (A.B.C)
+- Changelog: CHANGELOG/agents/<name>.md
+- Авто-детект через SHA256 checksum от __file__
+- EvolutionAgent управляет minor/major, агенты — patch
+
+## СИСТЕМНЫЕ АГЕНТЫ (11 штук)
+
+| Агент | Ответственность | Триггеры |
+|-------|-----------------|----------|
+| DocAgent | Документация, комментарии, Runbook | pre-commit, push, manual |
+| AuditAgent | Соблюдение правил, прогресс проекта | pre-commit, daily, manual |
+| SecurityAgent | Безопасность, уязвимости, 152-ФЗ | pre-commit, weekly, manual |
+| SpecAgent | Спецификации, версионирование **проекта**, CHANGELOG | tag creation, push |
+| ObserverAgent | Наблюдение за пользователями | continuous, daily report |
+| QATesterAgent | Функциональное тестирование | pre-commit, daily, manual |
+| FixAgent | Исправление багов (создаёт PR) | QATesterAgent results |
+| UITestAgent | Визуальное тестирование | weekly, manual |
+| RolloutAgent | Постепенное развёртывание | after tests, manual |
+| EvolutionAgent | Саморазвитие и **версионирование агентов** | daily, learning |
+| BacklogAgent | Управление отложенными задачами | continuous |
+
+### Особенности агентов:
+- Автоматический запуск (pre-commit, push, cron)
+- Ручной запуск через админ-панель (кнопка)
+- Делегирование между собой при необходимости
+- Саморазвитие через EvolutionAgent
+- Чёткое описание ролей и поведения
+
+## ИИ-АГЕНТЫ (11 ролей для анализа идей)
+
+| Роль | Провайдер | Описание |
+|------|-----------|----------|
+| Координатор | Yandex GPT | Управляет диалогом, обобщает результаты |
+| Организатор задач | Yandex GPT | Разбивает идею на шаги |
+| Бизнес-аналитик | Yandex GPT | Оценивает ROI, сроки, аудиторию |
+| Юрист | GigaChat | Проверяет соответствие законам РФ |
+| Финансовый консультант | Yandex GPT | Составляет смету, прогноз доходов |
+| Архитектор решений | Yandex GPT | Проектирует архитектуру |
+| Тестировщик | Yandex GPT | Составляет тест-кейсы |
+| UI-дизайнер | Yandex GPT | Прорабатывает интерфейс |
+| SMM-специалист | Yandex GPT | Планирует продвижение |
+| Лайф-коуч | Yandex GPT | Помогает ставить цели |
+| Эксперт по доступности | Yandex GPT | Проверяет инклюзивность |
+
+### Fallback chain для ИИ-агентов:
+1. Yandex GPT → первичный
+2. GigaChat → при недоступности
+3. Error → вернуть сообщение с retry suggestion
+
+## ДИЗАЙН-СИСТЕМА
+
+### Структура
+- docs/design-system/tokens.json — единый источник истины
+- docs/design-system/generators/ — Python CLI генераторы
+- app/design-tokens/ — сгенерированные файлы (CSS, Swift, Kotlin)
+
+### Темы
+- system (auto) — определяется по OS
+- dark — тёмная тема
+- light — светлая тема
+
+### Генераторы
+- CSS Generator → app/design-tokens/css/theme.css
+- Swift Generator → app/design-tokens/swift/Colors.swift
+- Kotlin Generator → app/design-tokens/kotlin/colors.xml
+
+## АДМИН-ПАНЕЛЬ
+
+### Функции
+- Просмотр логов (фильтры, критичность)
+- Управление агентами (запуск, статус, отчёты)
+- Пользователи (CRUD, роли)
+- Системное здоровье (БД, Redis, uptime)
+
+### Логи
+- PostgreSQL (system_logs) + файлы
+- Критические: RED + email админу
+- Предупреждения: ORANGE
+- Обычные: не подсвечивать
+
+## БЕЗОПАСНОСТЬ
+
+- .env никогда в git
+- JWT: HS256, 60min access, 30 days refresh
+- Пароли: bcrypt
+- Pydantic валидация на всех входах
+- RBAC: user, admin, owner
+- Защита ввода (от взлома и атак)
+
+## ЛОГИРОВАНИЕ
+
+- Формат: JSON для автоматизации
+- Для людей: админ-панель с цветовой подсветкой
+- Структура: [ISO8601] [LEVEL] [component] message key=val
+- Запрещено логировать: пароли, JWT, API keys, raw email
+
+## BACKLOG ЗАМЕТКИ
+
+- design-system-generators-note.md
+- rollout-process-note.md
+- agent-evolution-note.md
+- qa-tester-agent-note.md
+- fix-agent-note.md
+- hotkeys-system-note.md
+- undo-redo-note.md
+- export-formats-note.md
+- oauth-schema-note.md
+- changelog-generation-note.md
+- ui-themes-note.md
+- car-integration-note.md (ГУ автомобиля — изучить)
+- rate-limiting-note.md
+- observer-metrics-stages-note.md
+- temp-users-cleanup-note.md
+
+## ВЕРСИОНИРОВАНИЕ
+
+### Проект (SpecAgent)
+- Формат: MAJOR.MINOR.PATCH (SemVer)
+- CHANGELOG/v*.md — файлы по версиям
+- Новый файл при смене X или Y, патчи в существующий
+
+### Агенты (EvolutionAgent + само-детект)
+- Каждый агент: A.B.C, независимо от проекта
+- CHANGELOG/agents/<name>.md — вся история в одном файле
+- SHA256 checksum от __file__ → авто-бамп patch
+- EvolutionAgent: minor при новой capability, major при breaking change
+
+## ПЛАН РАЗРАБОТКИ (ФАЗЫ)
+
+```
+ФАЗА 1: FOUNDATION (2-3 недели) ✅ ЗАВЕРШЕНО
+├── 00-rules.md ✅
+├── 01-core ✅
+├── System Agents (6 штук) ✅
+├── 02-data ⏳ (следующий)
+└── 08-devops
+```
+
+Last Updated: 2026-05-10T15:41:04.073549+00:00
+================================================================================
+# ИСТОРИЯ СЕССИЙ
+Last Updated: 2026-05-10T15:41:04.073549+00:00
+================================================================================
+
+## Session 2026-05-10 (Первая сессия)
+
+### Настроение
+Продуктивная, конструктивная. Owner вовлечён, задаёт вопросы, быстро принимает решения.
+
+### Ключевые решения сессии
+1. ✅ Создана структура проекта (folders, docs)
+2. ✅ Адаптирован 00-rules.md для VoIdea
+3. ✅ Создан детальный план (PLAN.md)
+4. ✅ Зафиксированы 11 backlog заметок
+5. ✅ Созданы 5 ADR файлов
+6. ✅ Созданы 11 spec файлов для ИИ-агентов
+7. ✅ Создан quick-start в runbook
+8. ✅ Реализован Block 1: Core
+9. ✅ Созданы 6 системных агентов (DocAgent, BacklogAgent, SpecAgent, AuditAgent, ObserverAgent, EvolutionAgent)
+10. ✅ Создан AgentRegistry для централизованного управления
+11. ✅ Созданы триггеры (pre-commit, cron, manual)
+12. ✅ Созданы тесты для всех агентов
+
+### Что уже создано (55+ файлов)
+- docs/blocks/: 00-rules.md, PLAN.md, AUDIT.md, BACKLOG.md, VERSIONS.md, GLOSSARY.md, full.md
+- docs/backlog/: 15 файлов (все backlog заметки)
+- docs/adr/: 5 файлов (001-005)
+- docs/specs/agents/: 11 файлов (все ИИ-агенты)
+- docs/instructions/: 4 файла (system-prompt, developer, tester, admin)
+- docs/design-system/: tokens.json, README.md
+- docs/runbook/: 01-quick-start.md
+- app/core/: все файлы Block 1
+- app/: __init__.py, main.py, README.md
+- app/agents/ (НОВОЕ): base.py, models.py, registry.py, triggers.py
+- app/agents/ (НОВОЕ): doc_agent.py, backlog_agent.py, spec_agent.py, audit_agent.py, observer_agent.py, evolution_agent.py
+- tests/unit/agents/: 7 тестовых файлов
+
+### Текущий прогресс
+- Block 0: Rules ✅
+- Block 1: Core ✅
+- System Agents (6): DocAgent, BacklogAgent, SpecAgent, AuditAgent, ObserverAgent, EvolutionAgent ✅ (Все созданы!)
+- System Agents (5): SecurityAgent, QATesterAgent, FixAgent, UITestAgent, RolloutAgent ⏳ (Ожидают)
+- Остальное: ожидает
+
+### Следующие шаги
+1. Block 2: Data (миграции, модели БД)
+2. Настройка локального окружения (PostgreSQL)
+3. Запуск первого рабочего API
+4. Создание оставшихся 5 системных агентов (SecurityAgent, QATesterAgent, FixAgent, UITestAgent, RolloutAgent)
+
+### Особые замечания
+- Owner просит все вопросы на русском
+- Owner принимает все рекомендации с пояснениями
+- Кривой код = переписать сразу (принцип Owner)
+- Вопросы задавать только когда НЕ описано в 00-rules.md
+- Созданы 6 системных агентов: DocAgent, BacklogAgent, SpecAgent, AuditAgent, ObserverAgent, EvolutionAgent
+- Агенты могут запускаться автоматически (pre-commit, cron) или вручную
+- Registry обеспечивает централизованное управление агентами
+- Хранение состояния: PostgreSQL (отчёты, метрики) + Redis (быстрые обновления статуса)
+
+### Нерешённые вопросы
+- Точная дата переезда на VPS
+- Домен (пока подбирает)
+
+## Session 2026-05-10 (Вторая сессия)
+
+### Настроение
+Owner принимает решения быстро, без лишних обсуждений.
+
+### Ключевые решения сессии
+1. ✅ Принята архитектура версионирования агентов (A.B.C) — ADR-006
+2. ✅ Agent versioning отделён от project versioning
+3. ✅ Каждый агент сам детектирует изменения через SHA256 checksum
+4. ✅ EvolutionAgent управляет minor/major бампами
+5. ✅ Changelog агентов: CHANGELOG/agents/<name>.md
+6. ✅ SpecAgent — только версионирование проекта (уточнено)
+7. ✅ Определён формат A.B.C для агентов
+
+### Что сделано в этой сессии
+- **ADR-006** — Agent Versioning (docs/adr/006-agent-versioning.md)
+- **00-rules.md** — §4.4 Agent Versioning, §20 уточнён
+- **VERSIONS.md** — раздел Agent Versioning
+- **GLOSSARY.md** — термины Agent Version, Checksum, Changelog
+- **BACKLOG.md** — задачи по версионированию агентов
+- **requirements.txt** — обновлён под VPS (fastapi==0.115.6 и т.д.)
+- **AgentConfig** — last_run_at → DateTime, +version, +checksum
+- **BaseAgent** — compute_checksum(), bump_version(), _check_version(), _write_changelog_entry()
+- **EvolutionAgent** — actions: version_check, version_bump (minor/major)
+- **CHANGELOG/agents/** — 11 файлов с начальной версией 1.0.0
+- **test_base.py** (новый) — 12 тестов на versioning
+- **test_evolution_agent.py** — 16 тестов (добавлены version_check/bump)
+- **Исправлено**: `metadata` → `extra` в agents/models.py (reserved word)
+- **Исправлено**: `AgentTrigger.TAG_CREATION` добавлен в base.py
+- **Исправлено**: QATesterAgent импорт User из app.models.user
+- **Исправлено**: FixAgent._identify_error_type (улучшено распознавание)
+- **Исправлено**: app.core.config добавлен глобальный `settings`
+- **111 тестов** — все проходят
+
+### Текущий прогресс
+- Block 0: Rules ✅
+- Block 1: Core ✅
+- Block 2: Data (модели) ✅
+- Block 3: API (25 routes) ✅
+- Block 5: Services (5 базовых) ✅
+- System Agents (11): Все ✅
+- Test coverage: 125 tests ✅
+- ADR: 006 ✅
+- CHANGELOG/agents/: 11 files ✅
+
+### Следующие шаги
+1. Block 5-bis: AI integrations (Yandex GPT, GigaChat, Fallback)
+2. Block 4: WebUI
+3. Настройка PostgreSQL локально
+
+## Session 2026-05-10 (Третья сессия)
+
+### Ключевые решения сессии
+1. ✅ Block 3: API полностью реализован (25 routes)
+2. ✅ Tags: PostgreSQL ARRAY (рекомендация принята)
+3. ✅ Sync делаем в этом блоке (решение Owner)
+4. ✅ Admin — полное управление (потом дополним)
+5. ✅ POST /ideas/{id}/analyze — заглушка до Block 5-bis
+
+### Что создано в этой сессии
+- **app/schemas/** — 7 файлов: auth, user, idea, agent, sync, admin
+- **app/services/** — 5 файлов: auth, user, idea, agent, sync
+- **app/api/v1/** — 7 файлов: __init__, auth, users, ideas, agents, sync, admin
+- **app/core/dependencies.py** — переписан (get_db, get_current_user, require_admin)
+- **app/models/idea.py** — tags → ARRAY(String(50))
+- **app/main.py** — подключён api_v1_router
+- **tests/unit/api/** — 2 файла: test_routes, test_schemas
+
+### API Routes (25 шт.)
+| Роутер | Endpoints |
+|--------|-----------|
+| auth | POST register, login, refresh; GET oauth/{provider}, callback |
+| users | GET/PATCH/DELETE /me |
+| ideas | GET/POST /, GET/PATCH/DELETE /{id}, POST /{id}/analyze |
+| agents | GET /, GET /{name}, POST /{name}/run |
+| sync | POST /pull, /push |
+| admin | GET /users, PATCH /users/{id}/role, GET /health, /logs |
+
+### Исправлено
+- `dependencies.py` — полностью переписан под актуальные модели User (is_superuser вместо role)
+- `get_current_user` — теперь возвращает User, а не dict
+- `require_admin` — проверяет is_superuser
+- `tests/conftest.py` — убран PROJECT_NAME override (ломало тесты)
+
+### Тесты: 125 passed
+
+Last Updated: 2026-05-10T15:41:04.073549+00:00
+================================================================================
+# АКТИВНЫЕ ЗАМЕТКИ
+Last Updated: 2026-05-10T15:41:04.073549+00:00
+================================================================================
+
+### К изучению
+- Интеграция с ГУ автомобиля (Android Auto / CarPlay)
+
+### К реализации позже
+- Rate limiting для ИИ-агентов
+- Локальные ИИ-модели
+- Apple OAuth
+
+### Возможные улучшения
+- Автоматическая документация API (генерация из Pydantic)
+- Типобезопасные агенты (TypedDict + Pydantic)
+- Мониторинг агентов в реальном времени (WebSocket)
+- Feature Flags для rollout
+
+Last Updated: 2026-05-10T15:41:04.073549+00:00
+================================================================================
+# КОНТАКТЫ
+Last Updated: 2026-05-10T15:41:04.073549+00:00
+================================================================================
+
+Project Owner: [Указать после заполнения]
+License: AGPL-3.0
+Version: 1.0.0
+
+Last Updated: 2026-05-10T15:41:04.073549+00:00
+
+Last Updated: 2026-05-12T22:45:00.000000+00:00
+================================================================================
+# Session 2026-05-12 (Web App Engine — документация + код-стайл + инструменты)
+================================================================================
+
+### Ключевые решения сессии
+1. ✅ Zustand для новых сториджей (Context не трогать)
+2. ✅ react-hook-form + zod для сложных форм
+3. ✅ WCAG AA через eslint-plugin-jsx-a11y (enforcement)
+4. ✅ i18n-ready: строки через strings.ts, <T>, заглушка en.json
+5. ✅ ErrorBoundary обязателен вокруг Layout
+6. ✅ React 18 фиксирован (19 — отдельный этап)
+7. ✅ QATesterAgent — новый vitest режим
+8. ✅ Дизайн-токены: 3 генератора (CSS, Swift, Kotlin) реализованы
+
+### Что создано в этой сессии
+- Документация: STYLE_GUIDE.md, SPECIFICATION.md, TECHNICAL.md, PROJECT_GUIDE.md
+- Обновлено: user-guide.md (PWA), admin-guide.md (VPS deploy), template/docs/00-rules.md (ESLint+Vitest)
+- Компоненты: ErrorBoundary.tsx, SkipToContent.tsx, T.tsx
+- Стор: stores/auth.ts (Zustand) + AuthContext wrapper
+- Формы: LoginPage, RegisterPage, IdeaCreate, IdeaEdit (react-hook-form+zod)
+- WCAG AA: VoiceInput (aria-label+keyboard), VoiceChat (role=log), SettingsPage (htmlFor/id)
+- i18n: constants/strings.ts, i18n/en.json
+- Агент: QATesterAgent._run_vitest_tests()
+- Генераторы: css_generator.py, swift_generator.py, kotlin_generator.py
+- Инструменты: tools/backup_db.py, tools/metrics_service.py
+- CI: .github/workflows/ci.yml — frontend lint + test jobs
+- Тесты: 7 Vitest тестов (ErrorBoundary, SkipToContent, strings) — все passed
+- TypeScript: tsc --noEmit — 0 errors
+
+### Зависимости (npm)
+- Zustand 5.x, react-hook-form 7.x, zod 4.x, @hookform/resolvers
+- Vitest 4.x, @testing-library/react, jsdom
+
+================================================================================
+# КОНЕЦ КОНТЕКСТА
+Last Updated: 2026-05-12T22:45:00.000000+00:00
+================================================================================