rckrdmrd
ea1879f4ad
- Configure workspace Git repository with comprehensive .gitignore - Add Odoo as submodule for ERP reference code - Include documentation: SETUP.md, GIT-STRUCTURE.md - Add gitignore templates for projects (backend, frontend, database) - Structure supports independent repos per project/subproject level Workspace includes: - core/ - Reusable patterns, modules, orchestration system - projects/ - Active projects (erp-suite, gamilit, trading-platform, etc.) - knowledge-base/ - Reference code and patterns (includes Odoo submodule) - devtools/ - Development tools and templates - customers/ - Client implementations template 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
331 lines
11 KiB
Markdown
331 lines
11 KiB
Markdown
# ADR-017: Admin Portal Avanzado vs Alcance Inicial EAI-005
|
|
|
|
**Estado:** Aceptado
|
|
**Fecha:** 2025-11-24
|
|
**Autor:** Architecture-Analyst
|
|
**Relacionado con:** EAI-005, EXT-002, ARCH-ANALYSIS-ADMIN-001
|
|
|
|
---
|
|
|
|
## Contexto
|
|
|
|
Durante el análisis arquitectónico del Portal de Administración, se identificó una **discrepancia significativa** entre el alcance definido en la documentación inicial (EAI-005: Administración y Escalabilidad) y la implementación real del sistema.
|
|
|
|
### Alcance Documentado (EAI-005)
|
|
|
|
Según `docs/01-fase-alcance-inicial/EAI-005-admin-base/README.md`, el alcance inicial incluía:
|
|
|
|
**Módulos Incluidos (Alcance v1):**
|
|
- Gestión de Aulas Básica (CRUD)
|
|
- Gestión de Estudiantes en Aulas
|
|
- Asignación de Módulos
|
|
- Configuración Básica de Aulas
|
|
- Vista de Actividad de Aula
|
|
|
|
**Presupuesto:** $16,800 MXN
|
|
**Story Points:** 42 SP
|
|
**User Stories:** 6 historias (US-ADM-001 a US-ADM-007)
|
|
**Restricción Crítica:** En v1, las aulas NO tienen maestros asignados
|
|
|
|
### Implementación Real (Portal Admin Actual)
|
|
|
|
El Portal de Administración implementado incluye:
|
|
|
|
**Funcionalidades Implementadas:**
|
|
- Dashboard Ejecutivo con métricas del sistema (11 endpoints)
|
|
- Gestión Completa de Usuarios (13 endpoints, CRUD, suspender, bulk ops)
|
|
- Gestión Multi-Tenant/Organizaciones (5 endpoints)
|
|
- Aprobación de Contenido Educativo (9 endpoints)
|
|
- Configuración de Gamificación (8 endpoints - US-AE-005)
|
|
- Asignación Classroom-Teacher (2 endpoints - US-AE-007)
|
|
- Sistema de Reportes (4 endpoints)
|
|
- Roles y Permisos (4 endpoints)
|
|
- Monitoreo del Sistema (15 endpoints health/metrics/maintenance)
|
|
- Operaciones Masivas (5 endpoints)
|
|
|
|
**Implementación Real:**
|
|
- ~75 endpoints backend
|
|
- 13 páginas frontend (8 funcionales, 2 parciales, 3 en construcción)
|
|
- 33 DTOs
|
|
- 11 hooks custom
|
|
- 8 schemas de base de datos integrados
|
|
|
|
**Estimación de Esfuerzo Real:** ~250-300 SP (~$100,000 MXN)
|
|
|
|
### Problema Identificado
|
|
|
|
1. **Exceso de Alcance:** El Portal Admin implementado excede en **600%** el presupuesto de EAI-005
|
|
2. **Contradicción:** Implementa funcionalidades explícitamente excluidas (asignación de maestros)
|
|
3. **Confusión de Ubicación:** Las funcionalidades de EAI-005 se implementaron en el Portal de Maestros (/teacher/*), no en el Portal Admin (/admin/*)
|
|
4. **Fase Incorrecta:** Implementa funcionalidades de Fase 2-3, no de Fase 1
|
|
|
|
---
|
|
|
|
## Decisión
|
|
|
|
### Decisión Principal
|
|
|
|
**MANTENER la implementación actual del Portal Admin** como un sistema avanzado de Fase 2-3, reconociendo que excede significativamente el alcance inicial.
|
|
|
|
### Decisiones Secundarias
|
|
|
|
1. **Actualizar Documentación de Alcances**
|
|
- Mantener EAI-005 como referencia histórica del alcance inicial
|
|
- Crear nuevo documento EXT-002-ADMIN-PORTAL-AVANZADO.md
|
|
- Clarificar que el Admin Portal actual corresponde a Fase 2-3
|
|
|
|
2. **Mantener Separación de Portales**
|
|
- `/admin/*` - Portal Super Admin (gestión global, multi-tenant)
|
|
- `/teacher/*` - Portal Maestros (gestión de aulas, estudiantes)
|
|
- `/student/*` - Portal Estudiantes (aprendizaje)
|
|
|
|
3. **Documentar Funcionalidades en Construcción**
|
|
- Mantener componente `UnderConstruction` para features en desarrollo
|
|
- Clarificar en cada página qué está disponible vs qué viene próximamente
|
|
- Agregar fechas estimadas cuando sea posible
|
|
|
|
4. **No Retroceder Implementación**
|
|
- El código actual está bien estructurado y funcional
|
|
- Los objetos de BD están correctamente diseñados
|
|
- La arquitectura es escalable y sigue best practices
|
|
- Retroceder sería desperdiciar ~$80K en desarrollo
|
|
|
|
---
|
|
|
|
## Consecuencias
|
|
|
|
### Positivas
|
|
|
|
1. **Sistema Robusto Desde el Inicio**
|
|
- Portal Admin completo y profesional
|
|
- Infraestructura preparada para escalar
|
|
- Mejor experiencia de usuario para super admins
|
|
|
|
2. **Separación Clara de Responsabilidades**
|
|
- Tres portales bien diferenciados (admin/teacher/student)
|
|
- Cada portal con su propósito específico
|
|
- Reducción de acoplamiento entre módulos
|
|
|
|
3. **Preparado para Multi-Tenancy**
|
|
- Gestión de organizaciones desde el inicio
|
|
- Feature flags por tenant
|
|
- Configuración global vs por organización
|
|
|
|
4. **Herramientas Avanzadas de Monitoreo**
|
|
- Dashboard con métricas en tiempo real
|
|
- Sistema de alertas
|
|
- Logs y auditoría completos
|
|
|
|
### Negativas
|
|
|
|
1. **Exceso de Presupuesto**
|
|
- $100K invertidos vs $16.8K presupuestados
|
|
- Funcionalidades de Fase 2-3 adelantadas sin planificación
|
|
|
|
2. **Confusión en Documentación**
|
|
- Alcance documentado vs alcance real no coinciden
|
|
- User Stories de EAI-005 implementadas en otro portal
|
|
- Necesidad de actualizar múltiples documentos
|
|
|
|
3. **Páginas "En Construcción"**
|
|
- 3 páginas parcialmente implementadas pueden confundir
|
|
- Expectativas de usuario pueden no alinearse con disponibilidad
|
|
- Necesidad de comunicación clara sobre roadmap
|
|
|
|
4. **Complejidad Arquitectónica**
|
|
- Sistema más complejo de mantener que el alcance inicial
|
|
- Más objetos de BD, endpoints, y lógica de negocio
|
|
- Mayor superficie de ataque para bugs
|
|
|
|
### Mitigaciones
|
|
|
|
Para mitigar las consecuencias negativas:
|
|
|
|
1. **Actualizar Documentación Completa**
|
|
- Crear EXT-002-ADMIN-PORTAL-AVANZADO.md con alcance real
|
|
- Actualizar roadmap reflejando fases reales
|
|
- Clarificar en EAI-005 que funcionalidades están en Portal Maestros
|
|
|
|
2. **Mejorar Componentes "En Construcción"**
|
|
- Mensajes claros sobre qué está disponible
|
|
- Fechas estimadas de features próximas
|
|
- Links a documentación de roadmap
|
|
|
|
3. **Tests y Validación**
|
|
- Suite de tests E2E para Admin Portal
|
|
- Tests de integración entre portales
|
|
- Validación manual de flujos críticos
|
|
|
|
4. **Monitoreo de Presupuesto Futuro**
|
|
- Tracking más riguroso de story points vs implementación
|
|
- Revisión de alcances antes de implementar
|
|
- Aprobación de stakeholders para features out-of-scope
|
|
|
|
---
|
|
|
|
## Alternativas Consideradas
|
|
|
|
### Alternativa 1: Retroceder a Alcance EAI-005
|
|
|
|
**Descripción:** Eliminar funcionalidades fuera de alcance, dejar solo gestión básica de aulas.
|
|
|
|
**Pros:**
|
|
- Alineación con documentación
|
|
- Reducción de complejidad
|
|
- Cumplimiento de presupuesto
|
|
|
|
**Cons:**
|
|
- ❌ Pérdida de $80K en desarrollo
|
|
- ❌ Sistema menos funcional
|
|
- ❌ Necesidad de re-implementar en Fase 2-3
|
|
- ❌ Experiencia de usuario degradada
|
|
|
|
**Veredicto:** Rechazada (desperdicio de inversión)
|
|
|
|
---
|
|
|
|
### Alternativa 2: Mantener "As-Is" Sin Actualizar Documentación
|
|
|
|
**Descripción:** Dejar el código actual sin cambios y sin actualizar documentación.
|
|
|
|
**Pros:**
|
|
- Sin esfuerzo adicional
|
|
- Código funcional se mantiene
|
|
|
|
**Cons:**
|
|
- ❌ Confusión permanente sobre alcances
|
|
- ❌ Nuevos desarrolladores no entenderán decisiones
|
|
- ❌ Futuras decisiones de arquitectura sin contexto
|
|
- ❌ Auditorías identificarán discrepancias
|
|
|
|
**Veredicto:** Rechazada (deuda técnica documental)
|
|
|
|
---
|
|
|
|
### Alternativa 3: Mantener y Documentar (SELECCIONADA)
|
|
|
|
**Descripción:** Mantener código actual, actualizar documentación para reflejar realidad.
|
|
|
|
**Pros:**
|
|
- ✅ Conserva inversión en desarrollo
|
|
- ✅ Clarifica decisiones arquitectónicas
|
|
- ✅ Base para futuras decisiones
|
|
- ✅ Facilita onboarding de nuevos desarrolladores
|
|
|
|
**Cons:**
|
|
- Requiere esfuerzo en documentación (~8 horas)
|
|
- Necesidad de comunicar a stakeholders
|
|
|
|
**Veredicto:** Aceptada (balance óptimo)
|
|
|
|
---
|
|
|
|
## Referencias
|
|
|
|
### Documentos Relacionados
|
|
|
|
- **Análisis Completo:** `orchestration/agentes/architecture-analyst/analisis-portal-admin-alcances-2025-11-24/REPORTE-ANALISIS-PORTAL-ADMIN-ALCANCES.md`
|
|
- **Alcance Original:** `docs/01-fase-alcance-inicial/EAI-005-admin-base/README.md`
|
|
- **Estado Actual:** `docs/90-transversal/ADMIN-PORTAL-UNDER-CONSTRUCTION-2025-11-24.md`
|
|
- **Inventario Admin:** `docs/90-transversal/inventarios/INVENTARIO-ADMIN-PORTAL-EXT-002.md`
|
|
- **User Stories:**
|
|
- `US-ADM-001-gestion-aulas-crud.md`
|
|
- `US-ADM-002-gestion-estudiantes-aula.md`
|
|
- `US-ADM-004-asignacion-modulos.md`
|
|
|
|
### ADRs Relacionados
|
|
|
|
- ADR-015: Centralized API Routes Configuration
|
|
- ADR-016: Simplificar Backend XP Acumulación
|
|
|
|
### User Stories Relacionadas
|
|
|
|
- US-AE-005: Configuración de Gamificación (implementada en Admin Portal)
|
|
- US-AE-007: Asignaciones Classroom-Teacher (implementada en Admin Portal)
|
|
|
|
---
|
|
|
|
## Impacto
|
|
|
|
### Equipos Afectados
|
|
|
|
| Equipo | Impacto | Acción Requerida |
|
|
|--------|---------|------------------|
|
|
| **Frontend Team** | Bajo | Revisar mensajes UnderConstruction |
|
|
| **Backend Team** | Bajo | Completar endpoints pendientes si aprobado |
|
|
| **QA Team** | Medio | Tests E2E para Admin Portal |
|
|
| **Product Team** | Alto | Revisar roadmap y prioridades |
|
|
| **Documentation Team** | Alto | Actualizar documentación de alcances |
|
|
|
|
### Cronograma de Implementación
|
|
|
|
```
|
|
INMEDIATO (Hoy - 2025-11-24):
|
|
├─ Crear este ADR (COMPLETADO)
|
|
├─ Actualizar README de EAI-005
|
|
└─ Validar mensajes UnderConstruction
|
|
|
|
ESTA SEMANA (2025-11-25 a 2025-11-29):
|
|
├─ Crear documento EXT-002-ADMIN-PORTAL-AVANZADO.md
|
|
├─ Actualizar roadmap del proyecto
|
|
└─ Presentar análisis a stakeholders
|
|
|
|
PRÓXIMO SPRINT:
|
|
├─ Tests E2E para Admin Portal
|
|
├─ Completar features pendientes (si aprobado)
|
|
└─ Validación manual de flujos críticos
|
|
```
|
|
|
|
---
|
|
|
|
## Lecciones Aprendidas
|
|
|
|
### Para Futuros Desarrollos
|
|
|
|
1. **Validar Alcance Antes de Implementar**
|
|
- Revisar documentación de US antes de codificar
|
|
- Confirmar presupuesto vs esfuerzo estimado
|
|
- Obtener aprobación para features out-of-scope
|
|
|
|
2. **Documentar Decisiones en Tiempo Real**
|
|
- Crear ADRs cuando se desvía del alcance original
|
|
- Actualizar roadmap conforme avanza implementación
|
|
- Comunicar cambios a stakeholders inmediatamente
|
|
|
|
3. **Separar Alcance Inicial de Extensiones**
|
|
- Implementar MVP estricto en Fase 1
|
|
- Dejar features avanzadas explícitamente para Fase 2-3
|
|
- Usar feature flags para habilitar/deshabilitar features
|
|
|
|
4. **Tracking de Presupuesto**
|
|
- Monitorear story points vs trabajo real
|
|
- Alertar cuando se excede presupuesto en 20%+
|
|
- Revisar alcances mensualmente
|
|
|
|
---
|
|
|
|
## Conclusión
|
|
|
|
La decisión de **mantener el Portal Admin actual** como un sistema avanzado es la correcta desde una perspectiva técnica y de inversión. El código está bien estructurado, sigue best practices, y proporciona valor real a los usuarios.
|
|
|
|
Sin embargo, la **falta de alineación con la documentación de alcances** es un problema que debe resolverse mediante actualización de documentos, no mediante eliminación de código.
|
|
|
|
Esta decisión sienta precedente para futuros desarrollos: **documentar siempre las desviaciones de alcance mediante ADRs** y **comunicar proactivamente los cambios arquitectónicos**.
|
|
|
|
---
|
|
|
|
**Estado:** Aceptado
|
|
**Próxima Revisión:** 2025-12-31 (post-implementación de correcciones)
|
|
**Responsable de Seguimiento:** Architecture-Analyst
|
|
**Aprobadores:** [Pendiente de aprobación de stakeholders]
|
|
|
|
---
|
|
|
|
**Firma Digital:**
|
|
```
|
|
SHA-256: adr-017-admin-portal-avanzado-vs-alcance-inicial
|
|
Fecha: 2025-11-24
|
|
Analista: Architecture-Analyst
|
|
Estado: Aceptado (Pendiente aprobación stakeholders)
|
|
```
|