jennisonzhang/LabelChange-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

上传源代码版本

Browse Source
This commit is contained in:
Im-Jenisson
2026-06-01 16:30:29 +08:00
commit b2a9b7d3c2
462 changed files with 104365 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

257
变色龙换单系统后端-系统设计文档.md Normal file
View File

@@ -0,0 +1,257 @@
# 标签替换服务系统设计文档
## 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 |