workspace/projects/gamilit/docs/00-vision-general/README.md
rckrdmrd a249c99be2
Some checks failed
CI Pipeline / changes (push) Has been cancelled
CI Pipeline / core (push) Has been cancelled
CI Pipeline / trading-backend (push) Has been cancelled
CI Pipeline / trading-data-service (push) Has been cancelled
CI Pipeline / trading-frontend (push) Has been cancelled
CI Pipeline / erp-core (push) Has been cancelled
CI Pipeline / erp-mecanicas (push) Has been cancelled
CI Pipeline / gamilit-backend (push) Has been cancelled
CI Pipeline / gamilit-frontend (push) Has been cancelled
feat: Sincronizacion completa workspace 2025-12-26
## Backend
- fix(ranks): Reordenar rutas en RanksController para evitar conflictos 404
- feat(gamification): Agregar MayaRankEntity al modulo
- feat(ml-coins): Expandir funcionalidad del servicio
- feat(teacher): Mejoras en dashboard, mensajes y reportes
- feat(entities): Nuevas entidades admin, educational, progress, social

## Frontend
- feat(gamificationAPI): API completa para ranks con endpoints
- feat(RubricEvaluator): Nuevo componente para evaluacion docente
- refactor(admin): Mejoras en hooks y paginas
- refactor(teacher): Mejoras en paginas del portal

## Database
- fix(initialize_user_stats): Agregar is_current y achieved_at a user_ranks
- fix(notifications-policies): Corregir RLS con JOIN correcto
- feat(friendships): Agregar columna status con estados
- sync(seeds): Homologacion completa DEV <-> PROD

## Docs & Orchestration
- docs(api): Actualizar API-TEACHER-MODULE.md
- docs(frontend): COMPONENTES-INVENTARIO.md
- docs(database): VIEWS-INVENTARIO.md, VALIDACION-DDL-SEEDS
- Reportes de analisis y validacion

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-26 17:53:38 -06:00

448 lines
16 KiB
Markdown

