openapi: 3.0.0
info:
  title: 课程管理模块API
  version: 1.0.0
  description: 课程与知识点的最小契约（骨架）

paths:
  /api/v1/courses:
    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 }
        - in: query
          name: status
          schema: { type: string }
        - in: query
          name: category
          schema: { type: string }
      responses:
        200:
          description: 成功
    post:
      summary: 创建课程（管理员）
      tags: [课程]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CourseCreate'
      responses:
        201:
          description: 已创建

  /api/v1/courses/{id}:
    get:
      summary: 获取课程
      tags: [课程]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: integer }
      responses:
        200:
          description: 成功
        404:
          description: 未找到
    put:
      summary: 更新课程（管理员）
      tags: [课程]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CourseCreate'
      responses:
        200:
          description: 已更新
    delete:
      summary: 删除课程（管理员）
      tags: [课程]
      security:
        - bearerAuth: []
      responses:
        204:
          description: 已删除

  /api/v1/courses/{id}/materials:
    post:
      summary: 上传课程资料（管理员）
      tags: [课程]
      security:
        - bearerAuth: []
      responses:
        201:
          description: 已上传

  /api/v1/courses/{id}/knowledge-points:
    get:
      summary: 获取课程知识点
      tags: [知识点]
      security:
        - bearerAuth: []
      responses:
        200:
          description: 成功
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/KnowledgePoint'

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

  schemas:
    Course:
      type: object
      properties:
        id: { type: integer }
        name: { type: string }
        description: { type: string }
        category: { type: string }
        status: { type: string }
    CourseCreate:
      type: object
      required: [name]
      properties:
        name: { type: string, minLength: 1 }
        description: { type: string }
        category: { type: string }
    KnowledgePoint:
      type: object
      properties:
        id: { type: integer }
        title: { type: string }
        course_id: { type: integer }
