# Design Doc — Hub de Autogestión WooCommerce (Coordenadas.co)

**Fecha:** 2026-09-01
**Estado:** Aprobado (diseño validado en sesión de brainstorming)
**Cliente objetivo:** Negocio con tienda en línea WordPress + WooCommerce
**Autor de referencia:** Coordenadas.co (agencia)

---

## 1. Propósito

Entregable single-file HTML (`hub-woo.html`) que permite a un cliente **no tech savvy**
autogestionar el 100% de su tienda WooCommerce sin depender de la agencia. El objetivo es
que la agencia **deje de recibir llamadas por tareas básicas** (subir productos, cambiar
precios, ver pedidos, hacer cupones, editar contenido) y que, cuando el cliente sí necesite
ayuda, la agencia pueda localizar y compartir la sección exacta del hub con un enlace directo.

## 2. Decisiones acordadas

| Decisión | Valor |
|---|---|
| Formato | HTML single-file autocontenido (`hub-woo.html`) |
| Marca | Coordenadas.co — design system: verde `#20C162`, amarillo `#FCCC09`, azul `#01C7FE`, naranja `#FF4200`, tipografía Baloo 2 (display) + Inter (body) |
| Tema | Toggle dark/light, default dark, persistente en localStorage |
| Idioma | Bilingüe ES/EN con toggle en vivo, sin recarga |
| Acceso | URL pública simple, sin login, no indexada |
| Credenciales | Solo URL de login + usuario; **sin contraseña** (guía de recuperación) |
| Alcance | 11 secciones de tareas + FAQ + Glosario (ver sección 4) |
| Videos | Embeds de YouTube en inglés (mismos videos para ES y EN), mapeados por `tutorial-id` en `CONFIG.videos` |
| Widgets | Buscador por tarea, checklists (localStorage), barra de progreso + logros, modo pasos rápidos, contenido plegable, glosario con tooltips |
| Tutoriales | Pasos numerados + mockups SVG ilustrativos del panel con resaltado |
| Videos | Embeds propios + YouTube, con fallback a pasos escritos |
| Para la agencia | Botón "Copiar enlace directo" por tutorial + botón flotante "Necesito ayuda" con contexto adjunto |
| Enfoque | **A**: single-file con bloque `CONFIG` editable + data embebida + engine vanilla JS |

## 3. Arquitectura del archivo

```
hub-woo.html
├── <head>: CSS completo (variables dark/light, responsive, animaciones)
├── <body>: shell HTML (header, sidebar, main, footer, botón flotante)
├── <script CONFIG>: datos del cliente editables por la agencia
│     • clientName, storeUrl, loginUrl, whatsappNumber, email, defaultLang
│     • videos: { 'tutorial-id': 'youtube-key' }
│     • sección comentada "✏️ EDITAR AQUÍ"
├── <script DATA>: base de contenido embebida (ES + EN)
│     • secciones[], tutoriales[] (id, título ES/EN, duración, video,
│       keywords, pasos[] {texto, mockup, resaltar}, checklist[])
│     • glosario[], faq[], logros[], I18N { es, en }
└── <script ENGINE>: vanilla JS
      • renderizador de secciones/tutoriales/pasos
      • renderizador de mockups SVG (plantillas + zonas resaltadas)
      • motor de checklists + localStorage, buscador, tooltips, i18n, dark/light, logros
```

### Principio de datos sobre presentación
Los tutoriales se definen como **objetos de datos**, no como HTML escrito a mano. Agregar un
tutorial nuevo = duplicar un bloque en `DATA` y cambiar texto; el engine lo renderiza solo.

```js
{
  id: "crear-producto",
  titulo: { es: "Agregar un producto nuevo", en: "Add a new product" },
  video: "youtube-key",
  pasos: [
    { texto: {es: "...", en: "..."}, mockup: "editor-producto", resaltar: "btn-titulo" },
    { texto: {es: "...", en: "..."}, mockup: "editor-producto", resaltar: "btn-publicar" }
  ],
  checklist: ["ir-a-productos", "llenar-titulo", "guardar"]
}
```

