{
  "openapi": "3.0.3",
  "info": {
    "title": "懂古筝 API 文档",
    "version": "1.0.0",
    "description": "懂古筝古筝爱好者社区平台 API 文档"
  },
  "servers": [
    { "url": "https://www.dongguzheng.com", "description": "生产环境" },
    { "url": "http://localhost:3000", "description": "开发环境" }
  ],
  "tags": [
    { "name": "认证", "description": "用户认证相关接口" },
    { "name": "用户", "description": "用户信息相关接口" },
    { "name": "专栏", "description": "付费专栏相关接口" },
    { "name": "课程", "description": "课程相关接口" },
    { "name": "课程包", "description": "课程包相关接口" },
    { "name": "社区", "description": "社区动态相关接口" },
    { "name": "评分", "description": "评分曲谱相关接口" },
    { "name": "消息", "description": "消息通知相关接口" },
    { "name": "支付", "description": "支付相关接口" },
    { "name": "管理", "description": "后台管理接口" }
  ],
  "paths": {
    "/api/auth/register": {
      "post": {
        "tags": ["认证"],
        "summary": "用户注册",
        "description": "新用户注册账号",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["username", "email", "password"],
                "properties": {
                  "username": { "type": "string", "description": "用户名", "example": "zhangsan" },
                  "email": { "type": "string", "format": "email", "description": "邮箱", "example": "user@example.com" },
                  "password": { "type": "string", "description": "密码", "example": "password123" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "注册成功", "content": { "application/json": { "example": { "code": 0, "message": "注册成功", "data": { "token": "xxx", "user": { "id": 1, "username": "zhangsan" } } } } } },
          "400": { "description": "参数错误或用户名已存在" }
        }
      }
    },
    "/api/auth/login": {
      "post": {
        "tags": ["认证"],
        "summary": "用户登录",
        "description": "用户登录获取 token",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["email", "password"],
                "properties": {
                  "email": { "type": "string", "format": "email", "description": "邮箱", "example": "user@example.com" },
                  "password": { "type": "string", "description": "密码", "example": "password123" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "登录成功", "content": { "application/json": { "example": { "code": 0, "message": "登录成功", "data": { "token": "xxx", "user": { "id": 1, "username": "zhangsan" } } } } } },
          "401": { "description": "邮箱或密码错误" }
        }
      }
    },
    "/api/auth/logout": {
      "post": {
        "tags": ["认证"],
        "summary": "用户退出",
        "description": "退出登录（清除 token）",
        "security": [{ "bearerAuth": [] }],
        "responses": {
          "200": { "description": "退出成功" }
        }
      }
    },
    "/api/column/list": {
      "get": {
        "tags": ["专栏"],
        "summary": "获取专栏列表",
        "description": "获取所有可订阅的专栏列表",
        "parameters": [
          { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 }, "description": "页码" },
          { "name": "size", "in": "query", "schema": { "type": "integer", "default": 10 }, "description": "每页数量" },
          { "name": "keyword", "in": "query", "schema": { "type": "string" }, "description": "搜索关键词" }
        ],
        "responses": {
          "200": { "description": "获取成功" }
        }
      }
    },
    "/api/column/{slug}": {
      "get": {
        "tags": ["专栏"],
        "summary": "获取专栏详情",
        "description": "获取指定专栏的详细信息",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "专栏 slug" }
        ],
        "responses": {
          "200": { "description": "获取成功" },
          "404": { "description": "专栏不存在" }
        }
      }
    },
    "/api/column/{slug}/subscribe": {
      "post": {
        "tags": ["订阅"],
        "summary": "订阅专栏",
        "description": "订阅指定专栏（免费或创建订单）",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "专栏 slug" }
        ],
        "responses": {
          "200": { "description": "订阅成功" },
          "201": { "description": "订单创建成功" }
        }
      },
      "delete": {
        "tags": ["订阅"],
        "summary": "取消订阅",
        "description": "取消订阅指定专栏",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "专栏 slug" }
        ],
        "responses": {
          "200": { "description": "取消订阅成功" }
        }
      }
    },
    "/api/course/list": {
      "get": {
        "tags": ["课程"],
        "summary": "获取课程列表",
        "description": "获取所有课程列表",
        "parameters": [
          { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 }, "description": "页码" },
          { "name": "type", "in": "query", "schema": { "type": "string", "enum": ["LESSON", "PACKAGE"] }, "description": "课程类型" },
          { "name": "keyword", "in": "query", "schema": { "type": "string" }, "description": "搜索关键词" }
        ],
        "responses": {
          "200": { "description": "获取成功" }
        }
      }
    },
    "/api/course/{slug}": {
      "get": {
        "tags": ["课程"],
        "summary": "获取课程详情",
        "description": "获取指定课程的详细信息",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "课程 slug" }
        ],
        "responses": {
          "200": { "description": "获取成功" }
        }
      }
    },
    "/api/course/{slug}/progress": {
      "get": {
        "tags": ["课程"],
        "summary": "获取学习进度",
        "description": "获取当前用户在指定课程中的学习进度",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "课程 slug" }
        ],
        "responses": {
          "200": { "description": "获取成功" }
        }
      }
    },
    "/api/course/{slug}/lesson/{id}": {
      "put": {
        "tags": ["课程"],
        "summary": "更新课时进度",
        "description": "更新指定课时的学习状态",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "课程 slug" },
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "课时 ID" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["status"],
                "properties": {
                  "status": { "type": "string", "enum": ["IN_PROGRESS", "COMPLETED"], "description": "学习状态" },
                  "watchTime": { "type": "integer", "description": "观看时长（秒）" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "更新成功" }
        }
      }
    },
    "/api/course/package/{id}": {
      "get": {
        "tags": ["课程包"],
        "summary": "获取课程包详情",
        "description": "获取指定课程包的详细信息",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "课程包 ID" }
        ],
        "responses": {
          "200": { "description": "获取成功" }
        }
      }
    },
    "/api/course/package": {
      "post": {
        "tags": ["课程包"],
        "summary": "购买课程包",
        "description": "购买指定课程包（免费或创建订单）",
        "security": [{ "bearerAuth": [] }],
        "responses": {
          "200": { "description": "购买成功" }
        }
      }
    },
    "/api/community/posts": {
      "get": {
        "tags": ["社区"],
        "summary": "获取动态列表",
        "description": "获取社区动态列表",
        "parameters": [
          { "name": "type", "in": "query", "schema": { "type": "string", "enum": ["latest", "hot", "following"] }, "description": "列表类型" },
          { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 }, "description": "页码" }
        ],
        "responses": {
          "200": { "description": "获取成功" }
        }
      },
      "post": {
        "tags": ["社区"],
        "summary": "发布动态",
        "description": "发布新的社区动态",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["content"],
                "properties": {
                  "content": { "type": "string", "description": "动态内容", "maxLength": 2000 },
                  "images": { "type": "array", "items": { "type": "string" }, "description": "图片 URL 列表" },
                  "videoUrl": { "type": "string", "description": "视频 URL" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "发布成功" }
        }
      }
    },
    "/api/community/posts/{id}/like/{action}": {
      "post": {
        "tags": ["点赞"],
        "summary": "点赞/取消点赞",
        "description": "对指定动态进行点赞或取消点赞",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "动态 ID" },
          { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "enum": ["like", "unlike"] }, "description": "操作类型" }
        ],
        "responses": {
          "200": { "description": "操作成功" }
        }
      }
    },
    "/api/community/posts/{id}/comments": {
      "get": {
        "tags": ["评论"],
        "summary": "获取评论列表",
        "description": "获取指定动态的评论列表",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "动态 ID" }
        ],
        "responses": {
          "200": { "description": "获取成功" }
        }
      },
      "post": {
        "tags": ["评论"],
        "summary": "发表评论",
        "description": "对指定动态发表评论",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "动态 ID" }
        ],
        "responses": {
          "200": { "description": "评论成功" }
        }
      }
    },
    "/api/score/list": {
      "get": {
        "tags": ["评分"],
        "summary": "获取曲谱列表",
        "description": "获取所有曲谱列表",
        "parameters": [
          { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 }, "description": "页码" },
          { "name": "category", "in": "query", "schema": { "type": "string" }, "description": "曲谱分类" },
          { "name": "keyword", "in": "query", "schema": { "type": "string" }, "description": "搜索关键词" }
        ],
        "responses": {
          "200": { "description": "获取成功" }
        }
      }
    },
    "/api/score/{id}": {
      "get": {
        "tags": ["评分"],
        "summary": "获取曲谱详情",
        "description": "获取指定曲谱的详细信息",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "曲谱 ID" }
        ],
        "responses": {
          "200": { "description": "获取成功" }
        }
      }
    },
    "/api/messages": {
      "get": {
        "tags": ["消息"],
        "summary": "获取消息列表",
        "description": "获取当前用户的消息列表",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "type", "in": "query", "schema": { "type": "string", "enum": ["all", "comment", "like", "follow", "system"] }, "description": "消息类型" },
          { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 }, "description": "页码" }
        ],
        "responses": {
          "200": { "description": "获取成功" }
        }
      }
    },
    "/api/messages/unread-count": {
      "get": {
        "tags": ["消息"],
        "summary": "获取未读消息数",
        "description": "获取当前用户各类型未读消息数量",
        "security": [{ "bearerAuth": [] }],
        "responses": {
          "200": { "description": "获取成功" }
        }
      }
    },
    "/api/payment/create": {
      "post": {
        "tags": ["支付"],
        "summary": "创建支付订单",
        "description": "创建支付订单（支付宝/微信）",
        "security": [{ "bearerAuth": [] }],
        "responses": {
          "200": { "description": "订单创建成功" }
        }
      }
    },
    "/api/payment/orders": {
      "get": {
        "tags": ["支付"],
        "summary": "获取订单列表",
        "description": "获取当前用户的支付订单列表",
        "security": [{ "bearerAuth": [] }],
        "responses": {
          "200": { "description": "获取成功" }
        }
      }
    },
    "/api/admin/content/list": {
      "get": {
        "tags": ["管理"],
        "summary": "获取待审核内容",
        "description": "获取需要审核的内容列表（管理员）",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "type", "in": "query", "schema": { "type": "string", "enum": ["post", "comment", "score", "column"] }, "description": "内容类型" },
          { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "审核状态" }
        ],
        "responses": {
          "200": { "description": "获取成功" },
          "403": { "description": "无权限" }
        }
      }
    },
    "/api/admin/content/{type}/{id}": {
      "put": {
        "tags": ["管理"],
        "summary": "审核内容",
        "description": "对内容进行审核操作（管理员）",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "type", "in": "path", "required": true, "schema": { "type": "string" }, "description": "内容类型" },
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "内容 ID" }
        ],
        "responses": {
          "200": { "description": "操作成功" },
          "403": { "description": "无权限" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  }
}