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. Al mover este historial a su repositorio de GitLab, los números se mantienen como están.

Índice (numerado por escritura)¶

N.º	ADR	Estado	Tema
0001	Microservicio de identidad y acceso	Propuesto	Creación de `svc-identidad` y dominios que posee
0002	Stack de herramientas y librerías	Aceptado	Librerías y herramientas del servicio: ORM, validación, testing, calidad, CI
0003	Catálogos y tablas maestras generales	Propuesto	Países, ciudades, tipos de documento
0004	Modelo de datos: empresas, sucursales y aplicaciones	Propuesto	mae_empresas, mae_sucursales, rel_empresa_aplicacion
0005	Modelo de datos: usuarios, credenciales y sesiones	Propuesto	mae_usuarios, mae_personas, rel_usuario_empresa, rel_usuario_sucursal, trx_refresh_tokens, log_sesiones
0006	Catálogo: aplicaciones, módulos y menú	Propuesto	cat_aplicaciones, cfg_modulos, cfg_menu, cfg_menu_acciones, rel_empresa_aplicacion
0007	Tipos de usuario y permisos individuales	Propuesto	cat_tipos_usuario (usuario/root/externo), cat_permisos, rel_usuario_permiso, rel_usuario_menu
0008	Flujo de alta de empresa (onboarding multiempresa)	Propuesto	Alta transaccional en svc-identidad + propagación por outbox (empresa.creada)
0009	Gestión de usuarios y asignación de permisos	Propuesto	CRUD de identidad, asignación de empresas, permisos individuales y páginas
0010	Flujo de acceso y panel de aplicaciones	Propuesto	Login en dos pasos (credenciales → selector de empresa), panel de apps/módulos
0011	Login: firma JWT y gestión de claves	Propuesto	RS256, clave privada/JWKS, claims, refresh tokens
0012	Menú del módulo y permisos de navegación	Propuesto	Panel y sidebar filtrados por permisos (rel_usuario_menu)
0013	Catálogo inicial de módulos y acciones (seed)	Propuesto	Plantilla core/erp/crm (módulos → páginas → acciones) y clon por empresa
0014	Catálogo inicial de permisos	Propuesto	`cat_permisos`: códigos `<módulo>.<página>.<acción>`, wildcard `.*`
0015	Permisos finos por acción	Propuesto	`rel_usuario_menu_accion`: acciones por página, claim `permisos`
0016	Ciclo de vida de empresa y aprovisionamiento del tenant	Propuesto	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`	Propuesto	`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	Propuesto	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	Propuesto	mae_entidades, mae_personas, mae_personas_juridicas, cat_tipos_usuario, mae_usuarios.entidad_id/tipo_usuario_id

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.