jennisonzhang/LabelChange-server

Fork 0

Files

Im-Jenisson b2a9b7d3c2 上传源代码版本

2026-06-01 16:30:29 +08:00

13 KiB

Raw Permalink Blame History

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

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 核心流程

接收标签替换请求
验证客户API权限
验证请求参数
执行标签替换操作
保存操作记录
返回操作结果

6.2 Excel导入模块

6.2.1 功能描述

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

6.2.2 核心流程

接收Excel文件
解析文件内容
验证数据格式
处理数据逻辑
保存到数据库
返回导入结果

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

13 KiB Raw Permalink Blame History Unescape Escape