changes

final_implementation.md

@@ -0,0 +1,463 @@
+# 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.