Resumen. Cada cuenta de KopTup tiene un rol: tres para personas de fuera (user, client, prospect) y cuatro para el equipo (developer, sales, manager, admin). El rol decide a qué páginas entra la persona, qué ve en el panel y qué puede hacer con la API. Las demos tienen además un modo de acceso (Abierta, Con solicitud o Solo por invitación) que decide quién puede abrirlas.

Todas las reglas se verifican en el servidor, en tres capas: el middleware de la web antes de mostrar la página, el layout del panel o del portal, y la API en cada petición, que lee el rol vigente de la base de datos. Esconder un botón nunca es la única protección.

1. Los roles en una imagen
2. Qué ve cada rol al iniciar sesión
3. Matriz de páginas web
4. Cómo se decide el acceso a una demo
5. Modos de acceso de las demos
6. Capacidades del equipo en el panel
7. Cómo se decide el acceso: las tres capas
8. Matriz de la API
9. Qué datos ve cada rol
10. Cómo se asigna o cambia un rol
11. Para desarrolladores
12. Limitaciones conocidas
13. Páginas relacionadas

flowchart LR
    classDef visitante fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
    classDef admin fill:#fef3c7,stroke:#d97706,color:#78350f
    classDef sistema fill:#e0e7ff,stroke:#4f46e5,color:#312e81

    V["Visitante: sin cuenta"]:::visitante

    subgraph EXT["Personas de fuera"]
        U["user: se registró en /register o con Google"]:::visitante
        C["client: cliente con proyecto, igual que user"]:::visitante
        P["prospect: cuenta creada al aprobarle una demo"]:::visitante
    end

    subgraph EQ["Equipo de KopTup"]
        D["developer: abre todas las demos, sin panel"]:::admin
        S["sales: comercial, gestiona solicitudes y accesos"]:::admin
        M["manager: gerente, todo el panel, en lo comercial solo consulta"]:::admin
        A["admin: todo, incluido catálogo, roles y demos privadas"]:::admin
    end

    V -->|"Se registra"| U
    V -->|"Solicita una demo y el equipo la aprueba"| P
    V -->|"Invitación directa del equipo"| P
    A -->|"Asigna el rol"| C
    A -->|"Asigna el rol"| D
    A -->|"Asigna el rol"| S
    A -->|"Asigna el rol"| M

Azul: personas de fuera. Ámbar: equipo de KopTup. Solo un admin cambia roles (ver §10).

Siete cuadros, uno por rol: visitante, prospecto, cliente, developer, comercial, gerente y administrador, con cuentas ficticias del entorno de capturas.

Panel del administrador	Panel del comercial (sales)
① Grupo Comercial (Solicitudes, Accesos y Catálogo de demos) · ② Grupo Operación (Inicio, Pedidos, Entregables, Facturas, Conversaciones, Usuarios, Contactos) · ③ Configuración · ④ Nombre y rol. El gerente ve exactamente el mismo menú.	① Solo el grupo Comercial: no ve Operación ni Configuración, y si escribe /admin lo devuelve a Solicitudes · ② Nombre y rol ("Comercial").

Izquierda: el menú completo (admin y manager). Derecha: el menú reducido del rol sales.

Los menús del prospecto (solo Mis demos y Mi perfil) y del cliente (portal completo) están con capturas en Flujos del prospecto y cliente §8.

✅ entra · 👁 entra solo a consultar · ➜ lo redirige · ❌ no entra.

La columna user / client también vale para un prospecto que luego pasa a cliente: conserva sus accesos a demos.

La misma regla la aplican la web (al abrir /demo/<slug>) y la API (en las rutas de las demos que usan backend). Vive en un solo lugar: evaluateDemoAccess en apps/backend/src/services/demo-access.service.ts.

