Casos de uso — svc-identidad¶

Fecha: 2026-09-08 Autor: Duval Alcivar Servicio: svc-identidad (identidad y acceso: usuarios, empresas, sucursales, permisos)

Documento de casos de uso del servicio de identidad: quién usa el sistema (actores), qué puede hacer cada uno (casos de uso) y cómo se comporta el sistema en cada situación. Complementa los ADRs (decisiones de arquitectura) con la vista funcional.

Actores del sistema¶

Actor	Quién es	Qué hace en el sistema
Usuario	Persona que trabaja en una empresa cliente (vendedor, contador, bodeguero, etc.)	Inicia sesión, cambia su contraseña, cierra sesión
Root de plataforma	Tipo `root` (ADR 0007): personal interno de SIGFA o delegado con permiso a todo	Crea y gestiona empresas, usuarios, aplicaciones, módulos y permisos; habilita catálogos
Sistema externo	Otro servicio de la plataforma (ERP, CRM)	Recibe avisos de empresas creadas; valida tokens

Regla general: un admin de empresa solo ve y toca los datos de su empresa (la base de datos lo garantiza con RLS, ADR transversal 0002). El admin de plataforma es el único que puede crear empresas.

1. Diagrama general de casos de uso¶

flowchart LR
    usuario(["👤 Usuario"])
    rootPlat(["👤 Root de plataforma"])
    sistExt(["🖥️ Sistema externo<br/>(ERP / CRM)"])

    subgraph Sistema["svc-identidad"]
        UC01("CU-01 Iniciar sesión")
        UC02("CU-02 Cerrar sesión")
        UC03("CU-03 Renovar sesión")
        UC04("CU-04 Cambiar contraseña")
        UC05("CU-05 Gestionar usuarios")
        UC06("CU-06 Asignar permisos")
        UC07("CU-07 Asignar sucursales")
        UC08("CU-08 Gestionar sucursales")
        UC09("CU-09 Consultar historial de sesiones")
        UC10("CU-10 Crear empresa")
        UC11("CU-11 Habilitar aplicaciones")
        UC12("CU-12 Recibir aviso de empresa creada")
        UC13("CU-13 Validar token")
    end

    usuario --> UC01
    usuario --> UC02
    usuario --> UC03
    usuario --> UC04

    rootPlat --> UC05
    rootPlat --> UC06
    rootPlat --> UC07
    rootPlat --> UC08
    rootPlat --> UC09

    rootPlat --> UC10
    rootPlat --> UC11

    sistExt --> UC12
    sistExt --> UC13

    UC05 -.incluye.-> UC04
    UC10 -.genera.-> UC12

2. Módulo: Sesiones (el usuario y su acceso)¶

flowchart LR
    usuario(["👤 Usuario"])

    subgraph Sesiones["Módulo: Sesiones"]
        UC01("CU-01<br/>Iniciar sesión")
        UC02("CU-02<br/>Cerrar sesión")
        UC03("CU-03<br/>Renovar sesión")
        UC04("CU-04<br/>Cambiar contraseña")
    end

    usuario --> UC01
    usuario --> UC02
    usuario --> UC03
    usuario --> UC04

CU-01 — Iniciar sesión¶

Campo	Detalle
Actor	Usuario
Precondición	El usuario tiene una cuenta activa y acceso a al menos una empresa
Descripción	El usuario ingresa en dos pasos: primero valida su usuario y contraseña, luego elige la empresa en la que quiere trabajar, y recibe su credencial de acceso (token)
Flujo principal	1. El usuario envía username y contraseña. 2. El sistema verifica la contraseña (hash Argon2id) y que esté activo. 3. Devuelve la lista de empresas del usuario (`rel_usuario_empresa` activas). 4. Si tiene una sola empresa, el sistema la selecciona automáticamente y carga directo el panel de módulos. Si tiene varias, se abre un modal con la lista y el usuario elige a cuál entrar. 5. El sistema firma y entrega el token de acceso (30 min) + token de refresco (30 días). 6. Registra el ingreso en el historial (`log_sesiones`).
Flujos alternos	A1. Credenciales incorrectas → 401 genérico (no revela si el usuario existe). A2. Usuario inactivo o sin empresas asignadas → 403. A3. Contraseña temporal → el sistema exige cambiarla antes de continuar (CU-04). A4. Varias empresas → modal de selección; si el usuario lo cierra, queda en el login sin consumir el `pre_token`.
Postcondición	El usuario tiene un token con su identidad (`sub`), la empresa elegida (`empresa_id`), su `tipo_usuario` y sus `permisos`. Las sucursales no viajan en el token. A continuación se muestra el panel de aplicaciones (CU-14).

CU-02 — Cerrar sesión¶

