This commit is contained in:
196
docs/order_status_quick_reference.md
Normal file
196
docs/order_status_quick_reference.md
Normal file
@@ -0,0 +1,196 @@
|
||||
# 订单状态与佣金系统 - 快速参考
|
||||
|
||||
## 订单支付状态速查表
|
||||
|
||||
| 状态值 | 常量名 | 说明 | 触发条件 | 后续操作 |
|
||||
|-------|-------|------|---------|---------|
|
||||
| 1 | `PaymentStatusPending` | 待支付 | 微信/支付宝支付创建订单 | 支付回调或30分钟超时 |
|
||||
| 2 | `PaymentStatusPaid` | 已支付 | 线下/钱包支付或支付成功回调 | 激活套餐、计算佣金 |
|
||||
| 3 | `PaymentStatusCancelled` | 已取消 | 待支付订单超时30分钟 | 解冻钱包余额 |
|
||||
| 4 | `PaymentStatusRefunded` | 已退款 | 退款操作 | 返还金额 |
|
||||
|
||||
## 订单佣金状态速查表
|
||||
|
||||
| 状态值 | 常量名 | 说明 | 触发条件 | 后续操作 |
|
||||
|-------|-------|------|---------|---------|
|
||||
| 1 | `CommissionStatusPending` | 待计算 | 订单创建时默认 | 异步任务计算佣金 |
|
||||
| 2 | `CommissionStatusCalculated` | 已计算 | 佣金计算完成 | 佣金入账到分佣钱包 |
|
||||
|
||||
## 订单创建流程速查
|
||||
|
||||
### 线下支付（offline）
|
||||
```
|
||||
创建订单 → PaymentStatus=2(已支付) → 激活套餐 → 入队佣金计算
|
||||
```
|
||||
|
||||
### 钱包支付（wallet）
|
||||
```
|
||||
创建订单 → PaymentStatus=2(已支付) → 扣款 → 激活套餐 → 入队佣金计算
|
||||
```
|
||||
|
||||
### 微信/支付宝（wechat/alipay）
|
||||
```
|
||||
创建订单 → PaymentStatus=1(待支付) → 支付回调 → PaymentStatus=2 → 激活套餐 → 入队佣金计算
|
||||
↓
|
||||
30分钟超时 → PaymentStatus=3(已取消) → 解冻余额
|
||||
```
|
||||
|
||||
## 钱包冻结状态速查表
|
||||
|
||||
| 字段 | 说明 | 计算方式 |
|
||||
|------|------|---------|
|
||||
| `balance` | 总余额 | 充值 + 佣金入账 - 扣款 |
|
||||
| `frozen_balance` | 冻结余额 | 提现申请时冻结 |
|
||||
| 可用余额 | 可提现金额 | `balance - frozen_balance` |
|
||||
|
||||
## 提现流程速查
|
||||
|
||||
### 阶段 1: 代理发起申请
|
||||
```
|
||||
验证可用余额 ✓
|
||||
↓
|
||||
冻结余额 (frozen_balance += amount)
|
||||
↓
|
||||
创建提现申请 (Status=1 待审核)
|
||||
↓
|
||||
创建钱包流水 (Status=3 处理中)
|
||||
```
|
||||
|
||||
### 阶段 2a: 平台审核通过
|
||||
```
|
||||
检查冻结余额 ✓
|
||||
↓
|
||||
从冻结余额扣款 (frozen_balance -= amount)
|
||||
↓
|
||||
创建提现交易流水
|
||||
↓
|
||||
更新提现申请 (Status=2 已通过)
|
||||
```
|
||||
|
||||
### 阶段 2b: 平台审核拒绝
|
||||
```
|
||||
解冻余额 (frozen_balance -= amount)
|
||||
↓
|
||||
创建退款交易流水
|
||||
↓
|
||||
更新提现申请 (Status=3 已拒绝)
|
||||
```
|
||||
|
||||
## 佣金类型速查
|
||||
|
||||
| 佣金类型 | 常量值 | 触发条件 | 计算方式 |
|
||||
|---------|-------|---------|---------|
|
||||
| 成本价差 | `cost_diff` | 所有订单 | 销售价 - 销售成本价 |
|
||||
| 一次性 | `one_time` | 非代购订单首次购买 | 根据配置 |
|
||||
|
||||
## 关键代码位置速查
|
||||
|
||||
### 订单相关
|
||||
- 订单模型: `internal/model/order.go:98-110`
|
||||
- 订单创建: `internal/service/order/service.go:114-928`
|
||||
- 订单超时: `internal/service/order/service.go:1314-1385`
|
||||
|
||||
### 佣金相关
|
||||
- 佣金计算: `internal/service/commission_calculation/service.go:74-119`
|
||||
- 成本价差: `internal/service/commission_calculation/service.go:121-230`
|
||||
|
||||
### 提现相关
|
||||
- 发起申请: `internal/service/shop_commission/service.go:517-649`
|
||||
- 审核通过: `internal/service/commission_withdrawal/service.go:145-256`
|
||||
- 审核拒绝: `internal/service/commission_withdrawal/service.go:258-310`
|
||||
|
||||
## 常用常量速查
|
||||
|
||||
```go
|
||||
// 订单超时
|
||||
constants.OrderExpireTimeout = 30 * time.Minute
|
||||
|
||||
// 钱包状态
|
||||
constants.AgentWalletStatusNormal = 1 // 正常
|
||||
constants.AgentWalletStatusFrozen = 2 // 冻结
|
||||
constants.AgentWalletStatusClosed = 3 // 关闭
|
||||
|
||||
// 交易状态
|
||||
constants.TransactionStatusSuccess = 1 // 成功
|
||||
constants.TransactionStatusFailed = 2 // 失败
|
||||
constants.TransactionStatusProcessing = 3 // 处理中
|
||||
|
||||
// 提现状态
|
||||
constants.WithdrawalStatusPending = 1 // 待审核
|
||||
constants.WithdrawalStatusApproved = 2 // 已通过
|
||||
constants.WithdrawalStatusRejected = 3 // 已拒绝
|
||||
```
|
||||
|
||||
## 常见问题速查
|
||||
|
||||
### Q: 订单什么时候计算佣金？
|
||||
A: 订单支付成功后立即入队佣金计算任务（异步）。线下/钱包支付创建时已支付，微信/支付宝支付在回调时支付。
|
||||
|
||||
### Q: 提现时冻结的余额什么时候解冻？
|
||||
A:
|
||||
- 审核通过：从冻结余额扣款（不解冻，直接扣除）
|
||||
- 审核拒绝：解冻余额回到可用余额
|
||||
|
||||
### Q: 可用余额如何计算？
|
||||
A: `可用余额 = 总余额 - 冻结余额`
|
||||
|
||||
### Q: 订单超时自动取消后还会计算佣金吗？
|
||||
A: 不会。取消的订单佣金状态保持为 `待计算`，不会入队计算。
|
||||
|
||||
### Q: 代购订单是否计算一次性佣金？
|
||||
A: 不计算。一次性佣金仅对非代购订单触发。
|
||||
|
||||
### Q: 成本价差佣金如何沿代理链分配？
|
||||
A: 从销售店铺开始，沿着 `parent_id` 向上逐级分配。每一级的佣金 = 该级成本价 - 下级成本价。
|
||||
|
||||
## 数据库查询速查
|
||||
|
||||
### 查询待支付订单
|
||||
```sql
|
||||
SELECT * FROM tb_order WHERE payment_status = 1 AND expires_at < NOW();
|
||||
```
|
||||
|
||||
### 查询待计算佣金的订单
|
||||
```sql
|
||||
SELECT * FROM tb_order WHERE commission_status = 1;
|
||||
```
|
||||
|
||||
### 查询店铺可用余额
|
||||
```sql
|
||||
SELECT balance - frozen_balance as available_balance
|
||||
FROM tb_agent_wallet
|
||||
WHERE shop_id = ? AND wallet_type = 'commission';
|
||||
```
|
||||
|
||||
### 查询提现中的金额
|
||||
```sql
|
||||
SELECT SUM(amount) as withdrawing_amount
|
||||
FROM tb_commission_withdrawal_request
|
||||
WHERE shop_id = ? AND status = 1;
|
||||
```
|
||||
|
||||
### 查询已提现的金额
|
||||
```sql
|
||||
SELECT SUM(amount) as withdrawn_amount
|
||||
FROM tb_commission_withdrawal_request
|
||||
WHERE shop_id = ? AND status = 2;
|
||||
```
|
||||
|
||||
## 业务规则速查
|
||||
|
||||
1. **订单支付规则**
|
||||
- 待支付订单 30 分钟未支付自动取消
|
||||
- 取消时解冻钱包余额（如有）
|
||||
- 防止重复下单（幂等性检查）
|
||||
|
||||
2. **佣金计算规则**
|
||||
- 成本价差佣金：仅当 `销售价 > 销售成本价` 时计算
|
||||
- 一次性佣金：仅非代购订单首次购买时触发
|
||||
- 佣金链路断裂时标记为待审核
|
||||
|
||||
3. **提现规则**
|
||||
- 提现申请时冻结余额
|
||||
- 可用余额 = 总余额 - 冻结余额
|
||||
- 手续费 = 提现金额 × 费率 / 10000
|
||||
- 实际到账 = 提现金额 - 手续费
|
||||
|
||||
Reference in New Issue
Block a user