Adrian Flores Cortes 967ab360bb Initial commit: Workspace v1 with 3-layer architecture

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>

2025-12-23 00:35:19 -06:00

19 KiB

Raw Blame History

US-PERF-004: Interacciones Sociales

Información Básica

Campo	Valor
ID	US-PERF-004
Épica	EXT-004 - Perfiles Avanzados
Título	Sistema de Interacciones Sociales y Gestión de Amigos
Prioridad	Alta (P1)
Story Points	8 SP
Estado	NOT STARTED
Fase	Mes 3 (Extensiones Primera Ola)
Presupuesto	$4,000 MXN

Historia de Usuario

Como estudiante de la plataforma Gamilit Quiero gestionar amigos, enviar mensajes directos y configurar mi visibilidad social Para conectar con otros estudiantes, compartir logros y crear una comunidad de aprendizaje

Valor de Negocio

Impacto

Engagement: Conexiones sociales aumentan permanencia 45%
Retention: Usuarios con >3 amigos tienen 60% menos churn
Colaboración: Facilita aprendizaje entre pares
Community Building: Crea sentido de pertenencia

Métricas de Éxito

70% usuarios agregan al menos 3 amigos en primer mes
50% envían mensajes regularmente (1+ por semana)
<2% incidentes de comportamiento inapropiado reportados
Satisfacción social >4.2/5 en encuestas

Criterios de Aceptación

CA-01: Búsqueda y Descubrimiento de Usuarios

Dado que un estudiante quiere encontrar amigos Cuando utiliza la función de búsqueda Entonces debe poder:

Buscar usuarios por nombre de usuario o nombre completo
Filtrar por grado académico, intereses comunes
Ver sugerencias de "Personas que quizás conozcas" basado en:
- Compañeros de clase/aula
- Amigos en común
- Intereses similares
Ver perfil público del usuario antes de enviar solicitud
Respetar configuraciones de privacidad (usuarios privados no aparecen)

CA-02: Gestión de Solicitudes de Amistad

Dado que un usuario gestiona relaciones sociales Cuando envía o recibe solicitudes Entonces debe poder:

Enviar solicitud de amistad con mensaje opcional (hasta 200 caracteres)
Ver solicitudes pendientes enviadas (con opción de cancelar)
Ver solicitudes recibidas con:
- Información del remitente (avatar, nombre, grado)
- Mensaje personalizado si lo hay
- Amigos en común
- Botones: Aceptar / Rechazar / Bloquear
Recibir notificación in-app cuando recibe solicitud
Límite de 50 solicitudes pendientes enviadas simultáneamente
Cooldown de 24h si rechaza 10+ solicitudes del mismo usuario

CA-03: Lista de Amigos

Dado que el usuario visualiza sus amigos Cuando accede a lista de amigos Entonces debe ver:

Grid/Lista de amigos con:
- Avatar, nombre de usuario, nombre real
- Estado: Online (verde) / Idle (amarillo) / Offline (gris)
- Última actividad ("Hace 5 min", "Hace 2 días")
- Nivel actual y badge principal
Ordenar por: Estado / Nombre / Nivel / Fecha de amistad
Búsqueda de amigos en la lista
Contador total: "145 amigos"
Acciones por amigo:
- Ver perfil completo
- Enviar mensaje
- Eliminar amigo (con confirmación)
- Bloquear usuario
Categorías opcionales: "Mejores amigos", "Compañeros de clase", "Personalizado"

CA-04: Mensajes Directos (DM)

Dado que dos usuarios son amigos Cuando utilizan mensajería directa Entonces pueden:

Enviar mensajes de texto (hasta 2000 caracteres)
Ver conversaciones en formato chat (burbujas)
Ver indicadores:
- "Escribiendo..." cuando el otro escribe
- "Visto" cuando mensaje se lee
- Timestamp de cada mensaje
Enviar emojis básicos y stickers de Gamilit
Compartir logros directamente (vista enriquecida)
Compartir enlaces a mecánicas o módulos
Eliminar mensaje propio (antes de 5 min)
Reportar mensaje inapropiado
Límite de 100 mensajes/día por usuario (anti-spam)
Historial de mensajes: últimos 30 días (después archivado)

