# 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. ```mermaid 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.57 (Consolidación al 04/11/2026)" checkout main merge dev id: "v3.8.57 (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/](file:///c:/Users/Soporte%20IT/workspace/admin-edu-space/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/](file:///c:/Users/Soporte%20IT/workspace/admin-edu-space/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/](file:///c:/Users/Soporte%20IT/workspace/admin-edu-space/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/](file:///c:/Users/Soporte%20IT/workspace/admin-edu-space/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/](file:///c:/Users/Soporte%20IT/workspace/admin-edu-space/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/](file:///c:/Users/Soporte%20IT/workspace/admin-edu-space/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/](file:///c:/Users/Soporte%20IT/workspace/admin-edu-space/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/](file:///c:/Users/Soporte%20IT/workspace/admin-edu-space/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/](file:///c:/Users/Soporte%20IT/workspace/admin-edu-space/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/](file:///c:/Users/Soporte%20IT/workspace/admin-edu-space/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/](file:///c:/Users/Soporte%20IT/workspace/admin-edu-space/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/](file:///c:/Users/Soporte%20IT/workspace/admin-edu-space/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/](file:///c:/Users/Soporte%20IT/workspace/admin-edu-space/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: ```text ┌──────────────────────┬──────────────────────┬──────────────────────┬──────────────────────┐ │ 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.