diff --git a/CLAUDE.md b/CLAUDE.md index 8584527..25cb3b0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -10,6 +10,36 @@ SaaS B2B para reformistas en España. El cliente final del reformista deja sus d 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: @@ -17,53 +47,49 @@ 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/dev-strategy.md`](docs/dev-strategy.md) — Orden de implementación, pipeline assets, testing, milestones -5. [`funnel.md`](funnel.md) — Diagrama del funnel punta a punta -6. [`negocio/`](negocio/) — Modelo de negocio, plan financiero, riesgos, compliance legal -7. [`devdocs/plan.md`](devdocs/plan.md) — Plan vivo de implementación -8. [`devdocs/progress.md`](devdocs/progress.md) — Estado actual del proyecto (qué está hecho, qué no) -9. [`devdocs/decisions.md`](devdocs/decisions.md) — Decisiones técnicas tomadas y por qué +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 (cuando el código exista) +## 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 -# Setup (una sola vez) pnpm install cp .env.example .env.local # rellenar las claves pnpm db:migrate # migraciones Postgres con Drizzle Kit - -# Desarrollo -pnpm dev # Next.js dev server en :3000 - -# Build -pnpm build # build de producción -pnpm start # corre el build en local - -# Testing -pnpm test # vitest (unit + integration) -pnpm test:e2e # Playwright (flujos críticos) -pnpm test:watch # vitest watch mode - -# Quality -pnpm lint # ESLint + autofix donde sea posible -pnpm typecheck # tsc --noEmit -pnpm format # Prettier sobre todo - -# Database -pnpm db:generate # genera migration desde schema -pnpm db:migrate # aplica migrations -pnpm db:studio # Drizzle Studio (DB GUI) +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 alguno de estos comandos no existe o no funciona, **no improvises**. Reporta el problema y arregla el setup antes de seguir. +> 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 14** (App Router + Server Actions + API Routes) | Un único proyecto y deploy | +| 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** | | +| 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) | | @@ -79,6 +105,8 @@ pnpm db:studio # Drizzle Studio (DB GUI) | 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. @@ -98,23 +126,26 @@ pnpm db:studio # Drizzle Studio (DB GUI) ## Estructura del proyecto -Ver detalle completo en [`docs/dev-strategy.md` §3](docs/dev-strategy.md). Resumen: +Layout real del repositorio hoy: ``` -reformix/ -├── app/ # Next.js App Router (marketing, app, api) -├── lib/ # Server-side (ai, voice, telephony, whatsapp, budget, db, ...) -├── components/ # Componentes React compartidos (ui, marketing, funnel, panel) -├── design/ # Design system (tokens, config) -├── copy/ # Copy guide -├── docs/ # Documentación técnica -├── devdocs/ # Plan vivo + progreso + decisiones -├── negocio/ # Documentación de negocio -├── public/ # Assets estáticos -├── raw/ # Assets fuente (git-ignored) -└── tests/ # Unit + integration + e2e +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 @@ -125,12 +156,12 @@ reformix/ 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. **Update `devdocs/progress.md`** cada vez que cierres un milestone. +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 en `devdocs/decisions.md`. +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. @@ -139,10 +170,10 @@ reformix/ ### Cuando dudes -- Si el specs no es claro → escribe la duda en `devdocs/decisions.md` como "pending" y pregunta. -- Si el copy no encaja → propón nueva versión en `COPY-GUIDE.md` y pide validación. -- Si el design system no cubre un caso → propón añadir token a `design-system.md`. -- Si el plan no contempla algo → updateA `devdocs/plan.md` y notifica. +- 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) @@ -158,7 +189,7 @@ reformix/ 1. Mata la sesión actual. 2. Inicia nueva sesión. -3. Lee `CLAUDE.md` (este archivo) → `devdocs/plan.md` → `devdocs/progress.md` → `devdocs/decisions.md`. +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. diff --git a/README.md b/README.md index 0224f81..121719d 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ > SaaS 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. -**Estado:** planificación completa, código sin empezar. Equipo de 4 personas, 3 semanas (24-may → 11-jun) hasta demo MVP. +**Estado:** planificación completa. Código iniciado — landing B2C en Next.js ([`mvp/b2c/`](mvp/b2c/)) y prototipo estático de la landing B2B ([`mvp/b2b/`](mvp/b2b/)); backend y pipeline IA aún sin empezar. Equipo de 4 personas, 3 semanas (24-may → 11-jun) hasta demo MVP. --- @@ -12,9 +12,19 @@ Si eres una **persona o agente IA nuevo en el proyecto**, lee en este orden: 1. [`CLAUDE.md`](CLAUDE.md) — Onboarding para agentes IA + comandos + convenciones (también útil para humanos) 2. [`specs.md`](specs.md) — Requisitos formales (55 RF + 30 RNF en notación EARS) -3. [`docs/dev-strategy.md`](docs/dev-strategy.md) — Cómo se va a construir (orden, equipo, milestones) -4. [`devdocs/plan.md`](devdocs/plan.md) — Plan vivo de implementación -5. [`devdocs/progress.md`](devdocs/progress.md) — Estado actual +3. [`docs/funnel.md`](docs/funnel.md) — Diagrama del funnel punta a punta +4. [`mvp/b2c/`](mvp/b2c/) — Código de la landing B2C (Next.js); ver su `README.md` propio + +--- + +## Alcance del sprint (qué construimos) + +Este sprint cubre **F1 + F2 de [`specs.md`](specs.md)**. Todo el producto vive en [`mvp/b2c/`](mvp/b2c/). + +- ✅ **Landing B2C** (`mvp/b2c`). +- ✅ **Funnel B2C completo end-to-end** (`mvp/b2c`): lead → fotos → llamada del agente de voz → render IA → presupuesto → WhatsApp → panel del reformista. **Demo del 11-jun.** +- ✅ **Landing B2B** — solo la landing, puliendo [`mvp/b2b/landing_reformix.html`](mvp/b2b/landing_reformix.html). Sin backend de signup por ahora. +- ⏸️ **Definido pero aparcado:** Fase 1.5 (multi-tenant, NL refinement, B/M/P, m² automático), Fase 2 (marketplace + valorador "Precio Justo"), doble nomenclatura. --- @@ -25,7 +35,7 @@ Si eres una **persona o agente IA nuevo en el proyecto**, lee en este orden: | Doc | Para qué | |---|---| | [`specs.md`](specs.md) | Requisitos funcionales y no funcionales en EARS | -| [`funnel.md`](funnel.md) | Diagrama del funnel punta a punta (ASCII + Mermaid + descripción Miro) | +| [`docs/funnel.md`](docs/funnel.md) | Diagrama del funnel punta a punta (ASCII + Mermaid + descripción Miro) | | [`copy/COPY-GUIDE.md`](copy/COPY-GUIDE.md) | TODO el copy del producto (landings, agente voz, WhatsApp, emails) | | [`design/design-system.md`](design/design-system.md) | Sistema de diseño, identidad visual y verbal | | [`design/design-tokens.css`](design/design-tokens.css) | Tokens CSS custom properties | @@ -44,24 +54,22 @@ Si eres una **persona o agente IA nuevo en el proyecto**, lee en este orden: | [`negocio/roadmap.md`](negocio/roadmap.md) | Hitos por fase (hasta 18 meses) | | [`negocio/riesgos.md`](negocio/riesgos.md) | Matriz de riesgos + contingencias | | [`negocio/datos/`](negocio/datos/) | Costes desglosados, proveedores, KPIs | -| [`investigacion-competencia-internacional.md`](investigacion-competencia-internacional.md) | Mapa de competidores + analogías (~5k palabras) | +| [`docs/investigacion-competencia-internacional.md`](docs/investigacion-competencia-internacional.md) | Mapa de competidores + analogías (~5k palabras) | -### Desarrollo (código futuro) +### Desarrollo -| Doc | Para qué | +| Doc / dir | Para qué | |---|---| -| [`CLAUDE.md`](CLAUDE.md) | Onboarding para agentes IA | -| [`docs/dev-strategy.md`](docs/dev-strategy.md) | Estrategia de desarrollo, estructura, milestones | -| [`devdocs/plan.md`](devdocs/plan.md) | Plan de implementación vivo | -| [`devdocs/progress.md`](devdocs/progress.md) | Estado real | -| [`devdocs/decisions.md`](devdocs/decisions.md) | Decisiones arquitectónicas (ADRs ligeros) | +| [`CLAUDE.md`](CLAUDE.md) | Onboarding para agentes IA + comandos + convenciones | +| [`mvp/b2c/`](mvp/b2c/) | Landing B2C en Next.js 16 (código activo) — tiene su propio `README.md` | +| [`mvp/b2b/landing_reformix.html`](mvp/b2b/landing_reformix.html) | Prototipo estático de la landing B2B | --- ## Stack técnico (resumen) ``` -Frontend + Backend: Next.js 14 (App Router) → Vercel +Frontend + Backend: Next.js 16 (App Router) → Vercel UI: Tailwind + shadcn/ui Agente de voz: Retell.ai + ElevenLabs (ES) Telefonía: Zadarma (fijos provinciales) @@ -75,6 +83,8 @@ Analytics: PostHog Testing: Vitest + Playwright ``` +> Implementado hoy: solo **Next.js + Tailwind** en [`mvp/b2c/`](mvp/b2c/). El resto es el stack objetivo de la fase F2 (MVP, 11-jun), aún sin integrar. + --- ## Equipo