Añadir Requerimientos no funcionales

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.