Guillermo.Arrieta/acad-ia-2
1
0
Fork 0
Code Issues 13 Pull Requests Actions Wiki Activity
Page: Requerimientos no funcionales
Pages
Automatización Requerimientos Funcionales Requerimientos no funcionales Vistas de Lovable
Clone
3
Requerimientos no funcionales
Guillermo.Arrieta edited this page 2026-02-26 18:50:43 +00:00
Table of Contents

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.