# Vale AI — Master Doc (v5.1)

**Owner:** Franco (Supraide) · **Copilotos de Desarrollo:** Gemini + Claude Code
**Estado:** Locked / Final para Ejecución · **Fecha:** 7 de junio de 2026 · **Versión:** 5.1
**Para:** equipo Rivas + Claude Code · **Fuente de verdad absoluta** para la Fase 0 y el refactor.

> 🤖 **Directriz Crítica de Ingeniería para Claude Code y Rivas:** Este documento rige el desarrollo. No hay más debate de arquitectura. Cualquier script generado a partir de ahora debe seguir los contratos de datos, las prioridades de la Fase 0 y las políticas de cumplimiento de APIs aquí establecidas.

---

## 1. Visión del producto

Vale es una empleada de IA para negocios locales en LatAm (barberías, clínicas estéticas, odontología, médicos y servicios generales) diseñada para democratizar el acceso a la tecnología y empoderar a los pequeños comercios.

Tres pilares operativos:

1. **Configuración conversacional (Chat-first):** el dueño crea y configura a su asistente hablando con ella por chat (web/WhatsApp). Vale lo entrevista, interpreta sus servicios y se autoconfigura.
2. **Infraestructura unificada desde el Día 0:** Google Calendar es la fuente de verdad y el motor de disponibilidad nativo para todos los planes.
3. **Generadora de valor y retención:** construye fichas de estilo, retiene clientes mediante predicción de frecuencia, extrae testimonios y reactiva bases de datos inactivas.

---

## 2. Estado actual del sistema

- **Infraestructura:** Multi-tenant en PHP puro sobre cPanel. **Producción:** `valeai.app` (cPanel limpio, Supraide LLC). **Staging/Dev:** `vale.supraide.com` (entorno de desarrollo heredado).
- **Inteligencia:** Agente Gemini con Function Calling vía `ToolRegistry` y `FunctionDispatcher`.
- **Onboarding:** Flujo conversacional donde Gemini arma el perfil del negocio.
- **Canales activos:** Widget de chat web e integración con Meta Cloud API (WhatsApp).
- **Agendamiento:** Google OAuth 2.0 + Google Calendar.
- **Persistencia:** MySQL + tabla `agent_logs` capturando llamadas, funciones y tokens.
- **Bug crítico (Fase 0):** Error `400 INVALID_ARGUMENT` en el segundo mensaje por el manejo de firmas de pensamiento del modelo. Fix local listo para despliegue.

---

## 3. Stack tecnológico definitivo

| Capa | Tecnología | Justificación Estratégica |
| --- | --- | --- |
| **Backend** | PHP puro (sin frameworks) | Máxima velocidad, bajo costo, despliegue inmediato en cPanel. |
| **Inteligencia Artificial** | Google Gemini (`gemini-3.5-flash` principal, `gemini-2.0-flash` fallback) | Consumido vía **Vertex AI** para cumplir requisitos GCP del hackathon y habilitar el procesamiento seguro de PHI a futuro. |
| **Autenticación y Agenda** | Google OAuth 2.0 + Google Calendar API | Fuente de verdad desde el Día 0. Scopes no-sensibles (`openid`, `email`, `profile`, `calendar.app.created`, `freebusy`) para evitar la verificación de Google. |
| **Base de Datos** | MySQL (utf8mb4_unicode_ci) | Separación multi-tenant por `tenant_id` indexado en todas las queries, vía Wrapper PDO defensivo. |
| **WhatsApp** | Meta Cloud API | Webhook directo, menor costo e interactividad nativa (chips/botones). |
| **Emails de Conversión** | **Resend API** | Reemplaza al SMTP compartido de cPanel para asegurar entregabilidad en bandeja principal (requiere verificación de dominio por DNS). |
| **Pasarela de Pagos** | Stripe (Merchant US: Supraide LLC) | Checkout y Webhooks nativos para suscripciones. |

> 🚫 **Decisión de ingeniería:** el sistema se mantiene en PHP puro sobre cPanel. La robustez radica en la organización limpia del código (patrón Adapter), no en sobreingeniería de plataforma. **El código no se reescribe; solo se muda.**

---

## 4. Estrategia de monetización (PLG Freemium)

Crecimiento guiado por el producto, aportando valor real desde el plan gratuito y apalancando la conversión en la visibilidad del dinero en riesgo. Precios sujetos a validación regional durante el MVP.

