Kontia/final_implementation.md

# Final Implementation Plan - Modulos 8, 9 y 10

## 1. Objetivo
Implementar M08, M09 y M10 como una cadena operativa completa:

- M08 Gestion Estrategica de Contratos: registro de contratos, entregables, pagos y carga inteligente de PDF.
- M09 Proteccion Legal: diagnostico guiado, gestion de casos, ruta de escalada, generador de escritos y directorio.
- M10 Expediente Preventivo: simulador de auditoria y expediente institucional centralizado.

El alcance sigue exactamente la UX mostrada en las referencias y se integra con M5 y M7 ya existentes.

## 2. Principios de implementacion
- Reusar patrones actuales: App Router, Prisma, componentes estilo M7, endpoints administrativos autenticados.
- Mantener trazabilidad completa: cada caso legal y cada auditoria debe poder rastrear contrato, entregable, pago y evidencia origen.
- Diseñar para escalamiento nacional: iniciar con seed federal + NL y permitir extender por estado/municipio.
- Regla conservadora legal: donde no haya certeza normativa, marcar "requiere validacion legal".

## 3. M08 - Gestion Estrategica de Contratos

### 3.1 Ruta y UI
- Nueva ruta: `/gestion-contratos`.
- Header de flujo:
  - back: `M7: Alertas`
  - next: `M9: Legal`
- KPIs:
  - Contratos activos
  - Total cobrado
  - Entregables pendientes
  - Entregables vencidos
- Tabs:
  - Subir Contrato
  - Contratos
  - Entregables
  - Pagos

### 3.2 Dominio y modelo de datos
Agregar en Prisma:

- `ContractRecord`
  - `id, userId, sourceProposalId?`
  - `title, counterpartyEntity, contractNumber, contractType`
  - `startDate, endDate, totalAmount, currency`
  - `status` (`ACTIVE|COMPLETED|PAUSED|CANCELLED`)
  - `description, createdAt, updatedAt`
- `ContractDeliverable`
  - `id, contractId, title, dueDate, amountLinked?`
  - `status` (`PENDING|DELIVERED|APPROVED|REJECTED|OVERDUE`)
  - `deliveredAt?, approvedAt?, notes`
- `ContractPayment`
  - `id, contractId, amount, paymentDate, invoiceNumber?, concept`
  - `status` (`REGISTERED|CONFIRMED|DISPUTED`)
- `ContractDocument`
  - `id, contractId, fileName, filePath, mimeType, sizeBytes, checksumSha256`
  - `kind` (`SIGNED_CONTRACT|ADDENDUM|DELIVERABLE_EVIDENCE|PAYMENT_EVIDENCE|OTHER`)
- `ContractExtractionHistory`
  - `id, contractId?, userId, engine, model, resultJson, warningsJson, analyzedAt`

Indices:
- `ContractRecord(userId,status,endDate)`
- `ContractDeliverable(contractId,status,dueDate)`
- `ContractPayment(contractId,paymentDate)`

### 3.3 APIs
- `GET /api/contracts` list + filtros.
- `POST /api/contracts` crear contrato manual (modal Nuevo Contrato).
- `PATCH /api/contracts/:id` editar estado y datos clave.
- `POST /api/contracts/upload` subir PDF firmado.
- `POST /api/contracts/extract` OCR + IA y crear/actualizar contrato.
- `GET /api/contracts/kpis` dataset de M08.
- `POST /api/contracts/:id/deliverables` crear entregable (modal).
- `PATCH /api/deliverables/:id` cambiar estado.
- `POST /api/contracts/:id/payments` registrar pago (modal).
- `GET /api/contracts/:id/payments` historial.

### 3.4 IA para "Subir Contrato"
Reusar pipeline de PDF existente:
- `analyzePdf` para texto/OCR.
- Nuevo extractor IA `extractContractWithAi`:
  - campos: titulo, entidad contratante, numero, tipo, fechas, monto total.
  - lista de entregables detectados.
  - hitos de pago detectados.
  - clausulas de riesgo contractual (para alimentar M9).
- Guardar trazabilidad en `ContractExtractionHistory`.

### 3.5 Reglas funcionales
- Contrato activo: `status=ACTIVE` y fecha fin no vencida (o sin fecha fin).
- Entregable vencido: `status=PENDING` y `dueDate < now`.
- Total cobrado: sumatoria pagos confirmados.
- Barra de avance por contrato: `entregables completados / entregables totales`.

