openapi: 3.0.3
info:
  title: Base API
  description: AI 开发脚手架后端 API
  version: 1.0.0
servers:
  - url: http://localhost:8888/api/v1
    description: 本地开发

security:
  - BearerAuth: []

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

  schemas:
    Response:
      type: object
      properties:
        code: { type: integer }
        message: { type: string }
        success: { type: boolean }

    LoginResponse:
      type: object
      properties:
        code: { type: integer }
        message: { type: string }
        success: { type: boolean }
        token: { type: string }

    UserInfo:
      type: object
      properties:
        id: { type: integer, format: int64 }
        username: { type: string }
        email: { type: string }
        phone: { type: string }
        role: { type: string }
        source: { type: string }
        remark: { type: string }
        status: { type: integer }
        createdAt: { type: string }
        updatedAt: { type: string }

    UserListResponse:
      type: object
      properties:
        total: { type: integer, format: int64 }
        list:
          type: array
          items: { $ref: '#/components/schemas/UserInfo' }

    GetProfileResponse:
      type: object
      properties:
        id: { type: integer, format: int64 }
        username: { type: string }
        email: { type: string }
        phone: { type: string }
        avatar: { type: string }
        bio: { type: string }
        status: { type: integer }
        createdAt: { type: string }
        updatedAt: { type: string }

    DashboardStatsResponse:
      type: object
      properties:
        totalUsers: { type: integer, format: int64 }
        activeUsers: { type: integer, format: int64 }
        systemLoad: { type: integer }
        dbStatus: { type: string }
        userGrowth: { type: integer }

    Activity:
      type: object
      properties:
        id: { type: integer, format: int64 }
        user: { type: string }
        action: { type: string }
        time: { type: string }
        status: { type: string }

    FileInfo:
      type: object
      properties:
        id: { type: integer, format: int64 }
        name: { type: string }
        key: { type: string }
        size: { type: integer, format: int64 }
        mimeType: { type: string }
        category: { type: string }
        isPublic: { type: boolean }
        userId: { type: integer, format: int64 }
        storageType: { type: string }
        url: { type: string }
        createdAt: { type: string }
        updatedAt: { type: string }

    MenuItem:
      type: object
      properties:
        id: { type: integer, format: int64 }
        parentId: { type: integer, format: int64 }
        name: { type: string }
        path: { type: string }
        icon: { type: string }
        component: { type: string }
        type: { type: string }
        sortOrder: { type: integer }
        visible: { type: boolean }
        status: { type: integer }
        children:
          type: array
          items: { $ref: '#/components/schemas/MenuItem' }
        createdAt: { type: string }
        updatedAt: { type: string }

    RoleInfo:
      type: object
      properties:
        id: { type: integer, format: int64 }
        name: { type: string }
        code: { type: string }
        description: { type: string }
        isSystem: { type: boolean }
        sortOrder: { type: integer }
        status: { type: integer }
        createdAt: { type: string }
        updatedAt: { type: string }

    OrgInfo:
      type: object
      properties:
        id: { type: integer, format: int64 }
        parentId: { type: integer, format: int64 }
        name: { type: string }
        code: { type: string }
        leader: { type: string }
        phone: { type: string }
        email: { type: string }
        sortOrder: { type: integer }
        status: { type: integer }
        memberCount: { type: integer, format: int64 }
        children:
          type: array
          items: { $ref: '#/components/schemas/OrgInfo' }
        createdAt: { type: string }
        updatedAt: { type: string }

    OrgMember:
      type: object
      properties:
        userId: { type: integer, format: int64 }
        username: { type: string }
        email: { type: string }
        phone: { type: string }
        roleId: { type: integer, format: int64 }
        roleName: { type: string }
        roleCode: { type: string }
        createdAt: { type: string }

    UserOrgInfo:
      type: object
      properties:
        orgId: { type: integer, format: int64 }
        orgName: { type: string }
        roleId: { type: integer, format: int64 }
        roleName: { type: string }
        roleCode: { type: string }

    AIConversationInfo:
      type: object
      properties:
        id: { type: integer, format: int64 }
        title: { type: string }
        modelId: { type: string }
        providerId: { type: integer, format: int64 }
        totalTokens: { type: integer, format: int64 }
        totalCost: { type: number, format: double }
        isArchived: { type: boolean }
        createdAt: { type: string }
        updatedAt: { type: string }

    AIMessageInfo:
      type: object
      properties:
        id: { type: integer, format: int64 }
        conversationId: { type: integer, format: int64 }
        role: { type: string }
        content: { type: string }
        tokenCount: { type: integer }
        cost: { type: number, format: double }
        modelId: { type: string }
        latencyMs: { type: integer }
        createdAt: { type: string }

    AIProviderInfo:
      type: object
      properties:
        id: { type: integer, format: int64 }
        name: { type: string }
        displayName: { type: string }
        baseUrl: { type: string }
        sdkType: { type: string }
        protocol: { type: string }
        isActive: { type: boolean }
        sortOrder: { type: integer }
        createdAt: { type: string }
        updatedAt: { type: string }

    AIModelInfo:
      type: object
      properties:
        id: { type: integer, format: int64 }
        providerId: { type: integer, format: int64 }
        providerName: { type: string }
        modelId: { type: string }
        displayName: { type: string }
        inputPrice: { type: number, format: double }
        outputPrice: { type: number, format: double }
        maxTokens: { type: integer }
        contextWindow: { type: integer }
        supportsStream: { type: boolean }
        supportsVision: { type: boolean }

    AIApiKeyInfo:
      type: object
      properties:
        id: { type: integer, format: int64 }
        providerId: { type: integer, format: int64 }
        providerName: { type: string }
        userId: { type: integer, format: int64 }
        keyPreview: { type: string }
        isActive: { type: boolean }
        remark: { type: string }
        createdAt: { type: string }

    AIQuotaInfo:
      type: object
      properties:
        balance: { type: number, format: double }
        totalRecharged: { type: number, format: double }
        totalConsumed: { type: number, format: double }
        frozenAmount: { type: number, format: double }

    AIQuotaUserInfo:
      type: object
      properties:
        userId: { type: integer, format: int64 }
        username: { type: string }
        balance: { type: number, format: double }
        totalRecharged: { type: number, format: double }
        totalConsumed: { type: number, format: double }
        frozenAmount: { type: number, format: double }

    AIUsageRecordInfo:
      type: object
      properties:
        id: { type: integer, format: int64 }
        userId: { type: integer, format: int64 }
        username: { type: string }
        providerId: { type: integer, format: int64 }
        providerName: { type: string }
        modelId: { type: string }
        inputTokens: { type: integer }
        outputTokens: { type: integer }
        cost: { type: number, format: double }
        status: { type: string }
        latencyMs: { type: integer }
        errorMessage: { type: string }
        createdAt: { type: string }

    AIUsageStatsResponse:
      type: object
      properties:
        totalCalls: { type: integer, format: int64 }
        totalTokens: { type: integer, format: int64 }
        totalCost: { type: number, format: double }
        totalUsers: { type: integer, format: int64 }
        modelStats:
          type: array
          items:
            type: object
            properties:
              modelId: { type: string }
              calls: { type: integer, format: int64 }
              inputTokens: { type: integer, format: int64 }
              outputTokens: { type: integer, format: int64 }
              totalCost: { type: number, format: double }
        dailyStats:
          type: array
          items:
            type: object
            properties:
              date: { type: string }
              calls: { type: integer, format: int64 }
              totalTokens: { type: integer, format: int64 }
              totalCost: { type: number, format: double }

  parameters:
    IdPath:
      name: id
      in: path
      required: true
      schema: { type: integer, format: int64 }
    Page:
      name: page
      in: query
      schema: { type: integer, default: 1 }
    PageSize:
      name: pageSize
      in: query
      schema: { type: integer, default: 10 }

