# [nombre-del-servicio]

## Descripción

> Completar: qué dominio cubre este servicio, qué problema resuelve, qué tenants soporta.

## Arquitectura

Este microservicio sigue la arquitectura White Label. Las decisiones base están en:

| ADR | Tema | Leer cuando... |
|-----|------|----------------|
| [ADR-000](arch/adrs/ADR-000-arquitectura-en-cuatro-capas.md) | Organización en cuatro capas (Service/Core/Data/Platform) | agregas un caso de uso, un endpoint o un dominio |
| [ADR-001](arch/adrs/ADR-001-api-first-con-protocol-buffers.md) | API-first con Protocol Buffers (gen/ nunca se edita) | tocas el .proto o el código generado |
| [ADR-002](arch/adrs/ADR-002-modelo-multi-tenant.md) | Modelo multi-tenant con FX | agregas lógica que varía por tenant |
| [ADR-003](arch/adrs/ADR-003-comunicacion-orientada-a-eventos.md) | Comunicación orientada a eventos (NATS + CloudEvents) | agregas un producer, consumer o flujo entre servicios |

**Lee `arch/adrs/README.md` antes de tomar cualquier decisión de diseño no trivial.**

## Guardrails críticas

- **NUNCA editar archivos en `gen/`** — son generados automáticamente por `buf generate`. Cualquier cambio manual se pierde al regenerar.
- **El `.proto` es la fuente de verdad** — define el contrato antes de escribir código. Ningún feature empieza sin el proto definido.
- **Service layer**: solo valida la forma del request y delega al Core. Sin lógica de negocio.
- **Core**: orquesta casos de uso. Sin conocimiento de gRPC, HTTP ni mensajería.
- **Data**: nombra con nomenclatura de infraestructura (`cart_collection`, `session_storage`). Sin lógica de negocio.
- **Inter-dominio**: solo a través de eventos, nunca llamadas directas entre dominios.
- **Multi-tenant**: nunca `if tenant == "algo"` en lógica de negocio. Usar flags, function types o interfaces inyectados en el constructor del Core.

## Comandos de desarrollo

| Comando | Cuándo usarlo |
|---------|---------------|
| `make generate` | Después de modificar archivos `.proto` |
| `make lint` | Antes de dar una tarea de implementación por completada |
| `make fmt` | Formatear código Go y archivos `.proto` |
| `make test` | Ejecutar tests |
| `make tidy` | Limpiar dependencias después de agregar o quitar paquetes |
| `make pr` | Verificación completa pre-PR: formato, lint, tests y coverage |
| `make tools` | Instalar herramientas de desarrollo (solo setup inicial) |

## Workflow de cambios

### Cambios de implementación (día a día)
```
/spec:explore   → entender el problema
/spec:propose   → generar spec.md, design.md, tasks.md
/spec:apply     → implementar tarea por tarea
/spec:approve   → verificar con make lint y archivar
```

### Decisiones de arquitectura
```
/adr:explore    → explorar la decisión
/adr:draft      → generar borrador en arch/drafts/
/adr:record     → registrar oficialmente en arch/adrs/
```

### Decisiones autónomas del agente
Si durante la implementación necesitas tomar una decisión arquitectónica no trivial:
```
1. Crear AgDR en arch/agdrs/ con la propuesta
2. Informar al desarrollador
3. Esperar /agdr:approve antes de continuar
```

## Rol del agente

- No escribir código antes de que el `.proto` esté definido.
- No editar `gen/` bajo ninguna circunstancia.
- Crear AgDR antes de cualquier decisión arquitectónica autónoma.
- Trabajar dentro de las cuatro capas definidas en ADR-000.
- Seguir el modelo multi-tenant de ADR-002 (features, no tenants).
- Usar eventos para comunicación inter-dominio/inter-servicio (ADR-003).
- Leer los ADRs relevantes antes de proponer implementaciones.
- No implementar cambios significativos sin una spec activa.

## Estado del servicio

<!-- Actualizar al completar migraciones o tomar decisiones relevantes. -->

- [ ] [Caso de uso o migración pendiente — indicar qué archivo/patrón NO replicar si aplica]