# Tarea: Crear plugin "autobooking-admin-dashboard" + arreglar bug crítico de rol

Eres un desarrollador senior de WordPress. Trabajas dentro de una plataforma tipo Uber
llamada **AutoBooking**, compuesta por varios plugins. Tu trabajo tiene DOS partes:
(A) arreglar un bug crítico de roles, y (B) crear el panel de administrador del dueño.

**Lee este documento COMPLETO antes de escribir una sola línea de código.** Hay reglas
de auditoría y de reutilización de código existente que son obligatorias y que cambian
la forma en que debes trabajar.

---

## Contexto del sistema existente (NO reinventar)

Plugins actuales que debes tomar como referencia de estilo y convenciones:

- **autobooking-driver-dashboard v2.0** (el más completo)
- **autobooking-passenger-dashboard v1.0**
- **autobooking-corporate-dashboard** ← USA ESTE como referencia de UI:
  ya tiene íconos SVG profesionales en tabs (sin emojis), idioma ES/EN, y layout limpio.
  El admin dashboard debe verse y comportarse consistente con este.
- **autobooking-roles** (tiene el bug a corregir)

Tablas de base de datos ya existentes (prefijo `wp_`, usar SIEMPRE `$wpdb->prefix`):

- `wp_ab_trips` — viajes
- `wp_ab_driver_status` — online/offline + telemetría GPS
- `wp_ab_driver_sessions` — sesiones de conductor
- `wp_ab_incidents` — incidentes SOS/pánico, incluye audio
- `wp_ab_zone_alerts` — hotspots/bonus
- `wp_ab_zone_alert_responses`
- `wp_ab_companies` — empresas corporativas
- `wp_ab_company_users` — empleados de empresas
- `wp_ab_invoices` — facturas
- `wp_ab_reviews` — ratings
- `wp_ab_scheduled_trips` — viajes programados
- `wp_ab_trip_positions` — posiciones GPS por viaje (**tabla de alto volumen**)
- `wp_autobooking_chat` — chat pasajero-conductor
- `wp_ab_driver_daily` — agregados diarios por conductor

**Antes de escribir código:** inspecciona los plugins existentes para deducir el esquema
EXACTO de cada tabla (nombres de columnas, tipos), las convenciones de naming de
funciones/hooks, y cómo registran sus endpoints AJAX. NO asumas columnas; verifícalas.

---

## ⚠️ REGLA #0 — Registro de cambios y verificación (LEER PRIMERO)

Este sistema ya tiene trabajo previo hecho (snippets, tablas, lógica de tarifas). El mayor
riesgo de esta tarea es **pisar o duplicar algo que ya existe**. Por eso, ANTES de tocar
nada y A MEDIDA que avanzas, mantén un archivo **`CHANGES.md`** en la raíz del trabajo con
TODO lo que toques. No basta con hacer los cambios; se necesita un registro legible por una
persona. Debe incluir:

- **ESTADO INICIAL:** antes de tocar tarifas/roles/cualquier cosa existente, anota qué
  encontraste y dónde (qué snippets, en qué tabla, qué columnas, qué versión de plugin).
  Pega los nombres exactos de tablas/columnas/funciones/snippets que vas a tocar.
- **POR CADA CAMBIO,** una línea con:
  `[AÑADIDO|MODIFICADO|ELIMINADO|EXTENDIDO] — archivo o tabla afectada — qué cambió — por qué`.
- **ELIMINACIONES:** evita borrar. Si algo te parece obsoleto o duplicado, NO lo borres;
  márcalo como "candidato a eliminar" en `CHANGES.md` y explica por qué, para que el
  dueño decida. Solo borra si es estrictamente necesario y déjalo registrado.
- **SNIPPETS:** si desactivas o modificas un snippet existente, guarda una COPIA del
  código original del snippet dentro de `CHANGES.md` antes de tocarlo, para poder revertir.
- **BASE DE DATOS:** por cada `ALTER`/`CREATE TABLE`, registra la sentencia exacta y si es
  reversible. Toda creación/alteración debe ir vía `dbDelta` en el hook de activación.
- **AL FINAL:** una sección **"Cómo revertir"** con los pasos para deshacer cada cambio
  mayor, y una lista de TODOs/decisiones pendientes que dejaste para el dueño.

