workspace/projects/gamilit/docs/03-fase-extensiones/EXT-006-contenido/historias-usuario/US-CONT-004-versionamiento.md

US-CONT-004: Versionamiento de Contenido

Información Básica

Campo	Valor
ID	US-CONT-004
Épica	EXT-006 - Gestión de Contenido
Título	Sistema de Control de Versiones y Audit Trail
Prioridad	Media (P2)
Story Points	5 SP
Estado	NOT STARTED
Fase	Mes 3 (Extensiones Primera Ola)
Presupuesto	$2,900 MXN

---

Historia de Usuario

Como profesor o administrador Quiero historial completo de cambios en módulos y actividades con rollback, comparación y audit trail Para recuperar contenido eliminado, rastrear cambios y cumplir con auditorías

---

Valor de Negocio

Impacto

• Seguridad: Recuperar contenido eliminado accidentalmente
• Transparencia: Auditoría completa de cambios
• Colaboración: Ver quién cambió qué y cuándo
• Compliance: Cumplir requisitos regulatorios

Métricas de Éxito

• 90% recuperaciones exitosas de versiones

• 0 pérdidas de contenido irreversibles
• Tiempo de rollback <2 minutos

• 85% satisfacción con trazabilidad

---

Criterios de Aceptación

CA-01: Historial de Cambios

• Registrar cada guardado como nueva versión
• Metadata de versión:
  • Timestamp exacto
  • Usuario que modificó
  • Descripción del cambio (opcional)
  • Diff summary (caracteres cambiados)
• Límite de versiones: últimas 50 (configurable)
• Compresión de versiones antiguas
• Auto-purge de versiones >1 año (opcional)

CA-02: Versionamiento Automático

• Cada guardado crea versión automáticamente
• Versionamiento granular: por módulo, por actividad
• No requiere acción manual del usuario
• Snapshot completo del contenido
• Referencia a archivos multimedia (no duplicar)

CA-03: Rollback a Versiones Anteriores

• Lista de versiones en sidebar
• Preview de versión antes de restaurar
• Botón "Restaurar esta versión"
• Confirmación antes de rollback
• Crear nueva versión al restaurar (no sobrescribir)
• Rollback parcial (solo secciones específicas)

CA-04: Comparación de Versiones (Diff View)

• Vista side-by-side de dos versiones
• Highlighting de cambios:
  • Texto agregado (verde)
  • Texto eliminado (rojo)
  • Texto modificado (amarillo)
• Comparación línea por línea
• Jump to next/previous change
• Exportar diff como PDF
• Aceptar/rechazar cambios individuales (merge)

CA-05: Etiquetado de Versiones

• Etiquetar versiones importantes (v1.0, v2.0)
• Nombres descriptivos ("Antes de revisión", "Versión final")
• Filtrar por tags
• Versiones etiquetadas no se purgan automáticamente
• Comparar con versión etiquetada

CA-06: Audit Trail

Registrar todos los eventos:

• Creación de contenido
• Modificaciones (con diff)
• Eliminaciones
• Restauraciones
• Cambios de permisos
• Publicación/despublicación

Información capturada:

• Usuario (nombre, email, rol)
• IP address
• Timestamp exacto
• Acción realizada
• Before/after values
• User agent (browser)

CA-07: Papelera de Reciclaje

• Contenido eliminado va a papelera (no se borra)
• Retención: 30 días en papelera
• Restaurar desde papelera con un click
• Eliminar permanentemente (requiere confirmación)
• Vaciar papelera automáticamente después de 30 días
• Admin puede ver papelera de todos los usuarios

CA-08: Merge de Cambios

• Detectar conflictos si dos usuarios editan simultáneamente
• Vista de conflictos con opciones:
  • Mantener mi versión
  • Aceptar su versión
  • Merge manual (editar)
• Estrategias de merge:
  • Last write wins (default)
  • Manual resolution
  • Auto-merge si no hay conflictos
• Notificar a usuarios sobre conflictos

CA-09: Versionamiento de Archivos Multimedia

• Versionar archivos en biblioteca (US-CONT-003)
• Reemplazar imagen mantiene historial
• Rollback a versión anterior de archivo
• Comparación visual de imágenes (side-by-side)
• Metadata de versión (tamaño, dimensiones)

CA-10: Exportación de Historial

• Exportar audit log como CSV/Excel
• Filtrar por usuario, fecha, tipo de acción
• Reportes de actividad:
  • "Cambios en último mes"
  • "Modificaciones por usuario"
• Estadísticas:
  • Total de versiones
  • Frecuencia de cambios
  • Usuarios más activos

CA-11: Notificaciones de Cambios

• Notificar a stakeholders cuando contenido cambia
• Suscribirse a módulos específicos
• Digest diario/semanal de cambios
• RSS feed de cambios (opcional)
• Webhooks para integraciones externas

CA-12: Performance y Storage

• Almacenar solo diffs (no snapshots completos)
• Compresión de versiones antiguas
• Lazy loading de historial (últimas 10 primero)
• Índices en tablas de versiones
• Particionamiento por fecha
• Archive a cold storage después de 6 meses

