# 订单V2 API 文档

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

## 1. 全局响应结构

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

```json
{
  "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 | 风格标准定价积分 |

### 示例请求

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

### 示例响应

```json
{
  "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 | 创建时间 |

### 示例请求

```http
GET /v2/ai/order/v2/get/ORD_202603090001
```

### 示例响应

```json
{
  "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 | 更新时间（时间戳） |

### 处理逻辑

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

### 示例请求

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

### 示例响应（任务已完成）

```json
{
  "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
}
```

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

```json
{
  "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
}
```

### 示例响应（查询异常）

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