270 lines
9.6 KiB
Markdown
270 lines
9.6 KiB
Markdown
# 袋牌模块设计文档
|
||
|
||
## 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）
|
||
|
||
```sql
|
||
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）
|
||
|
||
```sql
|
||
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 袋牌生成实现
|
||
|
||
袋牌生成采用"渠道商名称+时间戳+序号"的格式，确保袋牌号的唯一性：
|
||
|
||
```csharp
|
||
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"的袋牌才能关联尾程运单号，确保业务逻辑的正确性：
|
||
|
||
```csharp
|
||
if (tag.Status != "Opened")
|
||
{
|
||
return false;
|
||
}
|
||
```
|
||
|
||
### 6.3 依赖注入配置
|
||
|
||
袋牌模块的依赖注入配置在Program.cs中：
|
||
|
||
```csharp
|
||
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. 总结
|
||
|
||
袋牌模块通过分层架构设计，实现了袋牌的全生命周期管理和与尾程运单号的关联功能。该模块设计合理、结构清晰、扩展性强，能够满足物流业务中对袋牌管理的各种需求。
|
||
|
||
- **数据一致性**：与系统其他模块保持一致的命名规范和数据结构
|
||
- **业务完整性**：实现了袋牌从生成到关闭的完整生命周期管理
|
||
- **系统集成性**：与系统其他模块无缝集成，共享相同的技术栈和架构
|
||
- **可扩展性**：设计考虑了未来的功能扩展和业务变化
|
||
|
||
袋牌模块的实现为物流业务中的袋牌管理提供了一个可靠、高效的解决方案，支持各种业务场景的需求。 |