0022. Dominio clientes — sexto slice: perfil financiero¶
Estado: Propuesto Fecha: 2026-10-01 Autor: Kevin Delgado Lopez Módulo(s) afectado(s): app/domains/clientes/, tests/unit/clientes/
Contexto¶
trx_perfil_financiero_cliente es la primera tabla transaccional del dominio:
un perfil declarado por cliente y año (único aun borrado), con montos
numeric(16,2) (ingreso y egreso no negativos, utilidades pueden ser
negativas), años de operación (smallint) y cantidades declaradas
(integer). docs-sql: una corrección actualiza la fila del año; no hay
perfiles nuevos para clientes borrados, pero los históricos se conservan.
Decisión¶
- Rutas planas
/api/v1/perfiles-financieroscon filtros?cliente_id=y?anio=; estrena el tagclientes-transaccionales(sub-routertransaccionales). Listado del año más reciente al más antiguo. - Al crear, el cliente debe existir (404) y estar activo (409). Si el año ya
tiene perfil activo → 409 («corrígelo con PUT»); si estaba borrado, el mismo
POSTreactiva la misma fila con los datos nuevos (como el ADR 0021). - El
PUTreemplaza los datos del perfil;cliente_idyaniono se editan. - Validaciones en el contrato (422): año 1900–2100, cantidades no negativas y dentro de su tipo, montos con 2 decimales.
- Montos como número, con tope de 13 enteros (
9 999 999 999 999,99): un número JSON se lee comofloat, que con 16 dígitos pierde el último centavo (probado contra la base). Con 15 dígitos siempre es exacto al recibir y al responder. La base sigue admitiendo 14 enteros. - Respuesta con
cliente(razón social) por relaciónviewonly+joinedload. - Borrar un cliente conserva sus perfiles.
Alternativas descartadas¶
- Montos como texto (
"1250000.50") — exactos hasta el tope de la base, pero el frontend tendría que enviar y convertir texto. - Aceptar los 14 enteros como número — en el extremo se pierde un centavo sin aviso.
- 409 al recrear un año borrado — el año es la clave natural; quedaría bloqueado para siempre.
Consecuencias¶
clientesexpone 30 operaciones (20 maestras, 5 transaccionales, 5 de relaciones).- Cualquier monto nuevo del servicio (por ejemplo, en visitas o pedidos) debe seguir la misma regla de 15 dígitos o pasar a texto.
Media página como máximo. Si el ADR crece más que eso, probablemente estás documentando el diseño completo del módulo, no una decisión puntual — separa.