order-service-architecture
约 4037 字大约 13 分钟
2026-02-03
1. 概述
OrderService 是 ShopXO 电商系统的核心订单业务服务层，负责订单全生命周期管理，包括订单创建、支付、发货、收货、取消等业务流程。
文件位置: app/service/OrderService.php
设计原则:
- 所有业务逻辑在 Service 层实现
- Controller 仅负责请求处理和响应
- 返回统一格式：
['code' => 0, 'msg' => 'success', 'data' => []]
2. 订单状态机设计
2.1 订单状态定义
┌─────────────────────────────────────────────────────────────────────────────┐
│ 订单状态流转图 │
└─────────────────────────────────────────────────────────────────────────────┘
┌──────────┐
│ 创建 │
│ (status= │
│ 0) │
└────┬─────┘
│ 确认订单
▼
┌──────────┐ 支付 ┌──────────┐
│待确认/ │──────────────►│ 待发货/ │
│待付款 │ │ 已支付 │
│ (status= │ │ (status= │
│ 1) │◄─────────────│ 2) │
└──────────┘ 取消订单 └──────────┘
▲ │ 发货
│ ▼
取消订单 ┌──────────┐ 收货 ┌──────────┐
│ 待收货/ │──────────────►│ 已完成 │
│ 已发货 │ │ (status= │
│ (status= │───────────────│ 4) │
│ 3) │ 售后申请 └──────────┘
└──────────┘ ▲ │
│ │ │
▼ │ │
┌──────────┐ 售后处理 │ │
│ 已取消 │◄─────────────────┘ │
│ (status= │ │
│ 5) │──────────────────────┘
└──────────┘ 超时未收货
┌──────────┐
│ 已关闭 │
│ (status= │
│ 6) │
└──────────┘2.2 状态详细说明
| 状态码 | 状态名称 | 说明 | 可执行操作 |
|---|---|---|---|
| 0 | 待确认 | 订单刚创建，等待商家确认 | 管理员确认、取消 |
| 1 | 待付款 | 订单已确认，等待用户支付 | 用户支付、取消 |
| 2 | 待发货 | 订单已支付，等待商家发货 | 管理员发货、取消（未支付时） |
| 3 | 待收货 | 订单已发货，等待用户确认收货 | 用户收货、管理员强制收货 |
| 4 | 已完成 | 订单已完成 | 用户评价、删除 |
| 5 | 已取消 | 订单已取消 | 删除 |
| 6 | 已关闭 | 订单已关闭（系统操作） | 删除 |
2.3 支付状态
| 支付状态码 | 名称 | 说明 |
|---|---|---|
| 0 | 未支付 | 订单未支付 |
| 1 | 已支付 | 订单已全额支付 |
| 2 | 已退款 | 订单已全额退款 |
| 3 | 部分退款 | 订单部分退款 |
2.4 订单模式
| 模式码 | 名称 | 发货方式 |
|---|---|---|
| 0 | 销售型 | 快递发货 |
| 1 | 展示型 | 同城配送 |
| 2 | 自提点 | 到店自提（验证取货码） |
| 3 | 虚拟销售 | 虚拟商品自动发货 |
3. 订单操作权限控制
3.1 操作权限矩阵
OrderOperateData($order, $user_type)| 操作 | 管理员 (admin) | 用户 (user) |
|---|---|---|
| is_confirm (确认) | status=0 | - |
| is_pay (支付) | pay_status=0 且 status∉ | status=1 |
| is_delivery (发货) | order_model=0 且 status∈ | - |
| is_service (同城) | order_model=1 且 status∈ | - |
| is_take (取货) | order_model∈{2,3} 且 status=2 | - |
| is_collect (收货) | status=3 | status=3 |
| is_cancel (取消) | status∈{0,1} 或 (status∈{2,3,4} 且 pay_status=0) | status∈{0,1} 或 (status=2 且 pay_status=0) |
| is_delete (删除) | status∈{5,6} 且 is_delete_time=0 | status∈{4,5,6} 且 user_is_delete_time=0 |
| is_comments (评价) | - | status=4 且 user_is_comments=0 |
3.2 权限检查流程
┌─────────────────────────────────────────────────────────┐
│ 订单操作权限检查 │
└─────────────────────────────────────────────────────────┘
用户请求
│
├─► 获取订单信息
│ └─► 验证订单存在
│ └─► 验证用户身份
│
├─► OrderOperateData($order, $user_type)
│ │
│ ├─► 根据 user_type 选择权限矩阵
│ │ ├─► admin: 管理员权限
│ │ └─► user: 用户权限
│ │
│ └─► 根据 status/pay_status/order_model 判断可操作性
│ └─► 返回操作权限数组
│
└─► 权限验证
├─► 有权限 → 执行操作
└─► 无权限 → 返回错误提示4. 订单支付流程
4.1 支付流程架构
┌─────────────────────────────────────────────────────────────────────────────┐
│ 订单支付流程 │
└─────────────────────────────────────────────────────────────────────────────┘
用户发起支付
│
├─► Pay($params)
│ │
│ ├─► 1. 参数校验
│ │ └─► 订单ID验证
│ │
│ ├─► 2. 订单信息加载
│ │ ├─► 获取订单基本信息
│ │ ├─► 获取订单用户信息
│ │ ├─► 获取订单地址信息
│ │ └─► 获取订单详情
│ │
│ ├─► 3. 支付前校验
│ │ ├─► 订单状态校验（是否可支付）
│ │ ├─► 商品状态校验（是否下架/删除）
│ │ └─► 库存校验
│ │
│ ├─► 4. 零金额订单处理
│ │ └─► OrderDirectSuccess() 直接支付成功
│ │
│ ├─► 5. 支付方式处理
│ │ ├─► 获取支付方式配置
│ │ ├─► 生成支付日志
│ │ └─► 更新订单支付方式
│ │
│ ├─► 6. 钩子触发
│ │ ├─► plugins_service_order_pay_launch_begin
│ │ └─► plugins_service_order_pay_launch_handle
│ │
│ ├─► 7. 发起支付
│ │ ├─► 线上支付 → 调用第三方支付接口
│ │ ├─► 线下支付 → UserOrderPayUnderLine()
│ │ └─► 钱包支付 → WalletPay
│ │
│ └─► 8. 返回支付数据
│
├─► 支付回调处理
│ │
│ ├─► 同步回调 (respond)
│ │ └─► 用户支付完成后的页面跳转
│ │
│ └─► 异步回调 (notify)
│ └─► PayNotify()
│ ├─► 验证签名
│ ├─► 更新订单状态
│ ├─► 库存处理
│ ├─► 销量更新
│ └─► 触发钩子 plugins_service_order_pay_success_handle_end
│
└─► 支付完成4.2 支付方式类型
| 支付类型 | 说明 | 回调方式 |
|---|---|---|
| 线上支付 | 微信、支付宝等第三方支付 | 异步回调 + 同步跳转 |
| 线下支付 | 银行转账、货到付款 | 管理员后台确认 |
| 钱包支付 | 会员钱包余额支付 | 即时扣款 |
4.3 支付日志
支付日志表 sxo_pay_log 记录每次支付请求：
支付日志结构:
┌─────────────┬──────────────┬─────────────┬─────────────┐
│ 字段 │ 类型 │ 说明 │ 示例 │
├─────────────┼──────────────┼─────────────┼─────────────┤
│ id │ int │ 自增ID │ 1 │
│ log_no │ char(60) │ 支付日志号 │ PL202301... │
│ user_id │ int │ 用户ID │ 1001 │
│ business_ids│ text │ 业务订单IDs │ "1,2,3" │
│ business_nos│ text │ 业务订单号 │ "ON001,..." │
│ total_price │ decimal(10,2)│ 支付金额 │ 99.99 │
│ payment │ char(60) │ 支付方式 │ WechatPay │
│ status │ tinyint │ 支付状态 │ 0=待支付,1=已支付│
└─────────────┴──────────────┴─────────────┴─────────────┘5. 订单发货流程
5.1 发货流程架构
┌─────────────────────────────────────────────────────────────────────────────┐
│ 订单发货流程 │
└─────────────────────────────────────────────────────────────────────────────┘
管理员发货
│
├─► OrderDelivery($params)
│ │
│ ├─► 1. 参数校验
│ │ └─► 订单ID、用户ID验证
│ │
│ ├─► 2. 权限检查
│ │ └─► OrderOperateData() 验证 is_delivery/is_take/is_service
│ │
│ └─► OrderDeliveryHandle($params)
│ │
│ ├─► 3. 订单模式判断
│ │ │
│ │ ├─► 销售型 (order_model=0)
│ │ │ ├─► 快递公司校验
│ │ │ ├─► 快递单号校验
│ │ │ └─► 支持单/多快递发货
│ │ │
│ │ ├─► 同城配送 (order_model=1)
│ │ │ ├─► 配送员信息校验
│ │ │ └─► 配送时间段校验
│ │ │
│ │ └─► 自提点 (order_model=2)
│ │ ├─► 取货码验证
│ │ └─► 取货码匹配检查
│ │
│ └─► OrderDeliveryUpdateHandle($order, $params)
│ │
│ ├─► 4. 发货信息保存
│ │ ├─► 快递发货 → 保存到 sxo_order_express
│ │ ├─► 同城配送 → 保存到 sxo_order_service
│ │ └─► 自提点 → 验证取货码后更新状态
│ │
│ ├─► 5. 订单状态更新
│ │ ├─► status: 2 → 3 (待发货 → 待收货)
│ │ ├─► delivery_time: 设置发货时间
│ │ └─► upd_time: 更新时间
│ │
│ ├─► 6. 库存扣除
│ │ └─► BuyService::OrderInventoryDeduct(opt_type='delivery')
│ │
│ ├─► 7. 用户消息通知
│ │ └─► MessageService::MessageAdd()
│ │
│ ├─► 8. 订单历史记录
│ │ └─► OrderHistoryAdd()
│ │
│ └─► 9. 微信发货同步
│ └─► OrderDeliverySyncWeixin()
│
└─► 发货完成5.2 发货数据表
快递发货表 sxo_order_express:
┌─────────────┬──────────────┬─────────────────────────┐
│ 字段 │ 类型 │ 说明 │
├─────────────┼──────────────┼─────────────────────────┤
│ id │ int │ 自增ID │
│ order_id │ int │ 订单ID │
│ user_id │ int │ 用户ID │
│ express_id │ int │ 快递公司ID │
│ express_number│ char(60) │ 快递单号 │
│ note │ text │ 备注 │
└─────────────┴──────────────┴─────────────────────────┘同城配送表 sxo_order_service:
┌──────────────────┬──────────────┬─────────────────────────┐
│ 字段 │ 类型 │ 说明 │
├──────────────────┼──────────────┼─────────────────────────┤
│ id │ int │ 自增ID │
│ order_id │ int │ 订单ID │
│ user_id │ int │ 用户ID │
│ service_name │ char(60) │ 配送员姓名 │
│ service_mobile │ char(15) │ 配送员电话 │
│ service_start_time│ int │ 配送开始时间 │
│ service_end_time │ int │ 配送结束时间 │
│ service_duration_minute│ int │ 配送持续时长(分钟) │
│ note │ text │ 备注 │
└──────────────────┴──────────────┴─────────────────────────┘自提取货码表 sxo_order_extraction_code:
┌─────────────┬──────────────┬─────────────────────────┐
│ 字段 │ 类型 │ 说明 │
├─────────────┼──────────────┼─────────────────────────┤
│ id │ int │ 自增ID │
│ order_id │ int │ 订单ID │
│ code │ char(60) │ 取货码（6位数字） │
└─────────────┴──────────────┴─────────────────────────┘6. 订单收货流程
6.1 收货流程架构
┌─────────────────────────────────────────────────────────────────────────────┐
│ 订单收货流程 │
└─────────────────────────────────────────────────────────────────────────────┘
用户/管理员收货
│
├─► OrderCollect($params)
│ │
│ ├─► 1. 参数校验
│ │ └─► 订单ID、用户ID验证
│ │
│ ├─► 2. 权限检查
│ │ └─► OrderOperateData() 验证 is_collect
│ │
│ └─► OrderCollectHandle($order, $params)
│ │
│ ├─► 3. 订单状态更新
│ │ ├─► status: 3 → 4 (待收货 → 已完成)
│ │ ├─► collect_time: 设置收货时间
│ │ └─► upd_time: 更新时间
│ │
│ ├─► 4. 积分赠送
│ │ └─► IntegralService::OrderGoodsIntegralGiving()
│ │ └─► 根据配置规则赠送用户积分
│ │
│ ├─► 5. 销量更新
│ │ └─► GoodsSalesCountInc(opt_type='collect')
│ │ └─► 增加商品销量
│ │
│ ├─► 6. 微信同步
│ │ └─► OrderDeliverySyncWeixin()
│ │ └─► 同步收货状态到微信
│ │
│ ├─► 7. 用户消息通知
│ │ └─► MessageService::MessageAdd()
│ │
│ └─► 8. 订单历史记录
│ └─► OrderHistoryAdd()
│
└─► 收货完成7. 订单取消流程
7.1 取消流程架构
┌─────────────────────────────────────────────────────────────────────────────┐
│ 订单取消流程 │
└─────────────────────────────────────────────────────────────────────────────┘
用户/管理员取消
│
├─► OrderCancel($params)
│ │
│ ├─► 1. 参数校验
│ │ └─► 订单ID、用户ID验证
│ │
│ ├─► 2. 权限检查
│ │ └─► OrderOperateData() 验证 is_cancel
│ │
│ ├─► 3. 事务处理
│ │ │
│ │ ├─► 4. 订单状态更新
│ │ │ ├─► status: → 5 (已取消)
│ │ │ ├─► cancel_time: 设置取消时间
│ │ │ └─► upd_time: 更新时间
│ │ │
│ │ ├─► 5. 库存回滚
│ │ │ └─► BuyService::OrderInventoryRollback()
│ │ │ └─► 恢复商品库存
│ │ │
│ │ ├─► 6. 用户消息通知
│ │ │ └─► MessageService::MessageAdd()
│ │ │
│ │ └─► 7. 订单历史记录
│ │ └─► OrderHistoryAdd()
│ │
│ ├─► 提交事务
│ │
│ └─► 返回取消结果
│
└─► 取消完成8. 订单确认流程
8.1 确认流程架构
┌─────────────────────────────────────────────────────────────────────────────┐
│ 订单确认流程 │
└─────────────────────────────────────────────────────────────────────────────┘
管理员确认
│
├─► OrderConfirm($params)
│ │
│ ├─► 1. 参数校验
│ │ └─► 订单ID、用户ID验证
│ │
│ ├─► 2. 权限检查
│ │ └─► OrderOperateData() 验证 is_confirm
│ │
│ ├─► 3. 事务处理
│ │ │
│ │ ├─► 4. 订单状态更新
│ │ │ ├─► status: 0 → 1 (待确认 → 待付款)
│ │ │ ├─► confirm_time: 设置确认时间
│ │ │ └─► upd_time: 更新时间
│ │ │
│ │ ├─► 5. 库存扣除
│ │ │ └─► BuyService::OrderInventoryDeduct(opt_type='confirm')
│ │ │
│ │ ├─► 6. 用户消息通知
│ │ │ └─► MessageService::MessageAdd()
│ │ │
│ │ └─► 7. 订单历史记录
│ │ └─► OrderHistoryAdd()
│ │
│ ├─► 提交事务
│ │
│ └─► 返回确认结果
│
└─► 确认完成9. 订单状态历史记录
9.1 历史记录结构
OrderHistoryAdd($order_id, $new_status, $original_status, $msg, $creator, $creator_name)状态历史表 sxo_order_status_history:
┌─────────────────┬──────────────┬─────────────────────────┐
│ 字段 │ 类型 │ 说明 │
├─────────────────┼──────────────┼─────────────────────────┤
│ id │ int │ 自增ID │
│ order_id │ int │ 订单ID │
│ new_status │ tinyint │ 新状态 │
│ original_status │ tinyint │ 原状态 │
│ msg │ text │ 状态变更描述 │
│ creator │ int │ 操作人ID │
│ creator_name │ char(60) │ 操作人姓名 │
│ add_time │ int │ 记录时间 │
└─────────────────┴──────────────┴─────────────────────────┘9.2 状态变更记录时机
| 业务操作 | 原状态 | 新状态 | 记录时机 |
|---|---|---|---|
| 支付成功 | 1 | 2 | 支付回调完成 |
| 确认订单 | 0 | 1 | 管理员确认 |
| 发货 | 2 | 3 | 发货处理完成 |
| 收货 | 3 | 4 | 收货处理完成 |
| 取消 | 0/1/2/3 | 5 | 取消处理完成 |
| 关闭 | 任意 | 6 | 系统自动关闭 |
10. 订单数据关联结构
10.1 核心数据表关系
┌─────────────────────────────────────────────────────────────────────────────┐
│ 订单核心数据表关系图 │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────┐
│ sxo_user │
│ (用户表) │
│ ─────────── │
│ id │
│ username │
│ nickname │
│ mobile │
└─────────┬───────────┘
│ 1
│
│ n
┌───────────────▼──────────────┐
│ sxo_order │
│ (订单主表) │
│ ──────────────────────── │
│ id (PK) │
│ order_no (UK) │
│ user_id (FK) │
│ warehouse_id (FK) │
│ payment_id (FK) │
│ status (订单状态) │
│ pay_status (支付状态) │
│ order_model (订单模式) │
│ total_price │
│ pay_price │
│ ... │
└───────┬─────────────┬────────┘
│ │
│ 1 │ 1
│ │
┌───────▼──────┐ ┌───▼────────────────┐
│sxo_order_detail│ │ sxo_payment │
│ (订单详情) │ │ (支付方式表) │
│ ─────────── │ │ ──────────── │
│ id (PK) │ │ id │
│ order_id(FK) │ │ payment │
│ goods_id(FK) │ │ name │
│ title │ │ config │
│ price │ └───────────────────┘
│ quantity │
└───────┬───────┘
│ 1
│
│ n
┌───────▼──────────────────┐
│ sxo_goods │
│ (商品表) │
│ ──────────────── │
│ id │
│ title │
│ images │
│ price │
│ inventory │
└────────────────────────┘
┌──────────────────────────────────────────────────────────┐
│ 订单关联表 │
├──────────────────────────────────────────────────────────┤
│ sxo_order_address (订单地址) │
│ sxo_order_express (快递发货) │
│ sxo_order_service (同城配送) │
│ sxo_order_extraction_code(自提取货码) │
│ sxo_order_fictitious_value(虚拟商品值) │
│ sxo_order_aftersale (售后记录) │
│ sxo_order_status_history (状态历史) │
│ sxo_pay_log (支付日志) │
└──────────────────────────────────────────────────────────┘10.2 订单详情关联
订单详情 (sxo_order_detail)
│
├─► 商品信息 (sxo_goods)
│ ├─► 基本信息：标题、图片、价格
│ ├─► 规格信息：spec (JSON)
│ └─► 库存信息：inventory
│
├─► 虚拟商品 (sxo_order_fictitious_value)
│ └─► 虚拟商品取货码
│
└─► 售后记录 (sxo_order_aftersale)
├─► 退款记录
├─► 退货记录
└─► 换货记录10.3 数据流转关系
┌─────────────────────────────────────────────────────────────────────────────┐
│ 订单数据流转关系 │
└─────────────────────────────────────────────────────────────────────────────┘
订单创建时:
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ sxo_goods │───►│ sxo_order │───►│ sxo_order_ │
│ (库存减少) │ │ (主订单) │ │ detail │
└──────────────┘ └──────────────┘ └──────────────┘
│
├─► sxo_order_address
├─► sxo_pay_log
└─► sxo_order_status_history
订单支付时:
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ 第三方支付 │───►│ sxo_pay_log │───►│ sxo_order │
│ (回调通知) │ │ (更新状态) │ │ (更新支付状态)│
└──────────────┘ └──────────────┘ └──────────────┘
│
├─► sxo_order_status_history
└─► sxo_goods (销量增加)
订单发货时:
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ 管理员操作 │───►│ sxo_order │───►│ sxo_order_ │
│ (发货) │ │ (更新状态) │ │ express/ │
│ │ │ │ │ service │
└──────────────┘ └──────────────┘ └──────────────┘
│
└─► sxo_order_status_history
订单完成时:
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ 用户收货 │───►│ sxo_order │───►│ sxo_user_ │
│ │ │ (更新状态) │ │ integral_log │
└──────────────┘ └──────────────┘ │ (积分赠送) │
│ └──────────────┘
└─► sxo_goods (销量增加)11. 扩展机制
11.1 钩子列表
| 钩子名称 | 触发时机 | 用途 |
|---|---|---|
plugins_service_order_pay_launch_begin | 发起支付前 | 支付前验证、数据准备 |
plugins_service_order_pay_launch_handle | 发起支付处理 | 支付参数处理、第三方对接 |
plugins_service_order_pay_success_handle_end | 支付成功后 | 支付后业务处理 |
plugins_service_order_detail_data | 订单详情加载 | 详情数据扩展 |
plugins_service_order_extraction_data | 自提信息加载 | 自提数据扩展 |
11.2 插件扩展点
┌─────────────────────────────────────────────────────────────────────────────┐
│ 插件扩展点 │
└─────────────────────────────────────────────────────────────────────────────┘
支付流程扩展:
┌──────────────────────────────────────────────────────────────┐
│ Pay() 触发钩子 │
│ ├─► plugins_service_order_pay_launch_begin │
│ │ ├─► 自定义支付前校验 │
│ │ └─► 修改支付参数 │
│ │ │
│ ├─► plugins_service_order_pay_launch_handle │
│ │ ├─► 接入新的支付方式 │
│ │ └─► 自定义支付逻辑 │
│ │ │
│ └─► PayNotify() 触发钩子 │
│ └─► plugins_service_order_pay_success_handle_end │
│ ├─► 支付成功后业务处理 │
│ └─► 数据同步 │
└──────────────────────────────────────────────────────────────┘
数据扩展:
┌──────────────────────────────────────────────────────────────┐
│ OrderItemList() 触发钩子 │
│ └─► plugins_service_order_detail_data │
│ ├─► 订单详情数据扩展 │
│ └─► 添加自定义字段 │
│ │
│ OrderExtractionData() 触发钩子 │
│ └─► plugins_service_order_extraction_data │
│ ├─► 自提信息扩展 │
│ └─► 自定义取货码格式 │
└──────────────────────────────────────────────────────────────┘12. 库存与销量处理
12.1 库存扣除时机
┌─────────────────────────────────────────────────────────────────────────────┐
│ 库存扣除规则 │
└─────────────────────────────────────────────────────────────────────────────┘
配置选项 (common_deduction_inventory_rules_list):
┌─────────┬─────────────────┬──────────────────────────────────────────┐
│ 规则 │ 说明 │ 扣除时机 │
├─────────┼─────────────────┼──────────────────────────────────────────┤
│ 0 │ 订单确认成功 │ OrderConfirm() → status: 0→1 │
│ 1 │ 订单支付成功 │ PayNotify() → pay_status: 0→1 │
│ 2 │ 订单发货 │ OrderDelivery() → status: 2→3 │
└─────────┴─────────────────┴──────────────────────────────────────────┘
库存回滚:
┌──────────────────────────────────────────────────────────────────────┐
│ OrderCancel() → BuyService::OrderInventoryRollback() │
│ ├─► 恢复商品库存 │
│ └─► 清理对应的锁定库存 │
└──────────────────────────────────────────────────────────────────────┘12.2 销量增加时机
┌─────────────────────────────────────────────────────────────────────────────┐
│ 销量增加规则 │
└─────────────────────────────────────────────────────────────────────────────┘
配置选项 (common_sales_count_inc_rules_list):
┌─────────┬─────────────────┬──────────────────────────────────────────┐
│ 规则 │ 说明 │ 增加时机 │
├─────────┼─────────────────┼──────────────────────────────────────────┤
│ 0 │ 订单支付 │ PayNotify() → pay_status: 0→1 │
│ 1 │ 订单收货 │ OrderCollect() → status: 3→4 │
└─────────┴─────────────────┴──────────────────────────────────────────┘
销量计算:
┌──────────────────────────────────────────────────────────────────────┐
│ GoodsSalesCountInc($order_id, $opt_type) │
│ └─► 累加商品 sales_count 字段 │
│ └─► 累加数量 = sum(订单详情中各商品数量) │
└──────────────────────────────────────────────────────────────────────┘13. 异常处理机制
13.1 事务处理
┌─────────────────────────────────────────────────────────────────────────────┐
│ 事务处理模式 │
└─────────────────────────────────────────────────────────────────────────────┘
模式一: 内部事务控制
┌──────────────────────────────────────────────────────────────┐
│ OrderCancel() │
│ ├─► Db::startTrans() │
│ ├─► 更新订单状态 │
│ ├─► 库存回滚 │
│ ├─► 消息通知 │
│ ├─► 历史记录 │
│ ├─► Db::commit() / Db::rollback() │
│ └─► 返回结果 │
└──────────────────────────────────────────────────────────────┘
模式二: 外部事务控制
┌──────────────────────────────────────────────────────────────┐
│ OrderDelivery() │
│ ├─► Db::startTrans() │
│ ├─► OrderDeliveryHandle() │
│ │ ├─► 发货信息保存 │
│ │ ├─► 订单状态更新 │
│ │ ├─► 库存扣除 │
│ │ └─► 抛出异常则回滚 │
│ └─► 根据结果 commit/rollback │
└──────────────────────────────────────────────────────────────┘13.2 异常捕获
┌─────────────────────────────────────────────────────────────────────────────┐
│ 异常处理策略 │
└─────────────────────────────────────────────────────────────────────────────┘
参数校验异常:
┌──────────────────────────────────────────────────────────────┐
│ ParamsChecked($params, $rules) │
│ ├─► 返回错误描述 │
│ └─► 立即返回 DataReturn($msg, -1) │
└──────────────────────────────────────────────────────────────┘
业务逻辑异常:
┌──────────────────────────────────────────────────────────────┐
│ try { │
│ // 业务处理 │
│ if($error) throw new \Exception($msg); │
│ Db::commit(); │
│ } catch(\Exception $e) { │
│ Db::rollback(); │
│ return DataReturn($e->getMessage(), -1); │
│ } │
└──────────────────────────────────────────────────────────────┘14. 业务依赖关系
14.1 依赖的服务层
┌─────────────────────────────────────────────────────────────────────────────┐
│ OrderService 依赖关系 │
└─────────────────────────────────────────────────────────────────────────────┘
┌────────────────────────────────────────────────────────────────────┐
│ 核心依赖 │
├────────────────────────────────────────────────────────────────────┤
│ PaymentService - 支付方式管理 │
│ BuyService - 购买流程、库存处理 │
│ IntegralService - 积分管理 │
│ RegionService - 地区数据处理 │
│ ExpressService - 快递公司管理 │
│ ResourcesService - 资源处理 │
│ PayLogService - 支付日志管理 │
│ UserService - 用户信息处理 │
│ GoodsService - 商品数据处理 │
│ OrderAftersaleService - 售后服务 │
│ MessageService - 消息通知 │
└────────────────────────────────────────────────────────────────────┘14.2 被依赖的模块
┌─────────────────────────────────────────────────────────────────────────────┐
│ 依赖 OrderService 的模块 │
└─────────────────────────────────────────────────────────────────────────────┘
前台:
├─► index/Order.php - 用户订单管理
├─► index/Buy.php - 购买流程
└─► index/User.php - 用户中心
后台:
├─► admin/Order.php - 订单管理
└─► admin/Orderrefund.php - 退款管理
API:
└─► api/Order.php - API订单接口
插件:
├─► distribution - 分销插件
├─► orderexportprint - 订单导出打印
└─► membershiplevelvip - 会员等级15. 关键业务规则
15.1 支付规则
| 规则 | 说明 |
|---|---|
| 零金额订单 | total_price ≤ 0 时直接支付成功，无需调用支付接口 |
| 多订单合并支付 | 支持多个订单同时支付，生成统一支付日志 |
| 支付方式锁定 | 发起支付时更新订单 payment_id，锁定支付方式 |
| 线下支付 | 线下支付订单状态特殊处理，等待管理员确认 |
15.2 发货规则
| 规则 | 说明 |
|---|---|
| 单/多快递 | 支持一个订单发货多个快递包裹 |
| 发货限制 | 仅待发货(2)、待收货(3)状态可发货/修改发货信息 |
| 取货码验证 | 自提订单发货必须验证6位数字取货码 |
| 库存扣除 | 发货时根据配置规则扣除库存（默认发货扣除） |
15.3 取消规则
| 规则 | 说明 |
|---|---|
| 用户取消 | 仅待确认(0)、待付款(1)、待发货(2)且未支付时可取消 |
| 管理员取消 | 可取消更多状态，包括未支付的已发货订单 |
| 库存回滚 | 取消订单自动回滚库存 |
| 退款处理 | 已支付订单取消需走退款流程 |
15.4 收货规则
| 规则 | 说明 |
|---|---|
| 收货条件 | 仅待收货(3)状态可确认收货 |
| 积分赠送 | 收货后根据商品配置赠送积分 |
| 销量增加 | 收货后根据配置增加商品销量 |
| 自动完成 | 超期未收货系统自动完成（需配置定时任务） |
16. 数据一致性保障
16.1 事务保障
┌─────────────────────────────────────────────────────────────────────────────┐
│ 数据一致性策略 │
└─────────────────────────────────────────────────────────────────────────────┘
关键操作事务保护:
┌──────────────────────────────────────────────────────────────┐
│ ● 订单支付 (PayNotify) │
│ ├─► 订单状态更新 │
│ ├─► 库存扣除 │
│ ├─► 销量增加 │
│ └─► 支付日志更新 │
│ │
│ ● 订单发货 (OrderDelivery) │
│ ├─► 发货信息保存 │
│ ├─► 订单状态更新 │
│ └─► 库存扣除 │
│ │
│ ● 订单取消 (OrderCancel) │
│ ├─► 订单状态更新 │
│ └─► 库存回滚 │
│ │
│ ● 订单收货 (OrderCollect) │
│ ├─► 订单状态更新 │
│ ├─► 积分赠送 │
│ └─► 销量增加 │
└──────────────────────────────────────────────────────────────┘16.2 状态同步
┌─────────────────────────────────────────────────────────────────────────────┐
│ 第三方平台同步 │
└─────────────────────────────────────────────────────────────────────────────┘
微信小程序发货同步:
┌──────────────────────────────────────────────────────────────┐
│ OrderDeliverySyncWeixin() │
│ ├─► 发货时触发 │
│ ├─► 收货时触发 │
│ └─► 同步发货/收货状态到微信小程序 │
└──────────────────────────────────────────────────────────────┘17. 附录：常量引用
17.1 订单相关常量
// 订单状态
MyConst('common_order_status')
// 0=待确认, 1=待付款, 2=待发货, 3=待收货, 4=已完成, 5=已取消, 6=已关闭
// 订单模式
// 0=销售型, 1=展示型, 2=自提点, 3=虚拟销售
// 支付状态
// 0=未支付, 1=已支付, 2=已退款, 3=部分退款
// 库存扣除规则
MyConst('common_deduction_inventory_rules_list')
// 0=订单确认成功, 1=订单支付成功, 2=订单发货
// 销量增加规则
MyConst('common_sales_count_inc_rules_list')
// 0=订单支付, 1=订单收货17.2 语言包引用
// 订单状态名称
MyLang('common_order_status.0') // '待确认'
MyLang('common_order_status.1') // '待付款'
// ...
// 业务提示
MyLang('order_id_error_tips')
MyLang('status_not_can_operate_tips')
MyLang('payment_method_error_tips')
// ...18. 总结
OrderService 作为 ShopXO 电商系统的核心订单服务，实现了完整的订单生命周期管理：
核心特性
- 状态机驱动: 基于7种订单状态的严格状态流转
- 权限分离: 管理员与用户操作权限完全分离
- 事务保障: 关键操作使用数据库事务保证数据一致性
- 扩展机制: 丰富的钩子系统支持插件扩展
- 多模式支持: 支持快递、同城、自提、虚拟等多种订单模式
设计亮点
- Service 层封装完整业务逻辑
- 统一返回格式
- 完整的状态历史记录
- 灵活的库存/销量配置
- 支付与业务分离设计
文档版本: 1.0最后更新: 2024-01-30适用版本: ShopXO v6.7.0