# PROMPT SPRINT 1.5a — Contratos NI (Necesidad Inmediata)

> **Para Ricci:** Pegá este prompt en sesión NUEVA de Claude Code.
> Este es el sprint que hace de Innovium un producto vendible para funerarias chilenas reales.

---

Hola Claude. Soy Ricci de Crono Systems. Sprint 1.4 cerrado (panel admin con upload R2), ahora vamos con **Sprint 1.5a: Contratos NI (Necesidad Inmediata) con fidelidad al sistema chileno funerario**.

## Contexto importante

Este sprint es **el más crítico del proyecto**. Está modelado sobre el sistema legacy `systemserp_sgc` que actualmente usa la Funeraria Infinia en producción. He revisado:
- 2 contratos PDF reales (CT-1149 Infinia, CT-1150 Memorias Santiago)
- Schema legacy con 143 tablas
- Código PHP de generación de PDF con FPDF
- Flujo de venta NI completo

Lo que vamos a construir es **el mismo flujo pero modernizado**: multi-tenant, schema limpio, models data-mapper, validaciones server-side, R2 storage, design system Innovium.

## Lectura obligatoria antes de codear

En orden:

1. `CLAUDE.md`
2. `docs/ARQUITECTURA.md`
3. `docs/sprint-1-3/SCHEMA_CATALOGO.md`
4. `docs/sprint-1-4/STORAGE_R2.md`
5. `docs/sprint-1-4/VALIDADOR_CHILE.md`
6. `docs/sprint-1-5a/SCHEMA_NI.md` — las 14 tablas nuevas
7. `docs/sprint-1-5a/CATALOGOS_LEGACY.md` — seeds chilenos
8. `docs/sprint-1-5a/WIZARD_NI.md` — los 7 pasos del wizard
9. `docs/sprint-1-5a/PDF_NI_TEMPLATE.md` — template del PDF (replicar Infinia)
10. `docs/sprint-1-5a/CRITERIOS_ACEPTACION_1_5a.md`

**No empieces hasta haber leído todo.**

## Alcance del sprint

### Lo que entra ✅

#### A. Schema (10 migraciones tenant)

1. `0024_create_entidades_previsionales_table.sql`
2. `0025_create_parentescos_table.sql`
3. `0026_create_estados_civiles_table.sql`
4. `0027_create_nacionalidades_table.sql`
5. `0028_create_geografia_chile_tables.sql` (regiones + provincias + comunas en uno)
6. `0029_create_capillas_y_carrozas_tables.sql`
7. `0030_create_convenios_y_sucursales_velatorios_tables.sql`
8. `0031_create_clientes_y_fallecidos_tables.sql`
9. `0032_create_contratos_y_secuencias_tables.sql`
10. `0033_create_aportes_y_servicios_tables.sql`

#### B. Seeders chilenos (al hacer migrate:tenant)

11. Modificar `MigrateTenantCommand` para aplicar seeds automáticamente
12. Crear archivos `database/seeds/catalogos/*.sql` con la data de:
    - 30 entidades previsionales
    - 19 parentescos
    - 5 estados civiles
    - 160 nacionalidades
    - 16 regiones, 56 provincias, 346 comunas (dataset chileno)
    - 3 capillas
    - 4 tipos de carroza
    - "Casa Matriz" como sucursal inicial
    - Secuencia inicial (NI=0, NF=0; demo arranca en NI=1148)

#### C. Comando para retroactivo

13. `php scripts/innovium catalogos:seed <slug>` — siembra catálogos en tenants existentes (demo, infinia)

#### D. Models nuevos (10)

- `EntidadPrevisional`
- `Parentesco`
- `EstadoCivil`
- `Nacionalidad`
- `Region`, `Provincia`, `Comuna`
- `Capilla`
- `TipoCarroza`
- `Convenio`
- `Sucursal`
- `Velatorio`
- `Cliente` (con `findByRut`, `searchByRutOrName`)
- `Fallecido`
- `Contrato` (con `generarNumero`, `crearTransaccional`)
- `AporteContrato`
- `ServicioContrato`

Todos siguen el patrón data-mapper de Sprint 1.1 (FILLABLE, soft delete, sin ORM).

#### E. Pantalla de gestión de catálogos en admin

14. **`/admin/sucursales`** — CRUD básico (modal, igual a categorías)
15. **`/admin/velatorios`** — CRUD básico
16. **`/admin/convenios`** — CRUD básico

