From 3763014eca40c1d36fdb2246f3f4281c5f8ea5d0 Mon Sep 17 00:00:00 2001 From: Consultoria AS Date: Sun, 25 Jan 2026 00:36:53 +0000 Subject: [PATCH] docs: add SAT sync implementation plan Detailed implementation plan with 9 phases: 1. Database models and migrations 2. Cryptography and FIEL services 3. SAT communication services 4. CFDI XML parser 5. Main orchestrator service 6. Scheduled cron job 7. API endpoints 8. Frontend components 9. Testing and validation Includes: - 16 new files to create - 5 files to modify - Dependencies list - Implementation order Co-Authored-By: Claude Opus 4.5 --- .../2026-01-25-sat-sync-implementation.md | 228 ++++++++++++++++++ 1 file changed, 228 insertions(+) create mode 100644 docs/plans/2026-01-25-sat-sync-implementation.md 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 | +