375 lines
12 KiB
Markdown
375 lines
12 KiB
Markdown
# 标签替换服务系统流程文档
|
||
|
||
## 1. 流程概述
|
||
|
||
本文档描述了标签替换服务系统的核心业务流程，包括标签替换请求处理流程、Excel数据导入流程和物流消息解析流程。通过流程图和详细步骤说明，帮助开发人员和用户理解系统的工作原理。
|
||
|
||
## 2. 系统核心流程
|
||
|
||
### 2.1 标签替换请求处理流程
|
||
|
||
#### 2.1.1 流程概述
|
||
此流程描述了系统处理标签替换请求的完整过程，从接收请求到返回结果的所有步骤。
|
||
|
||
#### 2.1.2 流程图
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[接收标签替换请求] --> B[验证请求参数]
|
||
B -->|参数无效| C[返回错误响应]
|
||
B -->|参数有效| D[验证API权限]
|
||
D -->|权限验证失败| E[返回401错误]
|
||
D -->|权限验证成功| F[执行标签替换操作]
|
||
F --> G[保存操作记录]
|
||
G --> H[返回成功响应]
|
||
```
|
||
|
||
#### 2.1.3 详细步骤
|
||
|
||
1. **接收标签替换请求**
|
||
- 客户端发送POST请求到`/api/Tag/label-replace`接口
|
||
- 接口接收请求头中的`customer_code`和`api_key`进行身份验证
|
||
- 请求体包含标签替换所需的各项参数
|
||
|
||
2. **验证请求参数**
|
||
- 检查请求体是否为空
|
||
- 验证必填字段`NeutralWaybillNumber`是否存在且有效
|
||
- 检查其他字段的数据格式是否符合要求
|
||
|
||
3. **验证API权限**
|
||
- 使用请求头中的`customer_code`和`api_key`查询数据库
|
||
- 验证API密钥是否有效
|
||
- 检查API密钥是否过期
|
||
- 验证客户是否有权限执行标签替换操作
|
||
|
||
4. **执行标签替换操作**
|
||
- 根据请求参数构建标签替换请求
|
||
- 处理标签内容（如base64解码等）
|
||
- 执行标签替换逻辑
|
||
|
||
5. **保存操作记录**
|
||
- 将操作记录保存到数据库的`label_replace_requests`表
|
||
- 记录操作时间、操作人员、操作结果等信息
|
||
|
||
6. **返回响应**
|
||
- 根据操作结果返回相应的HTTP状态码
|
||
- 返回操作结果的详细信息
|
||
|
||
### 2.2 Excel数据导入流程
|
||
|
||
#### 2.2.1 流程概述
|
||
此流程描述了系统处理Excel数据导入的完整过程，包括文件上传、数据解析、验证和保存。
|
||
|
||
#### 2.2.2 流程图
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[接收Excel文件] --> B[验证文件格式]
|
||
B -->|格式无效| C[返回错误响应]
|
||
B -->|格式有效| D[解析文件内容]
|
||
D --> E[验证数据格式]
|
||
E -->|数据无效| F[返回错误信息]
|
||
E -->|数据有效| G[处理数据逻辑]
|
||
G --> H[保存到数据库]
|
||
H --> I[返回导入结果]
|
||
```
|
||
|
||
#### 2.2.3 详细步骤
|
||
|
||
1. **接收Excel文件**
|
||
- 客户端通过API上传Excel文件
|
||
- 系统接收文件并进行初步处理
|
||
|
||
2. **验证文件格式**
|
||
- 检查文件是否为有效的Excel文件
|
||
- 验证文件大小是否在限制范围内
|
||
- 检查文件扩展名是否正确
|
||
|
||
3. **解析文件内容**
|
||
- 使用EPPlus库解析Excel文件
|
||
- 读取工作表数据
|
||
- 转换为系统内部数据结构
|
||
|
||
4. **验证数据格式**
|
||
- 检查数据是否符合预设的格式要求
|
||
- 验证必填字段是否存在
|
||
- 检查数据类型是否正确
|
||
|
||
5. **处理数据逻辑**
|
||
- 根据业务规则处理数据
|
||
- 执行必要的数据转换
|
||
- 处理数据间的关联关系
|
||
|
||
6. **保存到数据库**
|
||
- 将处理后的数据批量保存到数据库
|
||
- 处理可能的数据库异常
|
||
|
||
7. **返回导入结果**
|
||
- 返回导入成功或失败的信息
|
||
- 如果失败，返回详细的错误信息
|
||
- 如果成功，返回导入的数据量统计
|
||
|
||
### 2.3 物流消息解析流程
|
||
|
||
#### 2.3.1 流程概述
|
||
此流程描述了系统解析物流接口消息的完整过程，包括消息接收、解析、验证和结果返回。
|
||
|
||
#### 2.3.2 流程图
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[接收物流消息] --> B[验证消息格式]
|
||
B -->|格式无效| C[返回错误响应]
|
||
B -->|格式有效| D[根据请求类型选择解析器]
|
||
D --> E[解析消息内容]
|
||
E --> F[验证解析结果]
|
||
F -->|解析失败| G[返回错误信息]
|
||
F -->|解析成功| H[保存解析结果]
|
||
H --> I[返回解析结果]
|
||
```
|
||
|
||
#### 2.3.3 详细步骤
|
||
|
||
1. **接收物流消息**
|
||
- 客户端发送POST请求到`/api/Tag/logistics-parse`接口
|
||
- 请求体包含物流接口消息内容和请求类型
|
||
|
||
2. **验证消息格式**
|
||
- 检查请求体是否为空
|
||
- 验证`LogisticsInterface`字段是否存在且有效
|
||
- 检查`RequestType`字段是否有效
|
||
|
||
3. **根据请求类型选择解析器**
|
||
- 根据`RequestType`字段选择对应的解析器
|
||
- 初始化解析器实例
|
||
|
||
4. **解析消息内容**
|
||
- 使用选定的解析器解析物流消息
|
||
- 提取关键信息
|
||
- 转换为统一的数据格式
|
||
|
||
5. **验证解析结果**
|
||
- 检查解析结果是否符合预期格式
|
||
- 验证必填字段是否存在
|
||
- 检查数据的完整性
|
||
|
||
6. **保存解析结果**
|
||
- 将解析结果保存到数据库
|
||
- 记录解析时间、请求类型等信息
|
||
|
||
7. **返回解析结果**
|
||
- 返回解析成功或失败的信息
|
||
- 如果成功，返回解析后的结构化数据
|
||
|
||
### 2.4 标签扫描记录流程
|
||
|
||
#### 2.4.1 流程概述
|
||
此流程描述了系统记录标签扫描的完整过程，包括自动触发扫描和手动调用扫描记录接口的两种模式。特别强调了在标签下载过程中，确保每个请求只记录一次扫描记录的优化。
|
||
|
||
#### 2.4.2 流程图
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
subgraph 自动触发扫描（标签下载时）
|
||
A[接收标签下载请求] --> B[处理标签下载流程]
|
||
B --> C{下载成功？}
|
||
C -->|是| D[设置扫描结果为ReturnedLabel]
|
||
C -->|否| E{订单是否冻结？}
|
||
E -->|是| F[设置扫描结果为OrderFrozen]
|
||
E -->|否| G{无标签数据？}
|
||
G -->|是| H[设置扫描结果为NoLabelData]
|
||
G -->|否| I[设置扫描结果为Other]
|
||
D --> J[在finally块中记录扫描]
|
||
F --> J
|
||
H --> J
|
||
I --> J
|
||
J --> K[保存扫描记录到label_scan_history表]
|
||
end
|
||
|
||
subgraph 手动调用扫描接口
|
||
L[接收扫描记录请求] --> M[验证请求参数]
|
||
M -->|参数无效| N[返回错误响应]
|
||
M -->|参数有效| O[创建新扫描记录]
|
||
O --> P[保存扫描记录到label_scan_history表]
|
||
P --> Q[返回成功响应]
|
||
end
|
||
```
|
||
|
||
#### 2.4.3 详细步骤
|
||
|
||
1. **自动触发扫描（标签下载时）**
|
||
- **接收标签下载请求**：客户端调用`GET /api/Label/label-replace/waybill/{waybillNumber}/download`接口
|
||
- **处理标签下载流程**：验证参数、查询标签记录、处理订单冻结情况、下载标签文件
|
||
- **确定扫描结果**：
|
||
- 如果成功找到并下载标签，设置扫描结果为`ReturnedLabel`
|
||
- 如果订单被冻结，设置扫描结果为`OrderFrozen`
|
||
- 如果未找到标签数据，设置扫描结果为`NoLabelData`
|
||
- 其他异常情况，设置扫描结果为`Other`
|
||
- **在finally块中记录扫描**：无论标签下载成功或失败，都在`finally`块中调用`LabelScanService.RecordScanAsync`方法，确保每个请求只记录一次扫描
|
||
- **保存扫描记录**：将扫描记录保存到`label_scan_history`表，包含扫描结果、客户ID、中性面单号等信息
|
||
|
||
2. **手动调用扫描接口**
|
||
- **接收扫描请求**：系统内部模块调用`LabelScanService.RecordScanAsync`方法或通过API调用`POST /api/Label/label-scan/record`接口
|
||
- **验证请求参数**：检查`NeutralWaybillNumber`是否为空且有效，验证其他可选参数的数据格式
|
||
- **创建新扫描记录**：为每次扫描创建新的历史记录，包含扫描结果、时间、操作人员等信息
|
||
- **保存扫描记录**：将扫描记录保存到`label_scan_history`表
|
||
- **返回响应**：返回扫描记录的详细信息
|
||
|
||
### 2.4.4 扫描结果类型
|
||
|
||
| 扫描结果 | 枚举值 | 描述 |
|
||
|---------|--------|------|
|
||
| ReturnedLabel | 0 | 成功返回标签 |
|
||
| NoLabelData | 1 | 未找到标签数据 |
|
||
| NoOrderData | 2 | 未找到订单数据 |
|
||
| OrderFrozen | 3 | 订单被冻结，无法下载面单 |
|
||
| Other | 4 | 其他异常情况 |
|
||
|
||
## 3. 系统交互流程
|
||
|
||
### 3.1 客户端与服务器交互流程
|
||
|
||
#### 3.1.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: 返回响应
|
||
```
|
||
|
||
#### 3.1.2 详细步骤
|
||
|
||
1. **客户端发送请求**
|
||
- 客户端根据接口文档构建请求
|
||
- 设置请求头和请求体
|
||
- 发送HTTP请求到服务器
|
||
|
||
2. **API层接收请求**
|
||
- API层接收客户端请求
|
||
- 验证请求格式和参数
|
||
- 记录请求日志
|
||
|
||
3. **调用业务逻辑**
|
||
- API层调用BLL层的相应服务
|
||
- 传递处理所需的参数
|
||
|
||
4. **数据访问**
|
||
- BLL层根据业务需求调用DAL层
|
||
- DAL层执行数据库操作
|
||
|
||
5. **返回结果**
|
||
- 数据库返回查询结果
|
||
- DAL层将结果传递给BLL层
|
||
- BLL层处理业务逻辑并返回结果
|
||
- API层构建响应并返回给客户端
|
||
|
||
## 4. 异常处理流程
|
||
|
||
### 4.1 异常处理概述
|
||
|
||
系统采用统一的异常处理机制，对各类异常进行捕获、记录和处理，确保系统的稳定性和可靠性。
|
||
|
||
### 4.2 异常处理流程
|
||
|
||
#### 4.2.1 流程图
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[发生异常] --> B[捕获异常]
|
||
B --> C[记录异常日志]
|
||
C --> D[分析异常类型]
|
||
D -->|业务异常| E[返回业务错误信息]
|
||
D -->|系统异常| F[返回系统错误信息]
|
||
D -->|权限异常| G[返回401错误]
|
||
```
|
||
|
||
#### 4.2.2 详细步骤
|
||
|
||
1. **发生异常**
|
||
- 系统在执行过程中遇到错误
|
||
- 可能是业务逻辑错误、数据访问错误或系统级错误
|
||
|
||
2. **捕获异常**
|
||
- 使用try-catch语句捕获异常
|
||
- 确保异常不会导致系统崩溃
|
||
|
||
3. **记录异常日志**
|
||
- 将异常信息记录到日志文件
|
||
- 包括异常类型、错误消息、堆栈跟踪等
|
||
- 记录异常发生的时间、位置和上下文信息
|
||
|
||
4. **分析异常类型**
|
||
- 识别异常的类型和原因
|
||
- 区分业务异常、系统异常和权限异常
|
||
|
||
5. **返回错误响应**
|
||
- 根据异常类型返回相应的HTTP状态码
|
||
- 返回详细的错误信息
|
||
- 对于业务异常，返回具体的错误原因
|
||
- 对于系统异常，返回通用的错误信息
|
||
|
||
## 5. 日志记录流程
|
||
|
||
### 5.1 日志记录概述
|
||
|
||
系统使用Serilog框架进行日志记录，记录系统运行过程中的各种事件和操作，便于问题排查和系统监控。
|
||
|
||
### 5.2 日志记录流程
|
||
|
||
#### 5.2.1 流程图
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[系统事件发生] --> B[生成日志信息]
|
||
B --> C[确定日志级别]
|
||
C --> D[格式化日志内容]
|
||
D --> E[写入日志文件]
|
||
E --> F[定期清理旧日志]
|
||
```
|
||
|
||
#### 5.2.2 详细步骤
|
||
|
||
1. **系统事件发生**
|
||
- 系统执行各类操作和处理
|
||
- 产生需要记录的事件
|
||
|
||
2. **生成日志信息**
|
||
- 收集事件相关的信息
|
||
- 包括时间、位置、事件类型等
|
||
|
||
3. **确定日志级别**
|
||
- 根据事件的严重程度确定日志级别
|
||
- 包括Debug、Info、Warning、Error、Fatal等
|
||
|
||
4. **格式化日志内容**
|
||
- 使用统一的格式格式化日志内容
|
||
- 包括时间戳、日志级别、来源、消息内容等
|
||
|
||
5. **写入日志文件**
|
||
- 将格式化后的日志写入日志文件
|
||
- 日志文件按天滚动，确保日志文件不会过大
|
||
|
||
6. **定期清理旧日志**
|
||
- 根据配置定期清理旧日志文件
|
||
- 保留指定天数的日志记录
|
||
|
||
## 6. 文档版本控制
|
||
|
||
| 版本 | 更新日期 | 更新内容 | 更新人 |
|
||
|------|----------|----------|--------|
|
||
| 1.0 | 2026-01-16 | 初始版本 | 系统流程团队 |
|
||
| 1.1 | 2026-01-19 | 1. 新增标签扫描记录流程<br>2. 详细描述了扫描记录的自动触发机制<br>3. 添加了标签扫描记录的API接口信息 | 系统流程团队 |
|
||
| 1.2 | 2026-01-23 | 1. 优化标签扫描记录流程，确保每个标签下载请求只记录一次扫描<br>2. 详细描述了在finally块中执行扫描记录的机制<br>3. 增加了扫描结果类型说明表格<br>4. 更新了流程图，区分自动触发和手动调用两种模式 | 系统流程团队 | |