### Mantenimiento para la agencia
- Buscar el tutorial en el archivo → copiar su URL con `#id-tutorial` → enviar al cliente.
- El engine no requiere cambios salvo agregar nuevas plantillas de mockup o widgets.

## 4. Estructura de contenido

> **Nota de idioma:** todos los videos son de YouTube en inglés y se usan igual para las
> versiones ES y EN de la documentación (decisión del cliente). Los embeds van mapeados en
> `CONFIG.videos` por `tutorial-id`.

### 🏠 Home / Inicio
- Buscador grande "¿Qué quieres hacer hoy?" (filtra en vivo)
- 8 tarjetas de acceso rápido + tarjeta "Empieza aquí" (primer login)
- Barra de progreso general + insignias de logros
- Botón "Tu acceso" (URL de login + usuario)

### 🔑 Tu acceso (prioridad alta) — sin video
1. Cómo entrar a tu tienda (URL + usuario, sin contraseña)
2. Recuperé mi contraseña (reseteo de WordPress)
3. Cerrar sesión / seguridad básica

### 📦 Productos y catálogo (prioridad alta)
1. Agregar un producto nuevo → 🎬 `6OJSAn6A5mA`
2. Tipos de producto en WooCommerce (cuándo usar cada uno) → 🎬 `HhOf9260a2o`
3. Subir fotos a un producto + arreglar imágenes borrosas → 🎬 `9wte-83NSnI`
4. Cambiar precio o stock
5. Organizar con categorías y etiquetas → 🎬 `kPJnJomWU4Y`
6. Imagen a una categoría de producto → 🎬 `oTaBcQG9oNI`
7. Variaciones (tallas/colores) → 🎬 `lWQkNR38_EM`
8. Producto agrupado (grupo de productos) → 🎬 `MahrLowOGng`
9. Quitar/desactivar un producto

### 🛒 Pedidos y envíos (prioridad alta)
1. Ver mis pedidos (lista + filtros) → 🎬 `rjS3mbiLN_c` (overview) + 🎬 `3nfmJcPR3I4` (in-depth)
2. Cambiar el estado de un pedido (pendiente → enviado)
3. Ver y descargar una factura
4. Manejar devoluciones y reembolsos → 🎬 `mFNAY2dsXwY`
5. Notas del cliente en el pedido
6. Agregar costos de envío a la tienda → 🎬 `3d7yNpIi2_8`

### 🎟️ Cupones y promociones (prioridad alta)
1. Crear un cupón de descuento (% o monto fijo) → 🎬 `gi-MhzDSdb4`
2. Envío gratis (cupón o regla global)
3. Promo por fechas (cuándo activar/desactivar)
4. Restricciones (mín. compra, uso único, categoría)

### ✏️ Mi web y contenido (prioridad alta)
1. Editar el texto de una página (Elementor) → 🎬 `Z4fUt4WpRhE`
2. Cambiar el banner de la portada
3. Agregar una página nueva y añadirla al menú → 🎬 `ZsbVIO-1u8g`
4. Actualizar el menú de navegación → 🎬 `Zyl-lRH-5Os`
5. Editar el footer (tema Astra) → 🎬 `FOU5UzlRyhk`

### 💰 Pagos y facturación
1. Verificar que un pago llegó (panel de pasarela)
2. Conectar PayPal → 🎬 `5tCIpGAxUh4`
3. Conectar Stripe → 🎬 `h0vvueoj16k`
4. Configurar impuestos → 🎬 `s-fgmY6nwJA`
5. Dónde cae el dinero (retiros/transferencias)
6. Emitir factura/recibo al cliente

### 👥 Clientes y cuentas — sin video
1. Ver la lista de clientes y su historial
2. Responder a una reseña
3. Cambiar el rol de un usuario (agregar empleado)

### 📊 Reportes y ventas
1. Ver cuánto vendí (reportes de WooCommerce) → 🎬 `B6XS3Z1reVw`
2. Producto más vendido / por categoría
3. Entender Google Analytics en simple

### 📧 Correos de tu tienda (solo correos automáticos del sitio; sin marketing)
> Reemplaza a la sección de marketing promocional. Solo educa sobre los correos que el sitio
> envía automáticamente: pedido nuevo, cuenta nueva/usuario, pago fallido, etc.
1. Qué correos envía tu tienda sola (pedido nuevo, cliente nuevo, pago fallido…) → 🎬 `g_wR3VWvATg`
2. Configurar los correos del sitio (ajustes de email) → 🎬 `2vtzGc92tFU`

