LabelChange-server/袋牌模块设计文档.md

袋牌模块设计文档

1. 模块概述

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

1.1 设计目标

• 提供统一的袋牌生成能力，支持单个或批量生成
• 支持袋牌的生命周期管理（生成、打开、关闭）
• 支持袋牌与尾程运单号的关联
• 确保袋牌的唯一性和完整性
• 保持与系统其他模块的一致性

1.2 适用场景

• 物流分拣中心的袋牌管理
• 仓库装箱操作中的袋牌追踪
• 运输过程中的袋牌交接
• 尾程配送的袋牌关联

2. 系统架构

2.1 架构层次

袋牌模块采用分层架构设计，与系统其他模块保持一致：

┌─────────────────────┐
│    CONTROLLER层     │  // 控制器层，处理HTTP请求
├─────────────────────┤
│      BLL层          │  // 业务逻辑层，实现核心业务逻辑
├─────────────────────┤
│      DAL层          │  // 数据访问层，处理数据库操作
├─────────────────────┤
│      MDL层          │  // 数据模型层，定义数据结构
└─────────────────────┘

2.2 核心组件

组件名称	所在文件	功能描述
BagTagEntity	MDL/Models/BagTagEntity.cs	袋牌实体模型
BagTagWaybillEntity	MDL/Models/BagTagWaybillEntity.cs	袋牌与尾程运单号关联实体模型
IBagTagRepository	DAL/Interfaces/IBagTagRepository.cs	袋牌数据访问接口
BagTagRepository	DAL/Repositories/BagTagRepository.cs	袋牌数据访问实现
IBagTagService	BLL/Interfaces/IBagTagService.cs	袋牌业务逻辑接口
BagTagService	BLL/Services/BagTagService.cs	袋牌业务逻辑实现
BagTagController	CONTROLLER/Controllers/BagTagController.cs	袋牌API控制器

3. 数据模型设计

3.1 袋牌实体（BagTagEntity）

字段名称	数据类型	长度	约束	描述
Id	int	-	主键，自增	袋牌ID
TagNumber	string	100	非空，唯一	袋牌号
ChannelName	string	50	非空	渠道商名称
Status	string	20	默认"Generated"	状态：Generated, Opened, Closed
CreatedAt	DateTime	-	默认当前时间	创建时间
OpenedAt	DateTime	-	可空	打开时间
ClosedAt	DateTime	-	可空	关闭时间

3.2 袋牌与尾程运单号关联实体（BagTagWaybillEntity）

字段名称	数据类型	长度	约束	描述
Id	int	-	主键，自增	关联ID
TagNumber	string	100	非空	袋牌号
FinalMileTrackingNumber	string	100	非空	尾程运单号
CreatedAt	DateTime	-	默认当前时间	创建时间
Creator	string	50	非空	创建人
Remark	string	200	可空	备注

3.3 请求模型（BagTagRequest）

模型名称	字段名称	数据类型	描述
GenerateBagTagsRequest	ChannelName	string	渠道商名称
GenerateBagTagsRequest	Count	int	生成数量，默认1
OpenBagTagRequest	TagNumber	string	袋牌号
CloseBagTagRequest	TagNumber	string	袋牌号
AssociateWaybillRequest	TagNumber	string	袋牌号
AssociateWaybillRequest	FinalMileTrackingNumber	string	尾程运单号

4. 业务逻辑设计

4.1 袋牌生成

• 功能：根据渠道商名称和数量生成袋牌号
• 流程：
  1. 接收生成请求（渠道商名称、数量）
  2. 生成时间戳（精确到秒）
  3. 循环生成指定数量的袋牌号
  4. 每个袋牌号由渠道商名称（大写）+ 时间戳 + 序号组成
  5. 将生成的袋牌保存到数据库
  6. 返回生成的袋牌号列表

4.2 袋牌打开

• 功能：将袋牌状态设置为"打开"
• 流程：
  1. 接收打开请求（袋牌号）
  2. 验证袋牌是否存在
  3. 验证袋牌状态是否为"Generated"
  4. 更新袋牌状态为"Opened"
  5. 记录打开时间
  6. 返回操作结果

4.3 袋牌关闭

• 功能：将袋牌状态设置为"关闭"
• 流程：
  1. 接收关闭请求（袋牌号）
  2. 验证袋牌是否存在
  3. 验证袋牌状态是否为"Opened"
  4. 更新袋牌状态为"Closed"
  5. 记录关闭时间
  6. 返回操作结果

4.4 尾程运单号关联

• 功能：将尾程运单号与袋牌建立关联
• 流程：
  1. 接收关联请求（袋牌号、尾程运单号）
  2. 验证袋牌是否存在
  3. 验证袋牌状态是否为"Opened"
  4. 创建关联记录
  5. 保存到数据库
  6. 返回操作结果

5. 数据库设计

5.1 袋牌表（bag_tags）

