# KQ OTP + Apoyo escolar — Runbook de deploy (sesión coordinada)

> Estado al 2026-06-22: **código 100% implementado y testeado** en la rama
> `feature/kq-otp-support` (24 commits sobre `2078c41`). **Nada está en producción.**
> Suite completa verde: 12/12 grupos, incluida integración con PocketBase 0.36.8 real.

Este deploy es un **rollout de producción de cero** (OTP/familias + calendario de apoyo + tools de Sam).
Requiere el WhatsApp de Edd para la verificación final. Richard corre los pasos automáticos.

## Hallazgos de estado (pre-deploy)
- El árbol `main` NO tiene `backend/pb_hooks/` → el contenedor vivo monta una ruta inexistente y no carga hooks (`/api/kq/auth/request-otp` da 404).
- El `.env` vivo solo tiene `EVOLUTION_KEY`. El compose nuevo exige `KQ_*` con guardas `:?`.
- Ningún servicio vivo usa las credenciales admin del KQ PB → **rotar la password admin es bajo riesgo** (consumidores mapeados; ver memoria de rotación de secretos).
- Agente vivo `kq-chatwoot-agent` presente y activo (el patch lo encontrará).

## Backups ya tomados (2026-06-22, read-only)
`Edd-OS/server/backups/manual-kq-otp-support/`
- `data-before.db` (KQ PocketBase, 200 KB)
- `docker-compose.before.yml` (compose vivo)
- `n8n-workflows-before.sql` (workflow_entity + workflow_history, incluye Sam)

> Si pasa tiempo y entran datos nuevos antes del deploy, re-tomar `data-before.db`.

## Pre-requisitos antes de mutar runtime
1. **Merge** `feature/kq-otp-support` → `main` (o deploy desde el worktree). El contenedor monta los hooks desde `…/Edd-OS/projects/kings-and-queens/backend/pb_hooks` del árbol `main`, así que el código nuevo tiene que estar ahí.
2. Definir en `Edd-OS/server/.env` (los demás `KQ_*` los genera el migrate):
   - `KQ_CHATWOOT_HOST=<host público de Chatwoot>` (para validar URLs de comprobante; si queda vacío, la ruta de comprobante rechaza por seguridad).
   - `CHATWOOT_ADMIN_API_TOKEN=<token>` (ya documentado en el CLAUDE.md de KQ; lo usa el workflow de confirmación y n8n).

## Secuencia de deploy (Richard corre 1–5, Edd hace 6 y 7)

### 1. OTP Task 7 — migrar secretos y aplicar schema OTP/familias
```bash
cd /home/edd/Proyectos/Edd-OS/server
python3 scripts/migrate_kq_secrets.py          # genera/rota KQ_PB_ADMIN_PASSWORD, KQ_OTP_PEPPER, KQ_TOOL_TOKEN, KQ_ALE_PHONE en .env (no imprime valores)
grep -E '^(KQ_PB_ADMIN_EMAIL|KQ_PB_ADMIN_PASSWORD|KQ_OTP_PEPPER|KQ_TOOL_TOKEN)=' .env | sed 's/=.*/=<set>/'
set -a; . ./.env; set +a
cd ../projects/kings-and-queens
KQ_PB_URL=http://127.0.0.1:8091 python3 scripts/setup_auth_family.py
```

### 2. OTP Task 7 — aplicar schema de apoyo (Support Task 8 Step 2)
```bash
KQ_PB_URL=http://127.0.0.1:8091 python3 scripts/setup_support_booking.py
```

### 3. Recrear KQ PocketBase con hooks y verificar
```bash
cd /home/edd/Proyectos/Edd-OS/server
docker compose up -d --force-recreate kq-pocketbase
docker compose ps kq-pocketbase
docker logs --since 2m eddos-kq-pocketbase 2>&1 | tail -40        # sin errores de sintaxis de hooks
python3 ../projects/kings-and-queens/backend/verify_auth_family.py
```

### 4. Recrear n8n (toma KQ_TOOL_TOKEN/CHATWOOT_ADMIN_API_TOKEN) y deployar tools de Sam
```bash
docker compose up -d --force-recreate n8n
cd ../projects/kings-and-queens/whatsapp-agent/workflows
set -a; . /home/edd/Proyectos/Edd-OS/server/.env; set +a
N8N_API_KEY="<api key n8n>" N8N_BASE_URL=http://127.0.0.1:5678 python3 deploy_support_workflows.py
```
Esperado: 5 tool workflows upserted; `kq-support-confirmation` activo; `kq-chatwoot-agent` parcheado (5 tools `ai_tool`, prompt con marcador una sola vez) y **sigue activo**.

### 5. Smoke automatizado
```bash
curl -fsS http://127.0.0.1:8091/api/health
curl -fsS http://127.0.0.1:5678/healthz
curl -fsSI -H 'Host: www.kingsandqueens.com.ar' http://127.0.0.1:8080/login.html
KQ_PB_URL=http://127.0.0.1:8091 KQ_TOOL_TOKEN="$KQ_TOOL_TOKEN" python3 ../../backend/verify_support_booking.py  # tras crear 1 slot de prueba
```

### 6. Verificación OTP por WhatsApp (Edd) — Task 7 Step 6
Desde `https://www.kingsandqueens.com.ar/login.html`, pestaña WhatsApp: pedir código a tu número, recibir OTP por la instancia `Kings-and-Queens`, elegir identidad, entrar al dashboard. Probar login email/contraseña (profe/alumno) sigue OK.

### 7. Verificación flujo de apoyo (Edd) — Task 8 Steps 5–7
Crear 2 slots en el calendario; reservar por WhatsApp con Sam (≤3 opciones, hold 12 h, datos de transferencia del tool); mandar comprobante JPEG → aparece `payment_review`; aprobar → `confirmed`, llega 1 confirmación, sin recordatorios, replay del webhook no duplica.

## Rollback
```bash
cd /home/edd/Proyectos/Edd-OS/server
cp backups/manual-kq-otp-support/docker-compose.before.yml docker-compose.yml
docker cp backups/manual-kq-otp-support/data-before.db eddos-kq-pocketbase:/pb_data/data.db
docker compose up -d --force-recreate kq-pocketbase
# n8n: restaurar workflow_entity/workflow_history desde n8n-workflows-before.sql si hizo falta
```

Detalle completo paso a paso: `docs/superpowers/plans/2026-06-21-kq-otp-familias-implementation.md` (Task 7) y `…-kq-calendario-apoyo-sam-implementation.md` (Task 8).