Cliente
{CLIENTE_RAZON_SOCIAL}
DevZen Solutions
Filial de Nümia Group
Project runbook · operating manual
{TITULO_PROYECTO}[Ej. Plataforma multi-clínica · Fase 2]
Operating manual entregado al cierre del proyecto. Punto único de verdad para operación normal, atención de incidentes, mantenimiento programado y referencia a la garantía técnica DevZen.
Referencia legal. Documento de handoff entregado conforme a la cláusula 7 del Master Service Agreement firmado entre las Partes con fecha {FECHA_MSA} y la § 2 entregable 5 del SOW-{NUMERO_SOW}. La garantía técnica de noventa (90) días naturales corre a partir de {FECHA_GO_LIVE} y vence el {FECHA_FIN_GARANTIA}. Si el proyecto involucra tratamiento de datos personales, aplica el DPA · Anexo B firmado el {FECHA_DPA}.
Lo que entregamos hoy es lo que usaríamos en producción mañana. Frase firma · cierre de proyecto
DevZen Solutions
Filial de Nümia Group
§ 1
Arquitectura del sistema.
Componentes desplegados, stack tecnológico activo en producción y decisiones arquitectónicas clave que sostienen el sistema entregado. Esta sección es el punto de partida para cualquier intervención técnica futura.
1.1
Stack tecnológico desplegado.
Frontend{FRONTEND_STACK} [Ej. React 18.3]
Backend{BACKEND_STACK} [Ej. Node 20 + Express]
Base de datos{DB_STACK} [Ej. PostgreSQL 15]
Hosting / cloud{HOSTING} [Ej. Vercel + Supabase]
CDN / Edge{CDN} [Ej. Cloudflare]
Autenticación{AUTH} [Ej. Supabase Auth + MFA]
Servicios externos{SERVICIOS_EXT} [Ej. BBVA API · SAT]
Observabilidad{MONITORING} [Ej. Sentry + Logs]
1.2
Diagrama de componentes.
1.3
Decisiones arquitectónicas clave.
Decisión 01
Recomendamos cola persistente para BBVA porque el endpoint responde con timeout intermitente — evita pérdida de transacciones bajo carga.
Decisión 02
Recomendamos Supabase + Postgres porque resuelve auth, storage y DB en un solo proveedor verificado, con cumplimiento SOC 2 y backups automáticos.
Decisión 03
Recomendamos Vercel para frontend porque entrega edge caching nativo y previews automáticos por PR — reduce ciclo de feedback en QA.
DevZen Solutions
Filial de Nümia Group
§ 2
Accesos y credenciales.
Inventario de repositorios, ambientes y servicios externos. Las credenciales productivas no viven en este documento — se entregan por separado vía canal seguro.
2.1
Repositorios.
| Repo | URL | Ramas principales | Rol Cliente |
|---|---|---|---|
| Frontend | {URL_REPO_FRONTEND} | main · staging | {ROL_CLIENTE} [Ej. Admin] |
| Backend | {URL_REPO_BACKEND} | main · staging | {ROL_CLIENTE} |
| Infraestructura | {URL_REPO_IAC} | main | Read-only |
2.2
Ambientes desplegados.
| Ambiente | URL | Auth | Monitoreo |
|---|---|---|---|
| Producción | {URL_PROD} | SSO + MFA | {URL_MONITOR_PROD} |
| Staging | {URL_STAGING} | SSO | {URL_MONITOR_STAGING} |
| Logs centralizados | {URL_LOGS} | SSO + RBAC | Retención: 90 días |
2.3
Servicios externos · sin credenciales literales.
| Servicio | Función | Contacto para acceso |
|---|---|---|
| BBVA API | Cobranza · conciliación bancaria | {CONTACTO_BBVA} |
| SAT | Facturación electrónica | CFO Cliente |
| Cloudflare | DNS · WAF · edge cache | DevZen (transferible) |
| Supabase | DB · auth · storage | Owner: Cliente |
| Vercel | Frontend hosting | Owner: Cliente · team transferido |
Nota crítica · credenciales productivas
Las credenciales de producción se entregaron por canal seguro separado: vault compartido {VAULT_REFERENCIA} con acceso para {CONTACTO_TI_CLIENTE}. Este documento no contiene secretos. Cualquier rotación se coordina con DevZen durante la vigencia de la garantía.
DevZen Solutions
Filial de Nümia Group
§ 3
Operación normal · cómo se usa día a día.
3.1
Flujo principal del sistema.
| Paso | Acción | Sistema |
|---|---|---|
| 01 | El usuario inicia sesión vía SSO + MFA [Ej.] | Frontend → Auth |
| 02 | Carga el dashboard consolidado de la sede asignada | API · GET /dashboard |
| 03 | Ejecuta acción operativa {ACCION_PRINCIPAL} | API · POST |
| 04 | El sistema valida, encola si corresponde, y persiste | Backend → DB |
| 05 | Servicios externos se invocan async (BBVA · SAT) | Queue → integraciones |
| 06 | Notifica al usuario y registra evento auditable | Logs · Sentry |
3.2
Tareas operativas recurrentes.
- Diario. Conciliación bancaria automática · revisión de cola de errores.
- Semanal. Cierre administrativo · exportación de reportes a PDF.
- Mensual. Cierre contable · validación de facturas SAT.
- Trimestral. Revisión de roles y permisos · poda de cuentas inactivas.
3.3
Cron jobs y procesos automatizados.
| Job | Cuándo | Notifica |
|---|---|---|
| Conciliación BBVA | 04:00 diario | Email TI |
| Backup DB | 02:00 diario | Slack ops |
| Health check | cada 5 min | Sentry |
| Limpieza logs > 90d | domingo 03:00 | log silente |
3.4
Métricas y dashboards.
Estado del sistema en vivo: {URL_DASHBOARD_OPS}. Métricas críticas — uptime mensual, latencia p95, tasa de error, cola BBVA, queue SAT — visibles en tiempo real con alertas configuradas hacia {CANAL_ALERTAS}.
DevZen Solutions
Filial de Nümia Group
§ 4
Cuando algo falla.
Cinco escenarios típicos esperados con diagnóstico, mitigación y owner. Si el síntoma no aparece en la tabla, abrir ticket en kike@numia.group con descripción reproducible.
| Síntoma | Causa probable | Diagnóstico | Mitigación | Owner |
|---|---|---|---|---|
| Cobranza no se concilia con BBVA. | Endpoint BBVA respondió 500 o timeout. | Revisar logs en {URL_LOGS} · filtrar level:error service:bbva en últimas 24h. |
Reintento manual desde panel admin · si persiste > 2h, levantar ticket BBVA. | Kike Vázquez post-garantía: Cliente TI |
| Factura SAT en estado pendiente > 1h. | Queue SAT con backlog · certificado por vencer. | Verificar tamaño de queue en dashboard ops · revisar vencimiento del CSD. | Procesar manualmente desde admin · renovar CSD si aplica. | Kike Vázquez |
| Usuarios no pueden iniciar sesión. | SSO caído o MFA mal configurado. | Probar login con cuenta de test · revisar Supabase Auth status page. | Si SSO externo está caído, activar bypass temporal por sede · documentar en log. | Cliente TI |
| Reporte semanal no se generó. | Cron job falló · permisos de storage. | Revisar logs del scheduler · verificar permisos del bucket de export. | Ejecutar reporte manual desde panel admin · re-otorgar permisos. | Cliente TI |
| Latencia > 3s en endpoints clave. | Pico de carga · query lento · CDN cache miss. | Revisar APM · identificar query top · revisar hit ratio CDN. | Activar rate limiting si pico anormal · escalar pool DB temporal. | Kike Vázquez |
4.6
Escalación · niveles 1 / 2 / 3.
Nivel 1 · interno del Cliente
Mesa de ayuda del Cliente intenta resolución con el presente runbook. SLA respuesta < 1 hora hábil.
Nivel 2 · DevZen email
Escalar a kike@numia.group si nivel 1 no resuelve en 2 horas. SLA reconocimiento: {SLA_HORAS_RESPUESTA} horas hábiles.
Nivel 3 · DevZen emergencia
Solo para incidentes de severidad alta (sistema caído > 30 min · pérdida de datos · brecha de seguridad) durante la vigencia de la garantía. Teléfono directo: +52 981 123-6415. Notificación de incidentes de seguridad: 72 horas máximo según DPA cláusula 8.
DevZen Solutions
Filial de Nümia Group
§ 5
Mantenimiento programado.
5.1
Backups.
| Qué se respalda | Frecuencia | Retención | Cómo restaurar |
|---|---|---|---|
| DB completa | Diario 02:00 | 30 días | Supabase dashboard → restore from backup |
| DB incremental | Cada 6h | 7 días | Point-in-time recovery vía Supabase |
| Storage / archivos | Diario | 90 días | S3 versioning · contactar DevZen para asistencia |
| Configuración / secrets | Al cambio | Versionado | Vault history |
Prueba de restauración trimestral documentada · responsable: {OWNER_BACKUPS}.
5.2
Actualizaciones de dependencias.
- Mensual. Parches de seguridad (npm audit · CVE alerts).
- Trimestral. Minor updates de librerías clave con regression suite.
- Anual. Major versions con plan de migración formal.
5.3
Renovación de certificados.
| Certificado | Vence |
|---|---|
| SSL Cloudflare | Auto-renovación |
| CSD SAT | {FECHA_VENC_CSD} |
| API key BBVA | {FECHA_VENC_BBVA} |
5.4
Política de retención de datos.
| Categoría | Retención | Justificación |
|---|---|---|
| Logs operativos | 90 días | Suficiente para diagnóstico · cumple LFPDPPP. |
| Datos transaccionales | 5 años | Obligación fiscal (CFF) · resguardo contable. |
| Datos personales sensibles | {PLAZO_DATOS_SENSIBLES} | Conforme DPA cláusula 3.1 · plazo del Servicio. |
| Backups completos | 30 días | Window de recuperación operativa. |
DevZen Solutions
Filial de Nümia Group
§ 6
Garantía técnica DevZen.
Cobertura, exclusiones, procedimiento de reporte y niveles de servicio durante los noventa (90) días naturales posteriores al go-live. Referencia: MSA cláusula 7.
Cobertura · sí entra
Bugs reproducibles atribuibles al código entregado por DevZen. Defectos identificados que impiden la operación documentada. Documentación faltante en este runbook que entorpezca operación normal.
No entra
Modificaciones realizadas por el Cliente o terceros sin autorización. Uso fuera de las condiciones operativas documentadas. Fallas de servicios de terceros (BBVA, SAT, Supabase) ajenas al código DevZen. Caso fortuito o fuerza mayor.
6.1
Cómo reportar un bug.
Enviar correo a kike@numia.group con el asunto "{TITULO_PROYECTO} · BUG · [breve descripción]" y el siguiente bloque pre-llenado:
Plantilla bug report
Descripción del comportamiento esperado: ___
Descripción del comportamiento observado: ___
Pasos para reproducir (1, 2, 3): ___
Ambiente (producción / staging): ___
Usuario / rol que lo encontró: ___
Fecha y hora del incidente: ___
Logs relevantes adjuntos: sí / no
Screenshots o video: sí / no
Severidad percibida (bloqueador · alto · medio · bajo): ___
Descripción del comportamiento observado: ___
Pasos para reproducir (1, 2, 3): ___
Ambiente (producción / staging): ___
Usuario / rol que lo encontró: ___
Fecha y hora del incidente: ___
Logs relevantes adjuntos: sí / no
Screenshots o video: sí / no
Severidad percibida (bloqueador · alto · medio · bajo): ___
6.2
SLA de respuesta durante garantía.
| Severidad | Reconocimiento | Fix o mitigación | Comunicación |
|---|---|---|---|
| Bloqueador · sistema caído | {SLA_BLOQUEADOR} hrs [Ej. 2 hrs] | 8 hrs hábiles | Updates cada 2 hrs |
| Alto · función crítica degradada | 4 hrs hábiles | 2 días hábiles | Update diario |
| Medio · función no crítica | 1 día hábil | 5 días hábiles | Update al fix |
| Bajo · cosmético / mejora | 3 días hábiles | Siguiente release | Roadmap mensual |
Lo que entregamos hoy es lo que usaríamos en producción mañana. Frase firma · § garantía técnica
DevZen Solutions
Filial de Nümia Group
§ 7
Contactos y cierre.
7.1
Equipo DevZen.
| Nombre | Rol | Contacto |
|---|---|---|
| Kike Vázquez | CEO/CTO · soporte técnico | kike@numia.group +52 981 123-6415 |
| Eduardo Nepote | COO/CFO · comercial / admin | kike@numia.group +52 981 123-6415 |
7.2
Equipo Cliente.
| Nombre | Rol | Contacto |
|---|---|---|
| {PO_NOMBRE} | Product owner | {PO_EMAIL} |
| {TI_NOMBRE} | TI · operaciones | {TI_EMAIL} |
| {SPONSOR_NOMBRE} | Sponsor ejecutivo | {SPONSOR_EMAIL} |
Lo que entregamos hoy es lo que usaríamos en producción mañana. Cierre de proyecto · DevZen Solutions
Entrega y aceptación de handoff
Las Partes manifiestan que el presente runbook se entrega conforme a la cláusula 7 del MSA y al SOW-{NUMERO_SOW}, y que el Cliente ha recibido el código fuente, la documentación técnica y las credenciales productivas necesarias para la operación independiente del sistema. La garantía técnica corre desde la fecha indicada en la portada.
Kike Vázquez
CEO / CTO · DevZen Solutions
Fecha de entrega: {FECHA_HANDOFF}
{CLIENTE_REPRESENTANTE}
{CLIENTE_CARGO} · {CLIENTE_RAZON_SOCIAL}
Acepta handoff: {FECHA_HANDOFF}
Disclaimer template
Template DevZen v1.0 · Runbook parametrizable por proyecto · Los datos marcados como [Ejemplo] o
{...} se llenan con la información específica del proyecto entregado · Documento sujeto a actualizaciones durante la vigencia de la garantía técnica.