# 订单待办事项（Todo）完整对接方案

> 日期: 2026-03-19 | 服务: hl-order-service

---

## 一、功能说明

订单支付成功后，系统自动生成一组「待办事项」，按顺序推进内部流程。每个待办有对应的负责角色，完成后自动推进到下一步。

### 待办流程（6步）

```
确认订单 → 配置保险 → 签订合同 → 安排住宿 → 安排车辆 → 确认清单
(定制师)   (定制师)   (定制师)   (房管)     (车管)     (定制师)
```

### 关联字典

**`order_todo_type`（订单待办类型）**：

| dict_value | dict_label | 序号 | 负责角色 |
|------------|-----------|------|---------|
| CONFIRM_ORDER | 确认订单 | 1 | CUSTOMIZER（定制师） |
| INSURANCE | 配置保险 | 2 | CUSTOMIZER（定制师） |
| CONTRACT | 签订合同 | 3 | CUSTOMIZER（定制师） |
| ARRANGE_ROOM | 安排住宿 | 4 | ROOM_MANAGER（房管） |
| ARRANGE_VEHICLE | 安排车辆 | 5 | VEHICLE_MANAGER（车管） |
| CONFIRM_CHECKLIST | 确认清单 | 6 | CUSTOMIZER（定制师） |
| PROCESS_REFUND | 处理退款 | 7 | CUSTOMIZER（定制师） |

**待办状态**：

| 值 | 含义 |
|----|------|
| PENDING | 待处理 |
| COMPLETED | 已完成 |
| CANCELLED | 已取消（订单取消/退款时自动取消） |

---

## 二、接口清单

| # | 方法 | 路径 | 说明 | 使用场景 |
|---|------|------|------|---------|
| 1 | GET | `/admin/order/{orderId}/todos` | 获取订单待办列表 | 订单详情页 → 待办面板 |
| 2 | PUT | `/admin/order/todo/{todoId}/complete` | 完成待办 | 点击「完成」/「去投保」按钮 |
| 3 | GET | `/admin/order/todo/my-list` | 我的待办列表 | 首页/工作台 → 待办列表 |
| 4 | GET | `/admin/order/todo/my-count` | 我的待办数量 | 首页/菜单 → 红点角标 |
| 5 | GET | `/admin/order/todo/customizer-list` | 定制师列表 | 更换定制师弹窗 → 下拉选择 |
| 6 | PUT | `/admin/order/{orderId}/customizer` | 更换定制师 | 更换定制师弹窗 → 确认 |
| 7 | GET | `/admin/order/todo/contract-eligible` | 可签合同订单列表 | 合同管理页 → 待签合同 |

---

## 三、接口详细定义

### 1. 获取订单待办列表

**接口**：`GET /admin/order/{orderId}/todos`

**使用场景**：订单详情页右侧「待办事项」面板，展示该订单所有待办项的时间线

**路径参数**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| orderId | Long(String) | 是 | 订单ID |

**响应示例**：
```json
{
  "code": 200,
  "message": "成功",
  "data": [
    {
      "todoId": "1902000000000000001",
      "orderId": "1901000000000000001",
      "orderNo": "HL202603191600255172",
      "todoType": "CONFIRM_ORDER",
      "todoLabel": "确认订单",
      "sequence": 1,
      "status": "COMPLETED",
      "assigneeRoleKey": "CUSTOMIZER",
      "assigneeAdminId": "1800000000000000010",
      "completedBy": "1800000000000000010",
      "completedAt": "2026-03-19 10:30:00",
      "createTime": "2026-03-19 10:00:00"
    },
    {
      "todoId": "1902000000000000002",
      "orderId": "1901000000000000001",
      "orderNo": "HL202603191600255172",
      "todoType": "INSURANCE",
      "todoLabel": "配置保险",
      "sequence": 2,
      "status": "PENDING",
      "assigneeRoleKey": "CUSTOMIZER",
      "assigneeAdminId": "1800000000000000010",
      "completedBy": null,
      "completedAt": null,
      "createTime": "2026-03-19 10:00:00"
    },
    {
      "todoId": "1902000000000000003",
      "orderId": "1901000000000000001",
      "orderNo": "HL202603191600255172",
      "todoType": "CONTRACT",
      "todoLabel": "签订合同",
      "sequence": 3,
      "status": "PENDING",
      "assigneeRoleKey": "CUSTOMIZER",
      "assigneeAdminId": "1800000000000000010",
      "completedBy": null,
      "completedAt": null,
      "createTime": "2026-03-19 10:00:00"
    },
    {
      "todoId": "1902000000000000004",
      "orderId": "1901000000000000001",
      "orderNo": "HL202603191600255172",
      "todoType": "ARRANGE_ROOM",
      "todoLabel": "安排住宿",
      "sequence": 4,
      "status": "PENDING",
      "assigneeRoleKey": "ROOM_MANAGER",
      "assigneeAdminId": null,
      "completedBy": null,
      "completedAt": null,
      "createTime": "2026-03-19 10:00:00"
    },
    {
      "todoId": "1902000000000000005",
      "orderId": "1901000000000000001",
      "orderNo": "HL202603191600255172",
      "todoType": "ARRANGE_VEHICLE",
      "todoLabel": "安排车辆",
      "sequence": 5,
      "status": "PENDING",
      "assigneeRoleKey": "VEHICLE_MANAGER",
      "assigneeAdminId": null,
      "completedBy": null,
      "completedAt": null,
      "createTime": "2026-03-19 10:00:00"
    },
    {
      "todoId": "1902000000000000006",
      "orderId": "1901000000000000001",
      "orderNo": "HL202603191600255172",
      "todoType": "CONFIRM_CHECKLIST",
      "todoLabel": "确认清单",
      "sequence": 6,
      "status": "PENDING",
      "assigneeRoleKey": "CUSTOMIZER",
      "assigneeAdminId": "1800000000000000010",
      "completedBy": null,
      "completedAt": null,
      "createTime": "2026-03-19 10:00:00"
    }
  ]
}
```

