# RUTA AL CIERRE — Especificación para Prototipo
### Plan, diseño general, diseño de interfaz y specs técnicas para construir en Claude Code

> **Supuesto de stack:** PHP/MySQL + JS vanilla + PWA, desplegable en Namecheap — el mismo patrón de FOSA 360 y la app de rutina de tiro (auth por token, single-file donde aplica). Si prefieres otro stack para este proyecto, es el primer punto a ajustar antes de dárselo a Claude Code.

---

## 1. PLAN

### Objetivo del prototipo
Un flujo jugable de principio a fin — candidato completa la simulación, sistema calcula el perfil de 6-7 dimensiones, reclutador lo consulta — usable con candidatos reales desde el día uno, aunque el contenido y el scoring todavía sean hipótesis por validar.

### Alcance V1 (prototipo)
- Track Vendedor completo (6 capítulos, Semana 1)
- Track Gerente de Ventas completo (Semana 1 + Semana 2 de liderazgo)
- Acceso del candidato por link único con token (sin registro/cuenta)
- Motor de scoring funcional con pesos editables en JSON
- Panel reclutador simple: login, lista de candidatos, perfil radar por candidato

### Fuera de alcance V1 (para versión funcional posterior)
- CMS para editar escenarios desde el navegador (V1 se edita el JSON directo)
- Multi-empresa / multi-cliente
- Analítica de validación (correlación score vs. desempeño real de venta)
- Exportación a ATS / integración con Yomp HRP
- Generación asistida por IA de nuevos escenarios

### Sprints sugeridos

| Sprint | Entregable |
|---|---|
| **1 — Motor y datos** | Esquema de BD, motor de scoring, JSON de escenarios cargado con el contenido de Semana 1 (Vendedor) |
| **2 — UI candidato** | Flujo jugable completo end-to-end para track Vendedor (pantallas 1-4 abajo) |
| **3 — Gerente + panel reclutador** | Semana 2 (liderazgo), login reclutador, lista + detalle con radar |
| **4 — Post-prototipo** | CMS de escenarios, multi-empresa, analítica de validación |

### Contenido
Los 9 escenarios (6 núcleo + 3 de Liderazgo Situacional) ya están completos y disponibles en `escenarios.json`, listos para colocarse directo en `/content/escenarios.json` del proyecto — Sprint 1 puede arrancar con contenido real, no placeholders.

---

## 2. DISEÑO GENERAL

### Flujo del sistema
```
Reclutador crea candidato → sistema genera link único (token)
→ Candidato abre link → Bienvenida → Selección de track (o ya viene asignado)
→ Recorre capítulos/escenarios → Motor calcula pesos en cada respuesta
→ Pantalla de cierre (genérica para el candidato)
→ Reclutador entra al panel → ve perfil radar del candidato
```

### Roles
- **Candidato:** solo juega. Nunca ve su propio desglose de dimensiones (evita que aprenda a "jugar" el test y filtrar info de evaluación).
- **Reclutador/Admin:** crea candidatos, genera links, consulta resultados.

### Modelo de datos conceptual
- **Candidato** → tiene un token único, un track asignado (vendedor / gerente), un estado (pendiente / en progreso / completado)
- **Escenario** → pertenece a un capítulo, una dimensión, un track (ambos / solo gerente)
- **Respuesta** → candidato + escenario + opción elegida + tiempo de respuesta
- **Resultado** → perfil calculado: puntaje 0-100 por dimensión, derivado de todas las respuestas

### Motor de scoring (lógica)
1. Cada opción de cada escenario tiene pesos predefinidos por dimensión (no necesariamente una sola dimensión — una opción puede tocar 2, ej. "consultas con tu gerente" toca FN medio-bajo Y disciplina de proceso)
2. Al completar el juego, el motor suma los pesos de todas las respuestas, agrupados por dimensión
3. Normaliza cada dimensión a escala 0-100
4. Guarda tanto el perfil final como las respuestas crudas (auditable, necesario para validación futura)
5. **Chequeo de consistencia:** si dos escenarios que miden la misma dimensión dan resultados muy divergentes, marcar el perfil con una bandera de "revisar" (posible respuesta al azar)