CA-13: Permisos y Seguridad

Control de acceso:

• Solo autor puede ver historial de sus borradores
• Admin puede ver todo el historial
• Profesores ven historial de su contenido
• Estudiantes NO ven historial (solo versión publicada)

Audit de auditoría:

• Log de quién accede al audit trail
• Prevenir modificación de logs
• Inmutabilidad de registros históricos
• Encriptación de datos sensibles

CA-14: Interfaz de Usuario

• Timeline visual de versiones (gráfico)
• Filtros: Por usuario, por fecha, por tipo
• Búsqueda en historial
• Badges de versiones importantes
• Indicador de "Sin guardar" en editor
• Última modificación mostrada (ej: "Editado hace 5 min por Juan")

CA-15: Integración con Sistema

• Versionamiento transparente (no afecta flujo normal)
• API para versiones:

  GET /api/content/:id/versions
  GET /api/content/:id/versions/:versionId
  POST /api/content/:id/restore/:versionId
  GET /api/content/:id/diff?from=v1&to=v2
  

• Hooks en sistema de guardado
• Compatible con US-CONT-001 (editor)

---

Especificaciones Técnicas

Database Schema

CREATE TABLE content_versions (
  id UUID PRIMARY KEY,
  content_id UUID REFERENCES content(id),
  version_number INTEGER,
  content_snapshot JSONB, -- full snapshot or diff
  changes_summary TEXT,
  user_id UUID REFERENCES users(id),
  tag VARCHAR(100),
  created_at TIMESTAMP,
  is_deleted BOOLEAN DEFAULT FALSE
);

CREATE INDEX idx_versions_content ON content_versions(content_id);
CREATE INDEX idx_versions_created ON content_versions(created_at);

CREATE TABLE audit_trail (
  id UUID PRIMARY KEY,
  entity_type VARCHAR(50), -- 'module', 'activity', etc.
  entity_id UUID,
  action VARCHAR(50), -- 'create', 'update', 'delete', 'restore'
  user_id UUID REFERENCES users(id),
  ip_address VARCHAR(45),
  user_agent TEXT,
  before_state JSONB,
  after_state JSONB,
  timestamp TIMESTAMP
);

CREATE INDEX idx_audit_entity ON audit_trail(entity_type, entity_id);
CREATE INDEX idx_audit_timestamp ON audit_trail(timestamp);
CREATE INDEX idx_audit_user ON audit_trail(user_id);

Frontend Components

src/features/versioning/
├── components/
│   ├── VersionHistory.tsx
│   ├── VersionTimeline.tsx
│   ├── DiffViewer.tsx
│   ├── RestoreModal.tsx
│   ├── AuditLog.tsx
│   └── RecycleBin.tsx
└── hooks/
    ├── useVersions.ts
    └── useAuditTrail.ts

Technology Stack

Backend:
- PostgreSQL JSONB para snapshots
- diff-match-patch para generar diffs
- compression (zlib) para versiones antiguas

Frontend:
- react-diff-viewer para comparación
- react-timeline para visualización
- moment.js para timestamps

---

Diferenciación con Alcance Inicial

Alcance Inicial (EAI)

• Sin versionamiento
• Guardado sobrescribe
• Sin recuperación de contenido eliminado
• Sin audit trail

Esta Historia (EXT-006)

• Historial completo de cambios
• Rollback a cualquier versión
• Comparación visual de versiones
• Papelera de reciclaje
• Audit trail completo
• Merge de conflictos
• Etiquetado de versiones
• Esto es control de versiones tipo Git

---

Dependencias

Depende de

• US-CONT-001: Editor (integración)
• US-CONT-002: Ejercicios (versionamiento)
• US-CONT-003: Multimedia (versionamiento de archivos)

---

Definición de Terminado (DoD)

• Sistema de versionamiento automático
• Historial de versiones UI
• Rollback funcional
• Diff viewer side-by-side
• Etiquetado de versiones
• Audit trail completo
• Papelera de reciclaje
• Merge de conflictos
• Exportación de historial
• Notificaciones de cambios
• API de versiones
• Performance optimizada (diffs)
• Tests >80% coverage
• Documentación
• Video tutorial

---

Estimación Detallada (5 SP)

Tarea	Horas
Diseño de schema	4h
Sistema de versionamiento	10h
Historial UI	8h
Rollback	6h
Diff viewer	10h
Papelera	6h
Audit trail	8h
Merge conflicts	8h
Backend API	8h
Testing	8h
Documentación	4h
TOTAL	80h

Presupuesto: $2,900 MXN Duración: 2 días

---

Tags

#ext-006 #versionamiento #audit-trail #rollback #historial #diff #git-like #mes-3

---

Creado: 2025-11-02 Autor: Sistema de Migración - Subagente EXT 4-6 Origen: EP010/HU-EP010-03-content-management.md Compliance: PF-001 (XXX líneas)