Campo	Detalle
Actor	Usuario
Precondición	Sesión activa
Descripción	El usuario sale del sistema; su token de refresco queda revocado
Flujo principal	1. El usuario solicita cerrar sesión. 2. El sistema revoca su token de refresco. 3. Registra la salida en el historial.
Flujos alternos	A1. "Cerrar todas las sesiones" → revoca todos los tokens del usuario (útil si perdió su dispositivo).
Postcondición	El token de refresco ya no sirve; el token de acceso muere solo a los 30 min.

CU-03 — Renovar sesión¶

Campo	Detalle
Actor	Usuario (automático desde el frontend)
Precondición	Tiene un token de refresco válido
Descripción	Cuando el token de acceso expira (30 min), el sistema emite uno nuevo sin pedir la contraseña otra vez
Flujo principal	1. El frontend envía el token de refresco. 2. El sistema lo valida, emite un nuevo par de tokens y revoca el refresco anterior (rotación).
Flujos alternos	A1. El refresco ya fue usado (intento de reuso) → se revocan todas las sesiones del usuario por seguridad (posible robo).
Postcondición	Sesión extendida sin interrumpir al usuario.

CU-04 — Cambiar contraseña¶

Campo	Detalle
Actor	Usuario
Precondición	Sesión activa, o contraseña temporal obligatoria tras el primer login
Descripción	El usuario reemplaza su contraseña actual por una nueva
Flujo principal	1. El usuario envía su contraseña actual y la nueva. 2. El sistema verifica la actual, guarda el nuevo hash y quita la marca de "temporal". 3. Revoca las demás sesiones activas por seguridad.
Flujos alternos	A1. Contraseña actual incorrecta → error. A2. La nueva no cumple la política mínima → error con el detalle.
Postcondición	Nueva contraseña activa; sesiones anteriores cerradas.

3. Módulo: Administración de la plataforma (root)¶

flowchart LR
    rootPlat(["👤 Root de plataforma"])

    subgraph AdminPlataforma["Módulo: Administración de plataforma"]
        UC05("CU-05<br/>Gestionar usuarios")
        UC06("CU-06<br/>Asignar permisos")
        UC07("CU-07<br/>Asignar sucursales")
        UC08("CU-08<br/>Gestionar sucursales")
        UC09("CU-09<br/>Consultar historial<br/>de sesiones")
    end

    rootPlat --> UC05
    rootPlat --> UC06
    rootPlat --> UC07
    rootPlat --> UC08
    rootPlat --> UC09

CU-05 — Gestionar usuarios¶

Campo	Detalle
Actor	Root de plataforma
Precondición	Sesión activa de un usuario `root`
Descripción	Crear, editar, activar/desactivar y resetear la contraseña de los usuarios de la plataforma
Flujo principal	1. El admin crea un usuario: crea la entidad (`mae_entidades`) con la persona natural (`mae_personas`) o jurídica (`mae_personas_juridicas`) y su cuenta (`mae_usuarios`) con contraseña temporal. 2. Le da acceso a su empresa (`rel_usuario_empresa`). 3. El usuario nuevo debe cambiar la contraseña en su primer login (CU-04).
Flujos alternos	A1. Username o email ya existe → error. A2. Resetear contraseña → genera una temporal nueva. A3. Desactivar → el usuario ya no puede ingresar (sus sesiones se revocan).
Postcondición	El usuario puede ingresar a la empresa del admin.

CU-06 — Asignar permisos individuales¶

Campo	Detalle
Actor	Root de plataforma (puede delegar vía permisos)
Precondición	El usuario existe y tiene acceso a la empresa
Descripción	Asignar o quitar permisos al usuario (ej. `rrhh.nomina.crear`) y páginas del menú; con acciones finas por página (`rel_usuario_menu_accion`, ADR 0015). Los permisos viajan en su token al próximo login
Flujo principal	1. El admin elige usuario, página, acciones y permisos. 2. El sistema guarda la asignación (`rel_usuario_permiso` / `rel_usuario_menu` / `rel_usuario_menu_accion`, ADR 0014/0015). 3. En el próximo login, el token incluye los permisos actualizados.
Flujos alternos	A1. Asignar permisos a un `root` → el sistema los rechaza o los ignora (el `root` ya tiene todo, ADR 0007).
Postcondición	Los permisos del usuario cambian en su próxima sesión.

CU-07 — Asignar sucursales¶

Campo	Detalle
Actor	Root de plataforma
Precondición	La empresa tiene sucursales registradas
Descripción	Delimitar a qué sucursales del usuario se le asignan, para que las consultas de negocio (bodegas, almacenes) filtren por ellas. No da ni quita acceso al sistema.
Flujo principal	1. El admin elige usuario y sucursales. 2. El sistema guarda la asignación (`rel_usuario_sucursal`).
Flujos alternos	A1. Usuario sin sucursales asignadas → válido: opera sobre toda la empresa.
Postcondición	Las consultas del ERP/CRM pueden filtrar por las sucursales del usuario.