CA-05: Notificaciones de Mensajería

Dado que un usuario recibe comunicaciones Cuando ocurren eventos sociales Entonces debe recibir:

Solicitud de amistad recibida: Notificación in-app + email (opcional)
Solicitud aceptada: "Juan Pérez aceptó tu solicitud"
Mensaje nuevo: Badge de contador en ícono de mensajes
Amigo online: Notificación sutil si está en favoritos
Configuración granular en preferencias (ver US-PERF-001)
Modo "No Molestar" desactiva notificaciones temporalmente
Resumen diario: "Tienes 3 mensajes nuevos y 2 solicitudes"

Dado que el usuario configura privacidad social Cuando ajusta opciones de visibilidad Entonces puede definir:

Perfil visible para: Todos / Solo Amigos / Nadie
Permitir solicitudes de: Todos / Compañeros de clase / Nadie
Mostrar estado online: Sí / Solo Amigos / No
Permitir mensajes de: Todos los amigos / Solo favoritos / Nadie
Aparecer en búsquedas: Sí / No
Mostrar lista de amigos: Sí / Solo Amigos / No
Preview en tiempo real de cómo se ve perfil según config
Modo "Invisible": aparece offline para todos

CA-07: Bloqueo de Usuarios

Dado que un usuario necesita bloquear a alguien Cuando bloquea a otro usuario Entonces el sistema debe:

Eliminar amistad existente automáticamente
Prevenir que el bloqueado:
- Vea su perfil
- Envíe solicitudes de amistad
- Envíe mensajes
- Vea actividad en leaderboards
No notificar al bloqueado (bloqueo invisible)
Permitir al bloqueador:
- Ver lista de usuarios bloqueados
- Desbloquear en cualquier momento
Límite de 100 usuarios bloqueados por cuenta
Audit log de bloqueos en backend

CA-08: Reporte de Comportamiento Inapropiado

Dado que un usuario observa conducta inapropiada Cuando reporta a otro usuario o mensaje Entonces debe poder:

Seleccionar tipo de reporte:
- Spam
- Acoso o bullying
- Contenido inapropiado
- Suplantación de identidad
- Otro (especificar)
Agregar descripción (opcional, hasta 500 caracteres)
Adjuntar screenshot (opcional)
Enviar reporte anónimo (el reportado no ve quién reportó)
Recibir confirmación: "Reporte enviado. Lo revisaremos en 48h"
Sistema debe:
- Notificar a moderadores
- Marcar usuario con múltiples reportes (>3)
- Suspender automáticamente si >10 reportes en 24h
- Guardar evidencia para revisión

Dado que el usuario ve actividad de amigos Cuando accede a feed social Entonces puede ver:

Timeline de actividades de amigos (si su privacidad lo permite):
- "Ana completó Módulo 2 con 95% de acierto"
- "Carlos desbloqueó el logro 'Maestro del Cacao'"
- "Luis alcanzó nivel 15"
Reacciones simples: Like, Celebrar, Wow (tipo LinkedIn)
Comentarios básicos (hasta 300 caracteres)
Filtros: Todos / Solo mejores amigos / Por actividad
Opción "Ocultar esta publicación"
Configurar qué actividades propias se comparten (en privacidad)

CA-10: Estadísticas Sociales

Dado que el usuario accede a métricas sociales Cuando visualiza su actividad social Entonces debe ver:

Total de amigos / solicitudes pendientes
Mensajes enviados/recibidos esta semana
Logros compartidos este mes
Reacciones recibidas en publicaciones
Gráfico de crecimiento de amigos (últimos 6 meses)
"Amigo más activo" (con quien más interactúa)
Comparativa de red social (vs promedio de plataforma)

CA-11: Responsive y Accesibilidad

Dado que el usuario accede desde cualquier dispositivo Cuando utiliza features sociales Entonces debe:

Funcionar en 320px - 2560px
Chat optimizado para mobile (teclado no oculta mensajes)
Notificaciones nativas en mobile (Push)
Navegación por teclado en desktop
ARIA labels en listas de amigos y mensajes
Screen reader anuncia mensajes nuevos
Alto contraste en burbujas de chat
Touch targets 44x44px mínimo