(Las entidades previsionales, parentescos, etc., NO tienen UI editable porque son catálogos master compartidos.)

#### F. Wizard de venta NI (7 pasos)

17. **`/admin/contratos`** — listado con filtros
18. **`/admin/contratos/nuevo`** — wizard de 7 pasos:
    - Paso 1 · Cliente (búsqueda RUT + form)
    - Paso 2 · Fallecido
    - Paso 3 · Plan + cofre (medidas)
    - Paso 4 · Servicio funerario (capilla, carroza, toggles, otros servicios)
    - Paso 5 · Complemento (lugar velación/sepultación, fecha funeral)
    - Paso 6 · Pagos (aportes previsionales hasta 3, abono cliente)
    - Paso 7 · Firma + confirmación + creación transaccional
19. **`/admin/contratos/<id>`** — vista de contrato
20. **Botón "Descargar PDF"** que genera y descarga
21. **Botón "Enviar por email"** (manual con `mail()` PHP, Sprint 2.x SMTP profesional)

#### G. Generación de PDF idéntico a Infinia

22. `app/Core/PdfGeneratorNI.php` — wrapper sobre DomPDF
23. `app/Views/contratos/pdf_ni.php` + `pdf_ni_styles.css` — template
24. **Marca de agua del logo a tamaño grande** centrado, color original, opacidad 12-15%
25. RUT formato chileno con puntos y guión
26. Formato monetario chileno ($ 1.380.000)
27. Formato fecha chileno (DD/MM/AAAA)
28. Las 5 cards numeradas idénticas al PDF de referencia

#### H. Tests

29. `EntidadPrevisionalTest`, `ParentescoTest` — CRUD básico
30. `ContratoNITest` — generación de número, creación transaccional, snapshot
31. `WizardNIFlowTest` — flujo completo end-to-end (mock HTTP)
32. `PdfGeneratorNITest` — PDF se genera con PDF válido
33. `RutFormatTest` — formato chileno

### Lo que NO entra ❌

- 🚫 **NF (Necesidad Futura)** → Sprint 1.5b siguiente
- 🚫 **Anulación de contratos** → Sprint 1.5c
- 🚫 **Vista de contrato con tabs detallados** → Sprint 1.5c (por ahora vista simple)
- 🚫 **Detalle de cheques/tarjetas/transferencias** → Sprint 2.x cobranzas
- 🚫 **Médico certificador con honorarios** → Sprint 2.x
- 🚫 **Datero/comisiones** → Sprint 2.x
- 🚫 **Egresos del contrato (gastos reales)** → Sprint 2.x
- 🚫 **Licitaciones municipales** → Sprint 2.x
- 🚫 **Inscripciones / Registro Civil tracking** → Sprint 2.x
- 🚫 **SMTP profesional** → Sprint 2.x (por ahora `mail()`)

## Decisiones ya tomadas

### Numeración

- Secuencial por tenant + tipo: `NI` empieza en 0001 (excepto demo que arranca en 1148 para que el primer contrato sea 1149 como Infinia real)
- Sin prefijo en el campo `numero` (legacy usa solo "1149"). El PDF muestra "CONTRATO Nº 1149"
- Tabla `contratos_secuencias (tipo_contrato, ultimo_numero)` con transacción para evitar race conditions

### Aportes previsionales

- Hasta **3 entidades** por contrato (límite legacy)
- Tabla `contrato_aportes_previsionales` con FK a `entidades_previsionales`
- Snapshot del nombre por si se desactiva la entidad después
- Campo `fecha_verificada` opcional (cuando finanzas confirma el pago)

### Firma

- Igual que Sprint 1.5 plan original: PNG en R2, canvas signature_pad
- Path: `tenants/<slug>/firmas/CT-NI-NNNN.png`

### PDF

