Saltar a contenido

ADR — svc-identidad

Registro de decisiones de arquitectura de svc-identidad (identidad y acceso). Es el servicio que centraliza para toda la plataforma cómo cada microservicio identifica al usuario y la empresa seleccionada, su tipo (usuario/root) y sus permisos. Desde aquí se crean y gestionan empresas, usuarios, aplicaciones, módulos, menú y se asignan permisos individuales (generales y por módulo), además de albergar las tablas maestras y catálogos comunes.

La numeración es local a este microservicio. Esta serie (0001–0031) documenta el diseño del servicio y se mantiene como está: cuando una decisión de implementación la cambia, el ADR original no se reescribe, cambia su estado y el detalle queda en los ADR de complemento 0025–0031.

Las decisiones tomadas durante la implementación viven en ../adr-implementacion/, con su propia numeración (0001–0067). Son dos series independientes: no se mezclan ni se renumeran para no romper las citas existentes.

Índice (numerado por escritura)

N.º ADR Estado Tema
0001 Microservicio de identidad y acceso Complementado por ADR 0026 Creación de svc-identidad y dominios que posee
0002 Stack de herramientas y librerías Parcialmente reemplazado por ADR 0030 Librerías y herramientas del servicio: ORM, validación, testing, calidad, CI
0003 Catálogos y tablas maestras generales Superado por 0024; complementado por ADR 0029 Países, ciudades, provincias, tipos de documento, feriados, mae_documentos
0004 Modelo de datos: empresas, sucursales y aplicaciones Parcialmente reemplazado por ADR 0028 mae_empresas, mae_sucursales, rel_empresa_aplicacion
0005 Modelo de datos: usuarios, credenciales y sesiones Parcialmente reemplazado por ADR 0026 mae_usuarios, mae_personas, rel_usuario_empresa, rel_usuario_sucursal, trx_refresh_tokens, log_sesiones
0006 Catálogo: aplicaciones, módulos y menú Parcialmente reemplazado por ADR 0027 cat_aplicaciones, cfg_modulos, cfg_menu, cfg_menu_acciones, cfg_variables_sistemas, rel_empresa_aplicacion
0007 Tipos de usuario y permisos individuales Reemplazado por 0023; complementado por ADR 0026 cat_tipos_usuario (usuario/root/externo), cat_permisos, rel_usuario_permiso, rel_usuario_menu
0008 Flujo de alta de empresa (onboarding multiempresa) Parcialmente reemplazado por ADR 0028 Alta transaccional en svc-identidad + propagación por outbox (empresa.creada)
0009 Gestión de usuarios y asignación de permisos Parcialmente reemplazado por ADR 0026 CRUD de identidad, asignación de empresas, permisos individuales y páginas
0010 Flujo de acceso y panel de aplicaciones Parcialmente reemplazado por ADR 0025 y ADR 0027 Login en dos pasos (credenciales → selector de empresa), panel de apps/módulos
0011 Login: firma JWT y gestión de claves Parcialmente reemplazado por ADR 0025 RS256, clave privada/JWKS, claims, refresh tokens
0012 Menú del módulo y permisos de navegación Reemplazado por ADR 0027 Panel y sidebar filtrados por permisos (rel_usuario_menu)
0013 Catálogo inicial de módulos y acciones (seed) Parcialmente reemplazado por ADR 0027 Plantilla core/erp/crm (módulos → páginas → acciones) y clon por empresa
0014 Catálogo inicial de permisos Reemplazado por 0023; complementado por ADR 0027 cat_permisos: códigos <módulo>.<página>.<acción>, wildcard .*
0015 Permisos finos por acción Reemplazado por 0023 rel_usuario_menu_accion: acciones por página, claim permisos
0016 Ciclo de vida de empresa y aprovisionamiento del tenant Parcialmente reemplazado por ADR 0028 CRUD + soft-delete de empresas, clon de plantilla, acceso inicial
0017 Rotación y renovación de claves Propuesto Operativa de rotación RS256: ventana de gracia, retiro, revocación de emergencia
0018 Seguridad del pre_token Parcialmente reemplazado por ADR 0025 pre_token: expiración corta, un solo uso y detección de replay
0019 Versionado de eventos de integración Propuesto Eventos empresa.creada.v1 en outbox/Kafka con JSON Schema versionado
0020 Params de Argon2id y expiración de tokens Parcialmente reemplazado por ADR 0025 Argon2id (64 MiB, t=3), TTL de access/refresh/pre_token y audiencia fija com.sigfa.plataforma
0021 Limpieza programada de sesiones y tokens Propuesto Purga diaria de trx_refresh_tokens, trx_pre_tokens y particiones de log_sesiones
0022 Patrón party: entidad, persona natural y jurídica Parcialmente reemplazado por ADR 0026 y ADR 0031 mae_entidades, mae_personas, mae_personas_juridicas (hoy mae_personas_comerciales), cat_tipos_usuario, mae_usuarios.entidad_id/tipo_usuario_id
0023 Modelo unificado de permisos: una acción por sujeto Complementado por ADR 0026 Unifica permisos en rel_usuario_accion; sujeto polimórfico (usuario o rol), jerarquía derivada
0024 Fusión de catálogos: tipos de identificación absorbe tipos de documentos Complementado por ADR 0029 Fusiona cat_tipos_documentos en cat_tipos_identificacion (migración 20260929_001); elimina el endpoint tipos-documentos
0025 Autenticación: naming godexerp, claims nuevos y dos tokens de autorización Aceptado Naming com.godexerp.*, claims nuevos, refresh con empresa y tokens admin/tenant
0026 Modelo de datos: 28 tablas, permiso único y entidades party Aceptado 28 tablas, rel_usuario_accion, entidades party y alta entidad + usuario
0027 Navegación: plantilla declarativa, códigos jerárquicos y dashboard Aceptado PLANTILLA_BASE, materialización opt-in, copiar/mover y /dashboard
0028 Tenencia y RLS: historial de aplicaciones, bloqueo de borrado y dos pools Aceptado Historial de rel_empresa_aplicacion, 409 de borrado y pools tenant/BYPASSRLS
0029 Catálogos: lectura autenticada y escritura exclusiva de root Aceptado Listas maestras autenticadas y escrituras de catálogos root-only
0030 Stack y migraciones: asyncpg, ruff y .env.migrations Aceptado asyncpg, ruff sin black, httpx2 y entorno de migraciones
0031 Persona comercial y tipo de contribuyente Aceptado PERSONA/PERSONA_COMERCIAL, mae_personas_comerciales, tipo_contribuyente y rutas /comerciales

