v1.0

distributeNormalAgentBonus配置项说明.md

@@ -0,0 +1,101 @@
+# distributeNormalAgentBonus 函数使用的配置项说明
+
+## 函数位置
+`ycc-proxy-server/app/main/api/internal/service/agentService.go:254-478`
+
+## 使用的配置项列表
+
+### 1. `direct_parent_amount_normal`
+- **配置键**：`direct_parent_amount_normal`
+- **类型**：浮点数（float64）
+- **默认值**：2.0元
+- **使用位置**：第376行
+- **用途**：普通代理给直接上级普通代理的返佣金额
+- **使用场景**：
+  - 当直接上级是普通代理时使用
+  - 无论后续层级有多少普通代理，这部分金额只给推广人的直接上级
+- **示例**：等级加成6元，给直接上级普通代理2元
+
+### 2. `direct_parent_amount_gold`
+- **配置键**：`direct_parent_amount_gold`
+- **类型**：浮点数（float64）
+- **默认值**：3.0元
+- **使用位置**：第326行
+- **用途**：普通代理给直接上级黄金代理的返佣金额
+- **使用场景**：
+  - 当直接上级是黄金代理时使用
+  - 这部分金额给直接上级黄金代理，剩余部分继续向上分配给钻石上级
+- **示例**：等级加成6元，给直接上级黄金代理3元，剩余3元给钻石上级
+
+### 3. `max_gold_rebate_amount`
+- **配置键**：`max_gold_rebate_amount`
+- **类型**：浮点数（float64）
+- **默认值**：3.0元
+- **使用位置**：第492行
+- **用途**：普通代理给黄金上级的最大返佣金额
+- **使用场景**：
+  - 当直接上级是普通代理，且只有黄金上级（没有钻石上级）时使用
+  - 即使剩余金额超过这个值，也只能给黄金上级最多这个金额，超出部分归平台
+- **示例**：剩余4元，最大限额3元，则给黄金3元，剩余1元归平台
+
+### 4. `level_2_bonus`
+- **配置键**：`level_2_bonus`
+- **类型**：整数（int64），从配置读取时转换为浮点数计算
+- **默认值**：3元
+- **使用位置**：第438行（通过 `getLevelBonus(ctx, 2)` 调用）
+- **用途**：黄金代理的等级加成
+- **使用场景**：
+  - 用于计算等级加成的差（普通等级加成 - 黄金等级加成）
+  - 当直接上级是普通代理，且上级链中有黄金和钻石时，用于计算给黄金的返佣金额
+- **计算逻辑**：
+  - 等级加成差 = 普通等级加成（6元）- 黄金等级加成（3元）= 3元
+  - 给黄金的金额 = 等级加成差（3元）- 已给普通的部分（2元）= 1元
+
+### 5. `level_1_bonus`
+- **配置键**：`level_1_bonus`
+- **类型**：整数（int64）
+- **默认值**：6元
+- **使用位置**：通过 `amount` 参数传入（在 `AgentProcess` 中通过 `getLevelBonus(ctx, 1)` 获取）
+- **用途**：普通代理的等级加成
+- **说明**：
+  - 不在 `distributeNormalAgentBonus` 函数中直接读取
+  - 作为 `amount` 参数传入函数
+  - 这是需要分配的总额
+
+## 配置项使用总结表
+
+| 配置键 | 默认值 | 使用场景 | 代码行号 |
+|--------|--------|---------|---------|
+| `direct_parent_amount_normal` | 2.0元 | 直接上级是普通代理时，给直接上级的返佣金额 | 376 |
+| `direct_parent_amount_gold` | 3.0元 | 直接上级是黄金代理时，给直接上级的返佣金额 | 326 |
+| `max_gold_rebate_amount` | 3.0元 | 只有黄金上级（无钻石）时，给黄金的最大返佣金额 | 492 |
+| `level_2_bonus` | 3元 | 黄金代理等级加成，用于计算等级加成差 | 438 |
+| `level_1_bonus` | 6元 | 普通代理等级加成，通过参数传入 | - |
+
+## 配置项在代码中的调用关系
+
+```
+AgentProcess (处理订单)
+  ↓
+  调用 getLevelBonus(ctx, agent.Level) 获取普通代理等级加成
+  ↓
+  传入 distributeNormalAgentBonus(amount=6元, ...)
+  ↓
+  在函数内使用：
+    1. getRebateConfigFloat("direct_parent_amount_normal", 2.0)  # 第376行
+    2. getRebateConfigFloat("direct_parent_amount_gold", 3.0)    # 第326行
+    3. getRebateConfigFloat("max_gold_rebate_amount", 3.0)       # 第492行
+    4. getLevelBonus(ctx, 2) -> 读取 level_2_bonus              # 第438行
+```
+
+## 注意事项
+
+1. **所有配置项都支持动态配置**：如果配置不存在，会使用默认值
+2. **配置读取失败会记录日志**：确保配置问题时可以追踪
+3. **配置值的类型转换**：
+   - 返佣配置直接使用浮点数（支持小数）
+   - 等级加成从配置读取时为整数，计算时转换为浮点数
+4. **配置项命名规范**：
+   - 返佣配置使用描述性名称：`direct_parent_amount_normal`、`direct_parent_amount_gold`、`max_gold_rebate_amount`
+   - 等级加成配置使用数字后缀：`level_1_bonus`、`level_2_bonus`
+