物流管理开发文档

1. 文档概述

1.1 文档目的

本文档旨在详细说明CRMEB系统中物流管理模块的设计架构、核心功能、代码实现及开发规范，为系统开发人员提供完整的开发参考。

1.2 适用范围

本文档适用于CRMEB系统开发人员、维护人员及二次开发人员，用于指导物流管理模块的开发、扩展和维护工作。

1.3 术语定义

术语	解释
快递公司	提供物流配送服务的公司，如顺丰、中通、圆通等
物流模板	定义商品运费计算规则的模板，包含计费方式、区域配送规则等
电子面单	在线生成的快递单，可直接打印使用
配送员	负责配送订单的人员
物流单号	快递包裹的唯一标识，用于查询物流信息
批量发货	一次处理多个订单的发货操作

2. 核心功能模块

2.1 快递公司管理

快递公司列表：展示所有快递公司，支持搜索、分页
快递公司添加：添加新的快递公司
快递公司编辑：修改快递公司信息，包括名称、编码、状态等
快递公司删除：删除快递公司
快递公司状态管理：启用/禁用快递公司
同步平台快递公司：从物流平台同步最新的快递公司信息
物流信息查询接口：提供物流信息查询API

2.2 物流模板管理

物流模板列表：展示所有物流模板，支持搜索、分页
物流模板添加：添加新的物流模板
物流模板编辑：修改物流模板信息
物流模板删除：删除物流模板
计费方式设置：支持按件数、按重量、按体积计费
区域配送设置：设置不同地区的配送规则
包邮规则设置：设置指定地区的包邮条件
不送达区域设置：设置不配送的地区
模板排序与状态管理：调整模板排序和状态

2.3 订单配送管理

订单发货：处理订单发货，支持快递发货、自提配送
物流信息查询：查询订单的物流信息
批量发货：支持批量处理多个订单的发货
电子面单打印：在线生成和打印电子面单
配送员管理：添加、编辑、删除配送员
物流单号管理：管理订单的物流单号
订单拆分发货：将一个订单拆分成多个包裹发货
商家寄件：支持商家通过系统下单寄件

3. 代码结构与设计

3.1 架构设计

系统采用分层架构设计，严格遵循MVC设计模式：

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│    Controllers  │     │    Services     │     │     Daos        │
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                         ┌─────────────────┐
                         │    Models       │
                         └─────────────────┘
                                 │
                         ┌─────────────────┐
                         │   数据库          │
                         └─────────────────┘

3.2 核心文件结构

3.2.1 快递公司管理

控制器：crmeb/app/adminapi/controller/v1/freight/Express.php
服务层：crmeb/app/services/shipping/ExpressServices.php
数据访问层：crmeb/app/dao/shipping/ExpressDao.php
路由配置：crmeb/app/adminapi/route/freight.php

3.2.2 物流模板管理

控制器：crmeb/app/adminapi/controller/v1/setting/ShippingTemplates.php
服务层：crmeb/app/services/shipping/ShippingTemplatesServices.php
数据访问层：crmeb/app/dao/shipping/ShippingTemplatesDao.php
模型：crmeb/app/model/shipping/ShippingTemplates.php

3.2.3 订单配送管理

订单控制器：crmeb/app/adminapi/controller/v1/order/StoreOrder.php
配送员管理控制器：crmeb/app/adminapi/controller/v1/order/DeliveryService.php
配送服务层：crmeb/app/services/order/DeliveryServiceServices.php
订单配送服务：crmeb/app/services/order/StoreOrderDeliveryServices.php

4. 数据库设计

4.1 快递公司表（express）

字段名	数据类型	描述
id	int(10) unsigned	快递公司ID
name	varchar(50)	快递公司名称
code	varchar(20)	快递公司编码
logo	varchar(255)	快递公司Logo
sort	int(10)	排序
status	tinyint(1)	状态（0-禁用，1-启用）
is_show	tinyint(1)	是否显示（0-不显示，1-显示）
add_time	int(10)	添加时间

4.2 物流模板表（shipping_templates）

字段名	数据类型	描述
id	int(10) unsigned	模板ID
name	varchar(50)	模板名称
type	tinyint(1)	计费方式（0-按件数，1-按重量，2-按体积）
sregion	text	配送区域（JSON格式）
srules	text	配送规则（JSON格式）
sort	int(10)	排序
status	tinyint(1)	状态（0-禁用，1-启用）
add_time	int(10)	添加时间

