` centrado |
| `overview` | `prompt`, `text_file`, `title` | Lee el `.txt`, opcionalmente le aplica un prompt simple (puedes hardcodear un resumen pre-armado por archivo para evitar dependencia de LLM), renderiza como markdown convertido a HTML |
| `claim_review_chart` | (ninguno) | Renderiza un gráfico de barras Plotly con datos sintéticos de CPT codes vs charged/allowed/patient_responsibility |
| `table` | `csv_file`, `title` | Lee el CSV y lo renderiza como tabla HTML con styling Plotly |
**Archivos en `./app/data/` que tienes que crear:**
- **`combined_email.txt`** (~10 líneas): email mezclado proveedor + paciente. Ej:
```
From: dr.martinez@cityhospital.com
Subject: Follow-up after appointment
Hi Charlie,
Following our visit last week, I'm recommending a follow-up CT scan
to confirm the diagnosis. Please schedule within the next 2 weeks.
---
From: charlie.smith@gmail.com
Subject: Re: Follow-up
Thanks Dr. Martinez. Will the CT scan be covered by my Gold PPO plan?
Also, can I get a copy of the lab results from last visit?
```
- **`provider_email.txt`** (~8 líneas): email solo del proveedor con jerga médica.
```
Patient presented with bilateral lower quadrant tenderness, WBC 14k,
CRP elevated. Differential includes appendicitis vs diverticulitis.
Recommending CT abdomen/pelvis with contrast STAT.
CPT 74177 ordered. Pre-auth obtained: AUTH-2024-8821.
```
- **`aetna_email.txt`** (~8 líneas): email de aseguradora con EOB.
```
Claim #AET-2024-9912 has been processed.
Service date: 2024-04-15
Provider: City Hospital
Total billed: $1,847.50
Plan allowance: $1,200.00
Plan paid: $960.00
Patient responsibility (20% coinsurance after deductible): $240.00
```
- **`aetna_claim_review_summary.csv`** (~10 filas):
```csv
Date,CPT_Code,Description,Charged_Amount,Allowed_Amount,Plan_Paid,Patient_Responsibility
2024-04-15,74177,CT Abdomen/Pelvis w/contrast,1847.50,1200.00,960.00,240.00
2024-03-22,99213,Office visit established patient,185.00,120.00,96.00,24.00
2024-02-10,80061,Lipid panel,82.00,55.00,44.00,11.00
...
```
**Lógica del handler:**
```python
import json, uuid
from pathlib import Path
OUTPUT_DIR = Path("app/data/reports_output")
OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
@app.post("/api/reports/generate-report")
def generate_report(payload: dict):
layout = json.loads(payload["layout_config"])
# expandir presets
expanded = []
for item in layout:
if item == "care_report":
expanded.extend(CARE_REPORT_PRESET) # constante definida arriba
else:
expanded.append(item)
# renderizar cada elemento
html_parts = []
for el in expanded:
kind = el["element_type"]
params = el.get("parameters", {})
if kind == "header":
html_parts.append(f"
{params['title']}
")
elif kind == "overview":
html_parts.append(render_overview(params))
elif kind == "claim_review_chart":
html_parts.append(render_claim_chart())
elif kind == "table":
html_parts.append(render_table(params))
# combinar en un HTML completo (usar templates/report.html como wrapper)
report_id = uuid.uuid4().hex[:12]
output_path = OUTPUT_DIR / f"{report_id}.html"
output_path.write_text(wrap_in_template("\n".join(html_parts)))
public_url = f"https://taller-wox.fitlabs.dev/api/reports/output/{report_id}.html"
return {"public_url": public_url}
# servir los HTMLs generados como estáticos
app.mount("/api/reports/output", StaticFiles(directory="app/data/reports_output"), name="reports")
```
**Response (200):**
```json
{ "public_url": "https://taller-wox.fitlabs.dev/api/reports/output/abc123def456.html" }
```
**Response (500) si algo falla:**
```json
{ "detail": "Error generating report: {mensaje}" }
```
**Template `templates/report.html`** (wrapper del reporte generado):
```html
Care Report
FACTORIT · FIT
{{ content | safe }}
```
---
## 6. Configuración por variables de entorno
```bash
# .env.example
SECRET_KEY=cambiar-esto-en-prod-string-largo-aleatorio
ADMIN_USER=admin
ADMIN_PASS=cambiar-esto
TOKEN_EXPIRY_HOURS=24
BASE_URL=https://taller-wox.fitlabs.dev
# Opcional, para mandar email de confirmación al registrarse
SMTP_HOST=
SMTP_PORT=587
SMTP_USER=
SMTP_PASS=
SMTP_FROM=bootcamp@fitlabs.dev
```
---
## 7. Deployment
### 7.1 Dockerfile
```dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app/ ./app/
COPY static/ ./static/
COPY material/ ./material/
# crear directorios runtime
RUN mkdir -p app/data/reports_output
EXPOSE 8000
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
```
### 7.2 DNS
Apuntar `taller-wox.fitlabs.dev` (registro A o CNAME) al hosting elegido (Railway/Render/etc.).
### 7.3 HTTPS
Obligatorio. Usar el SSL automático del proveedor o Let's Encrypt si es VPS propio. watsonx Orchestrate **rechaza** llamar HTTPS con certificados inválidos.
### 7.4 CORS
Los endpoints `/api/*` deben permitir requests desde `https://*.ibm.com` (donde corre watsonx Orchestrate). Configurar:
```python
from fastapi.middleware.cors import CORSMiddleware
app.add_middleware(
CORSMiddleware,
allow_origins=["*"], # o más restrictivo: ["https://us-south.dl.watson-orchestrate.cloud.ibm.com"]
allow_credentials=True,
allow_methods=["GET", "POST"],
allow_headers=["*"],
)
```
---
## 8. Testing manual antes de publicar
Una vez todo desplegado, verificar:
```bash
# Frontend
curl https://taller-wox.fitlabs.dev/ # debe devolver HTML del landing
curl -X POST https://taller-wox.fitlabs.dev/register \
-d "nombre=Test&email=test@test.com&empresa=ACME&consentimiento=on"
# debería devolver {"token":"...","redirect_url":"/descargas?token=..."}
# Descargas (con token válido)
curl -I "https://taller-wox.fitlabs.dev/download/Manual_Alumno_Bootcamp_FIT.docx?token=XXX"
# debe devolver 200 con Content-Type docx
# Endpoints del taller
curl -X POST https://taller-wox.fitlabs.dev/api/historical-procedures \
-H "Content-Type: application/json" \
-d '{"filters":"[]","group_by":"[]"}'
# debe devolver {"result":[...]}
curl https://taller-wox.fitlabs.dev/api/member-insights
# debe devolver el objeto con member, plan, overdue_procedures
curl https://taller-wox.fitlabs.dev/api/schedule
# debe devolver el texto de scheduling
curl -X POST https://taller-wox.fitlabs.dev/api/reports/generate-report \
-H "Content-Type: application/json" \
-d '{"layout_config":"[\"care_report\"]"}'
# debe devolver {"public_url":"..."}
```
**Test end-to-end del taller:**
1. Crear cuenta IBM Cloud trial.
2. Importar `openapi-tools-spec.json` en un agente nuevo en watsonx Orchestrate.
3. Hacer prompt: "¿Estoy atrasado en algún chequeo?" — debe llamar `/api/member-insights` y devolver los 4 procedimientos overdue.
4. Hacer prompt: "¿Cuánto cuesta una resonancia magnética?" — debe llamar `/api/available-procedures` con filtro `procedure contains MRI`.
---
## 9. Datos sintéticos — orientación
Los datasets CSV los inventas pero tienen que ser **coherentes entre sí**:
- En `historical_procedures.csv`, el afiliado principal (`member_name = Charlie Smith`) debería tener filas de `Annual Physical Exam`, `Dental Cleaning`, `Vision Exam` y `Blood Test` con `date` consistente con los `last_date` de `member_insights.json` (los procedimientos overdue).
- En `available_procedures.csv`, los `procedure` deben incluir al menos los procedimientos preguntables: `X Ray`, `MRI`, `CT Scan`, `Annual Physical Exam`, `Appendectomy`, `Dental Cleaning`, `Vision Exam`.
- Los costos en ambos datasets pueden diferir (uno es histórico, otro es catálogo de oferta).
**Importante:** los costos deben verse realistas. Una radiografía cuesta ~$80-300, una resonancia ~$1500-3000, una apendicectomía ~$10000-30000.
---
## 10. Logos y branding
**Logos a conseguir (Felipe los provee al desarrollador):**
1. `static/img/logo-factorit.svg` — logo oficial FactorIT (Felipe ya lo tiene)
2. `static/img/logo-watsonx.svg` — logo "IBM watsonx Orchestrate" oficial (bajar de https://www.ibm.com/brand/ o usar texto estilizado mientras tanto)
**Favicon:**
- `static/img/favicon.ico` y `favicon-32x32.png` — versión simplificada del logo FIT
**Meta tags para social sharing (OpenGraph):**
```html
```
---
## 11. Checklist de entrega para Claude Code
Cuando Claude Code termine, debe poder confirmar:
- [ ] El comando `uvicorn app.main:app --reload` levanta el server local en `http://localhost:8000`
- [ ] `GET /` muestra el landing brandeado FIT con formulario
- [ ] El formulario valida los 3 campos + checkbox y guarda en `leads.db`
- [ ] Tras submit redirige a `/descargas?token=...`
- [ ] La página de descargas muestra las 8-9 cards de archivos
- [ ] Cada botón "Descargar" baja el archivo correcto desde `material/`
- [ ] Los 5 endpoints responden correctamente con curl (ver sección 8)
- [ ] `GET /admin/leads` requiere basic auth y lista los registros
- [ ] El `Dockerfile` builda sin errores: `docker build -t taller-wox .`
- [ ] El container corre: `docker run -p 8000:8000 -v $(pwd)/leads.db:/app/leads.db taller-wox`
---
## 12. Lo que NO está en el alcance (para evitar scope creep)
- ❌ Editor visual de leads — solo lectura JSON/CSV.
- ❌ Recuperación de password — no hay password, solo email para descarga.
- ❌ Email transaccional obligatorio — opcional (SMTP en env).
- ❌ Analytics avanzados — solo conteos simples en `/admin/stats`.
- ❌ Multi-idioma — solo español.
- ❌ Re-captcha — basta con honeypot field invisible en el formulario.
---
## 13. Resumen ejecutivo para arrancar
**Lo primero que Claude Code debe hacer:**
1. Crear la estructura de carpetas (sección 2).
2. Implementar `app/main.py` con FastAPI básico, mount de static y templates Jinja2.
3. Implementar registro + descarga (sección 4) — eso es el corazón del producto.
4. Implementar los 5 endpoints (sección 5) — con datasets sintéticos pequeños primero.
5. Implementar el landing HTML con branding (sección 3).
6. Implementar la página de descargas (sección 3.4).
7. Dockerizar (sección 7.1).
8. Smoke tests (sección 8).
9. Deploy a un proveedor (a definir por Felipe).
10. Apuntar el DNS `taller-wox.fitlabs.dev` al deployment.
**Tiempo estimado total para un desarrollador senior:** 1-1.5 días de trabajo enfocado.
---
**Fin del SPEC. Cualquier ambigüedad → preguntar a Felipe antes de implementar.**