voidea/SESSION_CONTEXT.md

# 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
================================================================================