## 4. M09 - Proteccion Legal

### 4.1 Ruta y UI
- Nueva ruta: `/proteccion-legal`.
- Header de flujo:
  - back: `M8: Contratos`
  - next: `M10: Auditorias`
- KPIs:
  - Casos abiertos
  - Alta severidad
  - Monto en riesgo
  - Casos resueltos
- Tabs:
  - Diagnostico
  - Casos
  - Escalada
  - Escritos
  - Directorio

### 4.2 Dominio y modelo de datos
Agregar en Prisma:

- `LegalCase`
  - `id, userId, contractId?`
  - `caseType` (`CONTRACT_BREACH|PAYMENT_RETENTION|UNJUST_SANCTION|CONTRACT_DISPUTE`)
  - `severity` (`LOW|MEDIUM|HIGH`)
  - `counterparty, description`
  - `amountAtRisk`
  - `status` (`OPEN|IN_PROGRESS|ESCALATED|RESOLVED|CLOSED`)
  - `openedAt, resolvedAt?`
- `LegalDiagnosis`
  - `id, userId, legalCaseId?`
  - `stepIndex, totalSteps, answersJson, recommendedRouteJson`
- `LegalEscalationStepLog`
  - `id, legalCaseId, routeStepKey, completedAt?, notes`
- `LegalDocument`
  - `id, legalCaseId?, userId, templateKey?, aiGenerated`
  - `title, content, createdAt`
- `LegalDirectoryEntity`
  - `id, jurisdictionLevel, name, scopeTagsJson`
  - `websiteUrl?, phone?, email?, stateCode?, municipalityCode?`
  - `isActive`

### 4.3 APIs
- `GET /api/legal/kpis`
- `POST /api/legal/diagnosis/start`
- `POST /api/legal/diagnosis/answer`
- `POST /api/legal/cases`
- `GET /api/legal/cases`
- `PATCH /api/legal/cases/:id` (resolver/escalar)
- `GET /api/legal/escalation/:caseId`
- `POST /api/legal/documents/generate` (IA)
- `GET /api/legal/templates`
- `GET /api/legal/directory`

### 4.4 Motor de diagnostico
Wizard de 4 pasos como referencia:
1. Tipo de incumplimiento.
2. Estado procesal y evidencia disponible.
3. Impacto economico y urgencia.
4. Objetivo legal (pago, correccion, impugnacion, mediacion).

Salida:
- severidad sugerida
- tipo de caso sugerido
- ruta escalada sugerida
- lista de escritos recomendados

### 4.5 Ruta Escalada (tab Escalada)
Catalogo base de pasos:
1. Requerimiento formal
2. Conciliacion administrativa
3. Queja ante OIC
4. Inconformidad ante SFP/Organo estatal
5. Via jurisdiccional

Cada paso incluye:
- ventana estimada de tiempo
- checklist de acciones
- bandera de "requiere abogado"
- dependencias del paso previo

### 4.6 Escritos (IA + plantillas)
- Selector de tipo de caso y severidad.
- Inputs: contraparte, empresa, monto, descripcion.
- Generador IA produce borrador estructurado y editable.
- Plantillas predefinidas por categoria (como en referencia):
  - General: Acta entrega-recepcion.
  - Incumplimiento: Carta de inconformidad.
  - Retencion de pagos: Solicitud de liberacion.
  - Sanciones: Recurso de inconformidad.
- Guardar documento y boton copiar/exportar.

### 4.7 Directorio
Seed inicial federal + estatal:
- SFP, TFJA, ASF, OIC, CompraNet, sistemas anticorrupcion estatales, etc.
- Filtros por jurisdiccion y tipo de autoridad.

## 5. M10 - Expediente Preventivo

### 5.1 Ruta y UI
- Nueva ruta: `/expediente-preventivo`.
- Header de flujo:
  - back: `M9: Legal`
- KPIs:
  - Auditorias completadas
  - Ultima calificacion
  - Contratos registrados (desde M08)
  - PDFs resguardados (M08 + M5)
- Tabs:
  - Simulador
  - Expediente

### 5.2 Dominio y modelo de datos
Agregar en Prisma:

