1. Vision General
ApplicationUser
Una sola cuenta por persona — email, nombre
Central DB
Merchant(s)
Acceso a 1 o muchos negocios
con un rol por negocio
Central DB
Partner
Acceso a 1 socio de canal
PartnerAdmin o PartnerSupport
Central DB
Concepto clave: Un usuario existe una sola vez. La tabla UserMerchant le da acceso a uno o varios merchants con un rol diferente en cada uno. Un dueño con 5 farmacias tiene 1 usuario y 5 registros en UserMerchant.
2. Autenticacion — Sin Passwords
Decision: QIIUB no usa passwords. Nadie crea una contrasena nueva. El login es por Office 365, cuenta Microsoft, Google, o Magic Link (email con link de un solo uso).
Como funciona el login
Usuario entra su email
El sistema decide el flujo automaticamente
↓
@bcposgroup.com
@bcpos.com
Forzado a
Office 365
(Microsoft Entra ID)
Cuenta Microsoft
o Google ligada
Redirige a
Microsoft o Google
(SSO con su cuenta existente)
Cualquier otro email
Envia
Magic Link
(link de un uso, 15 min)
Como se crean usuarios nuevos
Por invitacion. Un SystemAdmin o PartnerAdmin envia una invitacion por email. El invitado acepta, liga su cuenta (Microsoft, Google, o magic link), y queda registrado. No hay auto-registro publico.
Dos app registrations en Microsoft
| App Registration | Para quien | Tipo |
|---|
| microsoft-bcpos |
Staff BCPOS (@bcposgroup.com, @bcpos.com) |
Single-tenant — solo cuentas del tenant corporativo de BCPOS |
| microsoft-external |
Partners, merchants, cualquiera con cuenta Microsoft |
Multi-tenant — acepta cualquier cuenta Microsoft (personal u organizacional) |
3. Roles, Portales, y Quien Accede a Que
| Rol | Quien | Admin Portal | Merchant Portal | Auth |
|---|
| SystemAdmin |
Staff BCPOS |
Ve todo — partners, merchants, plataforma |
Puede entrar y seleccionar cualquier merchant para ver |
Office 365 (forzado) |
| PartnerAdmin |
Socio de canal |
Sus merchants, usuarios partner, dispositivos, modulos |
Puede entrar y seleccionar merchant de su partner para ver |
Microsoft / Google / Magic Link |
| PartnerSupport |
Soporte del partner |
Solo lectura — config, dispositivos, sync |
Puede entrar y seleccionar merchant (solo lectura) |
Microsoft / Google / Magic Link |
| Admin |
Dueno del negocio |
No |
Todo en su(s) merchant(s) — productos, inventario, empleados, reportes |
Microsoft / Google / Magic Link |
| Manager |
Gerente de tienda |
No |
Operaciones diarias, reportes, empleados |
Microsoft / Google / Magic Link |
| Cashier |
Cajero (web) |
No |
Ventas, devoluciones, busqueda de clientes |
Microsoft / Google / Magic Link |
| Employee |
Cualquier empleado en tienda |
No |
No — solo terminal POS |
PIN numerico |
SystemAdmin y Partner no solo viven en el Admin Portal — tambien pueden entrar al Merchant Portal seleccionando un merchant especifico. SystemAdmin puede ver cualquier merchant; Partner solo los suyos.
4. Un Usuario, Muchos Negocios
Escenario: Dueno de varias empresas
Maria Rodriguez
maria@email.com — 1 sola cuenta
↓
UserMerchant (3 registros)
Farmacia Plaza
Rol: Admin
Farmacia Centro
Rol: Admin
Ferreteria Rodriguez
Rol: Admin
Maria es duena de 2 farmacias y una ferreteria. Entra al portal con un solo email, ve sus 3 negocios, y elige cual quiere administrar.
Escenario: Consultor de soporte externo
Luis (Consultor IT)
luis@techsupport.com — 1 sola cuenta
↓
Cada admin de merchant le asigna un rol
Farmacia Plaza
Rol: Manager
(asignado por Maria)
Mini Market Sol
Rol: Manager
(asignado por otro dueno)
Colmado Rivera
Rol: Cashier
(asignado por otro dueno)
Luis da soporte a 3 negocios de duenos distintos. Usa el mismo email para entrar a todos. Cada dueno decide que rol darle en su negocio. No tienen que ser del mismo partner.
Escenario: BCPOS (house partner) dando soporte
Ana (SystemAdmin BCPOS)
ana@bcposgroup.com — Office 365
↓
Entra al Merchant Portal
Seleccionar Partner
PharmaTech, HW Dist, o directo
↓
Seleccionar Merchant
Buscar entre miles de merchants
filtrar por partner, nombre, codigo
UX pendiente — Merchant Selector: Cuando un SystemAdmin o PartnerAdmin entra al Merchant Portal para dar soporte, necesita una forma eficiente de encontrar el merchant. Aplica a ambos roles pero con diferente escala:
| Rol | Ve | Escala | UX necesaria |
|---|
| SystemAdmin |
Todos los merchants de todos los partners |
Miles |
Filtrar por partner primero, luego buscar merchant por nombre/codigo. Paginacion server-side obligatoria. |
| PartnerAdmin |
Solo merchants de su partner |
Cientos |
Busqueda por nombre/codigo dentro de su partner. Puede ser client-side si son <500. |
| PartnerSupport |
Solo merchants de su partner (solo lectura) |
Cientos |
Mismo que PartnerAdmin pero sin acciones de escritura. |
5. Partners (Socios de Canal)
Partner: PharmaTech
Socio que maneja farmacias
Carlos (PartnerAdmin)
Gestiona merchants del partner
500 Farmacias
Merchants del partner
Carlos las ve todas
Regla: Cada merchant pertenece a exactamente un partner. Los merchants de BCPOS directo apuntan al "house partner" (BCPOS Group).
6. Pendiente: Web User vs POS Employee
Web User
Login: Office 365, Microsoft,
Google, o Magic Link
Central DB
POS Employee
Login: PIN numerico
4-6 digitos en la terminal
Merchant DB
Pendiente de definir: El Employee del POS y el User del portal son entidades separadas. Un gerente que usa el portal web Y la terminal POS tiene dos identidades sin conexion. Necesita design doc antes del merchant portal.
| Pregunta | Impacto |
|---|
| Si el Employee tiene PIN y tambien tiene cuenta web — como se conectan? | Merchant portal + POS |
| Un Admin web puede sobrepasar el PIN del Employee? | Seguridad de la terminal |
| Si un empleado trabaja en 2 tiendas del mismo dueno — como funciona el PIN? | Multi-location |
7. Findings — Para Discutir con el Dev
Estos son hallazgos del code review del commit de passwordless auth (3648d65). Requieren revision.
| # | Finding | Detalle | Severidad |
|---|
| 1 |
Invitation no crea UserMerchant ni PartnerUser |
El OAuth callback crea el ApplicationUser y liga el ExternalLogin, pero no crea el registro de membresia. Si la invitacion es para PartnerAdmin con PartnerId=5, el usuario queda sin PartnerUser. Lo mismo para merchant users — no se crea UserMerchant. El usuario existe pero no tiene acceso a nada. |
Critico |
| 2 |
No hay endpoint de invitacion para merchant users |
Solo existen CreatePlatformInvitation y CreatePartnerInvitation. No hay CreateMerchantInvitation. Como se invita a un Admin/Manager/Cashier de un merchant? |
Critico |
| 3 |
Invitation.TargetRole es string, no enum |
El campo usa strings ("SystemAdmin", "PartnerAdmin") en vez de los enums UserRole y PartnerRole que ya existen. Funciona, pero no hay validacion de tipo en compile time. |
Menor |
| 4 |
Dos flujos de login activos en paralelo (resuelto 2026-05-06, ADR-0068) |
El endpoint viejo POST /auth/login (password-based) fue removido per ADR-0068. Solo queda el flujo passwordless: POST /auth/login/initiate → magic link o OAuth → POST /auth/magic/verify o GET /auth/callback/{provider}. Las columnas ApplicationUser.PasswordHash y RequiresPasswordChange permanecen como dead-write data temporalmente; un follow-up migration las dropea. |
Resuelto |