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/.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/.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/.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, , заглушка 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