173 lines
8.8 KiB
Markdown
173 lines
8.8 KiB
Markdown
# 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".
|
|
|
|
## 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/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é
|
|
|
|
## Comandos (cuando el código exista)
|
|
|
|
```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)
|
|
```
|
|
|
|
> Si alguno de estos comandos 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 |
|
|
| Lenguaje | **TypeScript strict** | |
|
|
| UI | **Tailwind + shadcn/ui** | |
|
|
| 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) | |
|
|
|
|
## 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
|
|
|
|
Ver detalle completo en [`docs/dev-strategy.md` §3](docs/dev-strategy.md). Resumen:
|
|
|
|
```
|
|
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
|
|
```
|
|
|
|
## 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. **Update `devdocs/progress.md`** cada vez que cierres un milestone.
|
|
|
|
### 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`.
|
|
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 → 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.
|
|
|
|
## 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) → `devdocs/plan.md` → `devdocs/progress.md` → `devdocs/decisions.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 |
|