| Plan | Precio Target | Valor Real (Lo que DA) | Gatillo de Conversión (Lo que VENDE) | Guardrail de Costo / Anti-Abuso |
| --- | --- | --- | --- | --- |
| **Vale Free** | **$0** | Widget web: responde FAQs y **agenda citas reales en Google Calendar**. | Solo funciona si el cliente visita la web. Sin WhatsApp ni recordatorios salientes. | **Doble capa:** máx. 30 mensajes/día por tenant (cap de costo) + throttle por IP/sesión (anti-bot). |
| **Vale Growth** | **$23/mo** | Todo lo anterior + **WhatsApp nativo** y **recordatorios de citas** para reducir *no-shows*. | Canal reactivo; no sale a buscar ventas de forma autónoma. | Sin límites comerciales estándar (uso justo de Meta). |
| **Vale Pro** | **$73/mo** | **Prospectado y Reactivación** de clientes, optimización en Google Maps y alertas al staff. | El techo completo de automatización comercial. | Monitoreo estricto de plantillas de marketing aprobadas. |

**Trigger de conversión:** al final de cada jornada, Vale envía vía Resend un correo al dueño Free con analíticas ("hoy agendé 3 citas / $90 asegurados; sin recordatorios mañana podrías perder $31; activá Growth") + enlace de pago Stripe.

---

## 5. Arquitectura: el cerebro orquestador

```
CANAL (Web Chat / WhatsApp / Dashboard) ──► [ChannelAdapter] ──► AgentInput
                                                                       │
                                                                       ▼
┌─────────────────── ORCHESTRATOR (El Cerebro) ───────────────────┐
│ 1. Carga Contexto Exclusivo (Constitución + Config del Tenant)  │
│ 2. Unifica Historial mediante buildHistory()                    │
│    -> REGLA DE FIX: corre mandatoriamente con thinkingBudget:0  │
│       (Thinking OFF). No se genera signature.                   │
│    -> ROBUSTEZ: buildHistory() preserva el thoughtSignature     │
│       SOLO como salvaguarda pasiva si un fallback lo emite.     │
│ 3. Consulta Gemini vía Vertex AI + ToolRegistry                 │
│ 4. Bucle de Function Calling (FunctionDispatcher, máx 4)        │
│ 5. Consolida la estructura estricta de salida                   │
└─────────────────────────────────────────────────────────────────┘
                                                                       │
                                                                       ▼
PERSISTENCIA (messages + agent_logs) ◄── [ChannelAdapter] ◄── AgentOutput
```

**Contrato de extensibilidad:** canales y verticales son agnósticos al núcleo. Agregar un canal o rubro = registrar tools en `ToolRegistry` + tablas secundarias, sin tocar el motor.

---

## 6. Verticales y funciones de alto valor

### A. Servicios locales (Barberías, Estética, Spas) — *Live con el lanzamiento*

- **Ficha de Estilo:** extrae especificaciones ("navaja al 0.5 y cera mate") y las guarda en `contact_preferences`.
- **Alerta de Contexto al Staff:** 15 min antes de la cita, alerta interna al panel del empleado asignado.
- **Recordatorio de Frecuencia:** si el cliente asiste cada ~21 días, al día 20 Vale le escribe para bloquear su espacio.
- **Filtro de Amor (Feedback No-Gated):** Vale pide feedback a **todos** los clientes (tabla `testimonials`, evidencia XPRIZE). **Cumplimiento Google/FTC:** el enlace de Google Maps va a *todos* sin discriminar por sentimiento. Si el feedback fue negativo, dispara una alerta al dueño para **control de daños / service recovery en el local** (resolver el problema, nunca frenar la reseña).

### B. Vertical Médico / Odontológico — *Faseado*

- **Etapa 1 — Administrativa (con el lanzamiento):** perfiles generales de pacientes (identidad, contacto, histórico de citas) y agendas de doctores. **Riesgo PHI: cero** (no recopila ni procesa datos clínicos en la IA).
- **Etapa 2 — Clínica (post-lanzamiento, dentro de la ventana):** historias clínicas. Requiere consentimiento firmado, cifrado en reposo (AES-256-GCM), auditoría (`patient_access_log`) y Vertex AI bajo BAA.

### C. Módulo de Prospectado y Reactivación (Pro)

Campañas sobre la base de clientes antiguos. **Cumplimiento Meta:** solo **plantillas pre-aprobadas** (Utility/Marketing) con variables dinámicas, **atestación de opt-in del dueño** y monitoreo de tasa de bloqueos para detener la campaña ante anomalías. Se respeta `STOP/SALIR`.

---

## 7. Modelo de datos (estado real)

**Existentes y operativas hoy:** `tenants`, `vale_config`, `services`, `conversations`, `messages`, `contacts`, `agent_logs`.

**En desarrollo activo (target lanzamiento):** `tenants.deleted_at` / `tenants.is_test` / `tenants.relationship` / `evidence_consent`; `payments`; `testimonials`; `contact_preferences`; `staff`; `appointments` / `orders` / `leads` / `followups`.

**Fase médica (post-core):** `patients`, `doctors`, `patient_medical_history` (cifrada), `patient_visits` (cifrada), `patient_access_log`.

> **Regla dura:** prohibido HARD DELETE sobre `tenants`. Todo borrado es soft-delete.

