Plan estructurado: Retenciones fiscales (Honduras) — documento tipo 05 y pagos

1. Objetivo

Implementar el comprobante de retención como documento fiscal tipo 05, con líneas que vinculan factura origen + tipo de retención, integrado al panel de pagos (CxC y CxP), sin copia desde/hacia 05, trazabilidad contable, y comportamiento distinto en compras vs ventas respecto a CAI y numeración.

2. Alcance y principios

Principio	Detalle
Cabecera fiscal	Document con type = '05' (Honduras / SAR).
Líneas	Solo Opción A: DocumentLine ampliado (sin tabla puente ni tabla hija para líneas de retención).
Pagos	DocumentPayment.withholdingDocumentId → Documents.id donde type = '05' (mismo patrón que creditNoteId).
Tipos de retención	Tabla WithholdingTypes (por empresa).
Copia	Prohibido copiar desde o hacia 05.

---

3. Compras vs ventas — CAI y numeración (regla clave)

Un mismo tipo de cabecera 05, pero dos regímenes según el contexto (ver discriminación en §4):

3.1 Compras (nosotros retenemos al proveedor)

• El comprobante de retención se emite con el CAI y numeración del sistema (igual que otros documentos fiscales propios).
• Flujo estándar: DocumentRange + Cai, correlativo interno, validación de rango agotado, etc.
• Las líneas del 05 referencian facturas de compra (p. ej. tipos 103, 104, 11… según el catálogo actual de compras).

3.2 Ventas (el cliente nos retiene a nosotros)

• No se consume CAI propio del sistema para ese comprobante: es un registro del comprobante que nos entrega el cliente.
• En cabecera se ingresa manualmente el número de documento (y datos adicionales que el negocio exija en UI: fecha del comprobante del cliente, etc., si aplica).
• Campos técnicos sugeridos (reutilizar o ampliar Document):
  • Number: almacena el número fiscal que entrega el cliente (texto validado según formato acordado).
  • caiId / documentRangeId: null (o no asignar rango para este subcaso).
• Las líneas del 05 referencian facturas de venta (p. ej. 01, 113, etc.).

3.3 Validación de mezcla

• En un mismo documento 05, no permitir líneas que mezclen facturas de compra y venta; el contexto del documento se infiere de la primera factura elegida o se fija explícitamente al iniciar el documento (recomendado: campo explícito withholdingContext = purchase | sales en Document solo para type = '05', para simplificar UI y reglas CAI).

---

4. Modelo de líneas — únicamente Opción A (DocumentLine ampliado)

No se implementa tabla puente pago–línea ni tabla alternativa de líneas de retención.

Cada aplicación de retención es una fila en DocumentLines del documento padre 05:

Dato	Dónde
Factura a la que aplica	DocumentLine.sourceDocumentId
Tipo de retención	DocumentLine.withholdingTypeId → WithholdingTypes
Base usada (snapshot)	DocumentLine.withholdingBaseAmount
Monto retenido	total / subtotal de la línea (convención única acordada con el motor de documentos)

Ventajas: un solo modelo para Jasper, totales y pagos; alineado con NC.
Requisito: validaciones e inventario desactivados para líneas de documentos 05 (productId null).

---

5. Reglas de negocio (resumen)

1. Cada línea: seleccionar factura + tipo de retención; cálculo según catálogo (percentageBase, % o fijo).
2. Total cabecera 05 = suma de líneas.
3. Pagos: neto + retención referenciada no excede saldo pendiente (misma línea que validaciones actuales).
4. Compras: obligatorio CAI del sistema al confirmar 05.
5. Ventas: obligatorio número de documento ingresado (comprobante del cliente); sin asignación de CAI propio.
6. Listas de tipos en empresa / rangos: tipo 05 para compras (CAI); en ventas la UI no debe exigir selección de rango interno.

---

6. Modelo de datos (checklist)

• WithholdingTypes: name, calculationMode, percentageBase, rate, fixedAmount, isActive, timestamps (alcance interno por empresa).
• Documents (tipo 05):
  • Opcional withholdingContext: 'purchase' | 'sales' (recomendado) para ramificar CAI vs número externo.
  • Ventas: Number = número entregado por el cliente; sin caiId/documentRangeId (o nulos).
  • Compras: numeración y CAI como hoy en documentos fiscales propios.
• DocumentLines: withholdingTypeId, withholdingBaseAmount; sourceDocumentId = factura; productId null en 05.
• DocumentPayments: withholdingDocumentId (nullable); opcional withholdingAmount.
• Asociaciones en Backend/src/models/index.js.
• Sin tabla puente de asignación pago–línea en este plan.

---

7. Pasos de implementación (orden sugerido)

Fase 0 — Preparación

• [ ] 0.1 Constante DOCUMENT_TYPE_WITHHOLDING = '05' + enum/contexto purchase | sales.
• [ ] 0.2 Listas CAI / tipos documento: incluir 05 para emisión propia (compras); documentar que en ventas no se usa rango interno.

Fase 1 — Catálogo WithholdingTypes

• [ ] 1.1 Migración + modelo + CRUD API.
• [ ] 1.2 UI configuración.

Fase 2 — Documento 05 (cabecera y líneas)

• [ ] 2.1 Migración: columnas en DocumentLines + campo cabecera withholdingContext (si se adopta).
• [ ] 2.2 Backend: ramas compra (CAI/rango obligatorio) vs venta (solo número externo, sin CAI sistema).
• [ ] 2.3 Validaciones líneas: sourceDocumentId + withholdingTypeId; coherencia factura↔contexto (solo compras o solo ventas); sin inventario.
• [ ] 2.4 Bloqueo de copia hacia/desde 05.
• [ ] 2.5 Frontend Frontend/components/document/DocumentDrawer.tsx: flujo 05 (contexto → cabecera compra vs venta → líneas factura + tipo retención).

Fase 3 — Pagos

• [ ] 3.1 Migración DocumentPayment.withholdingDocumentId (+ opcional withholdingAmount).
• [ ] 3.2 documentPaymentController.js + includes.
• [ ] 3.3 Frontend/components/document/DocumentPayments.tsx: UI análoga a NC.

Fase 4 — Contabilidad e impresión

• [ ] 4.1 Asientos y reversión (documentAccountingService.js).
• [ ] 4.2 Jasper / PDF 05 (líneas: factura, tipo, base, monto); variante impresión según compra (CAI propio) vs venta (referencia a comprobante del cliente).

Fase 5 — Pruebas y cierre

• [ ] 5.1 Casos: 05 compra con CAI; 05 venta solo con número cliente; pagos; cancelaciones; sin mezcla de líneas compra/venta.

---

8. Riesgos y dependencias

• Formato y longitud del número en ventas: validación flexible (string) según lo que entregue el cliente.
• DTE / futuro: si HN migra a esquemas electrónicos, revisar si el registro en ventas sigue siendo solo número o requiere JSON adicional.

---

9. Criterios de aceptación (mínimos)

• Compra: 05 confirmado con correlativo y CAI del sistema; líneas con facturas de compra.
• Venta: 05 guardado con número ingresado del comprobante del cliente, sin CAI interno; líneas con facturas de venta.
• Pagos con withholdingDocumentId correctos; sin copia desde/hacia 05.
• Impresos coherentes con cada subcaso.

---

Plan actualizado: compras = CAI sistema; ventas = solo número de documento del cliente; arquitectura solo Opción A (DocumentLine ampliado, sin tabla puente).