电商业务表 | DouPHP 开发手册 | 文档中心 | DouPHP企业建站系统

电商业务表

引言

本设计文档面向DouPHP电商业务模块的数据库表结构设计，聚焦商品、订单、购物车、支付记录、优惠券、收货地址、发票、退款等核心实体与关系。文档基于仓库中实际模型类与升级脚本进行归纳，说明字段用途、关联关系、状态流转、价格计算与库存扣减的数据模型支撑，并提供业务流程时序图与ER图，帮助开发者与业务分析师快速理解并扩展电商能力。

更新本次更新重点增强了订单管理的完整性，新增了发票管理、支付台账、退款管理等高级功能，支持混合支付场景和完整的订单生命周期管理。

项目结构

围绕电商核心域，代码采用"模块+分层"组织：

商品域：产品与分类模型位于 product 模块
订单域：订单主表、条目、地址、券、发票、退款、状态日志位于 order 模块
优惠域：优惠券定义与日志位于 coupon 模块
支付域：独立支付台账记录每笔支付尝试与回调原文
服务层：订单服务协调下单、库存校验、状态迁移、定时任务等逻辑

graph TB
subgraph "商品域"
P["商品(product)"]
PC["商品分类(product_category)"]
end
subgraph "订单域"
O["订单(order)"]
OI["订单条目(order_item)"]
OA["收货地址快照(order_address)"]
OC["订单优惠券(order_coupon)"]
OIv["订单发票(order_invoice)"]
ORF["退款(order_refund)"]
OSLOG["状态日志(order_status_log)"]
OP["支付台账(order_payment)"]
end
subgraph "优惠域"
C["优惠券(coupon)"]
end
subgraph "服务层"
OS["订单服务(OrderService)"]
end
PC --> P
O --> OI
O --> OA
O --> OC
O --> OIv
O --> ORF
O --> OSLOG
O --> OP
C --> OC
OS --> O
OS --> OI
OS --> OC

图表来源

Order.php:32-82
OrderItem.php:31-42
OrderAddress.php:31-40
OrderCoupon.php:32-42
OrderInvoice.php:32-39
OrderRefund.php:35-42
OrderStatusLog.php:35-40
upgrade.php:157-179

核心组件

订单主表（order）：订单核心数据，包含订单号、用户、金额、运费、支付方式、物流、状态、时间戳等，新增混合支付金额拆分、来源追踪、关闭完成时间等字段
订单条目表（order_item）：订单内商品明细，冻结购买时的价格、数量、类目等
收货地址快照表（order_address）：下单时冻结的收件人信息，与会员地址本解耦
订单优惠券表（order_coupon）：一单可叠加多张券，记录使用的券与券流水
订单发票表（order_invoice）：一单一行，支持企业/个人发票类型、开票状态管理
支付台账表（order_payment）：独立记录每笔支付尝试，承载原始请求与回调留底
退款表（order_refund）：售后退款记录，支持混合支付下各渠道分别退款
状态日志表（order_status_log）：订单状态变更审计，记录状态转换轨迹
优惠券表（coupon）：券模板与规则（面额、门槛、有效期、状态等）

章节来源

Order.php:32-82
OrderItem.php:31-42
OrderAddress.php:31-40
OrderCoupon.php:32-42
OrderInvoice.php:32-39
OrderRefund.php:35-42
OrderStatusLog.php:35-40
upgrade.php:227-238

架构总览

订单服务作为编排中心，协调购物车查询、库存守卫、订单条目写入、状态迁移与定时任务，形成下单到支付的完整链路。新增的支付台账和退款管理提供了更精细的财务追踪能力。

sequenceDiagram
participant U as "用户"
participant F as "前端/小程序"
participant S as "订单服务(OrderService)"
participant CQ as "购物车查询(OrderCartQuery)"
participant SG as "库存守卫(OrderStockGuard)"
participant O as "订单(order)"
participant OI as "订单条目(order_item)"
participant OC as "订单优惠券(order_coupon)"
participant OP as "支付台账(order_payment)"
participant ORF as "退款(order_refund)"
participant ST as "状态迁移(OrderStatusTransition)"
participant T as "定时任务(OrderScheduledTasks)"
U->>F : 提交订单
F->>S : 创建订单请求
S->>CQ : 获取购物车视图
CQ-->>S : 购物车明细
S->>SG : 预占库存(按SKU/件数)
SG-->>S : 库存校验通过/失败
alt 库存不足
S-->>F : 返回库存不足
else 库存充足
S->>O : 写入订单主表
S->>OI : 写入订单条目(冻结价/数量)
S->>OC : 写入使用券(多张)
S->>OP : 创建支付记录
S->>ST : 更新订单状态为待支付
S->>T : 注册超时取消/发货等任务
S-->>F : 返回订单号与支付参数
Note over OP : 支付成功后创建退款记录
OP->>ORF : 生成退款单
end