> **Convención de migraciones:** los scripts `.sql` viven en `/database/migrations/` con nomenclatura correlativa. Toda alteración nueva sigue la secuencia; el próximo script de la Fase 0 es `026_soft_delete_evidencia.sql`. (Documentá solo las migraciones que existen de verdad en tu entorno; las fechas/timestamps que valen son los reales de cada archivo, no los que se escriban a mano.)

---

## 8. Protocolo de desarrollo y Git (innegociable)

Flujo **Local-First** para mitigar riesgos de seguridad y habilitar a Claude Code:

```
[Tu PC Local] ──(Claude Code / Git Commits)──► [GitHub (Repo Privado)]
      │
      └──────────────(Deploy)──────────────► [cPanel Live]
```

**Protocolo de despegue, en orden:**

1. **Bajar el código:** descargar la estructura completa actual desde cPanel a la máquina local.
2. **Escaneo de secretos (gate de seguridad)** — antes de añadir nada a Git:

   ```bash
   grep -rniE "(api[_-]?key|secret|token|password|sk_live|EAAG)" --include=*.php .
   ```

   Cualquier secreto encontrado se mueve a `.env` o `config.php` y se reemplaza por una variable/constante.

3. **Escaneo de URLs antiguas (solo si hay migración de dominio):**

   ```bash
   grep -rni "vale.supraide.com" --include=*.php .
   ```

4. **Plantillas de configuración:** mantener los reales en `.gitignore` y commitear `config.example.php` y `.env.example` con placeholders.
5. **Perímetro del servidor:** bloquear la descarga del historial si el repo vive en el web root, agregando al `.htaccess`:

   ```apache
   RedirectMatch 404 /\.git
   ```

---

## 9. Roadmap de la Fase 0 (orden de ejecución — no se altera)

1. **Git Base:** repo privado local, `.gitignore` extendido, auditoría de secretos, primer commit honesto del baseline.
2. **Soft-Delete + Evidencia:** migración de `deleted_at`, `is_test`, `relationship`, `evidence_consent`. Modificar **todas** las queries globales con `WHERE deleted_at IS NULL` y cambiar el "reset" a UPDATE (no DELETE).
3. **Fix `thinkingBudget: 0`:** presupuesto cero en la llamada a Vertex AI para estabilizar el multi-turno.
4. **OAuth Scopes + Calendario Secundario:** restringir a scopes no-sensibles, apuntar las redirect URIs **exclusivamente a `valeai.app`** y crear/usar la agenda secundaria "Vale AI".
5. **Resend (DNS) + Política de Privacidad:** integrar la API de Resend, verificar el dominio **`valeai.app`** por DNS (SPF/DKIM) y publicar la ruta `/privacy`.

> **Host de producción:** `valeai.app`. Todas las constantes globales en `config.php`/`.env` apuntan a esta URL base. `vale.supraide.com` queda como staging/dev.

---

## 10. Riesgos técnicos y mitigaciones

| Riesgo | Impacto | Mitigación |
| --- | --- | --- |
| Pérdida de evidencia por resets | Crítico | Soft-delete (`deleted_at`) + `WHERE deleted_at IS NULL` en todas las queries. |
| Saturación de webhooks (Meta) | Alto | `fastcgi_finish_request()` para devolver el `200 OK` en <5s y procesar la IA en segundo plano. |
| Fugas de datos multi-tenant | Crítico | Wrapper de PDO que fuerza el `tenant_id` en cada query. |
| Baneo de WhatsApp por spam | Alto | Solo plantillas aprobadas por Meta (Pro y recordatorios Growth), validación de opt-in y monitoreo de bloqueos. |
| Review gating (baneo en Google) | Alto | Enlace de Google Maps a todos por igual, sin filtrar por sentimiento. |
| Desangre de costos del Plan Free | Alto | Cuotas duras por IP y por tenant desde el día 1. |

---

## 11. El `.gitignore` definitivo

```text
# === Secretos y credenciales (NUNCA al repo) ===
.env
config.php
*credentials*.json
*service-account*.json
*.key
*.pem
.htpasswd

# === Logs y temporales ===
error_log
*.log
logs/
cache/
tmp/

# === Dependencias ===
vendor/
node_modules/

# === Respaldos y dumps (jamás) ===
*.sql
*.sql.gz
*.bak
*.zip
*.tar.gz

# === Basura de entorno / cPanel / editor ===
.user.ini
.DS_Store
Thumbs.db
.idea/
.vscode/
```

---

## Documentos de referencia (deep-dives en `/docs`)

- `vale-orquestador-spec.md` — el cerebro, el refactor por fases y los prompts para Claude Code.
- `vale-evidencia-hackathon-spec.md` — requisitos del XPRIZE, schema de evidencia, soft-delete, checklist de submission.
- `vale-vertical-medico-spec.md` — perfiles de paciente/doctor, evolución en dos etapas y reglas de PHI.