CA-12: Seguridad y Validación

Dado que la mensajería puede ser vector de abuso Cuando usuarios interactúan Entonces el sistema debe:

Sanitizar todos los mensajes (prevenir XSS)
Filtro de palabras inapropiadas (configurable)
Detección automática de:
- Spam (mensajes repetidos)
- Enlaces sospechosos (phishing)
- Patrones de acoso
Rate limiting: 100 mensajes/día, 10 solicitudes/hora
Encriptación end-to-end en mensajes (opcional en roadmap)
Retención de datos: mensajes >30 días archivados
GDPR compliance: derecho al olvido (eliminar historial)
Audit trail de todas las interacciones sociales

CA-13: Integración con Sistema de Gamificación

Dado que las interacciones sociales otorgan recompensas Cuando el usuario completa acciones sociales Entonces debe ganar:

Primera amistad: 50 Cacao, Badge "Social Butterfly"
10 amigos: 100 Cacao, Badge "Popular"
50 mensajes enviados: Badge "Comunicativo"
100 amigos: Badge "Networker Experto"
Quests sociales: "Agrega 5 amigos esta semana" (200 Cacao)
Bonus XP por ayudar amigos (compartir recursos)

CA-14: Moderación de Contenido

Dado que se necesita mantener ambiente sano Cuando moderadores revisan reportes Entonces deben poder:

Ver dashboard de reportes pendientes
Revisar evidencia (mensajes, perfiles)
Acciones disponibles:
- Advertir al usuario (warning)
- Suspender mensajería (1 día, 7 días, 30 días)
- Suspender cuenta temporal
- Ban permanente
Comunicar decisión al reportante y reportado
Apelar decisiones (proceso de revisión)
Estadísticas de moderación (tiempo de respuesta, % casos resueltos)

CA-15: Performance y Escalabilidad

Dado que el sistema debe soportar miles de usuarios Cuando operan features sociales Entonces debe:

Mensajes entregados en <200ms (p95)
Estado online actualizado cada 30 segundos
Notificaciones push en <1 segundo
Lista de amigos carga en <500ms (hasta 500 amigos)
Búsqueda de usuarios responde en <300ms
WebSockets para chat en tiempo real
Caché de estados online (Redis)
Índices en tablas de relaciones (user_friends, messages)

Especificaciones Técnicas

Frontend Components

src/features/social/
├── pages/
│   ├── FriendsPage.tsx
│   ├── MessagesPage.tsx
│   └── DiscoverPage.tsx
├── components/
│   ├── FriendsList.tsx
│   ├── FriendCard.tsx
│   ├── FriendRequestCard.tsx
│   ├── ChatWindow.tsx
│   ├── MessageBubble.tsx
│   ├── UserSearchBar.tsx
│   ├── OnlineStatus.tsx
│   ├── BlockUserModal.tsx
│   ├── ReportModal.tsx
│   └── SocialTimeline.tsx
├── hooks/
│   ├── useFriends.ts
│   ├── useMessages.ts
│   ├── useWebSocket.ts
│   └── useOnlineStatus.ts
└── contexts/
    └── ChatContext.tsx

TypeScript Interfaces

interface Friendship {
  id: string;
  userId1: string;
  userId2: string;
  status: 'pending' | 'accepted' | 'rejected';
  initiatorId: string;
  requestMessage?: string;
  createdAt: Date;
  acceptedAt?: Date;
}

interface DirectMessage {
  id: string;
  conversationId: string;
  senderId: string;
  recipientId: string;
  content: string;
  type: 'text' | 'achievement' | 'link' | 'sticker';
  metadata?: any;
  status: 'sent' | 'delivered' | 'read';
  createdAt: Date;
  readAt?: Date;
  deletedAt?: Date;
}

interface UserBlock {
  id: string;
  blockerId: string;
  blockedId: string;
  reason?: string;
  createdAt: Date;
}

interface Report {
  id: string;
  reporterId: string;
  reportedId: string;
  targetType: 'user' | 'message';
  targetId: string;
  category: 'spam' | 'harassment' | 'inappropriate' | 'impersonation' | 'other';
  description?: string;
  screenshot?: string;
  status: 'pending' | 'reviewing' | 'resolved' | 'dismissed';
  resolution?: string;
  resolvedBy?: string;
  resolvedAt?: Date;
  createdAt: Date;
}

