feat: AutoBooking initial commit — PHP WordPress Plugin (REST API, wpdb, WP_User_Query)
This commit is contained in:
@@ -0,0 +1,211 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user