# Contraseñas de pago (pendiente de definir)

Estado: **sin implementar**. No existe nada en el código (entidades, plantillas, migraciones, traducciones).
Se pidió "crearlo", pero todavía no está claro qué es. Este documento recoge lo que se sabe para retomarlo.

## Qué se pidió

Lista de mejoras del 21/10/2026: "contraseñas de pago (eso falta) creemos esa parte".
El 23/10/2026 se confirmó que todavía no está claro a qué se refiere y se pidió dejarlo documentado para resolverlo luego.

## Interpretaciones posibles

1. **Contra-recibo (la más probable).** En Guatemala (y México) es el comprobante que la empresa entrega al proveedor
   cuando recibe sus facturas, con un número y la fecha en que se le pagará. El proveedor lo presenta para cobrar.
   Encaja con el flujo de CxP: facturas recibidas -> contraseña -> pago.
2. **Clave de autorización de pagos.** Una contraseña/PIN que un usuario debe digitar para autorizar o ejecutar un pago
   (aprobación de pagos). No tiene relación con documentos ni proveedores.
3. **Otra cosa propia del cliente** (formato interno, lote de pagos, etc.).

La búsqueda web no encontró una definición estándar de "contraseña de pago"; la interpretación 1 es una inferencia.

## Preguntas que hay que responder antes de construirlo

1. ¿Es el contra-recibo (interpretación 1) o algo distinto? Pedir a quien lo solicitó un ejemplo en papel.
2. ¿Una contraseña cubre varias facturas del mismo proveedor, o una por factura?
3. ¿La fecha de pago se calcula (días de crédito del proveedor/condición de pago), sigue un calendario fijo
   (p. ej. "pagamos los jueves") o se escribe a mano?
4. ¿Numeración correlativa por cliente/sitio? ¿Con prefijo?
5. ¿Qué formato de impresión lleva (carta, media carta, logo, firma de quien recibe)? ¿Debe usar el diseñador de formatos?
6. ¿Al emitirla se bloquea la factura (como el bloqueo de documentos existente) o es solo informativa?
7. ¿Debe enlazarse al pago/voucher cuando se pague y mostrar su número?
8. ¿Qué roles pueden emitirla y anularla?

## Diseño propuesto (si es el contra-recibo)

Patrón a copiar: `PagoVoucher` (cabecera + detalle, numeración `VCH-%06d`, estado, auditoría), `PagoVoucherController`
y `templates/pago_voucher/*`.

- **Entidad `ContrasenaPago`** (tabla `contrasenas_pago`, por sitio como `PagoVoucher`): cliente, sitio, proveedor,
  número (`CTP-%06d`, único por cliente), fecha de emisión, fecha de pago programada, moneda, total,
  estado (`emitida`, `pagada`, `anulada`), observaciones, pago_id opcional, creado por/en.
- **Entidad `ContrasenaPagoDetalle`** (tabla `contrasenas_pago_detalles`): contraseña, documento (`SET NULL`),
  snapshot de serie, número, fecha y monto, orden.
- **Reglas:** solo documentos del mismo proveedor con saldo > 0; un documento no puede estar en dos contraseñas vigentes;
  fecha de pago sugerida = fecha de recepción + días de la `CondicionPago`.
- **Pantallas:** `/contrasenas` (lista), nueva (elegir proveedor y facturas pendientes), detalle, impresión, anulación.
  Entrada en el menú (`templates/layouts/_sidebar.html.twig`), permisos en `PermissionCheckSubscriber::MODULE_MAP`
  y en la matriz de permisos del formulario de usuarios.
- **Servicio `ContrasenaPagoService`:** generar número, validar documentos, auditoría.

## Riesgo técnico: tablas nuevas en bases por cliente

`app:tenant:repair-all` (que corre `deploy.sh`) solo agrega columnas/índices a tablas que ya existen en cada tenant
(`TenantSchemaRepairer::TABLES`); **no crea tablas**. Los tenants nuevos sí clonan las tablas desde la base central
(`TenantDatabaseProvisioner::syncMissingTablesFromMaster`). Para tablas nuevas hay que extender el reparador para que
cree las que falten desde `SHOW CREATE TABLE` de la base central. Lo mismo aplica a cualquier otra tabla nueva
(por ejemplo `dashboard_tarjetas`).

## Si resulta ser la interpretación 2 (autorización de pagos)

Sería otro diseño: aprobación en dos pasos del pago (usuario autorizador + clave), con estados `pendiente_aprobacion` /
`aprobado` en `Pago` y permisos por rol. Definirlo con el cliente antes de tocar código.