openapi: 3.0.3
info:
  title: Eduplanner API
  description: |
    La API de Eduplanner permite a desarrolladores y sistemas externos generar contenido educativo (planeaciones, exámenes, rúbricas, presentaciones) usando inteligencia artificial, así como consultar los recursos guardados por el docente.

    ### 🔧 Cómo usar la API

    La API se divide en dos tipos de operaciones:

    | Tipo | Método | Descripción |
    |------|--------|-------------|
    | **Generación** | `POST /v1/*` | Ejecuta la generación de contenido educativo con IA |
    | **Consulta** | `GET /v1/*` | Recupera el contenido generado y almacenado del docente |

    Todas las peticiones requieren autenticación vía **Bearer token (JWT)** en el header `Authorization: Bearer <token>`.

    > Para obtener tu token, utiliza el endpoint [`POST /auth/login`](#operation/login) con tu correo y contraseña de Eduplanner.
  version: 1.0.0
  contact:
    name: Eduplanner Support
    email: soporte@plannners.com.mx
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://localhost:3000/api
    description: Servidor de desarrollo
  - url: https://edu.planners.com.mx/api
    description: Servidor de producción

paths:
  /auth/login:
    post:
      tags:
        - Autenticación
      summary: Iniciar sesión y obtener token JWT
      description: |
        Autentica al usuario con su correo y contraseña de Eduplanner y devuelve un token JWT para usar en el resto de las peticiones.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  example: docente@escuela.mx
                password:
                  type: string
                  format: password
                  example: "••••••••"
              required:
                - email
                - password
      responses:
        '200':
          description: Inicio de sesión exitoso
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    description: Token JWT para autenticación
                    example: eyJhbGciOiJIUzI1NiIs...
                  user:
                    type: object
                    properties:
                      id:
                        type: string
                      email:
                        type: string
                      name:
                        type: string
        '401':
          description: Credenciales inválidas
        '500':
          description: Error del servidor

  /v1/planeaciones:
    get:
      tags:
        - Planeaciones
      summary: Obtener listado de planeaciones didácticas
      description: Recupera la lista de planeaciones didácticas generadas por el docente autenticado, ordenadas cronológicamente.
      security:
        - BearerAuth: []
      parameters:
        - name: limit
          in: query
          description: Cantidad máxima de registros a retornar (máximo 50)
          required: false
          schema:
            type: integer
            default: 10
        - name: offset
          in: query
          description: Número de registros a omitir para paginación
          required: false
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Listado de planeaciones recuperado exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        titulo:
                          type: string
                        metodologia:
                          type: string
                        grado:
                          type: string
                        created_at:
                          type: string
                          format: date-time
                        contenido:
                          type: object
                          description: Objeto JSON con el desglose pedagógico completo
                  pagination:
                    type: object
                    properties:
                      limit:
                        type: integer
                      offset:
                        type: integer
        '401':
          description: No autorizado
        '500':
          description: Error del servidor

  /v1/seguimiento:
    post:
      tags:
        - Seguimiento
      summary: Generar sesiones de seguimiento con Inteligencia Artificial
      description: Endpoint de la versión 1 (móvil y web) para generar sesiones de seguimiento de alumnos mediante Inteligencia Artificial.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                messages:
                  type: array
                  items:
                    $ref: '#/components/schemas/ChatMessage'
                prompt:
                  type: string
                tipoSecuencia:
                  type: string
                  default: unica
                nivelDetalle:
                  type: string
                  default: detallado
                metodologia:
                  type: string
                  default: NEM
                parentContent:
                  type: string
                contexto:
                  type: object
                  properties:
                    grado:
                      type: string
                context:
                  type: object
              required:
                - prompt
      responses:
        '200':
          description: Seguimiento generado exitosamente. Si responde como stream, la cabecera X-Vercel-AI-Data-Stream indica stream de datos.
          content:
            text/plain; charset=utf-8:
              schema:
                type: string
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: string
                    description: Contenido de seguimiento generado
                  usage:
                    type: object
                    description: Metadatos de uso del motor de IA
        '401':
          description: No autorizado
        '500':
          description: Error del servidor

  /v1/examenes:
    post:
      tags:
        - Exámenes
      summary: Generar examen estructurado mediante IA
      description: Genera reactivos de examen en base a planeaciones y prompt mediante el motor de IA de Eduplanner. Puede retornar un stream o un JSON.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                prompt:
                  type: string
                titulo:
                  type: string
                planeaciones:
                  type: array
                  items:
                    type: object
                instruccionesAdicionales:
                  type: string
                numPreguntas:
                  type: integer
                  default: 10
              required:
                - prompt
      responses:
        '200':
          description: Examen generado estructurado exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    description: Reactivos estructurados del examen (preguntas, opciones, respuestas)
                  usage:
                    type: object
        '401':
          description: No autorizado
        '500':
          description: Error del servidor


    get:
      tags:
        - Exámenes
      summary: Obtener listado de exámenes generados
      description: Recupera la lista de exámenes estructurados generados por el docente autenticado.
      security:
        - BearerAuth: []
      parameters:
        - name: limit
          in: query
          description: Cantidad máxima de registros a retornar (máximo 50)
          required: false
          schema:
            type: integer
            default: 10
        - name: offset
          in: query
          description: Número de registros a omitir para paginación
          required: false
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Listado de exámenes recuperado exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        title:
                          type: string
                        created_at:
                          type: string
                          format: date-time
                        content:
                          type: object
                          description: Contenido estructurado de reactivos y opciones
                  pagination:
                    type: object
                    properties:
                      limit:
                        type: integer
                      offset:
                        type: integer
        '401':
          description: No autorizado
        '500':
          description: Error del servidor

  /v1/fichas-descriptivas:
    post:
      tags:
        - Fichas Descriptivas
      summary: Generar ficha descriptiva del alumno
      description: Genera fichas descriptivas del alumno con logros, dificultades y recomendaciones.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                nombre:
                  type: string
                grado:
                  type: string
                observacionesLogros:
                  type: string
                observacionesDificultades:
                  type: string
                observacionesRecomendaciones:
                  type: string
                calificacionesContext:
                  type: string
                asistenciaContext:
                  type: string
              required:
                - nombre
                - grado
      responses:
        '200':
          description: Ficha descriptiva generada exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    description: Objeto de la ficha descriptiva generada
                  usage:
                    type: object
        '401':
          description: No autorizado
        '500':
          description: Error del servidor

  /v1/kahoot:
    post:
      tags:
        - Kahoot
      summary: Generar reactivos para Kahoot
      description: Genera preguntas y respuestas compatibles con el formato Kahoot usando IA.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tema:
                  type: string
                prompt:
                  type: string
                numPreguntas:
                  type: integer
                  default: 10
                grado:
                  type: string
      responses:
        '200':
          description: Cuestionario generado exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    description: Preguntas estructuradas estilo Kahoot
                  usage:
                    type: object
        '401':
          description: No autorizado
        '500':
          description: Error del servidor

  /v1/rubricas:
    post:
      tags:
        - Rúbricas
      summary: Generar rúbrica de evaluación
      description: Genera una rúbrica analítica estructurada para el alumno usando IA.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tema:
                  type: string
                prompt:
                  type: string
                grado:
                  type: string
                materia:
                  type: string
      responses:
        '200':
          description: Rúbrica generada exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: string
                    description: Contenido de la rúbrica generada en texto o markdown
                  usage:
                    type: object
        '401':
          description: No autorizado
        '500':
          description: Error del servidor

  /v1/ai/execute:
    post:
      tags:
        - Chat IA
      summary: Ejecución directa en el motor de IA de Eduplanner
      description: Pasarela directa para la ejecución de peticiones de lenguaje natural en el motor de IA de Eduplanner. Puede retornar un stream (text/plain) o un JSON (application/json).
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                messages:
                  type: array
                  items:
                    $ref: '#/components/schemas/ChatMessage'
                prompt:
                  type: string
                context:
                  type: object
              required:
                - prompt
      responses:
        '200':
          description: Respuesta de ejecución del agente. Puede ser un stream (text/plain) o JSON.
          content:
            text/plain; charset=utf-8:
              schema:
                type: string
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: string
                  usage:
                    type: object
        '401':
          description: No autorizado
        '500':
          description: Error del servidor


components:
  schemas:
    Message:
      type: object
      properties:
        id:
          type: string
        user_id:
          type: string
        content:
          type: string
        type:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    ChatMessage:
      type: object
      properties:
        role:
          type: string
          enum: [user, assistant, system]
        content:
          type: string
      required:
        - role
        - content

    ExamResponse:
      type: object
      properties:
        examen_contenido:
          type: string
          description: Contenido del examen en formato Markdown
        hoja_de_respuestas:
          type: string
          description: Clave de respuestas en formato Markdown

    PlanAnaliticoCreate:
      type: object
      properties:
        nombre:
          type: string
        contexto_trabajo_id:
          type: string
        diagnostico:
          type: object
        contextualizacion:
          type: object
        codiseno:
          type: object
      required:
        - nombre
        - contexto_trabajo_id

    PlanAnalitico:
      type: object
      properties:
        id:
          type: string
        nombre:
          type: string
        user_id:
          type: string
        contexto_trabajo_id:
          type: string
        diagnostico:
          type: object
        contextualizacion:
          type: object
        codiseno:
          type: object
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    ProyectoCreate:
      type: object
      properties:
        titulo:
          type: string
        descripcion:
          type: string
        grado:
          type: string
        campo_formativo:
          type: string
        contexto_trabajo_id:
          type: string
      required:
        - titulo
        - grado

    Proyecto:
      type: object
      properties:
        id:
          type: string
        titulo:
          type: string
        descripcion:
          type: string
        grado:
          type: string
        campo_formativo:
          type: string
        user_id:
          type: string
        contexto_trabajo_id:
          type: string
        fases:
          type: array
          items:
            type: object
        created_at:
          type: string
          format: date-time

    PDA:
      type: object
      properties:
        id:
          type: string
        nombre:
          type: string
        descripcion:
          type: string
        campo_formativo:
          type: string

    Rubrica:
      type: object
      properties:
        titulo:
          type: string
        aprendizaje_esperado:
          type: string
        criterios:
          type: array
          items:
            type: object
            properties:
              nombre:
                type: string
              niveles:
                type: array
                items:
                  type: object
                  properties:
                    nivel:
                      type: string
                    descripcion:
                      type: string

    ChatLog:
      type: object
      properties:
        id:
          type: string
        user_id:
          type: string
        user_name:
          type: string
        user_email:
          type: string
        question:
          type: string
        answer:
          type: string
        created_at:
          type: string
          format: date-time
        metadata:
          type: object
          properties:
            context_docs:
              type: array
              items:
                type: string

    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string

  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Token JWT obtenido al iniciar sesión mediante `POST /auth/login`. Incluir en el header `Authorization: Bearer <token>`.

security:
  - BearerAuth: []

tags:
  - name: Autenticación
    description: Inicio de sesión y obtención de token JWT para acceder a la API
  - name: Planeaciones
    description: Consulta y obtención de planeaciones didácticas guardadas del docente
  - name: Chat IA
    description: Pasarela directa y ejecución en el motor de IA de Eduplanner
  - name: Seguimiento
    description: Registro de incidencias y generación de sesiones de seguimiento escolar
  - name: Exámenes
    description: Generación estructurada de exámenes mediante Inteligencia Artificial
  - name: Fichas Descriptivas
    description: Creación de fichas descriptivas y sugerencias pedagógicas para boletas SEP
  - name: Kahoot
    description: Gamificación y exportación estructurada de reactivos a formato Kahoot
  - name: Rúbricas
    description: Generación analítica de rúbricas e instrumentos de evaluación
