reformix-hackaton/CLAUDE.md

# Reformix — CLAUDE.md

> Punto de entrada para cualquier agente IA (Claude Code, Cursor, Copilot) o desarrollador humano nuevo en el proyecto. Lee esto **antes** de tocar nada.

---

## Qué es Reformix

SaaS B2B para reformistas en España. El cliente final del reformista deja sus datos en una landing, sube fotos de su cocina o baño, recibe en menos de 2 minutos una **llamada de un agente IA** desde un número fijo de su provincia, y al colgar recibe por **WhatsApp** un render IA del espacio reformado + presupuesto orientativo desglosado con el branding del reformista. El reformista recibe el lead pre-cualificado completo en su panel.

Visión 18 meses: Fase 1 SaaS B2B → Fase 2 marketplace B2C con valorador "Precio Justo".

## Estado actual del código (27-may-2026)

La planificación (specs, negocio, copy, design) está completa. El **código está empezado pero es mínimo**: solo el front de marketing, sin backend ni pipeline IA.

| Superficie | Estado | Dónde |
|---|---|---|
| Landing B2C | App Next.js 16 en desarrollo (Hero, ReformaSlider, Features, Pricing, ContactForm, Footer) | [`mvp/b2c/`](mvp/b2c/) |
| Landing B2B | Prototipo estático en un único HTML | [`mvp/b2b/landing_reformix.html`](mvp/b2b/landing_reformix.html) |
| Backend, telefonía, voz, WhatsApp, render IA, motor de presupuesto, panel, DB | **Sin empezar** | — |

> Todo lo descrito más abajo como "stack técnico" es el **objetivo** de la fase F2. Salvo el front de `mvp/b2c`, nada de eso existe todavía en el repo. No asumas que un servicio está integrado: compruébalo.

## Alcance que construimos ahora

Decisión de equipo (mayo 2026): este sprint cubre **F1 + F2 de `specs.md`** y nada más. Todo el trabajo de producto sigue en `mvp/b2c`.

**Sí construimos:**

- **Landing B2C** (`mvp/b2c`) — superficie B de specs.
- **Funnel B2C completo end-to-end** (`mvp/b2c`) — superficies C + D: captura del lead → subida de fotos → llamada del agente de voz (Retell/Zadarma) → render IA → presupuesto desglosado → entrega por WhatsApp → panel del reformista. **Es la demo del 11-jun-2026.**
- **Landing B2B** — superficie A, **solo la landing**, puliendo [`mvp/b2b/landing_reformix.html`](mvp/b2b/landing_reformix.html). Sin backend de signup/trial funcional por ahora.

**Definido en `specs.md` pero NO se construye ahora:**

- **Fase 1.5:** configurador multi-tenant real, validación pre-envío del reformista, refinamiento por lenguaje natural, 3 versiones B/M/P, cálculo automático de m².
- **Fase 2 (producto):** marketplace B2C, valorador "Precio Justo", sello certificado.
- **Doble nomenclatura** (feature B2B post-hackathon).

> En el MVP el reformista es **"Reformas Ejemplo" hardcoded** (multi-tenant real va a F1.5). Si un requisito de specs.md está marcado F1.5 o Fase 2, **no lo implementes** sin abrir la conversación.

## Documentos canónicos (la fuente de la verdad)

Antes de implementar nada, lee estos en este orden:

1. [`specs.md`](specs.md) — Requisitos formales (55 RF + 30 RNF en notación EARS, con criterios de aceptación binarios)
2. [`copy/COPY-GUIDE.md`](copy/COPY-GUIDE.md) — TODO el copy del producto. **Cero lorem ipsum permitido** en ningún sitio
3. [`design/design-system.md`](design/design-system.md) — Tokens visuales, identidad verbal, componentes
4. [`docs/funnel.md`](docs/funnel.md) — Diagrama del funnel punta a punta
5. [`negocio/`](negocio/) — Modelo de negocio, plan financiero, riesgos, compliance legal
6. [`docs/`](docs/) — Investigación de competencia, insights de entrevistas, ideas iniciales

## Comandos

### Hoy (landing B2C — `mvp/b2c/`)

Lo único que funciona ahora mismo. Usa **npm** (hay `package-lock.json`), no pnpm.

```bash
cd mvp/b2c
npm install        # instala dependencias
npm run dev        # Next.js dev server en :3000
npm run build      # build de producción
npm run start      # corre el build
npm run lint       # ESLint
```

