workspace/projects/gamilit/docs/90-transversal/features/SOCIAL-FEATURES-COMPLETO.md

Características Sociales - Schema: social_features

Schema: social_features Propósito: Funcionalidades sociales y colaborativas de GAMILIT Total de tablas: 7 Estado: ✅ Implementado Última actualización: 2025-11-08

---

📋 Descripción

El schema social_features implementa todas las funcionalidades sociales y colaborativas de la plataforma GAMILIT, incluyendo:

• 🏫 Escuelas e instituciones educativas
• 👥 Aulas virtuales (classrooms)
• 🤝 Sistema de amistades
• 🎯 Equipos colaborativos
• 🏆 Desafíos entre equipos

---

📊 TABLAS DEL SCHEMA (7)

Tabla	Propósito	Registros estimados	Estado Docs
schools	Escuelas/instituciones	~100-1000	⚠️ Parcial
classrooms	Aulas virtuales	~1000-10000	✅ EXT-001
classroom_members	Estudiantes en aulas	~10000-100000	✅ EXT-001
friendships	Amistades entre usuarios	~50000+	⚠️ Parcial
teams	Equipos de estudiantes	~5000-20000	⚠️ Parcial
team_members	Miembros de equipos	~20000-80000	⚠️ Parcial
team_challenges	Desafíos entre equipos	~1000-5000	⚠️ Parcial

---

🏫 TABLA: schools

Archivo: apps/database/ddl/schemas/social_features/tables/02-schools.sql

Propósito

Gestión de escuelas e instituciones educativas en el sistema multi-tenant.

Columnas Principales

CREATE TABLE social_features.schools (
    id UUID PRIMARY KEY,
    tenant_id UUID NOT NULL,              -- Tenant propietario
    name TEXT NOT NULL,                   -- Nombre de la escuela
    code TEXT,                            -- Código único de escuela
    short_name TEXT,                      -- Nombre corto/acrónimo
    description TEXT,

    -- Información de contacto
    address TEXT,
    city TEXT,
    region TEXT,
    country TEXT DEFAULT 'México',
    postal_code TEXT,
    phone TEXT,
    email TEXT,
    website TEXT,

    -- Personal administrativo
    principal_id UUID,                    -- Director
    administrative_contact_id UUID,       -- Contacto administrativo

    -- Configuración académica
    academic_year TEXT,                   -- Año académico actual
    semester_system BOOLEAN DEFAULT true, -- Sistema semestral o anual
    grade_levels TEXT[] DEFAULT ARRAY['6','7','8'], -- Grados que imparte
    settings JSONB DEFAULT '{}',

    -- Capacidades
    max_students INTEGER DEFAULT 1000,
    max_teachers INTEGER DEFAULT 100,
    current_students_count INTEGER DEFAULT 0,
    current_teachers_count INTEGER DEFAULT 0,

    -- Estado
    is_active BOOLEAN DEFAULT true,
    is_verified BOOLEAN DEFAULT false,    -- Escuela verificada
    metadata JSONB DEFAULT '{}',

    created_at TIMESTAMPTZ DEFAULT gamilit.now_mexico(),
    updated_at TIMESTAMPTZ DEFAULT gamilit.now_mexico()
);

Características

• ✅ Multi-tenancy (una escuela por tenant)
• ✅ Verificación de instituciones
• ✅ Contadores automáticos de estudiantes y maestros
• ✅ Configuración flexible por escuela
• ✅ Soporta diferentes sistemas académicos

Casos de Uso

1. Registro de Escuela: Director registra su institución
2. Gestión Administrativa: Asignación de personal
3. Configuración Académica: Definir grados, semestres
4. Estadísticas: Tracking de población estudiantil

Relaciones

• tenant_id → auth_management.tenants
• principal_id → auth.users (rol: admin_teacher)
• classrooms.school_id → schools.id

RLS Policies

• Directores pueden ver/editar su escuela
• Maestros pueden ver escuelas donde trabajan
• Super admins pueden ver todas

---

👥 TABLA: classrooms

Archivo: apps/database/ddl/schemas/social_features/tables/03-classrooms.sql

Propósito

Aulas virtuales donde maestros organizan estudiantes y asignan tareas.

Columnas Principales

