Saltar a contenido

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-financieros con filtros ?cliente_id= y ?anio=; estrena el tag clientes-transaccionales (sub-router transaccionales). 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 POST reactiva la misma fila con los datos nuevos (como el ADR 0021).
  • El PUT reemplaza los datos del perfil; cliente_id y anio no 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 como float, 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ón viewonly + 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

  • clientes expone 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.