图表来源

Order.php:32-82
OrderItem.php:31-42
OrderCoupon.php:32-42
OrderRefund.php:35-42
upgrade.php:157-179

详细组件分析

订单主表与条目（order / order_item）

订单主表关键字段与作用
- 基础字段：订单号、用户ID、直推/间推用户、模式、模块、类目、联系人、邮箱、支付方式、物流、运单号、运费、商品金额、订单金额、积分、奖励、付款/发货时间、售后状态、评论权限、条目链接状态、订单状态、创建时间等
- 新增字段：parent_order_id（父订单ID）、wallet_paid（钱包支付金额）、gateway_paid（网关支付金额）、cancel_reason（取消原因）、refund_status（退款状态）、buyer_message（买家留言）、seller_message（卖家留言）、source（订单来源）、closed_at（关闭时间）、completed_at（完成时间）
- 提供多种统计口径：按付款时间窗的成交额、订单数、付费用户数、新客/复购、Top商品、分类组成、支付方式聚合等
订单条目关键字段与作用
- 订单ID、用户ID、商品ID、购买数量、类目ID等，冻结购买时的价格与数量，支撑结算与售后

erDiagram
ORDER {
int id PK
string order_sn UK
int user_id
int direct_user_id
int indirect_user_id
string mode
string module
int category_id
int contact_id
string email
int pay_id
int shipping_id
string tracking_no
decimal shipping_fee
decimal item_amount
decimal order_amount
decimal wallet_paid
decimal gateway_paid
int order_point
int direct_reward
int indirect_reward
datetime paid_at
datetime shipped_at
bool allow_aftersale
string aftersale_status
bool allow_comment
bool item_link_status
string status
string parent_order_id
string cancel_reason
string refund_status
string buyer_message
string seller_message
string source
datetime closed_at
datetime completed_at
datetime created_at
}
ORDER_ITEM {
int id PK
int order_id FK
int user_id
int item_id
int item_number
int category_id
}
ORDER ||--o{ ORDER_ITEM : "id -> order_id"

图表来源

Order.php:32-82
OrderItem.php:31-42
upgrade.php:227-238

章节来源

Order.php:32-82
OrderItem.php:31-42

收货地址快照（order_address）

作用：在下单瞬间冻结收件人信息，避免后续修改会员地址影响历史订单
关键字段：订单ID、用户ID、收件人姓名、电话、身份证号、国家、省份、城市、地区、详细地址、邮编、创建时间等
约束：每个订单唯一地址，通过UNIQUE KEY保证

erDiagram
ORDER_ADDRESS {
int id PK
int order_id FK UK
int user_id
string contact_name
string phone
string id_card
string country
string province
string city
string district
string address
string postcode
int created_at
}
ORDER ||--|| ORDER_ADDRESS : "id -> order_id"

图表来源

OrderAddress.php:31-40
upgrade.php:265-283

章节来源

OrderAddress.php:31-40

优惠券与订单优惠券（coupon / order_coupon）

优惠券表：券模板与规则（名称、券码、类型、面额、门槛、起止时间、简介、状态、排序、创建时间）
订单优惠券：一单可叠加多张券，记录订单ID、券ID、券流水ID、优惠金额、优惠类型、创建时间

erDiagram
COUPON {
int id PK
string name
string coupon_sn UK
string type
decimal face_value
text condition
date start_at
date end_at
string brief
string status
int sort
datetime created_at
}
ORDER_COUPON {
int id PK
int order_id FK
int coupon_id FK
int coupon_log_id
decimal amount
string type
int created_at
}
COUPON ||--o{ ORDER_COUPON : "id -> coupon_id"

图表来源

OrderCoupon.php:32-42
upgrade.php:284-296

章节来源

OrderCoupon.php:32-42

订单发票（order_invoice）

作用：支持企业和个人发票管理，一单一行记录
关键字段：订单ID、发票类型（personal/business）、发票抬头、税号、邮箱、是否已开票、开票时间、创建时间
约束：每个订单唯一发票记录

erDiagram
ORDER_INVOICE {
int id PK
int order_id FK UK
string type
string title
string tax_no
string email
tinyint is_issued
int issued_at
int created_at
}
ORDER ||--|| ORDER_INVOICE : "id -> order_id"

图表来源

OrderInvoice.php:32-39
upgrade.php:330-344

章节来源

OrderInvoice.php:32-39

支付台账（order_payment）

作用：独立记录每笔支付尝试，承载原始请求与回调原文留底
关键字段：支付单号、订单ID、订单号、支付网关、金额、状态、交易ID、支付凭证、原始请求、原始回调、支付时间、过期时间、添加时间等
索引优化：支付单号唯一索引、网关交易ID唯一索引、订单ID索引、状态过期时间复合索引

erDiagram
ORDER_PAYMENT {
int id PK
string payment_sn UK
int order_id FK
string order_sn
string gateway
decimal amount
string status
string transaction_id
string pay_evidence
text raw_request
text raw_callback
int paid_at
int expired_at
int add_time
}
ORDER ||--o{ ORDER_PAYMENT : "id -> order_id"

图表来源

upgrade.php:157-179

章节来源

upgrade.php:157-179

退款管理（order_refund）

作用：售后退款记录，支持混合支付下各渠道分别退款
关键字段：退款单号、订单ID、售后ID、原支付ID、渠道、金额、状态、原始回调、退款时间、创建时间等
约束：退款单号唯一，支持按订单和状态筛选

erDiagram
ORDER_REFUND {
int id PK
string refund_sn UK
int order_id FK
int aftersale_id
int order_payment_id
string channel
decimal amount
string status
text raw_callback
int refunded_at
int created_at
}
ORDER ||--o{ ORDER_REFUND : "id -> order_id"

图表来源

OrderRefund.php:35-42
upgrade.php:312-329

章节来源

OrderRefund.php:35-42

状态日志（order_status_log）

作用：订单状态变更审计，记录状态转换轨迹
关键字段：订单ID、原状态、目标状态、原因、操作者类型、操作者ID、IP地址、创建时间等
排序：默认按创建时间和ID升序排列，用于时间线展示

erDiagram
ORDER_STATUS_LOG {
int id PK
int order_id FK
string from_status
string to_status
string reason
string operator_type
int operator_id
string ip
int created_at
}
ORDER ||--o{ ORDER_STATUS_LOG : "id -> order_id"

图表来源

OrderStatusLog.php:35-40
upgrade.php:297-311

章节来源

OrderStatusLog.php:35-40

支付集成与状态流转

支付集成：通过独立的order_payment表记录每笔支付尝试，支持混合支付场景，paid_at标记实际付款时间
状态流转：订单状态通过OrderStatus常量驱动，配合状态日志表记录变更轨迹；服务层提供状态迁移能力

stateDiagram-v2
[*] --> 待支付
待支付 --> 已支付 : "支付成功"
已支付 --> 已发货 : "商家发货"
已发货 --> 已完成 : "确认收货"
待支付 --> 已取消 : "超时未支付/主动取消"
已支付 --> 已退款 : "申请退款成功"
已发货 --> 已退款 : "退货退款"
已支付 --> 已关闭 : "订单关闭"

图表来源

Order.php:32-82
OrderStatusLog.php:35-40

章节来源

Order.php:32-82

价格计算与优惠券使用

价格计算：订单金额由商品条目sale_price × item_number汇总，叠加运费、积分抵扣、优惠券减免后得到最终order_amount
混合支付：支持钱包支付和网关支付金额拆分，wallet_paid和gateway_paid字段分别记录
优惠券使用：下单时选择一张或多张券，写入order_coupon，并在订单金额计算中应用对应减免规则

flowchart TD
Start(["开始"]) --> CalcItems["计算商品小计<br/>Σ(sale_price × item_number)"]
CalcItems --> AddShipping["加上运费"]
AddShipping --> ApplyPoints["积分抵扣(如有)"]
ApplyPoints --> ApplyCoupons["应用优惠券(可叠加)"]
ApplyCoupons --> SplitPayment["混合支付拆分<br/>wallet_paid + gateway_paid"]
SplitPayment --> FinalAmount["得出订单实付金额"]
FinalAmount --> End(["结束"])

图表来源

Order.php:32-82
OrderItem.php:31-42
OrderCoupon.php:32-42
upgrade.php:227-238

章节来源

Order.php:32-82
OrderItem.php:31-42
OrderCoupon.php:32-42

库存管理与事务策略

库存管理：下单前通过库存守卫对商品库存进行校验与预占，防止超卖；支付成功后正式扣减或保持预占直至发货/完成
事务策略：订单创建、条目写入、券使用、状态迁移应在同一事务中执行，确保一致性；支付回调需幂等处理，避免重复落库

sequenceDiagram
participant FE as "前端"
participant SVC as "订单服务"
participant STOCK as "库存守卫"
participant DB as "数据库"
FE->>SVC : 提交订单
SVC->>STOCK : 预占库存(件数)
STOCK-->>SVC : 通过/拒绝
alt 拒绝
SVC-->>FE : 提示库存不足
else 通过
SVC->>DB : 开启事务
SVC->>DB : 写入订单主表
SVC->>DB : 写入订单条目
SVC->>DB : 写入订单优惠券
SVC->>DB : 创建支付记录
SVC->>DB : 更新订单状态
SVC->>DB : 提交事务
SVC-->>FE : 返回订单号
end

图表来源

Order.php:32-82
OrderItem.php:31-42
OrderCoupon.php:32-42
upgrade.php:157-179

章节来源

Order.php:32-82

依赖关系分析

商品与分类：product.category_id → product_category.id
订单与条目：order.id → order_item.order_id
订单与地址：order.id → order_address.order_id
订单与券：order.id → order_coupon.order_id；coupon.id → order_coupon.coupon_id
订单与发票：order.id → order_invoice.order_id
订单与支付：order.id → order_payment.order_id
订单与退款：order.id → order_refund.order_id；order_payment.id → order_refund.order_payment_id
订单与状态日志：order.id → order_status_log.order_id

graph LR
PC["product_category"] --> P["product"]
O["order"] --> OI["order_item"]
O --> OA["order_address"]
O --> OC["order_coupon"]
O --> OIv["order_invoice"]
O --> OP["order_payment"]
O --> ORF["order_refund"]
O --> OSLOG["order_status_log"]
C["coupon"] --> OC

图表来源

Order.php:32-82
OrderItem.php:31-42
OrderAddress.php:31-40
OrderCoupon.php:32-42
OrderInvoice.php:32-39
OrderRefund.php:35-42
OrderStatusLog.php:35-40
upgrade.php:157-179

章节来源

Order.php:32-82

性能考虑

索引建议
- order: order_sn、user_id、status、created_at、paid_at、module、pay_id、idx_user_status
- order_item: order_id、item_id、category_id
- order_address: order_id、user_id
- order_coupon: order_id、coupon_id、coupon_log_id
- order_invoice: order_id
- order_payment: payment_sn、gateway_txn、order_id、status_expired、status_gateway_time、idx_order_gateway
- order_refund: refund_sn、order_id
- order_status_log: order_id、created_at
- product: category_id、brand_id、slug、model
- product_category: parent_id、sync_to_nav
查询优化
- 使用范围条件与分组聚合（如按paid_at窗口统计）减少全表扫描
- 列表页使用默认排序与分页，避免大结果集
- 利用复合索引优化复杂查询
写放大控制
- 下单事务内批量写入，减少往返
- 库存预占与正式扣减分离，降低热点竞争
- 支付台账独立存储，避免主表膨胀

故障排查指南

下单失败
- 检查库存守卫返回与错误原因（库存不足、商品下架）
- 核对订单事务是否完整写入（主表、条目、券）
支付异常
- 检查order_payment表的支付记录状态和回调原文
- 核对支付回调幂等性，避免重复入账
- 验证混合支付金额拆分是否正确
优惠券问题
- 检查优惠券状态、有效期、门槛是否满足
- 核对order_coupon是否写入以及金额减免是否正确
退款问题
- 检查order_refund表中的退款记录和状态
- 验证混合支付下各渠道退款是否正确
发票问题
- 检查order_invoice表中的发票信息和开票状态
- 验证发票类型和抬头信息是否正确
状态不一致
- 查看order_status_log定位状态变更路径
- 核对状态转换逻辑和操作者信息

章节来源

Order.php:32-82
OrderRefund.php:35-42
OrderInvoice.php:32-39
OrderStatusLog.php:35-40

结论

本设计文档基于DouPHP实际模型与升级脚本，梳理了电商核心表的职责与关系，明确了价格计算、优惠券使用、库存管理、发票管理、支付台账、退款管理等高级功能的数据支撑点。通过ER图与时序图，帮助开发者快速把握下单到支付的关键路径与事务边界，并为后续扩展（如多渠道支付、复杂促销、售后流程）提供清晰的数据模型基础。

更新本次更新显著增强了订单管理的完整性和灵活性，特别是混合支付支持和完整的财务追踪能力，为大型电商平台提供了可靠的数据基础。

附录

术语
- 订单金额：订单实付金额，含运费、积分、优惠券等综合计算结果
- 商品金额：订单内商品小计之和
- 预占库存：下单时临时锁定库存，支付成功后转为正式扣减
- 状态日志：记录订单状态变更的历史轨迹
- 混合支付：同时使用钱包余额和第三方支付网关的组合支付方式
- 支付台账：独立记录每笔支付尝试的财务明细表
- 发票管理：支持企业和个人发票的申请、开具、管理功能
- 退款管理：支持部分退款、全额退款、分渠道退款的售后流程

添加日期：2026-10-05