CREATE TABLE social_features.classrooms (
    id UUID PRIMARY KEY,
    school_id UUID,                       -- Escuela (opcional)
    tenant_id UUID NOT NULL,
    teacher_id UUID NOT NULL,             -- Maestro responsable

    name TEXT NOT NULL,                   -- "6to A - Matemáticas"
    code TEXT UNIQUE,                     -- Código de invitación
    description TEXT,
    subject TEXT,                         -- Materia
    grade_level TEXT,                     -- Grado escolar
    academic_year TEXT,
    semester TEXT,

    -- Capacidad
    max_students INTEGER DEFAULT 40,
    current_members_count INTEGER DEFAULT 0,

    -- Configuración
    allow_self_enrollment BOOLEAN DEFAULT false,
    require_approval BOOLEAN DEFAULT true,
    is_public BOOLEAN DEFAULT false,

    -- Estado
    is_active BOOLEAN DEFAULT true,
    is_archived BOOLEAN DEFAULT false,

    -- Gamificación
    total_xp INTEGER DEFAULT 0,
    total_ml_coins INTEGER DEFAULT 0,

    settings JSONB DEFAULT '{}',
    metadata JSONB DEFAULT '{}',

    created_at TIMESTAMPTZ DEFAULT gamilit.now_mexico(),
    updated_at TIMESTAMPTZ DEFAULT gamilit.now_mexico()
);

Características

• ✅ Códigos de invitación únicos
• ✅ Auto-inscripción opcional
• ✅ Gamificación grupal
• ✅ Archivado de clases pasadas
• ✅ Multi-materia y multi-grado

Casos de Uso

1. Crear Aula: Maestro crea aula para su curso
2. Invitar Estudiantes: Compartir código de aula
3. Organización: Agrupar por materia/grado
4. Seguimiento: Métricas de progreso grupal

Relaciones

• school_id → schools.id
• teacher_id → auth.users (rol: admin_teacher)
• tenant_id → auth_management.tenants

Documentación Relacionada

• ✅ EXT-001: Portal de Maestros (US-PM-001a, US-PM-001b)
• ✅ Funciones: assign_to_classroom(), calculate_classroom_progress()

---

📚 TABLA: classroom_members

Archivo: apps/database/ddl/schemas/social_features/tables/04-classroom_members.sql

Propósito

Relación estudiante-aula con información de inscripción.

Columnas Principales

CREATE TABLE social_features.classroom_members (
    id UUID PRIMARY KEY,
    classroom_id UUID NOT NULL,
    user_id UUID NOT NULL,               -- Estudiante

    -- Inscripción
    enrollment_method TEXT,              -- 'invite','code','bulk','manual'
    enrolled_by UUID,                    -- Maestro que inscribió
    enrolled_at TIMESTAMPTZ DEFAULT gamilit.now_mexico(),

    -- Estado
    status TEXT DEFAULT 'active',        -- 'active','dropped','completed'
    is_active BOOLEAN DEFAULT true,

    -- Seguimiento
    attendance_rate NUMERIC(5,2),        -- % asistencia
    participation_score INTEGER,
    last_activity_at TIMESTAMPTZ,

    metadata JSONB DEFAULT '{}',
    created_at TIMESTAMPTZ DEFAULT gamilit.now_mexico(),
    updated_at TIMESTAMPTZ DEFAULT gamilit.now_mexico(),

    UNIQUE(classroom_id, user_id)
);

Características

• ✅ Constraint de unicidad (un estudiante una vez por aula)
• ✅ Tracking de método de inscripción
• ✅ Métricas de participación
• ✅ Estado de inscripción (activo/abandonado/completado)

Casos de Uso

1. Inscripción: Estudiante se une a aula
2. Gestión: Maestro ve lista de estudiantes
3. Analytics: Asistencia y participación
4. Graduación: Marcar como completado al fin de curso

Triggers

• update_classroom_member_count() - Actualiza contador en classroom

Documentación Relacionada

• ✅ EXT-001: Portal de Maestros (US-PM-001b)

---

🤝 TABLA: friendships

Archivo: apps/database/ddl/schemas/social_features/tables/01-friendships.sql

Propósito

Sistema de amistades entre estudiantes para interacción social.

Columnas Principales

