Saltar a contenido

0027. Permisos por menú de identidad y root de sólo lectura

Estado: Aceptado Fecha: 2026-10-26 Autor: David Garcia Módulo(s) afectado(s): app/core/permisos.py, app/main.py, app/domains/catalogos/router.py, app/domains/clientes/router.py, tests/unit/

Contexto

svc-clientes sólo valida el token y separa por empresa (RLS): cualquier usuario autenticado de la empresa lee y escribe todo. Identidad ya emite en el claim permisos los códigos clientes.<menú>.<acción> (clientes.clientes.crear, clientes.prospectos.convertir, clientes.catalogos.terminos-pago.listar…), pero nadie los mira. Un usuario sin ningún permiso de clientes (SVENTAS) hoy lista clientes, prospectos y asignaciones. root también escribe, a diferencia de fuerza-ventas.

Decisión

  • root sólo lee: un método distinto de GET, HEAD u OPTIONS da 403. Va en una dependencia del router padre, por método HTTP, como en fuerza-ventas.
  • Cada operación exige su permiso, declarado en el endpoint con una dependencia (requiere(...)). Acción por operación: GET de la colección → listar, GET por id → ver, POST → crear, PUT → editar, DELETE → eliminar, POST …/convertir → convertir.
  • Menús: los 8 catálogos (clientes.catalogos.<catálogo>), grupos económicos, clientes y prospectos usan su código. Lo que no tiene menú en identidad es parte de la ficha del cliente y usa clientes.clientes.<acción> con la misma acción: contactos, locales, perfiles financieros, cliente–contactos y cliente–promotores (también la transferencia del ADR 0028, como editar).
  • Los códigos viven sólo en app/core/permisos.py; los routers usan sus constantes. Si identidad cambia un código, nadie lo tiene: 403 (falla cerrado).
  • root no pasa por los permisos (su token no los trae; su acceso es implícito), pero sigue sin escribir.
  • Excepción, sólo token: los existe de clientes, prospectos, locales y cartera (ADR 0029). Los consulta fuerza-ventas con el token del promotor, que puede no tener permisos de clientes.
  • El permiso se revisa antes que el registro: sin él, un id que no existe también es 403. Un test recorre el OpenAPI y exige que cada operación declare un permiso o esté en la lista explícita SIN_PERMISO.

Alternativas descartadas

  • Deducir el permiso del método HTTP — un GET puede ser listar o ver.
  • Menús propios para locales, contactos, etc. — exige cambios en identidad antes de desplegar; son partes de la ficha del cliente.
  • Revisar el permiso en el service — es autorización de la operación HTTP, no una regla del dominio; el service seguiría sin conocer los códigos.

Consecuencias

  • Antes de desplegar, cada rol que use clientes debe tener sus códigos en identidad: sin ellos, 403. SVENTAS, por ejemplo, hoy no tiene ninguno.
  • Quien puede editar un cliente también edita sus locales, contactos y promotores asignados.
  • Los tests de la API necesitan un usuario con permisos (o root para leer).

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.