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.