§14 Versionado del análisis

14.1 📋 Historial de versiones

v1.0.0 — 2026-05-21 · Primera publicación

Cobertura

• 📋 Resumen ejecutivo + 17 hallazgos priorizados.
• 🗂️ Mapa completo de archivos (63 archivos · ~29 K LOC).
• 🗄️ Schema de las 33 tablas de la BD + relaciones lógicas.
• 💰 Módulo Venta: 20+ funciones de queries documentadas.
• 🏦 Módulo Caja: hub + 3 submódulos + pipeline 3-tier.
• 💸 Módulo Cashflow: 4 tablas + cruce comercial + clasificación de riesgo.
• 📦 Módulo Artículos: cross-module bootstrap + JOIN con venta.
• 🏷️ Módulo Listas: 17 listas + sync delegado.
• 🧮 12 fórmulas y cálculos clave (margen, peso, IVA, runway, aging).
• 🔀 10 diagramas de flujo ASCII (sync, pipeline, cross-filter, etc).
• 🐛 17 hallazgos categorizados (3 críticos · 6 altos · 8 medios).
• 🚀 Roadmap en 4 fases (~14-20 semanas-persona).
• 📊 Análisis de escalabilidad a 2 años.
• 🎨 Propuestas de mejoras visuales (design system, empty states, toasts).

Métricas del documento

Fuentes consultadas

• u120688891_chess.sql (dump real del 2026-05-21, 765 MB) — schema + AUTO_INCREMENTs reales.
• /reportes/DOCUMENTACION.md y los 9 docs markdown por módulo (~4.700 líneas).
• Lectura directa de data_api.php · sync_api_process.php · save.php · _schema.php de cada módulo.
• caja/version.php · cashflow/version.php · venta/config/database.php para versiones.
• caja/TROUBLESHOOTING.md · caja/REFERENCIA_EXCEL.md para diagnóstico operativo.

Próximas versiones planificadas

• v1.1.0 (esperada Q3 2026): incorporar resultados de la Fase 0 Hardening. Validar fixes de SEC-01, SEC-02, SEC-03.
• v1.2.0 (esperada Q4 2026): documentar nueva arquitectura de _shared/ y migración de credenciales.
• v2.0.0 (esperada 2027): refresh completo post-Fase 2 (vistas materializadas + cron syncs + cache HTTP).

14.2 📐 Política de versionado

El análisis sigue semver propio independiente de las versiones de los módulos del sistema.

Frecuencia de bumps esperada

• PATCH: cada ~2 meses (ajustes menores, fix de typos).
• MINOR: cada ~6 meses (refresh trimestral o post-fase).
• MAJOR: cada ~2 años o ante reestructura grande del sistema.

14.3 📂 Estructura del directorio

Cada versión vive en su propio subdirectorio para preservar el histórico:

/reportes/analisis/
├── README.md                       ← Cómo leer este análisis
│
├── v1.0.0/                         ← Versión actual ★
│   ├── index.html                  ← Landing
│   ├── secciones/                  ← 14 secciones HTML
│   │   ├── 01_estructura.html
│   │   ├── 02_base_datos.html
│   │   ├── 03_modulo_venta.html
│   │   ├── 04_modulo_caja.html
│   │   ├── 05_modulo_cashflow.html
│   │   ├── 06_modulo_articulos.html
│   │   ├── 07_modulo_listas.html
│   │   ├── 08_calculos_formulas.html
│   │   ├── 09_flujos_diagramas.html
│   │   ├── 10_analisis_errores.html
│   │   ├── 11_mejoras_propuestas.html
│   │   ├── 12_escalabilidad.html
│   │   ├── 13_mejoras_visuales.html
│   │   └── 14_changelog.html
│   ├── diagramas/                  ← Diagramas externos (vacío en v1.0.0)
│   └── assets/
│       ├── css/style.css           ← Estilos del análisis
│       └── js/app.js               ← Theme toggle, TOC, syntax highlight
│
├── v1.1.0/  (futuro)
└── v2.0.0/  (futuro)

Convenciones

• Cada versión es self-contained: copia completa de assets + secciones.
• Permite comparar versiones (diff visual del análisis evolutivo).
• El URL siempre incluye la versión: /reportes/analisis/v1.0.0/....
• Hay un symlink/redirect en /reportes/analisis/latest → versión actual.
• /reportes/analisis/README.md mantiene un índice de todas las versiones publicadas.

14.4 🚀 Cómo bumpear a una versión nueva

1. Copiar la carpeta actual a la nueva versión:

   cp -r /reportes/analisis/v1.0.0 /reportes/analisis/v1.1.0

2. Editar el badge en cada header de los HTML:

   <span class="version-badge">v1.1.0 · 2026-08-15</span>

3. Actualizar la sección 14.1 con la nueva entrada (al inicio):

   ### v1.1.0 — 2026-08-15 · <título corto>
   <span class="tag-prio prio-medium">MINOR</span>
   
   #### Cambios visibles
   - ...
   
   #### Hallazgos cerrados
   - SEC-01: ✅ Implementada autenticación en endpoints admin.
   - SEC-03: ✅ Dump SQL movido fuera del doc root.

4. Actualizar /reportes/analisis/README.md con el link a la nueva versión.
5. (Opcional) Actualizar symlink latest:

   ln -sfn v1.1.0 /reportes/analisis/latest

6. Commit + tag git:

   git add reportes/analisis/v1.1.0/
   git commit -m "analisis: v1.1.0 — <título>"
   git tag analisis-v1.1.0

Cuándo hacer PATCH (sin copiar carpeta)

Si la corrección es trivial (typo, dato actualizado), se puede editar la versión actual y bumpear sólo el patch en el badge:

# Editar directamente v1.0.0 → bump badge a v1.0.1
# Documentar el cambio al final de la sección 14.1
# git tag analisis-v1.0.1

14.5 🤝 Cómo contribuir al análisis

Si encontrás un hallazgo nuevo

1. Identificar la categoría: SEC · ARQ · PERF · UX · DOC · RES.
2. Asignar el siguiente ID consecutivo en esa categoría (ej. SEC-06).
3. Documentar en §10 siguiendo el patrón existente: ID · descripción · evidencia · impacto · fix sugerido.
4. Agregar a la matriz riesgo × impacto.
5. Actualizar el resumen ejecutivo del landing si es crítico.

Si proponés una mejora

1. Decidir si es de un módulo específico o transversal.
2. Si específico → agregar a "Propuestas específicas del módulo" en su sección.
3. Si transversal → agregar a §11 en la fase correspondiente (F0/F1/F2/F3).
4. Incluir esfuerzo estimado y prioridad.

Si querés agregar un diagrama

1. Usar ASCII art con <pre class="ascii-flow"> (consistente con resto).
2. O subir SVG/PNG a v<n>/diagramas/ e incluir con <img>.
3. Agregar al índice de §9 y en la sidebar.

Validación antes de publicar

• Verificar links rotos: find v*/ -name "*.html" | xargs grep -l 'href="[^"#]'.
• Validar HTML: tidy -q -e secciones/*.html.
• Verificar que el toggle de tema funcione en todas las páginas.
• Probar en mobile (Chrome DevTools → device toolbar).
• Verificar que se imprime bien (Ctrl+P → Save as PDF).

Fin del análisis v1.0.0
Documento mantenido por el equipo técnico de Zonas Áridas.
Próxima revisión planificada: Q3 2026 (post-Fase 0 Hardening).