# CLAUDE.md — [Nombre del Proyecto]

> Fuente de verdad del proyecto para Claude Code.
> Claude lee este archivo al inicio de cada sesión.
> Actualizar cuando cambien convenciones, stack o arquitectura.
> Mantener bajo 200 líneas — usar .claude/rules/ para instrucciones extensas.
> Última actualización: [YYYY-MM-DD]

---

## Qué es este proyecto

[2-3 oraciones describiendo el propósito del proyecto, el problema que resuelve
y a quién va dirigido. Ser específico — evitar frases genéricas como "sistema
de gestión empresarial".]

**Ejemplo**:
> API REST para el sistema de facturación electrónica de PyMEs en México.
> Genera CFDIs 4.0 certificados por el SAT e integra con los PACs Finkok y Diverza.
> Expone una interfaz REST consumida por el frontend Angular y la app móvil React Native.

---

## 1. Stack tecnológico

| Capa | Tecnologia | Version |
|------|-----------|---------|
| Lenguaje backend | Python | 3.12 |
| Framework backend | FastAPI | 0.115+ |
| ORM | SQLAlchemy | 2.0 (async) |
| Base de datos | PostgreSQL | 16 |
| Migraciones | Alembic | 1.13+ |
| Gestor de paquetes | uv | 0.5+ |
| Lenguaje frontend | TypeScript | 5.4+ |
| Framework frontend | Angular | 20+ |
| Estilos | Tailwind CSS | 4.0 |
| Tests backend | pytest + httpx | - |
| Tests frontend | Jasmine + Karma | - |
| CI/CD | GitHub Actions | - |
| Contenedores | Docker + Compose | - |

> Ajustar esta tabla al stack real del proyecto. Eliminar filas que no aplican.

---

## 2. Convenciones de código

### Python / Backend

- **Estilo**: PEP 8 + Ruff para lint y formato. Máximo 88 caracteres por línea.
- **Type hints**: Obligatorios en toda función pública. Sin `Any` sin justificación.
- **Docstrings**: Solo en funciones públicas de módulos, clases y endpoints complejos.
  Formato Google Style.
- **Imports**: Agrupados — stdlib, terceros, locales. Separados por línea en blanco.
- **Nombres**: `snake_case` para variables y funciones, `PascalCase` para clases.

### TypeScript / Frontend

- **Framework**: Angular 20+ con signals. Sin NgModules para componentes nuevos.
- **Directivas de control**: `@if`, `@for`, `@switch`. NUNCA `*ngIf`, `*ngFor`.
- **Estado**: `signal()` y `computed()` para estado reactivo.
- **Estilos**: Tailwind CSS. Angular Material SOLO para componentes funcionales.
- **HTTP**: Siempre tipado. Sin `any` en responses de API.

### Naming conventions

- Archivos: `kebab-case` para todos los archivos
- Componentes Angular: `nombre.component.ts`, `nombre.component.html`
- Services: `nombre.service.ts`
- Models: `nombre.model.ts`
- Tests: `nombre.spec.ts` (frontend), `test_nombre.py` (backend)

---

## 3. Arquitectura

```
src/
+-- [capa-1]/          # [Descripción: ej. "Componentes React compartidos"]
+-- [capa-2]/          # [Descripción: ej. "Handlers / lógica de negocio"]
+-- [capa-3]/          # [Descripción: ej. "Utilidades compartidas"]
+-- [capa-4]/          # [Descripción: ej. "Modelos de datos y schemas"]
```

### Reglas de arquitectura
- Services no importan directamente modelos de otros dominios
- Endpoints no tienen lógica de negocio — delegan a services
- Componentes no hacen llamadas HTTP directamente — usan services

---

## 4. Seguridad

- No secretos en código ni logs — usar variables de entorno
- Validar todos los inputs del usuario en el boundary del sistema
- Usar queries parametrizadas — NUNCA concatenación de strings SQL
- RBAC en todos los endpoints que modifican datos
- CORS configurado explícitamente — no wildcard `*` en producción
- Rate limiting en endpoints públicos
- Headers de seguridad: HSTS, X-Content-Type-Options, X-Frame-Options

---

## 5. Testing

### Estrategia de tests

| Tipo | Framework | Cobertura mínima |
|------|-----------|-----------------|
| Unit tests backend | pytest | 80% líneas |
| Integration tests | pytest + httpx | Todos los endpoints |
| Unit tests frontend | Jasmine + Karma | 70% líneas |
| E2E tests | Playwright / Cypress | Flujos críticos |

### Como correr tests

```bash
# Backend — tests completos con cobertura
pytest tests/ --cov=app --cov-report=html -v

# Backend — solo un modulo
pytest tests/test_facturacion.py -v

# Frontend — tests unitarios
ng test

# Frontend — E2E
ng e2e

# Lint y tipo-checking
ruff check app/ tests/
mypy app/
```

### Reglas de testing
- Todo PR debe incluir tests para código nuevo/modificado
- Tests deben tener assertions reales (no solo verificar que no lanza excepción)
- Fixtures compartidas en `conftest.py` / `test-utils.ts`
- Mock solo para dependencias externas (APIs, email). NUNCA mockear la BD en integration tests.

---

## 6. Git Workflow

### Ramas
- `main` — produccion, protegida
- `develop` — integracion (si aplica)
- `feature/descripcion-corta` — features nuevas
- `fix/descripcion-corta` — bug fixes
- `chore/descripcion` — mantenimiento

### Commits
Formato Conventional Commits en inglés:
```
feat: add CFDI billing endpoint
fix: correct RFC validation in schema
chore: update security dependencies
refactor: extract billing logic to service
test: add integration tests for auth flow
```

### Pull Requests
- Al menos 1 revisor
- Tests pasando en CI
- Sin TODO sin ticket asociado
- Squash merge a main

---

## 7. Comandos comunes (Workflows)

```bash
# --- Setup inicial ---
uv sync                                    # Instalar dependencias Python
npm install                                # Instalar dependencias frontend

# --- Desarrollo ---
uvicorn app.main:app --reload --port 8000  # Backend dev server
ng serve --open                            # Frontend dev server

# --- Base de datos ---
alembic revision --autogenerate -m "desc"  # Crear migracion
alembic upgrade head                       # Aplicar migraciones
alembic downgrade -1                       # Revertir ultima

# --- Testing ---
pytest tests/ -v                           # Tests backend
ng test                                    # Tests frontend

# --- Calidad ---
ruff check app/ tests/                     # Lint Python
ruff format app/ tests/                    # Format Python
mypy app/                                  # Type checking

# --- Docker ---
docker compose up -d postgres redis        # Solo infra
docker compose up --build                  # Todo
docker compose down                        # Detener
```

---

## Reglas anti-error del proyecto

> Estas reglas documentan errores que ya ocurrieron en este proyecto.
> Son la segunda defensa después de los tests.

### Backend

- **selectinload OBLIGATORIO**: Toda relación accedida en serialización Pydantic
  DEBE tener `selectinload()` en el query. Sin esto -> `MissingGreenlet` en runtime.
- **Services NO hacen commit**: Solo `db.add()`, `db.flush()`, `db.refresh()`.
  El commit SIEMPRE en el endpoint.
- **Literal[] en schemas**: Campos con dominio cerrado (`estatus`, `tipo`) DEBEN
  usar `Literal["valor1", "valor2"]`. NUNCA `str` sin restricción.
- **RBAC en escritura**: Todos los endpoints POST/PUT/DELETE deben tener
  `_=Depends(require_role([...]))`.

### Frontend

- **PaginatedResponse**: Todo endpoint paginado parsear con `.pipe(map(r => r.items))`.
- **track obligatorio en @for**: `@for (item of items; track item.id)`.
- **takeUntilDestroyed()**: En toda suscripcion larga o polling.

---

## Estructura de archivos

```
[Pegar aqui la estructura de arbol del proyecto, generada con:
  tree -I "node_modules|__pycache__|.git|*.pyc|dist|build" --max-depth=3
]
```

---

## Variables de entorno requeridas

Copiar `.env.example` a `.env` y completar antes de ejecutar:

```bash
cp .env.example .env
```

Descripción de cada variable en `.env.example`. Las variables marcadas con `*`
son obligatorias para correr en desarrollo.

---

## Agentes y skills activos en este proyecto

| Tipo | Nombre | Propósito |
|------|--------|-----------|
| Skill | [nombre] | [qué cubre] |
| Agente | [nombre] | [cuándo se usa] |
| Comando | `/proyecto:nombre` | [qué hace] |

---

*Template generado con `Skill("estructura-proyecto-claude")` el [YYYY-MM-DD].*
*Mantener actualizado al cierre de cada fase con `consolidador-swl`.*
