Files
admin-edu-space/docs/entregables/MINUTAS_Y_EVIDENCIAS_GESTION_AGIL.md
T

14 KiB

Evidencias de Gestión Ágil, Minutas de Diseño y Metodología SDD

Asignatura: Programación de Vanguardia — Ciclo Lectivo 2026 (2° Cuatrimestre)

Cátedra: Ing. Alejandro Vázquez — Alumno: Carlos Facundo Tello

Proyecto: Admin Edu-Space (Plataforma Inteligente de Asignación Áulica, Asistencia IA y Control de Accesos)
Metodología de Desarrollo: Spec-Driven Development (SDD) & Desarrollo Ágil Basado en Pruebas (TDD)


1. Modelo de Gestión y Flujo de Ramas en Git

El desarrollo del proyecto se ejecutó bajo una disciplina estricta de control de versiones fundamentada en SemVer (Semantic Versioning 2.0.0) y un flujo de ramas continuo:

  • Rama main: Rama protegida de despliegue estable institucional.
  • Rama dev: Rama activa de integración continua, consolidación de sprints y ejecución de auditorías automatizadas de seguridad.
  • Trazabilidad de Commits: Commits semánticos estandarizados (feat:, fix:, refactor:, docs:, test:, chore:), registrando en cada iteración la especificación asociada, las pruebas superadas y el bump de versión.
gitGraph
    commit id: "v1.0.0 (Monolito Inicial)"
    commit id: "v2.0.0 (Desacople REST API)"
    branch dev
    checkout dev
    commit id: "v3.0.0 (Matriz de Conflictos)"
    commit id: "v3.5.0 (Cierre MVP Bedelía SDD-001)"
    commit id: "v3.6.0 (Migración FastAPI SDD-003)"
    commit id: "v3.8.0 (Erradicación Flask SDD-004)"
    commit id: "v3.8.25 (IA Local RAG UdeCi SDD-009/010)"
    commit id: "v3.8.27 (Servidor MCP Institucional SDD-011)"
    commit id: "v3.8.39 (Beneficios & Credencial QR SDD-012)"
    commit id: "v3.8.52 (Web Serial Multi-COM & DNI SDD-013)"
    commit id: "v3.8.56 (Consolidación al 04/11/2026)"
    checkout main
    merge dev id: "v3.8.56 (Producción LXC Estable)"

2. Metodología SDD (Spec-Driven Development) y Sintaxis EARS

Para garantizar que el software responda exactamente a las necesidades de la comunidad universitaria y evitar desvíos (scope creep), ninguna funcionalidad se programó sin contar previamente con su especificación formal.

Cada hito cuenta con su carpeta dedicada en specs/ conteniendo tres documentos obligatorios:

  1. spec.md: Requisitos funcionales expresados formalmente en sintaxis EARS en español (Easy Approach to Requirements Syntax):
    • Ubicuo: "El sistema siempre deberá..."
    • Eventos: "Al detectar [evento], el sistema deberá..."
    • Estado: "Mientras [estado activo], el sistema deberá..."
    • No Deseado: "Si ocurre [error/excepción], el sistema deberá..."
    • Opcional: "Donde [característica activada], el sistema deberá..."
  2. plan.md: Propuesta de arquitectura técnica, contratos de interfaces y análisis de riesgos.
  3. tasks.md: Plan de trabajo atómico dividido en tareas independientes de 20 a 30 minutos con criterios de aceptación verificables ("Hecho cuando:...").

2.1. Catálogo de Especificaciones SDD Implementadas en el Repositorio