CREATE TABLE social_features.friendships (
    id UUID PRIMARY KEY,
    user_id UUID NOT NULL,               -- Usuario que envía solicitud
    friend_id UUID NOT NULL,             -- Usuario receptor

    status VARCHAR(20) DEFAULT 'pending', -- 'pending','accepted','rejected','blocked'

    created_at TIMESTAMPTZ DEFAULT gamilit.now_mexico(),
    updated_at TIMESTAMPTZ DEFAULT gamilit.now_mexico(),

    CONSTRAINT friendships_check CHECK (user_id <> friend_id),
    CONSTRAINT friendships_status_check CHECK (
        status IN ('pending', 'accepted', 'rejected', 'blocked')
    ),

    UNIQUE(user_id, friend_id)
);

Estados de Amistad

Estado	Descripción
pending	Solicitud enviada, esperando respuesta
accepted	Amigos confirmados
rejected	Solicitud rechazada
blocked	Usuario bloqueado

Características

• ✅ Constraint para evitar auto-amistad
• ✅ Unicidad bidireccional
• ✅ Estados bien definidos
• ✅ Sistema de bloqueo

Casos de Uso

1. Enviar Solicitud: Estudiante envía solicitud de amistad
2. Aceptar/Rechazar: Receptor responde a solicitud
3. Ver Amigos: Lista de amigos aceptados
4. Bloquear: Prevenir interacción con usuario específico

Funcionalidad Social

• Ver progreso de amigos
• Comparar logros
• Desafíos entre amigos
• Chat/mensajería (futuro)

RLS Policies

• Solo usuarios involucrados pueden ver la relación
• Solo receptor puede cambiar estado de pending
• Solo user_id puede bloquear

---

🎯 TABLA: teams

Archivo: apps/database/ddl/schemas/social_features/tables/05-teams.sql

Propósito

Equipos colaborativos de estudiantes para gamificación y aprendizaje grupal.

Columnas Principales

CREATE TABLE social_features.teams (
    id UUID PRIMARY KEY,
    classroom_id UUID,                    -- Aula (opcional)
    tenant_id UUID NOT NULL,

    -- Identidad del equipo
    name TEXT NOT NULL,
    description TEXT,
    motto TEXT,                           -- Lema del equipo
    color_primary TEXT DEFAULT '#3B82F6',
    color_secondary TEXT DEFAULT '#10B981',
    avatar_url TEXT,
    banner_url TEXT,
    badges JSONB DEFAULT '[]',            -- Insignias del equipo

    -- Liderazgo
    creator_id UUID NOT NULL,             -- Fundador
    leader_id UUID,                       -- Líder actual

    -- Membresía
    team_code TEXT UNIQUE,                -- Código de invitación
    max_members INTEGER DEFAULT 5,
    current_members_count INTEGER DEFAULT 0,

    -- Configuración
    is_public BOOLEAN DEFAULT false,
    allow_join_requests BOOLEAN DEFAULT true,
    require_approval BOOLEAN DEFAULT true,

    -- Estadísticas de gamificación
    total_xp INTEGER DEFAULT 0,
    total_ml_coins INTEGER DEFAULT 0,
    modules_completed INTEGER DEFAULT 0,
    achievements_earned INTEGER DEFAULT 0,

    -- Estado
    is_active BOOLEAN DEFAULT true,
    is_verified BOOLEAN DEFAULT false,
    founded_at TIMESTAMPTZ DEFAULT gamilit.now_mexico(),
    last_activity_at TIMESTAMPTZ,

    metadata JSONB DEFAULT '{}',
    created_at TIMESTAMPTZ DEFAULT gamilit.now_mexico(),
    updated_at TIMESTAMPTZ DEFAULT gamilit.now_mexico()
);

Características

• ✅ Personalización visual (colores, avatar, banner)
• ✅ Sistema de liderazgo
• ✅ Gamificación colaborativa (XP y coins compartidos)
• ✅ Control de privacidad y membresía
• ✅ Tracking de logros grupales

Casos de Uso

1. Formar Equipo: Estudiantes crean equipo de estudio
2. Unirse a Equipo: Mediante código o solicitud
3. Competir: Desafíos contra otros equipos
4. Colaborar: Completar módulos juntos
5. Ranking: Leaderboard de equipos

Gamificación de Equipos

XP del Equipo = Suma de XP individual de miembros
ML Coins del Equipo = Suma de coins de miembros
Módulos Completados = Módulos que TODOS completaron
Achievements = Logros grupales especiales

