carlos/reformix-hackaton
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Actualización de documentación con estado real del código y alcance del sprint

Browse Source
This commit is contained in:
Carlos Narro
2026-05-27 12:27:16 +02:00
parent a9ad2d7e31
commit d6cc681e4c
2 changed files with 108 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files

137
CLAUDE.md
View File

@@ -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.

38
README.md
View File

@@ -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