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_tokende 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.mdcopiando la plantilla y añadir su fila a la tabla de arriba. El número siguiente es el del último + 1.