Relaciones

• classroom_id → classrooms.id (opcional - equipos pueden ser inter-aulas)
• creator_id → auth.users
• leader_id → auth.users

---

👤 TABLA: team_members

Archivo: apps/database/ddl/schemas/social_features/tables/06-team_members.sql

Propósito

Relación estudiante-equipo con roles y contribuciones.

Columnas Estimadas

CREATE TABLE social_features.team_members (
    id UUID PRIMARY KEY,
    team_id UUID NOT NULL,
    user_id UUID NOT NULL,

    -- Rol en el equipo
    role TEXT DEFAULT 'member',          -- 'member','leader','co-leader'

    -- Ingreso
    join_method TEXT,                    -- 'invite','code','request','founding'
    joined_at TIMESTAMPTZ DEFAULT gamilit.now_mexico(),
    invited_by UUID,

    -- Contribución
    xp_contributed INTEGER DEFAULT 0,
    ml_coins_contributed INTEGER DEFAULT 0,
    modules_completed_count INTEGER DEFAULT 0,

    -- Estado
    status TEXT DEFAULT 'active',        -- 'active','inactive','kicked','left'
    is_active BOOLEAN DEFAULT true,
    last_active_at TIMESTAMPTZ,

    metadata JSONB DEFAULT '{}',
    created_at TIMESTAMPTZ DEFAULT gamilit.now_mexico(),
    updated_at TIMESTAMPTZ DEFAULT gamilit.now_mexico(),

    UNIQUE(team_id, user_id)
);

Roles en Equipos

Rol	Permisos
founding	Fundador original (inmutable)
leader	Líder actual, puede invitar/expulsar
co-leader	Asistente del líder
member	Miembro regular

Contribuciones

• Se trackean contribuciones individuales al equipo
• Métricas de participación
• Identificar miembros más activos

---

🏆 TABLA: team_challenges

Archivo: apps/database/ddl/schemas/social_features/tables/07-team_challenges.sql

Propósito

Desafíos y competencias entre equipos.

Columnas Estimadas

CREATE TABLE social_features.team_challenges (
    id UUID PRIMARY KEY,

    -- Equipos participantes
    challenger_team_id UUID NOT NULL,    -- Equipo retador
    challenged_team_id UUID NOT NULL,    -- Equipo retado

    -- Desafío
    challenge_type TEXT,                 -- 'module_race','xp_battle','quiz_duel'
    challenge_name TEXT,
    description TEXT,
    rules JSONB DEFAULT '{}',

    -- Condiciones
    module_id UUID,                      -- Si es desafío de módulo específico
    target_score INTEGER,                -- Puntaje objetivo
    duration_minutes INTEGER,            -- Duración del desafío

    -- Estado
    status TEXT DEFAULT 'pending',       -- 'pending','accepted','in_progress','completed','cancelled'

    -- Resultado
    winner_team_id UUID,
    challenger_score INTEGER,
    challenged_score INTEGER,

    -- Premio
    reward_xp INTEGER,
    reward_ml_coins INTEGER,
    reward_badges JSONB DEFAULT '[]',

    -- Fechas
    challenged_at TIMESTAMPTZ DEFAULT gamilit.now_mexico(),
    accepted_at TIMESTAMPTZ,
    started_at TIMESTAMPTZ,
    completed_at TIMESTAMPTZ,

    metadata JSONB DEFAULT '{}',
    created_at TIMESTAMPTZ DEFAULT gamilit.now_mexico(),
    updated_at TIMESTAMPTZ DEFAULT gamilit.now_mexico()
);

Tipos de Desafíos

Tipo	Descripción
module_race	Carrera para completar módulo
xp_battle	Competencia de XP en tiempo límite
quiz_duel	Duelo de preguntas
achievement_hunt	Caza de logros específicos

Flujo de Desafío

1. Equipo A reta a Equipo B
2. Equipo B acepta o rechaza
3. Desafío inicia (in_progress)
4. Al terminar, se determina ganador
5. Se otorgan recompensas

---

🔧 FUNCIONES DEL SCHEMA

1. cleanup_old_notifications()

Archivo: apps/database/ddl/schemas/social_features/functions/cleanup_old_notifications.sql

Propósito: Limpia notificaciones antiguas (más de X días)

Firma:

