358 lines
12 KiB
Markdown
358 lines
12 KiB
Markdown
# 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"]
|
||
```
|
||
|
||
---
|
||
|
||
*Документ создан на основе шаблона. Адаптируйте под конкретный проект.*
|