订单V2 API 文档

本文档描述订单V2管理相关接口规范。

1. 全局响应结构

所有接口返回值均由统一响应结构包装，格式如下：

{
  "code": 200,
  "message": "success",
  "success": true,
  "data": {},
  "timestamp": 1709628736123
}

2. 订单V2列表查询

URL: /v2/ai/order/v2/list
Method: GET
描述: 分页查询订单V2列表，并关联返回风格信息（风格名称、封面、标准定价积分）。

请求参数

字段名	类型	必填	说明
`page`	integer	否	页码，默认 1
`size`	integer	否	每页大小，默认 10
`id`	string	否	订单ID（精确匹配）
`userId`	integer	否	用户ID
`status`	integer	否	订单状态（1:待支付 2:已支付 0:已退款）
`taskStatus`	integer	否	任务状态（0异常失败，1任务执行中，2执行完成，3执行失败）
`taskId`	string	否	任务ID（精确匹配）
`orderLang`	string	否	订单语言
`startTime`	string	否	开始时间（yyyy-MM-dd HH:mm:ss）
`endTime`	string	否	结束时间（yyyy-MM-dd HH:mm:ss）

响应参数（`data` 字段）

返回 Mybatis-Plus 分页对象，包含 records、total、size、current、pages 等字段。

records 中每条数据（AiOrderV2VO）结构如下：

字段名	类型	说明
`id`	string	订单ID
`userId`	integer	用户ID
`title`	string	商品标题
`status`	integer	订单状态（1:待支付 2:已支付 0:已退款）
`payPoints`	long	支付积分
`payTime`	string	支付时间
`albumId`	integer	相册ID
`styleId`	integer	模版ID
`taskId`	string	任务ID
`taskStatus`	integer	任务状态（0异常失败，1任务执行中，2执行完成，3执行失败）
`orderLang`	string	订单语言
`errorMessage`	string	错误信息
`result`	string	结果数据
`region`	string	地区
`language`	string	语言
`appVersion`	string	app版本
`phoneModel`	string	手机型号
`phoneOsVersion`	string	手机系统版本
`createTime`	string	创建时间
`styleName`	string	风格名称
`styleCoverImg`	string	风格封面图
`standardPlanPoints`	long	风格标准定价积分

示例请求

GET /v2/ai/order/v2/list?page=1&size=10&userId=10001&status=2

示例响应

{
  "code": 200,
  "message": "success",
  "success": true,
  "data": {
    "records": [
      {
        "id": "ORD_202603090001",
        "userId": 10001,
        "title": "写真生成套餐",
        "status": 2,
        "payPoints": 1990,
        "payTime": "2026-03-09 10:08:30",
        "albumId": 12,
        "styleId": 301,
        "taskId": "TASK_998877",
        "taskStatus": 2,
        "orderLang": "zh-CN",
        "errorMessage": null,
        "result": "{\"images\":[\"https://cdn.example.com/a.jpg\"]}",
        "region": "CN",
        "language": "zh-CN",
        "appVersion": "1.2.0",
        "phoneModel": "iPhone 15 Pro",
        "phoneOsVersion": "iOS 18.3",
        "createTime": "2026-03-09 10:05:00",
        "styleName": "春日写真",
        "styleCoverImg": "https://cdn.example.com/style-cover.jpg",
        "standardPlanPoints": 1990
      }
    ],
    "total": 1,
    "size": 10,
    "current": 1,
    "pages": 1
  },
  "timestamp": 1773033000000
}

3. 订单V2详情查询

URL: /v2/ai/order/v2/get/{id}
Method: GET
描述: 根据订单ID获取订单V2详情。

请求参数

字段名	类型	必填	说明
`id`	string	是	订单ID

响应参数（`data` 字段）

返回 TAiOrderV2 对象，字段如下：

字段名	类型	说明
`id`	string	订单ID
`userId`	integer	用户ID
`title`	string	商品标题
`status`	integer	订单状态（1:待支付 2:已支付 0:已退款）
`payPoints`	long	支付积分
`payTime`	string	支付时间
`albumId`	integer	相册ID
`styleId`	integer	模版ID
`taskId`	string	任务ID
`taskStatus`	integer	任务状态（0异常失败，1任务执行中，2执行完成，3执行失败）
`orderLang`	string	订单语言
`errorMessage`	string	错误信息
`result`	string	结果数据
`region`	string	地区
`language`	string	语言
`appVersion`	string	app版本
`phoneModel`	string	手机型号
`phoneOsVersion`	string	手机系统版本
`createTime`	string	创建时间

示例请求

GET /v2/ai/order/v2/get/ORD_202603090001

示例响应

{
  "code": 200,
  "message": "success",
  "success": true,
  "data": {
    "id": "ORD_202603090001",
    "userId": 10001,
    "title": "写真生成套餐",
    "status": 2,
    "payPoints": 1990,
    "payTime": "2026-03-09 10:08:30",
    "albumId": 12,
    "styleId": 301,
    "taskId": "TASK_998877",
    "taskStatus": 2,
    "orderLang": "zh-CN",
    "errorMessage": null,
    "result": "{\"images\":[\"https://cdn.example.com/a.jpg\"]}",
    "region": "CN",
    "language": "zh-CN",
    "appVersion": "1.2.0",
    "phoneModel": "iPhone 15 Pro",
    "phoneOsVersion": "iOS 18.3",
    "createTime": "2026-03-09 10:05:00"
  },
  "timestamp": 1773033000000
}

