Customers y portal de clientes
[object Object]
Cada organización puede tener customers (sus clientes) y cada customer puede tener usuarios propios con acceso a un portal separado. La clave del diseño: esos usuarios no son miembros de la organización — no aparecen en el equipo, no cuentan para el límite de miembros y todas las rutas internas los rechazan por defecto.
Organización (members: owner / org_admin / member)
├── Categorías de clientes (etiquetas N:M definidas por la organización)
└── Customer (nombre, email, estado, asignado a…)
└── Usuarios del portal (customer_manager / customer_user) ← no son members
Roles
| Rol | Quién es | Puede |
|---|---|---|
owner / org_admin | Staff de la organización | Crear/editar/borrar customers, gestionar sus usuarios e invitaciones |
member | Cualquier otro miembro | Ver customers y sus usuarios (solo lectura) |
customer_manager | Usuario del portal con mando | Gestionar los usuarios de su customer (invitar, rol, quitar) y su propia cuenta |
customer_user | Usuario del portal básico | Su propia cuenta; nada más |
Uso: lado organización (staff)
Todos los clientes viven en /app/customers:
- Nuevo cliente: pide nombre, email y (opcional) nombre del contacto. Al crearlo, la organización genera automáticamente su primer usuario — un
customer_manager, con cuenta sin contraseña — y le envía una invitación. - Detalle del cliente (
/app/customers/[id]): pestaña Overview (nombre, email, estado, asignado) y pestaña Users con los usuarios del portal y las invitaciones pendientes (reenviar / cancelar). - Borrado: se rechaza con
409mientras el cliente tenga usuarios aceptados (customer_has_users). Las invitaciones pendientes desaparecen con el cliente.
Categorías de clientes
Cada organización define sus propias categorías (etiquetas) y un cliente puede llevar una o más. Se gestionan desde el slideover «Categorías» de /app/customers y se asignan en la tarjeta Categories del detalle del cliente.
- Crear, renombrar, recolorear y borrar: solo owner / org_admin. Cualquier miembro ve la columna, el filtro y los badges en modo lectura.
- Nombre único por organización sin distinguir mayúsculas (índice único parcial →
409concode: 'duplicate_name'). - Color: un token de la paleta de Nuxt UI (
primary,info,success,warning,error,neutral), nunca un hex — los badges siguen el tema claro/oscuro sin trabajo extra. - Borrar una categoría la quita en cascada de todos los clientes que la llevan; el diálogo de confirmación dice a cuántos afecta. Ese borrado no emite un evento por cliente: el evento
customer_category.deletedllevacustomersCount. - El listado de clientes se puede filtrar por categoría (checkbox con contadores vivos) y la columna Categorías muestra hasta 2 badges +
+n. - Las categorías son metadata interna: el portal del cliente no las muestra.
La asignación es un full-state sync: la tarjeta envía la selección completa (PUT /api/customer/[id]/categories), el servidor la contrasta contra la organización y calcula el diff — solo las transiciones escriben y emiten eventos. Re-guardar la misma selección no hace nada.
Flujo de invitación
La cuenta se crea primero
Si el email no existe, se crea la cuenta sin contraseña (mustCompleteProfile). Si ya existe, se reutiliza.
Una sola fila, antes del email
La invitación se persiste en customer_invitation antes de intentar el envío. Un fallo de entrega no pierde la invitación: la API responde con emailSent: false y la UI avisa para reenviarla.
Un solo email
Cuenta nueva (o sin contraseña) → magic link con copy de invitación (customer-invitation-signin), que inicia sesión y aterriza en la aceptación. Cuenta con contraseña → email de invitación normal (customer-invitation) con enlace a la aceptación.
Aceptación
/auth/customer-invitation?invitationId=… valida que la invitación esté pendiente, vigente y dirigida al email de la sesión. Al aceptar se crea el vínculo y el usuario entra a /portal.
Las invitaciones caducan en 7 días. Solo puede haber una pendiente por cliente y email (índice único parcial); reenviar reutiliza la fila y extiende la fecha. Rechazar o cancelar se registra (invitation_rejected / invitation_cancelled).
El portal (/portal)
| Página | Quién la ve | Contenido |
|---|---|---|
/portal | Cualquier usuario | Saludo, ficha de su cliente, invitaciones pendientes y accesos rápidos |
/portal/users | Solo customer_manager | Los usuarios de su customer: invitar, cambiar rol, quitar, reenviar/cancelar |
/portal/settings | Cualquier usuario | Perfil (nombre), cambio de email, crear/cambiar contraseña y sesiones activas |
Reglas de navegación (middleware global):
- Un usuario solo cliente que visite
/app/**es redirigido a/portal. - Un miembro sin vínculo de cliente no entra al portal. Alguien con invitación pendiente va a la página de aceptación.
/portal/usersexige rolcustomer_manager; el resto es redirigido a/portal.
Referencia técnica
Modelo de datos
| Tabla | Para qué | Claves |
|---|---|---|
customer_user | Vínculo usuario ↔ customer con rol | Único (customerId, userId); FK en cascada |
customer_invitation | Ledger de invitaciones (estado, expiración, quién invitó) | Único parcial (customerId, lower(email)) where pending |
customer_category | Etiquetas definidas por la organización | Único (organizationId, lower(name)) |
customer_category_link | Asignación N:M cliente ↔ categoría | Único (customerId, categoryId); FK en cascada |
member, y aquí el usuario no debe ser miembro.API
| Método | Ruta | Quién |
|---|---|---|
GET | /api/customer | Cualquier miembro (paginado, filtros) |
POST | /api/customer | owner / org_admin (crea + invita) |
GET | /api/customer/[id] | Cualquier miembro |
PATCH / DELETE | /api/customer/[id] | owner / org_admin |
POST | /api/customer/[id]/assign | owner / org_admin |
PUT | /api/customer/[id]/categories | owner / org_admin (selección completa) |
GET | /api/customer-categories | Cualquier miembro (con contadores) |
POST | /api/customer-categories | owner / org_admin |
PATCH / DELETE | /api/customer-categories/[id] | owner / org_admin |
GET | /api/customer/[id]/users | Miembros y el manager del customer |
POST | /api/customer/[id]/users/invitations | owner / org_admin o su manager |
POST / DELETE | /api/customer/[id]/users/invitations/[invitationId]… | igual que la anterior |
PATCH / DELETE | /api/customer/[id]/users/[customerUserId] | igual que la anterior |
GET | /api/portal/customer | El propio usuario del portal |
GET | /api/portal/invitations | Cualquier cuenta con sesión (por email) |
POST | /api/portal/invitations/[id]/accept · …/reject | El destinatario de la invitación |
Los rechazos viajan como códigos en error.data.code: already_invited, already_user, last_manager, customer_has_users, invitation_not_found, invitation_expired, invitation_wrong_recipient.
Invariantes (aplicadas en servidor)
- Sin membership: nunca añadas usuarios de portal a
member. Su superficie es/portal/**,/api/user/**y las rutas compartidas de usuarios del cliente. - La fila primero, el email después:
emailSent: falsees un aviso, no un error; nunca una invitación perdida. - Crear un cliente crea su primer manager: una invitación
customer_managersale con la creación; un fallo no revierte el cliente. - Una pendiente por (cliente, email); reenviar reutiliza la fila y conserva el rol.
- Última manager: se protege cuando actúa el propio cliente; el staff de la organización puede desvincular o degradar.
- Borrado bloqueado con usuarios aceptados (409); las invitaciones pendientes caen con el cliente.
- Asignación = full-state sync:
PUT /api/customer/[id]/categoriesrecibe la selección completa; ids ajenos a la organización (o borrados entre la carga y el guardado) se descartan en vez de fallar. - Filtro por categoría con
EXISTS:categoryIdno es una columna decustomer; el listado lo resuelve conEXISTSsobre el vínculo para devolver cada fila una sola vez. - Borrar categoría nunca bloquea: el vínculo cae en cascada; no hay
409por uso.
Emails y eventos
- Claves nuevas en la capa MJML:
customer-invitationycustomer-invitation-signin. Se pueden revisar en/api/admin/emails/preview(con?key=…&locale=es). - Triggers para workflows:
customer.user_invited,customer.user_joined,customer.user_removed,customer.user_role_changed,customer.invitation_cancelled,customer.invitation_rejected. - Triggers de categorías:
customer_category.created,.updated,.deletedy, uno por transición,customer.category_assigned/customer.category_unassigned(filtrables por$json.categoryName). - Auditoría con
category: 'customer':user_invited,user_joined,user_removed,user_role_changed,invitation_resent,invitation_cancelled,invitation_rejected,categories_updated; y concategory: 'customer_category':created,updated,deleted. - El contexto de sesión expone
customerId,customerRole,customerName,customerOrganizationName(los mezcla el plugincustomSessionjunto al de organización).
Pruebas
# Los tres recorridos de la feature
pnpm exec playwright test tests/e2e/app/customers.spec.ts tests/e2e/app/customer-portal.spec.ts tests/e2e/app/customer-categories.spec.ts
| Spec | Qué cubre |
|---|---|
customers.spec.ts | Alta con invitación automática, acciones de invitación, edición de estado y borrado desde la UI |
customer-portal.spec.ts | Invitación → magic link → aceptación → portal → guardas de rol → regla de borrado. El token del magic link se lee de la tabla verification |
customer-categories.spec.ts | Categoría creada desde el slideover, asignada desde el detalle, badge y filtro en el índice, renombrado y borrado en cascada — con la API como fuente de verdad |
NUXT_DATABASE_URL): sin ella el spec se salta (por ejemplo en CI contra un entorno remoto). El helper vive en tests/e2e/utils/db.ts.Probarlo a mano
- Crea un customer en
/app/customerscon un email al que puedas acceder. - Abre la invitación desde ese correo (o lee el token del magic link como hace el spec) y acéptala.
- Dentro del portal, entra a Account o Users — verás la cabecera del portal, sin nada del panel de staff.
- Como
customer_manager, invita a una segunda persona desde/portal/usersy repite la aceptación para comprobar que uncustomer_userno ve Users ni puede abrir la ruta. - De vuelta en el staff: abre Categorías en
/app/customers, crea una, asígnala desde el detalle de un cliente y filtra la lista por ella.
emailSent es false (el comportamiento correcto). En ese entorno, permite experimentar con tu propio email o usa el token de verification.Mapa de archivos
| Pieza | Dónde |
|---|---|
| Esquema | server/database/schema/customerUser.ts, server/database/schema/customerCategory.ts |
| Reglas e invitaciones | server/utils/customer-users.ts, server/utils/customer-portal.ts, server/utils/customer-categories.ts |
| API staff y compartida | server/api/customer/**, server/api/customer-categories/** |
| API del portal | server/api/portal/** |
| Emails | server/emails/templates/customer-invitation{,-signin}.ts |
| UI de staff | app/pages/app/customers/**, app/components/customers/** (slideover de categorías, selector y swatches) |
| UI del portal | app/layouts/portal.vue, app/pages/portal/**, app/pages/auth/customer-invitation/index.vue |
| Middleware | app/middleware/auth.global.ts |