# Standard de Madurez — Paneles de Usuario BewPro

> Documento canónico. Define el nivel de madurez UX/funcional que debe alcanzar cada panel por tipo de usuario antes de considerarse "production-ready".
>
> Extraído de los paneles Reseller (`/reseller`) y Customer (`/my-projects` v2) — los dos paneles ya estabilizados al 100%.
>
> Última actualización: 2026-05-12

---

## Por qué este documento existe

BewPro sirve 5 tipos de usuario distintos. Cada uno tiene su propio panel y su propio journey. Sin un standard común, cada panel evoluciona ad-hoc y termina con experiencias inconsistentes: un botón "Comprar" en Reseller pero no en Visitor, un Help Center en Customer pero no en Admin, breadcrumbs en una vista y no en otra.

Este standard codifica los **15 ejes de calidad** que validamos como necesarios. Es el checklist para auditar un panel y decidir si está listo o tiene gaps.

---

## Los 15 ejes del standard

### 1 · Estructura base consistente
- Cada vista usa `<x-base-layout>` + `<x-skin-colors />` + `<x-admin-header>` con title/subtitle/icon/breadcrumbs.
- Container: `container-xxl` (no `container` ni `container-fluid` aleatorio).
- Breadcrumbs con jerarquía clara: Inicio → Sección → (subsección) → Vista actual.

### 2 · Onboarding visible
- Welcome card aparece para users fresh (< 24hs) en su primera carga del panel.
- 3 pasos numerados con CTAs claros, no walls-of-text.
- Dismissable con `?hide-welcome=1` y persistente vía URL (no cookie — cookie complica testing).
- Variantes según contexto: "sin nada cargado" vs "con algo en provisión".

### 3 · Stats / KPIs al top
- 4-5 counters key (total, activos, en curso, problemas, $$$ si aplica).
- Cada uno: icono + número grande + label.
- Responsive: `col-6 col-md-3` o `col-12 col-md-auto` para que se apilen bien en mobile.
- Si hay revenue, mostrar también monto proyectado cuando todos están en trial.

### 4 · Filtros + búsqueda
- Status filter badges aparecen cuando hay ≥2 items (no ensucia paneles vacíos).
- Cada badge: icono + label + count.
- Active state visual (color distinto).
- Search field cuando aplica (≥10 items o intent de búsqueda como customers/tenants).
- Filtros preservan query string al paginar (`->withQueryString()`).

### 5 · Empty states tipados
- **Sin datos en total**: icono + heading + descripción + CTA primary ("Comenzar nuevo proyecto").
- **Filtro no matchea**: copy distinto + link "Ver todos" para limpiar el filtro.
- Nunca dejar la vista en blanco — siempre indicar qué hacer.

### 6 · Lifecycle awareness
- Banners para eventos time-sensitive:
  - Trial expirando en X días
  - Pago pendiente / grace period
  - Action required (verificar email, completar perfil)
- Banner color-coded (warning/danger) con CTA directa a la acción.
- Computa sobre TODOS los items del user (no filtrado) — el banner no debe desaparecer al filtrar.

### 7 · Progress bars + ETA en async ops
- Provisión, sync, import: barra animada + texto estimado.
- ETA basado en historical average (no 100% lineal).
- Max 95% hasta que esté efectivamente done — si llega a 100 sin terminar, hay un bug.

### 8 · Acciones por item: primary + secondary
- Primary action visible (texto + icono, no solo icono): "Entrar al admin", "Pagar", "Ver detalle".
- Secondary: iconos pequeños agrupados (billing, eliminar, etc.) con tooltip.
- Disabled states con label claro: "Provisionando..." no "botón gris sin tooltip".

### 9 · Help / Self-service in-panel
- Centro de Ayuda en sidebar con FAQs estáticos por tema (3-4 temas × 3-4 preguntas).
- Accordion expandible.
- CTA al final: "¿No encontraste? Abrí un ticket".
- Contenido frequently-asked, no documentación exhaustiva.

### 10 · Integraciones críticas
- **Stripe Portal**: para customer-facing — un click hacia billing.stripe.com.
- **Support tickets**: link directo a `/support/new` con context (project_id si aplica).
- **Email confirmations**: passive — no requiere ack en panel.
- **Airtable sync**: backend, no expuesto excepto en Admin.