CU-08 — Gestionar sucursales¶

Campo	Detalle
Actor	Root de plataforma
Precondición	Sesión activa de un usuario `root`
Descripción	Crear, editar y activar/desactivar las sucursales de una empresa (código, nombre, dirección)
Flujo principal	1. El admin registra la sucursal con su código (ej. `SUC-01`). 2. El sistema la guarda y emite el aviso `sucursal.creada` para los demás sistemas.
Flujos alternos	A1. Código duplicado dentro de la empresa → error. A2. Desactivar una sucursal con usuarios asignados → el sistema advierte antes de continuar.
Postcondición	La sucursal queda disponible para asignar usuarios y para los módulos de negocio.

CU-09 — Consultar historial de sesiones¶

Campo	Detalle
Actor	Root de plataforma
Precondición	Sesión activa de un usuario `root`
Descripción	Ver quién ingresó, cuándo, desde qué IP y si falló (`log_sesiones`) — con alcance por empresa
Flujo principal	1. El admin filtra por usuario o fecha. 2. El sistema muestra los ingresos, salidas y fallos.
Flujos alternos	A1. Sin resultados → mensaje informativo.
Postcondición	Solo lectura; nada cambia en el sistema.

4. Módulo: Plataforma (root de plataforma)¶

flowchart LR
    rootPlat(["👤 Root de plataforma"])

    subgraph Plataforma["Módulo: Plataforma"]
        UC10("CU-10<br/>Crear empresa")
        UC11("CU-11<br/>Habilitar aplicaciones")
    end

    rootPlat --> UC10
    rootPlat --> UC11

CU-10 — Crear empresa¶

Campo	Detalle
Actor	Root de plataforma
Precondición	Sesión activa de un usuario `root`
Descripción	Dar de alta una empresa cliente nueva: sus datos, sus aplicaciones contratadas y su primer usuario con acceso; la plataforma aprovisiona el tenant (plantilla de módulos/menú, permisos base, acceso inicial — ADR 0016)
Flujo principal	1. El admin envía los datos de la empresa (nombre, identificación, país, ciudad, etc.). 2. El sistema guarda todo en una sola operación: empresa, sucursales (si se registraron — son opcionales), aplicaciones (core siempre + erp/crm), clon de la plantilla de navegación y el usuario inicial con acceso (ADR 0016). 3. Deja el aviso `empresa.creada` en la bandeja de salida para avisar a ERP/CRM (ADR 0008).
Flujos alternos	A1. Identificación duplicada → error. A2. Sin sucursales → válido, la empresa opera sin sucursales.
Postcondición	La empresa existe y su usuario inicial puede ingresar; ERP/CRM se enteran minutos después por el aviso.

CU-11 — Habilitar aplicaciones¶

Campo	Detalle
Actor	Root de plataforma
Precondición	La empresa existe
Descripción	Activar o desactivar qué aplicaciones ve la empresa en el login (ERP, CRM, etc.); al activar una app nueva se clona su plantilla de navegación (ADR 0013/0016)
Flujo principal	1. El admin marca las aplicaciones contratadas. 2. El sistema actualiza `rel_empresa_aplicacion`; si hay apps nuevas, clona su plantilla de módulos/menú/acciones (ADR 0013). 3. El login de esa empresa muestra solo sus aplicaciones activas.
Flujos alternos	A1. Desactivar la última aplicación → el sistema advierte (la empresa no verá nada al ingresar).
Postcondición	El catálogo de aplicaciones de la empresa queda actualizado.

5. Módulo: Integración entre sistemas¶

flowchart LR
    sistExt(["🖥️ Sistema externo<br/>(ERP / CRM)"])

    subgraph Integracion["Módulo: Integración"]
        UC12("CU-12<br/>Recibir aviso de<br/>empresa creada")
        UC13("CU-13<br/>Validar token")
    end

    sistExt --> UC12
    sistExt --> UC13

CU-12 — Recibir aviso de empresa creada¶

Campo	Detalle
Actor	Sistema externo (ERP, CRM)
Precondición	La empresa fue creada en svc-identidad (CU-10)
Descripción	El sistema externo recibe el aviso con los datos de la empresa nueva y crea su configuración inicial (numeración, parámetros)
Flujo principal	1. El proceso de envío entrega el aviso al endpoint `/internal/eventos` del sistema externo. 2. El sistema externo registra la empresa con su `empresa_id` y responde OK.
Flujos alternos	A1. El aviso llega repetido → se procesa una sola vez (se identifica por `evento + empresa_id`). A2. El sistema externo está caído → el proceso reintenta hasta su regreso.
Postcondición	La empresa existe en el sistema externo, lista para operar.

CU-13 — Validar token¶

