上传源代码版本

袋牌模块需求文档.md

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