# 🗺️ Plan Maestro Detallado – Proyecto Gloria (Sprints & QA)

Este documento define el plan de ejecución por sprints, controles de seguridad y fases de validación colaborativa.

---

## 🎨 Referencia Visual (Mockup)

> **Importante:** Se ha creado un prototipo visual de alta fidelidad en la carpeta `mockup/`.
> Este prototipo (`index.html` + `styles.css`) debe utilizarse como **referencia estricta de diseño** (colores, tipografía, espaciado, animaciones) para la implementación en Next.js.
> NO copiar y pegar el código HTML directamente; implementar usando componentes React y Tailwind/CSS Modules según la arquitectura del proyecto.

---

## 🟢 Sprint 1 – Cimientos, Infraestructura y Seguridad Base

**Estado:** 🚧 En Progreso
**Inicio:** 2026-02-01
**Responsable:** Ops-Agent + Data-Agent
**Tech Stack:** Next.js 14, TypeScript, Tailwind CSS, Shadcn/ui, Prisma, SQLite, Redis, Docker

### Foco

Aislamiento de procesos y entorno Non-Root.

### Stack Definitivo

- **Runtime:** Node.js 22.x
- **Package Manager:** pnpm
- **Framework:** Next.js 14 (App Router)
- **UI Library:** Shadcn/ui (basado en Radix UI)
- **Database:** SQLite + Prisma ORM
- **Cache:** Redis
- **Infrastructure:** Docker + Docker Compose
- **User:** appuser (UID 1001) - Non-Root

### Tareas Técnicas Detalladas

1.1 ✅ Crear Dockerfile con usuario `appuser` (UID 1001). Prohibir `RUN sudo`.

1.2 ✅ Configurar `docker-compose.yml` con límites de CPU y memoria.

1.3 ✅ Configurar SQLite con permisos restringidos.

1.4 ✅ Validar `.env` con zod en arranque.

1.5 ✅ Inicializar Next.js 14 con App Router.

1.6 ✅ Configurar TypeScript 5.x y ESLint.

1.7 ✅ Configurar Tailwind CSS con paleta Nano Banana.

1.8 ✅ Configurar Shadcn/ui components.

1.9 ✅ Crear estructura de carpetas base.

1.10 ✅ Configurar Prisma schema con modelos iniciales.

1.11 ✅ Implementar middleware de seguridad (helmet.js).

1.12 ✅ Configurar scripts de desarrollo (dev, build, lint, typecheck).

### Testing & Seguridad

- ✅ Funcional: `pnpm install` y `prisma migrate` dentro del contenedor.
- ✅ Manual: `docker exec -it <id> whoami` ≠ root.
- ✅ Automático: Integrar helmet.js.

### Criterios de Aceptación

1. ✅ `pnpm install` funciona sin errores
2. ✅ `pnpm dev` levanta servidor en http://localhost:3000
3. ✅ Docker compose funciona con Redis
4. ✅ Prisma schema crea tablas correctamente
5. ✅ Tailwind muestra colores Nano Banana
6. ✅ Usuario `appuser` (UID 1001) corre en Docker
7. ✅ ESLint y TypeScript no tienen errores
8. ✅ Shadcn components renderizan correctamente
9. ✅ Variables de entorno validan con Zod
10. ✅ Documentación actualizada

---

## 🔵 Sprint 2 – Identidad Phone-First y Onboarding

### Foco

Validación sin contraseñas y privacidad.

### Tareas Técnicas

2.1 Rate limiting con Redis (IP + teléfono).

2.2 Formulario multi-paso persistente.

2.3 Fidelidad visual Nano Banana.

### Testing & Seguridad

- Funcional: Registro completo.
- Manual: Inyección XSS en nombre.
- Privacidad: IDs con UUID.

---

## 🟡 Sprint 3 – Triaje de Crisis y Agenda

**Estado:** 🟡 90% Completado

### Foco

Lógica sensible y disponibilidad.

### Tareas Técnicas

3.1 ✅ Motor de detección de crisis.

3.2 ✅ Sincronización Google Calendar con locks.

3.3 ⏳ Pendiente: Configurar servicio de email SMTP

- Usar nodemailer con transport TLS
- Pool de conexiones para eficiencia
- Variables de entorno: SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS

  3.4 ⏳ Pendiente: Funcionalidad de reacomodar citas

- Botón "Reacomodar" en dashboards (asistente y terapeuta)
- Modal para seleccionar nueva fecha/hora
- Verificar disponibilidad con Google Calendar API
- Actualizar evento en Google Calendar y SQLite
- Invalidar caché de disponibilidad en Redis
- Enviar email de confirmación al paciente

  3.5 ⏳ Pendiente: Job programado para email diario a las 10 PM

