FactuGES_ERP/docs/catalogs/payment-methods-design.md

Payment Methods Backend Design

Scope

PaymentMethod es un catálogo company-scoped del módulo catalogs.

Shape

Campos persistidos y expuestos para administración:

• id
• company_id
• name
• description
• is_active
• is_system
• is_default
• system_key
• created_at
• updated_at
• deleted_at

System vs custom

Reglas:

• is_system = true implica system_key != null
• is_system = false implica system_key = null
• is_system = true no se puede editar, desactivar ni eliminar

Identidad estable de métodos del sistema:

• cash
• bank_transfer
• card
• direct_debit

Active and default

Reglas:

• is_default = true implica is_active = true
• un método default no se puede desactivar
• un método default no se puede eliminar
• el cambio de default solo se realiza mediante PATCH /catalogs/payment-methods/:payment_method_id/default

La unicidad del default se garantiza mediante servicio transaccional y bloqueo por empresa. No se fuerza con constraint SQL adicional para evitar una solución opaca en MariaDB.

Bootstrap

Endpoint explícito e idempotente:

• POST /catalogs/payment-methods/bootstrap-system

Comportamiento:

• crea los cuatro métodos del sistema que falten
• restaura un system method soft-deleted si ya existía por system_key
• resincroniza name, is_system, is_active, is_default = false y system_key
• si la empresa no tiene default, establece cash como default inicial

Métodos creados:

• Efectivo
• Transferencia bancaria
• Tarjeta
• Domiciliación bancaria

Delete policy

Un método solo puede eliminarse si:

• is_system === false
• is_default === false
• no está referenciado por consumidores vivos

Bloqueos actuales:

• customers.payment_method_id
• proformas.payment_method_id
• supplier_invoices.payment_method_id

No se bloquea por issued_invoices, porque ese módulo mantiene snapshot histórico suficiente del método de pago emitido.

Reference protection

La arquitectura ideal sería mediante public services consumidores, pero catalogs ya es dependencia de customers y customer-invoices. Para evitar un ciclo de módulos, la protección referencial se implementa en catalogs con un checker de infraestructura específico contra los modelos registrados en Sequelize.

Consumers

Consumidores actuales auditados:

• customers
• customer-invoices/proformas
• customer-invoices/issued-invoices
• supplier-invoices
• factuges

factuges no bloquea delete porque resuelve métodos de pago durante la importación y no mantiene una referencia persistente viva auditada en este flujo.

Emision de Proformas

customer-invoices consume PaymentMethod mediante servicios publicos de catalogs.

Semantica vigente en emision:

• la Proforma mantiene una referencia viva paymentMethodId;
• la Issued Invoice persiste un snapshot historico del metodo de pago emitido;
• si paymentMethodId no existe dentro de la company activa, la emision falla;
• si el metodo existe pero esta inactivo, la emision falla;
• este bloqueo aplica solo al boundary de emision y no convierte automaticamente paymentMethodId en obligatorio durante create draft.

Datos copiados al snapshot historico de issued_invoices:

• payment_method_id
• payment_method_name
• payment_method_description

Tras emitir, el detalle historico no depende del catalogo vivo para representar la forma de pago usada.

Frontend Settings

La gestión administrativa frontend vive en:

• /settings/general/payment-methods
• módulo técnico catalogs

Características:

• listado administrativo con activos e inactivos
• create/edit mediante dialogs
• cambio de default mediante radio por fila
• activación/desactivación con endpoints específicos
• protección visual para system y default
• confirmación de delete con manejo de conflicto in use

Compatibilidad:

• el listado administrativo reutiliza el catálogo compartido de payment-methods
• los selectores existentes siguen filtrando por isActive=true donde ya lo hacían
• esta fase no aplica el default automáticamente en Proformas ni Customers