flowchart TD
    classDef ok fill:#dcfce7,stroke:#16a34a,color:#14532d
    classDef error fill:#fee2e2,stroke:#dc2626,color:#7f1d1d
    classDef decision fill:#fff,stroke:#64748b,color:#334155
    classDef sistema fill:#e0e7ff,stroke:#4f46e5,color:#312e81

    S["Alguien abre /demo/slug o llama a la API de una demo"]:::sistema
    Q1{"¿La demo existe en el catálogo?"}:::decision
    Q2{"¿Rol admin, manager, sales o developer?"}:::decision
    Q3{"¿La demo está activa?"}:::decision
    Q4{"¿Modo Abierta?"}:::decision
    Q5{"¿Hay sesión?"}:::decision
    Q6{"¿Tiene un acceso activo que no ha vencido?"}:::decision
    Q7{"¿Tuvo algún acceso a esta demo?"}:::decision
    Q8{"¿El último fue retirado?"}:::decision

    NE["no_existe"]:::error
    ST["Permitido: staff"]:::ok
    DES["desactivada: En mantenimiento"]:::error
    PU["Permitido: publico"]:::ok
    SS["sin_sesion: pide iniciar sesión"]:::error
    GR["Permitido: grant, registra la visita"]:::ok
    SA["sin_acceso: Solicitar acceso"]:::error
    RV["revocado"]:::error
    EX["expirado: muestra la fecha y Pedir más tiempo"]:::error

    S --> Q1
    Q1 -->|"No"| NE
    Q1 -->|"Sí"| Q2
    Q2 -->|"Sí"| ST
    Q2 -->|"No"| Q3
    Q3 -->|"No"| DES
    Q3 -->|"Sí"| Q4
    Q4 -->|"Sí"| PU
    Q4 -->|"No: Con solicitud o Solo por invitación"| Q5
    Q5 -->|"No"| SS
    Q5 -->|"Sí"| Q6
    Q6 -->|"Sí"| GR
    Q6 -->|"No"| Q7
    Q7 -->|"No"| SA
    Q7 -->|"Sí"| Q8
    Q8 -->|"Sí"| RV
    Q8 -->|"No"| EX

Si MongoDB no responde, las demos Abiertas siguen abiertas y el resto queda cerrado con el motivo no_disponible (la API responde 503). La fecha de vencimiento se compara en cada consulta: no depende del job horario.

Qué ve la persona según el motivo (capturas en Flujos del prospecto y cliente §6):

stateDiagram-v2
    [*] --> activo: Aprobar solicitud o invitación directa
    activo --> activo: Extender (suma días)
    activo --> expirado: Pasa la fecha de vencimiento
    expirado --> activo: Extender
    activo --> revocado: Retirar
    expirado --> revocado: Retirar
    revocado --> [*]: Para volver a dar acceso se crea uno nuevo

Cada acceso dura 14 días por defecto (entre 1 y 365). El job horario marca como expirado los vencidos y envía un recordatorio 3 días antes si hay correo configurado.

• El administrador cambia el modo, activa o desactiva una demo y fija su vigencia por defecto en Admin › Catálogo de demos. El cambio se aplica en el sitio en máximo un minuto (caché del middleware) y queda en la bitácora. El chatbot RAG queda siempre Abierto: es el destino de la publicidad.
• La tabla de respaldo de la web (lib/demo-access-defaults.ts) y la semilla del backend tienen los mismos modos; una prueba automática verifica que coincidan.
• Una demo con acceso controlado se sirve con Cache-Control: private, no-store y X-Robots-Tag: noindex.
• El sitemap lista las demos Abiertas y activas según el catálogo (se regenera como mucho cada hora; ver SEO › 2.3).

Catálogo de demos visto por un gerente: ① el modo de acceso y ② el interruptor de activa aparecen deshabilitados, ③ el aviso "Solo un administrador puede editar el catálogo" y ④ el rol en el encabezado.

✅ puede · 👁 solo consulta · ❌ no puede. El developer no entra al panel.

Solicitud con una demo Solo por invitación vista por el comercial: ① el aviso "Las demos «Solo por invitación» las aprueba un administrador", ② el botón Aprobar y generar el enlace deshabilitado mientras esa demo esté marcada y ③ lo que sí puede hacer, como marcarla en revisión. Si quita la demo privada de la lista, puede aprobar el resto.

El paso a paso de cada acción está en el Manual del administrador.

