voidea/template/AI_CONTEXT.md

Полная спецификация проекта для ИИ-ассистента

Этот файл — единственный источник истины для ИИ, работающего с проектом. Прочитай его полностью перед началом любой работы. Если какой-то аспект не описан — спроси.

---

1. РОЛИ

• Ты — ИИ-ассистент. Твоя задача: писать код, соответствующий правилам проекта.
• Пользователь — владелец проекта. Он принимает все стратегические решения.
• Агенты — автоматические участники. Они следят за качеством, версиями и эволюцией.

---

2. СТРУКТУРА ПРОЕКТА (MUST FOLLOW)

project/
├── app/                    # Backend (Python FastAPI)
│   ├── __init__.py
│   ├── main.py             # FastAPI app, lifespan, middleware
│   ├── api/
│   │   └── v1/             # Версионированные роуты
│   │       ├── __init__.py  # api_v1_router = APIRouter(prefix="/api/v1")
│   │       ├── auth.py      # POST /login, /register, /refresh, /oauth
│   │       ├── users.py     # GET/PATCH /me
│   │       ├── ideas.py     # CRUD /ideas + POST /analyze
│   │       ├── agents.py    # GET /agents + POST /run
│   │       ├── sync.py      # POST /sync/pull, /sync/push
│   │       └── admin.py     # GET /users, /health, /logs
│   ├── core/
│   │   ├── __init__.py
│   │   ├── config.py       # Pydantic Settings из .env
│   │   ├── base.py         # SQLBase, CoreModel, UUIDMixin, TimestampMixin
│   │   ├── database.py     # Engine + async_session_maker + get_db
│   │   ├── security.py     # JWT create/decode, password hash
│   │   ├── exceptions.py   # HTTPException подклассы
│   │   ├── dependencies.py # get_db, get_current_user, require_admin
│   │   └── metrics.py      # Middleware для сбора метрик
│   ├── models/             # SQLAlchemy модели
│   ├── schemas/            # Pydantic схемы (Request/Response)
│   ├── services/           # Бизнес-логика
│   ├── integrations/       # AI провайдеры, внешние API
│   ├── tasks/              # Celery задачи (или прямой вызов)
│   └── agents/             # Системные агенты
├── webui/                  # Frontend (React + Vite + Tailwind)
│   ├── src/
│   │   ├── main.tsx
│   │   ├── App.tsx         # BrowserRouter + Routes
│   │   ├── index.css       # Tailwind directives
│   │   ├── api/            # HTTP-клиент, типы запросов
│   │   ├── auth/           # AuthContext, login/register
│   │   ├── components/     # Layout, ProtectedRoute
│   │   └── pages/          # Dashboard, IdeaView, Admin
│   └── vite.config.ts      # Vite + React + PWA proxy
├── tests/                  # pytest тесты
├── docs/                   # Документация
├── CHANGELOG/              # Версионирование
├── migrations/             # Alembic миграции
├── .env.example
└── project.yaml

3. ПРАВИЛА КОДИРОВАНИЯ (MUST FOLLOW)

3.1 Python

• Версия: Python 3.12+
• Типизация: from __future__ import annotations во всех файлах, X | None вместо Optional[X]
• Строки: двойные кавычки " для строковых литералов, одинарные ' для docstrings
• Длина строки: 88 символов (ruff format)
• Импорты: абсолютные, порядок: stdlib → third-party → local (алфавитный внутри групп)
• Docstrings: Google-style для всех публичных классов/функций/методов
• Именование: классы PascalCase, функции/переменные snake_case, константы UPPER_SNAKE
• Линтер: ruff (E, F, W, I, N, UP)
• Форматтер: ruff format

3.2 SQL

• Ключевые слова: UPPERCASE (SELECT, FROM, WHERE)
• Таблицы/поля: snake_case
• Индексы: ix_tablename_column
• Уникальность: uq_tablename_column

3.3 TypeScript/React

• Форматтер: Prettier (100 символов)
• Типы: strict TypeScript, any запрещён
• Импорты: абсолютные через @/ alias
• Стили: Tailwind CSS, никаких CSS-in-JS
• Асинхронность: async/await, .then() запрещён
• Состояние: zustand или React Context

4. АРХИТЕКТУРА (MUST FOLLOW)

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

API → Services → Integrations → Data → Core

• API не знает про БД. Не создаёт сессий. Только Depends(get_db).
• Services не знают про HTTP. Не импортируют FastAPI/fastapi. Работают с БД через сессию.
• Integrations не знают про бизнес-логику. Оборачивают внешние API.
• Data (models) — SQLAlchemy модели и репозитории.
• Core — конфиг, базовые классы, утилиты, безопасность.

4.2 Сервисы

Сервис — это класс, который принимает db: AsyncSession в конструкторе:

class IdeaService:
    def __init__(self, db: AsyncSession):
        self.db = db

    async def get_by_id(self, idea_id: str) -> Idea | None:
        result = await self.db.execute(select(Idea).where(Idea.id == idea_id))
        return result.scalar_one_or_none()

4.3 API

API-роуты — это функции, которые:

1. Принимают Depends(get_db) и Depends(get_current_user)
2. Создают сервис с сессией
3. Вызывают метод сервиса
4. Возвращают Pydantic response

@router.get("/{idea_id}", response_model=IdeaResponse)
async def get_idea(
    idea_id: str,
    user: Annotated[User, Depends(get_current_user)],
    db: AsyncSession = Depends(get_db),
):
    service = IdeaService(db)
    idea = await service.get_by_id(idea_id)
    if not idea or str(idea.user_id) != str(user.id):
        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)
    return _to_response(idea)