# 📖 Overview - GAMILIT Platform
**Carpeta:** `docs/00-vision-general/`
**Propósito:** Punto de entrada para todos los stakeholders (desarrolladores, PM, stakeholders, nuevos miembros)
**Última actualización:** 2025-11-29
---
## 🎯 ALCANCE MVP ACTUAL
| Componente | Estado MVP |
|-----------|------------|
| **Módulos Educativos** | M1-M5 implementados ✅ (completo) |
| **Épicas MVP** | EXT-001 a EXT-006 completas ✅ |
| **Épicas Backlog** | EXT-007 a EXT-011 parciales ⏳ |
| **Portales** | Student, Teacher, Admin funcionales ✅ |
> Ver alcances detallados en [VISION.md](./VISION.md) y [Fase 4: Backlog](../04-fase-backlog/README.md)
---
## 📋 ¿Qué encontrarás aquí?
Esta carpeta contiene documentación de **alto nivel** para entender rápidamente qué es GAMILIT Platform, su visión, arquitectura general y cómo empezar.
**Audiencia:**
- Nuevos desarrolladores (onboarding)
- Product Managers y stakeholders
- Tech Leads
- Cualquier persona que necesite entender GAMILIT Platform rápidamente
---
## 📚 Documentos Disponibles
### ✅ Documentos Completados
#### [VISION.md](./VISION.md)
**Audiencia:** Todos (stakeholders, developers, PM)
**Tiempo de lectura:** 15-20 minutos
**Última actualización:** 2025-11-07
**Qué contiene:**
- ¿Qué es GAMILIT Platform? (plataforma educativa gamificada)
- Visión y objetivos estratégicos
- Estado actual del producto (7.5/10 - BETA+)
- Modelo educativo (5 dimensiones de comprensión lectora)
- Sistema de gamificación (Rangos Maya, ML Coins)
- Stack tecnológico y arquitectura
- Métricas de éxito
- Ventajas competitivas
**Cuándo leerlo:**
- **Primer día** como nuevo miembro del equipo
- Antes de trabajar en features de gamificación
- Para entender el contexto de negocio
---
#### [ONBOARDING.md](./ONBOARDING.md)
**Audiencia:** Nuevos desarrolladores
**Tiempo de lectura:** 10 minutos (setup completo: 2-3 horas)
**Última actualización:** 2025-11-07
**Qué contiene:**
- Prerrequisitos (Node.js 18+, PostgreSQL 15+, Git)
- Guía paso a paso para configurar entorno local
- Setup de base de datos (crear DB, ejecutar DDL, seeds)
- Setup de backend (NestJS, .env, npm install, npm run dev)
- Setup de frontend (React, Vite, .env, npm run dev)
- Verificación de instalación (health checks)
- Siguientes pasos (días 1-3)
- Troubleshooting de problemas comunes
- Checklist de onboarding completo
**Cuándo leerlo:**
- **Primer día** como nuevo desarrollador
- Cuando necesites configurar un nuevo entorno de desarrollo
- Para ayudar a otro desarrollador con su setup
---
#### [_MAP.md](./_MAP.md)
**Audiencia:** Agentes IA, Tech Leads
**Tiempo de lectura:** 5 minutos
**Última actualización:** 2025-11-07
**Qué contiene:**
- Mapa de navegación de esta carpeta
- Archivos planeados vs completados
- Interdependencias con otras carpetas
- Issues conocidos y próximos pasos
**Cuándo leerlo:**
- Para agentes IA que necesitan contexto de la carpeta
- Para Tech Leads planificando próximos documentos
---
#### [DocumentoDeDiseño_Mecanicas_GAMILIT_v6_1.md](./DocumentoDeDiseño_Mecanicas_GAMILIT_v6_1.md)
**Audiencia:** Desarrolladores, PMs, diseñadores pedagógicos, QA
**Tiempo de lectura:** 60-90 minutos (documento completo de 14,500 palabras)
**Última actualización:** 2025-11-23 (v6.4)
**Qué contiene:**
- Especificación completa de mecánicas de gamificación GAMILIT
- 23 ejercicios organizados en 5 módulos (Cassany)
- Sistema de Rangos Maya (14 niveles jerárquicos)
- Sistema de ML Coins (economía del juego)
- Achievements, logros y misiones
- Flujos de usuario detallados
- Configuraciones JSONB de cada ejercicio
- Reglas de negocio y validaciones
**Cuándo leerlo:**
- Antes de desarrollar cualquier feature de gamificación
- Para entender las mecánicas de ejercicios (types, configs, validations)
- Al diseñar nuevos módulos educativos
- Durante QA para validar flujos completos
---
#### [GUIA-PRUEBAS-MODULO1-Respuestas-Ejemplo.md](./GUIA-PRUEBAS-MODULO1-Respuestas-Ejemplo.md)
**Audiencia:** QA, desarrolladores frontend/backend, demos pedagógicas
**Tiempo de lectura:** 30-40 minutos (documento completo), 5-8 min por ejercicio
**Última actualización:** 2025-11-23
**Qué contiene:**
- Ejemplos detallados de respuestas para los 5 ejercicios del Módulo 1
- 40+ ejemplos clasificados en 3 niveles: EXCELENTE, ACEPTABLE, INCORRECTA
- Criterios de scoring para cada ejercicio
- Keywords para validadores automáticos
- Datos de prueba listos para usar
**Ejercicios cubiertos (Comprensión Literal - Cassany Nivel 1):**
- 1.1: Crucigrama Científico (6 palabras clave sobre Marie Curie)
- 1.2: Línea de Tiempo (7 eventos cronológicos)
- 1.3: Completar Espacios en Blanco (6 datos biográficos)
- 1.4: Verdadero o Falso (10 afirmaciones sobre hechos explícitos)
- 1.5: Sopa de Letras BONUS (10 palabras de vocabulario científico)
**Cuándo usarlo:**
- Durante testing manual de ejercicios del Módulo 1
- Para crear test data en tests automatizados
- En demos pedagógicas con stakeholders
- Para validar componentes frontend (crucigrama, drag & drop, timers)
- Al desarrollar/ajustar validadores backend
---
#### [GUIA-PRUEBAS-MODULO2-Respuestas-Ejemplo.md](./GUIA-PRUEBAS-MODULO2-Respuestas-Ejemplo.md)
**Audiencia:** QA, desarrolladores frontend/backend, demos pedagógicas
**Tiempo de lectura:** 35-50 minutos (documento completo), 7-10 min por ejercicio
**Última actualización:** 2025-11-23
**Qué contiene:**
- Ejemplos detallados de respuestas para los 5 ejercicios del Módulo 2
- 50+ ejemplos clasificados en 3 niveles: EXCELENTE, ACEPTABLE, INCORRECTA
- Criterios de scoring para inferencias
- Keywords para validadores de texto libre
- Razonamiento inferencial esperado
**Ejercicios cubiertos (Comprensión Inferencial - Cassany Nivel 2):**
- 2.1: Detective Textual (4 preguntas inferenciales: causa-efecto, contexto, motivación)
- 2.2: Relaciones Causa-Efecto (emparejamiento de causas con múltiples consecuencias)
- 2.3: Predicción Narrativa (predicción histórica con 4 filtros de validación)
- 2.4: Puzzle de Contexto (ordenar 4 fragmentos sintácticamente)
- 2.5: Rueda de Inferencias (respuestas abiertas en 4 categorías: literal, inferencial, crítico, creativo)
**Cuándo usarlo:**
- Durante testing manual de ejercicios del Módulo 2
- Para validar evaluación de respuestas abiertas (NLP básico)
- En demos pedagógicas para mostrar pensamiento inferencial
- Para entrenar maestros en evaluación de inferencias estudiantiles
- Al desarrollar validadores de texto libre con keywords
---
#### [GUIA-PRUEBAS-MODULO3-Respuestas-Ejemplo.md](./GUIA-PRUEBAS-MODULO3-Respuestas-Ejemplo.md)
**Audiencia:** QA, desarrolladores frontend/backend, demos pedagógicas
**Tiempo de lectura:** 30-45 minutos (documento completo), 5-10 min por ejercicio
**Última actualización:** 2025-11-23
**Qué contiene:**
- Ejemplos detallados de respuestas para los 5 ejercicios del Módulo 3
- 50+ ejemplos clasificados en 3 niveles: EXCELENTE, ACEPTABLE, INCORRECTA
- Criterios de scoring para cada ejercicio
- Keywords para validadores automáticos
- Datos de prueba listos para usar
**Ejercicios cubiertos (Comprensión Crítica - Cassany Nivel 3):**
- 3.1: Tribunal de Opiniones (8 afirmaciones FACT/OPINION/INTERPRETATION)
- 3.2: Debate Digital (argumentos pro/contra con evidencia)
- 3.3: Análisis de Fuentes (evaluación CRAAP de 5 fuentes)
- 3.4: Podcast Argumentativo (script completo 2 minutos)
- 3.5: Matriz de Perspectivas (6 perspectivas históricas)
**Cuándo usarlo:**
- Durante testing manual de ejercicios del Módulo 3
- Para crear test data en tests automatizados
- En demos pedagógicas con stakeholders
- Para validar componentes frontend (forms, timers, validations)
- Al desarrollar/ajustar validadores backend
---
### ⏳ Documentos Planeados
Los siguientes documentos están planeados pero aún no creados:
#### GLOSARIO.md (Pendiente)
**Audiencia:** Todos
**Prioridad:** P1 (Alta)
**Esfuerzo estimado:** 2-3 horas
**Líneas estimadas:** 300-400
**Contenido planeado:**
- Términos técnicos (multi-tenant, SSOT, DDL, migrations)
- Términos de gamificación (ML Coins, Rangos Maya, achievements)
- Términos educativos (comprensión literal, inferencial, crítica, digital, producción)
- Acrónimos del proyecto (GLIT, API, JWT, RLS, CRUD)
- Conceptos de arquitectura (monorepo, feature-sliced design, repository pattern)
**Cuándo será útil:**
- Para nuevos miembros que no conocen terminología
- Como referencia rápida durante code reviews
- Para documentar decisiones de naming
---
#### QUICK-START.md (Pendiente)
**Audiencia:** Desarrolladores impacientes
**Prioridad:** P1 (Alta)
**Esfuerzo estimado:** 1-2 horas
**Líneas estimadas:** 100-150
**Contenido planeado:**
- Setup en 10 minutos (comandos mínimos)
- Docker Compose one-liner (cuando esté disponible)
- Script de setup automático
- Verificación rápida (1 comando)
**Diferencia con ONBOARDING.md:**
- ONBOARDING.md: Completo, explicado paso a paso (2-3 horas)
- QUICK-START.md: Mínimo, solo comandos (10 minutos)
---
#### ARQUITECTURA-ALTO-NIVEL.md (Pendiente)
**Audiencia:** Tech Leads, arquitectos, senior developers
**Prioridad:** P1 (Alta)
**Esfuerzo estimado:** 3-4 horas
**Líneas estimadas:** 200-250
**Contenido planeado:**
- Diagrama de arquitectura general (Mermaid)
- Flujo de datos Backend ↔ Frontend ↔ Database
- Decisiones arquitectónicas principales
- Patrones de diseño utilizados
- Escalabilidad y performance
- Seguridad (RLS, JWT, sanitización)
**Cuándo será útil:**
- Para entender el big picture técnico
- Antes de proponer cambios arquitectónicos
- Para onboarding de senior developers
---
## 🗺️ Navegación Rápida
### Para Nuevos Desarrolladores
1. **Día 1 - Mañana (2-3 horas):**
- ✅ Lee [VISION.md](./VISION.md) (20 min)
- ✅ Lee [ONBOARDING.md](./ONBOARDING.md) (10 min)
- ✅ Configura entorno local siguiendo ONBOARDING.md (2 horas)
2. **Día 1 - Tarde (2-3 horas):**
- Lee [apps/backend/_MAP.md](../../apps/backend/_MAP.md) (10 min)
- Lee [apps/frontend/_MAP.md](../../apps/frontend/_MAP.md) (10 min)
- Explora codebase (`tree -L 2 apps/`)
3. **Día 2 (4-6 horas):**
- Lee [docs/95-guias-desarrollo/](../95-guias-desarrollo/) (guías de desarrollo)
- Lee [docs/98-standards/](../98-standards/) (estándares de código)
- Ejecuta tests (`npm test` en backend y frontend)
4. **Día 3 (4-6 horas):**
- Toma primera tarea (good-first-issue)
- Crea branch, haz cambios, abre PR
- Participa en code review
---
### Para Stakeholders No-Técnicos
1.**Entender el producto:** [VISION.md](./VISION.md)
2. **Ver roadmap:** [docs/90-transversal/roadmap/](../90-transversal/roadmap/)
3. **Ver métricas:** [docs/90-transversal/metricas/](../90-transversal/metricas/)
---
### Para Tech Leads
1.**Visión del producto:** [VISION.md](./VISION.md)
2. **Arquitectura técnica:** [docs/90-transversal/arquitectura/](../90-transversal/arquitectura/)
3. **Decisiones arquitectónicas:** [docs/97-adr/](../97-adr/)
4. **Estándares de código:** [docs/98-standards/](../98-standards/)
---
## 🔗 Enlaces Relacionados
### Dentro de este Monorepo
**Documentación por Fases:**
- [docs/01-fase-alcance-inicial/](../01-fase-alcance-inicial/) - Fase 1: Fundamentos MVP
- [docs/02-fase-robustecimiento/](../02-fase-robustecimiento/) - Fase 2: BD Modular
- [docs/03-fase-extensiones/](../03-fase-extensiones/) - Fase 3: Extensions MVP
- [docs/04-fase-backlog/](../04-fase-backlog/) - Fase 4: Backlog Futuro
**Documentación Técnica:**
- [docs/95-guias-desarrollo/](../95-guias-desarrollo/) - Guías de desarrollo
- [docs/96-quick-reference/](../96-quick-reference/) - Referencias rápidas
- [docs/97-adr/](../97-adr/) - Architecture Decision Records
- [docs/98-standards/](../98-standards/) - Estándares del proyecto
**Código:**
- [apps/backend/_MAP.md](../../apps/backend/_MAP.md) - Backend (NestJS)
- [apps/frontend/_MAP.md](../../apps/frontend/_MAP.md) - Frontend (React)
- [apps/database/](../../apps/database/) - Database (PostgreSQL)
**Planificación:**
- [docs/90-transversal/roadmap/](../90-transversal/roadmap/) - Roadmap general
- [docs/90-transversal/sprints/](../90-transversal/sprints/) - Sprints históricos
---
### Externos
**Tecnologías principales:**
- [NestJS Documentation](https://docs.nestjs.com/) - Backend framework
- [React Documentation](https://react.dev/) - Frontend library
- [PostgreSQL Documentation](https://www.postgresql.org/docs/) - Database
**Herramientas:**
- [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html)
- [Vite Guide](https://vitejs.dev/guide/)
- [Tailwind CSS Documentation](https://tailwindcss.com/docs)
---
## 📋 Checklist: ¿Qué documento leer?
**Soy nuevo en el proyecto y quiero entender el producto:**
- ✅ [VISION.md](./VISION.md)
**Soy nuevo desarrollador y necesito configurar mi entorno:**
- ✅ [ONBOARDING.md](./ONBOARDING.md)
**Soy Tech Lead y necesito entender la arquitectura:**
- ✅ [VISION.md](./VISION.md) (contexto de negocio)
- ⏳ ARQUITECTURA-ALTO-NIVEL.md (pendiente)
- [docs/90-transversal/arquitectura/](../90-transversal/arquitectura/)
**Soy PM/PO y quiero ver el roadmap:**
- ✅ [VISION.md](./VISION.md) (contexto y métricas)
- [docs/90-transversal/roadmap/](../90-transversal/roadmap/)
**Quiero contribuir al proyecto (developer externo):**
- ✅ [VISION.md](./VISION.md)
- ✅ [ONBOARDING.md](./ONBOARDING.md)
- [docs/98-standards/](../98-standards/)
**No conozco un término técnico:**
- ⏳ GLOSARIO.md (pendiente)
- [docs/96-quick-reference/](../96-quick-reference/)
**Voy a desarrollar ejercicios o gamificación:**
- ✅ [DocumentoDeDiseño_Mecanicas_GAMILIT_v6_1.md](./DocumentoDeDiseño_Mecanicas_GAMILIT_v6_1.md)
**Voy a hacer QA/testing de ejercicios:**
- ✅ Módulo 1: [GUIA-PRUEBAS-MODULO1-Respuestas-Ejemplo.md](./GUIA-PRUEBAS-MODULO1-Respuestas-Ejemplo.md)
- ✅ Módulo 2: [GUIA-PRUEBAS-MODULO2-Respuestas-Ejemplo.md](./GUIA-PRUEBAS-MODULO2-Respuestas-Ejemplo.md)
- ✅ Módulo 3: [GUIA-PRUEBAS-MODULO3-Respuestas-Ejemplo.md](./GUIA-PRUEBAS-MODULO3-Respuestas-Ejemplo.md)
**Necesito datos de prueba para ejercicios:**
- ✅ Módulo 1: [GUIA-PRUEBAS-MODULO1-Respuestas-Ejemplo.md](./GUIA-PRUEBAS-MODULO1-Respuestas-Ejemplo.md)
- ✅ Módulo 2: [GUIA-PRUEBAS-MODULO2-Respuestas-Ejemplo.md](./GUIA-PRUEBAS-MODULO2-Respuestas-Ejemplo.md)
- ✅ Módulo 3: [GUIA-PRUEBAS-MODULO3-Respuestas-Ejemplo.md](./GUIA-PRUEBAS-MODULO3-Respuestas-Ejemplo.md)
---
## 🚨 Issues Conocidos
### P0 (Crítico)
Ninguno en esta carpeta actualmente.
### P1 (Alto)
- **P1-001:** Falta GLOSARIO.md con terminología del proyecto
- **Esfuerzo:** 2-3 horas
- **Impacto:** Nuevos miembros no entienden términos específicos
- **P1-002:** Falta QUICK-START.md para setup rápido
- **Esfuerzo:** 1-2 horas
- **Impacto:** Developers impacientes se frustran con ONBOARDING.md largo
- **P1-003:** Falta ARQUITECTURA-ALTO-NIVEL.md con diagrama general
- **Esfuerzo:** 3-4 horas
- **Impacto:** Tech Leads no tienen big picture visual
---
## 🎯 Próximos Pasos
### Fase 1 (Esta Semana - 6-8 horas)
1. ✅ README.md creado (este archivo)
2. ⬜ Crear GLOSARIO.md (2-3 horas)
3. ⬜ Crear QUICK-START.md (1-2 horas)
4. ⬜ Crear ARQUITECTURA-ALTO-NIVEL.md (3-4 horas)
**Owner:** @tech-lead
**Deadline:** 2025-11-14
---
## 📞 Contacto
**Preguntas sobre documentación:**
- Slack: #gamilit-docs
- Email: docs@gamilit.com
- Owner: @tech-writer
**Preguntas técnicas:**
- Slack: #gamilit-help
- Owner: @tech-lead
---
**Última actualización:** 2025-11-23
**Versión:** 1.1
**Método:** Sistema SIMCO - Fase 3 (Option A - Complete Content)
**Cambios v1.1:** Agregados DocumentoDeDiseño y GUIA-PRUEBAS-MODULO3