openapi: 3.0.0
info:
  title: 考试模块API
  version: 1.0.0
  description: 动态考试与成绩的最小契约（骨架）

paths:
  /api/v1/exams/start:
    post:
      summary: 开始考试
      tags: [考试]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [course_id]
              properties:
                course_id: { type: integer }
                count: { type: integer, minimum: 1, maximum: 100, default: 10 }
      responses:
        200:
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: { type: integer, example: 200 }
                  message: { type: string, example: success }
                  data:
                    type: object
                    properties:
                      exam_id: { type: integer }

  /api/v1/exams/submit:
    post:
      summary: 提交答案
      tags: [考试]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [exam_id, answers]
              properties:
                exam_id: { type: integer }
                answers:
                  type: array
                  items:
                    type: object
                    properties:
                      question_id: { type: string }
                      answer: { type: string }
      responses:
        200:
          description: 成功

  /api/v1/exams/{id}:
    get:
      summary: 获取考试详情
      tags: [考试]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: integer }
      responses:
        200:
          description: 成功
        404:
          description: 未找到

  /api/v1/exams/records:
    get:
      summary: 考试记录
      tags: [考试]
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: page
          schema: { type: integer, minimum: 1, default: 1 }
        - in: query
          name: size
          schema: { type: integer, minimum: 1, maximum: 100, default: 10 }
      responses:
        200:
          description: 成功

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
