# 袋牌模块需求文档

## 目标说明

袋牌服务用于在业务流程中对"袋牌"进行统一管理，包括袋牌的生成、启用、停用，以及袋牌与尾程运单号的关联，以支持分拣、装箱，交接、追踪等业务场景。

## 基本概念

- **袋牌**：系统内部生成的唯一标识，用于标记物流或业务单元。
- **尾程运单号**：由扫描设备、外部系统或客户提供的运单号字符串。
- **渠道商**：仅用于袋牌命名维度，不参与尾程运单号关联逻辑。

## 袋牌命名功能要求

### 3.1 命名规则

袋牌号由以下三部分组成：
- 渠道商全称（英文大写）
- 生成时间（精确到秒）
- 序号（用于保证唯一性）

命名格式：
```
{渠道商全称}{YYYYMMDDHHMMSS}{序号}
```

### 3.2 支持的渠道商（用于袋牌命名）

- USPS
- UPS
- FEDEX
- GOFO
- UNIUNI
- SPEEDX

## API 功能列表

### 接口 1：生成袋牌号

#### 功能描述
- 提供生成袋牌号的能力。
- 支持单个或批量生成袋牌号。
- 生成的袋牌号需符合统一命名规则。

#### 功能要求
- 调用方可指定生成数量。
- 系统需保证生成的袋牌号唯一。
- 返回生成成功的袋牌号列表。

### 接口 2：打开袋牌

#### 功能描述
- 将指定袋牌置为"打开"状态。
- 打开后的袋牌可参与后续业务操作。

#### 功能要求
- 仅存在的袋牌可被打开。
- 已打开的袋牌不可重复打开。
- 已关闭的袋牌不可再次打开。

### 接口 3：关闭袋牌

#### 功能描述
- 将指定袋牌置为"关闭"状态。
- 关闭后的袋牌不可再参与任何业务操作。

#### 功能要求
- 仅存在的袋牌可被关闭。
- 已关闭的袋牌不可重复关闭。

### 接口 4：关联尾程运单号与袋牌

#### 功能描述
- 将尾程运单号与指定袋牌建立关联关系。
- 关联行为不依赖尾程运单号所属渠道商。
- 系统不对尾程运单号进行渠道识别或校验。

#### 功能要求
- 仅"已打开"的袋牌允许进行关联。
- 关联时：
  - 不区分运单号来源（扫描 / 客户传输 / 外部系统）
  - 不针对任何渠道做特殊处理
- 系统需保存：
  - 原始输入的尾程运单号
  - 袋牌与运单号之间的关联关系
- 对格式异常或不符合业务预期的运单号，处理方式由业务流程决定（如拒绝或标记异常）。

## 状态与使用约束

- 袋牌生命周期包括：
  - 已生成
  - 已打开
  - 已关闭
- 仅"已打开"的袋牌允许关联尾程运单号。

## 功能性总结

- 系统提供统一的袋牌生成能力，支持批量操作。
- 系统支持袋牌的生命周期管理（打开 / 关闭）。
- 系统支持将任意尾程运单号与袋牌进行关联。