上传源代码版本

2026-06-01 16:30:29 +08:00
commit b2a9b7d3c2
462 changed files with 104365 additions and 0 deletions
--- a/USPS自动集包需求文档.md
+++ b/USPS自动集包需求文档.md
@@ -0,0 +1,144 @@
+# 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. 建议增加操作日志，便于后续追溯和审计