### 11 · Auth + permisos
- Middleware `auth + verified + role:X`.
- `authorize()` en show/update para data ajena → 403.
- `ensure.main.site` middleware para rutas que solo viven en bewpro.com (no en tenants).
- Soft-fail vs hard-fail: data ajena → 403, panel desactivado → redirect con flash.

### 12 · Responsive
- Mobile (375px): stats apilados, sidebar collapse, tabla con `table-responsive`.
- Tablet (768px): stats en línea, sidebar visible.
- Desktop (≥1200px): full layout.
- Iconos grandes ocultos en mobile, inline icons aparecen en su lugar (`d-md-block` + `d-md-none`).

### 13 · Flash + alerts
- `alert-success / danger / info` al top, debajo del breadcrumb.
- Session-based (no JS toast) — sobrevive a redirect.
- Auto-dismiss opcional con JS, pero no obligatorio.
- Para confirmaciones de ops async (provisión iniciada): SweetAlert con timer + CTA "Entendido".

### 14 · Footer útil
- Links a soporte, legal, blog.
- Last-sync info cuando aplique ("Estado actualizado hace 3 minutos").
- No es solo ornamental — es backup discovery path.

### 15 · Idioma + tono
- 100% español argentino (tuteo).
- Copy directo, accionable, sin jerga técnica innecesaria.
- Términos consistentes: "Activo" vs "Active", "Suspendido" vs "Paused" (siempre ES en UI, EN en code/DB).
- Mensajes de error con next step ("Contactá soporte si esto persiste"), no error codes crudos.

---

## Matriz de cumplimiento

| Eje | Reseller | Customer v2 | Admin | Visitor |
|-----|----------|-------------|-------|---------|
| 1. Estructura base | ✅ | ✅ | ✅ | ⚠️ (home no usa) |
| 2. Onboarding | ✅ | ✅ | ❌ | ❌ |
| 3. Stats top | ✅ | ✅ | ✅ | N/A |
| 4. Filtros + search | ✅ | ✅ | ✅ | ⚠️ (sin filtro precio/industria) |
| 5. Empty states | ✅ | ✅ | ⚠️ (sin CTA) | ❌ |
| 6. Lifecycle banners | ⚠️ (sin) | ✅ | ⚠️ (color sin badge) | N/A |
| 7. Progress + ETA | ✅ | ✅ | ✅ | N/A |
| 8. Primary + secondary actions | ✅ | ✅ | ⚠️ (bulk OK, primary regular) | ❌ (CTA "Comprar" missing) |
| 9. Help in-panel | ⚠️ (heredado de Client) | ✅ | ❌ | ⚠️ (FAQs escondidos) |
| 10. Integraciones | ⚠️ (Stripe N/A) | ✅ | ✅ | ⚠️ (checkout opaco) |
| 11. Auth + permisos | ✅ | ✅ | ✅ | N/A |
| 12. Responsive | ✅ | ✅ | ⚠️ (filtros tablet) | ⚠️ (sin CTA mobile) |
| 13. Flash + alerts | ✅ | ✅ | ✅ | ⚠️ (cookie banner OK) |
| 14. Footer útil | ✅ | ✅ | ⚠️ (genérico) | ⚠️ (sin pricing link) |
| 15. Idioma + tono | ✅ | ✅ | ⚠️ (mix EN en audit-log) | ✅ |

Leyenda: ✅ cumple · ⚠️ parcial · ❌ no cumple · N/A no aplica.

---

## Aplicación del standard

**Antes de declarar un panel "production-ready"**, todos los ejes aplicables deben estar en ✅. Los ⚠️ son aceptables si está documentado por qué (caso `Reseller > Stripe Portal`: no aplica porque el reseller no paga directamente).

**Trazabilidad**:
- Cada panel tiene su doc en `docs/bewpro2.0/paneles/` con tabla "Standard de madurez — checklist por eje".
- Los gaps abiertos se trackean ahí con prioridad.
- Cierre de un gap se documenta con fecha + commit ref.

---

## Referencias

- Paneles documentados: `01-customer.md`, `02-reseller.md`, `03-admin.md`, `04-visitor.md`
- Arquitectura técnica del portal: `docs/bewpro2.0/roadmap/06-user-portal.md`
- Roles & permisos: `docs/bewpro2.0/operaciones/roles-y-permisos.md`