@dewtech/dare-cli 3.3.0 → 3.5.0

package/templates/ide/cursor/.cursor/rules/skill-fastapi-api.mdc

@@ -1,352 +1,352 @@
----
-description: Padrões DARE para APIs REST em Python + FastAPI + Pydantic v2 + SQLAlchemy 2.0 async + alembic. Routers, dependency injection, schemas Pydantic, OAuth2+JWT, slowapi rate limit, pytest+httpx, OpenAPI auto-gerado.
-globs: **/*.py,pyproject.toml,requirements.txt,alembic.ini,alembic/**/*.py
-alwaysApply: false
----
-
-# Skill: FastAPI API DARE
-
-Você é um desenvolvedor sênior Python especialista em APIs REST com FastAPI. Esta skill garante código **assíncrono, fortemente tipado (Pydantic v2), com OpenAPI auto-gerado, auth/autz robustos**, seguindo Layered Design DARE.
-
-## Stack canônica
-
-- **Python 3.11+** com type hints obrigatórios
-- **FastAPI 0.115+** com async/await
-- **Pydantic v2** para schemas
-- **SQLAlchemy 2.0** async + **asyncpg** (PostgreSQL)
-- **alembic** para migrations
-- **passlib + argon2** para hash de senhas
-- **python-jose** ou **PyJWT** para JWT
-- **slowapi** para rate limiting
-- **pytest + pytest-asyncio + httpx**
-- **ruff** (lint + format) + **mypy**
-
----
-
-## Estrutura de pastas
-
-```
-app/
-├── main.py                       ← FastAPI app + middlewares
-├── core/
-│   ├── config.py                 ← pydantic-settings
-│   └── security.py               ← hash, JWT
-├── api/
-│   ├── deps.py                   ← Depends() comuns
-│   └── v1/
-│       ├── users.py              ← Handler (router)
-│       └── auth.py
-├── services/                     ← Service layer
-├── repositories/                 ← Repository layer
-├── models/                       ← SQLAlchemy ORM
-├── schemas/                      ← Pydantic DTOs
-└── tests/
-```
-
----
-
-## Routers (Handler)
-
-```python
-from fastapi import APIRouter, Depends, HTTPException, status
-from app.api.deps import get_current_user
-from app.schemas.user import UserCreate, UserOut
-from app.services.register_user import RegisterUser, UserAlreadyExistsError
-
-router = APIRouter(prefix="/users", tags=["users"])
-
-@router.post("", response_model=UserOut, status_code=status.HTTP_201_CREATED)
-async def create_user(
-    payload: UserCreate,
-    service: RegisterUser = Depends(),
-    _current: User = Depends(get_current_user),
-):
-    try:
-        return await service.execute(payload)
-    except UserAlreadyExistsError:
-        raise HTTPException(status_code=409, detail="User already exists")
-```
-
-Regras:
-- Apenas: valida via Pydantic → chama Service → retorna response_model
-- NUNCA: SQLAlchemy direto, lógica de negócio, validação manual
-
----
-
-## Schemas (Pydantic v2)
-
-```python
-from pydantic import BaseModel, EmailStr, Field
-from datetime import datetime
-
-class UserCreate(BaseModel):
-    email: EmailStr
-    name: str = Field(min_length=1, max_length=255)
-    password: str = Field(min_length=12)
-
-class UserOut(BaseModel):
-    id: int
-    email: EmailStr
-    name: str
-    created_at: datetime
-
-    model_config = {"from_attributes": True}   # Pydantic v2 substitui orm_mode
-```
-
----
-
-## Services
-
-```python
-class UserAlreadyExistsError(Exception): ...
-
-class RegisterUser:
-    def __init__(self, repo: UsersRepository = Depends()):
-        self.repo = repo
-
-    async def execute(self, payload: UserCreate) -> User:
-        if await self.repo.exists_by_email(payload.email):
-            raise UserAlreadyExistsError()
-        return await self.repo.create(
-            email=payload.email,
-            name=payload.name,
-            password_hash=hash_password(payload.password),
-        )
-```
-
----
-
-## Repositories (SQLAlchemy 2.0 async)
-
-```python
-from sqlalchemy import select
-from sqlalchemy.ext.asyncio import AsyncSession
-from fastapi import Depends
-from app.api.deps import get_db
-
-class UsersRepository:
-    def __init__(self, db: AsyncSession = Depends(get_db)):
-        self.db = db
-
-    async def exists_by_email(self, email: str) -> bool:
-        result = await self.db.execute(select(User.id).where(User.email == email))
-        return result.scalar_one_or_none() is not None
-
-    async def create(self, *, email: str, name: str, password_hash: str) -> User:
-        user = User(email=email, name=name, password_hash=password_hash)
-        self.db.add(user)
-        await self.db.commit()
-        await self.db.refresh(user)
-        return user
-```
-
----
-
-## Models (SQLAlchemy 2.0)
-
-```python
-from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
-from datetime import datetime
-
-class Base(DeclarativeBase): ...
-
-class User(Base):
-    __tablename__ = "users"
-    id: Mapped[int] = mapped_column(primary_key=True)
-    email: Mapped[str] = mapped_column(unique=True, index=True)
-    name: Mapped[str]
-    password_hash: Mapped[str]
-    created_at: Mapped[datetime] = mapped_column(default=datetime.utcnow)
-```
-
----
-
-## Auth (OAuth2 + JWT)
-
-```python
-# app/core/security.py
-from passlib.hash import argon2
-from datetime import datetime, timedelta
-from jose import jwt
-from app.core.config import settings
-
-def hash_password(p: str) -> str: return argon2.hash(p)
-def verify_password(p: str, h: str) -> bool: return argon2.verify(p, h)
-
-def create_access_token(sub: str) -> str:
-    expire = datetime.utcnow() + timedelta(minutes=15)
-    return jwt.encode({"sub": sub, "exp": expire}, settings.JWT_SECRET, algorithm="HS256")
-```
-
-```python
-# app/api/deps.py
-from fastapi.security import OAuth2PasswordBearer
-
-oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/v1/auth/login")
-
-async def get_current_user(token: str = Depends(oauth2_scheme)) -> User:
-    try:
-        payload = jwt.decode(token, settings.JWT_SECRET, algorithms=["HS256"])
-    except JWTError:
-        raise HTTPException(status_code=401, detail="Invalid token")
-    ...
-```
-
----
-
-## Rate limiting (slowapi)
-
-```python
-from slowapi import Limiter
-from slowapi.util import get_remote_address
-
-limiter = Limiter(key_func=get_remote_address)
-app.state.limiter = limiter
-app.add_middleware(SlowAPIMiddleware)
-
-@router.post("/login")
-@limiter.limit("5/15minute")
-async def login(request: Request, ...):
-    ...
-```
-
----
-
-## OpenAPI
-
-FastAPI auto-gera em `/openapi.json`. Customize:
-
-```python
-app = FastAPI(
-    title="Projeto API",
-    version="1.0",
-    openapi_url="/openapi.json",
-    docs_url="/docs",
-    redoc_url="/redoc",
-)
-```
-
----
-
-## Settings (pydantic-settings)
-
-```python
-from pydantic_settings import BaseSettings, SettingsConfigDict
-
-class Settings(BaseSettings):
-    DATABASE_URL: str
-    JWT_SECRET: str
-    JWT_EXPIRE_MINUTES: int = 15
-    model_config = SettingsConfigDict(env_file=".env")
-
-settings = Settings()
-```
-
----
-
-## Testes (pytest + httpx)
-
-```python
-import pytest
-from httpx import AsyncClient
-
-@pytest.mark.asyncio
-async def test_create_user(client: AsyncClient, admin_token: str):
-    response = await client.post(
-        "/v1/users",
-        json={"email": "jane@example.com", "name": "Jane", "password": "longsecret123"},
-        headers={"Authorization": f"Bearer {admin_token}"},
-    )
-    assert response.status_code == 201
-    assert response.json()["email"] == "jane@example.com"
-
-@pytest.mark.asyncio
-async def test_duplicate_email(client, admin_token):
-    await client.post("/v1/users", json={...}, headers={...})
-    response = await client.post("/v1/users", json={...}, headers={...})
-    assert response.status_code == 409
-```
-
----
-
-## Antipatterns
-
-| AP | Antipattern | Correção |
-|---|---|---|
-| AP-01 | SQLAlchemy direto no router | Repository injetado via Depends |
-| AP-02 | Validação manual no router | Pydantic schema |
-| AP-03 | Lógica no router | Service |
-| AP-04 | `return user` (ORM) sem response_model | `response_model=UserOut` |
-| AP-05 | Secret hardcoded | pydantic-settings + .env |
-| AP-06 | Login sem rate limit | `@limiter.limit("5/15minute")` |
-| AP-07 | Senha em response | response_model sem password |
-| AP-08 | Sem `from_attributes=True` | adicionar no model_config |
-| AP-09 | `db.execute` sem await | sempre `await db.execute(...)` |
-| AP-10 | Mistura sync/async no router | tudo `async def` |
-
----
-
-## Segurança
-
-- Senhas: `argon2.hash()` (passlib)
-- JWT: HS256 com `JWT_SECRET ≥ 32 bytes`, ou RS256 com par de chaves
-- Headers: middleware com HSTS, X-Frame-Options, CSP
-- CORS específico, nunca `*`
-- Rate limit em login + APIs públicas
-- Refresh token com rotação no DB
-
----
-
-## CI
-
-```bash
-ruff check .
-ruff format --check .
-mypy app
-pytest --cov=app --cov-fail-under=80
-pip-audit
-alembic upgrade head --sql > /dev/null
-```
-
----
-
-## Aplicação por fase DARE
-
-### Design
-- Endpoints REST com tags
-- Schemas Pydantic de input/output
-- Auth strategy
-
-### Blueprint
-- Estrutura de pastas
-- SQLAlchemy models preliminares
-- Roteamento `app.include_router(...)`
-
-### Tasks
-- Por feature: 4 tasks (Model, Schema, Repository, Service, Router)
-- Task de configuração slowapi + auth + OpenAPI custom
-
-### Execute
-- Ralph Loop:
-  ```bash
-  ruff check . && mypy app && pytest && pip-audit
-  ```
-
----
-
-## Checklist final
-
-- [ ] Python 3.11+, ruff configurado
-- [ ] Pydantic v2 com `model_config = {"from_attributes": True}` quando ORM
-- [ ] SQLAlchemy 2.0 async com `Mapped[...]`
-- [ ] Todos routers usam `response_model=`
-- [ ] Services injetáveis via `Depends()`
-- [ ] Repositories encapsulam SQLAlchemy
-- [ ] `slowapi` em login + APIs públicas
-- [ ] Settings via pydantic-settings + .env
-- [ ] `mypy --strict` passa
-- [ ] Cobertura ≥ 80%
-
----
-
-Skill licenciada MIT — parte do DARE Method v3.
+---
+description: Padrões DARE para APIs REST em Python + FastAPI + Pydantic v2 + SQLAlchemy 2.0 async + alembic. Routers, dependency injection, schemas Pydantic, OAuth2+JWT, slowapi rate limit, pytest+httpx, OpenAPI auto-gerado.
+globs: **/*.py,pyproject.toml,requirements.txt,alembic.ini,alembic/**/*.py
+alwaysApply: false
+---
+
+# Skill: FastAPI API DARE
+
+Você é um desenvolvedor sênior Python especialista em APIs REST com FastAPI. Esta skill garante código **assíncrono, fortemente tipado (Pydantic v2), com OpenAPI auto-gerado, auth/autz robustos**, seguindo Layered Design DARE.
+
+## Stack canônica
+
+- **Python 3.11+** com type hints obrigatórios
+- **FastAPI 0.115+** com async/await
+- **Pydantic v2** para schemas
+- **SQLAlchemy 2.0** async + **asyncpg** (PostgreSQL)
+- **alembic** para migrations
+- **passlib + argon2** para hash de senhas
+- **python-jose** ou **PyJWT** para JWT
+- **slowapi** para rate limiting
+- **pytest + pytest-asyncio + httpx**
+- **ruff** (lint + format) + **mypy**
+
+---
+
+## Estrutura de pastas
+
+```
+app/
+├── main.py                       ← FastAPI app + middlewares
+├── core/
+│   ├── config.py                 ← pydantic-settings
+│   └── security.py               ← hash, JWT
+├── api/
+│   ├── deps.py                   ← Depends() comuns
+│   └── v1/
+│       ├── users.py              ← Handler (router)
+│       └── auth.py
+├── services/                     ← Service layer
+├── repositories/                 ← Repository layer
+├── models/                       ← SQLAlchemy ORM
+├── schemas/                      ← Pydantic DTOs
+└── tests/
+```
+
+---
+
+## Routers (Handler)
+
+```python
+from fastapi import APIRouter, Depends, HTTPException, status
+from app.api.deps import get_current_user
+from app.schemas.user import UserCreate, UserOut
+from app.services.register_user import RegisterUser, UserAlreadyExistsError
+
+router = APIRouter(prefix="/users", tags=["users"])
+
+@router.post("", response_model=UserOut, status_code=status.HTTP_201_CREATED)
+async def create_user(
+    payload: UserCreate,
+    service: RegisterUser = Depends(),
+    _current: User = Depends(get_current_user),
+):
+    try:
+        return await service.execute(payload)
+    except UserAlreadyExistsError:
+        raise HTTPException(status_code=409, detail="User already exists")
+```
+
+Regras:
+- Apenas: valida via Pydantic → chama Service → retorna response_model
+- NUNCA: SQLAlchemy direto, lógica de negócio, validação manual
+
+---
+
+## Schemas (Pydantic v2)
+
+```python
+from pydantic import BaseModel, EmailStr, Field
+from datetime import datetime
+
+class UserCreate(BaseModel):
+    email: EmailStr
+    name: str = Field(min_length=1, max_length=255)
+    password: str = Field(min_length=12)
+
+class UserOut(BaseModel):
+    id: int
+    email: EmailStr
+    name: str
+    created_at: datetime
+
+    model_config = {"from_attributes": True}   # Pydantic v2 substitui orm_mode
+```
+
+---
+
+## Services
+
+```python
+class UserAlreadyExistsError(Exception): ...
+
+class RegisterUser:
+    def __init__(self, repo: UsersRepository = Depends()):
+        self.repo = repo
+
+    async def execute(self, payload: UserCreate) -> User:
+        if await self.repo.exists_by_email(payload.email):
+            raise UserAlreadyExistsError()
+        return await self.repo.create(
+            email=payload.email,
+            name=payload.name,
+            password_hash=hash_password(payload.password),
+        )
+```
+
+---
+
+## Repositories (SQLAlchemy 2.0 async)
+
+```python
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from fastapi import Depends
+from app.api.deps import get_db
+
+class UsersRepository:
+    def __init__(self, db: AsyncSession = Depends(get_db)):
+        self.db = db
+
+    async def exists_by_email(self, email: str) -> bool:
+        result = await self.db.execute(select(User.id).where(User.email == email))
+        return result.scalar_one_or_none() is not None
+
+    async def create(self, *, email: str, name: str, password_hash: str) -> User:
+        user = User(email=email, name=name, password_hash=password_hash)
+        self.db.add(user)
+        await self.db.commit()
+        await self.db.refresh(user)
+        return user
+```
+
+---
+
+## Models (SQLAlchemy 2.0)
+
+```python
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+from datetime import datetime
+
+class Base(DeclarativeBase): ...
+
+class User(Base):
+    __tablename__ = "users"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    email: Mapped[str] = mapped_column(unique=True, index=True)
+    name: Mapped[str]
+    password_hash: Mapped[str]
+    created_at: Mapped[datetime] = mapped_column(default=datetime.utcnow)
+```
+
+---
+
+## Auth (OAuth2 + JWT)
+
+```python
+# app/core/security.py
+from passlib.hash import argon2
+from datetime import datetime, timedelta
+from jose import jwt
+from app.core.config import settings
+
+def hash_password(p: str) -> str: return argon2.hash(p)
+def verify_password(p: str, h: str) -> bool: return argon2.verify(p, h)
+
+def create_access_token(sub: str) -> str:
+    expire = datetime.utcnow() + timedelta(minutes=15)
+    return jwt.encode({"sub": sub, "exp": expire}, settings.JWT_SECRET, algorithm="HS256")
+```
+
+```python
+# app/api/deps.py
+from fastapi.security import OAuth2PasswordBearer
+
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/v1/auth/login")
+
+async def get_current_user(token: str = Depends(oauth2_scheme)) -> User:
+    try:
+        payload = jwt.decode(token, settings.JWT_SECRET, algorithms=["HS256"])
+    except JWTError:
+        raise HTTPException(status_code=401, detail="Invalid token")
+    ...
+```
+
+---
+
+## Rate limiting (slowapi)
+
+```python
+from slowapi import Limiter
+from slowapi.util import get_remote_address
+
+limiter = Limiter(key_func=get_remote_address)
+app.state.limiter = limiter
+app.add_middleware(SlowAPIMiddleware)
+
+@router.post("/login")
+@limiter.limit("5/15minute")
+async def login(request: Request, ...):
+    ...
+```
+
+---
+
+## OpenAPI
+
+FastAPI auto-gera em `/openapi.json`. Customize:
+
+```python
+app = FastAPI(
+    title="Projeto API",
+    version="1.0",
+    openapi_url="/openapi.json",
+    docs_url="/docs",
+    redoc_url="/redoc",
+)
+```
+
+---
+
+## Settings (pydantic-settings)
+
+```python
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+class Settings(BaseSettings):
+    DATABASE_URL: str
+    JWT_SECRET: str
+    JWT_EXPIRE_MINUTES: int = 15
+    model_config = SettingsConfigDict(env_file=".env")
+
+settings = Settings()
+```
+
+---
+
+## Testes (pytest + httpx)
+
+```python
+import pytest
+from httpx import AsyncClient
+
+@pytest.mark.asyncio
+async def test_create_user(client: AsyncClient, admin_token: str):
+    response = await client.post(
+        "/v1/users",
+        json={"email": "jane@example.com", "name": "Jane", "password": "longsecret123"},
+        headers={"Authorization": f"Bearer {admin_token}"},
+    )
+    assert response.status_code == 201
+    assert response.json()["email"] == "jane@example.com"
+
+@pytest.mark.asyncio
+async def test_duplicate_email(client, admin_token):
+    await client.post("/v1/users", json={...}, headers={...})
+    response = await client.post("/v1/users", json={...}, headers={...})
+    assert response.status_code == 409
+```
+
+---
+
+## Antipatterns
+
+| AP | Antipattern | Correção |
+|---|---|---|
+| AP-01 | SQLAlchemy direto no router | Repository injetado via Depends |
+| AP-02 | Validação manual no router | Pydantic schema |
+| AP-03 | Lógica no router | Service |
+| AP-04 | `return user` (ORM) sem response_model | `response_model=UserOut` |
+| AP-05 | Secret hardcoded | pydantic-settings + .env |
+| AP-06 | Login sem rate limit | `@limiter.limit("5/15minute")` |
+| AP-07 | Senha em response | response_model sem password |
+| AP-08 | Sem `from_attributes=True` | adicionar no model_config |
+| AP-09 | `db.execute` sem await | sempre `await db.execute(...)` |
+| AP-10 | Mistura sync/async no router | tudo `async def` |
+
+---
+
+## Segurança
+
+- Senhas: `argon2.hash()` (passlib)
+- JWT: HS256 com `JWT_SECRET ≥ 32 bytes`, ou RS256 com par de chaves
+- Headers: middleware com HSTS, X-Frame-Options, CSP
+- CORS específico, nunca `*`
+- Rate limit em login + APIs públicas
+- Refresh token com rotação no DB
+
+---
+
+## CI
+
+```bash
+ruff check .
+ruff format --check .
+mypy app
+pytest --cov=app --cov-fail-under=80
+pip-audit
+alembic upgrade head --sql > /dev/null
+```
+
+---
+
+## Aplicação por fase DARE
+
+### Design
+- Endpoints REST com tags
+- Schemas Pydantic de input/output
+- Auth strategy
+
+### Blueprint
+- Estrutura de pastas
+- SQLAlchemy models preliminares
+- Roteamento `app.include_router(...)`
+
+### Tasks
+- Por feature: 4 tasks (Model, Schema, Repository, Service, Router)
+- Task de configuração slowapi + auth + OpenAPI custom
+
+### Execute
+- Ralph Loop:
+  ```bash
+  ruff check . && mypy app && pytest && pip-audit
+  ```
+
+---
+
+## Checklist final
+
+- [ ] Python 3.11+, ruff configurado
+- [ ] Pydantic v2 com `model_config = {"from_attributes": True}` quando ORM
+- [ ] SQLAlchemy 2.0 async com `Mapped[...]`
+- [ ] Todos routers usam `response_model=`
+- [ ] Services injetáveis via `Depends()`
+- [ ] Repositories encapsulam SQLAlchemy
+- [ ] `slowapi` em login + APIs públicas
+- [ ] Settings via pydantic-settings + .env
+- [ ] `mypy --strict` passa
+- [ ] Cobertura ≥ 80%
+
+---
+
+Skill licenciada MIT — parte do DARE Method v3.