Carpeta de Especificación Título y Dominio Requisitos EARS Clave Estado
specs/001-cierre-mvp-bedelia/ Cierre Formal del MVP de Bedelía Exportación Excel UTF-8 BOM, impresión membretada A4 y delimitación de alcance. 100% Completado
specs/002-moodle-export-sync/ Sincronización y Replicación Moodle Extracción de participantes, mapeo de roles y asignación de contraseñas DNI. 100% Completado
specs/003-migracion-fastapi/ Migración de Núcleo a FastAPI ASGI Routers modulares, Pydantic v2 DTOs y documentación interactiva /docs. 100% Completado
specs/004-depuracion-flask-total/ Erradicación Total de Frameworks Legacy Eliminación completa de librerías residuales de Flask y adopción pura de ASGI. 100% Completado
specs/005-importador-semanas-rango/ Ingesta por Rango Temporal en Sheets Sincronización cuatrimestral por semanas y fecha manual puntual. 100% Completado
specs/006-login-emergencia-adm/ Pasarela de Contingencia Administrativa Endpoint /adm/login con autenticación local ante fallas de Google/Moodle. 100% Completado
specs/007-formato-fechas-ddmmaaaa/ Estandarización de Fechas DD/MM/AAAA Formato visual legible e input de fecha nativo en toda la plataforma. 100% Completado
specs/008-paginacion-optimizacion-db/ Paginación y Rendimiento en PostgreSQL Paginación escalable (limit, offset, search) en tablas de usuarios y auditoría. 100% Completado
specs/009-asistente-ia-chatbot/ Copiloto de Inteligencia Artificial Inferencia asíncrona local con LLMs y UX bottom-sheet adaptativa en móviles. 100% Completado
specs/010-arquitectura-rag-udeci/ Arquitectura RAG Embebida Base vectorial de normativas de UniCABA e inyección de contexto de base de datos. 100% Completado
specs/011-servidor-mcp-asistente-guiado/ Servidor MCP Institucional y Spotlights Endpoints Model Context Protocol /api/v1/mcp y reflectores guiados en UI. 100% Completado
specs/012-beneficios-convenios-recepcion-qr/ Beneficios y Credencial QR Dinámica Catálogo de convenios y carnet universitario con QR rotativo cada 3 segundos. 100% Completado
specs/013-escaner-qr-puerto-com-serial/ Web Serial Multi-COM y Parser DNI Lectura por puerto serie para hasta 4 lectores y parser de DNI Renaper 2026. 100% Completado

3. Minutas de Reunión y Decisiones de Arquitectura (ADRs)

Minuta de Diseño Técnico N° 1: Desacople BFF Node.js + FastAPI vs. Monolito Spring Boot

  • Fecha: 28 de Agosto de 2026
  • Participantes: Carlos Facundo Tello (Líder Técnico)
  • Contexto: La cátedra sugiere implementar el núcleo en Java con Spring Boot y la analítica en Python.
  • Decisión Adoptada (ADR-001): Se resolvió adoptar un patrón Backend-For-Frontend (BFF) en Node.js 20 LTS acoplado a un Core REST API en FastAPI (Python 3.12).
  • Fundamentación:
    1. La huella de memoria RAM de una JVM estándar en reposo supera los 600 MB a 1 GB, mientras que Node.js (~45 MB) y FastAPI (~90 MB) permiten un uso altamente eficiente de la infraestructura cloud institucional.
    2. La interacción con lectores ópticos seriales mediante la Web Serial API requería un BFF web flexible y dinámico para procesar eventos en tiempo real.
    3. Para mantener compatibilidad con Java, se acordó diseñar el endpoint POST /api/v1/optimizer/spring-boot/sync con DTOs en camelCase, permitiendo a cualquier microservicio Spring Boot conectarse transparentemente.

Minuta de Diseño Técnico N° 2: Modelado del Algoritmo Genético de Asignación Áulica

  • Fecha: 15 de Septiembre de 2026
  • Participantes: Carlos Facundo Tello
  • Contexto: Se requiere un motor heurístico para resolver la colisión y optimización de horarios y aulas (problema NP-Hard).
  • Decisión Adoptada (ADR-002): Implementar un Algoritmo Genético multiobjetivo con representación vectorial de cromosomas.
  • Criterios de Fitness:
    • Penalización dura (W=1000): Choques físicos de aula, solapamientos docentes (salvo co-docencia habilitada) y superación de aforo.
    • Penalización blanda (W=1 a 10): Desperdicio de espacio físico y asignación en aulas teóricas cuando se requiere laboratorio.
    • Meta de rendimiento: Convergencia de 200 comisiones en menos de 5 segundos. Superada con éxito en 3.42 segundos.

