# 袋牌模块设计文档

## 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. 总结

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

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

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