david
5dfbdd2a1c
- 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.
122 lines
3.3 KiB
Markdown
122 lines
3.3 KiB
Markdown
# 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
|