consultoria-as/HoruxDespachosNuevo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b00b677c54ee54af8640bf1d265c67963085848c
HoruxDespachosNuevo/docs/plans/2026-04-23-features-fixes-y-derivados.md

15 KiB
Raw Blame History

Sesión 2026-04-23 — Cierre de features pending + derivados técnicos

Sesión extensa que cerró 4 features pending (#6 #7 #9 + investigación #10) y 3 derivados técnicos (#3 watchdog cron, #4 validación CSD, #5 logging SAT), además de 7 bugfixes descubiertos en el proceso.

1. Feature #6 — Enlazar obligaciones ↔ declaraciones (trazabilidad)

El backend del matching impuesto→obligación ya existía (completarObligacionesPorDeclaracion en declaraciones.service.ts hacía el UPSERT en obligacion_periodos). Faltaba la trazabilidad reversa: poder clickear una obligación completada y ver la declaración que la cubrió.

Migration 030 obligacion_periodos.declaracion_id INT REFERENCES declaraciones_provisionales(id) ON DELETE SET NULL + índice parcial.

Backend:

  • completarObligacionesPorDeclaracion ahora acepta declaracionId y lo persiste en el INSERT/UPDATE del ON CONFLICT.
  • createDeclaracion pasa declaracion.id tras el INSERT.
  • getObligacionesPorPeriodo hace LEFT JOIN declaraciones_provisionales y devuelve un objeto declaracion: DeclaracionLink | null por cada periodo completado (nuevo tipo exportado).

Frontend (/pendientes/page.tsx):

  • ObligacionPeriodo extendido con declaracion: DeclaracionLink | null.
  • Link ↗ Declaración MM/YYYY [Compl.] junto a obligaciones completadas con FK. Click abre PDF en nueva pestaña vía /documentos/declaraciones/:id/pdf/declaracion.

Semántica: ON DELETE SET NULL — el periodo sigue marcado completado si la declaración se borra, pero pierde la referencia. El usuario decide si reabrirlo.

2. Feature #7 — Calendario con colores por status

Backend + frontend ya estaban implementados end-to-end (tipos obligacion-pendiente|completada|atrasada generados desde obligacion_periodos, colores amber/green/red mapeados). Solo agregué 2 mejoras UX:

  • AlertTriangle icon para obligacion-atrasada (antes usaba el mismo Clock que pendiente).
  • Leyenda de colores visible en el header del grid del calendario: amber/green/red + violet (recordatorio custom).

3. Feature #10 — Alertas obligaciones per-contribuyente (investigado)

El bug reportado "las alertas manuales muestran más obligaciones de las que tiene el contribuyente" no se reproduce al 2026-04-23.

Auditoría SQL sobre los despachos activos:

  • 0 alertas ob-* con obligacion_id inexistente (huérfanas)
  • 0 alertas para obligaciones activa=false
  • 0 alertas para periodos ya completados
  • Count per-contribuyente: alertas ≤ obligaciones activas en todos los casos

Protecciones verificadas en código:

  1. removeObligacion hace soft-delete + DELETE alertas + DELETE periodos
  2. inactiveFilter en getAlertasManualesPendientes excluye por activa=false
  3. contribuyenteFilter strict previene leak cross-contribuyente
  4. sincronizarDesdeObligacionesContribuyente solo genera current + previous month

Probablemente fue arreglado implícitamente al agregar el cleanup en removeObligacion en una sesión anterior. Si reaparece el síntoma, hay que capturar el drift específico antes de tocar código.

4. Feature #9 — Emails al subir declaración / documento extra

Destinatarios: owners activos del despacho + supervisor del contribuyente (entidades_gestionadas.supervisor_user_id), excluyendo al uploader mismo.

Archivos:

  • services/email/templates/documento-subido.ts — nuevo, template parametrizable por kind: 'declaracion' | 'extra', con bloques condicionales para periodo/impuestos/monto (declaración) o nombre/categoría/descripción (extra). HTML escapado para evitar XSS.
  • services/email/email.service.ts:sendDocumentoSubido(recipients, data) — loop por recipient con try/catch individual.
  • utils/memberships.ts:
    • getTenantOwnerEmails(tenantId) — nuevo, lista todos los owners.
    • getUserEmailById(userId) — nuevo, resolver supervisor.
  • services/notify-upload.service.ts:notifyDocumentoSubido(...) — nuevo orquestador: resuelve recipients, dedupea, excluye uploader, envía.
  • controllers/documentos.controller.ts:
    • crearDeclaracion y crearExtra disparan notify con .catch() (fire-and-forget).

Dev mode: sin SMTP configurado, transport de @horux/core loguea a consola.

5. Bugfixes descubiertos en el camino

5.1 feature-gate.middleware.ts crash con planes despacho

hasFeature(plan) asumía PLANS[plan] siempre existe. Con planes business_cloud/ business_control (que viven en DESPACHO_PLANS, no PLANS) → undefined.features → crash del API. Fix en 2 capas:

  • Middleware ahora detecta plan despacho y rutea a hasDespachoFeature.
  • shared/constants/plans.ts:hasFeature defensive con ?. + ?? false.

5.2 Declaraciones sin filtro por contribuyente

declaraciones_provisionales no tenía columna contribuyente_id; todas las declaraciones se mezclaban entre RFCs de un despacho.

Migration 031 agrega contribuyente_id UUID NULL con ON DELETE SET NULL. Reemplaza el UNIQUE (año, mes) WHERE tipo='normal' por (año, mes, contribuyente_id) WHERE tipo='normal' para que cada RFC tenga su propia normal mensual.

Backend + controller + API client + hook + UI actualizados para pasar contribuyenteId end-to-end. Declaraciones legacy quedan con NULL (interpretadas como "tenant-wide / legacy") — invisibles cuando se filtra por un RFC específico.

5.3 completada_por UUID/email mismatch

obligacion_periodos.completada_por es UUID, pero createDeclaracion pasaba el email del usuario. Crash silencioso con invalid input syntax for type uuid: "jd@demo.com".

Separé en 2 campos:

  • creadoPor: string (email) — va a declaraciones_provisionales.creado_por VARCHAR.
  • creadoPorUserId: string (UUID) — va a obligacion_periodos.completada_por UUID.

5.4 Alertas de pago desaparecían al subir declaración normal con monto>0

La llamada a completarObligacionesPorDeclaracion se hacía SIEMPRE que hubiera contribuyenteId, incluyendo declaraciones normales cuyo pago aún está pendiente. Esto cerraba tanto alertas decl-* como ob-* (per-obligación), dejando al usuario sin visibilidad del pago pendiente.

Fix: completarObligacionesPorDeclaracion solo se llama si la declaración cubre el pago (tipo='complementaria' || montoPago=0). Además, uploadComprobantePago ahora también llama completarObligacionesPorDeclaracion para cerrar las obligaciones cuando se sube el comprobante de pago.

5.5 Keyword matching IVA → DIOT y mensual → anual

Subir una declaración con impuestos: ['IVA'] cerraba también obligaciones "Declaración de proveedores de IVA" (DIOT) y "Declaración anual de ISR" porque la sustring "iva"/"isr" matchaba demasiado amplio.

Fix doble:

  1. IMPUESTO_A_OBLIGACION_KEYWORDS ahora tiene include + exclude:
    • IVA: include=['iva'], exclude=['diot','proveedores de iva','informativa']
    • ISR: include=['isr'], exclude=['retenciones','asimilados a salarios']
  2. Filtro por periodicidad ↔ obligacion.frecuencia: una declaración mensual no cierra obligaciones anuales.

Datos revertidos en BD: 3 obligaciones que se habían marcado completadas por error (Husberto DIOT, Husberto anual ISR, Horux 360 anual ISR).

5.6 Drill-down: falta tipo E + columna Monto Pago

Los drill-downs desde dashboard/impuestos pasaban tipoComprobante: 'I,P' — excluían tipo E (notas de crédito), que sí entran en los cálculos de ingresos (NC recibida) y gastos (NC emitida).

Fix:

  • Nuevo param bucket en GET /cfdi/drill-down:
    • bucket=ingresos → (EMIT I PUE) + (EMIT P) + (RECIB E PUE)
    • bucket=gastos → (RECIB I PUE) + (RECIB P) + (EMIT E PUE)
    • Aliases causado/acreditable
  • 6 links en dashboard/impuestos migrados de type+tipoComprobante+metodoPago a bucket.
  • Nueva columna "Monto Pago" en la tabla drill-down — sortable, solo muestra valor para tipo P. Excel export incluye la columna.

6. Derivado #3 — Cron watchdog SAT

Refactoricé la lógica del script CLI scripts/sweep-stale-sat-jobs.ts a función exportable en services/sat/sweep-stale-jobs.service.ts:sweepStaleSatJobs.

El CLI ahora es un thin wrapper que reusa la función. El cron WATCHDOG_CRON_SCHEDULE = '0 */2 * * *' en sat-sync.job.ts llama sweepStaleSatJobs({ apply: true }) cada 2 horas. Thresholds vía env: STALE_PENDING_HOURS (default 12h) y STALE_RUNNING_HOURS (default 4h).

Gate del cron: usa el mismo cronsEnabled del index.ts (prod, o ENABLE_CRONS_IN_DEV=1).

7. Derivado #4 — Validación CSD↔RFC en uploadCsdContribuyente

Antes: el contador subía un CSD, Facturapi devolvía "Certificado no válido" sin decir por qué. Podría ser RFC mismatch, FIEL subida en lugar de CSD, o cert vencido.

Ahora uploadCsdContribuyente valida antes de subir a Facturapi usando @nodecfdi/credentials:

  1. Parseable + password correcta
  2. !credential.isFiel() — debe ser CSD, no FIEL
  3. certificate.rfc() === contribuyente.rfc (uppercase, strict)
  4. validToDateTime() > now — no vencido

Cada fallo tiene un mensaje específico. Facturapi sigue validando también; nuestra capa es defense-in-depth con diagnóstico mejor.

8. Derivado #5 — Investigación SAT rejections (logging mejorado)

La librería @nodecfdi/sat-ws-descarga-masiva expone verifyResult.getCodeRequest() con los 5 códigos SAT específicos del estado de la solicitud:

  • 5000 Accepted — solicitud recibida con éxito
  • 5002 Exhausted — agotadas solicitudes de por vida (mismos parámetros)
  • 5003 MaximumLimit — tope máximo de CFDI/Metadata
  • 5004 EmptyResult — no hay información en el rango
  • 5005 Duplicated — solicitud duplicada (existe una vigente con mismos params)

Antes verifySatRequest solo loggeaba getStatus().getCode() que es el HTTP-wrapper status (siempre 5000 "Aceptada" si la llamada HTTP funciona). Ahora también captura codeRequest.getValue() + getEntryId() + getMessage() en el debug log y en el error message cuando status es rejected/failed.

Patrón observado en Manuel (sin datos del nuevo log): 9 rejections de emitidos en bloques 3-9 + 12-13, pero 10-11 funcionaron. NO es rate-limit constante. Hipótesis más probable: 5005 Duplicated — solicitudes previas stale del SAT que interfieren con nuevas.

Acción pendiente: capturar un caso nuevo con el log mejorado para confirmar y decidir estrategia (limpiar solicitudes previas, esperar 72h entre intentos, reducir rangos, etc.).

Archivos tocados

Backend

  • apps/api/src/migrations/tenant/030_obligacion_periodos_declaracion_id.sql — nuevo (#6)
  • apps/api/src/migrations/tenant/031_declaraciones_contribuyente_id.sql — nuevo (fix 5.2)
  • apps/api/src/services/declaraciones.service.ts — completarObligacionesPorDeclaracion con declaracionId + periodicidad filter + include/exclude keywords; createDeclaracion con creadoPorUserId; listDeclaraciones con contribuyenteId filter; uploadComprobantePago llama completar obligaciones
  • apps/api/src/services/obligaciones.service.ts — getObligacionesPorPeriodo con LEFT JOIN declaraciones + tipo DeclaracionLink
  • apps/api/src/controllers/documentos.controller.ts — listarDeclaraciones lee contribuyenteId; crearDeclaracion/crearExtra disparan notify; subirComprobantePago pasa uploadedByUserId
  • apps/api/src/services/email/templates/documento-subido.ts — nuevo (#9)
  • apps/api/src/services/email/email.service.ts — sendDocumentoSubido
  • apps/api/src/utils/memberships.ts — getTenantOwnerEmails, getUserEmailById
  • apps/api/src/services/notify-upload.service.ts — nuevo (#9 orquestador)
  • apps/api/src/middlewares/feature-gate.middleware.ts — ruteo catálogo despacho/Horux 360 (fix 5.1)
  • packages/shared/src/constants/plans.ts — hasFeature defensive
  • apps/api/src/controllers/cfdi.controller.ts — nuevo param bucket en drillDown (fix 5.6)
  • apps/api/src/services/sat/sweep-stale-jobs.service.ts — nuevo (#3)
  • apps/api/src/jobs/sat-sync.job.ts — cron watchdog cada 2h (#3)
  • apps/api/scripts/sweep-stale-sat-jobs.ts — refactorizado a thin CLI wrapper (#3)
  • apps/api/src/services/contribuyente-facturapi.service.ts — uploadCsdContribuyente con validaciones pre-Facturapi (#4)
  • apps/api/src/services/sat/sat-client.service.ts — verifySatRequest expone codeRequest (#5)

Frontend

  • apps/web/app/(dashboard)/pendientes/page.tsx — tipo DeclaracionLink + link ↗ (#6)
  • apps/web/app/(dashboard)/calendario/page.tsx — ícono AlertTriangle + leyenda (#7)
  • apps/web/app/(dashboard)/dashboard/page.tsx — drill links usan bucket (fix 5.6)
  • apps/web/app/(dashboard)/impuestos/page.tsx — drill links usan bucket (fix 5.6)
  • apps/web/app/(dashboard)/drill-down/page.tsx — columna "Monto Pago" + sort (fix 5.6)
  • apps/web/app/(dashboard)/documentos/page.tsx — DeclaracionesTab pasa selectedContribuyenteId (fix 5.2)
  • apps/web/lib/api/declaraciones.ts — listDeclaraciones con contribuyenteId (fix 5.2)
  • apps/web/lib/hooks/use-declaraciones.ts — hook con contribuyenteId (fix 5.2)

Documentación

  • docs/plans/2026-04-19-pending-features.md — 4 secciones marcadas ✅ (#6 #7 #9 #10)
  • docs/plans/2026-04-22-pendientes-y-addons.md — derivados actualizados con #3 #4 #5
  • docs/plans/2026-04-23-features-fixes-y-derivados.md — este doc

Data directa

  • Zorro + Patito: UPDATE obligacion_periodos para revertir 3 filas completadas por error (DIOT + 2 anuales de ISR) — sus alertas ob-* reabiertas.
  • Declaraciones legacy con contribuyente_id=NULL se dejaron como están (test data, no se eliminaron).

Migrations aplicadas a tenants

  • 030_obligacion_periodos_declaracion_id (Zorro, Patito)
  • 031_declaraciones_contribuyente_id (Zorro, Patito)

Pendientes al cierre

Features pending (de 2026-04-19) — solo queda 1 abierto

  • #2 Convertir /pendientes → "Despacho" con métricas cross-contribuyente.

Derivados abiertos — 10

Prioridad Derivado
Alta Cloudflare Tunnel en prod para MP_NOTIFICATION_URL
Alta Recrear org Facturapi de Carlos (TORC9611214CA)
Media Prueba cross-contribuyente end-to-end
Media Re-sync custom de rangos emitidos de Manuel (depende de capturar codeRequest nuevo)
Baja Recomputar overage al cambiar de plan
Baja FRONTEND_URL dev HTTPS permanente
Baja Typecheck web cleanup (~12 errores)
Baja Declaraciones legacy con contribuyente_id=NULL
Baja Flag por despacho para activar/desactivar emails
Baja Email para declaraciones sin contribuyenteId

Cerrados hoy: #3 watchdog cron, #4 validación CSD, #5 logging SAT, 6 bugfixes.

Reference in New Issue View Git Blame Copy Permalink