Initial commit: VoIdeaAI - voice-first AI idea assistant

old/00-rules.md

@@ -0,0 +1,467 @@
+# Block 0: Rules & Conventions — VoIdea
+
+Конституция проекта VoIdea. Применяется ко всем блокам.
+Если в специфичном блоке нет явного описания ситуации — решение принимается по правилам Block 0.
+
+---
+
+## 1. Code Style Standards
+
+**Python (PEP8 + автоматизация):**
+- Кодировка UTF-8, отступы 4 пробела
+- Максимальная длина строки: 88 символов (
+uff format / lack)
+- Именование: переменные/функции — snake_case, классы — PascalCase, константы — UPPER_SNAKE_CASE
+- Аннотации типов — обязательны для аргументов и возвращаемых значений всех функций
+- Строки: двойные кавычки " для данных, одинарные ' для docstrings
+- Импорты: stdlib → third-party → local (алфавитный порядок внутри групп). Абсолютные импорты, относительные запрещены
+- Пробелы: вокруг операторов, не внутри скобок
+
+**SQL:**
+- Ключевые слова — UPPERCASE (SELECT, FROM, WHERE)
+- Имена таблиц и полей — snake_case
+- Сложные запросы разбивать на строки, выравнивать JOIN и WHERE
+
+**Оптимальный размер файла:**
+- Если файл маршрутов/контроллеров превышает 500 строк — разбить на модули
+
+**JavaScript/TypeScript (Web/PWA):**
+- Formatter: Prettier (100 символов)
+- Linter: ESLint с правилами irbnb + 
+eact
+- Типы: strict TypeScript, any запрещён
+- Импорты: абсолютные через @/ alias
+- Стили: Tailwind CSS
+- Состояние: zustand или RTK
+- Асинхронность: sync/await вместо .then()
+
+---
+
+## 2. Documentation
+
+- Docstrings: Google-формат для всех публичных классов, функций, методов
+- TODO/FIXME: с указанием причины и планируемого срока. # TODO(#TASK-N): причина
+- Предупреждения о рисках: если код затрагивает безопасность, производительность или совместимость
+- README.md: в каждой папке pp/* — краткое описание файлов внутри
+
+---
+
+## 3. Naming Conventions
+
+**Переменные окружения:**
+`
+PROJECT_NAME=VoIdea
+PROJECT_VERSION=X.Y.Z
+PROJECT_ENV=local|development|staging|production
+SERVER_HOST=X.X.X.X
+SERVER_PORT=8020
+SERVER_EXTERNAL_URL=http://X.X.X.X:8020
+DB_HOST=localhost
+DB_PORT=5432
+DB_NAME=voidea
+DB_USER=voidea
+DB_PASS=
+REDIS_HOST=localhost
+REDIS_PORT=6379
+AI_YANDEX_KEY=
+AI_GIGACHAT_KEY=
+AI_FALLBACK_MODEL=yandex_gpt
+AI_TIMEOUT=10
+OAUTH_YANDEX_ID=
+OAUTH_YANDEX_SECRET=
+OAUTH_GOOGLE_ID=
+OAUTH_GOOGLE_SECRET=
+SMTP_HOST=
+SMTP_PORT=
+SMTP_USER=
+SMTP_PASS=
+`
+
+**Индексы БД:**
+`
+ix_tablename_column
+uq_tablename_column
+fk_tablename_column
+`
+
+**Ветки Git:**
+`
+main        → стабильная, продакшен
+develop     → интеграция фич
+feature/*   → новая функция
+hotfix/*    → срочное исправление
+release/*   → подготовка релиза
+`
+
+**Миграции Alembic:**
+`
+{действие}_{таблица}
+`
+
+---
+
+## 4. Git & Versioning
+
+### 4.1 Формат
+SemVer: MAJOR.MINOR.PATCH
+
+### 4.2 CHANGELOG
+Формат: единый файл CHANGELOG.md с разделами по MINOR-версисиям
+Новый файл создаётся при смене X (major) или Y (minor):
+`
+CHANGELOG/
+├── v1.0.md   # 1.0.0 → 1.0.n (патчи добавляются в этот файл)
+├── v1.1.md   # 1.1.0 → 1.1.n (новый файл)
+└── v2.0.md   # 2.0.0 → ...
+`
+
+### 4.3 Conventional Commits
+`
+<тип>[optional scope]: <описание>
+`
+- eat: новая функция → MINOR
+- ix: исправление → PATCH
+- BREAKING: в теле коммита → MAJOR
+- docs, 
+efactor, 	est, chore: не влияют на версию
+
+### 4.4 Agent Versioning
+
+Агенты версионируются независимо от проекта по SemVer (A.B.C).
+
+**Правила бампа:**
+- **A (major)**: breaking change в публичном интерфейсе агента
+- **B (minor)**: новая capability (метод, роль, prompt)
+- **C (patch)**: внутренние правки без изменения поведения
+
+**Механика:**
+- Каждый агент после `run()` вычисляет SHA256 checksum своего файла
+- Сравнивает с `AgentConfig.checksum` в БД
+- Не совпал → авто-бамп patch, запись в `CHANGELOG/agents/<name>.md`
+- EvolutionAgent управляет minor/major бампами
+
+**Формат changelog:**
+```markdown
+CHANGELOG/agents/
+├── doc_agent.md
+├── audit_agent.md
+└── ...
+```
+
+---
+
+## 5. Code Review
+
+- Обязателен для всех PR в main и develop
+- Минимум 1 апрув от admin/owner
+- Чеклист ревью:
+  - [ ] Нет секретов в коде
+  - [ ] Нет сырых Exception в API ответах
+  - [ ] Есть тесты (или TODO с причиной)
+  - [ ] docs/blocks/*.md обновлён
+  - [ ] ADR создан при архитектурных изменениях
+
+---
+
+## 6. Definition of Done (DoD)
+
+- [ ] Код написан (соответствует стилю §1)
+- [ ] Линт проходит (
+uff check — 0 errors)
+- [ ] Тесты написаны (минимум 1 smoke)
+- [ ] Тесты проходят (pytest — green)
+- [ ] Документация блока обновлена
+- [ ] .env.example обновлён (если новая переменная)
+- [ ] Миграция написана (если менялась БД)
+
+---
+
+## 7. Architecture (SOLID + слоистая)
+
+**Слои (зависимости только внутрь):**
+`
+API → Services → Integrations → Data Layer → Core
+`
+
+**SOLID:**
+- S: каждый блок — одна доменная область
+- O: новые интеграции — новые классы
+- L: сервисы подчиняются общему интерфейсу
+- I: сервис принимает только нужные зависимости
+- D: API зависит от абстракции Service
+
+---
+
+## 8. Error Handling
+
+| Слой | Действие |
+|------|---------|
+| API | HTTPException с detail и status_code |
+| Services | Бизнес-исключения без HTTP-статусов |
+| Integrations | 	ry/except с fallback |
+| DB | Ошибки БД не всплывают выше |
+| WebUI | Flash-сообщение пользователю |
+
+---
+
+## 9. Security Base
+
+- .env — всегда в .gitignore
+- JWT: алгоритм HS256, expire = 60 минут, refresh = 30 дней
+- Пароли: bcrypt через passlib
+- Pydantic валидация на всех входах
+- RBAC: роли user, dmin, owner
+
+---
+
+## 10. Logging Standards
+
+**Формат строки лога:**
+`
+[ISO8601] [LEVEL] [component] message key=val
+2026-05-10T14:30:00.000Z INFO [auth] User logged in user_id=abc
+`
+
+**Уровни по слоям:**
+
+| Слой | DEBUG | INFO | WARNING | ERROR |
+|------|-------|------|---------|-------|
+| API | Параметры | Request | — | 5xx |
+| Service | Входные | Операция | Превышен лимит | Ошибка БД |
+| Integration | Raw ответ | Успех | Timeout | Внешний API |
+
+**Запрещено:** f-строки в logger. Только %s (lazy evaluation).
+**Разрешено:** f-строки в logging_service.log().
+
+---
+
+## 11. Sensitive Data Policy
+
+**Никогда не логировать:**
+- Пароли (даже хэш)
+- JWT токены
+- API keys и секреты
+- Email в открытом виде (логировать user_id)
+
+**Маскировать в логах:**
+- Email: u***@mail.ru
+- IP: 195.208.*.*
+
+---
+
+## 12. Third-party Call Fallback Pattern
+
+`
+1. Попытка (timeout: 10s)
+2. Успех → return data
+3. Таймаут → retry 1 (через 2s)
+4. Таймаут → retry 2 (через 5s)
+5. 4xx → WARNING, return None/fallback
+6. 5xx → ERROR, retry → если снова 5xx → return None/fallback
+7. Все retry исчерпаны → CRITICAL в SystemLog, возврат fallback
+`
+
+---
+
+## 13. Performance Budgets
+
+| Метрика | Лимит (p95) |
+|---------|-------------|
+| API response (без GPT) | < 500ms |
+| DB query (одиночный) | < 100ms |
+| DB query (агрегатный) | < 300ms |
+| GPT call | < 5s (иначе fallback) |
+| WebUI page load | < 2s |
+
+---
+
+## 14. Data Retention Policy
+
+| Данные | Срок хранения |
+|--------|---------------|
+| SystemLog | 90 дней |
+| SecurityEvent | 1 год |
+| Notification | 30 дней |
+| PaymentTransaction | 5 лет |
+| User data | До удаления + 30 дней |
+| Session (JWT) | 24 часа |
+
+---
+
+## 15. Dependency Management
+
+- **patch**: в любой момент (bugfix, security)
+- **minor**: не чаще 1 раза в спринт
+- **major**: только с полным регрессом
+
+---
+
+## 16. Async/Sync Decision Matrix
+
+| Сценарий | Механизм |
+|----------|----------|
+| GET-запросы, CRUD | sync (await) |
+| Отправка email | Celery async |
+| GPT вызовы | Celery async |
+| Бэкапы | Celery async |
+| WebSocket / SSE | Не используется |
+
+---
+
+## 17. Architecture Decision Records (ADR)
+
+Любое значимое архитектурное решение фиксируется в docs/adr/NNN-title.md.
+
+Формат:
+`markdown
+# ADR-001: Название решения
+
+Статус: принято
+Контекст: описание проблемы
+Решение: что выбрано
+Последствия: плюсы и минусы
+`
+
+---
+
+## 18. Tooling
+
+| Инструмент | Назначение |
+|------------|------------|
+| ruff | Линтер (E, F, W, I, N, UP) |
+| ruff format | Форматтер (line-length=88) |
+| mypy | Type checker |
+| pytest | Тесты (asyncio_mode=auto) |
+| pre-commit | Хуки (ruff, ruff-format, trailing-whitespace) |
+
+---
+
+## 19. AI Agents (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 | Проверяет инклюзивность |
+
+**Промпты хранятся в:** docs/agent_prompts.yaml (TDC)
+
+---
+
+## 20. System Agents (11 агентов)
+
+| Агент | Назначение |
+|-------|-----------|
+| DocAgent | Документация, комментарии, Runbook |
+| AuditAgent | Соблюдение правил, прогресс проекта |
+| SecurityAgent | Безопасность, уязвимости, 152-ФЗ |
+| SpecAgent | Спецификации, версионирование **проекта**, CHANGELOG |
+| ObserverAgent | Наблюдение за пользователями, генерация идей |
+| QATesterAgent | Функциональное тестирование, временные аккаунты |
+| FixAgent | Исправление багов, анализ логов |
+| UITestAgent | Визуальное тестирование |
+| RolloutAgent | Постепенное развёртывание (3→1%→5%→15%→100%) |
+| EvolutionAgent | Саморазвитие и **версионирование агентов** |
+| BacklogAgent | Управление отложенными задачами |
+
+**Триггеры запуска:**
+- Автоматически: pre-commit, push, daily cron
+- Вручную: кнопка в админ-панели
+
+---
+
+## 21. Design System
+
+Единый источник истины: docs/design-system/tokens.json
+
+| Файл | Назначение |
+|------|------------|
+| tokens.json | Единый источник (JSON) |
+| tokens.yaml | YAML версия для документации |
+| generators/*.py | Генераторы для платформ (CSS, Swift, Kotlin) |
+
+**Темы:** system (auto), dark, light
+**Форматы:** CSS Variables, Swift, Kotlin XML
+
+---
+
+## 22. Testing Standards
+
+- Модульные тесты — в 	ests/unit/
+- Интеграционные тесты — в 	ests/integration/
+- E2E сценарии — в docs/specs/e2e/
+- Минимум: 1 smoke-тест на endpoint
+- Фикстуры: conftest.py в корне 	ests/
+
+---
+
+## 23. Migration Policy
+
+- Alembic, async, одна миграция на одно изменение
+- Обратно совместимы (без breaking changes)
+- Название: {revision}_{action}_{table}.py
+
+---
+
+## 24. API Version Lifecycle
+
+`
+Текущая:  /api/v1/* — стабильная
+Deprecation: 3 месяца после выхода новой версии
+Отключение: 410 Gone
+`
+
+---
+
+## 25. Module Public API Convention
+
+__init__.py содержит ТОЛЬКО публичный API модуля:
+`python
+from app.models.user import User
+__all__ = ["User", ...]
+`
+
+---
+
+## 26. Project Glossary
+
+Глоссарий: docs/blocks/GLOSSARY.md
+
+| Термин | Значение |
+|--------|----------|
+| Idea | Основная сущность проекта (записанная пользователем) |
+| Agent | ИИ-агент для анализа идей (11 ролей) |
+| System Agent | Автоматический агент для поддержки проекта (11 штук) |
+| Backlog | Система отложенных задач/идей |
+| Rollout | Постепенное развёртывание |
+| Design Tokens | Единый источник стилей |
+
+---
+
+## 27. OAuth & Auth
+
+**Провайдеры:**
+- Email + пароль (классика)
+- Яндекс OAuth
+- Google OAuth
+- Apple OAuth (отложено)
+
+**Схема:** Один пользователь = один провайдер (нельзя привязать Google если уже есть Яндекс)
+
+---
+
+## 28. Car Integration (Roadmap)
+
+ГУ автомобиля — изучить и добавить в будущем:
+- Android Auto / Apple CarPlay
+- Bluetooth HID
+- Подключение кнопок руля
+