LabelChange-server/袋牌模块需求文档.md

袋牌模块需求文档

目标说明

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

基本概念

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

袋牌命名功能要求

3.1 命名规则

袋牌号由以下三部分组成：

• 渠道商全称（英文大写）
• 生成时间（精确到秒）
• 序号（用于保证唯一性）

命名格式：

{渠道商全称}{YYYYMMDDHHMMSS}{序号}

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

• USPS
• UPS
• FEDEX
• GOFO
• UNIUNI
• SPEEDX

API 功能列表

接口 1：生成袋牌号

功能描述

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

功能要求

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

接口 2：打开袋牌

功能描述

• 将指定袋牌置为"打开"状态。
• 打开后的袋牌可参与后续业务操作。

功能要求

• 仅存在的袋牌可被打开。
• 已打开的袋牌不可重复打开。
• 已关闭的袋牌不可再次打开。

接口 3：关闭袋牌

功能描述

• 将指定袋牌置为"关闭"状态。
• 关闭后的袋牌不可再参与任何业务操作。

功能要求

• 仅存在的袋牌可被关闭。
• 已关闭的袋牌不可重复关闭。

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

功能描述

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

功能要求

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

状态与使用约束

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

功能性总结

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