# Fermenty — Guía de encaminamiento

> Cómo llevar todo lo decidido a producción, en qué orden, y qué depende de qué. Va de lo
> que bloquea a lo que espera. **No es código: es la secuencia** para que Claude Code y tú
> no os piséis ni rehagáis trabajo.
>
> Destino sugerido: `docs/Encaminamiento.md` · v1 · 2026-07-24

---

## 0. El principio de orden

Tres reglas que evitan rehacer:

1. **Los cambios irreversibles primero, y en pruebas.** Los precios de Stripe no se editan y `tax_behavior` no se cambia una vez fijado. Equivocarse en producción cuesta rehacer el catálogo.
2. **El dato antes que la pantalla.** El límite de tandas, la zona horaria, el ámbito de inquilino y la superficie única de usuario son de esquema. Cuestan una columna hoy y una migración con usuarios dentro.
3. **La infraestructura antes que el contenido.** No sirve maquetar `/pro` si los enlaces todavía apuntan a `erp.` y el nombre del plan está sin unificar.

---

## 1. Stripe — lo primero, y en sandbox

### Por qué ahora

Con una sola suscripción viva es el momento más barato. Y hay dos cosas que **no tienen vuelta atrás**: los precios no se editan (se archivan y se crean nuevos), y `tax_behavior: inclusive` **no se puede cambiar** una vez puesto. Por eso se hace primero y se prueba en un *sandbox* antes de tocar producción.

### Paso a paso

**1 · Activar en la cuenta**
- **Stripe Tax**, para repercutir el IVA por país (España 21 %, Alemania 19 %).
- **Customer Portal**, que es lo que `/suscripcion` va a usar para casi todo (§3).
- **OSS** al día para la venta intracomunitaria a consumidores.

**2 · Crear los productos** (dos, no más):

```
Product: Fermenty Pro   (id lógico: fermenty_pro)
Product: Fermenty Scale (id lógico: fermenty_scale)  ← sin precio, solo contacto
```

**3 · Crear los precios de Pro**, todos con `tax_behavior: inclusive` y su `lookup_key`:

| lookup_key | Importe | Ciclo |
|---|---|---|
| `pro_monthly_eur` | 4,99 € | mes |
| `pro_quarterly_eur` | 12,99 € | trimestre |
| `pro_annual_eur` | 39,00 € | año |
| `earlybird_monthly_eur` | 3,49 € | mes |
| `earlybird_annual_eur` | 29,00 € | año |

> **Referenciar siempre por `lookup_key`, nunca por el ID `price_...`.** Así el día que cambie un precio, se crea uno nuevo y se le **transfiere la lookup_key** con `transfer_lookup_key=true`; el código no se toca. Es exactamente el mecanismo que evita desplegar para cambiar una cifra.

**4 · Archivar lo viejo**
Los productos y precios actuales se marcan como inactivos **en el mismo momento**, no «por si acaso». Un precio archivado deja de venderse pero respeta las suscripciones que ya lo usan.

**5 · Migrar la suscripción viva**
A mano, es una. Crear la nueva antes de cancelar la vieja para no saltarse un ciclo.

**6 · Webhooks**
Que el backend escuche al menos: `checkout.session.completed`, `customer.subscription.updated`, `customer.subscription.deleted`, `invoice.paid`, `invoice.payment_failed`. Son los que disparan los correos del inventario (`Correos_Avisos.md` §3.1) y los que mantienen el plan del usuario sincronizado.

> **Descriptor en el extracto:** `FERMENTY`. Se configura aquí y evita que el cliente vea la razón social en su banco (`Voz.md` §7 bis).

### Lo que Stripe NO decide

El **eje del freemium** —2 tandas activas en gratis, calibración en Pro— **no vive en Stripe**. Stripe solo sabe quién paga. El límite y los candados los aplica tu backend leyendo el plan. Hay que comprobar que el límite de tandas se lee del plan y no está cableado a «3» en el código viejo.

---

## 2. Esquema y dominios — antes de maquetar nada

Lo que es caro cambiar después:

- [ ] **Superficie única de usuario:** `app.fermenty.es` sirve PWA y escritorio; `erp.` solo administración (`Dominios_Navegacion.md` §1 bis)
- [ ] **`APP_URL` actualizado** antes de emitir enlaces firmados nuevos, o los de recuperar contraseña se rompen
- [ ] **Reparto por ruta:** PWA en `/`, escritorio en `/panel/`, canónica `/tandas/{id}` sin prefijo
- [ ] **Límite de tandas leído del plan**, no cableado
- [ ] **Zona horaria del usuario:** capturarla ya, la piden los correos y el resumen
- [ ] **Ámbito de inquilino en el esquema** si va a haber obradores (`Dominios_Navegacion.md` §6) — una columna ahora
- [ ] **Subdominios reservados** (`app`, `api`, `erp`, `www`, `blog`, `admin`…)
- [ ] **`noindex` de servidor** en `app.`, `api.` y `erp.`

