angel/voidea
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
688d043dad82ade759c0f4480eaa186c5f1b13f0
voidea/old/00-rules.md
T

16 KiB
Raw Blame History

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:

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)

Маскировать в логах:

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 Обновлён системными агентами автоматически

Reference in New Issue View Git Blame Copy Permalink