CREATE OR REPLACE FUNCTION social_features.cleanup_old_notifications(days INTEGER DEFAULT 90)
RETURNS INTEGER

Uso:

-- Limpiar notificaciones de más de 90 días
SELECT social_features.cleanup_old_notifications(90);
-- Retorna: número de notificaciones eliminadas

---

📊 VISTAS Y MATERIALIZED VIEWS

Vistas Sugeridas (no implementadas aún)

1. team_leaderboard - Ranking de equipos por XP
2. classroom_social_graph - Grafo de relaciones en aula
3. friendship_stats - Estadísticas de amistades por usuario
4. active_challenges - Desafíos activos del momento

---

🔐 SEGURIDAD (RLS)

Archivo: apps/database/ddl/schemas/social_features/rls-policies/*.sql

Políticas Implementadas

1. schools: Solo directores y admins
2. classrooms: Maestros ven sus aulas, estudiantes ven aulas donde están
3. classroom_members: Ver solo miembros de aulas propias
4. friendships: Solo usuarios involucrados
5. teams: Miembros ven detalles completos, otros ven resumen público
6. team_members: Miembros del equipo
7. team_challenges: Equipos participantes y espectadores (si público)

---

📈 INTERDEPENDENCIAS

Schema Dependencies

social_features depende de:
├── auth_management (users, profiles, tenants)
├── gamification_system (achievements, user_stats)
└── educational_content (modules para team challenges)

social_features es usado por:
├── progress_tracking (analytics por classroom)
├── gamification_system (logros sociales)
└── admin_dashboard (vistas de escuelas/aulas)

---

🎯 CASOS DE USO COMPLETOS

Caso 1: Escuela se Registra

1. Super admin crea tenant
2. Director crea school
3. Director crea classrooms
4. Director invita maestros
5. Maestros invitan estudiantes a classrooms

Caso 2: Estudiantes Forman Equipo

1. Estudiante A crea team
2. Envía invitaciones a compañeros
3. Compañeros aceptan
4. Equipo participa en challenges
5. Ganan rewards grupales

Caso 3: Competencia entre Equipos

1. Team A reta a Team B
2. Team B acepta desafío
3. Ambos completan módulos
4. Sistema determina ganador
5. Rewards distribuidos

---

📝 DOCUMENTACIÓN RELACIONADA

Épicas que Usan social_features

Épica	Tablas Usadas	Funcionalidad
EAI-001	schools (indirecto)	Multi-tenancy
EXT-001	classrooms, classroom_members	Portal de Maestros
EXT-004	friendships, teams	Perfiles Sociales
(Pendiente)	teams, team_challenges	Gamificación Social

Referencias Cruzadas

• ✅ TRACEABILITY: docs/03-fase-extensiones/EXT-001-portal-maestros/implementacion/TRACEABILITY.yml
• ⚠️ PENDIENTE: RF para friendships, teams, team_challenges

---

🚀 PRÓXIMOS PASOS

Documentación Faltante

1. Crear RFs:

   • RF-SOC-001: Sistema de Amistades
   • RF-SOC-002: Equipos Colaborativos
   • RF-SOC-003: Desafíos entre Equipos
   • RF-SOC-004: Gestión de Escuelas

2. Crear TRACEABILITY:

   • Épica EXT-002 o EXT-003 para funcionalidades sociales
   • Mapear tablas faltantes

3. Backend:

   • Documentar servicios sociales
   • APIs de teams, friendships, challenges

4. Frontend:

   • Componentes de perfil social
   • UI de equipos
   • Pantalla de desafíos

---

🔍 ANÁLISIS DE COBERTURA

Componente	Implementado	Documentado	Gap
schools	✅	⚠️ Parcial	Falta RF
classrooms	✅	✅ EXT-001	Completo
classroom_members	✅	✅ EXT-001	Completo
friendships	✅	⚠️ Parcial	Falta RF/ET
teams	✅	⚠️ Parcial	Falta RF/ET
team_members	✅	⚠️ Parcial	Falta RF/ET
team_challenges	✅	⚠️ Parcial	Falta RF/ET

Cobertura actual: ~30% completo, ~70% parcial

---

Creado: 2025-11-08 Tipo: Documentación consolidada Total de tablas: 7 Estado: ✅ Documentación básica completa, ⚠️ Falta TRACEABILITY formal