# 变色龙换单系统全流程文档

## 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数据导入、物流消息解析和标签扫描记录等核心功能。系统具有良好的扩展性和可维护性，采用分层架构和模块化设计，便于后续功能扩展和系统升级。

本全流程文档整合了后端系统设计文档、后端系统流程文档和前端流程文档的内容，全面描述了系统的架构、功能模块、业务流程和技术实现，为开发人员和用户提供了完整的系统参考资料。