Añadir Requerimientos Funcionales

Requerimientos-Funcionales.md

@@ -0,0 +1,195 @@
+# Requerimientos funcionales
+*(lunes, 8 de diciembre de 2025, 12:00 p. m.)*
+
+## 1. Gestión de usuarios, roles y permisos 👥
+1. El sistema debe permitir autenticación de usuarios internos (SSO / clave ultra y contraseña) y externos (correo + contraseña, por ahora vía Supabase Auth).
+2. El sistema debe manejar roles mínimos:
+   * Vicerrectoría académica
+   * Dirección de facultad
+   * Secretario académico
+   * Jefe de carrera
+   * Coordinación de Desarrollo Humano Profesional
+   * Planeación Curricular/biblioteca
+   * Profesor experto de materia
+   * Usuario invitado / experto externo (solo lectura o comentarios)
+3. El sistema debe permitir definir permisos por rol sobre un plan de estudios:
+   * Ver plan
+   * Editar contenidos de plan
+   * Editar solo ciertas secciones (ej. profesor solo su materia)
+   * Comentar/ sugerir cambios
+   * Aprobar/rechazar en cierta fase del flujo
+4. El sistema debe permitir que, para cada plan de estudios concreto, se puedan definir: 
+   * El administrador y el secretario académico pueden definir un responsable de plan de estudios.
+   * Quiénes son profesores responsables de cada materia
+   * Qué usuarios pueden participar en cada fase del flujo de aprobación.
+
+## 2. Modelo académico y estructura de datos
+1. El sistema debe representar la jerarquía académica mínima:
+   * Universidad
+   * Facultades / Direcciones
+   * Carreras (programas académicos)
+   * Planes de estudio
+   * Materias
+2. El sistema debe permitir que las materias puedan ser compartidas entre planes y facultades (no solo anidadas rígidamente a una carrera).
+3. El sistema debe soportar un modelo flexible de mapa curricular mediante JSON, incluyendo:
+   * Tipo de ciclo (semestre/cuatrimestre/trimestre/etc.)
+   * Número de ciclos
+   * Áreas (tronco común, profesionalizante, optativas, etc.)
+   * Líneas curriculares dentro de cada área
+   * Lista de materias asignadas a cada línea/ciclo (con carga horaria, créditos, seriación, etc.).
+4. El sistema debe permitir manejar materias "propietarias" por unidad (ej. Ciencias Básicas, Desarrollo Humano Profesional) que se puedan propagar a múltiples planes. Área básica y desarrollo humano profesional son su propia facultad pues deben de gestionar sus materias independientemente de los demás.
+5. El sistema debe soportar que una materia tenga:
+   * Objetivos
+   * Contenidos temáticos (temas/subtemas)
+   * Perfil de la materia (qué aporta al perfil de egreso)
+   * Bibliografía básica y complementaria
+   * Forma de evaluación (porcentajes, criterios)
+   * Requisitos (seriación, prerequisitos)
+   * Vínculos a líneas curriculares / áreas del plan.
+
+## 3. Ciclo de vida del plan de estudios y flujo de trabajo
+1. El sistema debe permitir crear un nuevo plan de estudios a partir de:
+   * ~~Una carrera existente~~
+   * Se debe de permitir la importación de un plan de estudios ya aprobado. Implementar un wizard para importación ordenada del plan y sus documentos.
+   * Un plan previo (clonado)
+   * Cero (nuevo programa). Campus virtual gestiona cursos sin RVOE.
+2. El sistema debe permitir registrar el origen de la detonación del cambio/creación:
+   * Coordinación de Desarrollo Humano Profesional (cambio en sus materias)
+   * Facultad/carrera (por análisis de mercado)
+   * Otro (campo libre con descripción)
+3. El plan debe tener un estado en su ciclo de vida, por ejemplo:
+   * Borrador del jefe de carrera
+   * En revisión de secretario académico
+   * En revisión de Planeación Curricular
+   * En consulta con expertos externos
+   * En revisión de otras sedes
+   * En Consejo Académico de Facultad
+   * En Consejo Universitario
+   * En Junta de Gobierno (si aplica)
+   * Enviado a SEP
+   * Aprobado SEP
+   * Rechazado en X fase
+4. El sistema debe permitir configurar y avanzar de estado manualmente (por ahora):
+   * Solo usuarios con permiso correspondiente pueden cambiar el estado.
+   * Cada cambio de estado debe quedar registrado (quién, cuándo, comentarios).
+5. El sistema debe permitir adjuntar comentarios y observaciones por fase:
+   * Comentarios del secretario académico
+   * Comentarios de Planeación Curricular
+   * Comentarios de expertos externos
+   * Comentarios de otras sedes
+   * Comentarios de consejo de facultad / universitario.
+6. El sistema debe permitir registrar "expertos":
+   * Agregar expertos (nombre, institución, contacto)
+   * Registrar su dictamen/comentarios por materia.
+7. El sistema debe permitir invitar a sedes hermanas. Tienen rol de expertos.
+
+## 4. Gestión y versionado de planes y materias
+1. El sistema debe mantener un histórico de versiones del plan de estudios:
+   * Cada cambio importante (estructura, mapa curricular, objetivos, etc.) genera una versión.
+   * Se debe poder consultar versiones anteriores y comparar campos clave.
+2. El sistema debe mantener un histórico de cambios por materia:
+   * Quién editó, qué campos cambió y cuándo.
+   * Idealmente agrupado por "revisión" o "entrega", no solo por fila de tabla.
+3. El sistema debe permitir duplicar/clonar:
+   * Planes completos (para crear una revisión nueva)
+   * Materias (por ejemplo, variantes para otra carrera o sede).
+4. El sistema debe permitir marcar planes como "vigentes" o "en transición":
+   * Vigente (ya en operación)
+   * En revisión (nuevo)
+   * Obsoleto (solo histórico)
+   * Rechazado
+
+## 5. Módulo de IA: generación y edición de planes
+### 5.1 Generación inicial
+1. El sistema debe permitir al jefe de carrera o usuario autorizado generar un plan de estudios con IA mediante:
+   * Un formulario/resumen donde describa el tipo de carrera, nivel, duración, enfoque, etc. Opcionalmente: adjuntar archivos de referencia (SEP, tendencias de mercado, documentos internos).
+2. El sistema debe enviar a la IA:
+   * Prompt base estructurado (formato SEP / institucional)
+   * Parámetros de modelo (modelo, temperatura, etc.)
+   * Archivos de referencia relevantes (subidos o desde vector store)
+   * Opcionalmente datos de la BD a través de MCP (para "inspirarse" en planes existentes).
+3. El sistema debe recibir un plan de estudios estructurado (JSON) desde la IA y:
+   * Guardarlo en la tabla de planes (objetivos, perfil de ingreso/egreso, mapa curricular, etc.)
+   * Asociar las materias generadas (como borradores) a ese plan.
+   * Marcarlo como "Borrador generado por IA" en el histórico del plan.
+4. El sistema debe permitir generar solo el mapa curricular, a partir de:
+   * Información básica de la carrera
+   * Líneas curriculares que el usuario indique
+   * Duración (n ciclos)
+   * Y devolverlo como estructura JSON directamente editable.
+
+### 5.2 Edición y mejora con IA
+1. El sistema debe permitir seleccionar un plan de estudios existente y:
+   * Pedir a la IA que lo revise/mejore con base en lineamientos (SEP, taxonomía de Bloom, verbos en infinitivo, etc.).
+   * Mostrar una propuesta de cambios antes de aplicarlos.
+2. El sistema debe permitir un chat contextual con el plan:
+   * Preguntar: "¿Dónde estoy débil en IA comparado con otras ingenierías?"
+   * "¿Qué líneas curriculares tengo más cargadas en los primeros semestres?"
+   * El backend, vía MCP, consulta Supabase y responde con datos + análisis de IA.
+   * El MCP debe ser de solo lectura.
+   * Debe de estar oculto para el usuario el uso de MCP.
+3. El sistema debe permitir edición puntual con IA de secciones de texto:
+   * Mejorar redacción de objetivos.
+   * Ajustar a formato SEP / institucional.
+   * Ajustar nivel de complejidad según taxonomía de Bloom (recordar/comprender/aplicar...).
+4. El sistema debe permitir usar IA para generar o mejorar una materia individual:
+   * Describir la materia (nombre, créditos, en qué semestre va, prerequisitos).
+   * Adjuntar bibliografía o tendencias.
+   * Recibir: objetivos, temario, evaluación, bibliografía propuesta.
+
+### 5.3 Manejo de referencias y archivos (IA)
+1. El sistema debe permitir subir archivos como referencia puntual a una sola petición de IA (uploads "temporales").
+2. Planeación curricular puede gestionar repositorios que serán públicos para otros usuarios de planeación curricular para su gestión, y a jefes de carrera para uso como referencia.
+3. El jefe de carrera puede gestionar y usar como referencia sus propios repositorios, que son privados.
+4. El sistema debe permitir que el usuario seleccione, al hacer una petición a IA:
+   * Qué fuentes usar:
+   * Archivos puntuales
+   * Vector Store(s)
+   * Base de datos vía MCP (contexto)
+   * Conversación previa.
+
+## 6. Plantillas y generación de documentos oficiales
+1. El sistema debe permitir configurar plantillas de documentos por tipo:
+   * Formato SEP para registro/modificación de plan.
+   * Formato interno de facultad (por ejemplo, documento para Consejo Académico).
+   * Formato para Junta de Gobierno (si es distinto).
+2. El sistema debe integrarse con Carbone.io para:
+   * Tomar un JSON estructurado del plan.
+   * Inyectarlo en la plantilla.
+   * Generar un documento descargable (DOCX/PDF).
+3. El sistema debe permitir que el usuario:
+   * Seleccione el plan y la plantilla.
+   * Genere el documento.
+   * Lo descargue desde la interfaz.
+4. El sistema debe permitir previsualizar el documento generado (como "document viewer" estilo PDF en el navegador) antes de descarga.
+
+## 7. Notificaciones y seguimiento
+1. El sistema debe enviar notificaciones internas (y luego email) cuando:
+   * Se le asigna a un usuario responsabilidad sobre un plan o materia.
+   * El plan cambia de etapa y requiere su acción (ej. "tienes un plan en revisión pendiente").
+   * Un experto externo entrega sus comentarios.
+   * Una sede externa agrega observaciones.
+2. El sistema debe proporcionar una vista de tablero por usuario:
+   * Planes en los que participa.
+   * Tareas pendientes (revisar, comentar, aprobar).
+   * Estado actual del plan (semáforo o timeline simple).
+
+## 8. Integraciones y datos externos
+1. El sistema debe permitir consultar datos de biblioteca (cuando la API esté lista) para:
+   * Proponer bibliografía para una materia.
+   * Verificar disponibilidad de títulos (básico: nombre y autor).
+2. El sistema debe permitir configurar múltiples estructuras de plan (por si cambian lineamientos SEP) sin romper la base:
+   * Definir "plantillas de estructura" (qué campos y secciones tiene un plan).
+   * Asociar cada plan a una plantilla de estructura determinada.
+
+## 9. Usabilidad y experiencia de los no-técnicos
+1. El sistema debe permitir a jefes de carrera y profesores editar planes y materias en formularios amigables, sin necesidad de pensar en JSON:
+   * Formularios guiados (secciones: objetivos, perfil, contenidos, etc.).
+   * Ayudas contextuales ("tip" sobre verbos de Bloom, etc.).
+2. El sistema debe ocultar la complejidad técnica de IA:
+   * Ofrecer presets como "Generar borrador", "Mejorar redacción", "Alinear a SEP".
+   * Los parámetros técnicos (modelo, temperatura) se configuran solo en un panel de admin.
+3. El sistema debe ofrecer historial de IA por plan:
+   * Qué prompts se usaron.
+   * Qué respuestas se aceptaron y aplicaron.
+   * Para rastrear cómo llegó a la versión actual.