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

RolQuién esPuede
owner / org_adminStaff de la organizaciónCrear/editar/borrar customers, gestionar sus usuarios e invitaciones
memberCualquier otro miembroVer customers y sus usuarios (solo lectura)
customer_managerUsuario del portal con mandoGestionar los usuarios de su customer (invitar, rol, quitar) y su propia cuenta
customer_userUsuario del portal básicoSu propia cuenta; nada más

Uso: lado organización (staff)

Todos los clientes viven en /app/customers:

  1. 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.
  2. 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).
  3. Borrado: se rechaza con 409 mientras el cliente tenga usuarios aceptados (customer_has_users). Las invitaciones pendientes desaparecen con el cliente.
El último manager de un cliente no puede quitarse ni degradarse desde el portal — la regla protege al cliente de quedarse sin nadie que gestione sus usuarios. El staff de la organización sí puede quitarlo (es el camino para poder borrar 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 → 409 con code: '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.deleted lleva customersCount.
  • 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áginaQuién la veContenido
/portalCualquier usuarioSaludo, ficha de su cliente, invitaciones pendientes y accesos rápidos
/portal/usersSolo customer_managerLos usuarios de su customer: invitar, cambiar rol, quitar, reenviar/cancelar
/portal/settingsCualquier usuarioPerfil (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/users exige rol customer_manager; el resto es redirigido a /portal.
Un mismo usuario puede ser cliente de varios customers (incluso de organizaciones distintas). La sesión resuelve el vínculo más antiguo de forma determinista; un selector de customer es una extensión futura, el modelo ya la soporta.

Referencia técnica

Modelo de datos

TablaPara quéClaves
customer_userVínculo usuario ↔ customer con rolÚnico (customerId, userId); FK en cascada
customer_invitationLedger de invitaciones (estado, expiración, quién invitó)Único parcial (customerId, lower(email)) where pending
customer_categoryEtiquetas definidas por la organizaciónÚnico (organizationId, lower(name))
customer_category_linkAsignación N:M cliente ↔ categoríaÚnico (customerId, categoryId); FK en cascada
La invitación es nuestra, no de Better Auth: el endpoint de aceptación del plugin de organización crearía un member, y aquí el usuario no debe ser miembro.

API

MétodoRutaQuién
GET/api/customerCualquier miembro (paginado, filtros)
POST/api/customerowner / org_admin (crea + invita)
GET/api/customer/[id]Cualquier miembro
PATCH / DELETE/api/customer/[id]owner / org_admin
POST/api/customer/[id]/assignowner / org_admin
PUT/api/customer/[id]/categoriesowner / org_admin (selección completa)
GET/api/customer-categoriesCualquier miembro (con contadores)
POST/api/customer-categoriesowner / org_admin
PATCH / DELETE/api/customer-categories/[id]owner / org_admin
GET/api/customer/[id]/usersMiembros y el manager del customer
POST/api/customer/[id]/users/invitationsowner / 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/customerEl propio usuario del portal
GET/api/portal/invitationsCualquier cuenta con sesión (por email)
POST/api/portal/invitations/[id]/accept · …/rejectEl 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)

  1. Sin membership: nunca añadas usuarios de portal a member. Su superficie es /portal/**, /api/user/** y las rutas compartidas de usuarios del cliente.
  2. La fila primero, el email después: emailSent: false es un aviso, no un error; nunca una invitación perdida.
  3. Crear un cliente crea su primer manager: una invitación customer_manager sale con la creación; un fallo no revierte el cliente.
  4. Una pendiente por (cliente, email); reenviar reutiliza la fila y conserva el rol.
  5. Última manager: se protege cuando actúa el propio cliente; el staff de la organización puede desvincular o degradar.
  6. Borrado bloqueado con usuarios aceptados (409); las invitaciones pendientes caen con el cliente.
  7. Asignación = full-state sync: PUT /api/customer/[id]/categories recibe la selección completa; ids ajenos a la organización (o borrados entre la carga y el guardado) se descartan en vez de fallar.
  8. Filtro por categoría con EXISTS: categoryId no es una columna de customer; el listado lo resuelve con EXISTS sobre el vínculo para devolver cada fila una sola vez.
  9. Borrar categoría nunca bloquea: el vínculo cae en cascada; no hay 409 por uso.

Emails y eventos

  • Claves nuevas en la capa MJML: customer-invitation y customer-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, .deleted y, 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 con category: 'customer_category': created, updated, deleted.
  • El contexto de sesión expone customerId, customerRole, customerName, customerOrganizationName (los mezcla el plugin customSession junto 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
SpecQué cubre
customers.spec.tsAlta con invitación automática, acciones de invitación, edición de estado y borrado desde la UI
customer-portal.spec.tsInvitació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.tsCategorí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
El recorrido del portal necesita acceso a la base de datos (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

  1. Crea un customer en /app/customers con un email al que puedas acceder.
  2. Abre la invitación desde ese correo (o lee el token del magic link como hace el spec) y acéptala.
  3. Dentro del portal, entra a Account o Users — verás la cabecera del portal, sin nada del panel de staff.
  4. Como customer_manager, invita a una segunda persona desde /portal/users y repite la aceptación para comprobar que un customer_user no ve Users ni puede abrir la ruta.
  5. 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.
Con una API key real de Resend en modo de pruebas, los envíos a direcciones que no sean la de la cuenta se rechazan con 4xx: la invitación queda pendiente y emailSent es false (el comportamiento correcto). En ese entorno, permite experimentar con tu propio email o usa el token de verification.

Mapa de archivos

PiezaDónde
Esquemaserver/database/schema/customerUser.ts, server/database/schema/customerCategory.ts
Reglas e invitacionesserver/utils/customer-users.ts, server/utils/customer-portal.ts, server/utils/customer-categories.ts
API staff y compartidaserver/api/customer/**, server/api/customer-categories/**
API del portalserver/api/portal/**
Emailsserver/emails/templates/customer-invitation{,-signin}.ts
UI de staffapp/pages/app/customers/**, app/components/customers/** (slideover de categorías, selector y swatches)
UI del portalapp/layouts/portal.vue, app/pages/portal/**, app/pages/auth/customer-invitation/index.vue
Middlewareapp/middleware/auth.global.ts