Adrian Flores Cortes
967ab360bb
Structure: - control-plane/: Registries, SIMCO directives, CI/CD templates - projects/: Gamilit, ERP-Suite, Trading-Platform, Betting-Analytics - shared/: Libs catalog, knowledge-base Key features: - Centralized port, domain, database, and service registries - 23 SIMCO directives + 6 fundamental principles - NEXUS agent profiles with delegation rules - Validation scripts for workspace integrity - Dockerfiles for all services - Path aliases for quick reference 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
416 lines
13 KiB
Markdown
416 lines
13 KiB
Markdown
# 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)
|