212 lines
11 KiB
Markdown
212 lines
11 KiB
Markdown
# 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.
|