---

## 3. `/suscripcion` — la página que falta

**No es una página, son estados**, y viven en `app.`, no en la web pública. La regla de oro: **pantalla propia delgada + Customer Portal de Stripe para lo pesado.** No reconstruir la facturación.

### Los estados

| Estado del usuario | Qué ve en `/suscripcion` |
|---|---|
| **Gratis** | Su plan actual, qué gana con Pro, y el selector de ciclo → Checkout |
| **Pro activo** | Plan, próxima factura, botón a *Gestionar en Stripe* (cambiar tarjeta, ver facturas, cancelar) |
| **Pro cancelado, aún vigente** | Hasta cuándo tiene Pro, y opción de reactivar |
| **Pago fallido** | Aviso claro y botón directo a actualizar el método (§ correos lo trae aquí) |
| **Early Bird** | Igual que Pro, indicando que tiene tarifa de fundador vitalicia |

### Qué es tuyo y qué es de Stripe

| Acción | Dónde |
|---|---|
| Ver el plan y el estado | Tu pantalla |
| Elegir plan y ciclo, y pagar | **Stripe Checkout** |
| Cambiar tarjeta, ver facturas, cancelar, reactivar | **Stripe Customer Portal** |
| Aplicar Early Bird o recomendación | Tu backend, al crear la sesión de Checkout |

### 🔴 El desistimiento vive aquí

La casilla de «empezar ya y renunciar a los 14 días» se marca **en el momento de contratar**, en el paso a Checkout (`legales/3-condiciones.md` §7). Si no está, toda suscripción es reembolsable dos semanas. Es requisito para publicar, no mejora.

### Enganches ya decididos

- **Vuelta de Checkout** → `app.fermenty.es/suscripcion/...`, la canónica, nunca `/panel/`
- **Cada cambio dispara su correo** del inventario: recibo, cancelación, fallo, Early Bird confirmada
- **El FAQ de `/pro`** ya promete «desde tu cuenta, portal de Stripe»: esta pantalla lo cumple

> Esta página necesita su propio brief de producto, al estilo de los de la web pero orientado a estados y transiciones. Es lo siguiente natural si se ataca el flujo de pago.

---

## 4. Web pública — el contenido ya escrito

Con Stripe y dominios resueltos, se maqueta lo de esta tanda. Orden por dependencia:

1. **Navegación:** menú `Afinador · Mentor · Fermentos · Blog · Pro`, footer unificado, todas las 301 (`Dominios_Navegacion.md` §4)
2. **Afinador** — endpoint contra el motor primero, luego la página. Es la puerta de entrada
3. **Fermentos + fichas** — mover del subdominio, publicar los `hints`. Mayor ganancia SEO
4. **Home, Mentor, Pro** — las tres troncales
5. **Recetas** — plantilla con los dos estados
6. **Blog** — plantilla primero (arregla 16 de una vez), luego los dos rojos, luego reescrituras
7. **Legales** — rellenar `[PENDIENTE]`, auditar cookies, y al abogado los tres puntos rojos

---

## 5. Correos — cuando el ciclo de tanda exista

Dependen de dos cosas que van antes: la zona horaria (§2) y la canónica `/tandas/{id}` (§2).

1. **Transaccionales primero** — los dispara Stripe vía webhook, y hacen falta desde el primer cobro
2. **Ciclo de la tanda** — los que dan el valor; requieren el motor de frecuencia
3. **Activación y afinador** — el correo del día N, los de sin-tanda
4. **Configurar** SPF, DKIM, DMARC, y el buzón `hola@` vigilado

---

## 6. Decisiones tuyas que bloquean

Ninguna es de código; todas frenan una pieza concreta:

| Decisión | Bloquea |
|---|---|
| **Determinista vs. «IA»** en `/mentor` §8 | Publicar `/mentor` y el eslogan del footer |
| **Nombre del tercer plan** (Scale u Obrador) | Copy final de `/pro` y el producto de Stripe |
| **Rutas de categoría** en `/fermentos` (A/B/C) | Maquetar las páginas de estante |
| **`erp.` interno vs. producto** | Ya resuelto: interno |
| **Vender en Alemania desde el día 1** | El bloque alemán de condiciones y la Button-Lösung |
| **Sorteo: se mantiene o no** | Sus bases y el bloque de la home |

---

## 7. El camino corto, si hay que priorizar

Si el objetivo es **lanzar el mentor cuanto antes** y no todo a la vez:

1. Stripe en sandbox → producción (§1)
2. Dominios y navegación (§2)
3. Afinador funcionando (§4.2) — es el imán
4. Home + Mentor + Pro (§4.4)
5. Fichas movidas del subdominio (§4.3)
6. Transaccionales + correo de ventana (§5)
7. `/suscripcion` con Checkout y Portal (§3)

El blog, las recetas, `/para-obradores` y los artículos nuevos entran después sin bloquear el lanzamiento.

---

*Documento vivo.*