voidea/template/docs/00-rules.md

Rules & Conventions

Конституция проекта. Применяется ко всем компонентам. Если в специфичном компоненте нет явного описания ситуации — решение принимается по этим правилам. Если сомневаешься — спроси.

---

1. Code Style Standards

Python (PEP8 + ruff):

• Кодировка UTF-8, отступы 4 пробела
• Максимальная длина строки: 88 символов (ruff format)
• Именование: переменные/функции — snake_case, классы — PascalCase, константы — UPPER_SNAKE_CASE
• Аннотации типов — обязательны для аргументов и возвращаемых значений всех функций
• Строки: двойные кавычки " для данных, одинарные ' для docstrings
• Импорты: stdlib → third-party → local (алфавитный порядок внутри групп). Абсолютные импорты, относительные запрещены
• Типизация: from __future__ import annotations во всех файлах, X | None вместо Optional[X]
• Пробелы: вокруг операторов, не внутри скобок

SQL:

• Ключевые слова — UPPERCASE (SELECT, FROM, WHERE)
• Имена таблиц и полей — snake_case
• Сложные запросы разбивать на строки, выравнивать JOIN и WHERE

Оптимальный размер файла:

• Маршруты/контроллеры: не более 500 строк → разбить на модули
• Модели: не более 200 строк
• Сервисы: не более 300 строк

TypeScript/React:

• Formatter: Prettier (100 символов)
• Типы: strict TypeScript, any запрещён
• Импорты: абсолютные через @/ alias
• Стили: Tailwind CSS
• Состояние: Zustand (новые сториджи) или Context API (legacy)
• Формы: react-hook-form + zod (сложные), нативный form (простые)
• Асинхронность: async/await
• Доступность: WCAG AA (eslint-plugin-jsx-a11y enforcement)
• i18n-ready: строки через constants/strings.ts, рендер через

ESLint (React/TypeScript):

• Плагины: @eslint/js + typescript-eslint + eslint-plugin-jsx-a11y
• Парсер: @typescript-eslint/parser (flat config)
• Ключевые правила:
  • @typescript-eslint/no-explicit-any: error
  • @typescript-eslint/strict-boolean-expressions: error
  • @typescript-eslint/no-unused-vars: error (кроме _)
  • jsx-a11y/alt-text: error
  • jsx-a11y/aria-props: error
  • jsx-a11y/aria-role: error
  • jsx-a11y/label-has-associated-control: error
  • jsx-a11y/click-events-have-key-events: error
  • no-console: error (кроме warn, error)
  • prefer-const: error
  • no-var: error
• Установка: npm install -D eslint @eslint/js typescript-eslint eslint-plugin-jsx-a11y
• Запуск: npx eslint src/ (в CI после npm install)

Testing (Vitest):

• Фреймворк: Vitest + @testing-library/react
• Имена файлов: *.test.ts / *.test.tsx рядом с модулем
• Smoke: каждая страница рендерится без падения
• Store: каждый action тестируется
• JSON-репортёр: vitest run --reporter=json (для QATesterAgent)
• Установка: npm install -D vitest @testing-library/react @testing-library/jest-dom jsdom
• Запуск: npx vitest run (в CI после npm ci)

---

2. Documentation

• Docstrings: Google-style для всех публичных классов, функций, методов
• TODO/FIXME: с указанием причины. # TODO(#TASK): причина
• Предупреждения о рисках: если код затрагивает безопасность, производительность или совместимость
• README.md: в каждой папке с кодом — краткое описание

---

3. Naming Conventions

Переменные окружения:

PROJECT_NAME=
PROJECT_VERSION=X.Y.Z
PROJECT_ENV=local|development|staging|production
SERVER_HOST=X.X.X.X
SERVER_PORT=8020
DATABASE_URL=...
JWT_SECRET_KEY=

Индексы БД:

ix_tablename_column
uq_tablename_column
fk_tablename_column

