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 |

    Las peticiones protegidas usan **Bearer** en `Authorization: Bearer <token>` o **API key** en `x-api-key`, según el endpoint. Las rutas familiares usan un token de sesión familiar firmado que se obtiene en `POST /v1/familias/login`; no es el JWT de Supabase para personal.

    > El personal puede autenticarse con el flujo institucional correspondiente; las familias usan `POST /v1/familias/login`. Para una API key de integración, contacta al administrador del plantel.

    ### 📄 Paginación

    Los endpoints de listado aceptan `?limit=` (1-100, default 50) y `?offset=` (0-based) y devuelven
    `pagination: { limit, offset, has_more }` junto a `data`. `has_more` es un indicio: si recibes
    justo `limit` elementos, pide la siguiente página con `offset += limit`.

    ### 🔀 CORS / preflight

    Las rutas `/api/*` incluyen cabeceras CORS y responden `OPTIONS` (preflight) con `204`, así que
    también se pueden consumir desde clientes web.
  version: 1.0.0
  contact:
    name: Eduplanner Support
    email: soporte@planners.com.mx
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

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

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: []
        - ApiKeyAuth: []
      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
    post:
      tags:
        - Planeaciones
      summary: Generar planeación didáctica con IA
      description: Genera una planeación didáctica completa usando inteligencia artificial (NEM, CIME o Tutoría). Incluye integración con libros SEP para referencias curriculares.
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                prompt:
                  type: string
                  description: Descripción del tema o contenido a planificar
                metodologia:
                  type: string
                  enum: [NEM, CIME, Tutoría]
                  default: NEM
                nivelDetalle:
                  type: string
                  enum: [estándar, avanzado]
                  default: estándar
                numSesiones:
                  type: integer
                  default: 1
                grado:
                  type: string
                materia:
                  type: string
                contenidos_relacionados:
                  type: array
                  items:
                    type: string
                  description: IDs de contenidos curriculares relacionados
              required:
                - prompt
      responses:
        '200':
          description: Planeación generada y guardada exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    description: Planeación guardada en la base de datos
                  generated:
                    type: object
                    description: Contenido completo generado por IA
                  usage:
                    type: object
        '401':
          description: No autorizado
        '500':
          description: Error del servidor

  /v1/planeaciones/{id}:
    get:
      tags:
        - Planeaciones
      summary: Obtener una planeación específica
      description: Recupera los detalles de una planeación específica por su ID.
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Planeación encontrada
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
        '401':
          description: No autorizado
        '404':
          description: Planeación no encontrada
    put:
      tags:
        - Planeaciones
      summary: Actualizar una planeación
      description: Actualiza los datos de una planeación existente.
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                titulo:
                  type: string
                materia:
                  type: string
                grado:
                  type: string
                duracion:
                  type: string
                objetivo:
                  type: string
                contenido:
                  type: object
                estado:
                  type: string
                  enum: [borrador, completada, archivada]
      responses:
        '200':
          description: Planeación actualizada exitosamente
        '401':
          description: No autorizado
        '404':
          description: Planeación no encontrada
    delete:
      tags:
        - Planeaciones
      summary: Eliminar una planeación
      description: Elimina una planeación existente.
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Planeación eliminada exitosamente
        '401':
          description: No autorizado
        '404':
          description: Planeación no encontrada

  /v1/seguimiento:
    get:
      tags:
        - Seguimiento
      summary: Obtener listado de seguimientos
      description: Recupera la lista de seguimientos diarios del docente autenticado.
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      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
        - name: alumno_id
          in: query
          description: Filtrar por ID de alumno
          required: false
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Listado de seguimientos recuperado exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        alumno_id:
                          type: string
                        fecha:
                          type: string
                          format: date
                        nota:
                          type: string
                        tipo:
                          type: string
                        created_at:
                          type: string
                          format: date-time
                  pagination:
                    type: object
                    properties:
                      limit:
                        type: integer
                      offset:
                        type: integer
        '401':
          description: No autorizado
        '500':
          description: Error del servidor
    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: []
        - ApiKeyAuth: []
      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/seguimiento/{id}:
    get:
      tags:
        - Seguimiento
      summary: Obtener un seguimiento específico
      description: Recupera los detalles de un seguimiento específico por su ID.
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Seguimiento encontrado
        '401':
          description: No autorizado
        '404':
          description: Seguimiento no encontrado
    put:
      tags:
        - Seguimiento
      summary: Actualizar un seguimiento
      description: Actualiza los datos de un seguimiento existente.
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                nota:
                  type: string
                tipo:
                  type: string
                  enum: [general, academico, comportamiento, logro, contacto_familia]
                fecha:
                  type: string
                  format: date
      responses:
        '200':
          description: Seguimiento actualizado exitosamente
        '401':
          description: No autorizado
        '404':
          description: Seguimiento no encontrado
    delete:
      tags:
        - Seguimiento
      summary: Eliminar un seguimiento
      description: Elimina un seguimiento existente.
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Seguimiento eliminado exitosamente
        '401':
          description: No autorizado
        '404':
          description: Seguimiento no encontrado

  /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: []
        - ApiKeyAuth: []
      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: []
        - ApiKeyAuth: []
      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/examenes/{id}:
    get:
      tags:
        - Exámenes
      summary: Obtener un examen específico
      description: Recupera los detalles de un examen específico por su ID.
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Examen encontrado
        '401':
          description: No autorizado
        '404':
          description: Examen no encontrado
    put:
      tags:
        - Exámenes
      summary: Actualizar un examen
      description: Actualiza los datos de un examen existente.
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                subject:
                  type: string
                content:
                  type: object
                is_public:
                  type: boolean
                shared_with:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Examen actualizado exitosamente
        '401':
          description: No autorizado
        '404':
          description: Examen no encontrado
    delete:
      tags:
        - Exámenes
      summary: Eliminar un examen
      description: Elimina un examen existente.
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Examen eliminado exitosamente
        '401':
          description: No autorizado
        '404':
          description: Examen no encontrado

  /v1/fichas-descriptivas:
    get:
      tags:
        - Fichas Descriptivas
      summary: Obtener listado de fichas descriptivas
      description: Recupera la lista de fichas descriptivas del docente autenticado.
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      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 fichas recuperado exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        alumno_id:
                          type: string
                        estado_promocion:
                          type: string
                        logros:
                          type: string
                        dificultades:
                          type: string
                        recomendaciones:
                          type: string
                        created_at:
                          type: string
                          format: date-time
                  pagination:
                    type: object
                    properties:
                      limit:
                        type: integer
                      offset:
                        type: integer
        '401':
          description: No autorizado
        '500':
          description: Error del servidor
    post:
      tags:
        - Fichas Descriptivas
      summary: Generar ficha descriptiva del alumno
      description: Genera fichas descriptivas del alumno con logros, dificultades y recomendaciones.
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      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/fichas-descriptivas/{id}:
    get:
      tags:
        - Fichas Descriptivas
      summary: Obtener una ficha descriptiva específica
      description: Recupera los detalles de una ficha descriptiva específica por su ID.
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Ficha descriptiva encontrada
        '401':
          description: No autorizado
        '404':
          description: Ficha no encontrada
    put:
      tags:
        - Fichas Descriptivas
      summary: Actualizar una ficha descriptiva
      description: Actualiza los datos de una ficha descriptiva existente.
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                estado_promocion:
                  type: string
                  enum: [promovido, condicionado, no_promovido]
                logros:
                  type: string
                dificultades:
                  type: string
                recomendaciones:
                  type: string
      responses:
        '200':
          description: Ficha descriptiva actualizada exitosamente
        '401':
          description: No autorizado
        '404':
          description: Ficha no encontrada
    delete:
      tags:
        - Fichas Descriptivas
      summary: Eliminar una ficha descriptiva
      description: Elimina una ficha descriptiva existente.
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Ficha descriptiva eliminada exitosamente
        '401':
          description: No autorizado
        '404':
          description: Ficha no encontrada

  /v1/kahoot:
    get:
      tags:
        - Kahoot
      summary: Obtener listado de cuestionarios Kahoot
      description: Recupera la lista de cuestionarios Kahoot generados por el docente autenticado.
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      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 Kahoot recuperado exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        titulo:
                          type: string
                        tema:
                          type: string
                        created_at:
                          type: string
                          format: date-time
                  pagination:
                    type: object
                    properties:
                      limit:
                        type: integer
                      offset:
                        type: integer
        '401':
          description: No autorizado
        '500':
          description: Error del servidor
    post:
      tags:
        - Kahoot
      summary: Generar reactivos para Kahoot
      description: Genera preguntas y respuestas compatibles con el formato Kahoot usando IA.
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      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/kahoot/{id}:
    get:
      tags:
        - Kahoot
      summary: Obtener un cuestionario Kahoot específico
      description: Recupera los detalles de un cuestionario Kahoot específico por su ID.
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Kahoot encontrado
        '401':
          description: No autorizado
        '404':
          description: Kahoot no encontrado
    put:
      tags:
        - Kahoot
      summary: Actualizar un cuestionario Kahoot
      description: Actualiza los datos de un cuestionario Kahoot existente.
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                titulo:
                  type: string
                tema:
                  type: string
                contenido:
                  type: object
      responses:
        '200':
          description: Kahoot actualizado exitosamente
        '401':
          description: No autorizado
        '404':
          description: Kahoot no encontrado
    delete:
      tags:
        - Kahoot
      summary: Eliminar un cuestionario Kahoot
      description: Elimina un cuestionario Kahoot existente.
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Kahoot eliminado exitosamente
        '401':
          description: No autorizado
        '404':
          description: Kahoot no encontrado

  /v1/rubricas:
    get:
      tags:
        - Rúbricas
      summary: Obtener listado de rúbricas
      description: Recupera la lista de rúbricas generadas por el docente autenticado.
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      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 rúbricas recuperado exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        titulo:
                          type: string
                        tema:
                          type: string
                        created_at:
                          type: string
                          format: date-time
                  pagination:
                    type: object
                    properties:
                      limit:
                        type: integer
                      offset:
                        type: integer
        '401':
          description: No autorizado
        '500':
          description: Error del servidor
    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: []
        - ApiKeyAuth: []
      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/rubricas/{id}:
    get:
      tags:
        - Rúbricas
      summary: Obtener una rúbrica específica
      description: Recupera los detalles de una rúbrica específica por su ID.
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Rúbrica encontrada
        '401':
          description: No autorizado
        '404':
          description: Rúbrica no encontrada
    put:
      tags:
        - Rúbricas
      summary: Actualizar una rúbrica
      description: Actualiza los datos de una rúbrica existente.
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                titulo:
                  type: string
                tema:
                  type: string
                contenido:
                  type: object
      responses:
        '200':
          description: Rúbrica actualizada exitosamente
        '401':
          description: No autorizado
        '404':
          description: Rúbrica no encontrada
    delete:
      tags:
        - Rúbricas
      summary: Eliminar una rúbrica
      description: Elimina una rúbrica existente.
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Rúbrica eliminada exitosamente
        '401':
          description: No autorizado
        '404':
          description: Rúbrica no encontrada

  /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: []
        - ApiKeyAuth: []
      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

  /v1/credits:
    get:
      tags:
        - Créditos
      summary: Consultar saldo de créditos
      description: Devuelve el saldo de créditos del usuario autenticado (créditos mensuales, comprados y total).
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      responses:
        '200':
          description: Saldo de créditos consultado exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      monthly_credits:
                        type: integer
                      purchased_credits:
                        type: integer
                      total:
                        type: integer
                      subscription_plan:
                        type: string
        '401':
          description: No autorizado
        '500':
          description: Error del servidor

  /v1/familias/login:
    post:
      tags:
        - Familias
      summary: Iniciar sesión de padre/tutor y obtener token
      description: |
        Autentica a un padre, madre o tutor con su correo y contraseña del Portal de Familias y devuelve un token Bearer para usar en el resto de las peticiones de la API familiar (portal web y app móvil).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  example: tutor@correo.com
                password:
                  type: string
                  format: password
                  example: "••••••••"
              required:
                - email
                - password
      responses:
        '200':
          description: Inicio de sesión exitoso
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      token:
                        type: string
                        description: Token Bearer para autenticación
                        example: 3f2a1b9c-...-0d.1730000000000.9f8e7d
                      tokenType:
                        type: string
                        example: Bearer
                      expiresIn:
                        type: integer
                        description: Vigencia del token en segundos
                        example: 2592000
                      parent:
                        type: object
                        properties:
                          id:
                            type: string
                          nombre_completo:
                            type: string
                          email:
                            type: string
                          estado_acceso:
                            type: string
                            enum: [activo, invitado, sin_activar, pendiente]
        '400':
          description: Datos incompletos
        '401':
          description: Credenciales inválidas
        '500':
          description: Error del servidor

  /v1/familias/me:
    get:
      tags:
        - Familias
      summary: Obtener perfil familiar y alumnos vinculados
      description: Devuelve los datos del tutor autenticado, su plantel y los alumnos vinculados a su cuenta.
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Perfil familiar
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      parent:
                        type: object
                        properties:
                          id:
                            type: string
                          nombre_completo:
                            type: string
                          email:
                            type: string
                          estado_acceso:
                            type: string
                      plantel:
                        type: object
                        nullable: true
                        properties:
                          id:
                            type: string
                          nombre:
                            type: string
                          logo_url:
                            type: string
                            nullable: true
                          familias_config:
                            type: object
                            nullable: true
                      students:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            nombre_completo:
                              type: string
                            numero_lista:
                              type: integer
                              nullable: true
                            grupo:
                              type: object
                              nullable: true
                              properties:
                                nombre:
                                  type: string
                                grado:
                                  type: string
                                  nullable: true
                                ciclo_escolar:
                                  type: string
                                  nullable: true
        '401':
          description: No autorizado (token ausente o inválido)
        '500':
          description: Error del servidor

  /v1/familias/alumnos/{id}/asistencia:
    get:
      tags:
        - Familias
      summary: Historial de asistencia de un alumno vinculado
      description: |
        Devuelve el resumen y el historial de asistencia del alumno, solo si está vinculado al tutor autenticado.
        Si el alumno no existe o pertenece a otra familia, responde 404 (no revela si el alumno existe).
        Las observaciones internas del docente (`notas`) no se exponen.
        `porcentaje` cuenta `presente` y `retardo` como asistencia válida; es `null` si no hay registros.
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: ID del alumno
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Asistencia del alumno
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      alumno:
                        type: object
                        properties:
                          id:
                            type: string
                          nombre_completo:
                            type: string
                          numero_lista:
                            type: integer
                            nullable: true
                          grupo:
                            type: object
                            nullable: true
                            properties:
                              nombre:
                                type: string
                              grado:
                                type: string
                                nullable: true
                              ciclo_escolar:
                                type: string
                                nullable: true
                      resumen:
                        type: object
                        properties:
                          total:
                            type: integer
                          presentes:
                            type: integer
                          ausentes:
                            type: integer
                          retardos:
                            type: integer
                          justificados:
                            type: integer
                          porcentaje:
                            type: integer
                            nullable: true
                      registros:
                        type: array
                        items:
                          type: object
                          properties:
                            fecha:
                              type: string
                              format: date
                            estado:
                              type: string
                              enum: [presente, ausente, retardo, justificado]
        '401':
          description: No autorizado (token ausente o inválido)
        '404':
          description: Alumno no encontrado o no vinculado a la cuenta
        '500':
          description: Error del servidor

  /v1/familias/alumnos/{id}/calificaciones:
    get:
      tags:
        - Familias
      summary: Calificaciones de boleta de un alumno vinculado
      description: |
        Devuelve las calificaciones del alumno agrupadas por trimestre, con promedio por trimestre.
        Solo si está vinculado al tutor autenticado (404 en caso contrario).
        La exposición depende de que la escuela habilite el módulo de calificaciones para familias.
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: ID del alumno
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Calificaciones del alumno
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      alumno:
                        type: object
                        properties:
                          id:
                            type: string
                          nombre_completo:
                            type: string
                          numero_lista:
                            type: integer
                            nullable: true
                          grupo:
                            type: object
                            nullable: true
                            properties:
                              id:
                                type: string
                              nombre:
                                type: string
                              grado:
                                type: string
                                nullable: true
                              ciclo_escolar:
                                type: string
                                nullable: true
                      trimestres:
                        type: array
                        items:
                          type: object
                          properties:
                            trimestre:
                              type: integer
                            promedio:
                              type: integer
                              nullable: true
                            materias:
                              type: array
                              items:
                                type: object
                                properties:
                                  campo_formativo:
                                    type: string
                                  calificacion:
                                    type: integer
                                    nullable: true
                                  observaciones:
                                    type: string
                                    nullable: true
        '401':
          description: No autorizado (token ausente o inválido)
        '404':
          description: Alumno no encontrado o no vinculado a la cuenta
        '500':
          description: Error del servidor

  /v1/familias/avisos:
    get:
      tags:
        - Familias
      summary: Avisos del plantel visibles para la familia
      description: |
        Devuelve los comunicados activos del plantel del tutor autenticado, ordenados por fijados y fecha.
        Solo incluye avisos vigentes (rango de fechas), excluye los dirigidos exclusivamente a docentes y,
        si el aviso está dirigido a un grupo, solo se devuelve cuando la familia tiene un alumno en ese grupo.
        El contenido no incluye los metadatos internos de segmentación.
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Lista de avisos
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        titulo:
                          type: string
                        contenido:
                          type: string
                        tipo:
                          type: string
                          enum: [normal, urgente, informativo]
                        fijado:
                          type: boolean
                        leido:
                          type: boolean
                          description: Si la familia ya confirmó la lectura de este aviso
                        publicado_en:
                          type: string
                          format: date-time
                        vigente_hasta:
                          type: string
                          format: date-time
                          nullable: true
        '401':
          description: No autorizado (token ausente o inválido)
        '500':
          description: Error del servidor

  /v1/familias/avisos/{id}/leido:
    post:
      tags:
        - Familias
      summary: Confirmar lectura de un aviso
      description: |
        Registra que la familia autenticada leyó el aviso. Valida que el aviso pertenezca
        al plantel del tutor y le sea visible antes de registrar la lectura. Es idempotente.
        Responde 404 si el aviso no existe o no es visible para la cuenta (no revela su existencia).
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: ID del aviso
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Lectura registrada
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      leido:
                        type: boolean
                        example: true
        '401':
          description: No autorizado (token ausente o inválido)
        '404':
          description: Aviso no encontrado o no visible para la cuenta
        '500':
          description: Error del servidor

  /v1/familias/alumnos/{id}/tareas:
    get:
      tags:
        - Familias
      summary: Tareas y actividades del grupo de un alumno vinculado
      description: |
        Devuelve las tareas/actividades evaluables del grupo del alumno, con su calificación
        y retroalimentación, clasificadas en `pendientes`, `vencidas` y `calificadas`.
        Excluye actividades eliminadas. Solo si el alumno está vinculado al tutor (404 en caso contrario).
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: ID del alumno
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Tareas del alumno
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      alumno:
                        type: object
                        properties:
                          id:
                            type: string
                          nombre_completo:
                            type: string
                          numero_lista:
                            type: integer
                            nullable: true
                          grupo:
                            type: object
                            nullable: true
                            properties:
                              id:
                                type: string
                              nombre:
                                type: string
                              grado:
                                type: string
                                nullable: true
                              ciclo_escolar:
                                type: string
                                nullable: true
                      pendientes:
                        type: array
                        items:
                          $ref: '#/components/schemas/TareaFamiliar'
                      vencidas:
                        type: array
                        items:
                          $ref: '#/components/schemas/TareaFamiliar'
                      calificadas:
                        type: array
                        items:
                          $ref: '#/components/schemas/TareaFamiliar'
        '401':
          description: No autorizado (token ausente o inválido)
        '404':
          description: Alumno no encontrado o no vinculado a la cuenta
        '500':
          description: Error del servidor

  /v1/familias/alumnos/{id}/tareas/{actividadId}/evidencias:
    post:
      tags:
        - Familias
      summary: Subir evidencia de una tarea (familia)
      description: |
        Adjunta una imagen (JPG, PNG, WEBP, HEIC) o PDF (máx. 10 MB) como evidencia de la
        actividad indicada. Requiere que el alumno esté vinculado al tutor y que el docente
        haya habilitado `permite_evidencia_familiar` en la actividad. La evidencia queda
        separada de la calificación formal.
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: ID del alumno vinculado
          schema:
            type: string
            format: uuid
        - name: actividadId
          in: path
          required: true
          description: ID de la actividad evaluable
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                comentario:
                  type: string
      responses:
        '201':
          description: Evidencia registrada
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/EvidenciaFamiliar'
        '400':
          description: Archivo faltante, formato/tamaño inválido o actividad no habilitada
        '401':
          description: No autorizado (token ausente o inválido)
        '500':
          description: Error del servidor

  /v1/familias/evidencias/{evidenciaId}:
    delete:
      tags:
        - Familias
      summary: Eliminar una evidencia propia de la familia
      description: Elimina la evidencia y su archivo. Solo el tutor que la subió puede eliminarla.
      security:
        - BearerAuth: []
      parameters:
        - name: evidenciaId
          in: path
          required: true
          description: ID de la evidencia
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Evidencia eliminada
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
        '401':
          description: No autorizado (token ausente o inválido)
        '404':
          description: Evidencia no encontrada o ajena al tutor
        '500':
          description: Error del servidor

  /v1/familias/alumnos/{id}/justificantes:
    get:
      tags:
        - Familias
      summary: Justificantes de falta de un alumno vinculado
      description: Devuelve los justificantes enviados por la familia para el alumno, con su estado.
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: ID del alumno
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Justificantes del alumno
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/JustificanteFamiliar'
        '401':
          description: No autorizado (token ausente o inválido)
        '404':
          description: Alumno no encontrado o no vinculado a la cuenta
        '500':
          description: Error del servidor
    post:
      tags:
        - Familias
      summary: Enviar un justificante de falta
      description: |
        Registra un justificante para una falta o retardo ya registrado. El motivo es obligatorio;
        el comprobante (imagen o PDF, máx. 10 MB) es opcional. Dirección aprueba o rechaza; al
        aprobar, la falta de ese día se marca como justificada.
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: ID del alumno vinculado
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - fecha
                - motivo
              properties:
                fecha:
                  type: string
                  format: date
                motivo:
                  type: string
                file:
                  type: string
                  format: binary
          application/json:
            schema:
              type: object
              required:
                - fecha
                - motivo
              properties:
                fecha:
                  type: string
                  format: date
                motivo:
                  type: string
      responses:
        '201':
          description: Justificante registrado
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/JustificanteFamiliar'
        '400':
          description: Datos inválidos, fecha sin falta registrada o falta ya justificada
        '401':
          description: No autorizado (token ausente o inválido)
        '500':
          description: Error del servidor

  /v1/familias/justificantes/{justificanteId}:
    delete:
      tags:
        - Familias
      summary: Retirar un justificante propio pendiente
      description: Solo se puede retirar un justificante que Dirección aún no ha revisado.
      security:
        - BearerAuth: []
      parameters:
        - name: justificanteId
          in: path
          required: true
          description: ID del justificante
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Justificante retirado
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
        '401':
          description: No autorizado (token ausente o inválido)
        '404':
          description: Justificante no encontrado, ajeno al tutor o ya revisado
        '500':
          description: Error del servidor

  /v1/familias/alumnos/{id}/documentos:
    get:
      tags:
        - Familias
      summary: Documentos escolares visibles para un alumno
      description: |
        Devuelve los documentos publicados por la escuela, dirigidos a todo el plantel o al grupo
        del alumno vinculado. El archivo va en bucket privado y se entrega con signed URL.
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: ID del alumno
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Documentos visibles
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/DocumentoFamiliar'
        '401':
          description: No autorizado (token ausente o inválido)
        '404':
          description: Alumno no encontrado o no vinculado a la cuenta
        '500':
          description: Error del servidor

  /v1/familias/alumnos/{id}/citas:
    get:
      tags:
        - Familias
      summary: Citas solicitadas para un alumno vinculado
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: ID del alumno
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Citas del alumno
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CitaFamiliar'
        '401':
          description: No autorizado (token ausente o inválido)
        '404':
          description: Alumno no encontrado o no vinculado a la cuenta
        '500':
          description: Error del servidor
    post:
      tags:
        - Familias
      summary: Solicitar una cita con la escuela
      description: |
        Registra una solicitud de cita con motivo y fecha tentativa. Dirección confirma o rechaza.
        Requiere que el plantel habilite el módulo `appointments`.
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: ID del alumno vinculado
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - motivo
                - preferencia_fecha
              properties:
                motivo:
                  type: string
                preferencia_fecha:
                  type: string
                  format: date
                preferencia_horario:
                  type: string
                  nullable: true
      responses:
        '201':
          description: Cita solicitada
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/CitaFamiliar'
        '400':
          description: Datos inválidos (motivo o fecha)
        '401':
          description: No autorizado (token ausente o inválido)
        '500':
          description: Error del servidor

  /v1/familias/citas/{citaId}:
    delete:
      tags:
        - Familias
      summary: Cancelar una cita propia
      description: Solo mientras siga pendiente o confirmada.
      security:
        - BearerAuth: []
      parameters:
        - name: citaId
          in: path
          required: true
          description: ID de la cita
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Cita cancelada
        '401':
          description: No autorizado (token ausente o inválido)
        '404':
          description: Cita no encontrada, ajena al tutor o ya atendida
        '500':
          description: Error del servidor

  /v1/familias/eventos:
    get:
      tags:
        - Familias
      summary: Eventos institucionales próximos visibles para la familia
      description: |
        Devuelve los eventos de la agenda escolar (`scope = institucional`) del plantel del tutor,
        desde hoy en adelante y ordenados por fecha. Solo incluye eventos cuya segmentación aplica
        a los alumnos vinculados (todo el plantel / familias, o su grupo).
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Lista de eventos próximos
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        titulo:
                          type: string
                        descripcion:
                          type: string
                          nullable: true
                        tipo:
                          type: string
                          nullable: true
                        fecha:
                          type: string
                          format: date
                        hora:
                          type: string
                          nullable: true
                        fecha_fin:
                          type: string
                          format: date
                          nullable: true
                        hora_fin:
                          type: string
                          nullable: true
                        todo_el_dia:
                          type: boolean
        '401':
          description: No autorizado (token ausente o inválido)
        '500':
          description: Error del servidor

  /v1/familias/notificaciones:
    get:
      tags:
        - Familias
      summary: Bandeja de notificaciones de la familia
      description: |
        Devuelve las notificaciones in-app del tutor autenticado (no leídas primero, luego por fecha)
        y el total de no leídas. Se generan al publicar avisos para su plantel/grupo.
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Bandeja de notificaciones
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/NotificacionFamiliar'
                  no_leidas:
                    type: integer
        '401':
          description: No autorizado (token ausente o inválido)
        '500':
          description: Error del servidor

  /v1/familias/notificaciones/{id}/leido:
    post:
      tags:
        - Familias
      summary: Marcar una notificación como leída
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: ID de la notificación
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Notificación marcada como leída
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      leida:
                        type: boolean
        '401':
          description: No autorizado (token ausente o inválido)
        '404':
          description: Notificación no encontrada
        '500':
          description: Error del servidor

  /v1/familias/notificaciones/leidas:
    post:
      tags:
        - Familias
      summary: Marcar todas las notificaciones como leídas
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Todas las notificaciones marcadas como leídas
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      leidas:
                        type: boolean
        '401':
          description: No autorizado (token ausente o inválido)
        '500':
          description: Error del servidor

  /v1/familias/notificaciones/preferencias:
    get:
      tags:
        - Familias
      summary: Preferencias de notificación de la familia
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Preferencias por tipo
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreferenciasNotificacion'
        '401':
          description: No autorizado (token ausente o inválido)
        '500':
          description: Error del servidor
    put:
      tags:
        - Familias
      summary: Actualizar preferencias de notificación
      description: 'Acepta el objeto de preferencias directamente o envuelto en { "preferencias": {...} }.'
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                preferencias:
                  $ref: '#/components/schemas/PreferenciasNotificacionValores'
      responses:
        '200':
          description: Preferencias actualizadas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreferenciasNotificacion'
        '401':
          description: No autorizado (token ausente o inválido)
        '500':
          description: Error del servidor

  /v1/familias/register-device:
    post:
      tags:
        - Familias
      summary: Registrar token de dispositivo para notificaciones push
      description: Registra el token FCM del dispositivo del tutor (idempotente). El envío push se conectará después.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                token:
                  type: string
              required:
                - token
      responses:
        '200':
          description: Dispositivo registrado
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      registrado:
                        type: boolean
        '400':
          description: Token ausente
        '401':
          description: No autorizado (token ausente o inválido)
        '500':
          description: Error del servidor

  /v1/familias/alumnos/{id}/resumen:
    get:
      tags:
        - Familias
      summary: Resumen consolidado del alumno (home de la app)
      description: |
        Vista "cómo va" de un vistazo: promedio general, asistencia (porcentaje, faltas y retardos),
        conteo de tareas (pendientes/vencidas/calificadas), avisos sin leer y próximos eventos.
        Solo si el alumno está vinculado al tutor (404 en caso contrario).
        `requiere_atencion` se activa con tareas vencidas o faltas (señales académicas accionables).
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: ID del alumno
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Resumen del alumno
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResumenFamiliar'
        '401':
          description: No autorizado (token ausente o inválido)
        '404':
          description: Alumno no encontrado o no vinculado a la cuenta
        '500':
          description: Error del servidor

  /v1/familias/conversaciones:
    get:
      tags:
        - Familias
      summary: Conversaciones de la familia con la escuela
      description: |
        Devuelve las conversaciones donde participa el tutor, con la contraparte, el último mensaje
        y el número de no leídos. Requiere que el plantel habilite el módulo de mensajería (si no, 403).
        Autenticación: `Authorization: Bearer` (app) o cookie de sesión (portal web).
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Lista de conversaciones
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ConversacionFamiliar'
        '401':
          description: No autorizado
        '403':
          description: Mensajería no habilitada para familias
        '500':
          description: Error del servidor

    post:
      tags:
        - Familias
      summary: Iniciar una conversación con la escuela
      description: |
        Crea una conversación privada vinculada al alumno. El mensaje se entrega al profesor activo
        asignado a su grupo; si no tiene uno, se envía a Dirección/Administración. Si no hay un
        destinatario activo, se conserva el hilo y el envío no se bloquea. El módulo de mensajería
        familiar debe estar habilitado.
        Autenticación: `Authorization: Bearer <token>` para móvil o cookie de sesión para web.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [alumnoId, asunto, contenido]
              properties:
                alumnoId:
                  type: string
                  format: uuid
                asunto:
                  type: string
                  maxLength: 120
                contenido:
                  type: string
                  maxLength: 5000
      responses:
        '201':
          description: Conversación iniciada
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
        '400':
          description: Datos inválidos
        '401':
          description: No autorizado
        '403':
          description: Módulo deshabilitado o alumno no vinculado a la cuenta
        '500':
          description: Error del servidor

  /v1/familias/conversaciones/{id}/mensajes:
    get:
      tags:
        - Familias
      summary: Mensajes de una conversación
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: ID de la conversación
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Mensajes de la conversación
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/MensajeFamiliar'
        '401':
          description: No autorizado
        '403':
          description: Mensajería no habilitada para familias
        '404':
          description: Conversación no encontrada o el tutor no participa
        '500':
          description: Error del servidor
    post:
      tags:
        - Familias
      summary: Enviar un mensaje como familia (con adjunto opcional)
      description: |
        Requiere que la escuela permita respuestas de familias
        (`communication_policy.families_can_reply`). Acepta JSON o `multipart/form-data`; el
        adjunto (imagen o PDF, máx. 10 MB) es opcional, y el texto puede ir vacío si hay adjunto.
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: ID de la conversación
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                contenido:
                  type: string
          multipart/form-data:
            schema:
              type: object
              properties:
                contenido:
                  type: string
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: Mensaje enviado
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/MensajeFamiliar'
        '400':
          description: Mensaje vacío o adjunto inválido
        '401':
          description: No autorizado
        '403':
          description: Mensajería no habilitada o respuestas de familias desactivadas
        '404':
          description: Conversación no encontrada o el tutor no participa
        '500':
          description: Error del servidor

  /v1/familias/conversaciones/{id}/leido:
    post:
      tags:
        - Familias
      summary: Marcar una conversación como leída
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: ID de la conversación
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Conversación marcada como leída
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      leida:
                        type: boolean
        '401':
          description: No autorizado
        '403':
          description: Mensajería no habilitada para familias
        '404':
          description: Conversación no encontrada o el tutor no participa
        '500':
          description: Error del servidor

  /v1/familias/alumnos/{id}/boleta:
    get:
      tags:
        - Familias
      summary: Datos de la boleta del alumno (para generar PDF en la app)
      description: |
        Devuelve los datos necesarios para generar la boleta (alumno, grupo, evaluaciones y asistencias).
        Respeta la política de publicación: con política "manual" solo se incluyen filas y observaciones aprobadas.
        Requiere que el plantel habilite el módulo de documentos (si no, 403).
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: ID del alumno
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Datos de la boleta
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BoletaFamiliar'
        '401':
          description: No autorizado
        '403':
          description: Documentos no habilitados para familias
        '404':
          description: Alumno no encontrado o no vinculado a la cuenta
        '500':
          description: Error del servidor

  /v1/familias/alumnos/{id}/autorizaciones:
    get:
      tags:
        - Familias
      summary: Autorizaciones escolares de un alumno
      description: |
        Devuelve las autorizaciones vigentes visibles para el alumno, con el estado de su respuesta
        (pendiente, aceptada, rechazada o vencida) y si aún admite respuesta.
        Requiere el módulo de documentos habilitado (403 en caso contrario).
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: ID del alumno
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Autorizaciones del alumno
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AutorizacionFamiliar'
        '401':
          description: No autorizado
        '403':
          description: Documentos no habilitados para familias
        '404':
          description: Alumno no encontrado o no vinculado a la cuenta
        '500':
          description: Error del servidor

  /v1/familias/autorizaciones/{id}/responder:
    post:
      tags:
        - Familias
      summary: Responder una autorización (aceptar o rechazar)
      description: |
        Registra la respuesta del tutor para un alumno vinculado. Reemplaza una respuesta previa.
        Falla con 409 si la autorización está cerrada o vencida.
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: ID de la autorización
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                alumno_id:
                  type: string
                respuesta:
                  type: string
                  enum: [aceptada, rechazada]
                comentario:
                  type: string
                  nullable: true
              required:
                - alumno_id
                - respuesta
      responses:
        '200':
          description: Respuesta registrada
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      alumno_id:
                        type: string
                      respuesta:
                        type: string
        '400':
          description: Datos incompletos
        '401':
          description: No autorizado
        '403':
          description: Documentos no habilitados para familias
        '404':
          description: Alumno no vinculado a la cuenta
        '409':
          description: Autorización cerrada o vencida
        '500':
          description: Error del servidor

  /v1/familias/alumnos/{id}/recursos:
    get:
      tags:
        - Familias
      summary: Recursos de apoyo para un alumno
      description: |
        Devuelve los recursos publicados visibles para el alumno (de todo el plantel, de su grupo
        o dirigidos a él), ordenados con los marcados como recomendados primero y luego por fecha.
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: ID del alumno
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Recursos del alumno
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/RecursoFamiliar'
        '401':
          description: No autorizado
        '403':
          description: Recursos no habilitados para familias
        '404':
          description: Alumno no encontrado o no vinculado a la cuenta
        '500':
          description: Error del servidor

  /v1/familias/cuenta/perfil:
    put:
      tags:
        - Familias
      summary: Actualizar datos de contacto del tutor
      description: |
        Actualiza nombre y teléfono del tutor. El correo no puede cambiarse aquí
        (es la identidad de acceso en `parent_auth`).
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                nombre_completo:
                  type: string
                telefono:
                  type: string
                  nullable: true
              required:
                - nombre_completo
      responses:
        '200':
          description: Datos actualizados
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      parent:
                        type: object
                        properties:
                          id:
                            type: string
                          nombre_completo:
                            type: string
                          email:
                            type: string
        '400':
          description: Nombre requerido
        '401':
          description: No autorizado
        '500':
          description: Error del servidor

  /v1/familias/cuenta/password:
    post:
      tags:
        - Familias
      summary: Cambiar la contraseña del tutor (con la actual)
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                actual:
                  type: string
                  format: password
                nueva:
                  type: string
                  format: password
              required:
                - actual
                - nueva
      responses:
        '200':
          description: Contraseña actualizada
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      actualizada:
                        type: boolean
        '400':
          description: Contraseña actual incorrecta o nueva demasiado corta
        '401':
          description: No autorizado
        '409':
          description: La cuenta no tiene credenciales activas
        '500':
          description: Error del servidor

  /v1/familias/alumnos/{id}/boleta/descarga:
    post:
      tags:
        - Familias
      summary: Registrar la descarga de una boleta
      description: |
        Registra que la familia descargó la boleta de un alumno vinculado (auditoría para la escuela).
        `trimestre` es opcional: `null` u omitido = boleta anual.
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: ID del alumno
          schema:
            type: string
            format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                trimestre:
                  type: integer
                  nullable: true
                  enum: [1, 2, 3]
      responses:
        '200':
          description: Descarga registrada
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      registrada:
                        type: boolean
        '401':
          description: No autorizado
        '403':
          description: Documentos no habilitados para familias
        '404':
          description: Alumno no encontrado o no vinculado a la cuenta
        '500':
          description: Error del servidor

  /v1/familias/alumnos/{id}/boleta/descargas:
    get:
      tags:
        - Familias
      summary: Descargas recientes de boletas del tutor
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: ID del alumno
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Descargas recientes
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        tipo:
                          type: string
                        trimestre:
                          type: integer
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
        '401':
          description: No autorizado
        '403':
          description: Documentos no habilitados para familias
        '404':
          description: Alumno no encontrado o no vinculado a la cuenta
        '500':
          description: Error del servidor


  /v1/director/familias/configuracion:
    get:
      tags:
        - Dirección
      summary: Leer la configuración del portal familiar
      description: Devuelve `familias_config` del plantel (módulos, políticas, canales de notificación).
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/PlantelId'
      responses:
        '200':
          description: Configuración del plantel
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      familias_config:
                        type: object
                        nullable: true
        '401':
          description: No autorizado
        '403':
          description: Permisos insuficientes
        '500':
          description: Error del servidor
    patch:
      tags:
        - Dirección
      summary: Mezclar parcialmente la configuración del portal familiar
      description: |
        Aplica solo las claves válidas presentes en el cuerpo (módulos, políticas, canales).
        No pisa el resto de la configuración.
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/PlantelId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                portal_enabled:
                  type: boolean
                mobile_app_enabled:
                  type: boolean
                ciclo_escolar:
                  type: string
                modules:
                  type: object
                  additionalProperties:
                    type: boolean
                notifications:
                  type: object
                  properties:
                    email:
                      type: boolean
                    push:
                      type: boolean
                publication_policy:
                  type: object
                  properties:
                    grades:
                      type: string
                      enum: [manual, automatic]
                    observations:
                      type: string
                      enum: [manual, automatic, hidden]
                    incidents:
                      type: string
                      enum: [internal, notify, both]
                communication_policy:
                  type: object
                  properties:
                    mode:
                      type: string
                      enum: [institutional, teacher_independent]
                    families_can_reply:
                      type: boolean
                    teachers_can_message:
                      type: boolean
      responses:
        '200':
          description: Configuración actualizada
        '400':
          description: Cuerpo inválido
        '401':
          description: No autorizado
        '403':
          description: Permisos insuficientes
        '500':
          description: Error del servidor

  /v1/director/familias/justificantes:
    get:
      tags:
        - Dirección
      summary: Justificantes de faltas del plantel
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/PlantelId'
        - name: estado
          in: query
          required: false
          schema:
            type: string
            enum: [pendiente, aprobado, rechazado]
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Justificantes del plantel
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/JustificanteDireccion'
        '401':
          description: No autorizado
        '403':
          description: Permisos insuficientes
        '500':
          description: Error del servidor

  /v1/director/familias/justificantes/{id}:
    patch:
      tags:
        - Dirección
      summary: Aprobar o rechazar un justificante
      description: Al aprobar, la asistencia de ese día se marca como `justificado`.
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/PlantelId'
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - estado
              properties:
                estado:
                  type: string
                  enum: [aprobado, rechazado]
                comentario:
                  type: string
                  nullable: true
      responses:
        '200':
          description: Justificante actualizado
        '400':
          description: Estado inválido
        '401':
          description: No autorizado
        '404':
          description: Justificante no encontrado
        '500':
          description: Error del servidor

  /v1/director/familias/documentos:
    get:
      tags:
        - Dirección
      summary: Documentos escolares del plantel
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/PlantelId'
      responses:
        '200':
          description: Documentos del plantel
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/DocumentoFamiliar'
                  grupos:
                    type: array
                    items:
                      $ref: '#/components/schemas/GrupoDocente'
        '401':
          description: No autorizado
        '403':
          description: Permisos insuficientes
        '500':
          description: Error del servidor
    post:
      tags:
        - Dirección
      summary: Publicar un documento escolar
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/PlantelId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentoEntrada'
      responses:
        '201':
          description: Documento publicado
        '400':
          description: Datos inválidos
        '401':
          description: No autorizado
        '403':
          description: Permisos insuficientes
        '500':
          description: Error del servidor

  /v1/director/familias/documentos/{id}:
    patch:
      tags:
        - Dirección
      summary: Actualizar un documento escolar
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/PlantelId'
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentoEntrada'
      responses:
        '200':
          description: Documento actualizado
        '400':
          description: Datos inválidos
        '401':
          description: No autorizado
        '404':
          description: Documento no encontrado
        '500':
          description: Error del servidor
    delete:
      tags:
        - Dirección
      summary: Eliminar un documento escolar
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/PlantelId'
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Documento eliminado
        '401':
          description: No autorizado
        '404':
          description: Documento no encontrado
        '500':
          description: Error del servidor

  /v1/director/familias/documentos/upload:
    post:
      tags:
        - Dirección
      summary: Subir archivo de un documento escolar
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/PlantelId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '201':
          description: Archivo subido
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ArchivoSubido'
        '400':
          description: Archivo faltante, formato o tamaño inválido
        '401':
          description: No autorizado
        '500':
          description: Error del servidor

  /v1/director/familias/citas:
    get:
      tags:
        - Dirección
      summary: Solicitudes de cita del plantel
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/PlantelId'
        - name: estado
          in: query
          required: false
          schema:
            type: string
            enum: [pendiente, confirmada, rechazada, atendida, cancelada]
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Citas del plantel
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CitaDireccion'
        '401':
          description: No autorizado
        '403':
          description: Permisos insuficientes
        '500':
          description: Error del servidor

  /v1/director/familias/citas/{id}:
    patch:
      tags:
        - Dirección
      summary: Confirmar, rechazar o marcar atendida una cita
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/PlantelId'
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - estado
              properties:
                estado:
                  type: string
                  enum: [confirmada, rechazada, atendida]
                comentario:
                  type: string
                  nullable: true
                programada_at:
                  type: string
                  format: date-time
                  nullable: true
                  description: Fecha/hora acordada (solo al confirmar).
      responses:
        '200':
          description: Cita actualizada
        '400':
          description: Estado inválido
        '401':
          description: No autorizado
        '404':
          description: Cita no encontrada
        '500':
          description: Error del servidor

  /v1/director/familias/recursos:
    get:
      tags:
        - Dirección
      summary: Recursos de apoyo del plantel
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/PlantelId'
      responses:
        '200':
          description: Recursos del plantel
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/RecursoFamiliar'
                  grupos:
                    type: array
                    items:
                      $ref: '#/components/schemas/GrupoDocente'
        '401':
          description: No autorizado
        '403':
          description: Permisos insuficientes
        '500':
          description: Error del servidor
    post:
      tags:
        - Dirección
      summary: Crear un recurso de apoyo
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/PlantelId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecursoEntrada'
      responses:
        '201':
          description: Recurso creado
        '400':
          description: Datos o destinatarios inválidos
        '401':
          description: No autorizado
        '500':
          description: Error del servidor

  /v1/director/familias/recursos/{id}:
    put:
      tags:
        - Dirección
      summary: Actualizar un recurso de apoyo
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/PlantelId'
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecursoEntrada'
      responses:
        '200':
          description: Recurso actualizado
        '401':
          description: No autorizado
        '404':
          description: Recurso no encontrado
        '500':
          description: Error del servidor
    delete:
      tags:
        - Dirección
      summary: Eliminar un recurso de apoyo
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/PlantelId'
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Recurso eliminado
        '401':
          description: No autorizado
        '404':
          description: Recurso no encontrado
        '500':
          description: Error del servidor

  /v1/director/familias/recursos/upload:
    post:
      tags:
        - Dirección
      summary: Subir archivo de un recurso de apoyo
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/PlantelId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '201':
          description: Archivo subido
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ArchivoSubido'
        '400':
          description: Archivo faltante, formato o tamaño inválido
        '401':
          description: No autorizado
        '500':
          description: Error del servidor

  /v1/director/familias/mensajes:
    get:
      tags:
        - Dirección
      summary: Consultar audiencia disponible para mensajes familiares
      description: Devuelve grupos, alumnos y padres/tutores del plantel para construir el selector de destinatarios.
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/PlantelId'
      responses:
        '200':
          description: Audiencia familiar del plantel
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      grupos:
                        type: array
                        items:
                          $ref: '#/components/schemas/GrupoDocente'
                      alumnos:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            nombre_completo:
                              type: string
                            grupo_id:
                              type: string
                              nullable: true
                      padres:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            nombre_completo:
                              type: string
                            email:
                              type: string
                              nullable: true
                            alumnos:
                              type: array
                              items:
                                type: object
        '401':
          description: No autorizado
        '403':
          description: Permisos insuficientes
        '500':
          description: Error del servidor
    post:
      tags:
        - Dirección
      summary: Enviar mensaje a familias
      description: Crea una conversación privada por padre/tutor destinatario (todos, grupo, familia de un alumno o padres seleccionados).
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/PlantelId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [alcance, titulo, contenido]
              properties:
                alcance:
                  type: string
                  enum: [todos, grupo, alumno, padres]
                titulo:
                  type: string
                contenido:
                  type: string
                grupoId:
                  type: string
                  format: uuid
                  nullable: true
                alumnoId:
                  type: string
                  format: uuid
                  nullable: true
                padreIds:
                  type: array
                  items:
                    type: string
                    format: uuid
      responses:
        '201':
          description: Mensaje enviado
        '400':
          description: Datos inválidos
        '401':
          description: No autorizado
        '500':
          description: Error del servidor

  /v1/director/avisos:
    get:
      tags:
        - Dirección
      summary: Avisos del plantel
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/PlantelId'
      responses:
        '200':
          description: Avisos del plantel
        '401':
          description: No autorizado
        '403':
          description: Permisos insuficientes
        '500':
          description: Error del servidor
    post:
      tags:
        - Dirección
      summary: Crear un aviso segmentado
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/PlantelId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AvisoEntrada'
      responses:
        '201':
          description: Aviso creado
        '400':
          description: Datos inválidos
        '401':
          description: No autorizado
        '500':
          description: Error del servidor

  /v1/director/avisos/{id}:
    patch:
      tags:
        - Dirección
      summary: Actualizar un aviso
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/PlantelId'
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AvisoEntrada'
      responses:
        '200':
          description: Aviso actualizado
        '401':
          description: No autorizado
        '404':
          description: Aviso no encontrado
        '500':
          description: Error del servidor
    delete:
      tags:
        - Dirección
      summary: Eliminar un aviso
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/PlantelId'
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Aviso eliminado
        '401':
          description: No autorizado
        '404':
          description: Aviso no encontrado
        '500':
          description: Error del servidor

  /v1/profesor/grupos:
    get:
      tags:
        - Docente
      summary: Grupos del docente
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      responses:
        '200':
          description: Grupos del docente
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/GrupoDocente'
        '401':
          description: No autorizado
        '500':
          description: Error del servidor

  /v1/profesor/grupos/{id}/alumnos:
    get:
      tags:
        - Docente
      summary: Alumnos de un grupo del docente
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Alumnos del grupo
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AlumnoDocente'
        '401':
          description: No autorizado
        '404':
          description: Grupo no encontrado o sin permisos
        '500':
          description: Error del servidor

  /v1/profesor/grupos/{id}/actividades:
    get:
      tags:
        - Docente
      summary: Actividades de un grupo
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Actividades del grupo
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ActividadDocente'
        '401':
          description: No autorizado
        '404':
          description: Grupo no encontrado o sin permisos
        '500':
          description: Error del servidor
    post:
      tags:
        - Docente
      summary: Crear una actividad
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActividadEntrada'
      responses:
        '201':
          description: Actividad creada
        '400':
          description: Datos inválidos o grupo sin permisos
        '401':
          description: No autorizado
        '500':
          description: Error del servidor

  /v1/profesor/actividades/{id}:
    patch:
      tags:
        - Docente
      summary: Actualizar una actividad (parcial)
      description: Solo se actualizan los campos presentes en el cuerpo.
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActividadEntrada'
      responses:
        '200':
          description: Actividad actualizada
        '400':
          description: Datos inválidos o nada que actualizar
        '401':
          description: No autorizado
        '404':
          description: Actividad no encontrada o sin permisos
        '500':
          description: Error del servidor
    delete:
      tags:
        - Docente
      summary: Eliminar (soft delete) una actividad
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Actividad eliminada
        '401':
          description: No autorizado
        '404':
          description: Actividad no encontrada o sin permisos
        '500':
          description: Error del servidor

  /v1/profesor/actividades/{id}/evidencias-familia:
    get:
      tags:
        - Docente
      summary: Evidencias enviadas por las familias
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Evidencias de la actividad
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/EvidenciaFamiliarDocente'
        '401':
          description: No autorizado
        '404':
          description: Actividad no encontrada o sin permisos
        '500':
          description: Error del servidor

  /v1/profesor/actividades/{id}/calificaciones:
    get:
      tags:
        - Docente
      summary: Calificaciones de una actividad
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Alumnos del grupo con su calificación
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CalificacionDocente'
        '401':
          description: No autorizado
        '404':
          description: Actividad no encontrada o sin permisos
        '500':
          description: Error del servidor
    put:
      tags:
        - Docente
      summary: Guardar calificaciones de una actividad
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - calificaciones
              properties:
                calificaciones:
                  type: array
                  items:
                    type: object
                    required:
                      - alumno_id
                    properties:
                      alumno_id:
                        type: string
                        format: uuid
                      calificacion:
                        type: number
                        nullable: true
                        minimum: 0
                        maximum: 10
                      retroalimentacion:
                        type: string
                        nullable: true
      responses:
        '200':
          description: Calificaciones guardadas
        '400':
          description: Calificación inválida o alumno ajeno al grupo
        '401':
          description: No autorizado
        '500':
          description: Error del servidor

  /v1/profesor/grupos/{id}/asistencia:
    get:
      tags:
        - Docente
      summary: Asistencia de un grupo en una fecha
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: fecha
          in: query
          required: true
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Alumnos del grupo con su estado de asistencia
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AsistenciaAlumnoDocente'
        '400':
          description: Parámetro `fecha` faltante o inválido
        '401':
          description: No autorizado
        '404':
          description: Grupo no encontrado o sin permisos
        '500':
          description: Error del servidor
    put:
      tags:
        - Docente
      summary: Guardar asistencia de un grupo en una fecha
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - fecha
                - registros
              properties:
                fecha:
                  type: string
                  format: date
                registros:
                  type: array
                  items:
                    type: object
                    required:
                      - alumno_id
                      - estado
                    properties:
                      alumno_id:
                        type: string
                        format: uuid
                      estado:
                        type: string
                        enum: [presente, ausente, retardo, justificado]
      responses:
        '200':
          description: Asistencia guardada
        '400':
          description: Fecha o registros inválidos
        '401':
          description: No autorizado
        '404':
          description: Grupo no encontrado o sin permisos
        '500':
          description: Error del servidor

  /v1/director/familias/conversaciones:
    get:
      tags: [Dirección]
      summary: Bandeja de conversaciones iniciadas por familias
      description: Solo devuelve hilos privados `family_portal` en los que participa la cuenta de Dirección autenticada.
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/PlantelId'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Conversaciones de familias
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxConversacionesFamiliar'
        '401':
          description: No autorizado
        '403':
          description: Permisos insuficientes para el plantel
        '500':
          description: Error del servidor

  /v1/director/familias/conversaciones/{id}/mensajes:
    get:
      tags: [Dirección]
      summary: Leer mensajes de una conversación familiar
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/PlantelId'
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Mensajes paginados
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxMensajesFamiliar'
        '401':
          description: No autorizado
        '403':
          description: Permisos insuficientes para el plantel
        '404':
          description: Conversación no asignada a esta cuenta
        '500':
          description: Error del servidor
    post:
      tags: [Dirección]
      summary: Responder a una conversación familiar
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/PlantelId'
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RespuestaInboxFamiliar'
      responses:
        '201':
          description: Respuesta enviada
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/MensajeFamiliar'
        '400':
          description: Mensaje vacío o demasiado largo
        '401':
          description: No autorizado
        '403':
          description: Permisos insuficientes para el plantel
        '404':
          description: Conversación no asignada a esta cuenta
        '500':
          description: Error del servidor

  /v1/director/familias/conversaciones/{id}/leido:
    post:
      tags: [Dirección]
      summary: Marcar una conversación familiar como leída
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/PlantelId'
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Conversación marcada como leída
        '401':
          description: No autorizado
        '403':
          description: Permisos insuficientes para el plantel
        '404':
          description: Conversación no asignada a esta cuenta

  /v1/profesor/familias/conversaciones:
    get:
      tags: [Docentes]
      summary: Bandeja de conversaciones familiares asignadas al profesor
      description: Solo devuelve conversaciones en las que participa el profesor asignado al grupo del alumno.
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Conversaciones familiares
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxConversacionesFamiliar'
        '401':
          description: No autorizado
        '403':
          description: Solo el profesor activo puede consultar esta bandeja
        '500':
          description: Error del servidor

  /v1/profesor/familias/conversaciones/{id}/mensajes:
    get:
      tags: [Docentes]
      summary: Leer mensajes de una conversación familiar
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Mensajes paginados
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxMensajesFamiliar'
        '401':
          description: No autorizado
        '403':
          description: Permisos insuficientes
        '404':
          description: Conversación no asignada a este profesor
        '500':
          description: Error del servidor
    post:
      tags: [Docentes]
      summary: Responder a una conversación familiar
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RespuestaInboxFamiliar'
      responses:
        '201':
          description: Respuesta enviada
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/MensajeFamiliar'
        '400':
          description: Mensaje vacío o demasiado largo
        '401':
          description: No autorizado
        '403':
          description: Permisos insuficientes
        '404':
          description: Conversación no asignada a este profesor
        '500':
          description: Error del servidor

  /v1/profesor/familias/conversaciones/{id}/leido:
    post:
      tags: [Docentes]
      summary: Marcar una conversación familiar como leída
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Conversación marcada como leída
        '401':
          description: No autorizado
        '403':
          description: Permisos insuficientes
        '404':
          description: Conversación no asignada a este profesor