### Objetivo (cuando exista el backend de la fase F2)

> **Aún no funcionan.** Es el set previsto cuando se monte el backend (Drizzle, Vitest, Playwright). No los ejecutes esperando que existan.

```bash
pnpm install
cp .env.example .env.local   # rellenar las claves
pnpm db:migrate              # migraciones Postgres con Drizzle Kit
pnpm dev                     # dev server
pnpm build / pnpm start      # build de producción / correrla
pnpm test / pnpm test:e2e    # Vitest (unit+integration) / Playwright (e2e)
pnpm lint / pnpm typecheck / pnpm format
pnpm db:generate / pnpm db:migrate / pnpm db:studio
```

> Si un comando no existe o no funciona, **no improvises**. Reporta el problema y arregla el setup antes de seguir.

## Stack técnico (decidido, no cuestionar sin evidencia)

| Capa | Servicio | Por qué |
|---|---|---|
| Framework | **Next.js** (App Router + Server Actions + API Routes) | Un único proyecto y deploy. El front actual de `mvp/b2c` corre sobre Next.js 16 + React 19 |
| Lenguaje | **TypeScript strict** | |
| UI | **Tailwind + shadcn/ui** (objetivo) | Hoy `mvp/b2c` usa Tailwind v4 (`@theme` en `globals.css`) sin shadcn |
| Tokens visuales | [`design/design-tokens.css`](design/design-tokens.css) + [`design/tailwind.config.ext.js`](design/tailwind.config.ext.js) | |
| Tipografías | Instrument Serif (display) + Inter (body) + JetBrains Mono | Via `next/font/google` |
| Agente de voz | **Retell.ai** + **ElevenLabs** (voces premium ES) | |
| Telefonía | **Zadarma** (números fijos provinciales España) | |
| WhatsApp | **Evolution API** (primario) o WhatsApp Business API (respaldo) | |
| Render IA | **Nano Banana 2 / Image 2** (Google Gemini) + Replicate SDXL fallback | |
| IA texto + vision | **GPT-4o** (OpenAI) | |
| DB | **Postgres** + **Drizzle ORM** | |
| Storage | **S3** (Cloudflare R2 recomendado) | |
| Email | **SMTP** (genérico) | |
| Deploy | **Vercel** | |
| Analytics | **PostHog** | |
| Forms | react-hook-form + zod | |
| Testing | Vitest (unit + integration) + Playwright (e2e) | |

> Implementado hoy: solo **Next.js + Tailwind** en `mvp/b2c`. Todo lo demás (Retell, Zadarma, Evolution API, Nano Banana, GPT-4o, Postgres/Drizzle, S3, PostHog, Vitest, Playwright) es objetivo de F2 y aún no está integrado.

## Convenciones de código

- **TypeScript strict.** Sin `any` salvo en límites con SDK externos sin tipos.
- **Server Components por defecto.** Client Components solo cuando hace falta interactividad (`'use client'`).
- **API Routes** en `app/api/.../route.ts`. **Server Actions** para mutaciones desde formularios server-rendered.
- **Naming:**
  - Componentes: `PascalCase` (`LeadDetailCard`)
  - Hooks: `camelCase` con prefijo `use` (`useLeadStatus`)
  - Funciones: `camelCase`
  - Tipos: `PascalCase`, sin prefijo `I`
  - Constantes top-level: `SCREAMING_SNAKE_CASE`
  - Archivos componentes: `PascalCase.tsx`
  - Archivos utilidades: `kebab-case.ts`
- **Comentarios:** solo cuando el *porqué* no es obvio. Nada de comentarios que describen *qué* hace el código.
- **Imports:** usar paths absolutos con alias `@/` (configurado en `tsconfig.json`).
- **Tests:** colocados en `tests/` espejando `app/` y `lib/`, no junto al código.

## Estructura del proyecto

Layout real del repositorio hoy:

```
reformix-hackaton/
├── mvp/
│   ├── b2c/                 # App Next.js 16 — landing del cliente final (código activo)
│   │   └── src/
│   │       ├── app/         # App Router: layout.tsx, page.tsx, globals.css
│   │       └── components/  # Un dir por componente: Hero/, ReformaSlider/, Features/, Pricing/, ContactForm/, Footer/, Navbar/
│   └── b2b/                 # landing_reformix.html — prototipo estático de la landing B2B
├── specs.md                 # Requisitos formales (EARS)
├── copy/                    # Copy guide
├── design/                  # Design system (tokens .css/.json, config Tailwind)
├── docs/                    # Funnel, investigación de competencia, insights, ideas
├── negocio/                 # Modelo de negocio, financiero, legal, operaciones, riesgos (+ datos/)
└── README.md / CLAUDE.md
```