### ⚙️ Ajustes avanzados — solo de vez en cuando (Guided Tours de WooCommerce)
> Tutoriales que el cliente quizá quiera tocar una vez cada tanto. Agrupados aparte para
> mantener la operación diaria simple.
1. Configuración de productos (Products Settings) → 🎬 `FEmwJsE8xDY`
2. Configuración de impuestos (Tax Settings) → 🎬 `0aPtye5ba4A`
3. Ejemplo de tasa de impuesto → 🎬 `HC2IUnJSJro`
4. Zonas de envío (solo productos físicos) → 🎬 `1HhBEbIMqAQ`
5. Envío plano (Flat Rate Shipping) → 🎬 `a5N99INu6Fs`
6. Retiro en tienda (Local Pickup) → 🎬 `HHYOQbcD2KE`
7. Envío gratis (Free Shipping) → 🎬 `7s-SHvVR2Os`
8. Configuración del checkout → 🎬 `zoejwJfXops`
9. Configuración de cuentas → 🎬 `AGZSeX5I-wo`
10. Configuración de correos → 🎬 `2vtzGc92tFU` *(referencia repetida del tutorial principal)*

### ❓ Ayuda / Preguntas frecuentes — sin video
- FAQ accordion con 15-20 preguntas típicas
- Glosario de términos con tooltips
- "¿Todavía atascado?" → botón WhatsApp con contexto

**Cada tutorial tiene:** pasos numerados + mockup ilustrado del panel + video (si aplica) +
checklist guardable + botón "Copiar enlace directo" para la agencia.

**Total aproximado: ~51 tutoriales, ~22 videos únicos de YouTube.**

## 4.1 Catálogo de videos (mapa `tutorial-id → youtube-key`)

| Tutorial | Video ID |
|---|---|
| Agregar un producto nuevo | `6OJSAn6A5mA` |
| Tipos de producto | `HhOf9260a2o` |
| Fotos + imágenes borrosas | `9wte-83NSnI` |
| Categorías y etiquetas | `kPJnJomWU4Y` |
| Imagen a categoría | `oTaBcQG9oNI` |
| Variaciones | `lWQkNR38_EM` |
| Producto agrupado | `MahrLowOGng` |
| Ver mis pedidos (overview) | `rjS3mbiLN_c` |
| Ver mis pedidos (in-depth) | `3nfmJcPR3I4` |
| Devoluciones y reembolsos | `mFNAY2dsXwY` |
| Costos de envío | `3d7yNpIi2_8` |
| Crear cupón | `gi-MhzDSdb4` |
| Editar página (Elementor) | `Z4fUt4WpRhE` |
| Página nueva + menú | `ZsbVIO-1u8g` |
| Menú de navegación | `Zyl-lRH-5Os` |
| Footer (Astra) | `FOU5UzlRyhk` |
| Conectar PayPal | `5tCIpGAxUh4` |
| Conectar Stripe | `h0vvueoj16k` |
| Configurar impuestos | `s-fgmY6nwJA` |
| Reportes / Analytics | `B6XS3Z1reVw` |
| Correos automáticos (qué envía el sitio) | `g_wR3VWvATg` |
| Configurar correos del sitio | `2vtzGc92tFU` |
| Ajustes avanzados: Products Settings | `FEmwJsE8xDY` |
| Ajustes avanzados: Tax Settings | `0aPtye5ba4A` |
| Ajustes avanzados: Tax Rate Example | `HC2IUnJSJro` |
| Ajustes avanzados: Shipping Zones | `1HhBEbIMqAQ` |
| Ajustes avanzados: Flat Rate Shipping | `a5N99INu6Fs` |
| Ajustes avanzados: Local Pickup | `HHYOQbcD2KE` |
| Ajustes avanzados: Free Shipping | `7s-SHvVR2Os` |
| Ajustes avanzados: Checkout Settings | `zoejwJfXops` |
| Ajustes avanzados: Accounts Settings | `AGZSeX5I-wo` |
| Ajustes avanzados: Emails Settings | `2vtzGc92tFU` *(repetido)* |