- Usar node-cron para schedule (0 22 \* \* \*)
- Consultar citas del día siguiente
- Enviar email a admin (Gloria) con resumen:
  - Hora de cita
  - Nombre del paciente
  - Teléfono
  - Tipo (crisis/regular)
  - Estado de pago
- Template HTML del reporte

### Testing & Seguridad

- ✅ Funcional: Alta en calendario.
- ✅ Manual: Manipulación consola.
- ✅ Resiliencia: Simulación fallo API.
- ⏳ Pendiente: Test de envío de emails SMTP.
- ⏳ Pendiente: Test de reacomodación de citas.
- ⏳ Pendiente: Test de job programado manual y automático.

---

## 🟠 Sprint 4 – Pagos y Roles

### Foco

Integridad financiera y control de acceso.

### Tareas Técnicas

4.1 ✅ Upload seguro (tipo/tamaño).

4.2 ✅ Middleware RBAC.

4.3 ✅ Dashboards de Asistente y Terapeuta.

4.4 ⏳ Pendiente: Upload de comprobantes con OCR (híbrido)

- Validar tipo de archivo (PDF, JPG, PNG)
- Validar tamaño máximo (5MB)
- Pre-procesar en cliente (escala de grises, contraste)
- OCR en servidor para extraer datos:
  - Monto
  - Fecha de transferencia
  - Clave/Referencia de transferencia
  - Nombre del remitente
  - Banco remitente
- Guardar archivo con nombre único
- Generar URL temporal
- Crear registro de Payment con datos extraídos

  4.5 ⏳ Pendiente: Botón "Ver Más Servicios" en landing

- Cambiar botón en sección de servicios
- Enlazar a /servicios

  4.6 ⏳ Pendiente: Contacto específico para cursos

- Formulario en página /cursos
- Campos: Nombre, Email, Curso de interés, Mensaje
- Email de notificación al admin

### Testing & Seguridad

- ✅ Funcional: Validación pago.
- ✅ Manual: Bypass dashboard.
- ⏳ Pendiente: Vulnerabilidades: Archivos maliciosos.
- ⏳ Pendiente: OCR accuracy test con diferentes comprobantes.

---

## 🔴 Sprint 5 – Voz y Notas Clínicas

### Foco

Privacidad extrema y ciclo de vida.

### Tareas Técnicas

5.1 Audio sandbox + Signed URLs.

5.2 Cron purga 7 días.

### Testing & Seguridad

- Funcional: Audio → WhatsApp.
- Manual: Acceso directo.
- Purga: Ejecución forzada.

---

## 🟣 Sprint 6 – Integración Final y Stress QA

### Foco

Estabilidad y cumplimiento.

### Tareas Técnicas

6.1 ⏳ Pendiente: Recordatorios WhatsApp (ya implementados en Sprint 3 con email en lugar de WhatsApp para evitar baneos de Meta).

6.2 ⏳ Pendiente: Log de auditoría.

### Testing & Seguridad

- Regresión completa.
- Cookies compliance.
- Stress test (50 usuarios).

---

## 📦 Nuevas Dependencias a Instalar (Sprints 3/4 Completación)

```bash
pnpm add nodemailer node-cron tesseract.js sharp pdf-parse @types/nodemailer
```

| Paquete             | Uso                                        | Sprint |
| ------------------- | ------------------------------------------ | ------ |
| `nodemailer`        | Enviar emails vía SMTP                     | 3      |
| `node-cron`         | Job programado para email diario           | 3      |
| `tesseract.js`      | OCR para extraer texto de imágenes         | 4      |
| `sharp`             | Pre-procesar imágenes (optimizar para OCR) | 4      |
| `pdf-parse`         | Extraer texto de PDFs                      | 4      |
| `@types/nodemailer` | TypeScript definitions                     | 3      |

---

## 📝 Protocolo de Colaboración en Testing

### Entregables del Agente

- Código fuente
- Comando de test
- Evidencia de ejecución

### Validación del Director Técnico

- Ejecución manual
- Prueba de seguridad
- Revisión de logs

### Aprobación

Solo tras validación manual se habilita la siguiente fase.

---

## 📋 Plan de Implementación Detallado - Sprints 3/4

### Fase 1: Sprint 3 Completación (10% Pendiente)

#### Tarea 1.1: Configurar Servicio de Email (SMTP)

- Archivos: `src/infrastructure/email/smtp.ts`, `src/lib/env.ts`, `src/lib/validations.ts`
- Variables: SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, ADMIN_EMAIL
- Specs: Transport TLS, pool de conexiones, manejo de errores con retry

#### Tarea 1.2: Funcionalidad de Reacomodar Citas