---

## 3. DISEÑO DE INTERFAZ

### Principios
- **Mobile-first, PWA** — candidatos completan esto desde el celular, muchas veces entre otras cosas
- **Tono de simulación de trabajo real**, no de videojuego infantil — nada de mascotas ni fantasía. El candidato ve mensajes de WhatsApp, notificaciones de CRM, llamadas — cosas que reconoce de su día a día real. Esto protege la validez aparente frente a candidatos a Gerente
- **Sin indicar nunca cuál opción es "mejor"** — ni en el copy, ni en el orden, ni visualmente (mismo estilo de botón para las 4 opciones)

### Paleta y tipografía (punto de partida, ajustable a marca Yomp)
- Base: grafito oscuro + blanco, un solo color de acento para CTAs (sugerido: azul medio — cámbialo si Yomp ya tiene paleta definida)
- Tipografía: Inter (consistente con tu línea gráfica en otros proyectos)
- Iconografía de escenario: burbuja de chat, ícono de llamada, ícono de CRM/notificación — para dar variedad visual sin ilustración custom

### Pantallas

**1. Bienvenida (candidato)**
- Contexto breve: "Estás a punto de vivir una semana simulada como [Vendedor/Gerente de Ventas]. Tus decisiones nos ayudan a conocerte. No hay respuestas correctas — sé tú mismo."
- Botón único: "Comenzar"

**2. Pantalla de escenario** (la pantalla que más se repite — el corazón de la app)
- Barra de progreso arriba: "Capítulo 2 de 6"
- Narrativa presentada como el medio que corresponda (mensaje de texto, notificación CRM, diálogo) — no como párrafo de examen
- 3-4 botones de opción, mismo tamaño y estilo visual, texto breve
- Sin timer visible de cara al candidato (el tiempo se mide en segundo plano, no se le presiona)

**3. Transición entre capítulos**
- Micro-pantalla: "Fin del Capítulo 2: Prospección" + botón "Continuar"
- Sirve de respiro narrativo y punto de guardado automático (si el candidato cierra la app, retoma aquí)

**4. Cierre (candidato)**
- Mensaje genérico: "Gracias por completar Ruta al Cierre. Tu reclutador revisará tus resultados y se pondrá en contacto contigo."
- Sin mostrar puntajes ni dimensiones

**5. Login reclutador**
- Usuario/contraseña simple, token de sesión

**6. Dashboard reclutador**
- Lista de candidatos: nombre, track, estado (pendiente/en progreso/completado), fecha
- Click en candidato completado → perfil

**7. Perfil de candidato (reclutador)**
- Radar chart con las 6 (o 7) dimensiones
- Tabla opcional de respuestas crudas, para auditoría
- Botón exportar/imprimir

---

## 4. ESPECIFICACIONES TÉCNICAS

### Stack
- **Backend:** PHP + MySQL
- **Frontend:** HTML/CSS/JS vanilla, PWA (service worker, manifest)
- **Auth:** token único por candidato (URL tipo `?t=abc123`, sin registro); usuario/password simple + token de sesión para reclutador
- **Hosting:** Namecheap (mismo patrón que tus otros proyectos)

### Estructura de archivos sugerida
```
/ruta-al-cierre
  /api
    candidatos.php
    respuestas.php
    resultados.php
    auth.php
  /content
    escenarios.json        ← contenido editable sin tocar código
  /public
    index.html              ← app candidato (PWA)
    admin.html               ← panel reclutador
    /assets
  /engine
    scoring.php              ← motor de cálculo de pesos
  sw.js
  manifest.json
```

### Esquema de base de datos (mínimo viable)

