100 lines
2.7 KiB
Markdown
100 lines
2.7 KiB
Markdown
# 袋牌模块需求文档
|
||
|
||
## 目标说明
|
||
|
||
袋牌服务用于在业务流程中对"袋牌"进行统一管理，包括袋牌的生成、启用、停用，以及袋牌与尾程运单号的关联，以支持分拣、装箱，交接、追踪等业务场景。
|
||
|
||
## 基本概念
|
||
|
||
- **袋牌**：系统内部生成的唯一标识，用于标记物流或业务单元。
|
||
- **尾程运单号**：由扫描设备、外部系统或客户提供的运单号字符串。
|
||
- **渠道商**：仅用于袋牌命名维度，不参与尾程运单号关联逻辑。
|
||
|
||
## 袋牌命名功能要求
|
||
|
||
### 3.1 命名规则
|
||
|
||
袋牌号由以下三部分组成：
|
||
- 渠道商全称（英文大写）
|
||
- 生成时间（精确到秒）
|
||
- 序号（用于保证唯一性）
|
||
|
||
命名格式：
|
||
```
|
||
{渠道商全称}{YYYYMMDDHHMMSS}{序号}
|
||
```
|
||
|
||
### 3.2 支持的渠道商（用于袋牌命名）
|
||
|
||
- USPS
|
||
- UPS
|
||
- FEDEX
|
||
- GOFO
|
||
- UNIUNI
|
||
- SPEEDX
|
||
|
||
## API 功能列表
|
||
|
||
### 接口 1：生成袋牌号
|
||
|
||
#### 功能描述
|
||
- 提供生成袋牌号的能力。
|
||
- 支持单个或批量生成袋牌号。
|
||
- 生成的袋牌号需符合统一命名规则。
|
||
|
||
#### 功能要求
|
||
- 调用方可指定生成数量。
|
||
- 系统需保证生成的袋牌号唯一。
|
||
- 返回生成成功的袋牌号列表。
|
||
|
||
### 接口 2：打开袋牌
|
||
|
||
#### 功能描述
|
||
- 将指定袋牌置为"打开"状态。
|
||
- 打开后的袋牌可参与后续业务操作。
|
||
|
||
#### 功能要求
|
||
- 仅存在的袋牌可被打开。
|
||
- 已打开的袋牌不可重复打开。
|
||
- 已关闭的袋牌不可再次打开。
|
||
|
||
### 接口 3：关闭袋牌
|
||
|
||
#### 功能描述
|
||
- 将指定袋牌置为"关闭"状态。
|
||
- 关闭后的袋牌不可再参与任何业务操作。
|
||
|
||
#### 功能要求
|
||
- 仅存在的袋牌可被关闭。
|
||
- 已关闭的袋牌不可重复关闭。
|
||
|
||
### 接口 4：关联尾程运单号与袋牌
|
||
|
||
#### 功能描述
|
||
- 将尾程运单号与指定袋牌建立关联关系。
|
||
- 关联行为不依赖尾程运单号所属渠道商。
|
||
- 系统不对尾程运单号进行渠道识别或校验。
|
||
|
||
#### 功能要求
|
||
- 仅"已打开"的袋牌允许进行关联。
|
||
- 关联时：
|
||
- 不区分运单号来源（扫描 / 客户传输 / 外部系统）
|
||
- 不针对任何渠道做特殊处理
|
||
- 系统需保存：
|
||
- 原始输入的尾程运单号
|
||
- 袋牌与运单号之间的关联关系
|
||
- 对格式异常或不符合业务预期的运单号，处理方式由业务流程决定（如拒绝或标记异常）。
|
||
|
||
## 状态与使用约束
|
||
|
||
- 袋牌生命周期包括：
|
||
- 已生成
|
||
- 已打开
|
||
- 已关闭
|
||
- 仅"已打开"的袋牌允许关联尾程运单号。
|
||
|
||
## 功能性总结
|
||
|
||
- 系统提供统一的袋牌生成能力，支持批量操作。
|
||
- 系统支持袋牌的生命周期管理（打开 / 关闭）。
|
||
- 系统支持将任意尾程运单号与袋牌进行关联。 |