diff --git a/.agents/skills/sdd/SKILL.md b/.agents/skills/sdd/SKILL.md index c25a737..77350c8 100644 --- a/.agents/skills/sdd/SKILL.md +++ b/.agents/skills/sdd/SKILL.md @@ -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. 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. -6. **Memoria**: Al completar cada fase o entrega, actualizar `MEMORY.md`. -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`. +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. **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`. diff --git a/.opencode/agents/coordinator.md b/.opencode/agents/coordinator.md index 9bf01ce..a62a14d 100644 --- a/.opencode/agents/coordinator.md +++ b/.opencode/agents/coordinator.md @@ -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`. 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. -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). diff --git a/.opencode/agents/implementer.md b/.opencode/agents/implementer.md index bbc6dc2..d2383ca 100644 --- a/.opencode/agents/implementer.md +++ b/.opencode/agents/implementer.md @@ -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/`. - 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 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. diff --git a/.opencode/agents/planner.md b/.opencode/agents/planner.md index 4597358..265972a 100644 --- a/.opencode/agents/planner.md +++ b/.opencode/agents/planner.md @@ -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. - 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**. +- 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:"*. diff --git a/.opencode/agents/reviewer.md b/.opencode/agents/reviewer.md index b814adb..05b48cb 100644 --- a/.opencode/agents/reviewer.md +++ b/.opencode/agents/reviewer.md @@ -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**: - 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 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`). - 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). diff --git a/AGENTS.md b/AGENTS.md index 576f7d1..2baa2dd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -35,10 +35,25 @@ Plataforma web de gestión de espacios áulicos, sincronización académica y as .\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**. - 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**. +- **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 - **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). - **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`. +- **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 - **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 - **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 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`). - **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. diff --git a/CHANGELOG.md b/CHANGELOG.md index f1d84c4..7056fd2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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. - **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 ### Added - **Principio 10 de la Constitución: Tolerancia Cero a Errores de Código y Diagnóstico (`@[current_problems]`)**: diff --git a/MEMORY.md b/MEMORY.md index eddd35e..1069423 100644 --- a/MEMORY.md +++ b/MEMORY.md @@ -270,6 +270,27 @@ Memoria del proyecto entre sesiones para la rama `dev`. - **Validación Automatizada**: - 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 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. \ No newline at end of file +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. \ No newline at end of file diff --git a/README.md b/README.md index 62e0f8e..c967901 100644 --- a/README.md +++ b/README.md @@ -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. -**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) **Entorno de Producción:** `https://eduspace.oemspot.com.ar` (LXC `10.0.0.217`) diff --git a/ROADMAP.md b/ROADMAP.md index 6afd430..a86fe9b 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -2,7 +2,7 @@ ## Gestión de Espacios Áulicos, Asignación de Comisiones y Operatoria de Bedelía **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 **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. - [ ] Configuración optimizada de `docker-compose.yml` de producción. - [ ] 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. + diff --git a/backend/app/__init__.py b/backend/app/__init__.py index ed5cb05..bcf8c35 100644 --- a/backend/app/__init__.py +++ b/backend/app/__init__.py @@ -6,7 +6,7 @@ from flask_babel import Babel, gettext as _ from config.config import Config # Initialize extensions -__version__ = "3.5.6" +__version__ = "3.5.7" db = SQLAlchemy() migrate = Migrate() cors = CORS() diff --git a/backend/app/routes/api/openapi.py b/backend/app/routes/api/openapi.py index 167f355..12cd60d 100644 --- a/backend/app/routes/api/openapi.py +++ b/backend/app/routes/api/openapi.py @@ -7,7 +7,7 @@ OPENAPI_SPEC = { "info": { "title": "Edu-Space REST API", "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": [ { diff --git a/backend/setup.py b/backend/setup.py index f3ab667..967c3dc 100644 --- a/backend/setup.py +++ b/backend/setup.py @@ -2,7 +2,7 @@ from setuptools import setup, find_packages setup( name="edu-space-admin", - version="3.5.6", + version="3.5.7", description="Administrative interface for Edu-Space Classroom Management System", author="Edu-Space Development Team", author_email="admin@edu-space.com", diff --git a/docs/constitution.md b/docs/constitution.md index 57e4195..4c9ef3d 100644 --- a/docs/constitution.md +++ b/docs/constitution.md @@ -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]`) - **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`. -- **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]`. \ No newline at end of file +- **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": "..."}`). \ No newline at end of file diff --git a/frontend/package.json b/frontend/package.json index 8e50986..704bc59 100644 --- a/frontend/package.json +++ b/frontend/package.json @@ -1,6 +1,6 @@ { "name": "frontend", - "version": "3.5.6", + "version": "3.5.7", "description": "", "main": "index.js", "scripts": { diff --git a/frontend/src/app.js b/frontend/src/app.js index 8df9c29..0e1b697 100644 --- a/frontend/src/app.js +++ b/frontend/src/app.js @@ -85,9 +85,9 @@ const env = nunjucks.configure(path.join(__dirname, '../views'), { }); // Versiones institucionales del sistema -const APP_VERSION = '3.5.6'; -const FRONTEND_VERSION = '3.5.6'; -const BACKEND_VERSION = '3.5.6'; +const APP_VERSION = '3.5.7'; +const FRONTEND_VERSION = '3.5.7'; +const BACKEND_VERSION = '3.5.7'; env.addGlobal('app_version', APP_VERSION); env.addGlobal('frontend_version', FRONTEND_VERSION);