257 lines
13 KiB
Markdown
257 lines
13 KiB
Markdown
# 标签替换服务系统设计文档
|
||
|
||
## 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 | |