- `AuditSimulation`
  - `id, userId, name, auditType`
  - `status` (`DRAFT|COMPLETED`)
  - `overallScore, completedAt?`
- `AuditSimulationSection`
  - `id, simulationId, key`
  - `score, status` (`READY|WARNING|CRITICAL`)
  - `findingsJson, recommendationsJson`
- `AuditChecklistResponse`
  - `id, simulationId, questionKey, answer, evidenceRefsJson`
- `InstitutionalDossierSnapshot`
  - `id, userId, generatedAt, payloadJson`

Secciones del simulador v1:
- Cumplimiento fiscal
- Cumplimiento laboral
- Documentacion legal
- Control operativo
- Transparencia financiera

### 5.3 APIs
- `POST /api/audits/simulations`
- `GET /api/audits/simulations`
- `POST /api/audits/simulations/:id/score`
- `GET /api/audits/simulations/:id`
- `GET /api/audits/expediente`
- `POST /api/audits/expediente/refresh`

### 5.4 Logica del expediente
Consolidar automaticamente:
- M5: propuestas, workflow, documentos.
- M8: contratos, entregables, pagos, contratos PDF.
- M9: casos, escritos, evidencia de escalada.
- M7: alertas activas de cumplimiento para semaforo preventivo.

Resultado:
- vista de historial institucional lista para auditoria.
- estado por componente (completo/incompleto).

## 6. Integraciones entre modulos
- M5 -> M8: crear contrato desde propuesta adjudicada.
- M8 -> M9: boton "abrir caso legal" desde contrato/entregable/pago.
- M8 -> M10: contratos y PDFs alimentan expediente.
- M9 -> M10: casos, escritos y escalada alimentan expediente.
- M7 <-> M8/M9: alertas por entregables vencidos, pagos disputados, casos alta severidad.

## 7. Tipos de dominio (frontend/backend)
Crear `src/lib/contracts/types.ts`, `src/lib/legal/types.ts`, `src/lib/audits/types.ts` con:
- snapshots KPI por modulo
- enums de estado
- payloads de formularios (modales)
- DTOs para tabs
- contratos de IA (input/output) para extractor de contrato y generador de escritos

## 8. Plan de implementacion por fases

### Fase A (base de datos + navegacion)
- Prisma models, migraciones, seeds.
- Rutas vacias M08/M09/M10 con header y tabs.
- Linkear dashboard (Plan 3) a rutas reales.

### Fase B (M08 operativo)
- CRUD contratos + entregables + pagos.
- KPIs y tabs funcionales.
- Upload PDF + extraccion IA + guardado en expediente.

### Fase C (M09 operativo)
- Diagnostico wizard y creacion de casos.
- Registro/seguimiento de casos.
- Escalada guiada con checklist por paso.
- Generador IA de escritos + plantillas + copiar/exportar.
- Directorio con seed inicial.

### Fase D (M10 operativo)
- Simulador de auditoria con scoring por seccion.
- Expediente centralizado con agregacion M5/M8/M9.
- KPIs finales y acciones correctivas sugeridas.

### Fase E (hardening)
- permisos por plan, auditoria de cambios, logs de errores IA.
- observabilidad de pipelines OCR/IA.
- refinamiento de UX responsive y accesibilidad.

## 9. Plan de pruebas

### Unit
- Formulas KPI M08/M09/M10.
- Reglas de estado (vencido, resuelto, escalado, activo).
- Scoring del simulador.
- Seleccion de ruta legal por diagnostico.

### Integration
- Flujo completo: contrato (M08) -> caso (M09) -> expediente (M10).
- Extraccion IA de contrato -> creacion de entregables/pagos.
- Generacion de escrito IA + guardado en caso.

### UI/E2E
- Paridad visual de tabs y KPI cards con referencias.
- Modales: Nuevo Contrato, Nuevo Entregable, Registrar Pago.
- Estados vacios y poblados.
- Responsive movil/escritorio.

## 10. Criterios de aceptacion
- M08 permite crear contrato, registrar entregable y pago, y ver KPIs actualizados en tiempo real.
- M09 permite abrir caso desde diagnostico, escalarlo por pasos, y generar escritos IA reutilizables.
- M10 muestra simulaciones con score y expediente consolidado de evidencia documental.
- Navegacion lineal operativa M7 -> M8 -> M9 -> M10.
- Build, test y lint sin errores bloqueantes.

