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 <noreply@anthropic.com>
This commit is contained in:
Consultoria AS
228
docs/plans/2026-01-25-sat-sync-implementation.md
Normal file
228
docs/plans/2026-01-25-sat-sync-implementation.md
Normal file
@@ -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 |
|
||||||
|
|
||||||
Reference in New Issue
Block a user