Orden de lectura (secuencia lógica)

Los números siguen el orden de escritura; el orden lógico de lectura sigue el ciclo de vida de la identidad. Lee así:

flowchart TD
    A["0001 · 0002<br/>qué es y con qué herramientas"]
    B["0003 · 0005 · 0022<br/>catálogos y modelos (empresa, usuario, entidad)"]
    C["0006 · 0007 · 0013 · 0014 · 0015<br/>navegación, catálogo inicial y permisos"]
    D["0008 · 0009 · 0016<br/>gestión (alta empresa, alta usuario, ciclo de vida)"]
    E["0010<br/>flujo de acceso y panel"]
    F["0011 · 0017 · 0018 · 0020<br/>seguridad: firma, claves, pre_token, expiraciones (de fondo)"]
    G["0012<br/>menú y permisos"]
    H["0019<br/>eventos de integración (outbox/Kafka)"]
    I["0021<br/>purga programada de sesiones"]

    A --> B --> C --> D --> E
    E --> F
    E --> G
    F --> I
    D -.->|"empresa.creada.v1"| H
Fase ADR Qué responde
1. Concepto 0001 (qué es) · 0002 (stack) ¿Qué es el servicio? ¿Con qué lo construyo?
2. Datos 0003 (catálogos) · 0004 (empresas) · 0005 (usuarios) · 0022 (party/entidades) ¿Qué tablas hay? ¿Qué maestros se centralizan?
3. Navegación y permisos 0006 (apps/módulos/menú) · 0007 (tipos/permisos) ¿Qué se ve y con qué permisos?
4. Catálogo inicial 0013 (seed de módulos/páginas/acciones) · 0014 (permisos base) · 0015 (acciones finas) ¿Qué trae una empresa y un usuario al nacer?
5. Gestión 0008 (alta de empresa) · 0009 (gestión de usuarios/permisos) · 0016 (ciclo de vida de empresa) ¿Cómo se crea, edita y administra?
6. Acceso 0010 (flujo y panel) ¿Cómo entra el usuario y qué ve?
7. Seguridad 0011 (firma y claves) · 0017 (rotación de claves) · 0018 (pre_token) · 0020 (Argon2id y expiración) ¿Cómo se asegura el ciclo de vida de credenciales y tokens?
8. Permisos en ejecución 0012 (menú y navegación) ¿Qué puede usar dentro?
9. Operación 0019 (eventos de integración) · 0021 (purga programada) ¿Cómo se comunican los cambios y se mantiene la casa?

El 0010 narra el flujo de entrada del usuario; el 0011 explica cómo se firma el token que ese flujo produce; el 0012 define qué se muestra al entrar. La creación y asignación de identidad vive en el 0008 (alta) y 0009 (usuarios/permisos), y el ciclo de vida completo de la empresa (edición, soft-delete, aprovisionamiento del tenant) en el 0016. El catálogo inicial de cada empresa/usuario (módulos, permisos y acciones) se siembra con los 0013/0014/0015. La seguridad técnica se cierra con los 0017 (rotación de claves), 0018 (pre_token de un solo uso) y 0020 (params de Argon2id y TTLs); la purga de las tablas de sesión la hace el 0021 y la salida de eventos se versiona según el 0019.

Notas

  • Plantilla: en template/0000-adr-template.md.
  • Cómo añadir: crear NNNN-titulo.md copiando la plantilla y añadir su fila a la tabla de arriba. El número siguiente es el del último + 1.