openapi: 3.1.0

info:
  title: platform
  description: 后端服务 API 列表
  version: 1.0.0

servers:
  - url: 'http://192.168.3.42:8080'
    description: 本地开发环境

components:
  schemas:
    PageRequest:
      type: object
      properties:
        page:
          type: integer
          description: 页码，从1开始
          default: 1
        size:
          type: integer
          description: 每页条数
          default: 10
          maximum: 100

    PageResponse:
      type: object
      properties:
        total:
          type: integer
          description: 总记录数
        page:
          type: integer
          description: 当前页码
        size:
          type: integer
          description: 每页大小
        list:
          type: array
          description: 数据列表
          items:
            type: object
      required:
        - total
        - page
        - size
        - list

tags:
  - name: Auth
    description: 认证授权相关接口
  - name: User
    description: 用户相关接口
  - name: Channel
    description: 通道相关接口
  - name: Whitelist
    description: 白名单相关接口
  - name: Resource
    description: 套餐资源相关接口
  - name: Bill
    description: 账单相关接口
  - name: Trade
    description: 交易相关接口
  - name: Announcement
    description: 公告相关接口

paths:

  /api/auth/token:
    post:
      tags:
        - Auth
      summary: OAuth2 Token 端点
      description: 获取访问令牌，支持授权码、密码、客户端凭据、刷新令牌四种授权方式
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  description: 授权类型
                  enum: [ authorization_code, password, client_credentials, refresh_token ]
                client_id:
                  type: string
                  description: 客户端ID
                client_secret:
                  type: string
                  description: 客户端密钥
                code:
                  type: string
                  description: 授权码（authorization_code 模式使用）
                redirect_uri:
                  type: string
                  description: 重定向URI（authorization_code 模式使用）
                username:
                  type: string
                  description: 用户名（password 模式使用）
                password:
                  type: string
                  description: 密码（password 模式使用）
                refresh_token:
                  type: string
                  description: 刷新令牌（refresh_token 模式使用）
                scope:
                  type: string
                  description: 权限范围
              required:
                - grant_type
      responses:
        '200':
          description: 认证成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                    description: 访问令牌
                  refresh_token:
                    type: string
                    description: 刷新令牌
                  expires_in:
                    type: integer
                    description: 过期时间（秒）
                  token_type:
                    type: string
                    description: 令牌类型
                    default: Bearer
                  scope:
                    type: string
                    description: 授权范围
                required:
                  - access_token
                  - expires_in
                  - token_type
        '400':
            description: 接口请求失败
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    error:
                      type: integer
                      description: 错误码
                    error_description:
                      type: string
                      description: 错误描述
                  required:
                    - error
                    - error_description

  /api/auth/revoke:
    post:
      tags:
        - Auth
      summary: OAuth2 Revoke 端点
      description: 撤销访问令牌或刷新令牌
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: true
              properties:
                access_token:
                  type: string
                  description: 访问令牌
                  required: true
                refresh_token:
                  type: string
                  description: 刷新令牌
                  required: true
      responses:
        '200':
          description: 撤销成功
          content:
            text/plain:
              schema: false

  /api/auth/introspect:
    post:
      tags:
        - Auth
      summary: OAuth2 Introspect 端点
      description: 检查令牌的有效性和相关信息
      responses:
        '200':
          description: 检查成功
          content:
            application/json:
              schema:
                type: object

  /api/auth/verify/sms:
    post:
      tags:
        - Auth
      summary: 短信验证码验证
      description: 验证短信验证码
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: true
              properties:
                purpose:
                  type: string
                  description: 验证码用途
                  required: true
                phone:
                  type: string
                  description: 手机号码
                  required: true
      responses:
        '200':
          description: 验证成功
          content:
            text/plain:
              schema: false

  /api/user/update:
    post:
      tags:
        - User
      summary: 更新用户信息
      description: 更新用户基本信息

  /api/user/update/account:
    post:
      tags:
        - User
      summary: 更新账号信息
      description: 更新用户账号相关信息

  /api/user/update/password:
    post:
      tags:
        - User
      summary: 更新密码
      description: 更新用户密码

  /api/user/identify:
    post:
      tags:
        - User
      summary: 用户身份认证
      description: 发起用户身份认证

  /api/user/identify/callback:
    post:
      tags:
        - User
      summary: 身份认证回调
      description: 身份认证回调处理

  /api/user/recharge/prepare/alipay:
    post:
      tags:
        - User
      summary: 准备支付宝充值
      description: 准备使用支付宝进行账户充值

  /api/user/recharge/confirm/alipay:
    post:
      tags:
        - User
      summary: 确认支付宝充值
      description: 确认支付宝充值结果

  /api/user/recharge/prepare/wechat:
    post:
      tags:
        - User
      summary: 准备微信充值
      description: 准备使用微信进行账户充值

  /api/user/recharge/confirm/wechat:
    post:
      tags:
        - User
      summary: 确认微信充值
      description: 确认微信充值结果

  /api/channel/list:
    post:
      tags:
        - Channel
      summary: 获取通道列表
      description: 获取所有可用通道的列表

  /api/channel/create:
    post:
      tags:
        - Channel
      summary: 创建通道
      description: 创建新的通道

  /api/channel/remove:
    post:
      tags:
        - Channel
      summary: 删除通道
      description: 删除指定的通道

  /api/whitelist/list:
    post:
      tags:
        - Whitelist
      summary: 获取白名单列表
      description: 获取所有白名单记录
      
  /api/whitelist/create:
    post:
      tags:
        - Whitelist
      summary: 创建白名单
      description: 创建新的白名单记录

  /api/whitelist/update:
    post:
      tags:
        - Whitelist
      summary: 更新白名单
      description: 更新指定的白名单记录

  /api/whitelist/remove:
    post:
      tags:
        - Whitelist
      summary: 删除白名单
      description: 删除指定的白名单记录

  /api/resource/list/pss:
    post:
      tags:
        - Resource
      summary: 获取套餐列表
      description: 获取所有可用套餐列表

  /api/resource/all:
    post:
      tags:
        - Resource
      summary: 获取所有资源
      description: 获取所有可用资源信息

  /api/resource/create/balance:
    post:
      tags:
        - Resource
      summary: 使用余额创建资源
      description: 使用账户余额购买资源


  /api/resource/prepare/alipay:
    post:
      tags:
        - Resource
      summary: 准备支付宝购买资源
      description: 准备使用支付宝购买资源

  /api/resource/create/alipay:
    post:
      tags:
        - Resource
      summary: 确认支付宝购买资源
      description: 确认使用支付宝购买资源

  /api/resource/prepare/wechat:
    post:
      tags:
        - Resource
      summary: 准备微信购买资源
      description: 准备使用微信购买资源

  /api/resource/create/wechat:
    post:
      tags:
        - Resource
      summary: 确认微信购买资源
      description: 确认使用微信购买资源

  /api/bill/list:
    post:
      tags:
        - Bill
      summary: 获取账单列表
      description: 获取用户账单记录列表

  /api/trade/callback/alipay:
    post:
      tags:
        - Trade
      summary: 支付宝交易回调
      description: 处理支付宝交易回调通知

  /api/announcement/list:
    post:
      tags:
        - Announcement
      summary: 获取公告列表
      description: 获取系统公告列表