简介

本设计文档聚焦 DouPHP 电商系统的“订单售后”能力，围绕售后主表、售后商品明细表、售后时间线日志表、售后寄回物流表等核心数据模型，系统阐述售后申请、审核处理、退款与换货/维修流程的状态机约束、费用计算与多类型支持。面向电商平台开发者，提供可落地的数据模型与业务流程参考实现。

项目结构

售后模块在系统中按领域分层组织：

• 后台模型层：定义售后主表、明细表、日志表、寄回表的查询封装与筛选器。
• 基础能力层：售后状态机与售后类型枚举，统一状态迁移校验与类型语义。
• 前台服务层：会员端售后申请、列表展示、详情格式化、提交售后申请等。
• 视图与语言包：后台售后列表与详情页、国际化文案。
• 升级脚本：数据库表结构与字段迁移、索引优化、历史数据兼容。

graph TB
subgraph "后台模型"
M1["售后主表模型<br/>Aftersale"]
M2["售后商品明细模型<br/>AftersaleItem"]
M3["售后日志模型<br/>AftersaleLog"]
M4["售后寄回模型<br/>AftersaleReturn"]
end
subgraph "基础能力"
F1["售后状态机<br/>AftersaleStatus"]
F2["售后类型枚举<br/>AftersaleType"]
end
subgraph "前台服务"
S1["售后服务<br/>AftersaleService"]
end
subgraph "视图与语言"
V1["后台售后页面<br/>aftersale.htm"]
L1["语言包<br/>aftersale.lang.php"]
end
subgraph "升级脚本"
U1["售后重构升级脚本<br/>upgrade.php"]
end
S1 --> F1
S1 --> F2
S1 --> M1
S1 --> M2
S1 --> M3
S1 --> M4
V1 --> M1
V1 --> M2
V1 --> M3
V1 --> M4
U1 --> M1
U1 --> M2
U1 --> M3
U1 --> M4

核心组件

• 售后主表模型：提供按售后单号、时间范围筛选与默认排序能力，映射到 aftersale 表。
• 售后商品明细模型：按售后单过滤明细行，支撑按行申请与部分退款场景。
• 售后日志模型：按售后单拉取时间线，记录状态变更、操作人、备注与附件令牌。
• 售后寄回模型：按售后单获取寄回物流信息，支撑退货退款流程的物流跟踪。
• 售后状态机：定义合法状态集合、终态集合与迁移规则，确保状态流转一致性。
• 售后类型枚举：定义仅退款、退货退款、换货、维修等类型，并提供是否需要寄回的判断。

架构总览

售后系统以“状态机 + 卫星表”为核心：

• 主表 aftersale 承载售后单生命周期；
• 明细表 aftersale_item 承载按行申请与金额拆分；
• 日志表 aftersale_log 承载全链路协商与操作轨迹；
• 寄回表 aftersale_return 承载退货退款物流信息；
• 状态机 AftersaleStatus 保证状态迁移合法性；
• 类型枚举 AftersaleType 决定流程分支（是否需寄回）。

sequenceDiagram
participant Buyer as "买家"
participant Front as "前台服务<br/>AftersaleService"
participant Status as "状态机<br/>AftersaleStatus"
participant DB as "数据库"
participant Admin as "后台界面<br/>aftersale.htm"
Buyer->>Front : "提交售后申请类型、原因、商品行"
Front->>DB : "写入 aftersale / aftersale_item"
Front->>Status : "校验初始状态 pending"
Status-->>Front : "允许"
Front-->>Buyer : "返回申请成功"
Admin->>Front : "审核/驳回/同意人工处理"
Front->>Status : "校验迁移pending→approved/rejected/cancelled"
Status-->>Front : "允许/拒绝"
Front->>DB : "更新状态并写日志"
Note over Front,DB : "若为退货退款且已收货，进入退款流程"

详细组件分析

数据模型与表结构

• 售后主表（aftersale）
  • 关键字段：id、order_id、user_id、aftersale_sn、type、status、apply_amount、refunded_amount、reason、created_at、handled_at、closed_at 等
  • 用途：记录售后单基本信息、申请金额、已退金额、原因、时间戳与处理节点
  • 索引：idx_status_expired(status, expired_at) 用于超时自动撤销等批量任务