## 5. Widgets y mecánicas interactivas (vanilla JS)

1. **Buscador "¿Qué quieres hacer hoy?"** — filtra en vivo por títulos, pasos y keywords.
   Soporta frases naturales ("no me llegan los pedidos" → "Ver mis pedidos"). Estado vacío
   empático + botón WhatsApp con el término buscado.
2. **Checklists guardables (localStorage)** — por `tutorial-id`, barra de progreso por
   tutorial ("3 de 7 pasos"), botón "Reiniciar checklist".
3. **Barra de progreso + logros** — % global de tutoriales completados en el sidebar.
   Logros: 🏆 Primer producto, 🚀 Primer pedido procesado, 🎉 Primera promo, 💰 Vi mis ventas.
   Toast de celebración al desbloquear.
4. **Modo pasos rápidos** — toggle que oculta teoría/videos/tips y muestra solo pasos
   numerados con mockup en fila.
5. **Contenido plegable** — tutoriales colapsables con duración estimada ("2 min"), FAQ en
   accordion, tabs para tutoriales largos.
6. **Glosario con tooltips** — términos marcados (Panel, Plugin, Stock, Pasarela de pago)
   con tooltip al hover/click + sección Glosario completa.

### Extras
- **Botón flotante "Necesito ayuda"** — abre `wa.me/NUMERO?text=...` con mensaje que
  incluye la sección/tutorial actual, su enlace directo y "estoy en el paso X de Y".
- **Toggle ES/EN** y **toggle dark/light** — ambos persistentes en localStorage.

## 6. Mockups SVG del panel

- ~12 plantillas SVG reutilizables: dashboard, lista de productos, editor de producto,
  lista de pedidos, detalle de pedido, cupones, páginas, clientes, reportes, ajustes.
- Zonas marcables (`data-zona`); el mockup de cada paso = plantilla + array de zonas
  resaltadas → círculo rojo pulsante + leyenda "Haz clic aquí".
- Textos neutros (sin datos reales): "Producto de ejemplo", "$25.000".

## 7. Modelo de datos

- `CONFIG`: nombre, URLs, WhatsApp, email, idioma default, `videos` (mapa tutorial-id → youtube-key).
- `DATA.secciones[]`: id, icono, color, título ES/EN, etiqueta opcional (p. ej. "rara vez" para Ajustes avanzados).
- `DATA.tutoriales[]`: id, sección, título ES/EN, duración, video (opcional), keywords,
  pasos[], checklist[].
- `DATA.glosario[]`, `DATA.faq[]`, `DATA.logros[]`.
- `I18N = { es: {...}, en: {...} }` para toda la UI.

## 8. Casos límite manejados

- **localStorage bloqueado/incógnito** → checklists funcionan en memoria, aviso suave.
- **Buscador sin resultados** → mensaje empático + WhatsApp con el término.
- **Video sin conexión** → fallback "Abrir en YouTube"; los pasos escritos siempre están.
- **Tutorial sin checklist** → se omite la barra de progreso.
- **Apertura por `file://`** → todo funciona; embeds requieren internet (con fallback).
- **Accesibilidad básica** → tooltips por teclado, contrastes mínimos, foco visible.

## 9. Verificación al terminar

1. Abrir en Chrome, Edge y Firefox.
2. Probar: toggle dark/light, toggle ES/EN, checklists + recarga (persistencia), buscador
   con términos reales ("cupón", "pedido", "no llegan"), copiar enlace, botón WhatsApp con
   contexto, modo rápido, logros desbloqueándose.
3. Validar en viewport mobile (sidebar colapsa).
4. Validar apertura por `file://` y sobre hosting estático.

## 10. Fuera de alcance (por ahora)

- Login/autenticación real del hub.
- Almacenamiento de contraseñas del cliente.
- Backoffice separado para edición de contenido.
- Soporte multi-tienda en un solo archivo (una instancia por cliente).
- Integración con CMS de la agencia.
- Marketing promocional (emails promocionales, carrito abandonado, popups de captura) —
  se documentan únicamente los correos automáticos del sitio.