diff --git a/Requerimientos-no-funcionales.md b/Requerimientos-no-funcionales.md new file mode 100644 index 0000000..2555cda --- /dev/null +++ b/Requerimientos-no-funcionales.md @@ -0,0 +1,111 @@ +# Requerimientos no funcionales +*(lunes, 8 de diciembre de 2025, 12:02 p. m.)* + +## 1. Seguridad y cumplimiento +1. El sistema deberá proteger todas las comunicaciones (frontend-backend-Supabase-OpenAl-Carbone) usando HTTPS/TLS extremo a extremo. +2. Las API keys (OpenAl, Carbone, Supabase service role, etc.) deberán almacenarse en variables de entorno / gestor de secretos, nunca en el código ni en el cliente. +3. Toda operación sensible (crear/editar planes, materias, estados, plantillas) deberá validarse en el backend / Edge Functions, sin confiar solo en la UI. +4. El sistema deberá registrar en bitácoras quién hizo qué cambio (usuario, timestamp, entidad afectada), suficiente para auditoría interna y aclaración de controversias. +5. Deberán seguirse buenas prácticas mínimas de protección de datos personales (especialmente si hay nombres/correos de expertos y profesores): + * No exponer datos innecesarios en listados. + * Ocultar correos personales a usuarios sin privilegio. + * Logs sin información sensible en texto plano. + +## 2. Rendimiento y escalabilidad +1. La interfaz deberá cargar el tablero principal / listado de planes en un tiempo percibido razonable (por ejemplo, < 3s en condiciones normales de red académica), utilizando paginación y filtros desde el backend. +2. Las consultas intensivas (ej. lectura masiva de planes, historiales) deberán estar apoyadas en índices en Supabase y en selects específicos, no select * indiscriminados. +3. Las llamadas a IA (OpenAI) y generación de documentos (Carbone) deberán implementarse como acciones asíncronas con feedback visual (loading, "pensando...") para no bloquear la UI. +4. El sistema deberá escalar horizontalmente de forma natural con Supabase/TanStack Query (cache, revalidación, lazy loading), sin dependencias en memoria local del servidor. + +## 3. Confiabilidad, disponibilidad y tolerancia a fallos +1. El sistema deberá manejar errores de servicios externos (OpenAl, Carbone, API de biblioteca) de forma controlada: + * Mensajes claros al usuario. + * Reintentos cuando tenga sentido. + * No pérdida de los datos capturados en formularios. +2. En caso de falla al generar un plan con IA, el sistema deberá conservar el prompt y parámetros enviados para poder reintentar sin reescribir todo. +3. La generación de documentos (Carbone) deberá ser idempotente: volver a generar el mismo documento no debe corromper datos ni estados. +4. Las Edge Functions deberán tener manejo explícito de timeouts y límites (tokens, tamaño de archivos, etc.) para evitar bloqueos. + +## 4. Usabilidad y experiencia de usuario +1. La Ul deberá estar diseñada para que un jefe de carrera / profesor no técnico pueda: + * Entender dónde está en el flujo del plan. + * Editar secciones sin ver JSON. + * Invocar IA con botones claros tipo "Generar borrador" / "Mejorar texto". +2. La interfaz deberá usar componentes consistentes (Shadcn + Tailwind) y un layout estable (sidebar, header, contenido) para reducir la curva de aprendizaje. +3. Las interacciones con IA deberán tener feedback visual: + * Estado "pensando" (animaciones sutiles tipo "IA respirando"). + * Claridad de cuándo llegó la respuesta y qué cambió. + * No abusar de animaciones que entorpezcan formularios. +4. Los efectos visuales "wow" (confetis al generar plan, degradados vivos, etc.) deberán ser opcionales y no bloquear la acción principal ni afectar el rendimiento. +5. Los mensajes de error deberán ser explicativos ("No se pudo generar el documento, el servicio externo tardó demasiado...") y no genéricos tipo "Error 500". +6. Al realizar acciones de modificación, se debe pedir confirmación al usuario, especialmente si son destructivas. + +## 5. Mantenibilidad y arquitectura +1. La lógica de negocio deberá residir en: + * Backend/ Edge Functions (validaciones, llamadas a IA, Carbone, integraciones). + * No en componentes de React dispersos. +2. El frontend deberá aplicar un patrón de separación de responsabilidades: + * Componentes de presentación (UI). + * Hooks/servicios de datos (TanStack Query, llamadas a API). + * Mínima lógica en el JSX. +3. El sistema deberá incluir al menos: + * Estándares de estilo (ESLint/Prettier) + * Tipado con TypeScript + * Nombres de tablas y campos coherentes. +4. Debe existir una capa clara para hablar con OpenAl (una especie de "IA service") que unifique: + * Cómo se construyen los prompts. + * Cómo se manejan Vector Stores/uploads/ MCP. + * Cómo se recuperan y validan respuestas estructuradas. +5. Se deberá evitar el acoplamiento fuerte entre estructura de BD y estructura SEP para permitir ajustes futuros (nuevas plantillas, nuevos campos). + +## 6. Trazabilidad y auditoría de cambios +1. El sistema deberá registrar cada cambio relevante en planes y materias: + * Quién lo hizo. + * Qué se cambió (antes/después, al menos por secciones). + * Cuándo ocurrió. +2. Los archivos usados como referencia (subidos por usuario o IA) deberán quedar almacenados en Supabase Storage o repositorio equivalente, asociados al plan / materia. +3. Las interacciones importantes con IA deberán registrarse: + * Prompt (o versión anonimizada si aplica). + * Fuentes usadas (vector store, uploads, MCP, etc.). + * Resultado aplicado / rechazado. +4. La plataforma deberá permitir reconstruir "cómo llegamos" a la versión actual de un plan: cadena de versiones + archivos + decisiones de IA aceptadas. + +## 7. Concurrencia y edición simultánea +1. El sistema deberá evitar, como mínimo, pérdida silenciosa de cambios cuando dos usuarios editen el mismo plan: + * Estrategia simple: versión/timestamp y rechazo de actualización si la versión cambió. + * Mensaje al usuario indicando que alguien más modificó el plan. +2. Opcional/Más adelante: el sistema podrá mostrar una advertencia de edición concurrente ("El usuario X está editando este plan ahora"), aunque no llegue a nivel Canva con cursores en tiempo real. +3. Los formularios largos deberán guardar datos intermedios o permitir guardado parcial, para evitar perder trabajo por cierre de sesión o errores de red. En cookies o local storage + +## 8. Integración, portabilidad y flexibilidad +1. El sistema deberá ser capaz de soportar cambios en lineamientos SEP mediante: + * Configuración de diferentes "plantillas de estructura de plan". + * No depender de un único modelo rígido hardcodeado. +2. La integración con la API de biblioteca deberá estar desacoplada (adaptador) para poder cambiar la implementación sin reescribir toda la lógica de materias. +3. La gestión de usuarios externos (expertos) deberá permitir, al menos: + * Invitar vía link firmade/token-e cuenta ligera. + * Restringir lo que pueden ver/editar/comentar sin tocar toda la arquitectura de auth. + +## 9. Observabilidad, monitoreo y métricas +1. El sistema deberá registrar logs de: + * Errores de frontend (captura básica). + * Errores de Edge Functions. + * Fallos de OpenAI / Carbone / APIs externas. +2. Deberán existir métricas mínimas: + * Número de planes creados/actualizados. + * Latencia promedio de llamadas a IA. + * Tasa de errores por módulo. +3. El equipo deberá poder identificar cuellos de botella (por ejemplo, generación de PDF muy lenta) a partir de estos logs/métricas y priorizar mejoras. + +## 10. Documentación y operación +1. Deberá existir documentación básica y actualizada sobre: + * Arquitectura general (frontend, backend, Supabase, IA, Carbone). + * Flujo de despliegue (cómo se sube una nueva versión). + * Cómo agregar un nuevo template de plan / materia. +2. Las Edge Functions y módulos de IA deberán estar documentados con: + * Inputs esperados (JSON). + * Esquemas de salida. + * Manejo de errores típico. +3. Deberá existir una guía corta para usuarios clave (jefes de carrera, secretarios académicos) explicando: + * Cómo crear/editar/mandar a aprobación un plan. + * Cómo usar las funciones de IA de forma segura y responsable. \ No newline at end of file