Ветки Git:

main        → стабильная, продакшен
develop     → интеграция фич
feature/*   → новая функция
hotfix/*    → срочное исправление
release/*   → подготовка релиза

Миграции БД:

{action}_{table}

---

4. Git & Versioning

4.1 Формат

SemVer: MAJOR.MINOR.PATCH

4.2 CHANGELOG

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]: <описание>

feat:      → новая функция → MINOR
fix:       → исправление → PATCH
BREAKING:  → несовместимость → MAJOR
docs:      → документация
refactor:  → рефакторинг
test:      → тесты
chore:     → обслуживание

4.4 Agent Versioning (если используются агенты)

Агенты версионируются независимо по A.B.C.

• A (major): breaking change в публичном интерфейсе
• B (minor): новая capability
• C (patch): внутренние правки, авто-бамп по checksum

Changelog агентов: CHANGELOG/agents/<name>.md

---

5. Code Review

• Обязателен для всех PR в main и develop
• Минимум 1 апрув от admin/owner
• [ASK]: кто апрувит в текущем проекте?

Чеклист ревью:

• Нет секретов в коде
• Нет сырых Exception в API ответах
• Есть тесты (или TODO с причиной)
• Документация обновлена
• ADR создан при архитектурных изменениях
• CHANGELOG обновлён

---

6. Definition of Done (DoD)

• Код написан (соответствует стилю §1)
• Линт проходит (ruff — 0 errors)
• Тесты написаны (минимум 1 smoke)
• Тесты проходят (pytest — green)
• Документация обновлена
• .env.example обновлён (если новая переменная)
• Миграция написана (если менялась БД)
• CHANGELOG обновлён

---

7. Architecture (SOLID + слоистая)

Слои (зависимости только внутрь):

API → Services → Integrations → Data → Core

SOLID:

• S: каждый модуль — одна доменная область
• O: новые интеграции — новые классы
• L: сервисы подчиняются общему интерфейсу
• I: сервис принимает только нужные зависимости
• D: API зависит от абстракции Service

---

8. Error Handling

Слой	Действие
API	HTTPException с detail и status_code
Services	Бизнес-исключения без HTTP-статусов
Integrations	try/except с fallback
DB	Ошибки БД не всплывают выше

---

9. Security Base

• .env — всегда в .gitignore
• JWT: алгоритм HS256, expire = 60 минут, refresh = 30 дней
• Пароли: bcrypt через passlib
• Pydantic валидация на всех входах
• RBAC: роли user, admin

---

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).

---

11. Sensitive Data Policy

Никогда не логировать:

• Пароли (даже хэш)
• JWT токены
• API keys и секреты
• Email в открытом виде

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

• 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 исчерпаны → return fallback результат

---

13. Performance Budgets (примерные)

Метрика	Лимит (p95)
API response	< 500ms
DB query (одиночный)	< 100ms
DB query (агрегатный)	< 300ms
AI call	< 5s (иначе fallback)
WebUI page load	< 2s

---

14. Data Retention Policy (примерная)

Данные	Срок хранения
SystemLog	90 дней
SecurityEvent	1 год
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	async (Celery или прямой)
AI вызовы	async (Celery или прямой)
Бэкапы	async (Celery)

---

17. ADR (Architecture Decision Records)

Любое значимое архитектурное решение фиксируется в docs/adr/NNN-title.md.

Формат:

# ADR-NNN: Название решения

Статус: принято
Контекст: описание проблемы
Решение: что выбрано
Последствия: плюсы и минусы

---

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. API Version Lifecycle

Текущая:  /api/v1/* — стабильная
Deprecation: 3 месяца после выхода новой версии
Отключение: 410 Gone

---

20. Module Public API Convention

__init__.py содержит ТОЛЬКО публичный API модуля:

from app.models.user import User
__all__ = ["User"]

---

Документ создан на основе шаблона. Адаптируйте под конкретный проект.