# 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
- Подключение кнопок руля

---

*Документ создан: 2026-05-10*
*Обновлён системными агентами автоматически*