ADR — Confirmación automática de cobros y pagos¶
Registro de decisiones de arquitectura y diseño del módulo. Formato ligero: una entrada por decisión, con contexto, decisión y consecuencias. Los detalles y la evidencia viven en los docs 01–04; acá está el qué se decidió y por qué, en un solo lugar.
| # | Fecha | Decisión | Estado |
|---|---|---|---|
| ADR-01 | 2026-08-04 | Alcance: solo transferencias bancarias | Aceptada |
| ADR-02 | 2026-08-04 | Log de matcheos en archivo JSONL append-only | Aceptada |
| ADR-03 | 2026-08-04 | Rollout en dos etapas con modo sombra | Aceptada |
| ADR-04 | 2026-08-04 | Auto-confirmación conservadora: monto único + identidad | Aceptada |
| ADR-05 | 2026-08-06 | Confirmación con cliente técnico + marca [auto] obligatoria |
Aceptada |
| ADR-06 | 2026-08-07 | QR eliminado del alcance | Aceptada |
| ADR-07 | 2026-08-07 | Registro de cuentas pagadoras: al margen, solo post-confirmación | Aceptada |
| ADR-08 | 2026-08-07 | Campos nativos primero; UDFs solo sin slot nativo | Aceptada |
| ADR-09 | 2026-08-07 | Normalización en el proveedor; mapeo SAP en el servicio | Aceptada |
| ADR-10 | 2026-08-07 | Nomenclatura de UDF: U_PayerName sin prefijo |
Aceptada |
| ADR-11 | 2026-08-04 | Sin re-sync retroactivo del histórico | Propuesta |
ADR-01 — Alcance: solo transferencias bancarias¶
Contexto: los cobros llegan por transferencia, efectivo, cheque, tarjetas/QR. Decisión: el matcheo automático cubre solo transferencias (cobros y pagos a proveedores) contra cuentas Continental integradas por API. Efectivo no pasa por extracto; cheques se procesan en SAP sin pasar por el OMS; Bancard tiene su circuito. Consecuencia: el universo de candidatos es 1:1 movimiento↔solicitud; los depósitos por ventanilla nunca entran al matcher.
ADR-02 — Log de matcheos en archivo JSONL¶
Contexto: el backend no tiene BD propia (Redis=caché, Firebase=comentarios); se evaluó UDT en SAP, Firebase e híbrido. Decisión: archivo JSONL append-only en el servidor, rotación diaria, una entrada por decisión del matcher (no solo por match), con ambos lados de cada comparación. Consecuencia: cero infra nueva; el log es a la vez auditoría, instrumento de medición del modo sombra y barrera de idempotencia. Migrar a otro almacenamiento queda fuera de esta etapa. (Spec: RF-22..25.)
ADR-03 — Rollout con modo sombra¶
Contexto: un falso positivo crea un pago contable real firmado por el sistema.
Decisión: dos modos (shadow/active); en sombra el matcher decide y registra
pero no confirma; el pasaje a activo exige precisión medida contra lo que el operador
confirmó a mano, con criterio de salida acordado con contabilidad (TBD-12).
Consecuencia: el sistema se valida con datos reales sin riesgo contable; los
TBD-05/07/12 se cierran con los contadores del propio modo sombra.
ADR-04 — Auto-confirmación conservadora¶
Contexto: el monto exacto solo no identifica al pagador (colisiones mismo día). Decisión: se auto-confirma únicamente con (1) candidato único por monto exacto en la ventana, (2) respaldo de identidad — RUC/CI (D1) o nombre exacto (D2) —, y (3) unicidad bilateral draft↔BankPage. Monto único sin identidad ⇒ sugerencia. Montos parciales (1↔N) quedan siempre en flujo manual. Consecuencia: menor cobertura inicial a cambio de precisión; el modo sombra dirá si puede relajarse. (Spec: RF-12.)
ADR-05 — Cliente técnico + marca [auto]¶
Contexto: la confirmación corre desde procesos de fondo sin sesión de usuario;
verificado que el batch funciona con SYSTEM_SAP_CLIENT pero IncomingPayments no
expone el firmante vía Service Layer.
Decisión: confirmar con el cliente técnico y marcar obligatoriamente el pago
con [auto] + id de la entrada del log en Remarks.
Consecuencia: todo pago automático es distinguible y trazable hasta su evidencia
completa; la reversa sigue siendo competencia de contabilidad en SAP (patrón Def. 5
de pagos-proveedores).
ADR-06 — QR eliminado del alcance¶
Contexto: se hipotetizó el QR del ticket como clave exacta; el piloto mostró que
solo 1/12 tickets lo trae, y que 3/12 imprimen la referencia SIPAP en texto.
Decisión: sin decodificación de QR; la referencia SIPAP se busca como texto en la
extracción de imagen (D4) y se cruza contra PaymentReference.
Consecuencia: menos dependencias (sin librería de decodificación), misma clave
exacta donde existe; intra-Continental nunca la tuvo y no la necesita.
ADR-07 — Registro de cuentas pagadoras al margen¶
Contexto: la cuenta origen permitiría matchear pagadores terceros recurrentes,
pero implica escribir asociaciones cuenta→cliente.
Decisión: mecanismo complementario fuera del núcleo (doc 03): se alimenta solo
tras una confirmación con evidencia independiente (nunca desde sugerencias ni desde
la imagen; un match por cuenta registrada no se realimenta); regla D6 futura, fuerte
solo con asociación unívoca + N≥2; almacenamiento propio del OMS primero,
BPBankAccounts diferido a decisión de contabilidad.
Consecuencia: cero riesgo de envenenar el registro con errores de matcheo; cero
escritura de datos maestros sin gobernanza.
ADR-08 — Campos nativos primero¶
Contexto: los datos estructurados necesitan destino en SAP; había columnas
estándar libres y la opción UDF.
Decisión: usar nativos donde la entidad lo soporte, verificado con E2E real:
PaymentReference (ref SIPAP, filtrable), InvoiceNumberEx (tipoDetalle),
StatementNumber como HHMMSS (hora), BICSwiftCode (SWIFT), CounterReference
en el draft (ref SIPAP de la imagen, sobrevive a la conversión). UDFs solo donde no
hay slot: nombre, RUC/CI y cuenta del pagador. Descartados con prueba:
Reference1 (SAP lo pisa con el DocNum al confirmar) y PaymentReferenceNo (corto);
InvoiceNumber==InvoiceNumberEx (un solo slot).
Consecuencia: mínima superficie de UDFs; los UDFs de OBNK no son filtrables por
OData → el matcher compara en memoria. (Detalle: doc 04.)
ADR-09 — Normalización en el proveedor, mapeo en el servicio¶
Contexto: el contrato IBankStatementProvider solo transportaba un string y las
rarezas de formato de Continental (año 2/4 dígitos, mojibake, ceros) contaminarían el
servicio común.
Decisión: contratos ampliados con campos estructurados (doc 04 §B½); el proveedor
normaliza lo específico del banco, el servicio de conciliación compone Memo/columnas/
UDFs de SAP. El detalle deja de reemplazar el description (fix del bug).
Consecuencia: el factory sigue agnóstico — un banco futuro solo implementa la
interfaz; movimientos sin detalle consultable se persisten igual con UDFs null.
ADR-10 — Nomenclatura U_PayerName¶
Contexto: los UDFs de verificación se crearon con prefijo provisorio U_OMS_*.
Decisión: el campo del nombre del ordenante se llama U_PayerName (espejo en
draft/pago y BankPage). En la base de prueba quedaron los provisorios; en producción
se crean con el nombre definitivo.
Consecuencia: ver nota de artefactos del doc 04 para no confundir al implementar.
ADR-11 — Sin re-sync retroactivo (propuesta)¶
Contexto: las BankPages históricas no tienen campos estructurados; el banco limita el rango consultable y las viejas ya fueron conciliadas a mano. Decisión propuesta: matcheo y persistencia estructurada solo hacia adelante. Estado: pendiente de confirmación con contabilidad (P-03 de la spec).