openapi: 3.0.3
info:
  title: 小智ESP32后端服务API
  description: |
    小智ESP32智能硬件后端管理服务API文档

    ## 认证方式
    - JWT Bearer Token认证
    - 通过 `/user/login` 接口获取token

    ## 权限级别
    - `sys:role:normal`: 普通用户权限
    - `sys:role:superAdmin`: 超级管理员权限
  version: 1.0.0
  contact:
    name: 小智ESP32项目组
  license:
    name: MIT

servers:
  - url: http://localhost:8002
    description: 本地开发环境
  - url: https://api.xiaozhi.com
    description: 生产环境

security:
  - BearerAuth: []

paths:
  # =================== 认证相关 ===================
  /user/login:
    post:
      tags:
        - 用户认证
      summary: 用户登录
      description: 用户登录获取JWT令牌
      operationId: userLogin
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginDTO'
      responses:
        '200':
          description: 登录成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/TokenDTO'
        '400':
          $ref: '#/components/responses/BadRequest'

  /user/register:
    post:
      tags:
        - 用户认证
      summary: 用户注册
      operationId: userRegister
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginDTO'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'

  /user/info:
    get:
      tags:
        - 用户认证
      summary: 获取当前用户信息
      operationId: getUserInfo
      responses:
        '200':
          description: 用户信息
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/UserDetail'

  /user/captcha:
    get:
      tags:
        - 用户认证
      summary: 获取图片验证码
      operationId: getCaptcha
      security: []
      parameters:
        - name: uuid
          in: query
          required: true
          schema:
            type: string
          example: uuid-12345
      responses:
        '200':
          description: 验证码图片
          content:
            image/jpeg:
              schema:
                type: string
                format: binary

  # =================== 智能体管理 ===================
  /agent/list:
    get:
      tags:
        - 智能体管理
      summary: 获取用户智能体列表
      operationId: getUserAgentList
      responses:
        '200':
          description: 智能体列表
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/AgentDTO'

  /agent:
    post:
      tags:
        - 智能体管理
      summary: 创建智能体
      operationId: createAgent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentCreateDTO'
      responses:
        '200':
          description: 创建成功，返回智能体ID
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      data:
                        type: string
                        example: AGT_1234567890

  /agent/{id}:
    get:
      tags:
        - 智能体管理
      summary: 获取智能体详情
      operationId: getAgentDetails
      parameters:
        - $ref: '#/components/parameters/AgentId'
      responses:
        '200':
          description: 智能体详情
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/AgentInfoVO'

    put:
      tags:
        - 智能体管理
      summary: 更新智能体
      operationId: updateAgent
      parameters:
        - $ref: '#/components/parameters/AgentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentUpdateDTO'
      responses:
        '200':
          $ref: '#/components/responses/Success'

    delete:
      tags:
        - 智能体管理
      summary: 删除智能体
      operationId: deleteAgent
      parameters:
        - $ref: '#/components/parameters/AgentId'
      responses:
        '200':
          $ref: '#/components/responses/Success'

  /agent/saveMemory/{macAddress}:
    put:
      tags:
        - 智能体管理
      summary: 更新智能体记忆
      operationId: updateAgentMemory
      parameters:
        - name: macAddress
          in: path
          required: true
          schema:
            type: string
          example: 'AA:BB:CC:DD:EE:FF'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentMemoryDTO'
      responses:
        '200':
          $ref: '#/components/responses/Success'

  /agent/template:
    get:
      tags:
        - 智能体管理
      summary: 获取智能体模板列表
      operationId: getAgentTemplates
      responses:
        '200':
          description: 模板列表
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/AgentTemplateEntity'

  # =================== 设备管理 ===================
  /device/register:
    post:
      tags:
        - 设备管理
      summary: 设备注册
      operationId: registerDevice
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceRegisterDTO'
      responses:
        '200':
          description: 注册成功，返回验证码
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      data:
                        type: string
                        example: '123456'
                        description: 6位数验证码

  /device/bind/{agentId}/{deviceCode}:
    post:
      tags:
        - 设备管理
      summary: 绑定设备到智能体
      operationId: bindDevice
      parameters:
        - $ref: '#/components/parameters/AgentId'
        - name: deviceCode
          in: path
          required: true
          schema:
            type: string
          example: '123456'
      responses:
        '200':
          $ref: '#/components/responses/Success'

  /device/bind/{agentId}:
    get:
      tags:
        - 设备管理
      summary: 获取智能体绑定的设备列表
      operationId: getBoundDevices
      parameters:
        - $ref: '#/components/parameters/AgentId'
      responses:
        '200':
          description: 绑定设备列表
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/DeviceEntity'

  /device/unbind:
    post:
      tags:
        - 设备管理
      summary: 解绑设备
      operationId: unbindDevice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceUnBindDTO'
      responses:
        '200':
          $ref: '#/components/responses/Success'

  # =================== OTA管理 ===================
  /ota/:
    post:
      tags:
        - OTA管理
      summary: 设备OTA检查
      operationId: checkOTA
      security: []
      parameters:
        - name: Device-Id
          in: header
          required: true
          schema:
            type: string
          example: device123
        - name: Client-Id
          in: header
          schema:
            type: string
          example: client456
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceReportReqDTO'
      responses:
        '200':
          description: OTA检查结果
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/DeviceReportRespDTO'

    get:
      tags:
        - OTA管理
      summary: 获取OTA状态
      operationId: getOTAStatus
      security: []
      responses:
        '200':
          $ref: '#/components/responses/Success'

  /ota/activate:
    post:
      tags:
        - OTA管理
      summary: 设备快速激活检查
      operationId: quickActivateCheck
      security: []
      parameters:
        - name: Device-Id
          in: header
          required: true
          schema:
            type: string
        - name: Client-Id
          in: header
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/Success'

  # =================== 模型管理 ===================
  /models/names:
    get:
      tags:
        - 模型管理
      summary: 获取模型名称列表
      operationId: getModelNames
      parameters:
        - name: modelType
          in: query
          schema:
            type: string
          example: LLM
        - name: modelName
          in: query
          schema:
            type: string
          example: ChatGLM
      responses:
        '200':
          description: 模型名称列表
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/ModelBasicInfoDTO'

  /models/{modelType}/provideTypes:
    get:
      tags:
        - 模型管理
      summary: 获取模型提供商类型
      operationId: getModelProviderTypes
      security:
        - BearerAuth: ['sys:role:superAdmin']
      parameters:
        - name: modelType
          in: path
          required: true
          schema:
            type: string
          example: LLM
      responses:
        '200':
          description: 提供商类型列表
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/ModelProviderDTO'

  /models/list:
    get:
      tags:
        - 模型管理
      summary: 获取模型配置列表
      operationId: getModelConfigList
      security:
        - BearerAuth: ['sys:role:superAdmin']
      parameters:
        - name: modelType
          in: query
          schema:
            type: string
        - name: modelName
          in: query
          schema:
            type: string
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: 模型配置分页列表
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/PageData'

  # =================== 服务端管理 ===================
  /admin/server/server-list:
    get:
      tags:
        - 服务端管理
      summary: 获取WebSocket服务器列表
      operationId: getWebSocketServerList
      security:
        - BearerAuth: ['sys:role:superAdmin']
      responses:
        '200':
          description: WebSocket服务器地址列表
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          type: string
                        example:
                          - 'ws://192.168.1.100:8000/xiaozhi/v1/'
                          - 'ws://192.168.1.101:8000/xiaozhi/v1/'

  /admin/server/emit-action:
    post:
      tags:
        - 服务端管理
      summary: 通知Python服务端更新配置
      description: 向指定WebSocket服务端发送操作指令，如重启服务或更新配置
      operationId: emitServerAction
      security:
        - BearerAuth: ['sys:role:superAdmin']
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmitSeverActionDTO'
      responses:
        '200':
          description: 操作执行成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      data:
                        type: boolean
                        example: true
        '400':
          description: 请求参数错误或目标WebSocket地址无效
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      code:
                        example: 400
                      msg:
                        example: 目标WebSocket地址不存在
        '500':
          description: WebSocket连接失败
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Result'
                  - type: object
                    properties:
                      code:
                        example: 500
                      msg:
                        example: WebSocket连接失败或连接超时

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

  parameters:
    AgentId:
      name: id
      in: path
      required: true
      schema:
        type: string
      example: AGT_1234567890

    Page:
      name: page
      in: query
      schema:
        type: integer
        default: 1
      example: 1

    Limit:
      name: limit
      in: query
      schema:
        type: integer
        default: 10
      example: 10

  responses:
    Success:
      description: 操作成功
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Result'
          example:
            code: 200
            msg: success
            data: null

    BadRequest:
      description: 请求参数错误
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Result'
          example:
            code: 400
            msg: 参数错误
            data: null

    Unauthorized:
      description: 未授权
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Result'
          example:
            code: 401
            msg: 未授权，请先登录
            data: null

  schemas:
    # =================== 通用响应结构 ===================
    Result:
      type: object
      properties:
        code:
          type: integer
          description: 响应码
          example: 200
        msg:
          type: string
          description: 响应消息
          example: success
        data:
          description: 响应数据
      required:
        - code
        - msg

    PageData:
      type: object
      properties:
        total:
          type: integer
          description: 总记录数
          example: 100
        list:
          type: array
          description: 数据列表
          items:
            type: object
      required:
        - total
        - list

    # =================== 认证相关 ===================
    LoginDTO:
      type: object
      properties:
        username:
          type: string
          description: 手机号码
          example: '13800138000'
        password:
          type: string
          description: 密码
          example: password123
        captcha:
          type: string
          description: 图片验证码
          example: AB3C
        mobileCaptcha:
          type: string
          description: 短信验证码
          example: '123456'
        captchaId:
          type: string
          description: 验证码唯一标识
          example: uuid-captcha-id-12345
      required:
        - username
        - password
        - captcha
        - captchaId

    TokenDTO:
      type: object
      properties:
        token:
          type: string
          description: JWT访问令牌
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        expire:
          type: integer
          format: int64
          description: 过期时间戳(毫秒)
          example: 1640995200000
      required:
        - token
        - expire

    UserDetail:
      type: object
      properties:
        id:
          type: string
          example: USER_123
        username:
          type: string
          example: '13800138000'
        mobile:
          type: string
          example: '13800138000'
        email:
          type: string
          example: user@example.com
        realName:
          type: string
          example: 张三
        avatar:
          type: string
          example: 'https://example.com/avatar.jpg'
        status:
          type: integer
          example: 1
        createDate:
          type: string
          format: date-time
          example: '2023-01-01T00:00:00Z'

    # =================== 智能体相关 ===================
    AgentCreateDTO:
      type: object
      properties:
        agentName:
          type: string
          description: 智能体名称
          example: 客服助手
      required:
        - agentName

    AgentUpdateDTO:
      type: object
      properties:
        agentCode:
          type: string
          description: 智能体编码
          example: AGT_1234567890
        agentName:
          type: string
          description: 智能体名称
          example: 客服助手Pro
        asrModelId:
          type: string
          description: 语音识别模型ID
          example: asr_model_02
        vadModelId:
          type: string
          description: 语音活动检测模型ID
          example: vad_model_02
        llmModelId:
          type: string
          description: 大语言模型ID
          example: llm_model_02
        vllmModelId:
          type: string
          description: 视觉语言模型ID
          example: vllm_model_02
        ttsModelId:
          type: string
          description: 语音合成模型ID
          example: tts_model_02
        ttsVoiceId:
          type: string
          description: 音色ID
          example: voice_02
        memModelId:
          type: string
          description: 记忆模型ID
          example: mem_model_02
        intentModelId:
          type: string
          description: 意图识别模型ID
          example: intent_model_02
        functions:
          type: array
          description: 插件函数配置列表
          items:
            $ref: '#/components/schemas/FunctionInfo'
        systemPrompt:
          type: string
          description: 系统提示词/角色设定
          example: 你是一个专业的客服助手，负责回答用户问题并提供帮助。
        summaryMemory:
          type: string
          description: 记忆总结配置
          example: 根据对话记录，总结user的重要信息，以便在未来的对话中提供更个性化的服务。
        chatHistoryConf:
          type: integer
          description: 聊天记录配置 (0=不记录, 1=仅文本, 2=文本+语音)
          example: 2
        langCode:
          type: string
          description: 语言编码
          example: zh_CN
        language:
          type: string
          description: 交互语言名称
          example: 中文
        sort:
          type: integer
          description: 排序值
          example: 1

    FunctionInfo:
      type: object
      properties:
        pluginId:
          type: string
          description: 插件ID
          example: weather_plugin
        paramInfo:
          type: object
          description: 插件参数配置
          additionalProperties: true
          example:
            api_key: your_api_key
            default_location: 北京

    AgentMemoryDTO:
      type: object
      properties:
        summaryMemory:
          type: string
          description: 记忆摘要内容
          example: 用户喜欢听音乐，经常询问天气信息。
      required:
        - summaryMemory

    AgentDTO:
      type: object
      properties:
        id:
          type: string
          example: AGT_1234567890
        agentCode:
          type: string
          example: AGT_1234567890
        agentName:
          type: string
          example: 客服助手
        systemPrompt:
          type: string
          example: 你是一个专业的客服助手
        createDate:
          type: string
          format: date-time

    AgentInfoVO:
      allOf:
        - $ref: '#/components/schemas/AgentDTO'
        - type: object
          properties:
            asrModelName:
              type: string
              example: FunASR
            llmModelName:
              type: string
              example: ChatGLM
            ttsModelName:
              type: string
              example: EdgeTTS

    AgentTemplateEntity:
      type: object
      properties:
        id:
          type: string
          example: TPL_001
        templateName:
          type: string
          example: 客服助手模板
        systemPrompt:
          type: string
          example: 你是一个专业的客服助手
        description:
          type: string
          example: 适用于客服场景的智能助手模板

    # =================== 设备相关 ===================
    DeviceRegisterDTO:
      type: object
      properties:
        macAddress:
          type: string
          description: 设备MAC地址
          example: 'AA:BB:CC:DD:EE:FF'
      required:
        - macAddress

    DeviceUnBindDTO:
      type: object
      properties:
        deviceId:
          type: string
          description: 设备ID
          example: DEV_123456
        agentId:
          type: string
          description: 智能体ID
          example: AGT_1234567890
      required:
        - deviceId
        - agentId

    DeviceEntity:
      type: object
      properties:
        id:
          type: string
          example: DEV_123456
        deviceName:
          type: string
          example: 客厅音箱
        macAddress:
          type: string
          example: 'AA:BB:CC:DD:EE:FF'
        deviceType:
          type: string
          example: ESP32
        status:
          type: integer
          example: 1
        createDate:
          type: string
          format: date-time

    DeviceReportReqDTO:
      type: object
      properties:
        version:
          type: string
          example: 1.0.0
        deviceType:
          type: string
          example: ESP32
        macAddress:
          type: string
          example: 'AA:BB:CC:DD:EE:FF'

    DeviceReportRespDTO:
      type: object
      properties:
        hasUpdate:
          type: boolean
          example: true
        version:
          type: string
          example: 1.0.1
        downloadUrl:
          type: string
          example: 'https://example.com/firmware.bin'
        updateMessage:
          type: string
          example: 修复了音频处理bug

    # =================== 模型相关 ===================
    ModelBasicInfoDTO:
      type: object
      properties:
        modelId:
          type: string
          example: llm_model_01
        modelName:
          type: string
          example: ChatGLM-4
        modelType:
          type: string
          example: LLM
        providerName:
          type: string
          example: 智谱AI
        isDefault:
          type: boolean
          example: true
        status:
          type: integer
          example: 1

    ModelProviderDTO:
      type: object
      properties:
        id:
          type: string
          example: PROV_001
        providerCode:
          type: string
          example: chatglm
        providerName:
          type: string
          example: 智谱AI
        description:
          type: string
          example: 智谱AI大模型服务商
        apiEndpoint:
          type: string
          example: 'https://open.bigmodel.cn/api/paas/v4/'

    # =================== 服务端管理相关 ===================
    EmitSeverActionDTO:
      type: object
      properties:
        targetWs:
          type: string
          description: 目标WebSocket服务器地址
          example: 'ws://192.168.1.100:8000/xiaozhi/v1/'
        action:
          $ref: '#/components/schemas/ServerActionEnum'
      required:
        - targetWs
        - action

    ServerActionEnum:
      type: string
      enum:
        - restart
        - update_config
      description: |
        服务端操作类型:
        - restart: 重启服务
        - update_config: 更新配置
      example: update_config

tags:
  - name: 用户认证
    description: 用户登录、注册、认证相关接口
  - name: 智能体管理
    description: 智能体的创建、配置、管理相关接口
  - name: 设备管理
    description: 设备注册、绑定、管理相关接口
  - name: OTA管理
    description: 固件更新、设备激活相关接口
  - name: 模型管理
    description: AI模型配置、管理相关接口
  - name: 服务端管理
    description: 服务端状态、配置管理相关接口