docs: formalizar Principio 11 - estandares modernos de APIs (FastAPI/Pydantic) e integracion asincrona con LLMs

This commit is contained in:
2026-10-16 17:04:21 -03:00
parent e1cc2d1212
commit 76647e228b
16 changed files with 115 additions and 16 deletions
+3 -2
View File
@@ -63,5 +63,6 @@ Todo Requisito Funcional (RF) debe redactarse usando exclusivamente una de las 5
3. **Test-First**: En la lógica de backend, escribir primero el test en rojo antes de tocar el código de la solución. 3. **Test-First**: En la lógica de backend, escribir primero el test en rojo antes de tocar el código de la solución.
4. **Validación RF por RF**: Al finalizar, verificar cada RF de la especificación contra los tests y la interfaz gráfica. 4. **Validación RF por RF**: Al finalizar, verificar cada RF de la especificación contra los tests y la interfaz gráfica.
5. **Tolerancia Cero a Errores de Código (`@[current_problems]`) (Principio 10 de la Constitución)**: Es estrictamente inadmisible declarar una tarea o spec como completada si persisten errores en la terminal o problemas de diagnóstico. Todos los errores de importación, narrowing de tipos, NoneType y linter deben ser resueltos antes de dar el veredicto de aprobación. 5. **Tolerancia Cero a Errores de Código (`@[current_problems]`) (Principio 10 de la Constitución)**: Es estrictamente inadmisible declarar una tarea o spec como completada si persisten errores en la terminal o problemas de diagnóstico. Todos los errores de importación, narrowing de tipos, NoneType y linter deben ser resueltos antes de dar el veredicto de aprobación.
6. **Memoria**: Al completar cada fase o entrega, actualizar `MEMORY.md`. 6. **Diseño Modular y Contratos Fuertes (Principio 11 de la Constitución)**: Toda nueva API o endpoint debe dividirse en 4 capas desacopladas (`main.py`, `routers/`, `schemas/`, `storage.py`), usar `Pydantic` (`BaseModel` + `Field`) para validar bodies y query params con tipado estricto, levantar `HTTPException` controladas (404/422/400) sin retornar `null` ante fallos, y documentarse automáticamente en Swagger UI (`/docs`). Las integraciones con modelos de lenguaje (LLMs) deben implementarse con clientes asíncronos `httpx`, timeouts generosos (600s), formato estándar de roles e integrarse con la pestaña de IA en Configuración Global.
7. **Bump de Versión, Git Push y Despliegue en Producción (Skill `deploy`)**: Conforme al Principio 9 de la Constitución, incrementar versión semántica (`package.json`, `app.js`, `__init__.py`, `CHANGELOG.md`), ejecutar `git push origin dev` al repositorio remoto y desplegar en producción al servidor institucional LXC (`10.0.0.217`) utilizando las credenciales de `.credenciales`. 7. **Memoria**: Al completar cada fase o entrega, actualizar `MEMORY.md`.
8. **Bump de Versión, Git Push y Despliegue en Producción (Skill `deploy`)**: Conforme al Principio 9 de la Constitución, incrementar versión semántica (`package.json`, `app.js`, `__init__.py`, `CHANGELOG.md`), ejecutar `git push origin dev` al repositorio remoto y desplegar en producción al servidor institucional LXC (`10.0.0.217`) utilizando las credenciales de `.credenciales`.
+1 -1
View File
@@ -12,4 +12,4 @@ Tu misión es guiar el avance hacia la entrega del MVP de Bedelía asegurando el
3. **Plan y Tareas**: Delegar en `@planner` la confección de `plan.md` y `tasks.md`. 3. **Plan y Tareas**: Delegar en `@planner` la confección de `plan.md` y `tasks.md`.
4. **Implementación**: Delegar en `@implementer` una tarea atómica a la vez. 4. **Implementación**: Delegar en `@implementer` una tarea atómica a la vez.
5. **Validación**: Delegar en `@reviewer` la validación RF por RF. 5. **Validación**: Delegar en `@reviewer` la validación RF por RF.
6. **Despliegue y Memoria**: Verificar tests en verde (`pytest tests -v`), asegurar cero errores en `@[current_problems]` (Principio 10: no es admisible dar una tarea o hito por completado con errores), actualizar `MEMORY.md` y cumplir con el Principio 9 de la Constitución (bump, git push y despliegue continuo). 6. **Despliegue y Memoria**: Verificar tests en verde (`pytest tests -v`), asegurar cero errores en `@[current_problems]` (Principio 10: no es admisible dar una tarea o hito por completado con errores), validar estándares del Principio 11 (arquitectura modular, contratos Pydantic e IA asíncrona), actualizar `MEMORY.md` y cumplir con el Principio 9 de la Constitución (bump, git push y despliegue continuo).
+1
View File
@@ -11,4 +11,5 @@ Tu misión es ejecutar UNA tarea específica de `tasks.md` sin rediseñar el pla
- Enfoque **Test-First**: si tocas lógica de negocio, crea o ajusta primero la prueba automatizada en `backend/tests/`. - Enfoque **Test-First**: si tocas lógica de negocio, crea o ajusta primero la prueba automatizada en `backend/tests/`.
- Ejecuta las pruebas (`python -m pytest tests -v` en backend) y asegura 100% de éxito. - Ejecuta las pruebas (`python -m pytest tests -v` en backend) y asegura 100% de éxito.
- **Principio 10 (Tolerancia Cero)**: Repara activamente todos los problemas reportados en la terminal o Language Server (`@[current_problems]`). Es estrictamente inadmisible decir que una tarea está terminada o completada si hay errores o fallos en el código. - **Principio 10 (Tolerancia Cero)**: Repara activamente todos los problemas reportados en la terminal o Language Server (`@[current_problems]`). Es estrictamente inadmisible decir que una tarea está terminada o completada si hay errores o fallos en el código.
- **Principio 11 (Arquitectura de APIs y LLMs)**: Diseña APIs modulares (`main.py`, `routers/`, `schemas/`, `storage.py`), utiliza Pydantic (`BaseModel` + `Field`) para validar bodies y query params tipados, responde con códigos de estado HTTP explícitos (201/200/204/404/422), levanta `HTTPException` descriptivas sin retornar `null` en fallos y utiliza `httpx` asíncrono con timeouts generosos (600s) para llamadas a modelos de lenguaje (LLMs).
- Marca la tarea con `[x]` en `tasks.md` al terminar únicamente si no hay ningún error y detén tu ejecución para supervisión. - Marca la tarea con `[x]` en `tasks.md` al terminar únicamente si no hay ningún error y detén tu ejecución para supervisión.
+1
View File
@@ -11,4 +11,5 @@ Tu objetivo es redactar especificaciones precisas, arquitecturas limpias y lista
- Escribe las especificaciones en `specs/NNN-nombre/spec.md` con sintaxis EARS en español. - Escribe las especificaciones en `specs/NNN-nombre/spec.md` con sintaxis EARS en español.
- Nunca incluyas nombres de archivos ni detalles de base de datos en `spec.md` (van en `plan.md`). - Nunca incluyas nombres de archivos ni detalles de base de datos en `spec.md` (van en `plan.md`).
- Define criterios de aceptación verificables y delimita claramente el **Fuera de Alcance**. - Define criterios de aceptación verificables y delimita claramente el **Fuera de Alcance**.
- En `plan.md`, estructura siempre el diseño técnico bajo las 4 capas del Principio 11 (`main.py`, `routers/`, `schemas/`, `storage.py`), definiendo contratos Pydantic (`BaseModel` con `Field`), códigos de estado HTTP semánticos (201, 204, 404, 422), y para módulos de IA prever clientes `httpx` asíncronos con timeouts generosos (600s) y la pestaña correspondiente en Configuración Global.
- En `tasks.md`, desglosa tareas en bloques atómicos de 20 a 30 minutos con `[ ]` y criterio *"Hecho cuando:"*. - En `tasks.md`, desglosa tareas en bloques atómicos de 20 a 30 minutos con `[ ]` y criterio *"Hecho cuando:"*.
+2 -1
View File
@@ -11,7 +11,8 @@ Tu misión es actuar como QA profesional y auditor de calidad, garantizando que
2. **En Validación de Implementación**: 2. **En Validación de Implementación**:
- Revisa los cambios (`git diff`). - Revisa los cambios (`git diff`).
- Verifica activamente que no existan errores ni problemas en la terminal o Language Server (`@[current_problems]`). Si persisten errores de sintaxis, imports, tipos o `NoneType`, emitir obligatoriamente `VEREDICTO: CAMBIOS NECESARIOS`. - Verifica activamente que no existan errores ni problemas en la terminal o Language Server (`@[current_problems]`). Si persisten errores de sintaxis, imports, tipos o `NoneType`, emitir obligatoriamente `VEREDICTO: CAMBIOS NECESARIOS`.
- Verifica el cumplimiento del **Principio 11**: arquitectura modular (`routers/`, `schemas/`, `storage.py`), validación con Pydantic `BaseModel` + `Field`, uso estricto de códigos HTTP (201/200/204/404/422), manejo controlado de excepciones (`HTTPException`) sin retornar `null` ante fallos, y uso de `httpx` asíncrono con timeouts generosos (600s) en integraciones con LLMs.
- Ejecuta las pruebas automatizadas (`python -m pytest tests -v`). - Ejecuta las pruebas automatizadas (`python -m pytest tests -v`).
- Recorre cada RF de la especificación y emite un veredicto formal: - Recorre cada RF de la especificación y emite un veredicto formal:
- `VEREDICTO: APROBADO` (solo admisible si pruebas pasan al 100% y cero problemas en `@[current_problems]`). - `VEREDICTO: APROBADO` (solo admisible si pruebas pasan al 100%, cero problemas en `@[current_problems]` y cumplimiento estricto de la Constitución).
- `VEREDICTO: CAMBIOS NECESARIOS` (con lista numerada de archivo:línea, incumplimiento y corrección esperada). - `VEREDICTO: CAMBIOS NECESARIOS` (con lista numerada de archivo:línea, incumplimiento y corrección esperada).
+22 -1
View File
@@ -35,10 +35,25 @@ Plataforma web de gestión de espacios áulicos, sincronización académica y as
.\security_audit.bat --no-pause .\security_audit.bat --no-pause
``` ```
## Convenciones de Desarrollo ## Convenciones de Desarrollo y Buenas Prácticas de APIs
- Nombres de variables, funciones, clases, tablas, endpoints y commits estrictamente en **inglés**. - Nombres de variables, funciones, clases, tablas, endpoints y commits estrictamente en **inglés**.
- Los endpoints de la API deben seguir estándares RESTful puros bajo `/api/v1/` retornando exclusivamente JSON. - Los endpoints de la API deben seguir estándares RESTful puros bajo `/api/v1/` retornando exclusivamente JSON.
- Interfaz gráfica de usuario, etiquetas de formularios, mensajes de error y documentación operativa exclusivamente en **español**. - Interfaz gráfica de usuario, etiquetas de formularios, mensajes de error y documentación operativa exclusivamente en **español**.
- **Arquitectura Modular en 4 Capas (Separación Estricta de Responsabilidades)**:
- `main.py`: Inicialización de la aplicación y registro de routers. No colocar lógica de negocio en el archivo principal ni en el frontend.
- `routers/`: Endpoints agrupados por dominio utilizando `APIRouter` (o Blueprints) con prefijos comunes (`prefix="/products"`, `prefix="/llm"`) y etiquetas (`tags=["..."]`) para una documentación limpia en Swagger UI.
- `schemas/` (`schemas.py`): Modelos de datos y validaciones con `Pydantic` (`BaseModel`).
- `storage.py` (o capa de persistencia `models/`): Centralización del acceso a datos y base de datos.
- **Validación de Datos con Pydantic y Tipado Fuerte**:
- Heredar de `BaseModel` para el cuerpo (body) de las peticiones.
- Uso mandatorio de `Field` para restricciones de negocio: `min_length`, `max_length`, `gt=0`, `ge=0`, etc.
- Manejo de parámetros: Path Parameters obligatorios en la URL y Query Parameters opcionales con defaults tipados (`limit: int = 10`).
- Validación y captura automática: ante datos inválidos responder con código `422 Unprocessable Entity` detallando el atributo exacto y la falla.
- **Códigos de Estado HTTP y Manejo de Excepciones**:
- Códigos de estado HTTP semánticos: `201 Created` en POST exitosos, `200 OK` en lecturas/actualizaciones, `204 No Content` en eliminaciones sin cuerpo.
- Prohibido retornar `null` o respuestas vacías ante fallos lógicos: levantar siempre excepciones controladas (`HTTPException`) con código adecuado (ej. `404 Not Found` con `detail="Recurso no encontrado"`, `400 Bad Request`, `409 Conflict`).
- **Documentación Interactiva Automática**:
- Contratos OpenAPI expuestos en `/docs` (Swagger UI) listos para pruebas en vivo (*Try it out*) y visualización de esquemas.
## Reglas de Dominio y Trampas Conocidas ## Reglas de Dominio y Trampas Conocidas
- **Reemplazo del Excel de Bedelía**: La gestión operativa diaria debe realizarse en la app a través del circuito secuencial de 9 pasos (Sedes -> Aulas -> Ciclos Lectivos -> Carreras -> Asignaturas -> Comisiones -> Profesores -> Alumnos -> Reservas). Las comisiones heredan y exponen la Carrera de la asignatura para trazabilidad por plan de estudios. Las hojas de cálculo son únicamente para importación masiva de datos iniciales. - **Reemplazo del Excel de Bedelía**: La gestión operativa diaria debe realizarse en la app a través del circuito secuencial de 9 pasos (Sedes -> Aulas -> Ciclos Lectivos -> Carreras -> Asignaturas -> Comisiones -> Profesores -> Alumnos -> Reservas). Las comisiones heredan y exponen la Carrera de la asignatura para trazabilidad por plan de estudios. Las hojas de cálculo son únicamente para importación masiva de datos iniciales.
@@ -47,6 +62,11 @@ Plataforma web de gestión de espacios áulicos, sincronización académica y as
- **Matriz de Conflictos de Reservas**: Una reserva no puede guardarse si genera superposición física de aula presencial, sobrepasa el aforo máximo o solapa al docente (salvo excepción justificada por co-docencia activa). - **Matriz de Conflictos de Reservas**: Una reserva no puede guardarse si genera superposición física de aula presencial, sobrepasa el aforo máximo o solapa al docente (salvo excepción justificada por co-docencia activa).
- **Restricción Diaria de Alumnos**: Un alumno no puede matricularse en dos materias regulares en el mismo día, a menos que sea un curso corto (`is_short_course`) o posea autorización expresa de Bedelía (`allow_same_day_exception`). - **Restricción Diaria de Alumnos**: Un alumno no puede matricularse en dos materias regulares en el mismo día, a menos que sea un curso corto (`is_short_course`) o posea autorización expresa de Bedelía (`allow_same_day_exception`).
- **Autenticación**: Los flujos de acceso pasan por tokens JWT transportados en cookies seguras `HttpOnly`. - **Autenticación**: Los flujos de acceso pasan por tokens JWT transportados en cookies seguras `HttpOnly`.
- **Integración Asíncrona con Modelos de IA Locales (LLMs) y Asistente en la App**:
- **Pestaña en Configuración Global**: Incluir una pestaña específica en la Configuración Global de la app para gestionar la integración con modelos de IA (servidor/URL, modelo seleccionado, tokens y timeout), sentando las bases para el futuro asistente virtual que guiará al usuario en la plataforma.
- **Cliente HTTP Asíncrono no Bloqueante (`httpx`)**: Toda llamada a servidores de inferencia locales (Ollama, llama.cpp, vLLM) o APIs de IA debe realizarse de forma asíncrona (`httpx.AsyncClient` con `async def` / `await`) para no bloquear el hilo de ejecución principal ni degradar la concurrencia.
- **Timeouts Generosos**: Fijar un tiempo de espera (`timeout`) amplio (mínimo 600 segundos en entornos locales) previendo la carga de modelos en VRAM o inferencias de prompts extensos.
- **Estructura de Roles Estándar**: Formatear el payload JSON enviando el modelo y los mensajes con roles explícitos (`role: "system" | "user" | "assistant"`, `content: prompt`).
## Metodología SDD (Spec-Driven Development) y Arnés de Agentes ## Metodología SDD (Spec-Driven Development) y Arnés de Agentes
- **La especificación manda**: Ninguna feature se codifica sin su carpeta `specs/NNN-nombre/` conteniendo `spec.md` (requisitos en sintaxis **EARS** en español: Ubicuo, Eventos, Estado, No Deseado, Opcional), `plan.md` y `tasks.md` (skill `.agents/skills/sdd/SKILL.md`). - **La especificación manda**: Ninguna feature se codifica sin su carpeta `specs/NNN-nombre/` conteniendo `spec.md` (requisitos en sintaxis **EARS** en español: Ubicuo, Eventos, Estado, No Deseado, Opcional), `plan.md` y `tasks.md` (skill `.agents/skills/sdd/SKILL.md`).
@@ -66,6 +86,7 @@ Plataforma web de gestión de espacios áulicos, sincronización académica y as
## Límites ## Límites
- **SIEMPRE**: Lee `docs/constitution.md` y la especificación activa (`specs/`) antes de proponer o modificar código. - **SIEMPRE**: Lee `docs/constitution.md` y la especificación activa (`specs/`) antes de proponer o modificar código.
- **SIEMPRE (Principio 10 - Tolerancia Cero)**: Repara activamente todos los problemas y errores reportados en la terminal / Language Server (`@[current_problems]`). **Es estrictamente inadmisible decir que una tarea está terminada o completada si hay errores o problemas en el código.** - **SIEMPRE (Principio 10 - Tolerancia Cero)**: Repara activamente todos los problemas y errores reportados en la terminal / Language Server (`@[current_problems]`). **Es estrictamente inadmisible decir que una tarea está terminada o completada si hay errores o problemas en el código.**
- **SIEMPRE (Principio 11 - Contratos Fuertes e IA)**: Implementar endpoints desacoplados en routers modulares, validar payloads con Pydantic `BaseModel` y `Field`, retornar códigos de estado HTTP semánticos (201, 204, 404, 422), exponer contratos en OpenAPI `/docs` y emplear `httpx` asíncrono con timeouts generosos (600s) para integraciones con LLMs.
- **SIEMPRE**: Al finalizar la tarea (con cero problemas en el código), realizar bump de versión, `git push origin dev` y despliegue a producción con `.credenciales` (Skill `.agents/skills/deploy/SKILL.md`). - **SIEMPRE**: Al finalizar la tarea (con cero problemas en el código), realizar bump de versión, `git push origin dev` y despliegue a producción con `.credenciales` (Skill `.agents/skills/deploy/SKILL.md`).
- **PREGUNTA ANTES DE**: Añadir nuevas dependencias a `requirements.txt` o `package.json`, alterar el esquema relacional de la base de datos o cambiar la estrategia de caché. - **PREGUNTA ANTES DE**: Añadir nuevas dependencias a `requirements.txt` o `package.json`, alterar el esquema relacional de la base de datos o cambiar la estrategia de caché.
- **NUNCA**: Expongas contraseñas, tokens de Moodle, secretos de API o el contenido del archivo `.credenciales` en el código fuente, commits o logs públicos. - **NUNCA**: Expongas contraseñas, tokens de Moodle, secretos de API o el contenido del archivo `.credenciales` en el código fuente, commits o logs públicos.
+14
View File
@@ -11,6 +11,20 @@ El formato está basado en [Keep a Changelog](https://keepachangelog.com/es-ES/1
- **Sincronización Continua Moodle (Fase 6):** Automatización de workers persistentes en background para el procesamiento continuo de la cola de Web Services Moodle 4.1. - **Sincronización Continua Moodle (Fase 6):** Automatización de workers persistentes en background para el procesamiento continuo de la cola de Web Services Moodle 4.1.
- **Pruebas de Carga y Hardening (Fase 6):** Pruebas de estrés de concurrencia y validación final de producción. - **Pruebas de Carga y Hardening (Fase 6):** Pruebas de estrés de concurrencia y validación final de producción.
## [3.5.7] - 2026-10-16
### Added
- **Principio 11 de la Constitución: Estándares Modernos de APIs (FastAPI/Pydantic) e Integración con Modelos de IA (LLMs)**:
- **Arquitectura Modular en 4 Capas**: Desacople estricto en `main.py` (arranque/routers), `routers/` (APIRouters por dominio con prefijo y tags), `schemas/` (Pydantic `BaseModel`) y `storage.py` (acceso a DB). Prohibición de lógica de negocio en el frontend o archivos únicos.
- **Contratos Fuertes y Pydantic**: Uso mandatorio de `Field` para validación (`min_length`, `max_length`, `gt`, `ge`), diferenciación estricta de Path Parameters (obligatorios) y Query Parameters (opcionales tipados), y respuestas automáticas de error `422 Unprocessable Entity` detalladas.
- **Semántica HTTP y Excepciones**: Uso estricto de códigos `201 Created` en POST, `200 OK`, `204 No Content` en DELETE y excepciones controladas `HTTPException` (404 con mensaje explícito, 400, 409) prohibiendo el retorno de `null` o respuestas vacías ambiguas.
- **Documentación Interactiva Automática**: Contratos OpenAPI expuestos en `/docs` (Swagger UI) con capacidades de prueba en vivo.
- **Integración Asíncrona con Modelos de IA Locales (LLMs) & Asistente Virtual**:
- Incorporación al Roadmap (Fase 7) de la pestaña de IA en la Configuración Global administrativa (URL de inferencia local Ollama/llama.cpp, modelo, token/clave API, switch de activación y timeout).
- Uso obligatorio de clientes asíncronos no bloqueantes `httpx.AsyncClient` (`async def` / `await`).
- Configuración de timeout generoso de 600 segundos previendo carga de modelos en VRAM o inferencia de prompts extensos.
- Estructura de payload estandarizada por historial de roles (`system`, `user`, `assistant`).
- Sincronización documental integral en `docs/constitution.md`, `AGENTS.md`, `.agents/skills/sdd/SKILL.md`, `.opencode/agents/` (`coordinator.md`, `planner.md`, `implementer.md`, `reviewer.md`), `ROADMAP.md` y `MEMORY.md`.
## [3.5.6] - 2026-10-16 ## [3.5.6] - 2026-10-16
### Added ### Added
- **Principio 10 de la Constitución: Tolerancia Cero a Errores de Código y Diagnóstico (`@[current_problems]`)**: - **Principio 10 de la Constitución: Tolerancia Cero a Errores de Código y Diagnóstico (`@[current_problems]`)**:
+22 -1
View File
@@ -270,6 +270,27 @@ Memoria del proyecto entre sesiones para la rama `dev`.
- **Validación Automatizada**: - **Validación Automatizada**:
- 52/52 tests pasando en verde al 100% (`pytest tests -v`). - 52/52 tests pasando en verde al 100% (`pytest tests -v`).
- **Sprint v3.5.7: Principio 11 de la Constitución — Estándares Modernos de APIs (FastAPI/Pydantic) e Integración con Modelos de IA (LLMs)**:
- **Arquitectura Modular en 4 Capas**:
- Desacople estricto: `main.py` (bootstrap/registro), `routers/` (endpoints agrupados por dominio con prefijos y tags para Swagger), `schemas/` (contratos con Pydantic `BaseModel`), `storage.py` (acceso a persistencia). Prohibida la lógica de negocio en el frontend o en archivos monolíticos.
- **Tipado Fuerte y Validación Pydantic**:
- Uso obligatorio de `Field` para validaciones declarativas (`min_length`, `max_length`, `gt`, `ge`, regex).
- Distinción estricta de Path Parameters (obligatorios) y Query Parameters (opcionales tipados con defaults).
- Manejo y respuesta automática de error `422 Unprocessable Entity` detallando el campo exacto.
- **Semántica HTTP y Excepciones Controladas**:
- Uso de códigos de estado HTTP semánticos (`201 Created` en POST, `200 OK`, `204 No Content`).
- Prohibido retornar `null` o respuestas vacías ante fallos: levantar `HTTPException` controladas con detalle descriptivo (404, 400, 409).
- **Documentación Interactiva Automática**:
- Contratos OpenAPI expuestos en `/docs` (Swagger UI) con capacidades de prueba en vivo (*Try it out*).
- **Integración Asíncrona con Modelos de IA Locales (LLMs) & Asistente Virtual**:
- **Pestaña en Configuración Global**: Planificada en `ROADMAP.md` y UI administrativa para configurar URL del servidor local (Ollama, llama.cpp), modelo, token y timeout para el futuro asistente virtual de la app.
- **Cliente Asíncrono no Bloqueante**: Uso mandatorio de `httpx.AsyncClient` con `async def` / `await` para inferencias concurrentes sin bloquear el servidor.
- **Timeout Generoso**: Configurar timeout de 600 segundos previendo carga de modelos en VRAM o prompts extensos.
- **Formato Estándar de Roles**: Historial estructurado bajo `role: "system" | "user" | "assistant"` y `content: prompt`.
- **Actualización Documental Completa**:
- Sincronizados `docs/constitution.md` (Principio 11), `AGENTS.md`, `.agents/skills/sdd/SKILL.md`, `.opencode/agents/` (`coordinator.md`, `planner.md`, `implementer.md`, `reviewer.md`), `ROADMAP.md` (Fase 7) y `MEMORY.md`.
## Próximos pasos ## Próximos pasos
1. Monitorear los inicios de sesión delegados en producción con cuentas docentes y estudiantiles. 1. Monitorear los inicios de sesión delegados en producción con cuentas docentes y estudiantiles.
2. Continuar con el roadmap hacia la Fase 6 de hardening y orquestación de servicios en Docker. 2. Implementar la pestaña de Asistente IA en la Configuración Global administrativa (`ROADMAP.md` Fase 7).
3. Continuar con el roadmap hacia la Fase 6 de hardening y orquestación de servicios en Docker.
+1 -1
View File
@@ -4,7 +4,7 @@ Plataforma integral de gestión áulica, asignación de espacios, control de hor
El proyecto se basa en una arquitectura **desacoplada (Frontend / Backend)** en formato monorepo. El proyecto se basa en una arquitectura **desacoplada (Frontend / Backend)** en formato monorepo.
**Versión Actual:** `3.5.6` (Principio 10 Tolerancia Cero a Errores, Robustez SystemSetting y Replicador) **Versión Actual:** `3.5.7` (Principio 11: Estándares Modernos de APIs, Pydantic e Integración de IA)
**Institución:** Universidad de la Ciudad de Buenos Aires (UniCABA) **Institución:** Universidad de la Ciudad de Buenos Aires (UniCABA)
**Entorno de Producción:** `https://eduspace.oemspot.com.ar` (LXC `10.0.0.217`) **Entorno de Producción:** `https://eduspace.oemspot.com.ar` (LXC `10.0.0.217`)
+17 -1
View File
@@ -2,7 +2,7 @@
## Gestión de Espacios Áulicos, Asignación de Comisiones y Operatoria de Bedelía ## Gestión de Espacios Áulicos, Asignación de Comisiones y Operatoria de Bedelía
**Institución:** Universidad de la Ciudad de Buenos Aires (UniCABA) **Institución:** Universidad de la Ciudad de Buenos Aires (UniCABA)
**Versión:** 3.5.6 (Principio 10 Tolerancia Cero a Errores, Robustez SystemSetting y Replicador) **Versión:** 3.5.7 (Principio 11: Estándares Modernos de APIs, Pydantic e Integración de IA)
**Fecha de Actualización:** 16 de Octubre de 2026 **Fecha de Actualización:** 16 de Octubre de 2026
**Rama Base:** `dev` **Rama Base:** `dev`
@@ -108,3 +108,19 @@ Fase 6: Despliegue en Servidores y Hardening [█████████░
- [ ] Automatización de workers persistentes en systemd para la cola asíncrona de Moodle. - [ ] Automatización de workers persistentes en systemd para la cola asíncrona de Moodle.
- [ ] Configuración optimizada de `docker-compose.yml` de producción. - [ ] Configuración optimizada de `docker-compose.yml` de producción.
- [ ] Pruebas de estrés de concurrencia y validación final de performance sub-segundo. - [ ] Pruebas de estrés de concurrencia y validación final de performance sub-segundo.
---
### Fase 7: Integración con Modelos de IA Locales (LLMs) & Asistente Virtual en la App 🤖 *(Diseñada / Por Implementar)*
- [ ] **Pestaña de Asistente IA en Configuración Global**:
- Incorporar en la vista de configuración general del Administrador una pestaña dedicada a la configuración de IA.
- Parámetros configurables: URL del servidor de inferencia (Ollama, llama.cpp, vLLM, LiteLLM), Modelo seleccionado, Clave de API / Token, Timeout de conexión (por defecto 600s para entornos locales), y Switch de activación general.
- Almacenamiento seguro de credenciales con Fernet en base de datos (`system_settings`).
- [ ] **Módulo Backend Asíncrono de Inferencia (`httpx`)**:
- Implementar servicio `AIService` utilizando `httpx.AsyncClient` con funciones asíncronas no bloqueantes (`async def` / `await`).
- Gestión estructurada del historial y contexto mediante el estándar de roles (`system`, `user`, `assistant`).
- Timeout generoso (600 segundos) para mitigar demoras en carga de modelos a VRAM o prompts extensos.
- [ ] **Asistente Conversacional para Usuarios**:
- Componente de interfaz flotante para guiar a Bedelía, Docentes y Alumnos en el uso de la plataforma.
- Capacidades de consulta sobre asignaciones áulicas, cronogramas, comisiones y manuales operativos.
+1 -1
View File
@@ -6,7 +6,7 @@ from flask_babel import Babel, gettext as _
from config.config import Config from config.config import Config
# Initialize extensions # Initialize extensions
__version__ = "3.5.6" __version__ = "3.5.7"
db = SQLAlchemy() db = SQLAlchemy()
migrate = Migrate() migrate = Migrate()
cors = CORS() cors = CORS()
+1 -1
View File
@@ -7,7 +7,7 @@ OPENAPI_SPEC = {
"info": { "info": {
"title": "Edu-Space REST API", "title": "Edu-Space REST API",
"description": "Enterprise Academic & Physical Space Management REST API with JWT Authentication and Role-Based Access Control.", "description": "Enterprise Academic & Physical Space Management REST API with JWT Authentication and Role-Based Access Control.",
"version": "3.5.6" "version": "3.5.7"
}, },
"servers": [ "servers": [
{ {
+1 -1
View File
@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
setup( setup(
name="edu-space-admin", name="edu-space-admin",
version="3.5.6", version="3.5.7",
description="Administrative interface for Edu-Space Classroom Management System", description="Administrative interface for Edu-Space Classroom Management System",
author="Edu-Space Development Team", author="Edu-Space Development Team",
author_email="admin@edu-space.com", author_email="admin@edu-space.com",
+24 -1
View File
@@ -49,4 +49,27 @@ La asignación de reservas de aulas debe validar en tiempo real e impedir de for
### 10. Tolerancia Cero a Errores de Código y Diagnóstico (`@[current_problems]`) ### 10. Tolerancia Cero a Errores de Código y Diagnóstico (`@[current_problems]`)
- **Prohibición de Cierre con Errores**: Es estrictamente inadmisible declarar una tarea, plan o sprint como "terminado", "completado" o "finalizado" si existen errores en el código, advertencias críticas de tipado, o problemas reportados por el analizador estático / terminal (`@[current_problems]`). - **Prohibición de Cierre con Errores**: Es estrictamente inadmisible declarar una tarea, plan o sprint como "terminado", "completado" o "finalizado" si existen errores en el código, advertencias críticas de tipado, o problemas reportados por el analizador estático / terminal (`@[current_problems]`).
- **Remediación Mandatoria Previa**: Toda tarea se considera incompleta por definición hasta que el agente verifique activamente y repare al 100% todos los errores de sintaxis, imports, resolución de módulos, estrechamiento de tipos (type narrowing) y accesos a `NoneType`. - **Remediación Mandatoria Previa**: Toda tarea se considera incompleta por definición hasta que el agente verifique activamente y repare al 100% todos los errores de sintaxis, imports, resolución de módulos, estrechamiento de tipos (type narrowing) y accesos a `NoneType`.
- **Quality Gate Infranqueable**: Ningún commit, bump de versión o despliegue a producción puede ser ejecutado mientras existan problemas o errores no resueltos en `@[current_problems]`. - **Quality Gate Infranqueable**: Ningún commit, bump de versión o despliegue a producción puede ser ejecutado mientras existan problemas o errores no resueltos en `@[current_problems]`.
### 11. Estándares Modernos de APIs, Contratos Fuertes (FastAPI / Pydantic) e Integración con Modelos de IA (LLMs)
- **Arquitectura Modular y Separación de Responsabilidades**:
- Prohibido el código monolítico o ubicar lógica de negocio en el frontend o en archivos únicos de arranque.
- Estructuración estricta en 4 capas desacopladas:
1. **Entrada / Bootstrap (`main.py`)**: Inicialización de la aplicación y registro de routers.
2. **Rutas y Controladores (`routers/`)**: Agrupación de endpoints por dominio con prefijos (`prefix="/..."`) y etiquetas (`tags=["..."]`) para OpenAPI/Swagger limpio.
3. **Contratos y Validación (`schemas/` o `schemas.py`)**: Definición de esquemas de datos de entrada/salida mediante `pydantic.BaseModel`.
4. **Capa de Persistencia / Almacenamiento (`storage.py` / `models/`)**: Conexión a bases de datos y persistencia desacoplada.
- **Tipado Fuerte y Contratos con Pydantic**:
- Toda entrada (Body) debe heredar de `BaseModel` con validaciones explícitas usando `Field` (`min_length`, `max_length`, `gt`, `ge`, regex).
- Manejo diferenciado de parámetros: Path Parameters (obligatorios en la URL) y Query Parameters (opcionales con valores tipados por defecto).
- Manejo de errores de validación automático (422 Unprocessable Entity con detalle preciso del atributo).
- **Semántica HTTP y Excepciones Controladas**:
- Uso estricto de códigos HTTP: `201 Created` para creación vía POST, `200 OK` para consultas/actualizaciones, `204 No Content` para borrados sin cuerpo.
- Prohibido retornar valores nulos (`null`) o respuestas vacías ante fallos lógicos: siempre levantar excepciones controladas (`HTTPException`) con código de estado semántico (ej. `404 Not Found` con `detail="Recurso no encontrado"`, `400 Bad Request`, `409 Conflict`).
- **Documentación Interactiva Automática**:
- Los contratos de API deben exponerse de forma nativa vía Swagger UI (`/docs`), permitiendo pruebas interactivas en vivo (*Try it out*) y visualización de esquemas.
- **Integración Asíncrona con Modelos de Lenguaje (LLMs) y Asistente en la App**:
- **Pestaña en Configuración Global**: La aplicación debe disponer en su configuración global de una pestaña dedicada a la configuración del Asistente de IA (URL del proveedor/servidor local, modelo, timeout, token y activación).
- **Cliente HTTP Asíncrono no Bloqueante**: Utilizar exclusivamente clientes asíncronos (`httpx.AsyncClient` con `async def` y `await`) para conectar con motores de inferencia locales (Ollama, llama.cpp, vLLM) o externos sin bloquear el bucle de eventos ni los hilos del servidor.
- **Configuración de Timeouts Generosos**: Configurar tiempos de espera adecuados para LLMs (ej. timeout por defecto de 600 segundos para dar soporte a inferencias locales en GPU/VRAM compartida).
- **Formato Estándar de Roles**: Toda comunicación con modelos de lenguaje debe emplear el estándar de historial estructurado por roles (`{"role": "system" | "user" | "assistant", "content": "..."}`).
+1 -1
View File
@@ -1,6 +1,6 @@
{ {
"name": "frontend", "name": "frontend",
"version": "3.5.6", "version": "3.5.7",
"description": "", "description": "",
"main": "index.js", "main": "index.js",
"scripts": { "scripts": {
+3 -3
View File
@@ -85,9 +85,9 @@ const env = nunjucks.configure(path.join(__dirname, '../views'), {
}); });
// Versiones institucionales del sistema // Versiones institucionales del sistema
const APP_VERSION = '3.5.6'; const APP_VERSION = '3.5.7';
const FRONTEND_VERSION = '3.5.6'; const FRONTEND_VERSION = '3.5.7';
const BACKEND_VERSION = '3.5.6'; const BACKEND_VERSION = '3.5.7';
env.addGlobal('app_version', APP_VERSION); env.addGlobal('app_version', APP_VERSION);
env.addGlobal('frontend_version', FRONTEND_VERSION); env.addGlobal('frontend_version', FRONTEND_VERSION);