codigo0/docs/ROADMAP_CONTENIDO_Y_ADMIN.md

613 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 🗺️ ROADMAP: SISTEMA DE GESTIÓN DE CONTENIDO Y PANEL DE ADMINISTRACIÓN
**Versión:** 1.0
**Fecha:** 2025-01-XX
**Estado:** Plan de Implementación - Sin Ejecución
**Autor:** Arquitecto de Software Senior + Arquitecto de Contenido + Diseñador Instruccional Sanitario
---
## 🎯 PROPÓSITO DEL DOCUMENTO
Este documento define **EL PLAN DE IMPLEMENTACIÓN PROGRESIVA** del sistema de gestión de contenido y panel de administración para EMERGES TES. Establece:
- ✅ Fases claras de implementación
- ✅ Dependencias entre fases
- ✅ Criterios de éxito por fase
- ✅ Riesgos y mitigaciones
- ✅ Timeline estimado
**Este documento se actualiza según progreso y aprendizajes.**
---
## 📋 PRINCIPIOS DEL ROADMAP
### Principio 1: Progresivo y No Disruptivo
**Cada fase:**
- ✅ No rompe funcionalidad existente
- ✅ Puede desplegarse independientemente
- ✅ Permite rollback si hay problemas
- ✅ Mantiene app funcional en todo momento
---
### Principio 2: Validación Continua
**Cada fase:**
- ✅ Se valida con usuarios reales (TES)
- ✅ Se prueba en entorno de producción
- ✅ Se documenta aprendizajes
- ✅ Se ajusta plan según feedback
---
### Principio 3: Priorización por Impacto
**Orden de implementación:**
1. Alto impacto, bajo riesgo
2. Alto impacto, medio riesgo
3. Medio impacto, bajo riesgo
4. Bajo impacto, cualquier riesgo
---
## 🚀 FASES DE IMPLEMENTACIÓN
---
## FASE 0: PREPARACIÓN (Sin Impacto en Usuarios)
**Duración estimada:** 2-3 semanas
**Riesgo:** Bajo
**Impacto en usuarios:** Ninguno
### Objetivos
1. ✅ Documentar modelo canónico (completado)
2. ✅ Documentar mapa de relaciones (completado)
3. ✅ Documentar arquitectura del panel (completado)
4. ✅ Documentar modelo de datos (completado)
5. ✅ Crear este roadmap (completado)
### Tareas
- [x] Crear `MODELO_CANONICO_CONTENIDO_EMERGES_TES.md`
- [x] Crear `MAPA_RELACIONES_CONTENIDO.md`
- [x] Crear `ARQUITECTURA_PANEL_ADMIN.md`
- [x] Crear `MODELO_DATOS_CONTENIDO.md`
- [x] Crear `ROADMAP_CONTENIDO_Y_ADMIN.md`
- [ ] Revisar y aprobar documentación con stakeholders
- [ ] Definir criterios de aceptación por fase
### Criterios de Éxito
- ✅ Documentación completa y aprobada
- ✅ Modelo canónico validado
- ✅ Roadmap consensuado
- ✅ Sin cambios en código de producción
### Riesgos y Mitigaciones
**Riesgo:** Documentación incompleta
**Mitigación:** Revisión iterativa con stakeholders
---
## FASE 1: EXTRACCIÓN DE CONTENIDO (Preparación)
**Duración estimada:** 3-4 semanas
**Riesgo:** Medio
**Impacto en usuarios:** Ninguno (paralelo)
### Objetivos
1. Extraer contenido de código TypeScript a archivos JSON
2. Crear estructura de archivos para contenido editable
3. Mantener compatibilidad con app actual
4. Validar que app sigue funcionando igual
### Tareas
#### 1.1 Extracción de Protocolos
- [ ] Crear script de migración `scripts/migrate-procedures.ts`
- [ ] Leer `src/data/procedures.ts`
- [ ] Convertir a formato JSON según `MODELO_DATOS_CONTENIDO.md`
- [ ] Guardar en `content/protocols/*.json`
- [ ] Añadir metadatos iniciales (version: 1, validationStatus: 'validated')
- [ ] Validar JSON con esquema
#### 1.2 Extracción de Fármacos
- [ ] Crear script de migración `scripts/migrate-drugs.ts`
- [ ] Leer `src/data/drugs.ts`
- [ ] Convertir a formato JSON
- [ ] Guardar en `content/drugs/*.json`
- [ ] Añadir metadatos iniciales
- [ ] Validar JSON con esquema
#### 1.3 Extracción de Guías
- [ ] Crear script de migración `scripts/migrate-guides.ts`
- [ ] Leer `docs/consolidado/SECCION_XX_*.md`
- [ ] Convertir a formato JSON (mantener Markdown en campo `content`)
- [ ] Guardar en `content/guides/{guideId}/section-{num}.json`
- [ ] Añadir metadatos iniciales
- [ ] Validar JSON con esquema
#### 1.4 Extracción de Manual
- [ ] Crear script de migración `scripts/migrate-manual.ts`
- [ ] Leer `public/manual/BLOQUE_XX_*/*.md`
- [ ] Convertir a formato JSON
- [ ] Guardar en `content/manual/bloque-{id}.json`
- [ ] Añadir metadatos iniciales
- [ ] Validar JSON con esquema
#### 1.5 Validación y Testing
- [ ] Comparar contenido extraído vs original
- [ ] Verificar que no se perdió información
- [ ] Validar esquemas JSON
- [ ] Ejecutar tests existentes (deben pasar)
- [ ] Verificar que app sigue funcionando
### Criterios de Éxito
- ✅ Todo el contenido extraído a JSON
- ✅ Estructura de archivos creada
- ✅ Metadatos iniciales añadidos
- ✅ App sigue funcionando igual
- ✅ Tests existentes pasan
- ✅ Sin regresiones
### Riesgos y Mitigaciones
**Riesgo:** Pérdida de información en migración
**Mitigación:** Comparación automática contenido original vs extraído
**Riesgo:** App deja de funcionar
**Mitigación:** Mantener código original hasta validación completa
---
## FASE 2: CARGA DINÁMICA DE CONTENIDO (MVP)
**Duración estimada:** 4-5 semanas
**Riesgo:** Medio-Alto
**Impacto en usuarios:** Bajo (mejora transparente)
### Objetivos
1. Modificar app para cargar contenido desde JSON
2. Implementar cache local (IndexedDB o localStorage)
3. Mantener fallback a contenido embebido
4. Garantizar funcionamiento offline
### Tareas
#### 2.1 Sistema de Carga de Contenido
- [ ] Crear `src/lib/content-loader.ts`
- [ ] Función `loadProtocols()`: Cargar protocolos desde JSON
- [ ] Función `loadDrugs()`: Cargar fármacos desde JSON
- [ ] Función `loadGuideSection()`: Cargar sección de guía
- [ ] Función `loadManualBlock()`: Cargar bloque de manual
- [ ] Implementar fallback a contenido embebido si falla carga
- [ ] Añadir logging de errores
#### 2.2 Sistema de Cache Local
- [ ] Crear `src/lib/content-cache.ts`
- [ ] Función `cacheContent()`: Guardar en IndexedDB
- [ ] Función `getCachedContent()`: Leer de IndexedDB
- [ ] Función `isStale()`: Verificar si cache está obsoleto
- [ ] Función `clearCache()`: Limpiar cache
- [ ] Implementar versionado de cache
- [ ] Añadir expiración de cache (ej: 7 días)
#### 2.3 Integración en App
- [ ] Modificar `src/data/procedures.ts`:
- [ ] Mantener array embebido como fallback
- [ ] Intentar cargar desde JSON al iniciar
- [ ] Usar contenido dinámico si disponible, fallback si no
- [ ] Modificar `src/data/drugs.ts` (mismo patrón)
- [ ] Modificar cargadores de guías (mismo patrón)
- [ ] Modificar cargadores de manual (mismo patrón)
#### 2.4 Testing y Validación
- [ ] Tests unitarios para content-loader
- [ ] Tests unitarios para content-cache
- [ ] Tests de integración: App carga contenido dinámico
- [ ] Tests de fallback: App funciona sin red
- [ ] Tests de cache: App usa cache cuando corresponde
- [ ] Testing manual en dispositivos reales
### Criterios de Éxito
- ✅ App carga contenido desde JSON
- ✅ Cache local funciona correctamente
- ✅ Fallback a contenido embebido funciona
- ✅ App funciona 100% offline
- ✅ Sin regresiones en funcionalidad
- ✅ Performance igual o mejor
### Riesgos y Mitigaciones
**Riesgo:** App deja de funcionar si falla carga
**Mitigación:** Fallback robusto a contenido embebido
**Riesgo:** Performance degradada
**Mitigación:** Cache agresivo, carga asíncrona
**Riesgo:** Cache corrupto
**Mitigación:** Validación de cache, limpieza automática
---
## FASE 3: PANEL MÍNIMO VIABLE (MVP)
**Duración estimada:** 6-8 semanas
**Riesgo:** Alto
**Impacto en usuarios:** Ninguno (panel separado)
### Objetivos
1. Crear panel de administración básico
2. Permitir edición de protocolos y fármacos
3. Implementar validación básica
4. Guardar cambios en archivos JSON (Git-based)
### Tareas
#### 3.1 Infraestructura del Panel
- [ ] Crear proyecto `admin-panel/` (React + Vite)
- [ ] Configurar autenticación básica (JWT)
- [ ] Crear layout del panel
- [ ] Implementar navegación básica
#### 3.2 Editor de Protocolos
- [ ] Crear `admin-panel/src/pages/ProtocolsEditor.tsx`
- [ ] Formulario para editar protocolo:
- [ ] Título, pasos, advertencias, etc.
- [ ] Validación de campos (Zod)
- [ ] Preview del protocolo
- [ ] Guardar en `content/protocols/*.json`
#### 3.3 Editor de Fármacos
- [ ] Crear `admin-panel/src/pages/DrugsEditor.tsx`
- [ ] Formulario para editar fármaco:
- [ ] Dosis, vías, indicaciones, etc.
- [ ] Validación de campos
- [ ] Preview del fármaco
- [ ] Guardar en `content/drugs/*.json`
#### 3.4 Sistema de Guardado
- [ ] Crear API básica (Node.js + Express o similar)
- [ ] Endpoint `PUT /api/content/protocols/:id`
- [ ] Endpoint `PUT /api/content/drugs/:id`
- [ ] Guardar en archivos JSON
- [ ] Incrementar versión automáticamente
- [ ] Crear entrada en changeLog
#### 3.5 Testing del Panel
- [ ] Tests unitarios de editores
- [ ] Tests de integración: Editar y guardar
- [ ] Validar que cambios se reflejan en app
- [ ] Testing manual completo
### Criterios de Éxito
- ✅ Panel permite editar protocolos
- ✅ Panel permite editar fármacos
- ✅ Cambios se guardan correctamente
- ✅ Versiones se incrementan
- ✅ App consume contenido actualizado
- ✅ Sin errores en producción
### Riesgos y Mitigaciones
**Riesgo:** Panel no funciona correctamente
**Mitigación:** Testing exhaustivo antes de producción
**Riesgo:** Cambios corruptos
**Mitigación:** Validación estricta, backups automáticos
**Riesgo:** Conflictos de edición
**Mitigación:** Sistema de locks o warnings
---
## FASE 4: VALIDACIÓN CLÍNICA Y ROLES
**Duración estimada:** 4-5 semanas
**Riesgo:** Medio
**Impacto en usuarios:** Ninguno (solo panel)
### Objetivos
1. Implementar sistema de roles
2. Implementar flujo de validación clínica
3. Añadir campos de metadatos de validación
4. Permitir aprobar/rechazar cambios
### Tareas
#### 4.1 Sistema de Roles
- [ ] Crear tabla de usuarios y roles
- [ ] Implementar RBAC (Role-Based Access Control)
- [ ] Roles: Administrador Clínico, Editor Docente, Editor Clínico, Revisor
- [ ] Proteger endpoints según roles
- [ ] UI del panel muestra/oculta según rol
#### 4.2 Flujo de Validación
- [ ] Añadir campo `validationStatus` a contenido
- [ ] Estados: 'draft', 'pending', 'validated', 'rejected'
- [ ] Botón "Solicitar Validación" en panel
- [ ] Panel de validación para Administrador Clínico
- [ ] Botones "Aprobar" / "Rechazar"
- [ ] Notificaciones de cambios de estado
#### 4.3 Metadatos de Validación
- [ ] Campos: `validatedBy`, `validatedAt`, `clinicalSource`
- [ ] Formulario para completar metadatos
- [ ] Validación obligatoria antes de aprobar
- [ ] Historial de validaciones
#### 4.4 Testing
- [ ] Tests de roles y permisos
- [ ] Tests de flujo de validación
- [ ] Testing manual con usuarios reales
### Criterios de Éxito
- ✅ Roles funcionan correctamente
- ✅ Flujo de validación completo
- ✅ Metadatos se guardan correctamente
- ✅ Solo contenido validado es público
- ✅ Historial de validaciones disponible
### Riesgos y Mitigaciones
**Riesgo:** Roles mal configurados
**Mitigación:** Testing exhaustivo, documentación clara
**Riesgo:** Contenido no validado se publica
**Mitigación:** Validación estricta en backend
---
## FASE 5: EDITORES COMPLETOS Y MIGRACIÓN
**Duración estimada:** 6-8 semanas
**Riesgo:** Medio
**Impacto en usuarios:** Bajo (mejoras transparentes)
### Objetivos
1. Completar editores de guías y manual
2. Migrar todo el contenido a sistema nuevo
3. Desactivar código embebido (solo fallback)
4. Validar que todo funciona correctamente
### Tareas
#### 5.1 Editor de Guías
- [ ] Crear `admin-panel/src/pages/GuidesEditor.tsx`
- [ ] Editor Markdown con preview
- [ ] Navegación entre secciones (1-8)
- [ ] Validación de estructura (8 secciones)
- [ ] Guardar en `content/guides/{guideId}/section-{num}.json`
#### 5.2 Editor de Manual
- [ ] Crear `admin-panel/src/pages/ManualEditor.tsx`
- [ ] Editor Markdown avanzado
- [ ] Navegación por bloques
- [ ] Búsqueda y reemplazo
- [ ] Guardar en `content/manual/bloque-{id}.json`
#### 5.3 Migración Completa
- [ ] Migrar todas las guías (10 guías × 8 secciones)
- [ ] Migrar todo el manual (94 archivos)
- [ ] Validar que todo el contenido está migrado
- [ ] Comparar contenido original vs migrado
#### 5.4 Desactivación de Código Embebido
- [ ] Marcar código embebido como "deprecated"
- [ ] Mantener solo como fallback de emergencia
- [ ] Documentar proceso de rollback
- [ ] Monitorear uso de fallback
### Criterios de Éxito
- ✅ Todos los editores funcionan
- ✅ Todo el contenido migrado
- ✅ Sin pérdida de información
- ✅ App funciona 100% con contenido dinámico
- ✅ Fallback solo se usa en emergencias
### Riesgos y Mitigaciones
**Riesgo:** Pérdida de contenido en migración
**Mitigación:** Validación exhaustiva, backups
**Riesgo:** App deja de funcionar
**Mitigación:** Fallback robusto, rollback plan
---
## FASE 6: MEJORAS Y OPTIMIZACIÓN
**Duración estimada:** 4-6 semanas
**Riesgo:** Bajo
**Impacto en usuarios:** Positivo (mejoras)
### Objetivos
1. Mejorar UX del panel
2. Optimizar performance
3. Añadir funcionalidades avanzadas
4. Documentar proceso completo
### Tareas
#### 6.1 Mejoras de UX
- [ ] Autoguardado en editores
- [ ] Indicadores de cambios no guardados
- [ ] Búsqueda en panel
- [ ] Filtros y ordenación
- [ ] Dashboard con estadísticas
#### 6.2 Optimización
- [ ] Lazy loading de contenido
- [ ] Compresión de JSON
- [ ] CDN para contenido estático
- [ ] Optimización de cache
#### 6.3 Funcionalidades Avanzadas
- [ ] Comparación de versiones (diff)
- [ ] Rollback a versiones anteriores
- [ ] Exportar/importar contenido
- [ ] Plantillas de contenido
#### 6.4 Documentación
- [ ] Manual de usuario del panel
- [ ] Guía de administración
- [ ] Proceso de validación clínica
- [ ] Troubleshooting
### Criterios de Éxito
- ✅ Panel es fácil de usar
- ✅ Performance mejorada
- ✅ Funcionalidades avanzadas disponibles
- ✅ Documentación completa
---
## 📊 RESUMEN DEL ROADMAP
### Timeline Estimado
| Fase | Duración | Riesgo | Impacto Usuarios |
|------|----------|--------|------------------|
| Fase 0: Preparación | 2-3 semanas | Bajo | Ninguno |
| Fase 1: Extracción | 3-4 semanas | Medio | Ninguno |
| Fase 2: Carga Dinámica | 4-5 semanas | Medio-Alto | Bajo |
| Fase 3: Panel MVP | 6-8 semanas | Alto | Ninguno |
| Fase 4: Validación | 4-5 semanas | Medio | Ninguno |
| Fase 5: Editores Completos | 6-8 semanas | Medio | Bajo |
| Fase 6: Mejoras | 4-6 semanas | Bajo | Positivo |
| **TOTAL** | **29-39 semanas** | | |
**Nota:** Timeline puede variar según recursos y prioridades.
---
### Dependencias
```
Fase 0 (Preparación)
Fase 1 (Extracción)
Fase 2 (Carga Dinámica)
Fase 3 (Panel MVP) ──┐
↓ │
Fase 4 (Validación) │
↓ │
Fase 5 (Editores) │
↓ │
Fase 6 (Mejoras) ←────┘
```
---
### Criterios de Éxito Global
- ✅ Contenido editable sin tocar código
- ✅ Panel funcional y seguro
- ✅ Validación clínica implementada
- ✅ App funciona 100% offline
- ✅ Sin regresiones
- ✅ Escalable a nivel institucional
---
## 🚨 RIESGOS GLOBALES Y MITIGACIONES
### Riesgo 1: Complejidad Técnica
**Descripción:** Sistema más complejo de lo esperado
**Mitigación:** Fases incrementales, validación continua
### Riesgo 2: Resistencia al Cambio
**Descripción:** Usuarios no adoptan panel
**Mitigación:** UX excelente, formación, documentación
### Riesgo 3: Contenido Corrupto
**Descripción:** Ediciones incorrectas rompen app
**Mitigación:** Validación estricta, backups, rollback
### Riesgo 4: Performance Degradada
**Descripción:** Carga dinámica más lenta
**Mitigación:** Cache agresivo, optimización, monitoreo
---
## 📝 NOTAS FINALES
### Priorización Flexible
**Este roadmap es una guía, no un contrato.** Las fases pueden:
- Reordenarse según necesidades
- Acelerarse si hay recursos
- Pausarse si hay problemas
- Iterarse según feedback
### Validación Continua
**Cada fase debe validarse con:**
- Usuarios reales (TES)
- Stakeholders (médicos, docentes)
- Testing exhaustivo
- Monitoreo en producción
### Documentación Viva
**Este roadmap se actualiza:**
- Al completar cada fase
- Al identificar nuevos riesgos
- Al recibir feedback
- Al cambiar prioridades
---
**Este roadmap es el plan de implementación. Se ejecutará de forma progresiva y validada.**