diff --git a/docs/plans/2026-01-25-sat-sync-implementation.md b/docs/plans/2026-01-25-sat-sync-implementation.md new file mode 100644 index 0000000..ca77714 --- /dev/null +++ b/docs/plans/2026-01-25-sat-sync-implementation.md @@ -0,0 +1,228 @@ +# Plan de Implementación: Sincronización SAT + +## Fase 1: Base de Datos y Modelos + +### 1.1 Migraciones Prisma +- [ ] Agregar modelo `FielCredential` en schema.prisma +- [ ] Agregar modelo `SatSyncJob` en schema.prisma +- [ ] Agregar campos a modelo `Cfdi`: source, sat_sync_job_id, xml_original, last_sat_sync +- [ ] Ejecutar migración + +### 1.2 Tipos TypeScript +- [ ] Crear `packages/shared/src/types/sat.ts` con interfaces +- [ ] Exportar tipos en index.ts + +## Fase 2: Servicios de Criptografía y FIEL + +### 2.1 Servicio de Criptografía +- [ ] Crear `apps/api/src/services/sat/sat-crypto.service.ts` +- [ ] Implementar encrypt() con AES-256-GCM +- [ ] Implementar decrypt() +- [ ] Tests unitarios + +### 2.2 Servicio de FIEL +- [ ] Crear `apps/api/src/services/fiel.service.ts` +- [ ] uploadFiel() - validar y guardar credenciales encriptadas +- [ ] getFielStatus() - obtener estado sin exponer datos sensibles +- [ ] deleteFiel() - eliminar credenciales +- [ ] validateFiel() - verificar que .cer y .key coincidan +- [ ] isExpired() - verificar vigencia + +### 2.3 Dependencias +- [ ] Instalar @nodecfdi/credentials +- [ ] Instalar node-forge + +## Fase 3: Servicios de Comunicación SAT + +### 3.1 Servicio de Autenticación SAT +- [ ] Crear `apps/api/src/services/sat/sat-auth.service.ts` +- [ ] buildAuthSoapEnvelope() - construir XML de autenticación +- [ ] signWithFiel() - firmar con llave privada +- [ ] getToken() - obtener token SAML del SAT +- [ ] Manejo de errores y reintentos + +### 3.2 Servicio de Descarga SAT +- [ ] Crear `apps/api/src/services/sat/sat-download.service.ts` +- [ ] requestDownload() - solicitar descarga de CFDIs +- [ ] verifyRequest() - verificar estado de solicitud +- [ ] downloadPackage() - descargar paquete ZIP +- [ ] Polling con backoff exponencial + +### 3.3 Dependencias +- [ ] Instalar fast-xml-parser +- [ ] Instalar adm-zip + +## Fase 4: Procesamiento de CFDIs + +### 4.1 Servicio de Parser +- [ ] Crear `apps/api/src/services/sat/sat-parser.service.ts` +- [ ] extractZip() - extraer XMLs del ZIP +- [ ] parseXml() - parsear XML a objeto +- [ ] mapToDbModel() - mapear a modelo de BD + +### 4.2 Dependencias +- [ ] Instalar @nodecfdi/cfdi-core + +## Fase 5: Orquestador Principal + +### 5.1 Servicio Principal SAT +- [ ] Crear `apps/api/src/services/sat/sat.service.ts` +- [ ] startSync() - iniciar sincronización +- [ ] processInitialSync() - extracción de 10 años +- [ ] processDailySync() - extracción mensual +- [ ] saveProgress() - guardar progreso en sat_sync_jobs +- [ ] handleError() - manejo de errores y reintentos + +## Fase 6: Job Programado + +### 6.1 Cron Job +- [ ] Crear `apps/api/src/jobs/sat-sync.job.ts` +- [ ] Configurar ejecución a las 3:00 AM +- [ ] Obtener tenants con FIEL activa +- [ ] Ejecutar sync para cada tenant +- [ ] Logging y monitoreo + +### 6.2 Dependencias +- [ ] Instalar node-cron + +## Fase 7: API Endpoints + +### 7.1 Controlador FIEL +- [ ] Crear `apps/api/src/controllers/fiel.controller.ts` +- [ ] POST /upload - subir credenciales +- [ ] GET /status - obtener estado +- [ ] DELETE / - eliminar credenciales + +### 7.2 Controlador SAT +- [ ] Crear `apps/api/src/controllers/sat.controller.ts` +- [ ] POST /sync - iniciar sincronización manual +- [ ] GET /sync/status - estado actual +- [ ] GET /sync/history - historial +- [ ] GET /sync/:id - detalle de job +- [ ] POST /sync/:id/retry - reintentar + +### 7.3 Rutas +- [ ] Crear `apps/api/src/routes/fiel.routes.ts` +- [ ] Crear `apps/api/src/routes/sat.routes.ts` +- [ ] Registrar en app.ts + +## Fase 8: Frontend + +### 8.1 Componentes +- [ ] Crear `apps/web/components/sat/FielUploadModal.tsx` +- [ ] Crear `apps/web/components/sat/SyncStatus.tsx` +- [ ] Crear `apps/web/components/sat/SyncHistory.tsx` + +### 8.2 Página de Configuración +- [ ] Crear `apps/web/app/(dashboard)/configuracion/sat/page.tsx` +- [ ] Integrar componentes +- [ ] Conectar con API + +### 8.3 API Client +- [ ] Agregar métodos en `apps/web/lib/api.ts` +- [ ] uploadFiel() +- [ ] getFielStatus() +- [ ] deleteFiel() +- [ ] startSync() +- [ ] getSyncStatus() +- [ ] getSyncHistory() + +## Fase 9: Testing y Validación + +### 9.1 Tests +- [ ] Tests unitarios para servicios de criptografía +- [ ] Tests unitarios para parser de XML +- [ ] Tests de integración para flujo completo +- [ ] Test con FIEL de prueba del SAT + +### 9.2 Validación +- [ ] Probar carga de FIEL +- [ ] Probar sincronización manual +- [ ] Probar job programado +- [ ] Verificar CFDIs descargados + +## Orden de Implementación + +``` +Fase 1 (BD) + │ + ▼ +Fase 2 (Crypto + FIEL) + │ + ▼ +Fase 3 (Auth + Download SAT) + │ + ▼ +Fase 4 (Parser) + │ + ▼ +Fase 5 (Orquestador) + │ + ▼ +Fase 6 (Cron Job) + │ + ▼ +Fase 7 (API) + │ + ▼ +Fase 8 (Frontend) + │ + ▼ +Fase 9 (Testing) +``` + +## Archivos a Crear/Modificar + +### Nuevos Archivos (16) +``` +apps/api/src/services/sat/sat-crypto.service.ts +apps/api/src/services/sat/sat-auth.service.ts +apps/api/src/services/sat/sat-download.service.ts +apps/api/src/services/sat/sat-parser.service.ts +apps/api/src/services/sat/sat.service.ts +apps/api/src/services/fiel.service.ts +apps/api/src/controllers/fiel.controller.ts +apps/api/src/controllers/sat.controller.ts +apps/api/src/routes/fiel.routes.ts +apps/api/src/routes/sat.routes.ts +apps/api/src/jobs/sat-sync.job.ts +packages/shared/src/types/sat.ts +apps/web/components/sat/FielUploadModal.tsx +apps/web/components/sat/SyncStatus.tsx +apps/web/components/sat/SyncHistory.tsx +apps/web/app/(dashboard)/configuracion/sat/page.tsx +``` + +### Archivos a Modificar (5) +``` +apps/api/prisma/schema.prisma +apps/api/src/app.ts +apps/api/src/index.ts +packages/shared/src/index.ts +apps/web/lib/api.ts +``` + +## Dependencias a Instalar + +```bash +# En apps/api +pnpm add @nodecfdi/credentials @nodecfdi/cfdi-core node-forge fast-xml-parser adm-zip node-cron + +# Tipos +pnpm add -D @types/node-forge @types/node-cron +``` + +## Estimación por Fase + +| Fase | Descripción | Complejidad | +|------|-------------|-------------| +| 1 | Base de datos | Baja | +| 2 | Crypto + FIEL | Media | +| 3 | Comunicación SAT | Alta | +| 4 | Parser | Media | +| 5 | Orquestador | Alta | +| 6 | Cron Job | Baja | +| 7 | API | Media | +| 8 | Frontend | Media | +| 9 | Testing | Media | +