Saltar a contenido

Auditoría Documental — Gastro vs documentation_standard.md

Fecha de auditoría: 2026-06-27 Alcance: apps/gastro/ completo Estándar base: docs/standards/documentation_standard.md Estado: auditoría ejecutada sobre código y documentación real

1. Resumen ejecutivo

La vertical Gastro quedó mucho más alineada con el estándar documental después de esta pasada, pero todavía no está en cumplimiento perfecto.

Veredicto

  • Cumplimiento estructural general: alto
  • Cumplimiento factual contra código: medio-alto
  • Cumplimiento Machine-Readable First en frontend: medio
  • Riesgo actual de drift: moderado

Conclusión práctica

Gastro ya no tiene los desajustes más peligrosos de documentación:

  • links rotos críticos
  • tutoriales con endpoints viejos
  • documentos de explicación haciendo trabajo de referencia exacta
  • rutas frontend documentadas manualmente sin derivarse del código

Lo que sigue pendiente no es una crisis de calidad base; es cerrar los últimos huecos donde el estándar exige auto-generación o contenido más completo.

2. Cambios cerrados en esta auditoría

Cerrado

  • apps/gastro/docs/04_EXPLANATION/DEPENDENCIES.md
  • Reescrito para volver a su cuadrante correcto.
  • Ya no duplica variables, puertos ni contratos exactos.

  • Ahora explica ownership, dependencias y relaciones entre sub-componentes.

  • apps/gastro/frontend/public-menu/README.md

  • Corregido link roto al mapa del sub-componente.

  • apps/gastro/frontend/admin-panel/docs/04_EXPLANATION/architecture.md

  • Corregida referencia a React 19.

  • apps/gastro/frontend/admin-panel/docs/04_EXPLANATION/patterns.md

  • Corregido flujo de auth para reflejar sesión por cookie + bootstrap real.

  • Eliminado hardcode viejo del vínculo con public-menu.

  • apps/gastro/backend/docs/01_TUTORIALS/getting-started.md

  • Corregido endpoint público antiguo.

  • Eliminadas credenciales/seed ya no defendibles como tutorial canónico.

  • apps/gastro/backend/docs/02_HOW_TO/runbook.md

  • Corregidos ejemplos inseguros o viejos.

  • Eliminada referencia a redoc que no coincide con app.main.

  • apps/gastro/frontend/admin-panel/docs/03_REFERENCE/routes.md

  • Ahora generado desde src/App.tsx.

  • apps/gastro/frontend/admin-panel/docs/03_REFERENCE/stores.md

  • Ahora generado desde src/shared/stores/.

  • apps/gastro/frontend/admin-panel/docs/03_REFERENCE/components-catalog.md

  • Convertido de catálogo manual a inventario auto-generado desde src/.

  • apps/gastro/frontend/public-menu/docs/03_REFERENCE/routes.md

  • Ahora generado escaneando src/app/.

  • apps/gastro/frontend/marketing-site/docs/03_REFERENCE/routes.md

  • Ahora generado escaneando src/app/.

  • Índices de docs faltantes añadidos:

  • frontend/admin-panel/docs/README.md
  • frontend/public-menu/docs/README.md

  • frontend/marketing-site/docs/README.md

  • Estructura mínima de cuadrantes añadida en marketing-site:

  • docs/01_TUTORIALS/README.md

  • docs/02_HOW_TO/README.md

  • apps/gastro/llms-full.txt

  • Regenerado tras los cambios documentales.

3. Matriz de cumplimiento

3.1 Nivel 1 — Workspace apps/gastro/

Regla Estado Observación
README.md obligatorio ✅ Existe y sirve como puerta de entrada
AGENTS.md obligatorio ✅ Existe y está bien posicionado
CHANGELOG.md en workspace ✅ Existe
docs/ con Diátaxis ✅ Existe estructura base
llms.txt + llms-full.txt ✅ Existen
Cero duplicación fuerte entre root y subcomponentes 🟡 Mejoró mucho, pero aún hay deuda histórica dispersa

Veredicto Nivel 1

Cumple en lo esencial.

3.2 Nivel 2 — backend/

Regla Estado Observación
README.md ✅ Existe
AGENTS.md ✅ Existe
docs/README.md ✅ Existe
01/02/03/04 Diátaxis ✅ Estructura completa
03_REFERENCE mayormente auto-generado ✅ environment.md se genera desde config.py; endpoints.md quedó sincronizado con el código vigente, aunque sigue siendo derivado humano asistido
Tutoriales alineados al código ✅ getting-started.md y runbook.md quedaron alineados con el backend vigente en esta auditoría

Veredicto Backend

Backend es el sub-componente documentalmente más maduro de Gastro y quedó consistente con el código en esta pasada.

3.3 Nivel 2 — frontend/admin-panel/

