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>
223 lines
5.8 KiB
Markdown
223 lines
5.8 KiB
Markdown
# 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)
|
|
|
|
- [x] Crear este ADR documentando la decisión
|
|
- [x] 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)
|
|
|
|
```typescript
|
|
/**
|
|
* 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)
|
|
|
|
```typescript
|
|
@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)
|