components:
  parameters:
    Limit:
      name: limit
      in: query
      required: false
      description: Tamaño de página (1-100). Default 50.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 50
    Offset:
      name: offset
      in: query
      required: false
      description: Desplazamiento para paginar (0-based).
      schema:
        type: integer
        minimum: 0
        default: 0
    PlantelId:
      name: plantel_id
      in: query
      required: false
      description: Solo administradores; los directores quedan acotados a su plantel.
      schema:
        type: string
        format: uuid
  schemas:
    RecursoFamiliar:
      type: object
      properties:
        id:
          type: string
        titulo:
          type: string
        descripcion:
          type: string
          nullable: true
        url:
          type: string
          nullable: true
        tipo:
          type: string
          enum: [enlace, guia, actividad, otro]
        campo_formativo:
          type: string
          nullable: true
        recomendado:
          type: boolean
        archivo_url:
          type: string
          nullable: true
        archivo_nombre:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
    AutorizacionFamiliar:
      type: object
      properties:
        id:
          type: string
        titulo:
          type: string
        descripcion:
          type: string
          nullable: true
        tipo:
          type: string
        fecha_limite:
          type: string
          format: date
          nullable: true
        estado:
          type: string
          enum: [pendiente, aceptada, rechazada, vencida]
        respondible:
          type: boolean
        respuesta:
          type: string
          nullable: true
          enum: [aceptada, rechazada]
        comentario:
          type: string
          nullable: true
    BoletaFamiliar:
      type: object
      properties:
        data:
          type: object
          properties:
            alumno:
              type: object
              properties:
                id:
                  type: string
                nombre_completo:
                  type: string
                curp:
                  type: string
                  nullable: true
            grupo:
              type: object
              nullable: true
              properties:
                grado:
                  type: string
                  nullable: true
                nivel:
                  type: string
                  nullable: true
                ciclo_escolar:
                  type: string
                  nullable: true
                grupo:
                  type: string
                  nullable: true
                turno:
                  type: string
                  nullable: true
                plantel_nombre:
                  type: string
                  nullable: true
                plantel_cct:
                  type: string
                  nullable: true
            evaluaciones:
              type: array
              items:
                type: object
                properties:
                  alumno_id:
                    type: string
                  campo_formativo:
                    type: string
                  trimestre:
                    type: integer
                  calificacion:
                    type: number
                    nullable: true
                  observaciones:
                    type: string
                    nullable: true
            asistencias:
              type: array
              items:
                type: object
                properties:
                  alumno_id:
                    type: string
                  trimestre:
                    type: integer
                  total_asistencias:
                    type: integer
    ConversacionFamiliar:
      type: object
      properties:
        id:
          type: string
        tipo:
          type: string
          enum: ['1:1', group, broadcast]
        titulo:
          type: string
          nullable: true
        actualizado_en:
          type: string
          format: date-time
        no_leidos:
          type: integer
        ultimo_mensaje:
          type: object
          nullable: true
          properties:
            contenido:
              type: string
            enviado_en:
              type: string
              format: date-time
            mio:
              type: boolean
        contraparte:
          type: string
    MensajeFamiliar:
      type: object
      properties:
        id:
          type: string
        contenido:
          type: string
        mio:
          type: boolean
        enviado_en:
          type: string
          format: date-time
        autor:
          type: string
        adjunto:
          type: object
          nullable: true
          properties:
            url:
              type: string
              nullable: true
              description: Signed URL temporal del archivo (bucket privado).
            nombre:
              type: string
              nullable: true
            tipo:
              type: string
              nullable: true
    InboxConversacionFamiliar:
      type: object
      properties:
        id:
          type: string
          format: uuid
        tipo:
          type: string
          enum: ['1:1', group]
        titulo:
          type: string
          nullable: true
        actualizado_en:
          type: string
          format: date-time
        no_leidos:
          type: integer
        ultimo_mensaje:
          type: object
          nullable: true
          properties:
            contenido:
              type: string
            enviado_en:
              type: string
              format: date-time
            mio:
              type: boolean
        contraparte:
          type: string
        alumno_id:
          type: string
          format: uuid
          nullable: true
    InboxConversacionesFamiliar:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/InboxConversacionFamiliar'
        pagination:
          $ref: '#/components/schemas/Paginacion'
    InboxMensajesFamiliar:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/MensajeFamiliar'
        pagination:
          $ref: '#/components/schemas/Paginacion'
    Paginacion:
      type: object
      properties:
        limit:
          type: integer
        offset:
          type: integer
        has_more:
          type: boolean
    RespuestaInboxFamiliar:
      type: object
      required: [contenido]
      properties:
        contenido:
          type: string
          minLength: 1
          maxLength: 5000
    ResumenFamiliar:
      type: object
      properties:
        data:
          type: object
          properties:
            alumno:
              type: object
              properties:
                id:
                  type: string
                nombre_completo:
                  type: string
                numero_lista:
                  type: integer
                  nullable: true
                grupo:
                  type: object
                  nullable: true
                  properties:
                    id:
                      type: string
                    nombre:
                      type: string
                    grado:
                      type: string
                      nullable: true
                    ciclo_escolar:
                      type: string
                      nullable: true
            requiere_atencion:
              type: boolean
            asistencia:
              type: object
              nullable: true
              properties:
                porcentaje:
                  type: integer
                  nullable: true
                ausentes:
                  type: integer
                retardos:
                  type: integer
            tareas:
              type: object
              nullable: true
              properties:
                pendientes:
                  type: integer
                vencidas:
                  type: integer
                calificadas:
                  type: integer
            promedio_general:
              type: integer
              nullable: true
            avisos_sin_leer:
              type: integer
            proximos_eventos:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  titulo:
                    type: string
                  fecha:
                    type: string
                    format: date
    NotificacionFamiliar:
      type: object
      properties:
        id:
          type: string
        tipo:
          type: string
          enum: [avisos, tareas, asistencia, calificaciones, eventos]
        titulo:
          type: string
        cuerpo:
          type: string
          nullable: true
        leida:
          type: boolean
        data:
          type: object
        created_at:
          type: string
          format: date-time
    PreferenciasNotificacionValores:
      type: object
      properties:
        avisos:
          type: boolean
        tareas:
          type: boolean
        asistencia:
          type: boolean
        calificaciones:
          type: boolean
        eventos:
          type: boolean
    PreferenciasNotificacion:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/PreferenciasNotificacionValores'
        canales:
          type: object
          description: Canales habilitados por el plantel (app siempre activo).
          properties:
            app:
              type: boolean
            email:
              type: boolean
            push:
              type: boolean
    TareaFamiliar:
      type: object
      properties:
        id:
          type: string
        nombre:
          type: string
        tipo:
          type: string
          description: Tipo de actividad (tarea, examen, etc.)
        descripcion:
          type: string
          nullable: true
        fecha_entrega:
          type: string
          format: date-time
          nullable: true
        ponderacion:
          type: integer
          nullable: true
        calificacion:
          type: number
          nullable: true
        retroalimentacion:
          type: string
          nullable: true
        permite_evidencia_familiar:
          type: boolean
          description: El docente habilitó que la familia adjunte evidencia para esta actividad.
        evidencias:
          type: array
          description: Evidencias enviadas por la familia para esta actividad.
          items:
            $ref: '#/components/schemas/EvidenciaFamiliar'
    EvidenciaFamiliar:
      type: object
      properties:
        id:
          type: string
        actividad_id:
          type: string
        archivo_url:
          type: string
          nullable: true
          description: Signed URL temporal del archivo en bucket privado.
        archivo_nombre:
          type: string
          nullable: true
        archivo_tipo:
          type: string
          nullable: true
        archivo_tamano:
          type: integer
          nullable: true
        comentario:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
    JustificanteFamiliar:
      type: object
      properties:
        id:
          type: string
        fecha:
          type: string
          format: date
          description: Día de la falta o retardo justificado.
        motivo:
          type: string
        estado:
          type: string
          enum: [pendiente, aprobado, rechazado]
        comentario_revision:
          type: string
          nullable: true
          description: Respuesta de la escuela al revisar.
        archivo_url:
          type: string
          nullable: true
          description: Signed URL temporal del comprobante (bucket privado).
        archivo_nombre:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
    DocumentoFamiliar:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        description:
          type: string
          nullable: true
        categoria:
          type: string
          description: reglamento, circular, formato, calendario u otro.
        url:
          type: string
          nullable: true
        archivo_url:
          type: string
          nullable: true
          description: Signed URL temporal del archivo (bucket privado).
        archivo_nombre:
          type: string
          nullable: true
        target_audience:
          type: string
          enum: [plantel, grupo]
        target_group_id:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
    CitaFamiliar:
      type: object
      properties:
        id:
          type: string
        motivo:
          type: string
        preferencia_fecha:
          type: string
          format: date
        preferencia_horario:
          type: string
          nullable: true
        estado:
          type: string
          enum: [pendiente, confirmada, rechazada, atendida, cancelada]
        programada_at:
          type: string
          format: date-time
          nullable: true
        comentario_respuesta:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
    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

    JustificanteDireccion:
      allOf:
        - $ref: '#/components/schemas/JustificanteFamiliar'
        - type: object
          properties:
            alumno_id:
              type: string
            alumno_nombre:
              type: string
              nullable: true
            grupo:
              type: string
              nullable: true
    CitaDireccion:
      allOf:
        - $ref: '#/components/schemas/CitaFamiliar'
        - type: object
          properties:
            alumno_id:
              type: string
            alumno_nombre:
              type: string
              nullable: true
            grupo:
              type: string
              nullable: true
    DocumentoEntrada:
      type: object
      required:
        - title
      properties:
        title:
          type: string
        description:
          type: string
          nullable: true
        categoria:
          type: string
          description: reglamento, circular, formato, calendario u otro.
        url:
          type: string
          nullable: true
        file_path:
          type: string
          nullable: true
        file_name:
          type: string
          nullable: true
        file_type:
          type: string
          nullable: true
        file_size:
          type: integer
          nullable: true
        target_audience:
          type: string
          enum: [plantel, grupo]
        target_group_id:
          type: string
          nullable: true
    ArchivoSubido:
      type: object
      properties:
        file_path:
          type: string
        file_name:
          type: string
        file_type:
          type: string
        file_size:
          type: integer
    RecursoEntrada:
      type: object
      required:
        - title
      properties:
        title:
          type: string
        description:
          type: string
          nullable: true
        url:
          type: string
          nullable: true
        tipo:
          type: string
        campo_formativo:
          type: string
          nullable: true
        recomendado:
          type: boolean
        file_path:
          type: string
          nullable: true
        file_name:
          type: string
          nullable: true
        file_type:
          type: string
          nullable: true
        file_size:
          type: integer
          nullable: true
        audiencias:
          type: array
          description: Destinos por grado o grupo. Vacío = todo el plantel.
          items:
            type: object
            properties:
              tipo:
                type: string
                enum: [grado, grupo]
              valor:
                type: string
    AvisoEntrada:
      type: object
      required:
        - title
      properties:
        title:
          type: string
        content:
          type: string
          nullable: true
        type:
          type: string
          nullable: true
        status:
          type: string
          enum: [activo, borrador, archivado]
        target_audience:
          type: string
          description: todos, familias, docentes, nivel, grado, grupo o alumno.
        target_group_id:
          type: string
          nullable: true
        start_date:
          type: string
          format: date
          nullable: true
        end_date:
          type: string
          format: date
          nullable: true
    GrupoDocente:
      type: object
      properties:
        id:
          type: string
        nombre:
          type: string
        grado:
          type: string
          nullable: true
        grupo:
          type: string
          nullable: true
        nivel:
          type: string
          nullable: true
        ciclo_escolar:
          type: string
          nullable: true
        plantel:
          type: string
          nullable: true
    AlumnoDocente:
      type: object
      properties:
        id:
          type: string
        nombre_completo:
          type: string
        numero_lista:
          type: integer
          nullable: true
        foto_url:
          type: string
          nullable: true
    ActividadDocente:
      type: object
      properties:
        id:
          type: string
        nombre:
          type: string
        tipo:
          type: string
        descripcion:
          type: string
          nullable: true
        fecha_entrega:
          type: string
          format: date-time
          nullable: true
        ponderacion:
          type: integer
          nullable: true
        trimestre:
          type: integer
          nullable: true
        campo_formativo:
          type: string
          nullable: true
        permite_evidencia_familiar:
          type: boolean
        evidencias_familia:
          type: integer
          description: Número de evidencias enviadas por familias.
        created_at:
          type: string
          format: date-time
    ActividadEntrada:
      type: object
      properties:
        nombre:
          type: string
        tipo:
          type: string
          enum: [tarea, examen, proyecto, participacion, otro]
        descripcion:
          type: string
          nullable: true
        fecha_entrega:
          type: string
          format: date-time
          nullable: true
        ponderacion:
          type: integer
          minimum: 0
          maximum: 100
        trimestre:
          type: integer
          enum: [1, 2, 3]
        campo_formativo:
          type: string
          nullable: true
        permite_evidencia_familiar:
          type: boolean
    EvidenciaFamiliarDocente:
      allOf:
        - $ref: '#/components/schemas/EvidenciaFamiliar'
        - type: object
          properties:
            alumno_id:
              type: string
            alumno_nombre:
              type: string
              nullable: true
    CalificacionDocente:
      type: object
      properties:
        alumno_id:
          type: string
        nombre_completo:
          type: string
        numero_lista:
          type: integer
          nullable: true
        calificacion:
          type: number
          nullable: true
        retroalimentacion:
          type: string
          nullable: true
    AsistenciaAlumnoDocente:
      type: object
      properties:
        alumno_id:
          type: string
        nombre_completo:
          type: string
        numero_lista:
          type: integer
          nullable: true
        estado:
          type: string
          nullable: true
          enum: [presente, ausente, retardo, justificado]
        notas:
          type: string
          nullable: true
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: "Token obtenido al iniciar sesión (`POST /auth/login` para docentes y `POST /v1/familias/login` para familias; el token familiar es una sesión firmada, no un JWT). Enviar en `Authorization: Bearer <token>`. Las rutas `/v1/familias/*` también aceptan la cookie `parent_session` para el portal web."
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: "Clave de integración (server-to-server). Se emite desde el panel de administración (`/admin/api-keys`). Incluir en el header `x-api-key: <key>`."

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
  - name: Créditos
    description: Consulta del saldo de créditos disponibles para generación con IA
  - name: Familias
    description: Acceso de padres, madres y tutores al portal familiar (login y perfil)
  - name: Dirección
    description: Gestión institucional para apps de Dirección (avisos, recursos, documentos, justificantes, citas, mensajes y configuración)
  - name: Docente
    description: Operación docente para la app de profesores (grupos, actividades, calificaciones, asistencia y evidencias familiares)
