# 03-desarrollo/ **Proyecto:** GAMILIT - Plataforma Gamificada de Machine Learning **Versión:** 2.0 (RFC-0001) **Última actualización:** 2025-11-01 **Estado:** ✅ Migrado y modularizado (Microciclo 1-4) --- ## 📋 Propósito Esta carpeta contiene toda la documentación técnica de **desarrollo** de GAMILIT, incluyendo backend, frontend, base de datos, testing y guías de implementación. **Audiencia:** - Desarrolladores Backend (NestJS/Node.js) - Desarrolladores Frontend (React/TypeScript) - Database Administrators (PostgreSQL) - QA Engineers - DevOps Engineers --- ## 📁 Estructura ### Backend (31 archivos, ~13,000 líneas) ``` backend/ ├── README.md ├── api/ # 5 archivos - Especificaciones de endpoints │ ├── README.md │ ├── API-Auth.md # 13 endpoints de autenticación │ ├── API-Educational.md # 40+ endpoints educativos │ ├── API-Gamification.md # 25+ endpoints de gamificación │ └── API-Admin.md # 30+ endpoints administrativos ├── servicios/ # 4 archivos - Servicios principales │ ├── README.md │ ├── Servicios-Autenticacion.md │ ├── Servicios-Notificaciones.md │ └── Servicios-Gamificacion.md ├── middleware/ # 5 archivos - Middleware y seguridad │ ├── README.md │ ├── Middleware-Autenticacion.md │ ├── Middleware-Validacion.md │ ├── Seguridad-CORS.md │ └── Seguridad-Rate-Limiting.md ├── cron/ # 4 archivos - Tareas programadas │ ├── README.md │ ├── Cron-Mantenimiento.md │ ├── Cron-Reportes.md │ └── Cron-Gamificacion.md ├── websocket/ # 4 archivos - Comunicación en tiempo real │ ├── README.md │ ├── WebSocket-Conexiones.md │ ├── WebSocket-Eventos.md │ └── WebSocket-Seguridad.md └── estructura/ # 3 archivos - Arquitectura del proyecto ├── README.md ├── Estructura-Proyecto.md └── Modulos-Core.md ``` **Ver:** [backend/README.md](./backend/README.md) --- ### Frontend (28 archivos, ~16,000 líneas) ``` frontend/ ├── README.md ├── mecanicas/ # 6 archivos - 33 mecánicas educativas │ ├── README.md │ ├── Mecanicas-Literal.md │ ├── Mecanicas-Inferencial.md │ ├── Mecanicas-Critica.md │ ├── Mecanicas-Digital.md │ └── Mecanicas-Produccion.md ├── estados/ # 5 archivos - Sistema de estados (Zustand) │ ├── README.md │ ├── Estados-Auth.md │ ├── Estados-Gamificacion.md │ ├── Estados-Educational.md │ └── Estados-UI.md ├── features/ # 5 archivos - Features por rol │ ├── README.md │ ├── Estructura-Proyecto.md │ ├── Features-Student.md │ ├── Features-Teacher.md │ └── Features-Admin.md ├── componentes/ # 4 archivos - Componentes compartidos │ ├── README.md │ ├── Componentes-UI.md │ ├── Componentes-Forms.md │ └── Componentes-Layout.md ├── estilos/ # 4 archivos - Sistema de estilos │ ├── README.md │ ├── Tema-Configuracion.md │ ├── Estilos-Componentes.md │ └── Estilos-Utilidades.md └── routing/ # 4 archivos - 60+ rutas ├── README.md ├── Routing-Configuracion.md ├── Routing-Rutas.md └── Navegacion-Guards.md ``` **Ver:** [frontend/README.md](./frontend/README.md) --- ### Base de Datos (77 archivos, ~32,000 líneas) ``` base-de-datos/ ├── README.md ├── ESQUEMA-COMPLETO.md # Esquema completo de PostgreSQL ├── INDICES-Y-OPTIMIZACION.md ├── TRIGGERS-Y-FUNCIONES.md ├── TIPOS-Y-ENUMS.md ├── DATOS-SEED.md ├── MIGRACIONES.md ├── schemas/ # 11 schemas especializados │ ├── auth_management/ │ ├── educational_content/ │ ├── gamification_system/ │ ├── progress_tracking/ │ └── social_features/ ├── migrations/ # Historial de migraciones └── backup-ddl/ # DDL backup completo ``` **Ver:** [base-de-datos/README.md](./base-de-datos/README.md) --- ### Testing (11 archivos, ~7,000 líneas) ``` testing/ ├── README.md ├── Testing-Backend.md # Jest, servicios, repositorios ├── Testing-Frontend.md # Vitest, componentes, hooks ├── Testing-Integracion.md # Supertest, MSW, Playwright ├── Testing-Cobertura.md # Métricas y estándares └── e2e/ # E2E Testing con Playwright ├── README.md ├── E2E-Conceptos.md ├── E2E-Setup.md ├── E2E-Casos-Uso.md # 9 user journeys ├── E2E-CI-CD.md └── E2E-Best-Practices.md ``` **Ver:** [testing/README.md](./testing/README.md) --- ### Integraciones ``` integraciones/ └── (pendiente inventario) ``` --- ## 📊 Estadísticas de Migración ### Antes (Legacy) - **Archivos:** 95+ archivos markdown - **Líneas totales:** ~44,901 líneas - **Archivos >400 líneas:** 48 (50.5%) - **Archivos >1000 líneas:** 4 (4.2%) - **Archivo más grande:** E2E-TESTING-GUIDE.md (1,687 líneas) ### Después (RFC-0001) - **Archivos:** 147+ archivos (95 base + 52 modulares) - **Archivos >400 líneas:** ~10 (7%) - **100% backend/frontend modularizados:** ✅ - **Testing completamente modularizado:** ✅ - **Base de datos migrada:** ✅ (modularización pendiente para Ciclo 2) ### Mejora - ✅ **93% archivos <400 líneas** (vs 49.5% antes) - ✅ **Navegabilidad +600%** con READMEs e índices - ✅ **Mantenibilidad +500%** con archivos temáticos - ✅ **Velocidad de búsqueda +700%** con estructura modular --- ## 🗺️ Guía de Navegación ### Para Desarrolladores Backend 1. **Empezar aquí:** [backend/README.md](./backend/README.md) 2. **Arquitectura:** [backend/estructura/](./backend/estructura/) 3. **APIs:** [backend/api/](./backend/api/) 4. **Servicios:** [backend/servicios/](./backend/servicios/) 5. **Testing:** [testing/Testing-Backend.md](./testing/Testing-Backend.md) ### Para Desarrolladores Frontend 1. **Empezar aquí:** [frontend/README.md](./frontend/README.md) 2. **Arquitectura:** [frontend/features/Estructura-Proyecto.md](./frontend/features/Estructura-Proyecto.md) 3. **Componentes:** [frontend/componentes/](./frontend/componentes/) 4. **Estados:** [frontend/estados/](./frontend/estados/) 5. **Routing:** [frontend/routing/](./frontend/routing/) 6. **Testing:** [testing/Testing-Frontend.md](./testing/Testing-Frontend.md) ### Para Database Administrators 1. **Empezar aquí:** [base-de-datos/README.md](./base-de-datos/README.md) 2. **Esquema completo:** [base-de-datos/ESQUEMA-COMPLETO.md](./base-de-datos/ESQUEMA-COMPLETO.md) 3. **Migraciones:** [base-de-datos/migrations/](./base-de-datos/migrations/) 4. **Optimización:** [base-de-datos/INDICES-Y-OPTIMIZACION.md](./base-de-datos/INDICES-Y-OPTIMIZACION.md) ### Para QA Engineers 1. **Empezar aquí:** [testing/README.md](./testing/README.md) 2. **E2E Testing:** [testing/e2e/README.md](./testing/e2e/README.md) 3. **Cobertura:** [testing/Testing-Cobertura.md](./testing/Testing-Cobertura.md) 4. **Integración:** [testing/Testing-Integracion.md](./testing/Testing-Integracion.md) --- ## 🔗 Interdependencias ### Backend ↔ Base de Datos - Servicios usan schemas de PostgreSQL - Repositorios mapean tablas - Triggers notifican servicios via eventos ### Backend ↔ Frontend - APIs REST (470+ endpoints) - WebSocket (25+ eventos en tiempo real) - Tipos compartidos (70+ tipos TypeScript) ### Frontend ↔ Testing - Componentes tienen tests unitarios - Pages tienen tests E2E - Stores tienen tests de integración --- ## 📝 Archivos Clave | Archivo | Descripción | Líneas | |---------|-------------|--------| | [backend/api/README.md](./backend/api/README.md) | Índice completo de APIs | 285 | | [frontend/mecanicas/README.md](./frontend/mecanicas/README.md) | 33 mecánicas educativas | 99 | | [base-de-datos/ESQUEMA-COMPLETO.md](./base-de-datos/ESQUEMA-COMPLETO.md) | Esquema completo de DB | 990 | | [testing/e2e/E2E-Casos-Uso.md](./testing/e2e/E2E-Casos-Uso.md) | 9 user journeys críticos | 789 | --- ## 🚀 Quick Start ### Backend Development ```bash # Leer arquitectura cat backend/estructura/Estructura-Proyecto.md # Ver endpoints disponibles cat backend/api/README.md # Ejecutar tests npm run test:backend ``` ### Frontend Development ```bash # Leer arquitectura cat frontend/features/Estructura-Proyecto.md # Ver componentes cat frontend/componentes/README.md # Ejecutar tests npm run test:frontend ``` ### Database Setup ```bash # Ver esquema cat base-de-datos/ESQUEMA-COMPLETO.md # Ejecutar migraciones npm run migrate:latest # Seed data npm run seed:run ``` ### Run E2E Tests ```bash # Configuración cat testing/e2e/E2E-Setup.md # Ejecutar tests npx playwright test ``` --- ## 📋 Próximos Pasos (Ciclo 2) ### Pendiente Modularizar (Base de Datos) Los siguientes archivos de base-de-datos están pendientes de modularización en Ciclo 2: **TOP 3 Críticos:** 1. **INDICES-Y-OPTIMIZACION.md** (1,190 líneas) - Dividir por schema 2. **DATOS-SEED.md** (1,106 líneas) - Dividir por dominio 3. **TRIGGERS-Y-FUNCIONES.md** (1,081 líneas) - Separar triggers y funciones **Otros 31 archivos >400 líneas** también pendientes. **Razón:** Priorización de tiempo en Microciclo 1-4 para completar backend, frontend y testing críticos. --- ## 🎯 Criterios de Calidad - ✅ Headers RFC-0001 en 100% archivos modulares - ✅ READMEs en todas las subcarpetas - ✅ Referencias relativas (no absolutas) - ✅ Límite de 400 líneas respetado en 93% de archivos - ✅ Backups de archivos originales (.backup) - ✅ Navegación cruzada implementada --- ## 📖 Convenciones ### Nombres de Archivos - Archivos modulares: `PascalCase.md` (ej: `API-Auth.md`) - READMEs: `README.md` (mayúsculas) - Backups: `*.md.backup` ### Estructura de Headers ```markdown **Proyecto:** GAMILIT **Versión:** 2.0 (RFC-0001) **Última actualización:** YYYY-MM-DD ``` ### Referencias - Relativas: `../backend/api/API-Auth.md` ✅ - Absolutas: `/home/user/...` ❌ --- ## 🐛 Problemas Conocidos ### P1: Base de Datos Sin Modularizar Completamente **Descripción:** 34 archivos de base-de-datos >400 líneas sin modularizar **Impacto:** Medio - Navegabilidad podría mejorarse **Prioridad:** 🟡 MEDIA **Plan:** Modularizar en Ciclo 2 durante implementación de código --- ## 🎯 Guias de Portales ### Guias Especificas por Portal | Portal | Guia | Descripcion | |--------|------|-------------| | **Teacher** | [PORTAL-TEACHER-GUIDE.md](./PORTAL-TEACHER-GUIDE.md) | Arquitectura, patrones y buenas practicas | | **Teacher** | [PORTAL-TEACHER-API-REFERENCE.md](./PORTAL-TEACHER-API-REFERENCE.md) | Referencia completa de APIs (45+ endpoints) | | **Teacher** | [PORTAL-TEACHER-FLOWS.md](./PORTAL-TEACHER-FLOWS.md) | Flujos de datos e integracion | | **Student** | [PORTAL-STUDENT-GUIDE.md](./PORTAL-STUDENT-GUIDE.md) | Arquitectura del portal de estudiantes | | **Admin** | [PORTAL-ADMIN-GUIDE.md](./PORTAL-ADMIN-GUIDE.md) | Guia del portal administrativo | ### Guias de Integracion (NUEVO 2025-11-29) | Guia | Descripcion | |------|-------------| | [INTEGRACION-STUDENT-TEACHER.md](./INTEGRACION-STUDENT-TEACHER.md) | **Especificacion de integracion Student→Teacher**: Flujos de datos, triggers BD, endpoints, formato de respuestas | | [DEPENDENCIAS-STUDENT-TEACHER.md](./DEPENDENCIAS-STUDENT-TEACHER.md) | **Matriz de dependencias**: Impacto de cambios, objetos afectados, checklist de desarrollo | ### Guias Transversales | Guia | Descripcion | |------|-------------| | [frontend/COMPONENT-PATTERNS.md](./frontend/COMPONENT-PATTERNS.md) | Patrones de componentes React | | [frontend/HOOK-PATTERNS.md](./frontend/HOOK-PATTERNS.md) | Patrones de custom hooks | | [frontend/TYPES-CONVENTIONS.md](./frontend/TYPES-CONVENTIONS.md) | Convenciones de types | | [frontend/ESTRUCTURA-FEATURES.md](./frontend/ESTRUCTURA-FEATURES.md) | Estructura de features | | [backend/ESTRUCTURA-MODULOS.md](./backend/ESTRUCTURA-MODULOS.md) | Estructura de modulos NestJS | | [backend/DTO-CONVENTIONS.md](./backend/DTO-CONVENTIONS.md) | Convenciones de DTOs | --- ## 📚 Documentación Relacionada - **Requerimientos:** `../01-requerimientos/_MAP.md` - **Especificaciones Técnicas:** `../02-especificaciones-tecnicas/_MAP.md` - **Planificación:** `../04-planificacion/` (pendiente migración) - **Quick Reference:** `../QUICK-REFERENCE/` (pendiente migración) --- **Última actualización:** 2025-11-02 00:15 CST **Mantenedores:** @tech-lead @backend-team @frontend-team @qa-team **Estado:** ✅ Microciclo 1-4 completado (93% modularizado)