• 售后商品明细表（aftersale_item）
  • 关键字段：id、aftersale_id、order_id、order_item_id、item_id、quantity、amount、reason
  • 用途：按行申请售后，记录每行数量与金额，支持部分退款/换货/维修
• 售后日志表（aftersale_log）
  • 关键字段：id、aftersale_id、from_status、to_status、action、operator_type、operator_id、note、attachment_token、created_at
  • 用途：完整记录协商与处理时间线，便于客服追溯
• 售后寄回表（aftersale_return）
  • 关键字段：id、aftersale_id、company、sn、shipped_at 等
  • 用途：记录退货退款时的物流公司、运单号与发货时间

erDiagram
AFTERSALE {
int id PK
int order_id
int user_id
varchar aftersale_sn
varchar type
varchar status
decimal apply_amount
decimal refunded_amount
text reason
datetime created_at
datetime handled_at
datetime closed_at
}
AFTERSALE_ITEM {
int id PK
int aftersale_id FK
int order_id
int order_item_id
int item_id
smallint quantity
decimal amount
text reason
}
AFTERSALE_LOG {
int id PK
int aftersale_id FK
varchar from_status
varchar to_status
varchar action
varchar operator_type
int operator_id
text note
varchar attachment_token
datetime created_at
}
AFTERSALE_RETURN {
int id PK
int aftersale_id FK
varchar company
varchar sn
datetime shipped_at
}
AFTERSALE ||--o{ AFTERSALE_ITEM : "包含"
AFTERSALE ||--o{ AFTERSALE_LOG : "记录"
AFTERSALE ||--o| AFTERSALE_RETURN : "退货退款时存在"

售后类型与状态管理

• 售后类型
  • 仅退款：无需寄回，审核通过可直接进入退款流程
  • 退货退款：需要买家寄回，进入等待寄回→已寄出→确认收货→退款流程
  • 换货/维修：预留类型位，可扩展后续流程
• 状态机
  • 状态集合：申请中、已同意、已驳回、已撤销、待寄回、买家已寄出、卖家已收货、退款中、已退款、退款失败
  • 终态：已退款、已驳回、已撤销
  • 迁移规则：严格限制状态转换路径，避免非法跳转

stateDiagram-v2
[*] --> 申请中
申请中 --> 已同意 : "商家同意"
申请中 --> 已驳回 : "商家驳回"
申请中 --> 已撤销 : "买家撤销/超时"
已同意 --> 待寄回 : "退货退款需寄回"
已同意 --> 退款中 : "仅退款直接退款"
待寄回 --> 买家已寄出 : "填写运单"
待寄回 --> 已撤销 : "逾期未寄回"
买家已寄出 --> 卖家已收货 : "确认收货"
买家已寄出 --> 已驳回 : "异常处理"
卖家已收货 --> 退款中 : "进入退款"
卖家已收货 --> 已驳回 : "异常处理"
退款中 --> 已退款 : "退款成功"
退款中 --> 退款失败 : "网关无回调等"
退款失败 --> 退款中 : "重试"

售后申请流程（买家侧）

• 前置校验：订单必须允许售后、属于当前用户
• 写入数据：创建 aftersale 与若干 aftersale_item 行
• 初始状态：设置为“申请中”，等待商家审核
• 草稿附件：支持上传草稿令牌，提交后关联到真实售后单

flowchart TD
Start(["开始"]) --> CheckOrder["校验订单是否允许售后"]
CheckOrder --> |否| Error["返回错误：订单不可申请售后"]
CheckOrder --> |是| CreateApply["创建售后主表与明细行"]
CreateApply --> SetStatus["设置状态为申请中"]
SetStatus --> AttachClaim["草稿附件认领到售后单"]
AttachClaim --> End(["完成"])

审核处理流程（商家侧）

• 商家在后台查看售后列表与详情，执行同意/驳回/撤销等操作
• 状态迁移由状态机校验，确保符合业务规则
• 每次操作写入日志表，记录操作人、动作、备注与附件令牌

sequenceDiagram
participant Admin as "商家后台"
participant Service as "售后服务"
participant Status as "状态机"
participant DB as "数据库"
Admin->>Service : "提交审核同意/驳回/撤销"
Service->>Status : "校验迁移from→to"
Status-->>Service : "允许/拒绝"
Service->>DB : "更新状态并写入日志"
Service-->>Admin : "返回结果"

退款处理流程

• 仅退款：审核通过后直接进入退款中，成功后标记已退款
• 退货退款：等待寄回→买家填运单→确认收货→进入退款中→成功后标记已退款
• 退款失败：网关无回调等异常，标记退款失败并可重试

flowchart TD
Start(["开始"]) --> Type{"售后类型"}
Type --> |仅退款| DirectRefund["进入退款中"]
Type --> |退货退款| WaitReturn["等待买家寄回"]
WaitReturn --> Ship["买家已寄出"]
Ship --> Receive["卖家已收货"]
Receive --> Refund["进入退款中"]
DirectRefund --> Result{"退款结果"}
Refund --> Result
Result --> |成功| Done["已退款"]
Result --> |失败| Failed["退款失败"]
Failed --> Retry["重试退款"]
Retry --> Result

换货与维修处理

• 类型预留：换货与维修作为扩展类型位，当前流程以退款为主
• 扩展建议：可在状态机中增加换货/维修专属状态分支，并在明细表中记录换货商品或维修费用
• 兼容性：现有数据模型支持按行金额与原因字段，便于未来扩展

售后费用计算

• 申请金额：来自售后主表 apply_amount，表示本次售后申请总金额
• 已退金额：refunded_amount 累计实际退款金额，支持多次退款与部分退款
• 明细金额：aftersale_item.amount 记录每行商品的售后金额，便于统计与对账
• 价格格式化：前端展示使用统一的价格格式化函数

售后数据流程跟踪与客户服务

• 时间线：aftersale_log 记录从申请到关闭的全量事件，包括状态变化、操作人、备注与附件令牌
• 物流跟踪：aftersale_return 记录物流公司与运单号，便于客服查询与提醒
• 列表与详情：后台页面展示售后单基本信息、状态、订单快照与操作入口

依赖关系分析

• 前台服务依赖状态机与类型枚举，确保申请与处理的合法性
• 后台视图依赖模型层进行筛选与排序，渲染售后列表与详情
• 升级脚本负责表结构迁移与索引优化，保障数据一致性与查询性能
• 语言包提供多语言文案，统一显示状态与类型文本

graph LR
Front["前台服务"] --> Status["状态机"]
Front --> Type["类型枚举"]
AdminView["后台视图"] --> Models["模型层"]
Models --> DB["数据库"]
Upgrade["升级脚本"] --> DB
Lang["语言包"] --> AdminView

性能考虑

• 索引优化：
  • idx_status_expired(status, expired_at) 支持批量超时撤销
  • aftersale_log 的 idx_aftersale(aftersale_id, created_at) 提升时间线查询效率
• 查询优化：
  • 模型层提供 scope 筛选器，减少冗余条件拼接
  • 分页查询默认按 id DESC，避免大偏移量导致的性能问题
• 数据迁移：
  • 升级脚本幂等执行，避免重复迁移导致的数据不一致

故障排查指南

• 常见错误提示：
  • 订单不可申请售后：检查订单是否允许售后、是否属于当前用户
  • 当前状态不允许该操作：检查状态机迁移是否合法
  • 请填写物流公司与运单号：退货退款必填项未填写
  • 售后申请已撤销：买家主动撤销或系统自动撤销
• 定位方法：
  • 查看 aftersale_log 时间线，确认最近一次状态变更与操作人
  • 核对 aftersale.status 与 AftersaleStatus 迁移规则
  • 检查 aftersale_return 是否存在寄回信息

结论

DouPHP 售后模块通过“状态机 + 卫星表”的设计，实现了严谨的流程控制与灵活的扩展能力。主表与明细表分离支持按行申请与金额拆分，日志表提供全链路可追溯性，寄回表支撑退货退款物流跟踪。结合升级脚本与索引优化，系统在数据一致性与查询性能方面具备良好实践。开发者可基于此参考实现快速搭建完善的售后服务体系。

附录

• 术语说明：
  • 仅退款：无需寄回，直接退款
  • 退货退款：需买家寄回，确认收货后退款
  • 换货/维修：预留类型位，可扩展专属流程
• 最佳实践：
  • 所有状态变更必须经过状态机校验
  • 关键操作写入日志表，保留操作痕迹
  • 使用索引优化高频查询，避免全表扫描