4.3 物流模板区域表（shipping_templates_region）

字段名	数据类型	描述
id	int(10) unsigned	区域ID
temp_id	int(10)	模板ID
region	text	区域（JSON格式）
first	decimal(10,2)	首件/首重/首体积
first_price	decimal(10,2)	首件/首重/首体积价格
continue	decimal(10,2)	续件/续重/续体积
continue_price	decimal(10,2)	续件/续重/续体积价格
add_time	int(10)	添加时间

4.4 订单表（store_order）

字段名	数据类型	描述
id	int(10) unsigned	订单ID
express_code	varchar(20)	快递公司编码
express_no	varchar(50)	物流单号
shipping_type	tinyint(1)	配送方式（0-快递，1-自提）
delivery_type	tinyint(1)	发货方式（0-未发货，1-已发货，2-已完成）
delivery_time	int(10)	发货时间
// 其他订单字段	// 数据类型	// 描述

4.5 配送员表（delivery_service）

字段名	数据类型	描述
id	int(10) unsigned	配送员ID
name	varchar(20)	配送员姓名
phone	varchar(20)	配送员手机号
avatar	varchar(255)	配送员头像
status	tinyint(1)	状态（0-禁用，1-启用）
add_time	int(10)	添加时间

5. API接口说明

5.1 快递公司管理

5.1.1 获取快递公司列表

请求URL：/adminapi/v1/freight/express/list
请求方法：GET
权限要求：freight/express/list
请求参数：
- page：页码
- limit：每页数量
- keyword：搜索关键词
- status：状态
返回结果：快递公司列表数据

5.1.2 添加快递公司

请求URL：/adminapi/v1/freight/express/create
请求方法：POST
权限要求：freight/express/create
请求参数：
- name：快递公司名称
- code：快递公司编码
- logo：快递公司Logo
- sort：排序
返回结果：操作结果

5.1.3 同步平台快递公司

请求URL：/adminapi/v1/freight/express/sync
请求方法：POST
权限要求：freight/express/sync
返回结果：操作结果

5.2 物流模板管理

5.2.1 获取物流模板列表

请求URL：/adminapi/v1/setting/shipping/template/list
请求方法：GET
权限要求：setting/shipping/template/list
请求参数：
- page：页码
- limit：每页数量
- keyword：搜索关键词
返回结果：物流模板列表数据

5.2.2 添加物流模板

请求URL：/adminapi/v1/setting/shipping/template/create
请求方法：POST
权限要求：setting/shipping/template/create
请求参数：
- name：模板名称
- type：计费方式
- sregion：配送区域
- srules：配送规则
返回结果：操作结果

5.3 订单配送管理

5.3.1 订单发货

请求URL：/adminapi/v1/order/delivery/{id}
请求方法：PUT
权限要求：order/delivery
请求参数：
- delivery_type：发货类型（0-快递发货，1-电子面单，2-商家寄件）
- express_code：快递公司编码
- express_no：物流单号
- delivery_name：发货人姓名
- delivery_phone：发货人手机号
返回结果：操作结果

5.3.2 批量发货

请求URL：/adminapi/v1/order/delivery/batch
请求方法：POST
权限要求：order/delivery/batch
请求参数：
- orders：订单ID数组
- delivery_type：发货类型
- express_code：快递公司编码
- express_no：物流单号
返回结果：操作结果

5.3.3 查询物流信息

请求URL：/adminapi/v1/order/express/{id}
请求方法：GET
权限要求：order/express
返回结果：物流信息数据

5.3.4 获取配送员列表

请求URL：/adminapi/v1/order/delivery/service/list
请求方法：GET
权限要求：order/delivery/service/list
请求参数：
- page：页码
- limit：每页数量
- keyword：搜索关键词
返回结果：配送员列表数据

5. 开发规范与流程

5.1 代码规范