**返回字段说明**：

| 字段 | 类型 | 说明 |
|------|------|------|
| todoId | String | 待办ID |
| orderId | String | 订单ID |
| orderNo | String | 订单号 |
| todoType | String | 待办类型（字典：`order_todo_type`） |
| todoLabel | String | 待办名称（中文） |
| sequence | Integer | 排序序号（1-6，决定显示顺序） |
| status | String | 状态：`PENDING`=待处理 / `COMPLETED`=已完成 / `CANCELLED`=已取消 |
| assigneeRoleKey | String | 负责角色标识：`CUSTOMIZER` / `ROOM_MANAGER` / `VEHICLE_MANAGER` |
| assigneeAdminId | String | 负责管理员ID（可能为null，表示尚未分配具体人） |
| completedBy | String | 完成人ID（未完成时为null） |
| completedAt | String | 完成时间（未完成时为null），格式 `yyyy-MM-dd HH:mm:ss` |
| createTime | String | 创建时间，格式 `yyyy-MM-dd HH:mm:ss` |

---

### 2. 完成待办

**接口**：`PUT /admin/order/todo/{todoId}/complete`

**使用场景**：点击待办项的「完成」或「去投保」按钮

**路径参数**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| todoId | Long(String) | 是 | 待办ID |

**请求体**：无

**响应示例**：
```json
{
  "code": 200,
  "message": "成功",
  "data": null
}
```

**权限说明**：
- 需要对应角色权限，例如 `ARRANGE_ROOM` 待办需要 `ROOM_MANAGER` 角色
- `SUPER_ADMIN` 可以完成所有类型的待办
- 权限不足时返回 403

**业务逻辑**：
- 完成待办后，系统自动检查是否满足推进条件
- 所有6个待办全部完成后，内部流程状态自动推进到 `READY`（就绪）

---

### 3. 我的待办列表

**接口**：`GET /admin/order/todo/my-list`

**使用场景**：首页/工作台的「我的待办」列表，展示当前登录管理员需要处理的所有未完成待办

**请求参数**：无（根据登录用户的 adminId 和 roleKey 自动筛选）

**响应示例**：
```json
{
  "code": 200,
  "message": "成功",
  "data": [
    {
      "todoId": "1902000000000000002",
      "orderId": "1901000000000000001",
      "orderNo": "HL202603191600255172",
      "todoType": "INSURANCE",
      "todoLabel": "配置保险",
      "sequence": 2,
      "status": "PENDING",
      "assigneeRoleKey": "CUSTOMIZER",
      "assigneeAdminId": "1800000000000000010",
      "completedBy": null,
      "completedAt": null,
      "createTime": "2026-03-19 10:00:00",
      "productName": "嗨·冰雪3.0南线7日游",
      "contactName": "张三",
      "departureDate": "2026-04-01",
      "orderStatus": "PAID",
      "blocked": false,
      "blockedReason": null
    }
  ]
}
```

**返回字段说明**（在基础字段上增加关联信息）：

| 字段 | 类型 | 说明 |
|------|------|------|
| productName | String | 产品名称（关联查询） |
| contactName | String | 联系人姓名（关联查询） |
| departureDate | String | 出发日期（关联查询），格式 `yyyy-MM-dd` |
| orderStatus | String | 订单状态（字典：`order_status`） |
| blocked | Boolean | 是否被阻塞（前序待办未完成时为true） |
| blockedReason | String | 阻塞原因（如 "等待「配置保险」完成"） |

