# USPS自动集包需求文档

## 一、目标

在创建 USPS 袋牌 时，系统自动筛选并关联符合条件的包裹，减少人工逐票集包操作，提高效率，并在系统操作记录上尽量模拟人工关联节奏。

---

## 二、适用范围

仅适用于 USPS 尾程包裹 的自动集包。

---

## 三、触发时机

当用户在系统中创建 USPS 袋牌后，系统自动触发一次"自动集包"处理。

---

## 四、自动集包筛选条件

系统仅自动关联同时满足以下条件的包裹：

1. **尾程渠道为 USPS**
2. **当前尚未被集包**
   - 即尚未关联到任何袋牌
3. **已完成换单**
   - 已生成并确认尾程面单
4. **换单时间在前 3 天内（往前推84小时）**
   - 以当前创建袋牌时间为基准，筛选近 3 天内完成换单的包裹

---

## 五、主流程

### Step 1：创建 USPS 袋牌

用户在系统中创建一个新的 USPS 袋牌。
系统完成袋牌创建后，进入自动集包流程。

---

### Step 2：系统筛选符合条件的包裹

系统从包裹池中查询符合以下条件的记录：

| 条件项 | 条件值 |
|--------|--------|
| 尾程渠道 | = USPS |
| 集包状态 | = 未集包 |
| 换单状态 | = 已换单 |
| 换单时间 | >= 当前时间往前 3 天（84小时） |

系统生成本次待自动关联的包裹清单。

---

### Step 3：系统按顺序自动关联包裹到袋牌

系统将筛选出的包裹，逐个关联到当前新创建的 USPS 袋牌。

为了模拟人工逐票操作，每次关联之间增加 **2 秒到 4 秒的随机间隔**。

**说明：**
- 不是一次性批量瞬间关联
- 而是按单条记录逐笔处理

---

### Step 4：更新状态与记录日志

每成功关联一个包裹，系统更新：

| 字段 | 更新值 |
|------|--------|
| 关联袋牌号 | = 当前 USPS 袋牌号 |
| 关联时间 | = 实际执行关联的时间 |

---

### Step 5：自动集包完成

当本次符合条件的包裹全部处理完成后，系统结束自动集包流程，并返回处理结果，例如：

- 本次自动关联成功数量
- 失败数量

---

## 六、流程图

```
┌─────────────────┐
│  创建USPS袋牌    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 触发自动集包流程 │
└────────┬────────┘
         │
         ▼
┌─────────────────────────────────────────┐
│           筛选符合条件的包裹              │
│  ├─ 尾程渠道 = USPS                     │
│  ├─ 集包状态 = 未集包                   │
│  ├─ 换单状态 = 已换单                   │
│  └─ 换单时间 >= 当前时间-84小时         │
└────────┬────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────┐
│         逐个关联包裹到袋牌               │
│  ├─ 逐条处理                            │
│  ├─ 每单间隔 2-4秒随机延迟              │
│  └─ 更新关联袋牌号和关联时间            │
└────────┬────────────────────────────────┘
         │
         ▼
┌─────────────────┐
│ 返回处理结果     │
│ ├─ 成功数量     │
│ └─ 失败数量     │
└─────────────────┘
```

---

## 七、异常处理

| 异常场景 | 处理方式 |
|----------|----------|
| 无符合条件的包裹 | 流程正常结束，返回成功数量：0 |
| 关联过程中某包裹失败 | 记录失败原因，继续处理下一个包裹 |
| 系统异常中断 | 记录已处理进度，支持人工介入或重新触发 |

---

## 八、备注

1. 自动集包仅作为辅助功能，不影响人工集包操作
2. 已自动集包的包裹，人工仍可进行解绑和重新集包操作
3. 建议增加操作日志，便于后续追溯和审计