4.4 Зависимости (dependencies.py)

• get_db() — yield async_session_maker(), commit/rollback/close
• get_current_user(credentials, db) — decode JWT → find user in DB
• require_admin(user) — check is_superuser

ВАЖНО: get_current_user принимает db = Depends(get_db), а не создаёт свою сессию.

4.5 Config

class Settings(BaseSettings):
    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
    
    server_host: str = "0.0.0.0"
    server_port: int = 8020
    database_url: str = "sqlite+aiosqlite:///./app.db"
    jwt_secret_key: str = ""
    log_level: str = "INFO"
    
    @property
    def is_sqlite(self) -> bool:
        return "sqlite" in self.database_url

5. БАЗА ДАННЫХ

5.1 Поддержка SQLite и PostgreSQL

Для портабельности между SQLite (dev) и PostgreSQL (prod) используем:

• UUID поля: String(36) во всех моделях (храним UUID как строку)
• JSON/Array: JSON вместо JSONB и ARRAY
• Автовыбор: через settings.database_url и settings.is_sqlite

5.2 Модели

class UUIDMixin:
    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=lambda: str(uuid4()))

class TimestampMixin:
    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now())

6. AI-ИНТЕГРАЦИЯ

6.1 Паттерн FallbackChain

class AIProvider(ABC):
    async def analyze(self, prompt: str, **kwargs) -> AIResult: ...

class FallbackChain:
    def __init__(self, providers: list[AIProvider], max_retries: int = 2):
        ...
    async def analyze(self, prompt: str, **kwargs) -> AIResult:
        # Try each provider in order, max_retries per provider
        # 1st retry after 2s, 2nd after 5s
        # All fail → AIResult(success=False, error="All providers failed")

6.2 Где хранить промпты

• YAML-файл (docs/agent_prompts.yaml) для настроек (system_prompt, temperature, max_tokens, provider)
• MD-файлы (docs/specs/agents/) для детальных спецификаций
• Загрузка через PromptLoader (пытается YAML → falls back к MD)

7. АГЕНТЫ (IF APPLICABLE)

7.1 Ядро (4 агента, с первого коммита)

1. DocAgent — пишет документацию
2. AuditAgent — проверяет правила
3. EvolutionAgent — версионирует агентов
4. SupervisorAgent — следит за всеми агентами

7.2 Архитектура агента

class BaseAgent(ABC):
    name: str
    version: str = "1.0.0"
    description: str = ""
    triggers: list[AgentTrigger]

    async def run(self, context: dict | None = None) -> AgentResult: ...
    async def health_check(self) -> bool: ...
    def compute_checksum(self) -> str: ...  # SHA256 от __file__
    def bump_version(self, version_type: str = "patch") -> str: ...

7.3 Agent Versioning

• Каждый агент: независимое A.B.C
• SHA256 checksum файла агента сравнивается с хранимым
• Не совпал → авто-бамп patch + запись в CHANGELOG/agents/<name>.md
• EvolutionAgent бампает minor (новая capability) и major (breaking change)
• Формат changelog:

# agent_name Changelog
<!-- checksum: sha256hash -->

## 1.0.1 (2026-05-10)
- Fixed: описание

## 1.0.0 (2026-05-09)
- Initial version

8. ФОНОВЫЕ ЗАДАЧИ

8.1 Celery (production) / Прямой вызов (dev)

# tasks/analysis.py
@celery_app.task(bind=True, max_retries=2, name="analyze_idea")
def analyze_idea(self, idea_id: str, role: str) -> dict:
    return asyncio.run(_analyze_idea_async(idea_id, role))

# services/analysis_service.py  
class AnalysisService:
    async def start_analysis(self, idea_id: str) -> dict:
        if settings.celery_broker_url:
            task = analyze_idea.delay(idea_id, role)
        else:
            task = await _analyze_local(idea_id, role)
        ...

9. ТЕСТИРОВАНИЕ

• Фреймворк: pytest с asyncio_mode=auto
• Unit-тесты: tests/unit/ — изолированные, mocked зависимости
• Integration-тесты: tests/integration/ — с БД, реальные запросы
• Smoke-тесты: tests/smoke/ — минимум 1 на endpoint
• Покрытие: > 80% (критический код: auth, security, payments — 100%)

10. БЕЗОПАСНОСТЬ

• JWT: HS256, access_token 60min, refresh_token 30d
• Пароли: bcrypt (passlib)
• .env в .gitignore — всегда
• Pydantic валидация на всех входах
• RBAC: user, admin (is_superuser)

11. РЕШЕНИЯ (SHOULD ASK)

Перед каждым из этих выборов — остановись и спроси пользователя:

Решение	Опции по умолчанию
База данных	SQLite (dev) → PostgreSQL (prod)
Фоновые задачи	Прямой вызов (dev) → Celery (prod)
AI провайдеры	FallbackChain с 2 провайдерами
Аутентификация	Email+password + JWT
Агенты	4 ядерных + остальные по необходимости
Фронтенд	React + Vite + Tailwind + PWA
CI/CD	GitHub Actions

12. ЧТО ДЕЛАТЬ ЕСЛИ НЕ ЗНАЕШЬ

1. Поищи в docs/ — там описано 90% ситуаций
2. Если не нашёл — открой notes/encountered-issues.md — может это уже было
3. Если и там нет — посмотри на notes/improvements.md — может это запланированное улучшение
4. Если ничего не помогло — спроси пользователя с рекомендацией

---

Этот файл сгенерирован на основе реального опыта. Обновляется при изменении проекта.