HoruxDespachos/docs/plans/2026-01-25-sat-sync-implementation.md

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

# 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