# Routers (v3)

Domain-based FastAPI routers under `/api/v3/` prefix. Each file = one resource.

## Patterns

- Every endpoint uses `@handle_db_errors` decorator (from `dependencies.py`)
- GET endpoints use `@cache_result(ttl=N, key_prefix="name")` for Redis caching
- Auth: `token: str = Depends(oauth2_scheme)` + `valid_token(token)` check on mutating endpoints
- Pydantic models for POST/PATCH bodies are defined inline in router files (not db_engine)
- POST models: `id` fields must be `Optional[int] = None` (DB auto-generates)

## Two Styles Coexist

- **Refactored** (players, teams): Thin HTTP layer → delegates to `services/` layer
- **Legacy** (most others): Business logic directly in router, imports models from `db_engine`

## Adding a New Router

1. Create `app/routers_v3/newrouter.py` with `router = APIRouter(prefix="/api/v3/name", tags=["name"])`
2. Import and register in `app/main.py`: `from .routers_v3 import newrouter` + `app.include_router(newrouter.router)`

## IMPORTANT

- PATCH endpoints: build update dict explicitly from parameters. Never use `locals()`.
- `stratplay/` is a sub-package with its own `__init__.py` and sub-routers (batting, pitching, fielding, plays, crud)