interface OnlineStatus {
  userId: string;
  status: 'online' | 'idle' | 'offline';
  lastSeen: Date;
  currentActivity?: string;
}

API Endpoints

// Friends
GET    /api/social/friends
POST   /api/social/friends/request
PUT    /api/social/friends/:id/accept
DELETE /api/social/friends/:id
GET    /api/social/friends/suggestions

// Messages
GET    /api/social/messages/conversations
GET    /api/social/messages/:conversationId
POST   /api/social/messages
PUT    /api/social/messages/:id/read
DELETE /api/social/messages/:id

// Blocking
POST   /api/social/block
DELETE /api/social/block/:userId
GET    /api/social/blocked

// Reporting
POST   /api/social/report
GET    /api/social/reports (admin only)
PUT    /api/social/reports/:id/resolve (admin only)

// Online Status
GET    /api/social/status/:userId
WS     /ws/social/status

Database Schema

-- Friendships table
CREATE TABLE friendships (
  id UUID PRIMARY KEY,
  user_id_1 UUID REFERENCES users(id),
  user_id_2 UUID REFERENCES users(id),
  status VARCHAR(20),
  initiator_id UUID,
  request_message TEXT,
  created_at TIMESTAMP,
  accepted_at TIMESTAMP,
  CONSTRAINT unique_friendship UNIQUE (user_id_1, user_id_2)
);
CREATE INDEX idx_friendships_user1 ON friendships(user_id_1);
CREATE INDEX idx_friendships_user2 ON friendships(user_id_2);
CREATE INDEX idx_friendships_status ON friendships(status);

-- Messages table
CREATE TABLE direct_messages (
  id UUID PRIMARY KEY,
  conversation_id UUID,
  sender_id UUID REFERENCES users(id),
  recipient_id UUID REFERENCES users(id),
  content TEXT,
  type VARCHAR(20),
  metadata JSONB,
  status VARCHAR(20),
  created_at TIMESTAMP,
  read_at TIMESTAMP,
  deleted_at TIMESTAMP
);
CREATE INDEX idx_messages_conversation ON direct_messages(conversation_id);
CREATE INDEX idx_messages_recipient ON direct_messages(recipient_id, status);

-- Blocks table
CREATE TABLE user_blocks (
  id UUID PRIMARY KEY,
  blocker_id UUID REFERENCES users(id),
  blocked_id UUID REFERENCES users(id),
  reason TEXT,
  created_at TIMESTAMP,
  CONSTRAINT unique_block UNIQUE (blocker_id, blocked_id)
);
CREATE INDEX idx_blocks_blocker ON user_blocks(blocker_id);

-- Reports table
CREATE TABLE reports (
  id UUID PRIMARY KEY,
  reporter_id UUID REFERENCES users(id),
  reported_id UUID REFERENCES users(id),
  target_type VARCHAR(20),
  target_id UUID,
  category VARCHAR(50),
  description TEXT,
  screenshot TEXT,
  status VARCHAR(20),
  resolution TEXT,
  resolved_by UUID,
  resolved_at TIMESTAMP,
  created_at TIMESTAMP
);
CREATE INDEX idx_reports_status ON reports(status);
CREATE INDEX idx_reports_reported ON reports(reported_id);

Diferenciación con Alcance Inicial (EAI)

Alcance Inicial (EAI)

EP008: Features sociales básicas planeadas pero NO implementadas

Esta Historia (EXT-004)

Sistema completo de amigos: búsqueda, solicitudes, gestión
Mensajería directa: chat en tiempo real con WebSockets
Configuración de privacidad: granular y flexible
Moderación: bloqueo, reportes, sistema anti-abuso
Gamificación social: logros por interacciones
Timeline social: actividad de amigos
Esto es extensión completa del aspecto social

Dependencias

Depende de

EAI-001: Sistema de usuarios y autenticación
US-PERF-001: Sistema de perfiles (necesita info de usuarios)
EAI-003: Sistema de logros (para compartir achievements)