4. 手动查询任务结果

URL: /v2/ai/order/v2/queryResult
Method: GET
描述: 根据 taskId 主动向外部 Workflow 服务查询任务结果，并自动处理（更新订单、相册、推送通知）。用于 Redis 通知遗漏时的手动补偿。

请求参数

字段名	类型	必填	说明
`taskId`	string	是	外部任务ID，例如 `2b80cfe9-eb90-44c2-9201-55ecff33a85d`

响应参数（`data` 字段）

返回外部 Workflow 服务原始响应 WorkflowTaskMessage 对象：

字段名	类型	说明
`taskId`	string	任务ID
`status`	string	任务状态（`successes`=成功, `failed`=失败, `running`=执行中）
`message`	string	消息/错误信息
`type`	string	任务类型
`data`	object	任务结果数据
`data.images`	string[]	生成的图片URL列表
`data.videos`	string[]	生成的视频URL列表
`request`	object	任务请求参数
`request.template`	string	模版名称
`request.inputs`	object	输入参数
`createTime`	long	创建时间（时间戳）
`updateTime`	long	更新时间（时间戳）

处理逻辑

调用外部接口 GET {workflow_host}/result?taskId=xxx 获取任务结果
如果 status 为 successes：更新订单状态为完成、更新相册、推送用户通知
如果 status 为失败状态：执行退款并标记订单/相册失败
如果 status 为 running/pending/processing 等执行中状态：跳过处理，仅返回当前状态

示例请求

GET /v2/ai/order/v2/queryResult?taskId=2b80cfe9-eb90-44c2-9201-55ecff33a85d

示例响应（任务已完成）

{
  "code": 200,
  "message": "success",
  "success": true,
  "data": {
    "taskId": "2b80cfe9-eb90-44c2-9201-55ecff33a85d",
    "status": "successes",
    "message": null,
    "type": "workflow",
    "data": {
      "images": [
        "https://cdn.example.com/result1.jpg",
        "https://cdn.example.com/result2.jpg"
      ],
      "videos": null
    },
    "request": {
      "template": "spring_photo",
      "inputs": {
        "style": "natural"
      }
    },
    "createTime": 1773033000,
    "updateTime": 1773033300
  },
  "timestamp": 1773033600000
}

示例响应（任务仍在执行中）

{
  "code": 200,
  "message": "success",
  "success": true,
  "data": {
    "taskId": "2b80cfe9-eb90-44c2-9201-55ecff33a85d",
    "status": "running",
    "message": null,
    "type": "workflow",
    "data": null,
    "request": null,
    "createTime": 1773033000,
    "updateTime": null
  },
  "timestamp": 1773033600000
}

示例响应（查询异常）

{
  "code": 500,
  "message": "查询异常: Connection refused",
  "success": false,
  "data": null,
  "timestamp": 1773033600000
}

5. 查询任务执行日志

URL: /v2/ai/order/v2/taskLog
Method: GET
描述: 根据 taskId 查询 ai-flow-py 容器中的执行日志。等价于在宿主机执行 docker logs ai-flow-py 2>&1 | grep "{taskId}"。通过 Docker Engine API（unix socket）直接访问同宿主机上的容器日志。

前置条件

部署时需要将 Docker Socket 挂载到容器内：

-v /var/run/docker.sock:/var/run/docker.sock

请求参数

字段名	类型	必填	说明
`taskId`	string	是	任务ID，例如 `b07cbbc8-1f8f-4060-98f8-051b66ccf1ab`

响应参数（`data` 字段）

返回匹配的日志行列表（List<String>），每行包含时间戳和日志内容。

示例请求

GET /v2/ai/order/v2/taskLog?taskId=b07cbbc8-1f8f-4060-98f8-051b66ccf1ab

示例响应

{
  "code": 200,
  "message": "success",
  "success": true,
  "data": [
    "2026-03-18T10:05:00.123456789Z INFO [task] Processing task b07cbbc8-1f8f-4060-98f8-051b66ccf1ab",
    "2026-03-18T10:05:01.234567890Z INFO [task] Task b07cbbc8-1f8f-4060-98f8-051b66ccf1ab completed"
  ],
  "timestamp": 1773033600000
}

示例响应（Docker Socket未挂载）

{
  "code": 500,
  "message": "Docker socket 不存在: /var/run/docker.sock，请确认已挂载 -v /var/run/docker.sock:/var/run/docker.sock",
  "success": false,
  "data": null,
  "timestamp": 1773033600000
}

AI_ORDER_V2_API.md 9.8 KB Verlauf Originalformat

订单V2 API 文档

1. 全局响应结构

2. 订单V2列表查询

请求参数

响应参数（data 字段）

示例请求

示例响应

3. 订单V2详情查询

请求参数

响应参数（data 字段）

示例请求

示例响应

4. 手动查询任务结果

请求参数

响应参数（data 字段）

处理逻辑

示例请求

示例响应（任务已完成）

示例响应（任务仍在执行中）

示例响应（查询异常）

5. 查询任务执行日志

前置条件

请求参数

响应参数（data 字段）

示例请求

示例响应

示例响应（Docker Socket未挂载）

AI_ORDER_V2_API.md 9.8 KB

Verlauf Originalformat

响应参数（`data` 字段）

响应参数（`data` 字段）

响应参数（`data` 字段）

响应参数（`data` 字段）