Saltar al contenido
ROXEX Labs

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:

  1. Arquitectura. Qué corre dónde: HTML estático, Pages Functions, base de datos D1 y bucket R2, y qué servicios externos son opcionales.

  2. Estructura. Una tabla con cada carpeta del repositorio y qué contiene.

  3. Requisitos. Versión de Node.js y dependencias.

  4. Ejecutar en local. Las órdenes para arrancar el proyecto y la base de datos local, y las variables de entorno (solo nombres).

  5. Scripts. Qué hace cada orden de package.json.

  6. Control de calidad. La cadena de comprobaciones que se ejecuta antes de desplegar, paso a paso.

  7. Base de datos y migraciones. Cómo se versiona y se aplica cada cambio de esquema.

  8. Despliegue. Quién despliega, en qué orden y dónde está la checklist completa.

  9. 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/_redirects

    Cabeceras 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 local

La 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:

  1. audit:deps: npm audit de las dependencias de producción
  2. typecheck: TypeScript del sitio y de las Functions
  3. lint: ESLint
  4. test: pruebas de los endpoints de las Functions
  5. audit:services-nav: la navegación de servicios coincide con sus datos
  6. build
  7. audit:out: todo public/ está en lo que se publica
  8. audit:csp: hashes CSP de los scripts inline del export
  9. audit:budget: presupuesto de peso y estructura por grupo de rutas
  10. audit:site: enlaces internos rotos, títulos, canonical y sitemap.xml
  11. audit:llms: llms.txt frente al sitemap y a los datos
  12. check-blog-escaping: escapado seguro de los artículos
  13. audit:claims: afirmaciones sin respaldo
  14. 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. 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. 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. 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. 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. 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.