Minuta de Diseño Técnico N° 3: Integración de Inteligencia Artificial Local (LLMs) y RAG

  • Fecha: 10 de Octubre de 2026
  • Participantes: Carlos Facundo Tello
  • Contexto: La consigna exige analítica predictiva avanzada. La cátedra valora la incorporación de tecnologías de vanguardia en IA.
  • Decisión Adoptada (ADR-003): Crear a "UdeCi", un asistente virtual institucional sustentado en LLMs locales (Qwen 30B / Llama 3) vía servidores locales (llama.cpp / Ollama).
  • Medidas de Seguridad y Privacidad:
    1. Uso mandatorio de llamadas asíncronas no bloqueantes con httpx.AsyncClient y timeout generoso (600s).
    2. Implementación de LiveContextService para consultar la base de datos PostgreSQL institucional en tiempo real sin alucinaciones.
    3. Aplicación de la directiva de Privacidad Estricta de Notas: un alumno solo puede consultar sus propias notas; el sistema rechaza solicitudes sobre calificaciones de otros estudiantes.
    4. Módulo prompt_security.py para interceptar intentos de Jailbreak y manipulación de directivas.

Minuta de Diseño Técnico N° 4: Hardware Serial COM y Parser Universal de DNI Argentino

  • Fecha: 22 de Octubre de 2026
  • Participantes: Carlos Facundo Tello
  • Contexto: Necesidad de controlar accesos físicos y molinetes en el Edificio Central mediante pistolas de código de barras USB/Serial.
  • Decisión Adoptada (ADR-004): Integrar la Web Serial API (navigator.serial) en el navegador, soportando hasta 4 ranuras COM simultáneas.
  • Resolución de Formatos de DNI:
    • Se diseñó el módulo argentine_dni_parser.py capaz de procesar el formato Renaper 2026 (extrayendo el número de documento y validando el JWT gubernamental embebido), los formatos PDF417 de DNIs tarjeta vigentes y libretas con prefijos F/M, la app Mi Argentina y tipeo directo con puntos (34.247.025).
    • Se añadió la normalización de teclado para corregir la sustitución de : por Ñ en pistolas configuradas en español, protegiendo nombres reales con Ñ.

Minuta de Diseño Técnico N° 5: Principio 10 de Tolerancia Cero y Consolidación de Calidad

  • Fecha: 28 de Octubre de 2026
  • Participantes: Carlos Facundo Tello
  • Contexto: Aseguramiento de calidad previo a la entrega final del cuatrimestre.
  • Decisión Adoptada (ADR-005): Establecer el Principio 10 de Tolerancia Cero en la constitución del proyecto: ninguna tarea o versión se da por finalizada si persisten advertencias o errores en el analizador de código estático (@[current_problems]).
  • Hito Alcanzado: 131 de 131 pruebas automatizadas pasando al 100% en pytest, 0 vulnerabilidades en escaneo estático bandit y despliegue continuo validado en producción en https://eduspace.oemspot.com.ar.

4. Estructura del Tablero de Trabajo Ágil (Kanban / User Stories)

A lo largo del cuatrimestre, el desarrollo se estructuró en cuatro columnas de flujo continuo:

┌──────────────────────┬──────────────────────┬──────────────────────┬──────────────────────┐
│  BACKLOG DE ÉPICAS   │    EN DESARROLLO     │      QA & TESTS      │  DESPLEGADO EN PROD  │
├──────────────────────┼──────────────────────┼──────────────────────┼──────────────────────┤
│ • Hardening Docker   │ • Optimización de    │ • Verificación 131   │ • Core FastAPI ASGI  │
│   Compose Prod       │   buffer serial      │   pruebas en pytest  │ • BFF Express Node.js│
│ • Workers background │   (380ms) para DNI   │ • Auditoría SAST/SCA │ • Algoritmo Genético │
│   continuos Moodle   │   Renaper 2026       │   con bandit/pip     │ • Copiloto IA UdeCi  │
│ • Pruebas de estrés  │ • Consolidación de   │ • Validación de DNI  │ • Servidor MCP       │
│   de concurrencia    │   documentación de   │   con puntos y sin   │ • Web Serial MultiCOM│
│                      │   entrega docente    │   puntos en receptor │ • QR Dinámico (3s)   │
│                      │                      │                      │ • Convenios/Beneficio│
│                      │                      │                      │ • Cartelera A4/Excel │
└──────────────────────┴──────────────────────┴──────────────────────┴──────────────────────┘

5. Conclusión de la Gestión de Proyecto

La aplicación de la metodología Spec-Driven Development (SDD) combinada con prácticas ágiles de ingeniería (TDD, CI/CD, revisiones de arquitectura y SemVer) permitió materializar un proyecto de altísima sofisticación técnica en los plazos previstos, garantizando que cada línea de código responda a un requerimiento formalizado, testeado y desplegado exitosamente en el servidor de producción institucional.