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>
326 lines
11 KiB
Markdown
326 lines
11 KiB
Markdown
# Guía: Agregar Referencias SIMCO en Código DDL
|
|
|
|
## 📋 Objetivo
|
|
|
|
Esta guía explica cómo agregar referencias bidireccionales entre la documentación (carpeta `docs/`) y el código de implementación (carpeta `apps/`) para cumplir con el estándar SIMCO (Sistema Indexado Modular por COntexto).
|
|
|
|
## ✅ Estado Actual
|
|
|
|
### Completado:
|
|
- ✅ **00-prerequisites.sql**: 16 ENUMs con referencias agregadas
|
|
- ✅ **auth_management.profiles**: Tabla de perfiles de usuario
|
|
- ✅ **gamification_system.comodines_inventory**: Tabla de inventario de comodines
|
|
- ✅ **educational_content.exercises**: Tabla de ejercicios
|
|
|
|
### Pendiente:
|
|
- ⏳ ~46 tablas SQL restantes
|
|
- ⏳ ~100 archivos TypeScript en Backend
|
|
- ⏳ ~80 componentes React en Frontend
|
|
|
|
---
|
|
|
|
## 📐 Patrón para Archivos SQL
|
|
|
|
### Formato de Referencias
|
|
|
|
Agregar un bloque de documentación **después del header existente** y **antes del código SQL**:
|
|
|
|
```sql
|
|
-- =====================================================
|
|
-- Table: nombre_schema.nombre_tabla
|
|
-- Description: Descripción de la tabla
|
|
-- ...header existente...
|
|
--
|
|
-- 📚 Documentación:
|
|
-- Requerimiento: docs/01-requerimientos/.../RF-XXX-xxx.md
|
|
-- Especificación: docs/02-especificaciones-tecnicas/.../ET-XXX-xxx.md
|
|
-- Ver también: docs/... (opcional, para referencias adicionales)
|
|
-- =====================================================
|
|
```
|
|
|
|
### Ejemplo Real: auth_management.profiles
|
|
|
|
```sql
|
|
-- =====================================================
|
|
-- Table: auth_management.profiles
|
|
-- Description: Perfiles de usuario con información básica, rol y configuraciones
|
|
-- Dependencies: auth_management.tenants, auth.users
|
|
-- Created: 2025-10-27
|
|
--
|
|
-- 📚 Documentación:
|
|
-- Requerimiento: docs/01-requerimientos/01-autenticacion-autorizacion/RF-AUTH-001-roles.md
|
|
-- Requerimiento: docs/01-requerimientos/01-autenticacion-autorizacion/RF-AUTH-002-estados-cuenta.md
|
|
-- Especificación: docs/02-especificaciones-tecnicas/01-autenticacion-autorizacion/ET-AUTH-001-rbac.md
|
|
-- Especificación: docs/02-especificaciones-tecnicas/01-autenticacion-autorizacion/ET-AUTH-002-estados-cuenta.md
|
|
-- =====================================================
|
|
|
|
SET search_path TO auth_management, public;
|
|
|
|
CREATE TABLE auth_management.profiles (
|
|
...
|
|
);
|
|
```
|
|
|
|
### Ejemplo Real: educational_content.exercises
|
|
|
|
```sql
|
|
-- =====================================================
|
|
-- Table: educational_content.exercises
|
|
-- Description: Ejercicios con 27 mecánicas diferentes
|
|
--
|
|
-- 📚 Documentación:
|
|
-- Requerimiento: docs/01-requerimientos/03-contenido-educativo/RF-EDU-001-mecanicas-ejercicios.md
|
|
-- Especificación: docs/02-especificaciones-tecnicas/03-contenido-educativo/ET-EDU-001-mecanicas-ejercicios.md
|
|
-- Ver también: docs/01-requerimientos/modulos/MODULOS-EDUCATIVOS.md
|
|
-- =====================================================
|
|
```
|
|
|
|
---
|
|
|
|
## 🗺️ Mapeo de Schemas → Documentación
|
|
|
|
### 1. auth_management
|
|
|
|
**Tablas:**
|
|
- `profiles` → RF-AUTH-001 (roles), RF-AUTH-002 (estados cuenta)
|
|
- `linked_providers` → RF-AUTH-003 (OAuth)
|
|
- `sessions`, `tokens` → RF-AUTH-001 (autenticación)
|
|
|
|
### 2. gamification_system
|
|
|
|
**Tablas:**
|
|
- `achievements`, `user_achievements` → RF-GAM-001 (achievements)
|
|
- `comodines_inventory` → RF-GAM-002 (comodines)
|
|
- `leaderboards`, `user_stats` → RF-GAM-003 (rangos Maya)
|
|
- `ml_coins_transactions` → RF-GAM-002 (ML Coins)
|
|
- `missions`, `user_missions` → RF-GAM-001 (misiones)
|
|
|
|
### 3. educational_content
|
|
|
|
**Tablas:**
|
|
- `modules` → RF-EDU-001 (módulos educativos)
|
|
- `exercises` → RF-EDU-001 (31 mecánicas)
|
|
- `media_resources` → RF-CNT-001 (gestión media)
|
|
- `assessment_rubrics` → RF-EDU-001 (evaluación)
|
|
|
|
### 4. progress_tracking
|
|
|
|
**Tablas:**
|
|
- `module_progress` → RF-PRG-001 (estados progreso)
|
|
- `learning_sessions` → RF-PRG-001 (sesiones)
|
|
- `exercise_attempts` → RF-PRG-001 (intentos)
|
|
- `exercise_submissions` → RF-PRG-001 (envíos)
|
|
|
|
### 5. social_features
|
|
|
|
**Tablas:**
|
|
- `classrooms` → RF-SOC-001 (aulas virtuales)
|
|
- `classroom_members` → RF-SOC-001
|
|
- `teams`, `team_members` → RF-SOC-001 (equipos)
|
|
- `friendships` → RF-SOC-001 (amistades)
|
|
|
|
### 6. audit_logging
|
|
|
|
**Tablas:**
|
|
- `audit_logs` → RF-AUD-001 (sistema auditoría)
|
|
- `admin_audit_log` → RF-AUD-001
|
|
- `security_alerts` → RF-AUD-001 (alertas)
|
|
|
|
### 7. content_management
|
|
|
|
**Tablas:**
|
|
- `media_files` → RF-CNT-001 (gestión media)
|
|
- `content_versions` → RF-CNT-001 (versionado)
|
|
|
|
---
|
|
|
|
## 📂 Archivos Pendientes por Schema
|
|
|
|
### Prioridad Alta (Core Functionality)
|
|
|
|
```bash
|
|
# auth_management (5 tablas)
|
|
apps/database/ddl/schemas/auth_management/tables/01-tenants.sql
|
|
apps/database/ddl/schemas/auth_management/tables/02-tenant_metadata.sql
|
|
apps/database/ddl/schemas/auth_management/tables/04-linked_providers.sql
|
|
apps/database/ddl/schemas/auth_management/tables/05-sessions.sql
|
|
apps/database/ddl/schemas/auth_management/tables/06-auth_tokens.sql
|
|
|
|
# gamification_system (8 tablas)
|
|
apps/database/ddl/schemas/gamification_system/tables/01-user_stats.sql
|
|
apps/database/ddl/schemas/gamification_system/tables/02-achievements.sql
|
|
apps/database/ddl/schemas/gamification_system/tables/03-user_achievements.sql
|
|
apps/database/ddl/schemas/gamification_system/tables/04-leaderboards.sql
|
|
apps/database/ddl/schemas/gamification_system/tables/05-ml_coins_transactions.sql
|
|
apps/database/ddl/schemas/gamification_system/tables/06-missions.sql
|
|
apps/database/ddl/schemas/gamification_system/tables/08-user_missions.sql
|
|
apps/database/ddl/schemas/gamification_system/tables/09-notifications.sql
|
|
|
|
# educational_content (3 tablas)
|
|
apps/database/ddl/schemas/educational_content/tables/01-modules.sql
|
|
apps/database/ddl/schemas/educational_content/tables/03-assessment_rubrics.sql
|
|
apps/database/ddl/schemas/educational_content/tables/04-media_resources.sql
|
|
|
|
# progress_tracking (5 tablas)
|
|
apps/database/ddl/schemas/progress_tracking/tables/01-module_progress.sql
|
|
apps/database/ddl/schemas/progress_tracking/tables/02-learning_sessions.sql
|
|
apps/database/ddl/schemas/progress_tracking/tables/03-exercise_attempts.sql
|
|
apps/database/ddl/schemas/progress_tracking/tables/04-exercise_submissions.sql
|
|
apps/database/ddl/schemas/progress_tracking/tables/05-scheduled_missions.sql
|
|
|
|
# social_features (6 tablas)
|
|
apps/database/ddl/schemas/social_features/tables/01-classrooms.sql
|
|
apps/database/ddl/schemas/social_features/tables/02-classroom_members.sql
|
|
apps/database/ddl/schemas/social_features/tables/03-teams.sql
|
|
apps/database/ddl/schemas/social_features/tables/04-team_members.sql
|
|
apps/database/ddl/schemas/social_features/tables/05-friendships.sql
|
|
apps/database/ddl/schemas/social_features/tables/06-user_activity.sql
|
|
|
|
# audit_logging (3 tablas)
|
|
apps/database/ddl/schemas/audit_logging/tables/01-audit_logs.sql
|
|
apps/database/ddl/schemas/audit_logging/tables/02-admin_audit_log.sql
|
|
apps/database/ddl/schemas/audit_logging/tables/03-security_alerts.sql
|
|
|
|
# content_management (2 tablas)
|
|
apps/database/ddl/schemas/content_management/tables/01-media_files.sql
|
|
apps/database/ddl/schemas/content_management/tables/02-content_versions.sql
|
|
```
|
|
|
|
---
|
|
|
|
## 🔄 Proceso para Agregar Referencias
|
|
|
|
### 1. Identificar la tabla
|
|
```bash
|
|
# Ejemplo
|
|
vim apps/database/ddl/schemas/gamification_system/tables/01-user_stats.sql
|
|
```
|
|
|
|
### 2. Leer el header existente
|
|
```sql
|
|
-- =====================================================
|
|
-- Table: gamification_system.user_stats
|
|
-- Description: Estadísticas de gamificación por usuario
|
|
-- Created: 2025-10-27
|
|
-- =====================================================
|
|
```
|
|
|
|
### 3. Agregar bloque de documentación
|
|
```sql
|
|
-- =====================================================
|
|
-- Table: gamification_system.user_stats
|
|
-- Description: Estadísticas de gamificación por usuario
|
|
-- Created: 2025-10-27
|
|
--
|
|
-- 📚 Documentación:
|
|
-- Requerimiento: docs/01-requerimientos/02-gamificacion/RF-GAM-001-achievements.md
|
|
-- Requerimiento: docs/01-requerimientos/02-gamificacion/RF-GAM-003-rangos-maya.md
|
|
-- Especificación: docs/02-especificaciones-tecnicas/02-gamificacion/ET-GAM-001-achievements.md
|
|
-- Especificación: docs/02-especificaciones-tecnicas/02-gamificacion/ET-GAM-003-rangos-maya.md
|
|
-- =====================================================
|
|
```
|
|
|
|
### 4. Verificar que las rutas existan
|
|
```bash
|
|
ls -la ../../docs/01-requerimientos/02-gamificacion/RF-GAM-001-achievements.md
|
|
ls -la ../../docs/02-especificaciones-tecnicas/02-gamificacion/ET-GAM-001-achievements.md
|
|
```
|
|
|
|
### 5. Commit con mensaje descriptivo
|
|
```bash
|
|
git add apps/database/ddl/schemas/gamification_system/tables/01-user_stats.sql
|
|
git commit -m "docs(ddl): Agregar referencias SIMCO en user_stats
|
|
|
|
- RF-GAM-001: Sistema de Achievements
|
|
- RF-GAM-003: Sistema de Rangos Maya
|
|
- ET-GAM-001: Implementación Achievements
|
|
- ET-GAM-003: Implementación Rangos Maya
|
|
|
|
Parte de Fase 3.2: Referencias en código DDL"
|
|
```
|
|
|
|
---
|
|
|
|
## 🎯 Próximos Pasos
|
|
|
|
### Fase 3.2: DDL (restante)
|
|
- [ ] Completar 32 tablas restantes (~4-6 horas)
|
|
- [ ] Agregar referencias en funciones SQL (~2 horas)
|
|
- [ ] Agregar referencias en vistas (~1 hora)
|
|
|
|
### Fase 3.3: Backend TypeScript
|
|
Agregar JSDoc con referencias:
|
|
|
|
```typescript
|
|
/**
|
|
* Service para gestionar achievements de gamificación
|
|
*
|
|
* @see {@link RF-GAM-001} docs/01-requerimientos/02-gamificacion/RF-GAM-001-achievements.md
|
|
* @see {@link ET-GAM-001} docs/02-especificaciones-tecnicas/02-gamificacion/ET-GAM-001-achievements.md
|
|
*/
|
|
export class AchievementService {
|
|
// ...
|
|
}
|
|
```
|
|
|
|
### Fase 3.4: Frontend React
|
|
Agregar JSDoc con referencias:
|
|
|
|
```typescript
|
|
/**
|
|
* Componente para mostrar galería de achievements desbloqueados
|
|
*
|
|
* @see {@link RF-GAM-001} docs/01-requerimientos/02-gamificacion/RF-GAM-001-achievements.md
|
|
* @see {@link TEACHER-PORTAL-API} docs/02-especificaciones-tecnicas/apis/TEACHER-PORTAL-API.md#achievements
|
|
*/
|
|
export const AchievementGallery: React.FC<Props> = () => {
|
|
// ...
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 📊 Progreso Estimado
|
|
|
|
| Fase | Estado | Archivos | Tiempo Estimado |
|
|
|------|--------|----------|-----------------|
|
|
| **3.1: ENUMs** | ✅ Completado | 1 archivo (16 ENUMs) | 1 hora |
|
|
| **3.2: Tablas DDL** | ⏳ 10% (4/46) | 42 archivos restantes | 5-7 horas |
|
|
| **3.3: Backend** | ⏳ Pendiente | ~100 archivos | 8-10 horas |
|
|
| **3.4: Frontend** | ⏳ Pendiente | ~80 archivos | 6-8 horas |
|
|
|
|
**Total Fase 3:** 20-26 horas de trabajo
|
|
|
|
---
|
|
|
|
## ✅ Validación
|
|
|
|
Para verificar que las referencias están correctas:
|
|
|
|
```bash
|
|
# Validar que todos los archivos referenciados existen
|
|
cd apps/database/ddl
|
|
grep -r "Requerimiento: docs/" . | while read line; do
|
|
file=$(echo "$line" | sed 's/.*Requerimiento: docs/docs/g' | sed 's/\.md.*/\.md/g')
|
|
if [ ! -f "../../$file" ]; then
|
|
echo "❌ FALTA: $file"
|
|
else
|
|
echo "✅ OK: $file"
|
|
fi
|
|
done
|
|
```
|
|
|
|
---
|
|
|
|
## 📚 Referencias
|
|
|
|
- **Plan SIMCO Original**: `docs/PROGRESO-PLAN-SIMCO-2025-11-07.md`
|
|
- **Ejemplo completo**: `apps/database/ddl/00-prerequisites.sql`
|
|
- **Documentación SIMCO**: `docs/_MAP.md`
|
|
|
|
---
|
|
|
|
**Última actualización**: 2025-11-07
|
|
**Autor**: Database Team
|
|
**Estado**: 🟡 En progreso (Fase 3.2)
|