492 lines
15 KiB
Markdown
492 lines
15 KiB
Markdown
# 变色龙换单系统全流程文档
|
||
|
||
## 1. 项目概述
|
||
|
||
变色龙换单系统是一个用于处理标签替换请求、Excel数据导入、物流消息解析和标签扫描记录的完整系统。该系统采用前后端分离架构，后端负责业务逻辑处理和数据存储，前端提供用户交互界面。系统的核心功能包括标签替换请求处理、Excel数据导入、物流数据解析、标签验证与处理、API接口服务、日志记录与监控以及标签扫描记录管理。
|
||
|
||
## 2. 系统架构
|
||
|
||
### 2.1 技术栈
|
||
|
||
| 技术/框架 | 用途 |
|
||
| --- | --- |
|
||
| C# | 后端开发语言 |
|
||
| ASP.NET Core | 后端Web框架 |
|
||
| SqlSugar | ORM框架，用于数据库操作 |
|
||
| Serilog | 日志记录框架 |
|
||
| EPPlus | Excel文件解析库 |
|
||
| UDP | 用于实时消息通信 |
|
||
| Mermaid | 流程图绘制工具 |
|
||
|
||
### 2.2 系统架构图
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Client[客户端] --> API[API层/CONTROLLER]
|
||
API --> BLL[业务逻辑层/BLL]
|
||
BLL --> DAL[数据访问层/DAL]
|
||
DAL --> DB[数据库]
|
||
BLL --> Service[外部服务]
|
||
|
||
subgraph 后端系统
|
||
API
|
||
BLL
|
||
DAL
|
||
DB
|
||
Service
|
||
end
|
||
|
||
subgraph 前端系统
|
||
Client
|
||
end
|
||
```
|
||
|
||
### 2.3 模块划分
|
||
|
||
| 模块 | 主要职责 | 文件位置 |
|
||
| --- | --- | --- |
|
||
| 标签替换模块 | 处理标签替换请求 | src/BLL/Services/LabelService.cs |
|
||
| Excel导入模块 | 处理Excel数据导入 | src/BLL/Services/ExcelImportService.cs |
|
||
| 物流消息解析模块 | 解析物流接口消息 | src/BLL/Services/LogisticsMessageService.cs |
|
||
| 标签扫描记录模块 | 管理标签扫描记录 | src/BLL/Services/LabelScanService.cs |
|
||
| API接口模块 | 提供RESTful API接口 | src/CONTROLLER/Controllers/LabelController.cs |
|
||
|
||
## 3. 功能模块
|
||
|
||
### 3.1 标签替换模块
|
||
|
||
#### 3.1.1 功能描述
|
||
|
||
标签替换模块负责接收标签替换请求，验证请求参数和API权限，执行标签替换操作，并保存操作记录。
|
||
|
||
#### 3.1.2 核心流程
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[接收标签替换请求] --> B[验证请求参数]
|
||
B -->|参数无效| C[返回错误响应]
|
||
B -->|参数有效| D[验证API权限]
|
||
D -->|权限验证失败| E[返回401错误]
|
||
D -->|权限验证成功| F[执行标签替换操作]
|
||
F --> G[保存操作记录]
|
||
G --> H[返回成功响应]
|
||
```
|
||
|
||
#### 3.1.3 详细步骤
|
||
|
||
1. **接收标签替换请求**
|
||
- API层接收客户端发送的标签替换请求
|
||
- 验证请求格式和参数
|
||
|
||
2. **验证API权限**
|
||
- 检查客户端的API权限
|
||
- 验证API密钥的有效性
|
||
|
||
3. **执行标签替换操作**
|
||
- 根据请求参数构建标签替换请求
|
||
- 处理标签内容（如base64解码等）
|
||
- 执行标签替换逻辑
|
||
|
||
4. **保存操作记录**
|
||
- 将操作记录保存到数据库的`label_replace_requests`表
|
||
- 记录操作时间、操作人员、操作结果等信息
|
||
|
||
5. **返回响应**
|
||
- 根据操作结果返回相应的HTTP状态码
|
||
- 返回操作结果的详细信息
|
||
|
||
### 3.2 Excel导入模块
|
||
|
||
#### 3.2.1 功能描述
|
||
|
||
Excel导入模块负责接收Excel文件，解析文件内容，验证数据格式，处理数据逻辑，并将数据保存到数据库。
|
||
|
||
#### 3.2.2 核心流程
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[接收Excel文件] --> B[验证文件格式]
|
||
B -->|格式无效| C[返回错误响应]
|
||
B -->|格式有效| D[解析文件内容]
|
||
D --> E[验证数据格式]
|
||
E -->|数据无效| F[返回错误信息]
|
||
E -->|数据有效| G[处理数据逻辑]
|
||
G --> H[保存到数据库]
|
||
H --> I[返回导入结果]
|
||
```
|
||
|
||
#### 3.2.3 详细步骤
|
||
|
||
1. **接收Excel文件**
|
||
- 客户端通过API上传Excel文件
|
||
- 系统接收文件并进行初步处理
|
||
|
||
2. **验证文件格式**
|
||
- 检查文件是否为有效的Excel文件
|
||
- 验证文件大小是否在限制范围内
|
||
- 检查文件扩展名是否正确
|
||
|
||
3. **解析文件内容**
|
||
- 使用EPPlus库解析Excel文件
|
||
- 读取工作表数据
|
||
- 转换为系统内部数据结构
|
||
|
||
4. **验证数据格式**
|
||
- 检查数据是否符合预设的格式要求
|
||
- 验证必填字段是否存在
|
||
- 检查数据类型是否正确
|
||
|
||
5. **处理数据逻辑**
|
||
- 根据业务规则处理数据
|
||
- 执行必要的数据转换
|
||
- 处理数据间的关联关系
|
||
|
||
6. **保存到数据库**
|
||
- 将处理后的数据批量保存到数据库
|
||
- 处理可能的数据库异常
|
||
|
||
7. **返回导入结果**
|
||
- 返回导入成功或失败的信息
|
||
- 如果失败，返回详细的错误信息
|
||
- 如果成功，返回导入的数据量统计
|
||
|
||
### 3.3 物流消息解析模块
|
||
|
||
#### 3.3.1 功能描述
|
||
|
||
物流消息解析模块负责接收物流接口消息，验证消息格式，根据请求类型选择合适的解析器，解析消息内容，并保存解析结果。
|
||
|
||
#### 3.3.2 核心流程
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[接收物流消息] --> B[验证消息格式]
|
||
B -->|格式无效| C[返回错误响应]
|
||
B -->|格式有效| D[根据请求类型选择解析器]
|
||
D --> E[解析消息内容]
|
||
E --> F[验证解析结果]
|
||
F -->|解析失败| G[返回错误信息]
|
||
F -->|解析成功| H[保存解析结果]
|
||
H --> I[返回解析结果]
|
||
```
|
||
|
||
#### 3.3.3 详细步骤
|
||
|
||
1. **接收物流消息**
|
||
- 接收外部物流系统发送的消息
|
||
- 记录消息接收时间和来源
|
||
|
||
2. **验证消息格式**
|
||
- 检查消息格式是否符合要求
|
||
- 验证消息头和消息体的完整性
|
||
|
||
3. **选择解析器**
|
||
- 根据消息的请求类型选择合适的解析器
|
||
- 支持多种物流接口格式
|
||
|
||
4. **解析消息内容**
|
||
- 使用选定的解析器解析消息内容
|
||
- 提取关键信息，如运单号、物流状态、时间等
|
||
|
||
5. **验证解析结果**
|
||
- 检查解析结果是否符合预期格式
|
||
- 验证必填字段是否存在
|
||
- 检查数据的完整性
|
||
|
||
6. **保存解析结果**
|
||
- 将解析结果保存到数据库
|
||
- 记录解析时间、请求类型等信息
|
||
|
||
7. **返回解析结果**
|
||
- 返回解析成功或失败的信息
|
||
- 如果成功，返回解析后的结构化数据
|
||
|
||
### 3.4 标签扫描记录模块
|
||
|
||
#### 3.4.1 功能描述
|
||
|
||
标签扫描记录模块负责记录标签的扫描信息，包括扫描次数、首次扫描时间和最近扫描时间等。该模块会在标签下载时自动记录扫描信息，也提供API接口供外部系统调用。
|
||
|
||
#### 3.4.2 核心流程
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[触发扫描记录] --> B{触发方式}
|
||
B -->|标签下载| C[自动记录扫描]
|
||
B -->|API调用| D[接收扫描请求]
|
||
C --> E[验证运单号]
|
||
D --> E
|
||
E -->|验证失败| F[记录错误日志]
|
||
E -->|验证成功| G{记录是否存在}
|
||
G -->|存在| H[更新扫描次数和时间]
|
||
G -->|不存在| I[创建新扫描记录]
|
||
H --> J[返回成功响应]
|
||
I --> J
|
||
F --> K[返回错误响应]
|
||
```
|
||
|
||
#### 3.4.3 详细步骤
|
||
|
||
1. **触发扫描记录**
|
||
- 标签下载时自动触发
|
||
- API接口调用触发
|
||
- 内部模块调用触发
|
||
|
||
2. **验证运单号**
|
||
- 检查运单号是否为空
|
||
- 验证运单号格式是否正确
|
||
|
||
3. **处理扫描记录**
|
||
- 如果记录已存在，更新扫描次数和最近扫描时间
|
||
- 如果记录不存在，创建新的扫描记录
|
||
|
||
4. **返回响应**
|
||
- 返回扫描记录的处理结果
|
||
- 记录操作日志
|
||
|
||
## 4. UDP消息处理流程
|
||
|
||
### 4.1 UDP消息接收与处理
|
||
|
||
系统通过UDP协议接收实时消息，支持JSON格式和纯文本格式的消息处理。
|
||
|
||
#### 4.1.1 整体流程
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[开始监听UDP端口] --> B[接收UDP消息]
|
||
B --> C[调用HandleMessageAsync]
|
||
C --> D{尝试解析为JSON}
|
||
D -->|成功| E{消息类型}
|
||
D -->|失败| F[处理为纯文本跟踪号]
|
||
E -->|label_update| G[调用ProcessLabelUpdateAsync]
|
||
E -->|label_request| H[调用ProcessLabelRequestAsync]
|
||
E -->|label_delete| I[调用ProcessLabelDeleteAsync]
|
||
E -->|print_request| J[调用ProcessPrintRequestAsync]
|
||
E -->|status_request| K[调用ProcessStatusRequestAsync]
|
||
E -->|其他| F
|
||
F --> L[调用ProcessTextMessageAsync]
|
||
G --> M[发送响应]
|
||
H --> M
|
||
I --> M
|
||
J --> M
|
||
K --> M
|
||
L --> M
|
||
M --> B
|
||
```
|
||
|
||
#### 4.1.2 JSON消息处理流程
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant UDPS as UdpService
|
||
participant UMH as UdpMessageHandler
|
||
participant LS as LabelService
|
||
participant UDP as UDP客户端
|
||
|
||
UDPS->>UMH: 触发MessageReceived事件
|
||
UMH->>UMH: 解析JSON消息
|
||
UMH->>LS: 根据消息类型调用对应方法
|
||
LS->>LS: 执行业务逻辑
|
||
LS-->>UMH: 返回处理结果
|
||
UMH->>UDPS: 发送响应消息
|
||
UDPS->>UDP: 发送UDP响应
|
||
```
|
||
|
||
#### 4.1.3 纯文本消息处理流程
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant UDPS as UdpService
|
||
participant UMH as UdpMessageHandler
|
||
participant LPS as LabelProcessService
|
||
participant LAS as LabelApiService
|
||
participant PPS as PdfPrintService
|
||
participant API as 后端API
|
||
participant PRT as 打印机
|
||
participant UDP as UDP客户端
|
||
|
||
UDPS->>UMH: 触发MessageReceived事件
|
||
UMH->>UMH: JSON解析失败
|
||
UMH->>LPS: 调用ProcessTextMessageAsync
|
||
LPS->>LAS: 调用GetLabelPdfAsync
|
||
LAS->>API: 请求面单PDF
|
||
API-->>LAS: 返回PDF字节流
|
||
LAS-->>LPS: 返回PDF字节流
|
||
LPS->>PPS: 调用PrintPdfAsync
|
||
PPS->>PRT: 打印PDF
|
||
PRT-->>PPS: 返回打印结果
|
||
PPS-->>LPS: 返回打印结果
|
||
LPS-->>UMH: 返回处理结果
|
||
UMH->>UDPS: 发送响应消息
|
||
UDPS->>UDP: 发送UDP响应
|
||
```
|
||
|
||
## 5. 系统交互流程
|
||
|
||
### 5.1 客户端与服务器交互流程
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Client as 客户端
|
||
participant API as API层
|
||
participant BLL as 业务逻辑层
|
||
participant DAL as 数据访问层
|
||
participant DB as 数据库
|
||
|
||
Client->>API: 发送API请求
|
||
API->>API: 验证请求格式
|
||
API->>BLL: 调用业务逻辑
|
||
BLL->>DAL: 访问数据
|
||
DAL->>DB: 执行数据库操作
|
||
DB-->>DAL: 返回数据
|
||
DAL-->>BLL: 返回结果
|
||
BLL-->>API: 返回业务处理结果
|
||
API-->>Client: 返回响应
|
||
```
|
||
|
||
#### 5.1.1 详细步骤
|
||
|
||
1. **客户端发送请求**
|
||
- 客户端根据接口文档构建请求
|
||
- 设置请求头和请求体
|
||
- 发送HTTP请求到服务器
|
||
|
||
2. **API层接收请求**
|
||
- API层接收客户端请求
|
||
- 验证请求格式和参数
|
||
- 记录请求日志
|
||
|
||
3. **调用业务逻辑**
|
||
- API层调用BLL层的相应服务
|
||
- 传递处理所需的参数
|
||
|
||
4. **数据访问**
|
||
- BLL层根据业务需求调用DAL层
|
||
- DAL层执行数据库操作
|
||
|
||
5. **返回结果**
|
||
- 数据库返回查询结果
|
||
- DAL层将结果传递给BLL层
|
||
- BLL层处理业务逻辑并返回结果
|
||
- API层构建响应并返回给客户端
|
||
|
||
## 6. 异常处理流程
|
||
|
||
### 6.1 异常处理流程
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[发生异常] --> B[捕获异常]
|
||
B --> C[记录异常日志]
|
||
C --> D[分析异常类型]
|
||
D -->|业务异常| E[返回业务错误信息]
|
||
D -->|系统异常| F[返回系统错误信息]
|
||
D -->|权限异常| G[返回401错误]
|
||
```
|
||
|
||
#### 6.1.1 详细步骤
|
||
|
||
1. **发生异常**
|
||
- 系统在执行过程中遇到错误
|
||
- 可能是业务逻辑错误、数据访问错误或系统级错误
|
||
|
||
2. **捕获异常**
|
||
- 使用try-catch语句捕获异常
|
||
- 确保异常不会导致系统崩溃
|
||
|
||
3. **记录异常日志**
|
||
- 将异常信息记录到日志文件
|
||
- 包括异常类型、错误消息、堆栈跟踪等
|
||
- 记录异常发生的时间、位置和上下文信息
|
||
|
||
4. **分析异常类型**
|
||
- 识别异常的类型和原因
|
||
- 区分业务异常、系统异常和权限异常
|
||
|
||
5. **返回错误响应**
|
||
- 根据异常类型返回相应的HTTP状态码
|
||
- 返回详细的错误信息
|
||
- 对于业务异常，返回具体的错误原因
|
||
- 对于系统异常，返回通用的错误信息
|
||
|
||
## 7. 日志记录流程
|
||
|
||
### 7.1 日志记录流程
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[系统事件发生] --> B[生成日志信息]
|
||
B --> C[确定日志级别]
|
||
C --> D[格式化日志内容]
|
||
D --> E[写入日志文件]
|
||
E --> F[定期清理旧日志]
|
||
```
|
||
|
||
#### 7.1.1 详细步骤
|
||
|
||
1. **系统事件发生**
|
||
- 用户操作触发系统事件
|
||
- 系统内部状态变化
|
||
- 异常或错误发生
|
||
|
||
2. **生成日志信息**
|
||
- 收集事件相关的信息
|
||
- 包括事件类型、时间、用户、操作内容等
|
||
|
||
3. **确定日志级别**
|
||
- 根据事件的重要性确定日志级别
|
||
- 常见级别：Debug、Information、Warning、Error、Fatal
|
||
|
||
4. **格式化日志内容**
|
||
- 使用统一的格式格式化日志内容
|
||
- 包括时间戳、日志级别、事件描述、上下文信息等
|
||
|
||
5. **写入日志文件**
|
||
- 将格式化后的日志写入日志文件
|
||
- 支持按时间或大小分割日志文件
|
||
|
||
6. **定期清理旧日志**
|
||
- 根据配置定期清理旧日志文件
|
||
- 保留指定天数的日志记录
|
||
|
||
## 8. 数据库设计
|
||
|
||
### 8.1 主要数据表
|
||
|
||
#### 8.1.1 标签替换请求表 (label_replace_requests)
|
||
|
||
| 字段名 | 数据类型 | 描述 |
|
||
| --- | --- | --- |
|
||
| Id | int | 主键ID |
|
||
| NeutralWaybillNumber | string | 中性运单号 |
|
||
| ReferenceNumber | string | 参考号 |
|
||
| FinalMileTrackingNumber | string | 末端跟踪号 |
|
||
| LabelContent | string | 标签内容 |
|
||
| CreatedAt | datetime | 创建时间 |
|
||
| UpdatedAt | datetime | 更新时间 |
|
||
|
||
#### 8.1.2 标签扫描记录表 (label_scan_records)
|
||
|
||
| 字段名 | 数据类型 | 描述 |
|
||
| --- | --- | --- |
|
||
| Id | int | 主键ID |
|
||
| NeutralWaybillNumber | string | 中性运单号 |
|
||
| ScanCount | int | 扫描次数 |
|
||
| FirstScanAt | datetime | 首次扫描时间 |
|
||
| LastScanAt | datetime | 最近扫描时间 |
|
||
| CreatedAt | datetime | 创建时间 |
|
||
| UpdatedAt | datetime | 更新时间 |
|
||
|
||
## 9. 文档版本控制
|
||
|
||
| 版本 | 更新日期 | 更新内容 | 更新人 |
|
||
| --- | --- | --- | --- |
|
||
| 1.0 | 2026-01-16 | 初始版本 | 系统开发团队 |
|
||
| 1.1 | 2026-01-19 | 1. 新增标签扫描记录模块<br>2. 详细描述了UDP消息处理流程<br>3. 整合前后端流程文档<br>4. 添加了数据库设计章节 | 系统开发团队 |
|
||
|
||
## 10. 总结
|
||
|
||
变色龙换单系统是一个功能完整的标签替换和管理系统，采用前后端分离架构，支持标签替换请求处理、Excel数据导入、物流消息解析和标签扫描记录等核心功能。系统具有良好的扩展性和可维护性，采用分层架构和模块化设计，便于后续功能扩展和系统升级。
|
||
|
||
本全流程文档整合了后端系统设计文档、后端系统流程文档和前端流程文档的内容，全面描述了系统的架构、功能模块、业务流程和技术实现，为开发人员和用户提供了完整的系统参考资料。 |