- Archivos: `src/app/api/calendar/reschedule/route.ts`, `src/components/dashboard/RescheduleModal.tsx`, `src/infrastructure/external/calendar.ts`
- Flujo: Modal → Verificar disponibilidad → Actualizar Google Calendar + SQLite → Enviar email al paciente

#### Tarea 1.3: Job Programado - Email Diario 10 PM

- Archivos: `src/jobs/send-daily-agenda.ts`, `src/lib/email/templates/daily-agenda.ts`, `src/app/api/jobs/trigger-agenda/route.ts`
- Schedule: `0 22 * * *` (10 PM todos los días)
- Destino: Admin (Gloria) - No se envía a asistente
- Contenido: Tabla HTML con citas del día siguiente (hora, paciente, teléfono, tipo, estado de pago)

### Fase 2: Sprint 4 Completación (15% Pendiente)

#### Tarea 2.1: Botón "Ver Más Servicios" en Landing

- Archivo: `src/components/layout/Services.tsx`
- Cambio: Botón en sección de servicios del landing → Enlaza a /servicios

#### Tarea 2.2: Contacto Específico para Cursos

- Archivos: `src/app/api/contact/courses/route.ts`, `src/lib/email/templates/course-inquiry.ts`, `src/app/cursos/page.tsx`
- Formulario: Nombre, Email, Curso de interés (dropdown), Mensaje
- Al enviar: Guardar registro + Email notificación a admin

#### Tarea 2.3: Upload de Comprobantes con OCR (Híbrido)

- Archivos: `src/app/api/payments/upload-proof/route.ts`, `src/lib/ocr/processor.ts`, `src/lib/ocr/templates.ts`, `src/components/dashboard/PaymentUpload.tsx`
- DB: Actualizar modelo Payment con campos extraídos por OCR
- Flujo:
  - Cliente: Drag & drop → Validación → Pre-procesar (escala grises, contraste)
  - Servidor: Validar → Guardar → OCR → Extraer datos (monto, fecha, referencia, remitente, banco) → Retornar URL + datos
- API: POST /api/payments/upload-proof
- Datos extraídos: extractedDate, extractedAmount, extractedReference, extractedSenderName, extractedSenderBank

---

## 📊 Cronograma de Ejecución

| Fase | Tarea              | Prioridad | Estimado  |
| ---- | ------------------ | --------- | --------- |
| 1.1  | Configurar SMTP    | Alta      | 1-2 horas |
| 1.2  | Reacomodar citas   | Alta      | 3-4 horas |
| 1.3  | Email diario 10 PM | Alta      | 2-3 horas |
| 2.1  | Botón servicios    | Baja      | 30 min    |
| 2.2  | Contacto cursos    | Media     | 2-3 horas |
| 2.3  | Upload con OCR     | Alta      | 4-5 horas |

**Total estimado:** 13-18 horas

---

## 🔍 Testing Checklist - Sprints 3/4

### Sprint 3

- [ ] Test de SMTP: enviar email de prueba
- [ ] Test de reacomodar: cambiar cita y verificar email enviado
- [ ] Test de job manual: trigger endpoint y verificar email diario
- [ ] Test de job programado: esperar a las 10 PM y verificar email automático

### Sprint 4

- [ ] Test de botón servicios: navegar a /servicios
- [ ] Test de contacto cursos: enviar consulta y verificar email
- [ ] Test de upload PDF: subida, OCR, extracción de datos
- [ ] Test de upload JPG: subida, OCR, extracción de datos
- [ ] Test de validación: intentar subir archivo inválido (tipo/size)
- [ ] Test de drag & drop: arrastrar archivo al componente

---

## ⚠️ Notas Importantes

1. **Reminders por WhatsApp:** Se decidió NO implementar recordatorios por WhatsApp para evitar baneos de Meta. Los recordatorios se manejan a través de:
   - Google Calendar (reminders de email a 24h antes - ya implementado)
   - Email diario a las 10 PM al admin con agenda del día siguiente (pendiente)

2. **Reacomodar Citas:** Flujo con confirmación enviada (email al paciente). El cambio es automático al recibir el email.

3. **Upload de Comprobantes:** Enfoque híbrido (pre-procesamiento en cliente, OCR en servidor) para extraer datos de cualquier banco sin plantillas específicas.

4. **Email Diario:** Se envía solo a admin (Gloria), no al asistente. Hora: 10 PM (configurable para timezone).

5. **Datos a Extraer del Comprobante:**
   - Monto
   - Fecha de transferencia
   - Clave/Referencia de transferencia
   - Nombre del remitente
   - Banco remitente

---

Documento de control operativo y aseguramiento de calidad – Proyecto Gloria