Campo	Detalle
Actor	Sistema externo (ERP, CRM)
Precondición	El usuario ya inició sesión y llama al sistema externo con su token
Descripción	Cada sistema verifica que el token del usuario sea genuino y vigente, sin llamar a svc-identidad
Flujo principal	1. El sistema externo recibe la petición con el token. 2. Verifica la firma con la clave pública (descargada una vez del JWKS). 3. Lee la empresa (`empresa_id`), el `tipo_usuario` y los `permisos` del token y atiende la petición.
Flujos alternos	A1. Token expirado o firma inválida → 401. A2. `aud`/`iss` no son los de la plataforma → 401.
Postcondición	La petición se procesa con el aislamiento de la empresa del token.

flowchart LR
    usuario(["👤 Usuario"])

    subgraph Navegacion["Módulo: Navegación"]
        UC14("CU-14<br/>Ver panel de<br/>aplicaciones")
        UC15("CU-15<br/>Navegar por el menú<br/>del módulo")
    end

    usuario --> UC14
    usuario --> UC15

CU-14 — Ver panel de aplicaciones¶

Campo	Detalle
Actor	Usuario
Precondición	Sesión iniciada (CU-01)
Descripción	Tras el login, el usuario ve las aplicaciones contratadas por su empresa y, dentro de cada una, solo los módulos a los que tiene permiso
Flujo principal	1. El frontend pide el panel (`GET /api/v1/navegacion/panel`). 2. El sistema devuelve las aplicaciones de la empresa (`rel_empresa_aplicacion`) con los módulos visibles para el usuario (según sus permisos, ADR 0007/0012). 3. El usuario ve las tarjetas agrupadas por núcleo (Core / ERP / CRM) y entra al módulo que necesita.
Flujos alternos	A1. Una aplicación sin ningún módulo visible para el usuario no se muestra. A2. El usuario cambia de empresa desde el menú → el panel se recarga con los datos de la nueva empresa.
Postcondición	El usuario entra a un módulo → CU-15.

Campo	Detalle
Actor	Usuario
Precondición	Eligió un módulo en el panel (CU-14)
Descripción	Al entrar a un módulo, el usuario ve el menú lateral (sidebar) con las páginas a las que tiene permiso, organizadas en hasta 3 niveles
Flujo principal	1. El frontend pide el menú del módulo (`GET /api/v1/navegacion/menu?modulo_id=...`). 2. El sistema devuelve el árbol de páginas filtrado por los permisos del usuario (`rel_usuario_menu`). 3. El usuario navega a la página que necesita.
Flujos alternos	A1. El usuario intenta entrar por URL directa a una página sin permiso → el backend la rechaza (la UI oculta, la API manda).
Postcondición	El usuario opera solo las páginas que su rol le permite.

Resumen de casos de uso¶

CU	Nombre	Actor principal	Módulo
CU-01	Iniciar sesión	Usuario	Sesiones
CU-02	Cerrar sesión	Usuario	Sesiones
CU-03	Renovar sesión	Usuario	Sesiones
CU-04	Cambiar contraseña	Usuario	Sesiones
CU-05	Gestionar usuarios	Root de plataforma	Administración
CU-06	Asignar permisos	Root de plataforma	Administración
CU-07	Asignar sucursales	Root de plataforma	Administración
CU-08	Gestionar sucursales	Root de plataforma	Administración
CU-09	Consultar historial de sesiones	Root de plataforma	Administración
CU-10	Crear empresa	Root de plataforma	Plataforma
CU-11	Habilitar aplicaciones	Root de plataforma	Plataforma
CU-12	Recibir aviso de empresa creada	Sistema externo	Integración
CU-13	Validar token	Sistema externo	Integración
CU-14	Ver panel de aplicaciones	Usuario	Navegación
CU-15	Navegar por el menú del módulo	Usuario	Navegación

Referencias¶

ADR 0003 — catálogos y tablas maestras generales.
ADR 0004 — tablas de empresas, sucursales y aplicaciones.
ADR 0005 — tablas de usuarios, credenciales y sesiones.
ADR 0006 — catálogo de aplicaciones, módulos y menú.
ADR 0007 — tipos de usuario (usuario/root) y permisos individuales.
ADR 0008 — flujo de alta de empresa y avisos a otros sistemas.
ADR 0009 — gestión de usuarios y asignación de permisos.
ADR 0010 — flujo de acceso y panel de aplicaciones.
ADR 0011 — login: firma JWT y gestión de claves.
ADR 0012 — menú del módulo y permisos de navegación.
ADR 0013 — catálogo inicial de módulos y acciones (seed core/erp/crm).
ADR 0014 — catálogo inicial de permisos (cat_permisos, wildcard .*).
ADR 0015 — permisos finos por acción (rel_usuario_menu_accion).
ADR 0016 — ciclo de vida de empresa y aprovisionamiento del tenant.