CREATE TABLE IF NOT EXISTS `bag_tags` (
  `Id` INT(11) NOT NULL AUTO_INCREMENT,
  `TagNumber` VARCHAR(100) NOT NULL COMMENT '袋牌号',
  `ChannelName` VARCHAR(50) NOT NULL COMMENT '渠道商名称',
  `Status` VARCHAR(20) DEFAULT 'Generated' COMMENT '状态：Generated, Opened, Closed',
  `CreatedAt` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `OpenedAt` DATETIME DEFAULT NULL COMMENT '打开时间',
  `ClosedAt` DATETIME DEFAULT NULL COMMENT '关闭时间',
  PRIMARY KEY (`Id`),
  UNIQUE KEY `UK_TagNumber` (`TagNumber`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='袋牌表';

5.2 袋牌与尾程运单号关联表（bag_tag_waybills）

CREATE TABLE IF NOT EXISTS `bag_tag_waybills` (
  `Id` INT(11) NOT NULL AUTO_INCREMENT,
  `TagNumber` VARCHAR(100) NOT NULL COMMENT '袋牌号',
  `FinalMileTrackingNumber` VARCHAR(100) NOT NULL COMMENT '尾程运单号',
  `CreatedAt` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `Creator` VARCHAR(50) NOT NULL COMMENT '创建人',
  `Remark` VARCHAR(200) NULL COMMENT '备注',
  PRIMARY KEY (`Id`),
  KEY `IX_TagNumber` (`TagNumber`),
  KEY `IX_FinalMileTrackingNumber` (`FinalMileTrackingNumber`),
  CONSTRAINT `FK_bag_tag_waybills_bag_tags` FOREIGN KEY (`TagNumber`) REFERENCES `bag_tags` (`TagNumber`) ON DELETE CASCADE ON UPDATE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='袋牌与尾程运单号关联表';

6. 实现细节

6.1 技术栈

• 语言：C#
• 框架：ASP.NET Core
• 数据库：MySQL
• ORM：SqlSugar
• 依赖注入：Microsoft.Extensions.DependencyInjection

6.2 核心实现

6.2.1 袋牌生成实现

袋牌生成采用"渠道商名称+时间戳+序号"的格式，确保袋牌号的唯一性：

var timestamp = DateTime.Now.ToString("yyyyMMddHHmmss");
var serialNumber = i.ToString("D4");
var tagNumber = $"{channelName.ToUpper()}{timestamp}{serialNumber}";

6.2.2 状态管理实现

袋牌状态流转：

• 生成时：状态为"Generated"
• 打开后：状态变为"Opened"，记录打开时间
• 关闭后：状态变为"Closed"，记录关闭时间

6.2.3 关联逻辑实现

只有状态为"Opened"的袋牌才能关联尾程运单号，确保业务逻辑的正确性：

if (tag.Status != "Opened")
{
    return false;
}

6.3 依赖注入配置

袋牌模块的依赖注入配置在Program.cs中：

builder.Services.AddScoped<IBagTagRepository, BagTagRepository>();
builder.Services.AddScoped<IBagTagService, BagTagService>();

7. 扩展性设计

7.1 数据模型扩展

• 支持在BagTagEntity中添加自定义字段
• 支持在BagTagWaybillEntity中添加关联信息

7.2 业务逻辑扩展

• 支持添加新的袋牌状态
• 支持添加袋牌的额外属性和验证规则
• 支持扩展袋牌生成的命名规则

7.3 接口扩展

• 支持添加新的API接口
• 支持添加袋牌的批量操作接口
• 支持添加袋牌的查询和统计接口

8. 代码结构

src/
├── MDL/
│   └── Models/
│       ├── BagTagEntity.cs          // 袋牌实体模型
│       ├── BagTagWaybillEntity.cs   // 袋牌与尾程运单号关联实体模型
│       └── BagTagRequest.cs          // 袋牌相关的请求模型
├── DAL/
│   ├── Interfaces/
│   │   └── IBagTagRepository.cs      // 袋牌数据访问接口
│   └── Repositories/
│       └── BagTagRepository.cs       // 袋牌数据访问实现
├── BLL/
│   ├── Interfaces/
│   │   └── IBagTagService.cs         // 袋牌业务逻辑接口
│   └── Services/
│       └── BagTagService.cs          // 袋牌业务逻辑实现
└── CONTROLLER/
    └── Controllers/
        └── BagTagController.cs        // 袋牌API控制器

9. 总结

袋牌模块通过分层架构设计，实现了袋牌的全生命周期管理和与尾程运单号的关联功能。该模块设计合理、结构清晰、扩展性强，能够满足物流业务中对袋牌管理的各种需求。

• 数据一致性：与系统其他模块保持一致的命名规范和数据结构
• 业务完整性：实现了袋牌从生成到关闭的完整生命周期管理
• 系统集成性：与系统其他模块无缝集成，共享相同的技术栈和架构
• 可扩展性：设计考虑了未来的功能扩展和业务变化

袋牌模块的实现为物流业务中的袋牌管理提供了一个可靠、高效的解决方案，支持各种业务场景的需求。