feat(sat): reporte diario de errores SAT por proxy

- Agrega tabla sat_proxy_errors con proxy_usado, error_code, stage, message. - sat-client.service.ts expone proxyInfo usado en cada conexión SAT. - sat.service.ts registra errores de bloqueo/devolución del SAT en sat_proxy_errors y guarda proxyUsed en sat_sync_jobs. - Nuevo job sat-proxy-report.job.ts: cron 8 AM CDMX, envía email a ADMIN_EMAIL con errores de las últimas 24h agrupados por proxy/error_code. - Template de email sat-proxy-report.ts y método sendSatProxyReport. - Registra el cron en src/index.ts. - Actualiza docs/SAT-SYNC-IMPLEMENTATION.md.
2026-08-03 14:27:19 +00:00
parent 3de0014e80
commit 099f34c903
57 changed files with 4554 additions and 7 deletions
--- a/apps/api/src/services/email/email.service.ts
+++ b/apps/api/src/services/email/email.service.ts
@@ -50,6 +50,11 @@ export const emailService = {
    await sendEmail(to, `🚨 Alerta SAT: ${total} anomalía${total === 1 ? '' : 's'} detectada${total === 1 ? '' : 's'}`, satSyncAlertEmail(data));
  },

+  sendSatProxyReport: async (to: string, data: import('./templates/sat-proxy-report.js').SatProxyReportData) => {
+    const { satProxyReportEmail } = await import('./templates/sat-proxy-report.js');
+    await sendEmail(to, `📊 Reporte diario SAT: ${data.totalErrors} errores por proxy`, satProxyReportEmail(data));
+  },
+
  sendSubscriptionExpiring: async (to: string, data: { nombre: string; plan: string; expiresAt: string }) => {
    const { subscriptionExpiringEmail } = await import('./templates/subscription-expiring.js');
    await sendEmail(to, 'Tu suscripción vence en 5 días', subscriptionExpiringEmail(data));
--- a/apps/api/src/services/email/templates/sat-proxy-report.ts
+++ b/apps/api/src/services/email/templates/sat-proxy-report.ts
@@ -0,0 +1,63 @@
+import { baseTemplate, heading, infoBox, BRAND_COLORS as C } from './base.js';
+
+export interface ProxyErrorRow {
+  proxy: string;
+  errorCode: string;
+  count: number;
+}
+
+export interface SatProxyReportData {
+  generatedAt: string;
+  recipient: string;
+  dateFrom: string;
+  dateTo: string;
+  totalErrors: number;
+  byProxy: ProxyErrorRow[];
+}
+
+function tableHeader(cells: string[]): string {
+  return `<tr>
+    ${cells.map(c => `<th align="left" style="padding:8px 12px;background-color:${C.bgLight};color:${C.textMuted};font-size:12px;font-weight:500;text-transform:uppercase;letter-spacing:0.04em;border-bottom:1px solid ${C.border};">${c}</th>`).join('')}
+  </tr>`;
+}
+
+function tableRow(cells: string[]): string {
+  return `<tr>
+    ${cells.map(c => `<td style="padding:10px 12px;border-bottom:1px solid ${C.border};color:${C.textPrimary};font-size:13px;vertical-align:top;">${c}</td>`).join('')}
+  </tr>`;
+}
+
+export function satProxyReportEmail(data: SatProxyReportData): string {
+  const rowsHtml = data.byProxy.length > 0
+    ? data.byProxy.map(r => tableRow([
+        r.proxy ? `<code style="font-size:12px;">${r.proxy}</code>` : '<span style="color:#dc2626;">IP directa del servidor</span>',
+        r.errorCode || '—',
+        `<strong>${r.count}</strong>`,
+      ])).join('')
+    : tableRow(['—', '—', '<span style="color:#16a34a;">Sin errores de bloqueo</span>']);
+
+  return baseTemplate(`
+    ${heading('📊 Reporte diario de errores SAT por proxy')}
+    <p style="color:${C.textPrimary};margin:0 0 16px;">
+      Resumen de errores de bloqueo/devolución del SAT en las últimas 24 horas,
+      agrupados por proxy/IP usada.
+    </p>
+    ${infoBox(`
+      <table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0">
+        <tr><td style="padding:6px 0;color:${C.textMuted};">Período</td><td style="padding:6px 0;color:${C.textPrimary};font-weight:600;text-align:right;">${data.dateFrom} → ${data.dateTo}</td></tr>
+        <tr><td style="padding:6px 0;color:${C.textMuted};">Errores totales</td><td style="padding:6px 0;color:${data.totalErrors > 0 ? '#dc2626' : '#16a34a'};font-weight:600;text-align:right;">${data.totalErrors}</td></tr>
+      </table>
+    `)}
+
+    <h3 style="font-family:'Inter', sans-serif;font-weight:600;color:${C.textPrimary};margin:28px 0 12px;font-size:16px;">Errores por proxy (${data.byProxy.length})</h3>
+    <table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0" style="border-collapse:collapse;">
+      <thead>${tableHeader(['Proxy / IP', 'Código', 'Cantidad'])}</thead>
+      <tbody>${rowsHtml}</tbody>
+    </table>
+
+    <p style="color:${C.textMuted};margin:24px 0 0;font-size:12px;">
+      Reporte generado el ${data.generatedAt} para ${data.recipient}.<br/>
+      Configura la lista de proxies con SAT_PROXY_LIST y la concurrencia con SAT_CONCURRENT_CONTRIBUYENTES.
+    </p>
+  `);
+}
--- a/apps/api/src/services/sat/sat-client.service.ts
+++ b/apps/api/src/services/sat/sat-client.service.ts
@@ -18,6 +18,12 @@ export interface FielData {
  password: string;
 }

+export interface ProxyInfo {
+  host: string;
+  port: number;
+  url: string;
+}
+
 /**
 * Timeout explícito para el cliente HTTP del SAT (ms).
 *
@@ -38,7 +44,7 @@ const SAT_WEB_CLIENT_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutos
 /**
 * Crea el servicio de descarga masiva del SAT usando los datos de la FIEL
 */
-export function createSatService(fielData: FielData): Service {
+export function createSatService(fielData: FielData): { service: Service; proxyInfo: ProxyInfo | null } {
  // Crear FIEL usando el método estático create
  const fiel = Fiel.create(fielData.cerContent, fielData.keyContent, fielData.password);

@@ -50,7 +56,8 @@ export function createSatService(fielData: FielData): Service {
  // Crear cliente HTTP con timeout explícito para evitar el bug de la librería
  // cuando ocurre un timeout de red. Si hay proxies configurados, se usa uno
  // del pool para reducir el riesgo de bloqueo por IP del SAT.
-  const proxyAgent = proxyManager.createNextAgent();
+  const proxy = proxyManager.getNextProxy();
+  const proxyAgent = proxy ? proxyManager.createAgent(proxy) : null;
  if (proxyAgent) {
    console.log('[SAT] Usando proxy para la conexión con el SAT');
  } else {
@@ -68,7 +75,11 @@ export function createSatService(fielData: FielData): Service {
  const requestBuilder = new FielRequestBuilder(fiel);

  // Crear y retornar el servicio
-  return new Service(requestBuilder, webClient, undefined, ServiceEndpoints.cfdi());
+  const service = new Service(requestBuilder, webClient, undefined, ServiceEndpoints.cfdi());
+  return {
+    service,
+    proxyInfo: proxy ? { host: proxy.host, port: proxy.port, url: proxy.url } : null,
+  };
 }

 export interface QueryResult {
--- a/apps/api/src/services/sat/sat.service.ts
+++ b/apps/api/src/services/sat/sat.service.ts
@@ -8,6 +8,7 @@ import {
  verifySatRequest,
  downloadSatPackage,
  type FielData,
+  type ProxyInfo,
 } from './sat-client.service.js';
 import { processPackage, processMetadataPackage, extractXmlsFromZip, type CfdiParsed, type CfdiMetadata } from './sat-parser.service.js';
 import { recomputarSaldoPendiente, uuidsAfectadosPorCfdi } from '../../utils/saldo.js';
@@ -91,6 +92,7 @@ function computeNextRetryAt(
 interface SyncContext {
  fielData: FielData;
  service: Service;
+  proxyInfo: ProxyInfo | null;
  rfc: string;
  tenantId: string;
  databaseName: string;
@@ -98,6 +100,33 @@ interface SyncContext {
  getPool: () => Promise<Pool>;
 }

+/**
+ * Registra un error de bloqueo/devolución del SAT junto con el proxy usado.
+ * Permite reportes diarios de errores por IP.
+ */
+async function recordSatProxyError(
+  jobId: string,
+  ctx: SyncContext,
+  errorCode: string | null,
+  stage: string,
+  message: string,
+): Promise<void> {
+  try {
+    const proxyUsed = ctx.proxyInfo ? `${ctx.proxyInfo.host}:${ctx.proxyInfo.port}` : null;
+    await prisma.satProxyError.create({
+      data: {
+        jobId,
+        proxyUsed,
+        errorCode,
+        stage,
+        message,
+      },
+    });
+  } catch (err: any) {
+    console.error('[SAT] Error guardando sat_proxy_error:', err.message);
+  }
+}
+
 /**
 * Actualiza el progreso de un job
 */
@@ -117,6 +146,7 @@ async function updateJobProgress(
    completedAt: Date;
    retryCount: number;
    nextRetryAt: Date;
+    proxyUsed: string | null;
  }>
 ): Promise<void> {
  await prisma.satSyncJob.update({
@@ -700,6 +730,7 @@ async function requestAndDownload(
        return { packageContents: [], totalCfdis: 0 };
      }
      if (/error no controlado/i.test(queryResult.message || '')) {
+        await recordSatProxyError(jobId, ctx, queryResult.statusCode || '404', stageIdForTimeout(label), queryResult.message || 'Error no controlado');
        if (isDaily) {
          // En daily no detenemos el job por un 404 transitorio del SAT; se
          // registra como no fatal para diagnóstico y se continúa.
@@ -709,6 +740,7 @@ async function requestAndDownload(
        console.warn(`[SAT] Rechazo transitorio del SAT (${label}): ${queryResult.message} — se reintentará`);
        throw new SatTransientError(stageIdForTimeout(label), queryResult.message);
      }
+      await recordSatProxyError(jobId, ctx, queryResult.statusCode || null, stageIdForTimeout(label), queryResult.message || 'Error SAT');
      throw new Error(`Error SAT (${label}): ${queryResult.message}`);
    }

@@ -735,6 +767,7 @@ async function requestAndDownload(
          console.log(`[SAT] Solicitudes agotadas de por vida (${label}); se cancela y se omite este rango.`);
          return { packageContents: [], totalCfdis: 0 };
        }
+        await recordSatProxyError(jobId, ctx, verifyResult.status, stageIdForTimeout(label), verifyResult.message || `Solicitud ${verifyResult.status}`);
        throw new Error(`Solicitud fallida (${label}): ${verifyResult.message}`);
      }
    }
@@ -1523,7 +1556,7 @@ export async function startSync(
    password: decryptedFiel.password,
  };

-  const service = createSatService(fielData);
+  const { service, proxyInfo } = createSatService(fielData);

  const tenant = await prisma.tenant.findUnique({
    where: { id: tenantId },
@@ -1564,12 +1597,14 @@ export async function startSync(
      dateTo: dateTo || now,
      startedAt: now,
      isCustomRange,
+      proxyUsed: proxyInfo ? `${proxyInfo.host}:${proxyInfo.port}` : null,
    },
  });

  const ctx: SyncContext = {
    fielData,
    service,
+    proxyInfo,
    rfc: decryptedFiel.rfc,
    tenantId,
    databaseName: tenant.databaseName,
@@ -1721,7 +1756,7 @@ export async function retryTimedOutJobs(): Promise<void> {
        continue;
      }

-      const service = createSatService({
+      const { service, proxyInfo } = createSatService({
        cerContent: decryptedFiel.cerContent,
        keyContent: decryptedFiel.keyContent,
        password: decryptedFiel.password,
@@ -1734,6 +1769,7 @@ export async function retryTimedOutJobs(): Promise<void> {
          password: decryptedFiel.password,
        },
        service,
+        proxyInfo,
        rfc: decryptedFiel.rfc,
        tenantId: job.tenantId,
        databaseName: job.tenant.databaseName,
@@ -1744,7 +1780,7 @@ export async function retryTimedOutJobs(): Promise<void> {
      // B: resetear startedAt al inicio de ESTE intento para que el watchdog
      // mida el intento actual (y no mate un retry legítimo por el startedAt
      // original del job). La política de retries se ancla a createdAt.
-      await updateJobProgress(job.id, { status: 'running', errorMessage: null as any, startedAt: new Date() });
+      await updateJobProgress(job.id, { status: 'running', errorMessage: null as any, startedAt: new Date(), proxyUsed: proxyInfo ? `${proxyInfo.host}:${proxyInfo.port}` : null });

      // Para jobs daily, intentamos retomar desde la última etapa completada.
      let resumeFromStage: string | undefined;
@@ -1890,7 +1926,7 @@ export async function continuePendingDailyRequests(): Promise<void> {
        continue;
      }

-      const service = createSatService({
+      const { service, proxyInfo } = createSatService({
        cerContent: decryptedFiel.cerContent,
        keyContent: decryptedFiel.keyContent,
        password: decryptedFiel.password,
@@ -1903,6 +1939,7 @@ export async function continuePendingDailyRequests(): Promise<void> {
          password: decryptedFiel.password,
        },
        service,
+        proxyInfo,
        rfc: decryptedFiel.rfc,
        tenantId: job.tenantId,
        databaseName: job.tenant.databaseName,