feat: comandos superadmin (ft admin) para onboarding enterprise white-label

[LucasLeguizamo]

feat: comandos superadmin para onboarding enterprise white-label

Contexto

free-admin ya tiene el tier Enterprise white-label (PR AppFreeticket/free-admin#230): plantillas 100% custom por Workspace.web_template (registry ENTERPRISE_TEMPLATES), dominios propios vía env ENTERPRISE_CUSTOM_DOMAINS, y plan enterprise asignado manualmente por un SUPER_ADMIN. Hoy TODO el onboarding es manual en el dashboard (/dashboard/master/clientes/[id]). Queremos que la mayor parte se pueda ejecutar desde el CLI si el usuario es superadmin, para que un agente (skill freeticket-enterprise, issue hermano en agent-skills) lo orqueste con un solo prompt.

Prerrequisitos en free-admin (bloqueantes, van primero)

El admin API (/api/admin, auth por AdminToken, contrato en /api/admin/openapi.json) hoy solo expone en PATCH /workspaces/{id}: name, slug, type, isPublished. Falta:

1. Extender PATCH /api/admin/workspaces/{id} con:
   • webTemplate (string | null) → workspace.web_template
   • customDomain (string | null) → workspace.custom_domain
   • customDomainVerifiedAt (datetime | null) → workspace.custom_domain_verified_at
2. Nuevo POST /api/admin/workspaces/{id}/plan — asignación manual de plan (reusar la lógica de assignPlanManually de /dashboard/master/clientes): si el workspace tenía suscripción Stripe activa, cancelarla antes de reasignar; si la cancelación falla, abortar sin tocar la fila. Body: { planSlug: "enterprise" | "spark" | "star" | "icon" }.
3. Registrar ambos en el OpenAPI (registerRoute) + audit log (recordAudit), como el resto de rutas admin.

Comandos CLI propuestos

Namespace ft admin (auth por AdminToken, separado de la API key de workspace):

ft admin login                                  # guarda AdminToken
ft admin workspaces get <slug|id>               # incluye webTemplate, customDomain, plan
ft admin workspaces set <slug|id> --web-template <clave>
ft admin workspaces set <slug|id> --custom-domain <dominio> [--verified]
ft admin plans assign <slug|id> enterprise      # POST /plan, muestra warning de Stripe
ft admin enterprise checklist <slug|id>         # imprime checklist de despliegue

Limitación conocida (documentar en el CLI, no resolver aquí)

El alta REAL de un dominio custom requiere hoy: editar la env ENTERPRISE_CUSTOM_DOMAINS en Vercel + agregar el dominio al proyecto + redeploy (serverActions.allowedOrigins se evalúa en build). ft admin workspaces set --custom-domain solo persiste la columna administrativa; el comando enterprise checklist debe imprimir los pasos manuales restantes. Cuando free-admin implemente F3b (resolución DB-backed de dominios), el checklist se reduce.

Criterios de aceptación

• Endpoints nuevos en free-admin con OpenAPI + audit + tests
• ft admin plans assign y ft admin workspaces set --web-template funcionan end-to-end contra un workspace de prueba
• ft admin enterprise checklist imprime el runbook completo (env, dominio Vercel, redeploy, verificación)
• Salida --json en todos los comandos (consumo por agentes/MCP)

Relacionado: AppFreeticket/agent-skills (skill freeticket-enterprise), AppFreeticket/free-admin PR #230.

🤖 Generated with Claude Code

[LucasLeguizamo]

Revisado contra el contrato admin en vivo (1.1.0): los prerrequisitos siguen sin estar.

• PATCH /api/admin/workspaces/{id} acepta solo name, slug, type, isPublished — sin webTemplate, customDomain ni customDomainVerifiedAt.
• No existe POST /api/admin/workspaces/{id}/plan.

Así que ft admin workspaces set --web-template y ft admin plans assign siguen bloqueados: sin esos endpoints solo se podrían fabricar inventando contrato.

Lo que sí llegó en admin 1.1.0 y avanza el issue por otro lado: GET/POST/DELETE /api/admin/tokens, o sea service tokens de plataforma. El CLI los expone en #33:

ft admin tokens create --data '{"name":"enterprise-onboarding"}'
ft admin tokens list
ft admin tokens revoke <id>

Eso saca a ft admin de depender de pegar la cookie better-auth.session_token a mano, que era el primer escalón del ft admin login que pedía el issue.

El resto queda anotado en CONTRACT-GAPS.md hasta que free-admin exponga los dos endpoints.

[LucasLeguizamo]

Pedido aguas arriba: free-admin#383 — webTemplate/customDomain/customDomainVerifiedAt en PATCH /api/admin/workspaces/{id} y POST /api/admin/workspaces/{id}/plan (con el aborto si falla la cancelación en Stripe). Con esos dos, los comandos de este issue se pueden construir sin inventar contrato.