workspace/projects/gamilit/docs/97-adr/ADR-0003-team-vs-guild.md

ADR: Team vs Guild Terminology

Estado: ✅ Aceptado Fecha: 2025-11-07 Contexto: Discrepancia P0-4 identificada durante validación Fase 1

---

Contexto

Durante la validación exhaustiva del código contra la documentación, se identificó una inconsistencia semántica:

• Documentación (/docs): Usa consistentemente los términos "Guild" y "GuildMember"
• Implementación (/src/modules/social): Usa los términos "Team" y "TeamMember"

Esta discrepancia afecta:

• Entidades de base de datos (teams, team_members)
• DTOs y tipos de TypeScript
• Comentarios y documentación inline
• Nomenclatura de APIs

---

Decisión

Se adopta el término "Team" como estándar oficial en lugar de "Guild".

---

Justificación

1. Claridad y Simplicidad

• "Team" es un término más universal y claro:

  • Familiar para usuarios no-gamers
  • Usado comúnmente en contextos educativos
  • Menos ambiguo que "Guild" (que tiene connotaciones de juegos MMORPG)

• "Guild" tiene connotaciones específicas:

  • Asociado principalmente con videojuegos (WoW, RPGs)
  • Puede confundir a educadores y administradores
  • Menos apropiado en contexto educativo formal

2. Alineación con Contexto Educativo

Gamilit es una plataforma educativa con gamificación, no un juego puro:

• Los educadores hablan de "equipos de estudio"
• Los administradores gestionan "grupos de trabajo"
• "Team" se integra mejor con terminología académica

3. Código Ya Implementado

La implementación actual usa "Team" en:

• 3 entidades TypeORM (Team, TeamMember, TeamInvite)
• Múltiples servicios y controllers
• Endpoints de API (/api/teams/*)
• Tablas de base de datos (social_features.teams)

Cambiar a "Guild" requeriría:

• Refactoring masivo de código
• Migración de base de datos
• Actualización de APIs (breaking changes)
• Re-testing completo

Costo estimado: 20+ horas de desarrollo Riesgo: Alto (posibles bugs en migración)

4. Compatibilidad Frontend

El frontend ya puede estar usando "teams" en:

• Componentes React
• Store/State management
• Llamadas a API
• Mensajes de UI

Cambiar el backend a "Guild" crearía mayor inconsistencia.

5. Internacionalización (i18n)

"Team" se traduce fácilmente a múltiples idiomas:

• Español: "Equipo"
• Inglés: "Team"
• Francés: "Équipe"

"Guild" es más difícil de traducir apropiadamente en contexto educativo.

---

Consecuencias

Positivas ✅

1. Terminología consistente en código implementado
2. Menor deuda técnica (no requiere refactoring)
3. Mejor UX para audiencia educativa
4. Facilita i18n con términos estándar
5. Reduce confusión entre developers

Negativas ❌

1. Requiere actualizar documentación (/docs) para usar "Team"
2. Posible confusión temporal si docs no se actualizan
3. Divergencia inicial con especificaciones originales

---

Plan de Acción

Inmediato (P0)

• Crear este ADR documentando la decisión
• Actualizar comentarios en entities para clarificar
• Crear issue para actualizar docs (/docs)

Corto Plazo (P1)

• Actualizar /docs/02-especificaciones-tecnicas/TYPES-SOCIAL.md
  • Reemplazar "Guild" → "Team"
  • Reemplazar "GuildMember" → "TeamMember"
• Actualizar /docs/02-especificaciones-tecnicas/SOCIAL-SCHEMAS.md
  • Actualizar esquemas de base de datos
  • Actualizar ejemplos de API
• Actualizar /docs/01-requerimientos/casos-uso/
  • Reemplazar referencias a "Guild" en user stories

Mediano Plazo (P2)

• Crear glosario de términos oficiales
• Agregar a style guide del proyecto
• Training para developers sobre terminología estándar

---

Mapping de Términos

Documentación (Old)	Código (Current)	Uso
Guild	Team	Entidad principal de equipo
GuildMember	TeamMember	Miembro de un equipo
GuildInvite	TeamInvite	Invitación a equipo
guild_id	team_id	ID de equipo
guildName	teamName	Nombre del equipo
guildRole	teamRole	Rol dentro del equipo

---

Ejemplos de Código

Entidad (Correcto)

/**
 * Team Entity
 *
 * Representa un equipo de colaboración/competencia entre estudiantes.
 * Los equipos pueden estar asociados a un classroom o ser independientes.
 *
 * @table social_features.teams
 * @note Anteriormente referenciado como "Guild" en documentación legacy
 */
@Entity({ schema: 'social_features', name: 'teams' })
export class Team {
  @Column('text')
  name: string;

  @Column('integer', { name: 'max_members', default: 5 })
  maxMembers: number;
}

API Endpoint (Correcto)

@Controller('api/teams')
export class TeamsController {
  @Post()
  async createTeam(@Body() dto: CreateTeamDto) {
    // ...
  }

  @Get(':teamId/members')
  async getTeamMembers(@Param('teamId') teamId: string) {
    // ...
  }
}

---

Referencias

• Issue: Discrepancia P0-4 - Reporte Final Fase 1
• Archivos Afectados:
  • /src/modules/social/entities/team.entity.ts
  • /src/modules/social/entities/team-member.entity.ts
  • /src/modules/social/services/teams.service.ts
  • /src/modules/social/controllers/teams.controller.ts
• Docs a Actualizar:
  • /docs/02-especificaciones-tecnicas/TYPES-SOCIAL.md
  • /docs/02-especificaciones-tecnicas/SOCIAL-SCHEMAS.md
  • /docs/01-requerimientos/casos-uso/student/

---

Revisiones

Fecha	Cambio	Autor
2025-11-07	Decisión inicial - Team sobre Guild	Claude Code (Sonnet 4.5)

---

Notas

• Este ADR debe ser revisado con el equipo de producto
• Si hay fuerte preferencia por "Guild" en UX research, se puede reconsiderar
• La decisión es reversible pero costosa (requiere migración completa)

---

Aprobado por: Backend Lead (pendiente) Revisión siguiente: Q1 2026 (post-launch user feedback)