- DomPDF
- Tamaño Carta chileno (216×330mm), NO A4
- Marca de agua del logo del tenant a tamaño grande, opacidad 12%
- Si tenant no tiene logo, marca de agua se omite
- Tipografía Helvetica (compatibilidad DomPDF)
- Cards con borde sutil + bg blanco + bg gris en headers (#f5f5f5)

### Validaciones

- Server-side siempre con `Validator` del Sprint 1.4
- Cliente-side ligero para mejor UX (RUT formato mientras tipea)
- RUT obligatorio para cliente y fallecido (excepto si fallecido lo desconoce)
- Fecha defunción ≤ hoy
- Mínimo 1 entidad previsional en aportes (puede ser 0 monto)

### Audit log

- Todas las mutaciones registran:
  - `cliente.creado`, `cliente.actualizado`
  - `fallecido.creado`
  - `contrato.creado` (con número, total, etc.)
  - `aporte_previsional.agregado`
  - `convenio.aplicado`

## Plan de commits sugerido

Atómicos, en orden:

### Fase A · Schema y catálogos
1. `feat(db): migraciones catálogos chilenos (entidades, parentesco, estado civil, nacionalidad)`
2. `feat(db): migraciones geografía chile (regiones, provincias, comunas)`
3. `feat(db): migraciones tablas operativas NI (clientes, fallecidos, contratos)`
4. `feat(db): migraciones aportes y servicios extra`
5. `feat(seeds): catálogos chilenos sembrados al migrate:tenant`
6. `feat(cli): comando catalogos:seed para tenants existentes`
7. `chore: aplicar seeds a demo e infinia`

### Fase B · Models y helpers
8. `feat(models): catálogos chilenos (10 models de read-mostly)`
9. `feat(models): Cliente con búsqueda por RUT`
10. `feat(models): Fallecido y Contrato con generación de número`
11. `feat(models): AporteContrato y ServicioContrato`
12. `feat(util): formatters chilenos (RUT, CLP, fecha)`

### Fase C · Pantallas admin para sucursales/velatorios/convenios
13. `feat(admin): CRUD sucursales`
14. `feat(admin): CRUD velatorios`
15. `feat(admin): CRUD convenios`

### Fase D · Wizard de venta NI
16. `feat(contratos): listado con filtros`
17. `feat(contratos): wizard layout base con barra de progreso`
18. `feat(contratos): wizard paso 1 (cliente con búsqueda RUT)`
19. `feat(contratos): wizard paso 2 (fallecido)`
20. `feat(contratos): wizard paso 3 (plan + cofre + medidas)`
21. `feat(contratos): wizard paso 4 (servicio funerario)`
22. `feat(contratos): wizard paso 5 (complemento)`
23. `feat(contratos): wizard paso 6 (pagos: aportes + abono)`
24. `feat(contratos): wizard paso 7 (firma + crear transaccional)`

### Fase E · Vista detalle + PDF
25. `feat(contratos): vista detalle simple`
26. `feat(core): PdfGeneratorNI con DomPDF`
27. `feat(views): template PDF idéntico a Infinia con marca de agua`
28. `feat(contratos): generación PDF + descarga + envío email manual`

### Fase F · Tests + cierre
29. `test: catálogos y models NI`
30. `test: wizard NI flow completo`
31. `test: PdfGeneratorNI`
32. `chore: sprint 1.5a cerrado - contratos NI funcional`

## Cómo trabajar conmigo

1. **Lee todo lo de "lectura obligatoria"** primero

2. **Confirmá 8 puntos antes de tocar archivos:**
   - ¿Leíste SCHEMA_NI.md y entendés las 14 tablas nuevas?
   - ¿Leíste WIZARD_NI.md y entendés los 7 pasos?
   - ¿Leíste PDF_NI_TEMPLATE.md y vas a replicar el layout fielmente?
   - ¿Confirmás que las medidas del cofre, capilla, carroza son requeridas en el wizard?
   - ¿Confirmás generación transaccional del contrato (cliente + fallecido + contrato + aportes + servicios todo o nada)?
   - ¿Confirmás snapshot de nombre de entidad previsional por si se desactiva después?
   - ¿Confirmás que demo arranca en número 1148 (siguiente será 1149)?
   - ¿Tenés claro que NF, anulación y detalle de cheques NO están en este sprint?

3. **Vas mostrando avance al final de cada Fase (A-F)**, esperás OK antes de seguir.

4. **CRÍTICO:** después de cualquier cambio CSS, **siempre** correr `npm run build` antes de mostrarme. Sprint 1.4 nos dio esa lección.

5. Si tenés dudas técnicas, **preguntá** antes de inventar.

6. Cuando termines toda Fase F, mostrame:
   - `git log --oneline | head -32`
   - URL de cada pantalla nueva
   - Un PDF de prueba renderizado (screenshot)
   - Output de PHPUnit con todos verdes

## Tiempo estimado

- Trabajo de Claude Code: **5-8 sesiones** (es el sprint más complejo)
- Validación de Ricci: **2-3 horas**
- **Total: 2-3 días distribuidos**

¡Vamos! 🚀 Después de este sprint, Innovium puede vender contratos NI reales.