flowchart TD
    classDef sistema fill:#e0e7ff,stroke:#4f46e5,color:#312e81
    classDef decision fill:#fff,stroke:#64748b,color:#334155
    classDef error fill:#fee2e2,stroke:#dc2626,color:#7f1d1d
    classDef ok fill:#dcfce7,stroke:#16a34a,color:#14532d

    REQ["Petición del navegador"]:::sistema
    M1{"¿Ruta /admin, /dashboard, /liquidacion o /demo/slug?"}:::decision
    PUB["Next sirve la página sin verificar sesión"]:::sistema
    M2{"¿Es /demo/slug?"}:::decision
    GATE["Regla de acceso a la demo (sección 4)"]:::sistema
    ME["Capa 1, middleware: GET /api/auth/me con el accessToken, y lo renueva si venció"]:::sistema
    E503["503: No pudimos verificar tu sesión"]:::error
    LOGIN["Redirige a /login con redirect a la ruta pedida"]:::error
    ROL{"¿El rol puede entrar a esa área?"}:::decision
    HOME["Redirige a la página de inicio de su rol"]:::error
    PR{"¿Prospecto fuera de Mis demos o Mi perfil?"}:::decision
    MD["Redirige a /dashboard/demos"]:::error
    LAY["Capa 2, layout del panel o del portal: repite la regla con el rol guardado y arma el menú"]:::sistema
    API["Capa 3, API: authenticate y luego requireRole, requireStaffOrDemoAccess o verificación de dueño"]:::sistema
    OK["Datos"]:::ok
    NO["401, 403 o 503"]:::error

    REQ --> M1
    M1 -->|"No"| PUB
    M1 -->|"Sí"| M2
    M2 -->|"Sí"| GATE
    M2 -->|"No"| ME
    ME -->|"La API no responde"| E503
    ME -->|"Sin sesión válida"| LOGIN
    ME -->|"Sesión válida"| ROL
    ROL -->|"No"| HOME
    ROL -->|"Sí"| PR
    PR -->|"Sí"| MD
    PR -->|"No"| LAY
    LAY --> API
    PUB --> API
    GATE --> API
    API -->|"Permitido"| OK
    API -->|"Denegado"| NO

La capa que manda es la 3: aunque alguien llegue a una página, la API vuelve a autorizar cada consulta con el rol vigente.

Los guardias de la API:

Los cambios de rol o el retiro de un acceso se aplican de inmediato en la API; en la web pueden tardar hasta 30 segundos por la caché del middleware.

✅ puede · 🔒 solo lo propio · 🎟 si la demo es Abierta o tiene acceso vigente · ❌ no puede. Detalle de cada ruta en API y en apps/backend/src/routes/POLICIES.md.

La pantalla Admin › Usuarios, con su selector de rol anotado, está en el Manual del administrador §7. La persona a la que se le cambia el rol debe cerrar sesión y volver a entrar para que su menú cambie; la API aplica el rol nuevo de inmediato.

Cada cambio de rol queda en la bitácora (user.role_change, con el rol anterior y el nuevo). La API valida el rol contra la lista del modelo y no deja que un admin se quite su propio rol.

Para agregar un rol: súmalo a USER_ROLES, decide en qué listas de config/demos.ts y middleware/access.ts entra, actualiza lib/auth-roles.ts en la web (áreas y página de inicio), las etiquetas de adminLayout.roles en messages/ y el selector de Admin › Usuarios, y agrega pruebas de integración.

• Selector de roles incompleto. Admin › Usuarios solo ofrece Usuario, Developer, Manager y Admin. Para una cuenta sales, prospect o client el selector muestra "Usuario" aunque no lo sea, y esos tres roles solo se pueden asignar por la API.
• El gerente ve el selector de roles en Admin › Usuarios, pero la API rechaza el cambio (solo admin) y la pantalla muestra un error genérico.
• Sin pantalla para la bitácora completa: solo existe GET /api/admin/audit-log (admin). El detalle de cada solicitud sí muestra su historial.
• El developer no tiene etiqueta propia en el panel (no entra) y en el portal se ve como un cliente.
• Caché de 30 s en la web: un cambio de rol o un acceso retirado puede tardar hasta 30 segundos en reflejarse en las páginas (la API lo aplica de inmediato).
• En desarrollo: el paso de prospecto a cliente con propuesta y anticipo no está en main; ver Estado y próximos pasos.

• Flujos del prospecto y cliente: activación, Mis demos y pantallas de acceso.
• Manual del administrador: cómo aprobar, invitar, extender y retirar.
• Arquitectura: dónde corre cada capa.
• API: todas las rutas.
• Mapa del sitio: todas las páginas con su nivel de acceso.
• Plan relacionado: Sistema de demos y Seguridad y calidad.