Bloquea a

EXT-007: Portal de Comunidad (usa este sistema como base)

Definición de Terminado (DoD)

UI de búsqueda y descubrimiento de usuarios
Sistema de solicitudes de amistad (enviar, aceptar, rechazar)
Lista de amigos con estado online/offline
Chat en tiempo real con WebSockets
Notificaciones de mensajes y solicitudes
Configuración de privacidad social
Sistema de bloqueo de usuarios
Sistema de reportes y moderación
Timeline de actividad social
Estadísticas sociales
API endpoints implementados
WebSocket server configurado
Base de datos con índices optimizados
Rate limiting y anti-spam
Filtro de contenido inapropiado
Tests unitarios >80% coverage
Tests de integración para flujos sociales
Tests de carga (1000+ usuarios concurrentes)
Responsive design completo
Accesibilidad WCAG 2.1 AA
Documentación de API
Guía de moderación

Riesgos y Mitigaciones

Riesgo	Probabilidad	Impacto	Mitigación
Spam y abuso	Alta	Alto	Rate limiting, filtros, moderación activa
Escalabilidad de WebSockets	Media	Alto	Load balancer, Redis pub/sub, scaling horizontal
Contenido inapropiado	Media	Alto	Filtros automáticos, reportes, moderación 24/7
Privacy concerns	Media	Medio	Config granular, GDPR compliance, audit logs

Estimación Detallada (8 SP)

Tarea	Horas	Responsable
Diseño UI/UX social	8h	UX Designer
Sistema de amigos	10h	Frontend Dev
Chat UI y WebSockets	12h	Frontend Dev
Búsqueda y descubrimiento	6h	Frontend Dev
Notificaciones	6h	Frontend Dev
API de amigos	8h	Backend Dev
API de mensajería	10h	Backend Dev
WebSocket server	8h	Backend Dev
Sistema de bloqueo/reportes	8h	Backend Dev
Moderación dashboard	6h	Backend Dev
Testing	12h	QA + Devs
Documentación	4h	Tech Lead
TOTAL	98h

Presupuesto: $4,000 MXN (~$230 USD) Duración Estimada: 2-3 días (equipo de 5-6 personas)

Tareas de Implementación

Backend (14.4h - 45%)

Diseñar schema de tablas friendships, direct_messages, user_blocks, reports (2h)
Implementar API de gestión de amigos (solicitudes, aceptar, rechazar) (3h)
Desarrollar API de mensajería con WebSockets (3h)
Crear sistema de bloqueo y reportes de usuarios (2h)
Implementar moderación dashboard para admins (1.5h)
Desarrollar rate limiting y anti-spam (1.5h)
Configurar índices en BD para performance (1.4h)

Frontend (11.2h - 35%)

Crear FriendsPage con lista de amigos y búsqueda (2h)
Implementar MessagesPage con chat en tiempo real (3h)
Desarrollar sistema de solicitudes de amistad (1.5h)
Crear componentes de bloqueo y reporte de usuarios (1.5h)
Implementar notificaciones de mensajes y solicitudes (1.5h)
Desarrollar timeline de actividad social (1.5h)
Configurar WebSocket client para chat (0.2h)

Testing y QA (4.8h - 15%)

Escribir tests unitarios para sistema social (2h)
Crear tests de integración para flujos sociales (1.5h)
Realizar tests de carga con 1000+ usuarios concurrentes (1h)
Validar filtro de contenido inapropiado (0.3h)

Deploy y Documentación (1.6h - 5%)

Configurar WebSocket server en producción (0.5h)
Documentar API de sistema social (0.6h)
Crear guía de moderación para administradores (0.5h)

Total Estimado: 32h

Cronograma

Fase	Fecha Inicio Planificada	Fecha Fin Estimada	Horas	Estado
Backend	28 Oct 2024	29 Oct 2024	14.4h	Planificado
Frontend	29 Oct 2024	31 Oct 2024	11.2h	Planificado
Testing	31 Oct 2024	01 Nov 2024	4.8h	Planificado
Deploy	01 Nov 2024	01 Nov 2024	1.6h	Planificado

19 KiB Raw Blame History