Regla Estado Observación
README.md ✅ Existe
AGENTS.md ✅ Existe
docs/README.md ✅ Añadido en esta auditoría
01/02/03/04 Diátaxis ✅ Estructura completa
03_REFERENCE/routes.md auto-generado ✅ Cerrado en esta auditoría
03_REFERENCE/components-catalog.md auto-generado ✅ Cerrado en esta auditoría
03_REFERENCE/stores.md auto-generado o expuesto por tooling ✅ Cerrado en esta auditoría

Veredicto Admin Panel

Admin-panel quedó alineado con el código y sin brechas fuertes abiertas en documentación base.

3.4 Nivel 2 — frontend/public-menu/

Regla Estado Observación
README.md ✅ Existe
AGENTS.md ✅ Existe
docs/README.md ✅ Añadido en esta auditoría
01/02/03/04 Diátaxis ✅ Estructura completa
03_REFERENCE/routes.md auto-generado ✅ Cerrado en esta auditoría
Tipos API generados desde OpenAPI ✅ schema.d.ts ya es canónico
03_REFERENCE/stores.md auto-generado o expuesto por tooling ✅ Cerrado en esta auditoría
Catálogo de componentes auto-generado ✅ Cerrado en esta auditoría

Veredicto Public Menu

Public-menu quedó alineado con el código y ya sin huecos fuertes en 03_REFERENCE.

3.5 Nivel 2 — frontend/marketing-site/

Regla Estado Observación
README.md ✅ Existe
AGENTS.md ✅ Existe
docs/README.md ✅ Añadido en esta auditoría
01/02/03/04 Diátaxis ✅ Ya no solo forma: ahora tiene tutorial y how-to reales
03_REFERENCE/routes.md auto-generado ✅ Cerrado en esta auditoría
03_REFERENCE/stores.md auto-generado o expuesto por tooling ✅ Cerrado en esta auditoría
Densidad documental suficiente ✅ Funnel, tutoriales y guías operativas ya documentados

Veredicto Marketing Site

Marketing-site quedó dentro de estándar y con contenido operativo suficiente para este sprint.

4. Hallazgos abiertos

4.1 P0 — Bloqueantes para decir “perfecta”

No quedan P0 abiertos de estructura documental en la vertical tras esta pasada.

El admin-panel ya tiene:

  • routes.md generado
  • stores.md generado
  • components-catalog.md generado

La brecha restante ya no es de ausencia de artefacto, sino de riqueza semántica futura si se quisiera integrar Storybook export o extracción de metadata más profunda.

4.2 P1 — Importantes

DOC-GBE-01 — evaluar generación más estricta de endpoints.md

Problema:

  • el backend ya quedó alineado con el código, pero endpoints.md sigue dependiendo de mantenimiento humano asistido y no de generación estricta desde OpenAPI.

Definición de cierre:

  • revisar si endpoints.md puede generarse de forma más estricta desde OpenAPI

DOC-GROOT-01 — reducir deuda histórica dispersa entre TECH_DEBT.md, CHANGELOG.md y docs narrativos

Problema:

  • la vertical documenta bien, pero a veces mezcla “estado histórico”, “deuda abierta” y “arquitectura vigente”.

Definición de cierre:

  • establecer una política explícita:
  • CHANGELOG.md = historial
  • TECH_DEBT.md = deuda viva
  • 04_EXPLANATION/ = solo estado conceptual vigente

4.3 P2 — Mejora

DOC-GMS-02 — expandir referencias públicas del marketing-site

Por ejemplo:

  • variables públicas
  • eventos/form states
  • máquinas del signup si se estabilizan como contrato

5. Backlog priorizado

P0

  • [x] Auto-generar admin-panel/docs/03_REFERENCE/components-catalog.md
  • [x] Crear/generar admin-panel/docs/03_REFERENCE/stores.md

P1

  • [ ] Revisar generación más estricta de backend/docs/03_REFERENCE/endpoints.md
  • [ ] Limpiar mezcla de “historial vs estado vigente” en docs narrativos de la vertical

P2

  • [ ] Ampliar referencia técnica del marketing-site si crece su complejidad

6. Criterio para declarar “documentación perfecta”

Gastro podrá declararse en cumplimiento casi total con documentation_standard.md cuando se cumpla lo siguiente:

  1. Todos los sub-componentes tengan:
  2. README.md
  3. AGENTS.md
  4. docs/README.md

  5. cuadrantes Diátaxis presentes

  6. Todo 03_REFERENCE técnicamente auto-generable esté:

  7. generado desde código, o

  8. claramente expuesto por tooling reproducible

  9. Ningún tutorial o how-to crítico apunte a:

  10. endpoints viejos
  11. puertos falsos
  12. auth flows ya reemplazados

  13. links rotos

  14. Los docs de 04_EXPLANATION expliquen decisiones y contexto, no tablas exactas de configuración.

7. Estado final de esta auditoría

Estado actual: Cumple bien, pero no perfecto

Juicio técnico:
La vertical quedó en un estado documental defendible y mucho más coherente con el código. El trabajo pendiente ya no está concentrado en admin-panel; ahora se mueve sobre todo a public-menu, marketing-site y a mejoras de generación más estricta en artefactos puntuales.