## 11. Defaults V1
- Sin firma digital de escritos dentro del sistema (solo generacion y exportacion).
- Sin integracion externa de tribunales/SFP para envio automatico (solo preparacion guiada).
- Directorio legal inicial federal + NL, extensible por seed.
- Clasificacion de riesgo legal conservadora si faltan evidencias.

## 12. Master Checklist de Implementacion

### 12.1 Preparacion
- [ ] Confirmar alcance funcional final con producto (M08, M09, M10 + integraciones).
- [ ] Validar naming final de rutas: `/gestion-contratos`, `/proteccion-legal`, `/expediente-preventivo`.
- [ ] Confirmar permisos por plan (Plan 3) y reglas de acceso admin/pago.

### 12.2 Fase A - Data + Navegacion Base
- [ ] Crear modelos Prisma M08/M09/M10.
- [ ] Crear enums Prisma para estados de contratos, casos y auditorias.
- [ ] Crear migraciones SQL + seeds iniciales (directorio legal, catalogos base).
- [ ] Ejecutar `npm run prisma:generate`.
- [ ] Crear paginas base de rutas M08, M09 y M10 con layout y header de flujo.
- [ ] Conectar dashboard (tarjetas M08/M09/M10) a rutas reales.

### 12.3 Fase B - M08 Operativo
- [ ] Implementar dominio `contracts` (`types.ts`, validadores, mappers).
- [ ] Implementar endpoints CRUD de contratos.
- [ ] Implementar endpoints de entregables y pagos.
- [ ] Implementar endpoint KPI de M08.
- [ ] Implementar tab Subir Contrato (upload PDF + persistencia de archivo).
- [ ] Implementar extraccion IA de contrato y guardado de `ContractExtractionHistory`.
- [ ] Implementar UI tabs M08 (Subir Contrato, Contratos, Entregables, Pagos).
- [ ] Implementar modales: Nuevo Contrato, Nuevo Entregable, Registrar Pago.
- [ ] Implementar reglas de negocio: activo, vencido, total cobrado, progreso.

### 12.4 Fase C - M09 Operativo
- [ ] Implementar dominio `legal` (`types.ts`, enums, validaciones).
- [ ] Implementar wizard Diagnostico (4 pasos) y recomendacion de ruta.
- [ ] Implementar CRUD de casos legales.
- [ ] Implementar tab Casos con acciones de resolver/escalar.
- [ ] Implementar tab Escalada (pasos, checklist, estatus por caso).
- [ ] Implementar generador de escritos IA y persistencia.
- [ ] Implementar repositorio de plantillas predefinidas y accion copiar/exportar.
- [ ] Implementar tab Directorio con filtros de jurisdiccion/autoridad.

### 12.5 Fase D - M10 Operativo
- [ ] Implementar dominio `audits` (`types.ts`, scoring, snapshots).
- [ ] Implementar CRUD de simulaciones de auditoria.
- [ ] Implementar motor de scoring por seccion.
- [ ] Implementar tab Simulador con historial y detalle de resultados.
- [ ] Implementar agregador de expediente institucional (M5 + M8 + M9 + M7).
- [ ] Implementar tab Expediente con estados vacios/poblados y trazabilidad.
- [ ] Implementar KPIs de M10.

### 12.6 Fase E - Hardening
- [ ] Reglas de autorizacion por plan en rutas y APIs.
- [ ] Auditoria de cambios (logs funcionales por entidad critica).
- [ ] Manejo robusto de errores IA/OCR con mensajes accionables.
- [ ] Validacion de performance en listados y agregadores (paginacion/indices).
- [ ] Reforzar accesibilidad (labels, focus, teclado, contraste).

## 13. Task Backlog (Orden de Ejecucion)

### 13.1 Arquitectura y Persistencia
1. [ ] Crear schema Prisma para M08 (contratos, entregables, pagos, documentos, extraccion).
2. [ ] Crear schema Prisma para M09 (casos, diagnostico, escalada, documentos, directorio).
3. [ ] Crear schema Prisma para M10 (simulaciones, respuestas, snapshots).
4. [ ] Agregar indices y constraints de integridad.
5. [ ] Generar y revisar migraciones.
6. [ ] Ejecutar seeds base (directorio legal + catalogos).