**角色筛选逻辑**：
- `SUPER_ADMIN`：看到所有未完成待办
- `CUSTOMIZER`：只看到 `CONFIRM_ORDER` / `INSURANCE` / `CONTRACT` / `CONFIRM_CHECKLIST` 类型的待办
- `ROOM_MANAGER`：只看到 `ARRANGE_ROOM` 类型的待办
- `VEHICLE_MANAGER`：只看到 `ARRANGE_VEHICLE` 类型的待办

---

### 4. 我的待办数量

**接口**：`GET /admin/order/todo/my-count`

**使用场景**：菜单栏/首页角标红点提醒

**请求参数**：无

**响应示例**：
```json
{
  "code": 200,
  "message": "成功",
  "data": 5
}
```

---

### 5. 定制师列表

**接口**：`GET /admin/order/todo/customizer-list`

**使用场景**：更换定制师弹窗中的下拉选择框

**请求参数**：无

**响应示例**：
```json
{
  "code": 200,
  "message": "成功",
  "data": [
    {
      "adminId": "1800000000000000010",
      "realName": "王骁",
      "avatar": "https://oss.example.com/avatar/wx.jpg"
    },
    {
      "adminId": "1800000000000000011",
      "realName": "李明",
      "avatar": "https://oss.example.com/avatar/lm.jpg"
    }
  ]
}
```

**返回字段说明**：

| 字段 | 类型 | 说明 |
|------|------|------|
| adminId | String | 管理员ID |
| realName | String | 姓名 |
| avatar | String | 头像URL |

---

### 6. 更换定制师

**接口**：`PUT /admin/order/{orderId}/customizer`

**使用场景**：更换定制师弹窗 → 确认按钮

**路径参数**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| orderId | Long(String) | 是 | 订单ID |

**请求体**：
```json
{
  "customizerId": "1800000000000000011"
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| customizerId | Long(String) | 是 | 目标定制师的管理员ID，从定制师列表接口获取 |

**响应示例**：
```json
{
  "code": 200,
  "message": "成功",
  "data": null
}
```

**业务逻辑**：
- 更换后，该订单中所有 `CUSTOMIZER` 角色的待办自动转移给新定制师
- 订单时间线会记录「更换定制师」操作

---

### 7. 可签合同订单列表

**接口**：`GET /admin/order/todo/contract-eligible`

**使用场景**：合同管理页面，展示保险已完成、可以进入签合同环节的订单列表

**请求参数**：无

**响应示例**：
```json
{
  "code": 200,
  "message": "成功",
  "data": [
    {
      "todoId": "1902000000000000003",
      "orderId": "1901000000000000001",
      "orderNo": "HL202603191600255172",
      "todoType": "CONTRACT",
      "todoLabel": "签订合同",
      "sequence": 3,
      "status": "PENDING",
      "assigneeRoleKey": "CUSTOMIZER",
      "assigneeAdminId": "1800000000000000010",
      "completedBy": null,
      "completedAt": null,
      "createTime": "2026-03-19 10:00:00",
      "productName": "嗨·冰雪3.0南线7日游",
      "contactName": "张三",
      "departureDate": "2026-04-01",
      "orderStatus": "PAID",
      "blocked": false,
      "blockedReason": null
    }
  ]
}
```

> 返回字段与「我的待办列表」相同（`OrderTodoVO`）

---

## 四、前端页面布局

### 1. 订单详情页 → 待办事项面板

在订单详情页右侧（或底部），使用**时间线组件**展示待办进度：

```
┌──────────────────────────────────────────────┐
│ 待办事项                                       │
│                                              │
│ ✅ 确认订单          已完成 2026-03-19 10:30    │
│                                              │
│ ⏳ 配置保险          [ 去投保 ]                │
│                                              │
│ ○ 签订合同           (等待上一步完成)           │
│                                              │
│ ○ 安排住宿           (等待上一步完成)           │
│                                              │
│ ○ 安排车辆           (等待上一步完成)           │
│                                              │
│ ○ 确认清单           (等待上一步完成)           │
│                                              │
│ [更换定制师]                                   │
└──────────────────────────────────────────────┘
```

### 2. 待办项状态展示规则

| 状态 | 图标 | 按钮 | 说明文字 |
|------|------|------|---------|
| `COMPLETED` | ✅ 绿色勾 | 无 | 显示 `completedAt` 完成时间 |
| `PENDING` + 非阻塞 | ⏳ 黄色 | 显示操作按钮 | 当前可操作项 |
| `PENDING` + 阻塞 | ○ 灰色 | 无 | 显示 `blockedReason`（如"等待上一步完成"） |
| `CANCELLED` | ❌ 红色 | 无 | 显示"已取消" |

### 3. 操作按钮规则

| 待办类型 | 按钮文案 | 按钮类型 | 点击行为 |
|---------|---------|---------|---------|
| CONFIRM_ORDER | 完成 | primary | 调用完成待办接口 |
| INSURANCE | 去投保 | warning | 跳转到保险配置页面（或弹窗配置后调用完成接口） |
| CONTRACT | 去签合同 | primary | 跳转到合同签署页面（或弹窗操作后调用完成接口） |
| ARRANGE_ROOM | 完成 | primary | 调用完成待办接口（仅ROOM_MANAGER角色可见） |
| ARRANGE_VEHICLE | 完成 | primary | 调用完成待办接口（仅VEHICLE_MANAGER角色可见） |
| CONFIRM_CHECKLIST | 完成 | primary | 调用完成待办接口 |

### 4. 权限控制

- 当前登录用户的 `roleKey` 不匹配待办的 `assigneeRoleKey` 时，**不显示操作按钮**
- `SUPER_ADMIN` 可以看到并操作所有待办的按钮
- 具体映射：
  - `CUSTOMIZER` → 可操作 CONFIRM_ORDER / INSURANCE / CONTRACT / CONFIRM_CHECKLIST
  - `ROOM_MANAGER` → 可操作 ARRANGE_ROOM
  - `VEHICLE_MANAGER` → 可操作 ARRANGE_VEHICLE

---

## 五、首页待办角标

### 实现要点

1. **页面加载时**调用 `GET /admin/order/todo/my-count` 获取待办数量
2. 如果 `data > 0`，在菜单项（如「订单管理」）右侧显示红点或数字角标
3. 点击菜单进入「我的待办」列表页

### 我的待办列表页

调用 `GET /admin/order/todo/my-list`，展示为卡片或表格：

```
┌──────────────────────────────────────────────────────────────┐
│ 我的待办 (5)                                                   │
├──────────────────────────────────────────────────────────────┤
│ 📋 配置保险 | HL202603191600255172 | 嗨·冰雪3.0南线7日游       │
│    联系人: 张三 | 出发: 2026-04-01 | [ 去投保 ] [ 查看订单 ]    │
├──────────────────────────────────────────────────────────────┤
│ 📋 签订合同 | HL202603191800123456 | 海岛亲子5日游              │
│    联系人: 李四 | 出发: 2026-04-15 | ⚠️ 等待「配置保险」完成     │
├──────────────────────────────────────────────────────────────┤
│ ...                                                          │
└──────────────────────────────────────────────────────────────┘
```

---

## 六、更换定制师

### 实现要点

1. 订单详情页待办面板底部放「更换定制师」按钮
2. 点击弹出弹窗，调用 `GET /admin/order/todo/customizer-list` 加载定制师列表
3. 下拉选择目标定制师（显示 `realName`，值 `adminId`）
4. 确认后调用 `PUT /admin/order/{orderId}/customizer`
5. 成功后刷新待办列表

---

## 七、调用示例

```javascript
import { http } from '@/utils/request'

