ycc-proxy-server/报告查询链路和代理分配逻辑检查报告.md

# 报告查询链路和代理分配逻辑检查报告

## 一、报告查询链路检查

### 1.1 整体流程

```
用户支付订单
  ↓
支付回调（支付宝/微信）
  ↓
更新订单状态为 "paid"
  ↓
发送异步任务 SendQueryTask(order.Id)
  ↓
异步任务处理 PaySuccessNotifyUserHandler.ProcessTask
  ├─ 创建报告记录（query表）
  ├─ 生成授权书
  ├─ 调用API请求服务获取报告数据
  ├─ 更新报告状态为 "success"
  ├─ 调用代理处理 AgentService.AgentProcess
  └─ 删除Redis缓存
```

### 1.2 链路检查结果

✅ **链路基本通顺**，但存在以下问题：

#### ✅ 问题1：代理处理失败时的处理逻辑 - 已修复

**原问题**：
- 代理处理在报告生成成功后同步执行
- 如果代理处理失败，会触发 `handleError`，但报告已经生成成功

**修复方案**：
1. ✅ 创建了独立的代理处理异步任务 Handler（`app/main/api/internal/queue/agentProcess.go`）
2. ✅ 修改 `paySuccessNotify.go` 改为发送异步任务，不再阻塞报告流程
3. ✅ 代理处理失败时只记录日志，不影响报告使用
4. ✅ 保留了手动重试接口供管理员使用

**修复后的代码**：
```go
// 报告生成成功后，发送代理处理异步任务（不阻塞报告流程）
if asyncErr := l.svcCtx.AsynqService.SendAgentProcessTask(order.Id); asyncErr != nil {
    // 代理处理任务发送失败，只记录日志，不影响报告流程
    logx.Errorf("发送代理处理任务失败，订单ID: %d, 错误: %v", order.Id, asyncErr)
}
```

### 1.3 支付回调链路

✅ **支付回调链路正常**：
- 支付宝回调：`AlipayCallbackLogic.handleQueryOrderPayment`
- 微信回调：`WechatPayCallbackLogic.handleQueryOrderPayment`
- 支付成功后正确发送异步任务

---

## 二、代理分配逻辑检查

### 2.1 代理收益计算

✅ **代理收益计算逻辑正确**

**计算公式**：
```go
实际底价 = 基础底价 + 等级加成
提价成本 = (设定价格 - 提价阈值) × 提价手续费比例（当设定价格 > 提价阈值时）
代理收益 = 设定价格 - 实际底价 - 提价成本
```

**位置**：`app/main/api/internal/service/agentService.go:131-132`

**验证**：
- ✅ 使用产品配置的底价（从 `agent_product_config` 表读取）
- ✅ 等级加成从配置表读取（支持动态配置）
- ✅ 提价成本计算逻辑正确

### 2.2 等级加成返佣分配

#### 2.2.1 黄金代理（等级加成3元）

✅ **实现正确**
- 全部给钻石上级
- 找不到钻石上级时，返佣归平台

**位置**：`app/main/api/internal/service/agentService.go:233-244`

#### 2.2.2 普通代理（等级加成6元）

✅ **已按照新规则修复**

**新规则**（已确认并实现）：
1. **直接上级是钻石**：等级加成全部给钻石上级
2. **直接上级是黄金**：一部分给黄金上级（配置：`normal_to_gold_rebate`，默认3元），剩余给钻石上级
3. **直接上级是普通**：
   - 一部分给直接上级普通（配置：`normal_to_normal_rebate`，默认2元）
   - 剩余金额：
     - 有钻石上级：剩余全部给钻石上级
     - 只有黄金上级：最多给黄金上级（配置：`normal_to_gold_rebate_max`，默认3元），超出归平台
     - 都没有：全部归平台

**代码实现**（`app/main/api/internal/service/agentService.go:254-368`）：
- ✅ 按照新规则完全重写
- ✅ 支持从配置表读取返佣金额（如果配置不存在使用默认值）
- ✅ 跳过多层普通代理，直接查找钻石/黄金上级

**配置项**：
- `normal_to_normal_rebate`：普通代理给直接上级普通的金额（默认2元）
- `normal_to_gold_rebate`：普通代理给直接上级黄金的金额（默认3元）
- `normal_to_gold_rebate_max`：普通代理给黄金上级的最大金额（默认3元）

### 2.3 代理收益分配流程

✅ **分配流程正确**

**流程**：
1. 检查是否是代理订单
2. 检查订单是否已处理（防重复）
3. 获取代理信息和产品配置
4. 使用事务处理（保证原子性）：
   - 计算代理收益
   - 更新代理订单状态
   - 发放代理佣金到代理钱包
   - 分配等级加成返佣给上级链

**位置**：`app/main/api/internal/service/agentService.go:76-156`

### 2.4 事务处理和错误处理

✅ **事务处理正确**

**验证**：
- ✅ 使用 `AgentWalletModel.Trans` 事务处理
- ✅ 所有数据库操作在同一事务中
- ✅ 任何步骤失败都会回滚

**位置**：`app/main/api/internal/service/agentService.go:109`

### 2.5 防重复处理

✅ **防重复处理正确**

**验证**：
- ✅ 检查 `agent_order.ProcessStatus == 1` 判断是否已处理
- ✅ 已处理的订单直接返回，不重复处理

**位置**：`app/main/api/internal/service/agentService.go:87-91`

---

## 三、其他发现

### 3.1 重试机制

✅ **已有手动重试接口**

**位置**：
- 接口：`POST /api/v1/admin/order/retry-agent-process/:id`
- Logic：`app/main/api/internal/logic/admin_order/adminretryagentprocesslogic.go`

**功能**：
- 管理员可以手动触发代理处理重试
- 可以处理代理处理失败的情况

### 3.2 代理处理失败时的错误处理

**当前行为**：
- 代理处理失败会触发 `handleError`
- `handleError` 会尝试退款（如果报告状态为 pending）
- 但报告已经生成成功，可能不会触发退款

**建议**：
- 代理处理失败不应该触发退款（因为报告已经成功生成）
- 应该记录错误日志，供管理员手动重试

---

## 四、总结和建议

### 4.1 需要确认的问题

1. **普通代理等级加成返佣分配规则**
   - 文档和代码实现不一致
   - 需要确认正确的业务规则

### 4.2 建议改进

1. **代理处理失败的处理**
   - 建议将代理处理改为独立的异步任务，或至少确保失败不影响报告使用
   - 失败时只记录日志，不触发退款

2. **文档更新**
   - 根据最终确认的业务规则，更新文档或代码

3. **日志增强**
   - 在代理处理失败时记录更详细的日志，方便排查问题

### 4.3 整体评价

- ✅ 报告查询链路基本通顺
- ✅ 代理收益计算逻辑正确
- ✅ 事务处理和防重复处理正确
- ⚠️ 普通代理等级加成返佣分配规则需要确认
- ⚠️ 代理处理失败时的处理逻辑可以优化

---

## 五、代码位置索引

### 报告查询链路
- 支付回调：`app/main/api/internal/logic/pay/alipaycallbacklogic.go:56-106`
- 异步任务：`app/main/api/internal/queue/paySuccessNotify.go:35-178`
- 报告查询：`app/main/api/internal/logic/query/querylistlogic.go`

### 代理分配逻辑
- 代理处理入口：`app/main/api/internal/service/agentService.go:76-156`
- 收益计算：`app/main/api/internal/service/agentService.go:131-132`
- 等级加成返佣：`app/main/api/internal/service/agentService.go:226-328`
- 普通代理返佣分配：`app/main/api/internal/service/agentService.go:254-328`