### 13.2 Backend APIs
1. [ ] Crear `src/app/api/contracts/*`.
2. [ ] Crear `src/app/api/legal/*`.
3. [ ] Crear `src/app/api/audits/*`.
4. [ ] Implementar servicios en `src/lib/contracts`, `src/lib/legal`, `src/lib/audits`.
5. [ ] Agregar validaciones de entrada/salida y manejo de errores uniforme.

### 13.3 Frontend M08
1. [ ] Crear pantalla principal M08 con 4 KPIs y tabs.
2. [ ] Implementar tab Contratos (cards, progreso, estado).
3. [ ] Implementar tab Entregables (pendiente/vencido/completado).
4. [ ] Implementar tab Pagos (registro e historial).
5. [ ] Implementar tab Subir Contrato + drag/drop + estado de analisis IA.
6. [ ] Conectar modales a APIs y refresco de dataset.

### 13.4 Frontend M09
1. [ ] Crear pantalla principal M09 con KPIs y tabs.
2. [ ] Implementar wizard Diagnostico con barra de progreso.
3. [ ] Implementar tab Casos con filtros por severidad/estado.
4. [ ] Implementar tab Escalada con timeline de pasos.
5. [ ] Implementar tab Escritos (formulario IA + plantillas).
6. [ ] Implementar tab Directorio (cards de entidades + acciones contacto).

### 13.5 Frontend M10
1. [ ] Crear pantalla principal M10 con KPIs y tabs.
2. [ ] Implementar tab Simulador (nueva simulacion, scoring y resultados).
3. [ ] Implementar tab Expediente (contratos, PDFs, propuestas, casos, escritos).
4. [ ] Implementar navegacion back/next M9 <-> M10 y Dashboard.

### 13.6 Integraciones Cross-Module
1. [ ] Habilitar handoff M5 -> M8 para crear contrato desde propuesta adjudicada.
2. [ ] Habilitar handoff M8 -> M9 para abrir caso legal contextual.
3. [ ] Habilitar agregacion M8 + M9 en M10.
4. [ ] Publicar alertas M8/M9 relevantes para M7 (vencimientos y riesgo legal).

## 14. Master Test Plan

### 14.1 Unit Tests
- [ ] Reglas de calculo KPI M08.
- [ ] Reglas de calculo KPI M09.
- [ ] Reglas de calculo KPI M10.
- [ ] Motor de scoring del simulador.
- [ ] Clasificacion de severidad y rutas legales.
- [ ] Normalizacion de extraccion IA de contrato.

### 14.2 Integration Tests
- [ ] Flujo M5 -> M8 (creacion de contrato desde propuesta).
- [ ] Flujo M08 completo (contrato -> entregable -> pago -> KPI).
- [ ] Flujo M8 -> M9 (apertura de caso legal).
- [ ] Flujo M9 -> M10 (caso/escrito visibles en expediente).
- [ ] Flujo M7 con alertas de entregables vencidos y casos severos.

### 14.3 UI/E2E
- [ ] Paridad visual de M08 (tabs, cards, modales, empty/data states).
- [ ] Paridad visual de M09 (diagnostico, casos, escalada, escritos, directorio).
- [ ] Paridad visual de M10 (simulador y expediente).
- [ ] Responsive movil/escritorio en M08/M09/M10.
- [ ] Accesibilidad basica de formularios y modales.

## 15. Release Gate (Definition of Done)

### 15.1 Calidad Tecnica
- [ ] Migraciones aplicadas sin errores en entorno objetivo.
- [ ] Seeds ejecutados y datos base disponibles.
- [ ] Sin errores TypeScript en build.
- [ ] Sin errores de lint bloqueantes.
- [ ] Tests unitarios/integracion/UI en verde.

### 15.2 Verificaciones por Comando (orden recomendado)
1. [ ] `npm run prisma:generate`
2. [ ] `npm run prisma:migrate`
3. [ ] `npm test`
4. [ ] `npm run lint`
5. [ ] `npm run build` (FINAL CHECK OBLIGATORIO)

### 15.3 Aprobacion Funcional Final
- [ ] Demo E2E: M8 -> M9 -> M10 con datos reales de prueba.
- [ ] Validacion de KPIs contra datos de ejemplo.
- [ ] Validacion de guardado y recuperacion de evidencia/documentos.
- [ ] Sign-off final de producto.