Muestra real · fase 04
Así entregamos la documentación técnica
En la fase de lanzamiento entregamos documentación técnica junto con el repositorio y los accesos. Para que veas cómo es antes de contratar, aquí está la de un proyecto nuestro.
Es la documentación de roxex.es, esta misma web. No es la de un cliente.
Resume dos ficheros de su repositorio, README.md y docs/deploy.md, tal como estaban el . De las variables de entorno solo aparecen los nombres: los valores nunca están en el repositorio. La de tu proyecto dependerá de su stack.
El README: qué hay y cómo se ejecuta
Empieza diciendo para qué sirve: es la documentación de entrega del repositorio, qué hay, cómo se ejecuta en local, qué comprueba el control de calidad y cómo se despliega. Sus secciones, en orden:
Arquitectura. Qué corre dónde: HTML estático, Pages Functions, base de datos D1 y bucket R2, y qué servicios externos son opcionales.
Estructura. Una tabla con cada carpeta del repositorio y qué contiene.
Requisitos. Versión de Node.js y dependencias.
Ejecutar en local. Las órdenes para arrancar el proyecto y la base de datos local, y las variables de entorno (solo nombres).
Scripts. Qué hace cada orden de package.json.
Control de calidad. La cadena de comprobaciones que se ejecuta antes de desplegar, paso a paso.
Base de datos y migraciones. Cómo se versiona y se aplica cada cambio de esquema.
Despliegue. Quién despliega, en qué orden y dónde está la checklist completa.
Después de desplegar. Qué comprobar y dónde mirar si algo falla.
Arquitectura
El navegador llega a Cloudflare Pages, que sirve:
out/HTML estático generado por next build (exportación estática de Next.js 16, React 19, TypeScript estricto, Tailwind CSS v4).
functions/Pages Functions de Cloudflare para /api/*: contacto, leads, bajas, área de compradores, pagos, descargas, salud y panel interno.
D1 (binding DB)Base de datos: CRM, cuentas, compras, sesiones y registros.
R2 (binding DOWNLOADS)Descargas de pago protegidas.
public/_headers y public/_redirectsCabeceras de seguridad y redirecciones 301.
Los servicios externos (email, pagos, avisos internos e IA) son opcionales: si falta su variable, esa integración se desactiva sin romper el resto.
Ejecutar en local y variables de entorno
Requisito: Node.js 22.18 o posterior. Las órdenes del README:
npm install
cp .dev.vars.example .dev.vars # rellena tus propios valores
npm run dev:ui # solo el front
npm run dev # build + Functions y D1 localLa base de datos local se prepara aplicando las migraciones en orden y, si se quieren, datos de prueba solo para local. También avisa de un problema conocido en Windows: cerrar lo que tenga abierta la carpeta de salida antes de volver a hacer build.
Variables de entorno: solo nombres
Los valores van en .dev.vars en local o como secretos de Cloudflare Pages, nunca en el repositorio. Los bindings de la base de datos y del almacenamiento no son variables: están en wrangler.toml.
ADMIN_USERADMIN_PASSWORD- Login del panel interno
ADMIN_TOKEN- Firma de las sesiones del panel
UNSUBSCRIBE_SECRET- Firma de los enlaces de baja (opcional)
RESEND_API_KEYRESEND_FROMRESEND_AUDIENCE_ID- Envío de email y lista de contactos (opcionales)
STRIPE_SECRET_KEYSTRIPE_WEBHOOK_SECRET- Pagos y webhook de Stripe
STRIPE_PRICE_*STRIPE_PRODUCT_*- IDs de precio y producto
TELEGRAM_BOT_TOKENTELEGRAM_CHAT_ID- Avisos internos (opcionales)
N8N_WEBHOOK_URLN8N_WEBHOOK_SECRET- Webhook de n8n (opcional)
ANTHROPIC_API_KEY- Ayudas con IA del panel interno (opcional)
ENVIRONMENTPUBLIC_SITE_URL- Entorno y URL pública (no secretas, en wrangler.toml)
La tabla incluye también las variables de verificación de buscadores y una solo para probar las auditorías.
Control de calidad antes de desplegar
Una sola orden, npm run verify, que se detiene en el primer fallo. El README enumera sus pasos y enlaza el documento que explica cada auditoría y cuándo falla:
- audit:deps: npm audit de las dependencias de producción
- typecheck: TypeScript del sitio y de las Functions
- lint: ESLint
- test: pruebas de los endpoints de las Functions
- audit:services-nav: la navegación de servicios coincide con sus datos
- build
- audit:out: todo public/ está en lo que se publica
- audit:csp: hashes CSP de los scripts inline del export
- audit:budget: presupuesto de peso y estructura por grupo de rutas
- audit:site: enlaces internos rotos, títulos, canonical y sitemap.xml
- audit:llms: llms.txt frente al sitemap y a los datos
- check-blog-escaping: escapado seguro de los artículos
- audit:claims: afirmaciones sin respaldo
- audit:contrast: contraste WCAG de los colores
Base de datos y migraciones
- Cada cambio de esquema es un fichero nuevo y numerado, con una cabecera que dice qué código lo usa y de qué migración depende.
- No se edita una migración ya aplicada.
- Se aplican a mano y en orden: la base de datos no lleva una tabla de versiones.
- Un script compara las migraciones con la base (solo lectura) y dice qué falta; el despliegue lo ejecuta y se detiene si falta alguna.
La checklist de despliegue
docs/deploy.md la ejecuta el propietario con su propia sesión de wrangler, la herramienta de Cloudflare. Explica cada paso y qué hacer si falla:
1. Control de calidad
npm run verify. Genera exactamente lo que se despliega.
Si falla: No se despliega. El script de despliegue ya no tiene una opción para saltárselo.
2. Comprobar migraciones pendientes
Un script compara los ficheros de migración con la base de destino lanzando solo consultas de lectura y dice qué falta (OK, FALTA, PARCIAL…).
Si falla: Si falta alguna, el despliegue se detiene sin subir nada.
3. Aplicar las que falten, en orden
En orden numérico, sin repetir una ya aplicada; las parciales se revisan antes de tocar nada. Después se vuelve a comprobar.
Si falla: La comprobación debe terminar sin pendientes antes de seguir.
4. Desplegar
Un script encadena los pasos 1 y 2, prepara el almacenamiento de descargas y sube el sitio a Cloudflare Pages.
Si falla: Si el control de calidad o las migraciones fallan, no se ha subido nada.
5. Smoke test
La ruta de salud de la API debe responder 200 y confirmar que existen las tablas que usa el código. Después se abren a mano la portada, el contacto y el panel.
Si falla: El despliegue anterior sigue disponible en el panel de Cloudflare Pages para volver a él (rollback).
Después del despliegue, el README indica dónde quedan registrados los errores 5xx de la API (sin datos personales, según docs/deploy.md) y las acciones sensibles del panel, y pide anotar cada cambio publicado en el changelog con su fecha.
Traspaso de accesos
La documentación acompaña al traspaso, no lo sustituye. Lo que te comprometemos ya está publicado:
- Acceso al repositorio Git desde el primer día. (Proceso, fase 03)
- Repositorio y accesos transferidos en el lanzamiento, con la documentación técnica. (Proceso, fase 04)
- Código, dominios, cuentas de proveedores y credenciales quedan transferidos. Puedes seguir con nosotros o con cualquier otro equipo. (Seguridad y datos)
Qué no está en esta muestra: el README de roxex.es no tiene una sección propia de modelo de datos; su esquema está en las migraciones numeradas del repositorio.