> Trata `CHANGES.md` como parte del entregable, no como algo opcional.
> Si un cambio no está en `CHANGES.md`, es como si no hubiera pasado.

---

## PARTE A — Bug crítico en autobooking-roles

**Problema:** el plugin crea los roles `driver` y `driver_pending`, pero NO crea
`corporate_admin`, por lo que las empresas no pueden entrar a su dashboard.

Requisitos del fix:

1. Registrar el rol `corporate_admin` con capabilities mínimas necesarias
   (`read` + las custom caps que use el corporate-dashboard; dedúcelas del código).
2. Crear también una capability custom `manage_autobooking` para el admin del dueño,
   y asignarla al rol `administrator` de WordPress.
3. **MIGRACIÓN RETROACTIVA:** al activar, recorrer `wp_ab_companies` / `wp_ab_company_users`
   y asignar el rol `corporate_admin` a los usuarios corporativos que YA existen y
   que no lo tengan. Esto debe ser **idempotente** (correrlo dos veces no duplica nada).
   *(Las empresas ya creadas no reciben el rol automáticamente solo con cambiar el
   activation hook; por eso esta migración es obligatoria.)*
4. En desactivación NO borrar roles ni datos (solo limpieza de caps temporales si aplica).
5. Subir la versión del plugin y dejar un comentario de changelog.

---

## PARTE B — Plugin nuevo: autobooking-admin-dashboard

Estructura estándar de plugin WP: archivo principal con cabecera, `/includes`, `/assets/css`,
`/assets/js`, carga condicional de scripts solo en la página del dashboard.

**Acceso:** SOLO usuarios con la capability `manage_autobooking`. Verificar en CADA carga de
página y en CADA endpoint AJAX con `current_user_can('manage_autobooking')`; si no, abortar.

El dashboard se renderiza vía shortcode `[autobooking_admin]` en una página, con tabs
(íconos SVG, mismo estilo que corporate-dashboard, soporte ES/EN). Tabs:

### 1. RESUMEN (overview)
- KPIs en (casi) tiempo real: viajes hoy/semana, conductores online ahora,
  viajes activos, ingresos del día, incidentes SOS abiertos, conductores pendientes.
- Gráfico de viajes por día (últimos 30 días).

### 2. CONDUCTORES
- Lista de conductores con búsqueda y filtros (online/offline, rating, estado).
- **Cola de APROBACIÓN:** usuarios con rol `driver_pending`. Para cada uno mostrar sus
  datos y documentos. Acciones: **Aprobar** (cambia `driver_pending` → `driver`),
  **Rechazar** (con motivo), **Suspender**. Cada acción debe quedar registrada en un
  **LOG DE AUDITORÍA** (crear tabla `wp_ab_admin_audit`: `id`, `admin_user_id`, `action`,
  `target_type`, `target_id`, `meta` JSON, `created_at`).
- Nota: si el flujo de verificación de documentos (licencia, seguro, tarjeta de
  circulación, foto del vehículo) aún no existe, deja la UI preparada con placeholders
  claros y un `TODO` marcado; **no inventes columnas**.

### 3. EMPRESAS (corporativo)
- Lista de `wp_ab_companies`. Acción: **Activar cuenta corporativa**, que debe asignar
  el rol `corporate_admin` al/los usuario(s) de esa empresa (reusa la lógica de Parte A).
- Ver facturas (`wp_ab_invoices`) por empresa.

### 4. VIAJES
- Tabla de TODOS los viajes (`wp_ab_trips`) con filtros por fecha, estado, conductor,
  pasajero/empresa. **Paginación server-side.** Exportar CSV.
- Detalle de viaje: ruta en mapa (`wp_ab_trip_positions`), estados, chat, rating.

### 5. INCIDENTES / SOS
- Lista de `wp_ab_incidents` priorizando los abiertos. Reproducir el audio del SOS.
  Mostrar ubicación en mapa, conductor, viaje asociado. Acciones: marcar como
  atendido / resuelto, con nota. Registrar en audit log.

### 6. ZONAS
- Crear/editar/desactivar zone alerts (`wp_ab_zone_alerts`) tipo hotspot/bonus,
  dibujando el área en el mapa. Ver respuestas (`wp_ab_zone_alert_responses`).

