Manual del admin

Manual operativo para administradores en EMA Vault. Tu rol bypassea todos los canRead/canWrite checks pero todas tus acciones quedan auditadas vía SQL trigger SECURITY DEFINER.

Tu día típico

Tu vista al loguearte:

1. Dashboard ejecutivo — KPIs MRR, clientes activos, pipeline value, alertas.
2. Notifications — contratos por vencer, obligaciones pendientes, leads fríos.
3. System health — documentos fiscales rechazados, conectores con errores, EMI alertas.

Gestionar staff EMA

Crear usuario nuevo

1. Equipo Vault → + Nuevo usuario.
2. Email @emahealth.io + nombre + rol.
3. Click Crear → INSERT vault_users.
4. Avisar al usuario que entre con Google.

Cambiar rol

1. Equipo Vault → click usuario → Cambiar rol.
2. Nuevo rol del dropdown.
3. Save → user re-loguea para refresh del sidebar.

Desactivar usuario

1. Equipo Vault → click usuario → Desactivar.
2. is_active=false → user pierde acceso inmediatamente.
3. Datos asociados (audit, contratos firmados, leads owned) se preservan.

Precaución

Nunca elimines un row de vault_users — siempre desactivar. Los audit_log y otras tablas referencian al user_id.

Provisioning de clientes

Workflow completo

1. Verificar que el cliente esté creado como organization con tipo cliente (Pipeline lo crea al convertir, o crear manual en Organizations).
2. Llenar el slug (subdominio único).
3. Llenar fiscal_config (identificador tributario del país, certificado digital .p12, ambiente del organismo fiscal y tipos de documentos habilitados).
4. Click Provisionar productos → seleccionar Lab/Clinic/Well/etc.
5. Sistema:
   • Crea Aidbox Organization raíz.
   • Crea OAuth client per-tenant.
   • AES-GCM encrypt secret.
   • INSERT tenant_aidbox_credentials.
   • Loop POST X-Platform-Key a cada producto.
   • INSERT en emashared.tenants + tenant_products en cada DB.
6. Click Invitar admin del cliente → email + nombre.
   • Sistema crea user + user_roles lab_admin (o equivalente).
   • Cliente recibe email Loops con link de activación.
7. Verificar tab Productos → cada uno con status active.

Re-provisionar (idempotente)

Si algo falló, re-correr el provisioning no duplica recursos — el sistema verifica existencia antes de INSERT.

Suspender / reactivar tenant

1. Clientes → click tenant → Tab Productos.
2. Click Suspender en producto específico.
3. PATCH /api/platform/tenants/:id/status con status=suspended.
4. Tenant pierde acceso a ese producto pero datos se preservan.
5. Reactivar con click → status=active.

EMI access matrix

1. Ir a EMI access admin.
2. Ver matriz tenants × apps EMI (clinic, lab, well, vault, landing).
3. Toggle ON/OFF cada celda → tenant_emi_access.is_active.
4. Cuando OFF → drawer EMI escondido en ese product, calls 403.

Audit log

Audit log te muestra toda mutación de 12 tablas críticas:

• contracts, finance_entries, mrr_entries, fiscal_config
• organizations, tenants, vault_users, vault_permissions
• products, releases, leads, invoices

Filtros:

• User: quién.
• Table: qué tabla.
• Action: INSERT/UPDATE/DELETE.
• Date range: cuándo.

Secrets sanitizados automáticamente (passwords, API keys, etc.).

Ejemplos útiles

-- ¿Quién canceló contratos esta semana?
WHERE table_name='contracts' AND action='UPDATE'
  AND after->>'status'='cancelled'
  AND created_at >= now() - interval '7 days'

-- ¿Cambios fiscales en el último mes?
WHERE table_name='fiscal_config'
  AND created_at >= now() - interval '30 days'

-- ¿Quién activó/desactivó usuarios?
WHERE table_name='vault_users' AND action='UPDATE'

Permisos granulares

Si un usuario reporta que no puede acceder a algo:

1. Ver su rol en Equipo Vault.
2. Ver vault_permissions para ese rol × módulo.
3. Si can_read=false para módulo necesario:
   • Cambiar rol a uno más permisivo.
   • O agregar fila granular: INSERT vault_permissions (role='X', module='Y', can_read=true).

Configuración del sistema

Settings:

• Brand assets — logo, colors.
• CSP whitelist — agregar dominios al CSP (requiere deploy nuevo).
• Cron schedules — ver crons activos.
• Feature flags — toggle features experimentales.

Lo que SÍ puedes hacer (poder total)

• Cualquier acción en el sistema.
• Provisionar tenants.
• Cambiar fiscal config.
• Anular documentos fiscales emitidos.
• Desactivar usuarios.
• Cambiar permisos.
• Acceder a audit log completo.
• Configurar EMI access.

Lo que NO debes hacer (aunque puedas)

• Provisionar clientes sin contrato firmado — siempre confirmar.
• Cambiar fiscal_config sin aprobación del cliente — los cambios al organismo fiscal son legales.
• Eliminar rows — siempre soft-delete o desactivar.
• Compartir tu password — cada admin con su user, audit es por user_id.
• Skipping audit — el audit_trigger es defense-in-depth.
• Modificar audit_log directamente — es append-only por diseño.

Atajos útiles

Atajo	Acción
g luego c	Clientes
g luego e	Equipo Vault
g luego a	Audit log
g luego s	Settings

Buenas prácticas

• Audit log review semanal — revisa eventos críticos.
• Provisioning con doble check — confirma slug + fiscal antes.
• Invitations a clientes — verifica email correcto antes.
• Monitor crons — GitHub sync, alertas contratos.
• Rotar secrets cada 6-12 meses (PLATFORM_API_KEY, EMI_API_KEY, etc.) coordinado con productos cliente.
• Backup restore drill — Supabase backups son automáticos pero practicar restore.
• Onboarding staff EMA — crear vault_user inmediatamente al contratarlos.
• Offboarding staff EMA — desactivar el mismo día que terminan.