> La estructura objetivo del backend F2 (`lib/ai`, `lib/voice`, `lib/telephony`, `lib/budget`, `tests/`...) aún no existe. Se creará dentro de `mvp/b2c` o en un workspace dedicado cuando arranque la fase F2.

## Reglas operativas para el agente IA

### Siempre

1. **Lee el documento canónico relevante antes de implementar.** Si vas a tocar el form B2C, lee §RF-B en specs.md y §"Landing B2C" en COPY-GUIDE.md.
2. **Usa copy de COPY-GUIDE.md literal.** No reescribas. Si necesitas un texto que no existe, añádelo primero al copy guide, luego úsalo.
3. **Usa tokens del design system.** No hardcodees colores, espaciados o tipografías. Si falta un token, propón añadirlo en design-system.md primero.
4. **Tests primero (TDD)** para el motor de presupuesto, extracción de entidades, parsers críticos.
5. **Salida mínima:** evita `console.log` verboso. Los tests deben fallar con mensajes accionables, pasar en silencio.
6. **Commit frecuente** cada milestone (≥ 1/día de trabajo activo). Mensaje en imperativo conciso: `Add lead capture form`, no `added lead form`.
7. **Documenta el avance** al cerrar cada milestone (commit descriptivo + aviso al equipo).

### Nunca

1. **No inventes requisitos.** Si no está en specs.md, pregunta antes de implementar. Si es una mejora obvia, añádela primero a specs.md y luego implementa.
2. **No metas dependencias nuevas sin justificación documentada.** Si añades una librería, justifica el porqué en el mensaje de commit (y en `specs.md` si afecta al stack).
3. **No uses ningún proveedor de IA que no esté en el stack decidido** sin abrir una decisión explícita.
4. **No hardcodees secretos.** Todo via `process.env.*` con tipo derivado de `zod` schema.
5. **No optimices prematuramente.** Performance budget en specs.md (FCP < 2s, llamada < 2 min, pipeline < 60s). Si vas dentro de presupuesto, no toques.
6. **No instales paquetes globales** ni modifiques config del editor de otros.
7. **No commits con tests rojos** (salvo en branch personal con flag `--no-verify` documentado en el mensaje).

### Cuando dudes

- Si el specs no es claro → anótalo en `specs.md` como duda pendiente y pregunta antes de implementar.
- Si el copy no encaja → propón nueva versión en `copy/COPY-GUIDE.md` y pide validación.
- Si el design system no cubre un caso → propón añadir token a `design/design-system.md`.
- Si el plan no contempla algo → coméntalo con el equipo y refleja el acuerdo en `specs.md`.

## Compliance imprescindible (no negociable)

- **HTTPS** forzado siempre.
- **Consentimiento LSSI-CE** separado del RGPD en el form del cliente final (RF-LEG-01).
- **Aviso de grabación** al inicio de la llamada del agente (RF-C-12, RNF-LEG-02).
- **Consulta Lista Robinson** antes de cada llamada saliente (RF-C-03, RNF-LEG-03).
- **Identificación como IA** en la llamada (AI Act, RNF-LEG-05).
- **Horario permitido** lun-vie 9-21, sáb 9-14, no domingos (RNF-LEG-06).
- **Retención grabaciones** máximo 12 meses (RNF-LEG-04).

## Cuando el contexto se llene (reset de sesión)

1. Mata la sesión actual.
2. Inicia nueva sesión.
3. Lee `CLAUDE.md` (este archivo) → la sección "Estado actual del código" → `specs.md`.
4. Lee el documento canónico de la superficie en la que estabas trabajando.
5. Continúa donde lo dejaste sin perder el hilo.

## Contacto / responsables

| Área | Owner | Backup |
|---|---|---|
| Producto + Coordinación + Voz | Carlos | Simon |
| Backend + IA + WhatsApp | Simon | Carlos |
| Motor de presupuesto + Dominio | Goyo | Carlos |
| UI/UX + Creativos | Antonio | Simon |