tags:
  - name: 认证
    description: 注册、登录、Token 刷新
  - name: 用户管理
    description: 用户 CRUD (admin)
  - name: 个人中心
    description: 个人资料、密码、机构
  - name: 仪表盘
    description: 统计数据、活动日志
  - name: 文件管理
    description: 文件上传、列表、删除
  - name: 菜单管理
    description: 菜单 CRUD、排序
  - name: 角色管理
    description: 角色 CRUD、菜单分配
  - name: 机构管理
    description: 机构 CRUD、成员管理
  - name: AI 对话
    description: AI 聊天、对话、配额
  - name: AI 密钥
    description: 用户 API Key 管理
  - name: AI 管理
    description: 平台/模型/额度/统计/系统密钥 (admin)

paths:
  # ============ 认证 ============
  /register:
    post:
      tags: [认证]
      summary: 用户注册
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [username, password, phone]
              properties:
                username: { type: string, minLength: 3, maxLength: 32 }
                password: { type: string, minLength: 6, maxLength: 32 }
                phone: { type: string }
                email: { type: string }
      responses:
        '200':
          description: 注册成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/UserInfo' }

  /login:
    post:
      tags: [认证]
      summary: 用户登录
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [account, password]
              properties:
                account: { type: string }
                password: { type: string, minLength: 6, maxLength: 32 }
      responses:
        '200':
          description: 登录成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/LoginResponse' }

  /refresh:
    post:
      tags: [认证]
      summary: 刷新 Token
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [token]
              properties:
                token: { type: string }
      responses:
        '200':
          description: 刷新成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/LoginResponse' }

  # ============ 用户管理 ============
  /user:
    post:
      tags: [用户管理]
      summary: 创建用户
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [username, email, password]
              properties:
                username: { type: string, minLength: 3, maxLength: 32 }
                email: { type: string, format: email }
                password: { type: string, minLength: 6, maxLength: 32 }
                phone: { type: string }
                role: { type: string }
                remark: { type: string }
      responses:
        '200':
          description: 创建成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/UserInfo' }

  /users:
    get:
      tags: [用户管理]
      summary: 获取用户列表
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
        - name: keyword
          in: query
          schema: { type: string }
        - name: status
          in: query
          schema: { type: integer }
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/UserListResponse' }

  /user/{id}:
    get:
      tags: [用户管理]
      summary: 获取用户详情
      parameters:
        - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/UserInfo' }
    put:
      tags: [用户管理]
      summary: 更新用户信息
      parameters:
        - $ref: '#/components/parameters/IdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username: { type: string }
                email: { type: string }
                phone: { type: string }
                status: { type: integer }
                role: { type: string }
                remark: { type: string }
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/UserInfo' }
    delete:
      tags: [用户管理]
      summary: 删除用户
      parameters:
        - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: 删除成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Response' }

  # ============ 个人中心 ============
  /profile/me:
    get:
      tags: [个人中心]
      summary: 获取个人信息
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/GetProfileResponse' }
    put:
      tags: [个人中心]
      summary: 更新个人资料
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username: { type: string, minLength: 3, maxLength: 32 }
                phone: { type: string }
                avatar: { type: string }
                bio: { type: string }
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/GetProfileResponse' }

  /profile/password:
    post:
      tags: [个人中心]
      summary: 修改密码
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [oldPassword, newPassword]
              properties:
                oldPassword: { type: string, minLength: 6, maxLength: 32 }
                newPassword: { type: string, minLength: 6, maxLength: 32 }
      responses:
        '200':
          description: 修改成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Response' }

  /profile/orgs:
    get:
      tags: [个人中心]
      summary: 获取我的机构列表
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  list:
                    type: array
                    items: { $ref: '#/components/schemas/UserOrgInfo' }

  /profile/current-org:
    put:
      tags: [个人中心]
      summary: 切换当前机构
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [orgId]
              properties:
                orgId: { type: integer, format: int64 }
      responses:
        '200':
          description: 切换成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  token: { type: string }

  # ============ 仪表盘 ============
  /dashboard/stats:
    get:
      tags: [仪表盘]
      summary: 获取仪表盘统计数据
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/DashboardStatsResponse' }

  /dashboard/activities:
    get:
      tags: [仪表盘]
      summary: 获取最近活动列表
      parameters:
        - name: limit
          in: query
          schema: { type: integer, default: 10 }
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  activities:
                    type: array
                    items: { $ref: '#/components/schemas/Activity' }

  # ============ 文件管理 ============
  /file/upload:
    post:
      tags: [文件管理]
      summary: 上传文件
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file: { type: string, format: binary }
                category: { type: string }
                isPublic: { type: boolean }
      responses:
        '200':
          description: 上传成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/FileInfo' }

  /files:
    get:
      tags: [文件管理]
      summary: 获取文件列表
      parameters:
        - $ref: '#/components/parameters/Page'
        - { name: pageSize, in: query, schema: { type: integer, default: 20 } }
        - { name: keyword, in: query, schema: { type: string } }
        - { name: category, in: query, schema: { type: string } }
        - { name: mimeType, in: query, schema: { type: string } }
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  total: { type: integer, format: int64 }
                  list:
                    type: array
                    items: { $ref: '#/components/schemas/FileInfo' }

  /file/{id}:
    get:
      tags: [文件管理]
      summary: 获取文件详情
      parameters:
        - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/FileInfo' }
    put:
      tags: [文件管理]
      summary: 更新文件信息
      parameters:
        - $ref: '#/components/parameters/IdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string }
                category: { type: string }
                isPublic: { type: boolean }
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/FileInfo' }
    delete:
      tags: [文件管理]
      summary: 删除文件
      parameters:
        - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: 删除成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Response' }

  /file/{id}/url:
    get:
      tags: [文件管理]
      summary: 获取文件访问 URL
      parameters:
        - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  url: { type: string }

  # ============ 菜单管理 ============
  /menus/current:
    get:
      tags: [菜单管理]
      summary: 获取当前用户可见菜单
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  list:
                    type: array
                    items: { $ref: '#/components/schemas/MenuItem' }

  /menus:
    get:
      tags: [菜单管理]
      summary: 获取全部菜单列表
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  list:
                    type: array
                    items: { $ref: '#/components/schemas/MenuItem' }

  /menu:
    post:
      tags: [菜单管理]
      summary: 创建菜单
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                parentId: { type: integer, format: int64 }
                name: { type: string }
                path: { type: string }
                icon: { type: string }
                component: { type: string }
                type: { type: string }
                sortOrder: { type: integer }
                visible: { type: boolean }
      responses:
        '200':
          description: 创建成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/MenuItem' }

  /menu/{id}:
    put:
      tags: [菜单管理]
      summary: 更新菜单
      parameters:
        - $ref: '#/components/parameters/IdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                parentId: { type: integer, format: int64 }
                name: { type: string }
                path: { type: string }
                icon: { type: string }
                component: { type: string }
                type: { type: string }
                sortOrder: { type: integer }
                visible: { type: boolean }
                status: { type: integer }
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/MenuItem' }
    delete:
      tags: [菜单管理]
      summary: 删除菜单
      parameters:
        - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: 删除成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Response' }

  /menus/sort:
    put:
      tags: [菜单管理]
      summary: 批量排序菜单
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [items]
              properties:
                items:
                  type: array
                  items:
                    type: object
                    required: [id, sortOrder, parentId]
                    properties:
                      id: { type: integer, format: int64 }
                      sortOrder: { type: integer }
                      parentId: { type: integer, format: int64 }
      responses:
        '200':
          description: 排序成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Response' }

  # ============ 角色管理 ============
  /roles:
    get:
      tags: [角色管理]
      summary: 获取角色列表
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  list:
                    type: array
                    items: { $ref: '#/components/schemas/RoleInfo' }

  /role:
    post:
      tags: [角色管理]
      summary: 创建角色
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, code]
              properties:
                name: { type: string }
                code: { type: string }
                description: { type: string }
                sortOrder: { type: integer }
      responses:
        '200':
          description: 创建成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RoleInfo' }

  /role/{id}:
    put:
      tags: [角色管理]
      summary: 更新角色
      parameters:
        - $ref: '#/components/parameters/IdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string }
                description: { type: string }
                sortOrder: { type: integer }
                status: { type: integer }
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RoleInfo' }
    delete:
      tags: [角色管理]
      summary: 删除角色
      parameters:
        - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: 删除成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Response' }

  /role/{id}/menus:
    get:
      tags: [角色管理]
      summary: 获取角色菜单
      parameters:
        - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  menuIds:
                    type: array
                    items: { type: integer, format: int64 }
    put:
      tags: [角色管理]
      summary: 设置角色菜单
      parameters:
        - $ref: '#/components/parameters/IdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [menuIds]
              properties:
                menuIds:
                  type: array
                  items: { type: integer, format: int64 }
      responses:
        '200':
          description: 设置成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Response' }

  # ============ 机构管理 ============
  /organizations:
    get:
      tags: [机构管理]
      summary: 获取机构列表
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  list:
                    type: array
                    items: { $ref: '#/components/schemas/OrgInfo' }

  /organization:
    post:
      tags: [机构管理]
      summary: 创建机构
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, code]
              properties:
                parentId: { type: integer, format: int64 }
                name: { type: string }
                code: { type: string }
                leader: { type: string }
                phone: { type: string }
                email: { type: string }
                sortOrder: { type: integer }
      responses:
        '200':
          description: 创建成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OrgInfo' }

  /organization/{id}:
    put:
      tags: [机构管理]
      summary: 更新机构
      parameters:
        - $ref: '#/components/parameters/IdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                parentId: { type: integer, format: int64 }
                name: { type: string }
                code: { type: string }
                leader: { type: string }
                phone: { type: string }
                email: { type: string }
                sortOrder: { type: integer }
                status: { type: integer }
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OrgInfo' }
    delete:
      tags: [机构管理]
      summary: 删除机构
      parameters:
        - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: 删除成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Response' }

  /organization/{id}/members:
    get:
      tags: [机构管理]
      summary: 获取机构成员
      parameters:
        - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  list:
                    type: array
                    items: { $ref: '#/components/schemas/OrgMember' }

  /organization/{id}/member:
    post:
      tags: [机构管理]
      summary: 添加机构成员
      parameters:
        - $ref: '#/components/parameters/IdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [userId, roleId]
              properties:
                userId: { type: integer, format: int64 }
                roleId: { type: integer, format: int64 }
      responses:
        '200':
          description: 添加成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Response' }

  /organization/{id}/member/{userId}:
    put:
      tags: [机构管理]
      summary: 更新成员角色
      parameters:
        - $ref: '#/components/parameters/IdPath'
        - name: userId
          in: path
          required: true
          schema: { type: integer, format: int64 }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [roleId]
              properties:
                roleId: { type: integer, format: int64 }
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Response' }
    delete:
      tags: [机构管理]
      summary: 移除机构成员
      parameters:
        - $ref: '#/components/parameters/IdPath'
        - name: userId
          in: path
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200':
          description: 移除成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Response' }

  # ============ AI 对话 ============
  /ai/chat/completions:
    post:
      tags: [AI 对话]
      summary: AI 对话补全 (支持 SSE 流式)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [model, messages]
              properties:
                model: { type: string }
                messages:
                  type: array
                  items:
                    type: object
                    required: [role, content]
                    properties:
                      role: { type: string }
                      content: { type: string }
                stream: { type: boolean }
                max_tokens: { type: integer }
                temperature: { type: number }
                conversation_id: { type: integer, format: int64 }
      responses:
        '200':
          description: 对话成功 (stream=true 时为 SSE 流)

  /ai/conversations:
    get:
      tags: [AI 对话]
      summary: 获取对话列表
      parameters:
        - $ref: '#/components/parameters/Page'
        - { name: pageSize, in: query, schema: { type: integer, default: 20 } }
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  list:
                    type: array
                    items: { $ref: '#/components/schemas/AIConversationInfo' }
                  total: { type: integer, format: int64 }

  /ai/conversation:
    post:
      tags: [AI 对话]
      summary: 创建对话
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title: { type: string }
                modelId: { type: string }
      responses:
        '200':
          description: 创建成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AIConversationInfo' }

  /ai/conversation/{id}:
    get:
      tags: [AI 对话]
      summary: 获取对话详情
      parameters:
        - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  conversation: { $ref: '#/components/schemas/AIConversationInfo' }
                  messages:
                    type: array
                    items: { $ref: '#/components/schemas/AIMessageInfo' }
    put:
      tags: [AI 对话]
      summary: 更新对话标题
      parameters:
        - $ref: '#/components/parameters/IdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [title]
              properties:
                title: { type: string }
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AIConversationInfo' }
    delete:
      tags: [AI 对话]
      summary: 删除对话
      parameters:
        - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: 删除成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Response' }

  /ai/models:
    get:
      tags: [AI 对话]
      summary: 获取可用模型列表
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  list:
                    type: array
                    items: { $ref: '#/components/schemas/AIModelInfo' }

  /ai/quota/me:
    get:
      tags: [AI 对话]
      summary: 获取我的配额
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AIQuotaInfo' }

  /ai/quota/records:
    get:
      tags: [AI 对话]
      summary: 获取我的用量记录
      parameters:
        - $ref: '#/components/parameters/Page'
        - { name: pageSize, in: query, schema: { type: integer, default: 20 } }
        - { name: userId, in: query, schema: { type: integer, format: int64 } }
        - { name: modelId, in: query, schema: { type: string } }
        - { name: status, in: query, schema: { type: string } }
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  list:
                    type: array
                    items: { $ref: '#/components/schemas/AIUsageRecordInfo' }
                  total: { type: integer, format: int64 }

  /ai/usage/export:
    get:
      tags: [AI 对话]
      summary: 导出用量记录 CSV
      parameters:
        - $ref: '#/components/parameters/Page'
        - { name: pageSize, in: query, schema: { type: integer, default: 20 } }
        - { name: userId, in: query, schema: { type: integer, format: int64 } }
        - { name: modelId, in: query, schema: { type: string } }
        - { name: status, in: query, schema: { type: string } }
      responses:
        '200':
          description: CSV 文件下载
          content:
            text/csv:
              schema: { type: string }

  # ============ AI 密钥 (用户) ============
  /ai/keys:
    get:
      tags: [AI 密钥]
      summary: 获取我的 API Key 列表
      parameters:
        - $ref: '#/components/parameters/Page'
        - { name: pageSize, in: query, schema: { type: integer, default: 20 } }
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  list:
                    type: array
                    items: { $ref: '#/components/schemas/AIApiKeyInfo' }
                  total: { type: integer, format: int64 }

  /ai/key:
    post:
      tags: [AI 密钥]
      summary: 添加 API Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [providerId, keyValue]
              properties:
                providerId: { type: integer, format: int64 }
                keyValue: { type: string }
                remark: { type: string }
      responses:
        '200':
          description: 添加成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AIApiKeyInfo' }

  /ai/key/{id}:
    put:
      tags: [AI 密钥]
      summary: 更新 API Key
      parameters:
        - $ref: '#/components/parameters/IdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                keyValue: { type: string }
                isActive: { type: boolean }
                remark: { type: string }
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AIApiKeyInfo' }
    delete:
      tags: [AI 密钥]
      summary: 删除 API Key
      parameters:
        - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: 删除成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Response' }

  # ============ AI 管理 (admin) ============
  /ai/providers:
    get:
      tags: [AI 管理]
      summary: 获取 AI 平台列表
      parameters:
        - $ref: '#/components/parameters/Page'
        - { name: pageSize, in: query, schema: { type: integer, default: 50 } }
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  list:
                    type: array
                    items: { $ref: '#/components/schemas/AIProviderInfo' }
                  total: { type: integer, format: int64 }

  /ai/provider:
    post:
      tags: [AI 管理]
      summary: 创建 AI 平台
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, displayName, baseUrl, sdkType]
              properties:
                name: { type: string }
                displayName: { type: string }
                baseUrl: { type: string }
                sdkType: { type: string }
                protocol: { type: string, default: openai }
                sortOrder: { type: integer }
      responses:
        '200':
          description: 创建成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AIProviderInfo' }

  /ai/provider/{id}:
    put:
      tags: [AI 管理]
      summary: 更新 AI 平台
      parameters:
        - $ref: '#/components/parameters/IdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                displayName: { type: string }
                baseUrl: { type: string }
                sdkType: { type: string }
                protocol: { type: string }
                isActive: { type: boolean }
                sortOrder: { type: integer }
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AIProviderInfo' }
    delete:
      tags: [AI 管理]
      summary: 删除 AI 平台
      parameters:
        - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: 删除成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Response' }

  /ai/model:
    post:
      tags: [AI 管理]
      summary: 创建 AI 模型
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [providerId, modelId, displayName, inputPrice, outputPrice]
              properties:
                providerId: { type: integer, format: int64 }
                modelId: { type: string }
                displayName: { type: string }
                inputPrice: { type: number, format: double }
                outputPrice: { type: number, format: double }
                maxTokens: { type: integer, default: 4096 }
                contextWindow: { type: integer, default: 128000 }
                supportsStream: { type: boolean }
                supportsVision: { type: boolean }
      responses:
        '200':
          description: 创建成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AIModelInfo' }

  /ai/model/{id}:
    put:
      tags: [AI 管理]
      summary: 更新 AI 模型
      parameters:
        - $ref: '#/components/parameters/IdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                displayName: { type: string }
                inputPrice: { type: number, format: double }
                outputPrice: { type: number, format: double }
                maxTokens: { type: integer }
                contextWindow: { type: integer }
                supportsStream: { type: boolean }
                supportsVision: { type: boolean }
                isActive: { type: boolean }
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AIModelInfo' }
    delete:
      tags: [AI 管理]
      summary: 删除 AI 模型
      parameters:
        - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: 删除成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Response' }

  /ai/quotas:
    get:
      tags: [AI 管理]
      summary: 获取用户额度列表
      parameters:
        - $ref: '#/components/parameters/Page'
        - { name: pageSize, in: query, schema: { type: integer, default: 20 } }
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  list:
                    type: array
                    items: { $ref: '#/components/schemas/AIQuotaUserInfo' }
                  total: { type: integer, format: int64 }

  /ai/quota/recharge:
    post:
      tags: [AI 管理]
      summary: 充值用户额度
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [userId, amount]
              properties:
                userId: { type: integer, format: int64 }
                amount: { type: number, format: double }
                remark: { type: string }
      responses:
        '200':
          description: 充值成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Response' }

  /ai/stats:
    get:
      tags: [AI 管理]
      summary: 获取 AI 使用统计
      parameters:
        - name: days
          in: query
          schema: { type: integer, default: 30 }
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AIUsageStatsResponse' }

  /ai/system-keys:
    get:
      tags: [AI 管理]
      summary: 获取系统密钥列表
      parameters:
        - $ref: '#/components/parameters/Page'
        - { name: pageSize, in: query, schema: { type: integer, default: 20 } }
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  list:
                    type: array
                    items: { $ref: '#/components/schemas/AIApiKeyInfo' }
                  total: { type: integer, format: int64 }

  /ai/system-key:
    post:
      tags: [AI 管理]
      summary: 创建系统密钥
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [providerId, keyValue]
              properties:
                providerId: { type: integer, format: int64 }
                keyValue: { type: string }
                remark: { type: string }
      responses:
        '200':
          description: 创建成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AIApiKeyInfo' }

  /ai/system-key/{id}:
    put:
      tags: [AI 管理]
      summary: 更新系统密钥
      parameters:
        - $ref: '#/components/parameters/IdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                keyValue: { type: string }
                isActive: { type: boolean }
                remark: { type: string }
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AIApiKeyInfo' }
    delete:
      tags: [AI 管理]
      summary: 删除系统密钥
      parameters:
        - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: 删除成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Response' }