# 标签替换服务系统设计文档

## 1. 系统概述

### 1.1 系统简介
标签替换服务系统是一个基于.NET Core的后台服务，主要用于处理物流标签的替换请求。系统支持多种数据格式的导入和处理，提供API接口供外部系统调用，并具备完善的日志记录和错误处理机制。

### 1.2 系统功能
- 标签替换请求处理
- Excel数据导入
- 物流数据解析
- 标签验证与处理
- API接口服务
- 日志记录与监控
- 标签扫描记录管理

## 2. 架构设计

### 2.1 分层架构
系统采用经典的分层架构设计，各层之间通过接口进行通信，实现了高内聚、低耦合的设计目标。

```
+---------------------+
|    CONTROLLER层     |
|  (API接口层)        |
+---------------------+
          ↑
          |
+---------------------+
|       BLL层         |
|  (业务逻辑层)        |
+---------------------+
          ↑
          |
+---------------------+
|       DAL层         |
|  (数据访问层)        |
+---------------------+
          ↑
          |
+---------------------+
|       DB层          |
|  (数据库操作层)      |
+---------------------+
          ↑
          |
+---------------------+
|       MDL层         |
|  (数据模型层)        |
+---------------------+
```

### 2.2 模块划分

| 模块 | 主要职责 | 文件位置 |
|------|----------|----------|
| 标签替换模块 | 处理标签替换请求 | src/BLL/Services/LabelReplaceService.cs |
| Excel导入模块 | 处理Excel数据导入 | src/BLL/Services/ExcelImportService.cs |
| 物流解析模块 | 解析物流数据 | src/BLL/Services/LogisticsParserService.cs |
| 标签验证模块 | 验证标签有效性 | src/BLL/Services/TagValidationService.cs |
| 标签扫描记录模块 | 管理标签扫描记录 | src/BLL/Services/LabelScanService.cs |
| API接口模块 | 提供RESTful API | src/CONTROLLER/Controllers/ |

## 3. 数据库设计

### 3.1 数据模型

#### 3.1.1 标签替换请求表 (label_replace_requests)

| 字段名 | 数据类型 | 约束 | 描述 |
|--------|----------|------|------|
| Id | INT UNSIGNED | PRIMARY KEY, AUTO_INCREMENT | 主键ID，自增 |
| BillOfLadingNumber | VARCHAR(100) | NULL | 提单号 |
| MasterPackageNumber | VARCHAR(100) | NULL | 大包号 |
| ReferenceNumber | VARCHAR(100) | NULL | 参考号（一般表示订单号） |
| NeutralWaybillNumber | VARCHAR(100) | NOT NULL | 中性面单单号（必填） |
| FinalMileTrackingNumber | VARCHAR(100) | NULL | 尾程跟踪单号 |
| Label | LONGTEXT | NULL | 标签内容（一般为PDF，可能是base64或其他格式） |
| ReplaceStatus | CHAR(1) | NOT NULL DEFAULT 'Y' | 换单状态（Y表示正常换单，N表示冻结换单） |
| CreatedAt | DATETIME | NOT NULL | 创建时间 |
| UpdatedAt | DATETIME | NOT NULL | 更新时间 |

#### 3.1.2 客户API表 (customer_apis)

| 字段名 | 数据类型 | 约束 | 描述 |
|--------|----------|------|------|
| id | INT UNSIGNED | PRIMARY KEY, AUTO_INCREMENT | 主键ID，自增 |
| customer_id | INT UNSIGNED | NOT NULL | 客户ID |
| customer_code | VARCHAR(50) | NOT NULL | 客户代码 |
| api_key | VARCHAR(100) | NOT NULL | API密钥 |
| status | CHAR(1) | NOT NULL DEFAULT 'Y' | API状态（Y：启用，N：禁用） |
| expire_date | DATETIME | NULL | 密钥过期时间 |
| created_at | DATETIME | NOT NULL | 创建时间 |
| updated_at | DATETIME | NOT NULL | 更新时间 |

#### 3.1.3 标签历史扫描记录表 (label_scan_history)

| 字段名 | 数据类型 | 约束 | 描述 |
|--------|----------|------|------|
| Id | INT UNSIGNED | PRIMARY KEY, AUTO_INCREMENT | 主键ID，自增 |
| CustomerId | INT UNSIGNED | NOT NULL | 客户ID |
| ReferenceNumber | VARCHAR(100) | NULL | 参考号（一般表示订单号） |
| NeutralWaybillNumber | VARCHAR(100) | NOT NULL | 中性面单单号 |
| FinalMileTrackingNumber | VARCHAR(100) | NULL | 尾程跟踪单号 |
| Result | TINYINT UNSIGNED | NOT NULL | 扫描结果：0=已返回面单, 1=无面单数据, 2=无下单数据, 3=订单被冻结, 4=其他 |
| Description | VARCHAR(500) | NULL | 描述 |
| CreatedBy | VARCHAR(100) | NOT NULL | 创建人 |
| CreatedAt | DATETIME | NOT NULL | 创建时间 |
| UpdatedAt | DATETIME | NOT NULL | 更新时间 |

## 4. 技术栈

