任务回调消息契约

draw.progress消息结构、消费约束与回调闭环说明

1. 目标

定义 Easyai Server 对外推送的任务进度消息结构，以及消费方如何基于 callback_url 完成任务回调闭环。

2. 责任边界

  • Easyai Server：发布 draw.progress 事件，注入 callback_url
  • Consumer（Portal 或网关消费者）：消费事件并按 callback_url 发起回调
  • 第三方回调端：接收回调并返回 2xx ACK

3. 回调地址来源与配置

payload.callback_url 来源于系统「运营配置」-> 「任务调度」 -> 「任务回调地址」。

约束：

  • 回调地址必须从 Consumer 所在网络可达（内网或公网均可）
  • 回调地址应保持稳定，避免执行期间切换

4. 时序图

5. 消息契约（基于共享类型）

核心结构：

export interface IQueueStatus {
  task_id: string;
  request_id?: string;
  server?: string;
  status: ITaskStatusEnum;
  queue?: number;
  data?: DrawResponse;
  output_content?: GeneralOutput[];
  message?: string;
  original_error_message?: string;
  time_remained?: number;
  progress?: number;
}

export interface IGenerateStatus {
  node_status?: IWorkflowNodeExecuteStatus;
  queue_status?: IQueueStatus;
  usage?: any;
  callback_url?: string;
  user?: { _id?: string; sso_id?: string };
  generate_info?: {
    input?: Record<string, unknown>;
    workflow?: { _id: string };
  };
  billings?: Array<BillDetail>;
}

export interface IWsGateWayMessage<T = any> {
  toUserId?: string;
  message: T;
  type?: IWebsocketSceneType;
}

5.1 事件包络字段

字段含义
eventName固定 draw.progress
payload任务消息体，类型 IGenerateStatus
target.channel投递通道（默认 default、canvas_flow）
target.clientId当前用户 ID
metadata.source固定 easyai-server-main
metadata.queueStatus来自 payload.queue_status.status
correlationId优先 request_id，其次 task_id

5.2 payload 关键字段

字段路径类型含义
callback_urlstring | undefined回调地址
user._idstring | undefined本系统用户 ID
user.sso_idstring | undefinedSSO 用户 ID
queue_status.task_idstring任务主 ID
queue_status.request_idstring | undefined请求链路 ID
queue_status.statusenum任务状态
queue_status.progressnumber | undefined进度值
queue_status.messagestring | undefined状态描述
queue_status.original_error_messagestring | undefined原始错误信息
node_statusobject | undefined节点级执行状态
generate_infoobject | undefined扩展生成信息
usageany用量信息（兼容字段）
billingsBillDetail | undefined账单信息

6. 真实 payload 示例（脱敏）

{
  "queue_status": {
    "task_id": "69eaed5c2083d0d2450e3e42",
    "status": "success",
    "data": {
      "task_id": "69eaed5c2083d0d2450e3e42",
      "output": [
        "http://127.0.0.1:3001/upload/files/image_20260424041130760.png"
      ],
      "output_content": [
        {
          "type": "image",
          "uploaded": true,
          "url": "http://127.0.0.1:3001/upload/files/image_20260424041130760.png",
          "b64_json": "http://127.0.0.1:3001/upload/files/image_20260424041130760.png"
        }
      ],
      "billings": [
        {
          "billing_type": "external-api",
          "result": { "image": 10 },
          "platform": {
            "name": "即梦AI-开发",
            "id": "699fa93dae0e0f9f4134c8a2",
            "code": "jimeng"
          }
        }
      ],
      "status": "success"
    }
  },
  "billings": [
    {
      "billing_type": "external-api",
      "result": { "image": 10 }
    }
  ],
  "user": {
    "_id": "68ae8389d2750f156573b69c",
    "sso_id": "68c0203f19621fd444269c75"
  },
  "callback_url": "http://127.0.0.1:5001/sub-app/callback"
}

7. 消费与回调实现要求

项目要求
回调地址必须网络可达（内网/公网均可），并保持稳定
幂等键推荐 task_id
重试非 2xx 自动重试，指数退避

8. 完成标准

  • 能正确消费 draw.progress 消息
  • 能按 callback_url 成功回调第三方系统
  • 重复消息不会导致重复入账/重复状态推进
Portal能力对接
基于SSO的资源白名单、权限等级与余额能力对接规范
集成联调验收清单
SSO、Portal与任务回调的一体化联调步骤和验收标准