--- url: /blog/n4hasthz/index.md --- # OrderService 订单服务技术方案 ## 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∉{0,5,6} | status=1 | | **is\_delivery** (发货) | order\_model=0 且 status∈{2,3} | - | | **is\_service** (同城) | order\_model=1 且 status∈{2,3} | - | | **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 订单相关常量 ```php // 订单状态 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 语言包引用 ```php // 订单状态名称 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 电商系统的核心订单服务，实现了完整的订单生命周期管理： ### 核心特性 1. **状态机驱动**: 基于7种订单状态的严格状态流转 2. **权限分离**: 管理员与用户操作权限完全分离 3. **事务保障**: 关键操作使用数据库事务保证数据一致性 4. **扩展机制**: 丰富的钩子系统支持插件扩展 5. **多模式支持**: 支持快递、同城、自提、虚拟等多种订单模式 ### 设计亮点 * Service 层封装完整业务逻辑 * 统一返回格式 * 完整的状态历史记录 * 灵活的库存/销量配置 * 支付与业务分离设计 *** *文档版本: 1.0* *最后更新: 2024-01-30* *适用版本: ShopXO v6.7.0*