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.58 (Consolidación al 04/11/2026)"
checkout main
merge dev id: "v3.8.58 (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:
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á..."
plan.md: Propuesta de arquitectura técnica, contratos de interfaces y análisis de riesgos.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:
- 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.
- 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.
- Para mantener compatibilidad con Java, se acordó diseñar el endpoint
POST /api/v1/optimizer/spring-boot/synccon 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=1a10): 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.
- Penalización dura (
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:
- Uso mandatorio de llamadas asíncronas no bloqueantes con
httpx.AsyncClienty timeout generoso (600s). - Implementación de
LiveContextServicepara consultar la base de datos PostgreSQL institucional en tiempo real sin alucinaciones. - 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.
- Módulo
prompt_security.pypara interceptar intentos de Jailbreak y manipulación de directivas.
- Uso mandatorio de llamadas asíncronas no bloqueantes con
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.pycapaz 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 prefijosF/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Ñ.
- Se diseñó el módulo
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áticobandity despliegue continuo validado en producción enhttps://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.