openapi: 3.1.0
info:
  title: 云轩机器人管理公共 API
  version: 1.0.0
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
  description: |
    使用 AppID、AppKey 和 HMAC-SHA256 签名发送飞书、Telegram 或钉钉 消息。
    AppKey 只能保存在可信服务端。完整签名、路由和安全规则见 docs/api/接口说明.md。
servers:
  - url: https://bot.yunxuanwl.cn/api/v1
    description: 生产公共 API
  - url: http://127.0.0.1:13250/api/v1
    description: 本地公共 API
security:
  - hmacAuth: []
paths:
  /health:
    get:
      summary: 健康检查
      operationId: health
      security: []
      responses:
        "200":
          description: 服务正常
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
  /messages/send:
    post:
      summary: 签名发送消息
      description: |
        payload 是 SendMessagePayload 序列化后的原始紧凑 JSON 字符串。
        不提供目标筛选时广播；同时提供机器人和会话筛选时取应用已配置目标的交集。
      operationId: sendMessage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SignedSendRequest"
      responses:
        "200":
          description: 至少一个目标发送成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SendMessageApiResponse"
        "400":
          description: payload、目标筛选或应用配置错误
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: 应用、签名、时间戳或 nonce 错误
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: 应用停用或策略拒绝
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
components:
  securitySchemes:
    hmacAuth:
      type: http
      scheme: hmac-sha256
      description: AppID、时间戳、nonce、原始 payload 和 AppKey 组成的请求体签名，详见 docs/api/接口说明.md。
  schemas:
    SignedSendRequest:
      type: object
      additionalProperties: false
      required: [appid, timestamp, nonce, signature, payload]
      properties:
        appid:
          type: string
        timestamp:
          type: integer
          format: int64
          description: Unix 秒级时间戳，允许误差 5 分钟。
        nonce:
          type: string
          minLength: 1
          description: 有效窗口内不可重复。
        signature:
          type: string
          description: 标准 Base64 编码的 HMAC-SHA256。
        payload:
          type: string
          contentMediaType: application/json
          contentSchema:
            $ref: "#/components/schemas/SendMessagePayload"
          description: SendMessagePayload 的原始紧凑 JSON 字符串，必须与参与签名的字符串完全一致。
          examples:
            - '{"channel":"feishu","content":"任务审核完成","bot_ids":[100001],"chat_ids":["oc_xxx"]}'
    SendMessagePayload:
      type: object
      additionalProperties: false
      required: [channel, content]
      properties:
        channel:
          type: string
          enum: [feishu, telegram, dingtalk]
        content:
          type: string
          minLength: 1
        bot_id:
          type: integer
          format: int64
          minimum: 1
        bot_ids:
          type: array
          minItems: 1
          maxItems: 100
          items:
            type: integer
            format: int64
            minimum: 1
        chat_id:
          type: string
          minLength: 1
        chat_ids:
          type: array
          minItems: 1
          maxItems: 100
          items:
            type: string
            minLength: 1
        request_id:
          type: string
          description: 追踪编号，当前不提供服务端强制幂等。
        mock:
          type: boolean
          description: 测试开关，生产业务不要设置。
    SendMessageApiResponse:
      type: object
      required: [code, message, data]
      properties:
        code:
          type: integer
          const: 0
        message:
          type: string
          const: ok
        data:
          $ref: "#/components/schemas/SendMessageResponse"
    SendMessageResponse:
      type: object
      required: [status, channel, results, message_log_id, mock, result_message]
      properties:
        status:
          type: string
          enum: [accepted, partial]
        channel:
          type: string
          enum: [feishu, telegram, dingtalk]
        results:
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/SendMessageResultItem"
        message_log_id:
          type: integer
          format: int64
          description: 兼容字段，代表 results 第一项。
        mock:
          type: boolean
          description: 兼容字段，代表 results 第一项。
        result_message:
          type: string
          description: 兼容字段，代表 results 第一项。
        provider_message_id:
          type: [string, "null"]
          description: 兼容字段，代表 results 第一项。
    SendMessageResultItem:
      type: object
      required: [bot_id, chat_id, message_log_id, status, mock, result_message]
      properties:
        bot_id:
          type: integer
          format: int64
        chat_id:
          type: string
        message_log_id:
          type: integer
          format: int64
        status:
          type: string
          enum: [accepted, failed]
        mock:
          type: boolean
        result_message:
          type: string
        provider_message_id:
          type: [string, "null"]
    HealthResponse:
      type: object
      required: [code, message, data]
      properties:
        code:
          type: integer
          const: 0
        message:
          type: string
          const: ok
        data:
          type: object
          required: [service, status]
          properties:
            service:
              type: string
              const: bot-management-api
            status:
              type: string
              const: ok
    ErrorResponse:
      type: object
      required: [code, message]
      properties:
        code:
          type: integer
        message:
          type: string