# CLAUDE.md — Guía Principal del Proyecto

## Stack
Python/Django · PostgreSQL · Redis · Celery · MinIO · Nginx · Docker

## 🔐 MODO AUDITOR DE SEGURIDAD — SIEMPRE ACTIVO

Actuás simultáneamente como desarrollador y auditor de seguridad.
Antes de confirmar cualquier cambio, ejecutá mentalmente los checks del archivo correspondiente.

---

## REGLAS ABSOLUTAS (no negociables)

```
❌ NUNCA hardcodear secrets, API keys o passwords en el código
❌ NUNCA commitear .env, *.pem, *.key ni credenciales de ningún tipo
❌ NUNCA usar DEBUG=True en producción
❌ NUNCA exponer stack traces al usuario final
❌ NUNCA confiar en input del usuario sin validación y sanitización
❌ NUNCA correr contenedores Docker como root
❌ NUNCA saltear autenticación en endpoints de API
❌ NUNCA loguear passwords, tokens, datos de tarjetas o respuestas completas de APIs externas
❌ NUNCA usar .env en producción — usar Docker Secrets
❌ NUNCA exponer puertos de base de datos, Redis o servicios internos al exterior
❌ NUNCA usar tags :latest en imágenes Docker
```

---

## SECRETS — REGLA CRÍTICA

| Entorno     | Método                          | .env       |
|-------------|----------------------------------|------------|
| Desarrollo  | `.env` local (en `.gitignore`)  | ✅ permitido |
| Producción  | Docker Secrets                  | ❌ prohibido |

En producción, todas las credenciales se inyectan via Docker Secrets.
Django las lee desde `/run/secrets/` o variables de entorno del sistema.
El `.env` nunca existe en producción ni se commitea bajo ninguna circunstancia.

---

## CUÁNDO LEER CADA ARCHIVO

Claude lee estos archivos SOLO cuando la tarea lo requiere, no por defecto:

| Estás trabajando en...                                                              | Leer                      |
|-------------------------------------------------------------------------------------|---------------------------|
| Docker, Nginx, volúmenes, infraestructura                                           | `docs/INFRA.md`           |
| Settings, auth, permisos, headers, ataques                                          | `docs/SECURITY.md`        |
| Modelos, vistas, serializers, servicios, ORM, comentarios                           | `docs/CODING.md`          |
| Try/except, logging, excepciones, errores en tasks o signals                        | `docs/ERROR_HANDLING.md`  |
| Tests, factories, mocks, coverage                                                   | `docs/TESTING.md`         |
| Logs, métricas, Grafana, Flower, trazabilidad                                       | `docs/OBSERVABILITY.md`   |
| Celery tasks, emails, Resend, colas                                                 | `docs/EMAIL.md`           |
| Datos de usuarios, consentimiento, privacidad                                       | `docs/GDPR.md`            |
| Antes de un PR o deploy                                                             | `docs/VERIFICATION.md`    |
| API versioning, feature flags, i18n, timezones, search, migrations, archivos estáticos | `docs/DAY1.md`        |

---

## ESTRUCTURA DEL PROYECTO

```
config/
├── settings/
│   ├── base.py          # Settings base compartidos
│   ├── development.py   # Solo desarrollo local
│   ├── production.py    # Producción — sin DEBUG, con Docker Secrets
│   └── test.py          # Tests — SQLite en memoria, Celery eager
├── urls.py
├── wsgi.py
└── asgi.py
manage.py
apps/
├── users/               # Autenticación, perfil, RBAC
├── tracing/             # Middleware de trazabilidad (ver OBSERVABILITY.md)
└── [tu_app]/
docs/                    # Estos archivos de contexto
docker/                  # Dockerfiles y configs de servicios
```

---

## PRE-COMMIT CHECKLIST (mínimo antes de cada commit)

```
[ ] Sin secrets ni API keys en el código
[ ] .env en .gitignore y no commiteado
[ ] Sin print() o logger.debug() con datos sensibles
[ ] Nuevos endpoints tienen autenticación y permisos
[ ] Inputs de usuario validados antes de usar
[ ] Errores retornan mensajes genéricos al cliente
[ ] Nuevas dependencias con versiones pinneadas
[ ] Dockerfiles no corren como root
[ ] Nuevas acciones de negocio agregadas al ActionType enum (tracing)
[ ] Nuevos params en tracing pasan por _sanitize_params()
```