### 7. CONFIGURACIÓN
- **IMPORTANTE — TARIFAS POR PAÍS YA EXISTEN:** el sistema ya tiene un mecanismo de
  tarifas por país, implementado como **SNIPPETS** (revisa el plugin "Code Snippets"
  si está instalado —tabla `wp_snippets`— y también `functions.php` del tema activo y
  del child theme) y como una o más **TABLAS** de base de datos. **NO crees un sistema
  nuevo.** Tu trabajo es:
    1. **LOCALIZAR** ese sistema: busca en `wp_snippets`, en archivos `functions.php`,
       y en `wp_options`/`wp_postmeta` cualquier cosa que contenga
       `tarifa`, `fare`, `rate`, `country`, `pais`, `price`, `km`, `base`, `minute`.
    2. **IDENTIFICAR** la(s) tabla(s) reales que guardan tarifa por país (estructura
       exacta: columnas, tipos, qué país, base, por km, por minuto, moneda, etc.).
    3. La UI de configuración debe **LEER Y ESCRIBIR sobre esa estructura existente**,
       NO sobre una nueva. Si la estructura está incompleta, EXTIÉNDELA con cuidado
       (`dbDelta`, columnas nuevas) en vez de reemplazarla.
    4. **Documentar en `CHANGES.md`** qué encontraste y dónde vive cada cosa.
- **Comisión de la plataforma** (% — global o por país si el sistema actual ya lo soporta;
  síguelo del mismo modelo que las tarifas por país).
- API key de Google Maps (reutilizar la existente; no duplicar).
- Datos de la plataforma (nombre, logo, email de notificaciones SOS).
- Si encuentras lógica de tarifas DUPLICADA o conflictiva entre snippets y tablas,
  **NO borres nada:** documéntalo en `CHANGES.md` y propón cuál debería ser la fuente
  única de verdad, dejándolo marcado como decisión pendiente para el dueño.

---

## Requisitos técnicos NO negociables

- **Seguridad:** TODOS los endpoints AJAX con `check_ajax_referer` (nonce) +
  `current_user_can`. TODAS las consultas con `$wpdb->prepare`. TODA salida con
  `esc_html`/`esc_attr`/`esc_url`/`wp_kses`. Sanitizar TODA entrada
  (`sanitize_text_field`, `absint`, etc.).
- La tabla `wp_ab_trip_positions` es de **alto volumen**: usa `LIMIT` y rangos; nunca
  `SELECT *` sin acotar. Si notas falta de índices relevantes para las queries del admin,
  créalos en activación (con `dbDelta`).
- Crea la tabla `wp_ab_admin_audit` en activación con `dbDelta`.
- Idioma ES/EN igual que corporate-dashboard (mismo mecanismo, no inventes otro).
- Mapa con Google Maps, reusando el patrón de carga de los plugins existentes.
- Íconos SVG inline en tabs (sin emojis). Estética consistente con corporate-dashboard.
- Código comentado, versión del plugin definida, sin warnings de PHP.

---

## Lo que NO debes hacer (fuera de alcance de este prompt)

- NO implementar el motor de matching/despacho automático (irá en otro prompt).
- NO implementar el cálculo de tarifas ni Stripe Connect/payouts (otro prompt).
  Solo deja la configuración de comisión/tarifa leyendo y escribiendo sobre el sistema
  de tarifas por país que YA existe.
- NO tocar la lógica interna de los otros plugins salvo el fix de roles de la Parte A.
- NO borrar snippets, tablas ni columnas. Marca candidatos a eliminar en `CHANGES.md`.

---

## Entregables

1. Plugin **autobooking-roles** actualizado (Parte A) con changelog.
2. Plugin nuevo **autobooking-admin-dashboard** completo y funcional (Parte B).
3. **`CHANGES.md`** completo (estado inicial, cada cambio, copias de snippets tocados,
   sentencias SQL, sección "Cómo revertir", TODOs pendientes).
4. Un breve **`README.md`** con: cómo instalar, qué capability se requiere, qué tablas crea,
   y una lista de TODOs/placeholders que dejaste pendientes (verificación de documentos,
   integración del motor de despacho, payouts, fuente única de verdad de tarifas si había
   conflicto).

---

**Empieza** inspeccionando los plugins, los snippets y el esquema real de las tablas antes
de escribir nada, y abre `CHANGES.md` con el ESTADO INICIAL. Si encuentras una ambigüedad
de esquema que te bloquee, documéntala y elige la opción más segura en vez de adivinar
columnas.