157 lines
14 KiB
Markdown
157 lines
14 KiB
Markdown
# 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.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/](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.
|
|
|