命名规范：
- 类名采用大驼峰命名法，如 ExpressServices
- 方法名采用小驼峰命名法，如 getExpressList
- 变量名采用小驼峰命名法，如 shippingTemplate
- 常量名采用全大写，下划线分隔，如 SHIPPING_TYPE_EXPRESS
代码结构：
- 严格遵循分层架构，禁止跨层调用
- 每个方法职责单一，代码行数控制在50行以内
- 适当添加注释，说明方法功能、参数含义和返回值
- 所有物流操作必须记录日志，便于追溯
性能优化：
- 物流查询结果必须缓存，减少API调用次数
- 批量操作必须使用事务，确保数据一致性
- 大数据量操作必须使用队列，避免阻塞主流程

5.2 开发流程

需求分析：明确物流管理的功能需求和业务逻辑
设计阶段：设计数据结构、API接口和业务流程
编码实现：
- 实现物流服务层逻辑
- 实现物流控制器接口
- 实现物流模板和计费规则
单元测试：编写单元测试，确保功能正确性
集成测试：进行模块集成测试，测试物流与订单等模块的交互
性能测试：对物流查询、批量发货等操作进行性能测试
代码审查：提交代码审查，确保代码质量
部署上线：部署到生产环境

6. 常见问题与解决方案

6.1 物流信息查询失败

问题：调用物流查询API失败 解决方案：

检查快递公司编码是否正确
检查物流单号是否正确
检查物流平台API密钥是否有效
实现重试机制，处理网络异常
添加日志记录，便于排查问题

6.2 批量发货超时

问题：批量处理大量订单发货时超时 解决方案：

使用队列异步处理批量发货
优化数据库操作，减少查询次数
实现分批处理，减少单次处理数量
增加服务器资源，提高并发处理能力

6.3 物流模板计算错误

问题：根据物流模板计算的运费与预期不符 解决方案：

检查物流模板配置是否正确
检查区域划分是否合理
检查计费规则是否正确
添加运费计算日志，便于排查问题

6.4 电子面单打印失败

问题：电子面单生成或打印失败 解决方案：

检查电子面单配置是否正确
检查打印机连接是否正常
检查模板格式是否正确
实现重试机制，处理打印异常

7. 扩展与定制

7.1 添加新的物流公司

数据库操作：在express表中添加新的物流公司信息
代码修改：
- 更新快递公司列表
- 实现该物流公司的物流查询接口
前端修改：在前端添加新的物流公司选项

7.2 扩展物流模板计费方式

数据库修改：在shipping_templates表中添加新的计费方式
代码修改：
- 更新物流模板配置功能
- 实现新的计费方式计算逻辑
前端修改：在前端添加新的计费方式选项

7.3 集成第三方物流平台

设计集成方案：确定与第三方物流平台的集成方式
实现API对接：实现与第三方物流平台的API对接
更新物流查询逻辑：使用第三方物流平台的查询接口
前端修改：在前端添加第三方物流平台的相关功能

8. 文档更新记录

版本	更新日期	更新内容	更新人
1.0	2026-01-19	初始版本，包含快递公司管理、物流模板管理、订单配送管理等核心功能	AI Assistant

9. 附录

9.1 核心类关系图

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│    Controllers  │     │    Services     │     │     Daos        │
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                         ┌─────────────────┐
                         │    Models       │
                         └─────────────────┘
                                 │
                         ┌─────────────────┐
                         │   数据库          │
                         └─────────────────┘

9.2 订单发货流程图

订单发货流程：
1. 管理员进入订单详情页
2. 点击"发货"按钮
3. 选择发货方式（快递发货、电子面单、商家寄件）
4. 填写物流信息（快递公司、物流单号等）
5. 提交发货请求
6. 系统更新订单状态为已发货
7. 系统记录物流信息
8. 触发物流通知事件
9. 发送物流通知给用户

9.3 物流查询流程图

物流查询流程：
1. 用户或管理员请求查询物流信息
2. 系统验证请求合法性
3. 检查缓存中是否有物流信息
4. 缓存命中，返回缓存数据
5. 缓存未命中，调用物流查询API
6. 解析API返回结果
7. 缓存物流信息
8. 返回物流信息给请求方

9.4 物流模板计费方式

计费方式	描述
按件数	按照商品件数计算运费
按重量	按照商品重量计算运费
按体积	按照商品体积计算运费

9.5 订单配送状态

状态值	描述
0	未发货
1	已发货
2	已完成

9.6 配送方式

方式值	描述
0	快递配送
1	门店自提

提示：该文档由AI生成，仅供参考。

物流管理开发文档.md 16 KB History Raw