david 5dfbdd2a1c feat(payment-methods): add payment method management functionality

- Implemented `usePaymentMethodUpdateMutation` for updating payment methods with validation.
- Created settings controllers and hooks for managing payment methods.
- Added UI components for creating, editing, deleting, and displaying payment methods.
- Introduced error handling and feedback mechanisms for payment method operations.
- Developed form schemas and utility functions for handling payment method data.
- Established a new settings page for managing payment methods with appropriate loading and error states.

2026-08-13 01:04:56 +02:00

3.3 KiB

Raw Blame History

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.

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

3.3 KiB Raw Blame History