```sql
candidatos
  id, nombre, email, telefono, track ENUM('vendedor','gerente_ventas'),
  token VARCHAR UNIQUE, estado ENUM('pendiente','en_progreso','completado'),
  fecha_creacion, fecha_completado

respuestas
  id, candidato_id, escenario_id, opcion_elegida, tiempo_respuesta_segundos, timestamp

resultados
  id, candidato_id, dimension, puntaje (0-100), bandera_revisar BOOLEAN, fecha_calculo

reclutadores
  id, nombre, email, password_hash, token_sesion
```

### Formato de contenido (`escenarios.json`) — contrato de datos
Cada escenario se define así (ejemplo real, del set ya escrito):

```json
{
  "id": "ic_01",
  "capitulo": 2,
  "titulo": "La cuenta que nadie tocó",
  "dimension_principal": "IC",
  "track": "ambos",
  "medio": "notificacion_crm",
  "narrativa": "Llevas 3 semanas en el puesto. En el CRM ves una cuenta marcada inactiva: un cliente que dejó de comprar hace 8 meses. No está en tu lista de prioridades de esta semana.",
  "opciones": [
    { "texto": "La dejas, ya tienes suficiente con tu lista asignada", "pesos": { "IC": 1 } },
    { "texto": "La agregas para cuando tengas tiempo libre", "pesos": { "IC": 2 } },
    { "texto": "La llamas hoy mismo, antes de terminar tu lista asignada", "pesos": { "IC": 5 } },
    { "texto": "Preguntas a tu jefe si puedes tomarla oficialmente antes de actuar", "pesos": { "IC": 3, "DS": 4 } }
  ]
}
```

Este formato permite que Claude Code construya el motor y las pantallas sin que el contenido final (los 12+ escenarios de Semana 1 y Semana 2) esté 100% listo — se puede probar con placeholders y reemplazar el JSON después.

### Seguridad mínima para V1
- Sanitización de inputs en todos los endpoints PHP (prepared statements)
- Token de candidato de un solo uso funcional durante la sesión (no reautentica cada request, pero expira tras completar o tras X días)
- Rate limiting básico en `auth.php` para el login de reclutador

---

## 6. DESPLIEGUE EN NAMECHEAP

Mismo patrón que FOSA 360 y la app de rutina de tiro: hosting compartido con cPanel, sin build steps — se sube PHP/HTML directo, sin `npm install` ni `composer install`.

### Paquete que Claude Code debe entregar al cierre del Sprint 1
- **`db.sql`** — script único con las 4 tablas (candidatos, respuestas, resultados, reclutadores), listo para pegar tal cual en phpMyAdmin
- **`config.php`** — con 4 constantes de marcador de posición (`DB_HOST`, `DB_NAME`, `DB_USER`, `DB_PASS`) que edito con mis datos reales antes de subir
- Resto de archivos según la estructura de la sección 4, sin dependencias que requieran instalación en el servidor

### Dónde vive en el hosting
```
public_html/ruta-al-cierre/
```
(ajustamos la ruta si prefieres subdominio, ej. `evaluacion.tudominio.com`)

### Secuencia de instalación
1. Crear base de datos + usuario MySQL en cPanel
2. Pegar `db.sql` en phpMyAdmin → Go
3. Editar `config.php` con las credenciales reales
4. Subir todo por File Manager a `public_html/ruta-al-cierre/`
5. Confirmar que `escenarios.json` quedó en `/content/`
6. Probar con un candidato de prueba (link con token) y el login de reclutador

No necesita script de instalación con security key como MB9 (esa protección es para actualizar una BD de producción con datos vivos) — al ser una app nueva, aplica el patrón simple de FOSA 360: `db.sql` directo en phpMyAdmin.

---

*Paquete completo: este documento + `escenarios.json` (9 escenarios) son lo único que necesitas darle a Claude Code para arrancar Sprint 1 con contenido real.*