// 1. 获取订单待办列表（订单详情页加载时）
const todos = await http.get(`/order/${orderId}/todos`)
// todos = [{ todoId, todoType, todoLabel, status, completedAt, ... }]

// 2. 完成待办（点击「完成」按钮）
await http.put(`/order/todo/${todoId}/complete`)

// 3. 获取我的待办列表（首页/工作台）
const myTodos = await http.get('/order/todo/my-list')
// myTodos = [{ todoId, orderNo, todoLabel, productName, contactName, departureDate, blocked, ... }]

// 4. 获取待办数量（菜单角标）
const countRes = await http.get('/order/todo/my-count')
const todoCount = countRes  // Number

// 5. 获取定制师列表（更换定制师弹窗）
const customizers = await http.get('/order/todo/customizer-list')
// customizers = [{ adminId, realName, avatar }]

// 6. 更换定制师
await http.put(`/order/${orderId}/customizer`, { customizerId: targetAdminId })

// 7. 获取可签合同订单（合同管理页）
const eligibleOrders = await http.get('/order/todo/contract-eligible')
```

---

## 八、待办生命周期

```
订单支付成功
  ↓
系统自动创建6个待办（status=PENDING）
  ↓
定制师逐步完成待办（PENDING → COMPLETED）
  ↓
所有待办完成 → 内部流程推进到 READY（就绪）
  ↓
如果订单取消/退款 → 所有未完成待办自动取消（status=CANCELLED）
```

**注意事项**：
- 待办按 `sequence` 排序显示（1→6）
- 虽然显示顺序固定，但 ARRANGE_ROOM(4) 和 ARRANGE_VEHICLE(5) 可以并行完成（不互相阻塞）
- 只有 INSURANCE 完成后，CONTRACT 才能操作（有依赖关系）
- 前端拿到 `blocked: true` 的待办不显示操作按钮，显示 `blockedReason` 文字即可