468 lines
16 KiB
Markdown
468 lines
16 KiB
Markdown
# 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*
|
||
*Обновлён системными агентами автоматически*
|