# 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, рендер через <T>

**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`.

Формат:
```markdown
# 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 модуля:
```python
from app.models.user import User
__all__ = ["User"]
```

---

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