jennisonzhang/LabelChange-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
LabelChange-server/SystemFlowDocument.md
Im-Jenisson b2a9b7d3c2 上传源代码版本
2026-06-01 16:30:29 +08:00

8.8 KiB
Raw Permalink Blame History

标签替换服务系统流程文档

1. 流程概述

本文档描述了标签替换服务系统的核心业务流程，包括标签替换请求处理流程、Excel数据导入流程和物流消息解析流程。通过流程图和详细步骤说明，帮助开发人员和用户理解系统的工作原理。

2. 系统核心流程

2.1 标签替换请求处理流程

2.1.1 流程概述

此流程描述了系统处理标签替换请求的完整过程，从接收请求到返回结果的所有步骤。

2.1.2 流程图

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 流程图

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 流程图

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. 返回解析结果

    • 返回解析成功或失败的信息
    • 如果成功，返回解析后的结构化数据

3. 系统交互流程

3.1 客户端与服务器交互流程

3.1.1 流程图

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 流程图

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 流程图

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 初始版本 系统流程团队