Initial commit: VoIdeaAI - voice-first AI idea assistant

template/docs/00-rules.md

@@ -0,0 +1,357 @@
+# 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"]
+```
+
+---
+
+*Документ создан на основе шаблона. Адаптируйте под конкретный проект.*