| 技术/框架 | 版本 | 用途 |
|-----------|------|------|
| .NET Core | 7.0+ | 开发框架 |
| SqlSugar | 5.1.4.207 | ORM框架 |
| EPPlus | - | Excel处理 |
| Serilog | - | 日志框架 |
| Swagger | - | API文档 |
| MySQL | - | 数据库 |

## 5. 系统架构图

```
┌─────────────────────────────────────────────────────────────────┐
│                     客户端应用/外部系统                          │
└─────────────────────────────┬───────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────────┐
│                        API网关                                  │
└─────────────────────────────┬───────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────────┐
│                     CONTROLLER层                                │
│  ┌──────────────────────┐  ┌──────────────────────┐  ┌───────────┐
│  │    TagController     │  │ ExcelImportController │  │LabelController│
│  └──────────────────────┘  └──────────────────────┘  └───────────┘
└─────────────────────────────┬───────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────────┐
│                        BLL层                                    │
│  ┌──────────────────────┐  ┌──────────────────────┐  ┌───────────┐
│  │ LabelReplaceService  │  │ ExcelImportService   │  │LabelScanService│
│  └──────────────────────┘  └──────────────────────┘  └───────────┘
│  ┌──────────────────────┐  ┌──────────────────────┐             │
│  │ TagValidationService │  │ LogisticsParserService│             │
│  └──────────────────────┘  └──────────────────────┘             │
└─────────────────────────────┬───────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────────┐
│                        DAL层                                    │
│  ┌──────────────────────┐  ┌──────────────────────┐  ┌───────────┐
│  │ LabelReplaceRepo     │  │ CustomerRepo         │  │LabelScanRepo│
│  └──────────────────────┘  └──────────────────────┘  └───────────┘
└─────────────────────────────┬───────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────────┐
│                        DB层                                     │
│  ┌──────────────────────┐  ┌──────────────────────┐             │
│  │ 数据库连接管理       │  │ SQL语句执行          │             │
│  └──────────────────────┘  └──────────────────────┘             │
└─────────────────────────────┬───────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────────┐
│                        数据库                                   │
└─────────────────────────────────────────────────────────────────┘
```

## 6. 关键模块设计

### 6.1 标签替换模块

#### 6.1.1 功能描述
处理客户的标签替换请求，验证请求参数，执行标签替换操作，并返回结果。

#### 6.1.2 核心流程
1. 接收标签替换请求
2. 验证客户API权限
3. 验证请求参数
4. 执行标签替换操作
5. 保存操作记录
6. 返回操作结果

### 6.2 Excel导入模块

#### 6.2.1 功能描述
处理Excel文件的导入，解析文件内容，验证数据有效性，将数据保存到数据库。

#### 6.2.2 核心流程
1. 接收Excel文件
2. 解析文件内容
3. 验证数据格式
4. 处理数据逻辑
5. 保存到数据库
6. 返回导入结果

## 7. 安全设计

### 7.1 API认证
- 使用API密钥进行认证
- 支持密钥过期机制
- 记录API调用日志

### 7.2 数据安全
- 敏感数据加密存储
- 数据库访问权限控制
- 数据传输加密

## 8. 日志与监控

### 8.1 日志记录
- 使用Serilog进行日志记录
- 支持多级别日志（Info、Warning、Error）
- 日志文件按天滚动
- 记录API调用、错误信息、系统事件

### 8.2 监控指标
- API调用次数
- 响应时间
- 错误率
- 系统资源使用情况

## 9. 部署与维护

### 9.1 部署方式
- 支持Docker容器化部署
- 支持Windows/Linux环境
- 配置文件分离管理

### 9.2 维护策略
- 定期备份数据库
- 监控系统运行状态
- 及时更新依赖包
- 定期清理日志文件

## 10. 扩展设计

### 10.1 功能扩展
- 支持更多数据格式导入
- 增加报表统计功能
- 支持批量操作
- 增加用户管理系统

### 10.2 性能扩展
- 数据库读写分离
- 增加缓存机制
- 支持分布式部署
- 优化查询性能

## 11. 文档版本控制

| 版本 | 更新日期 | 更新内容 | 更新人 |
|------|----------|----------|--------|
| 1.0 | 2026-01-16 | 初始版本 | System Design Team |
| 1.1 | 2026-01-19 | 1. 添加标签扫描记录管理功能<br>2. 新增标签扫描记录表<br>3. 更新系统架构图，添加LabelController、LabelScanService和LabelScanRepo<br>4. 新增标签扫描记录模块 | System Design Team |
| 1.2 | 2026-01-22 | 1. 重构标签扫描记录模块为标签历史扫描记录<br>2. 更新数据库表结构为label_scan_history<br>3. 新增扫描结果枚举、客户ID、创建人等字段<br>4. 支持按客户和订单分组排序与统计功能 | System Design Team |
| 1.3 | 2026-01-23 | 1. 优化标签扫描记录逻辑，确保每个标签下载请求只记录一次扫描<br>2. 完善扫描结果处理逻辑，包括正常、订单冻结、无标签数据、异常等情况<br>3. 更新LabelController的DownloadLabelByWaybillNumber方法，确保扫描记录在finally块中执行 | System Design Team |