f

app/main/api/desc/admin/admin_agent.api

@@ -86,6 +86,10 @@ service main {
 	// 代理手机号修改
 	@handler AdminUpdateAgentMobile
 	post /mobile/update (AdminUpdateAgentMobileReq) returns (AdminUpdateAgentMobileResp)
+
+	// 代理等级降级（管理端）
+	@handler AdminDowngradeAgent
+	post /level/downgrade (AdminDowngradeAgentReq) returns (AdminDowngradeAgentResp)
 }
 
 type (
@@ -443,5 +447,14 @@ type (
 	AdminUpdateAgentMobileResp {
 		Success bool `json:"success"`
 	}
+	// 代理等级降级
+	AdminDowngradeAgentReq {
+		AgentId string `json:"agent_id"` // 代理ID
+		ToLevel int64  `json:"to_level"` // 目标等级：1=普通，2=黄金，3=钻石（须低于当前等级）
+		Remark  string `json:"remark,optional"` // 备注（可选）
+	}
+	AdminDowngradeAgentResp {
+		Success bool `json:"success"`
+	}
 )
 

app/main/api/internal/handler/admin_agent/admindowngradeagenthandler.go

@@ -0,0 +1,29 @@
+package admin_agent
+
+import (
+	"net/http"
+
+	"github.com/zeromicro/go-zero/rest/httpx"
+	"ycc-server/app/main/api/internal/logic/admin_agent"
+	"ycc-server/app/main/api/internal/svc"
+	"ycc-server/app/main/api/internal/types"
+	"ycc-server/common/result"
+	"ycc-server/pkg/lzkit/validator"
+)
+
+func AdminDowngradeAgentHandler(svcCtx *svc.ServiceContext) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		var req types.AdminDowngradeAgentReq
+		if err := httpx.Parse(r, &req); err != nil {
+			result.ParamErrorResult(r, w, err)
+			return
+		}
+		if err := validator.Validate(req); err != nil {
+			result.ParamValidateErrorResult(r, w, err)
+			return
+		}
+		l := admin_agent.NewAdminDowngradeAgentLogic(r.Context(), svcCtx)
+		resp, err := l.AdminDowngradeAgent(&req)
+		result.HttpResult(r, w, resp, err)
+	}
+}

app/main/api/internal/handler/routes.go

@@ -69,6 +69,11 @@ func RegisterHandlers(server *rest.Server, serverCtx *svc.ServiceContext) {
 					Path:    "/invite_code/list",
 					Handler: admin_agent.AdminGetInviteCodeListHandler(serverCtx),
 				},
+				{
+					Method:  http.MethodPost,
+					Path:    "/level/downgrade",
+					Handler: admin_agent.AdminDowngradeAgentHandler(serverCtx),
+				},
 				{
 					Method:  http.MethodGet,
 					Path:    "/link/list",
@@ -79,6 +84,11 @@ func RegisterHandlers(server *rest.Server, serverCtx *svc.ServiceContext) {
 					Path:    "/list",
 					Handler: admin_agent.AdminGetAgentListHandler(serverCtx),
 				},
+				{
+					Method:  http.MethodPost,
+					Path:    "/mobile/update",
+					Handler: admin_agent.AdminUpdateAgentMobileHandler(serverCtx),
+				},
 				{
 					Method:  http.MethodGet,
 					Path:    "/order/list",
@@ -94,11 +104,6 @@ func RegisterHandlers(server *rest.Server, serverCtx *svc.ServiceContext) {
 					Path:    "/product_config/update",
 					Handler: admin_agent.AdminUpdateAgentProductConfigHandler(serverCtx),
 				},
-				{
-					Method:  http.MethodPost,
-					Path:    "/mobile/update",
-					Handler: admin_agent.AdminUpdateAgentMobileHandler(serverCtx),
-				},
 				{
 					Method:  http.MethodGet,
 					Path:    "/real_name/list",

app/main/api/internal/logic/admin_agent/admindowngradeagentlogic.go

@@ -0,0 +1,51 @@
+package admin_agent
+
+import (
+	"context"
+
+	"ycc-server/app/main/model"
+	"ycc-server/common/xerr"
+
+	"github.com/pkg/errors"
+
+	"ycc-server/app/main/api/internal/svc"
+	"ycc-server/app/main/api/internal/types"
+
+	"github.com/zeromicro/go-zero/core/logx"
+)
+
+type AdminDowngradeAgentLogic struct {
+	logx.Logger
+	ctx    context.Context
+	svcCtx *svc.ServiceContext
+}
+
+func NewAdminDowngradeAgentLogic(ctx context.Context, svcCtx *svc.ServiceContext) *AdminDowngradeAgentLogic {
+	return &AdminDowngradeAgentLogic{
+		Logger: logx.WithContext(ctx),
+		ctx:    ctx,
+		svcCtx: svcCtx,
+	}
+}
+
+func (l *AdminDowngradeAgentLogic) AdminDowngradeAgent(req *types.AdminDowngradeAgentReq) (resp *types.AdminDowngradeAgentResp, err error) {
+	if req.AgentId == "" {
+		return nil, errors.Wrapf(xerr.NewErrMsg("代理ID不能为空"), "")
+	}
+
+	_, err = l.svcCtx.AgentModel.FindOne(l.ctx, req.AgentId)
+	if err != nil {
+		if errors.Is(err, model.ErrNotFound) {
+			return nil, errors.Wrapf(xerr.NewErrMsg("代理不存在"), "")
+		}
+		return nil, errors.Wrapf(xerr.NewErrCode(xerr.DB_ERROR), "查询代理失败, %v", err)
+	}
+
+	if err := l.svcCtx.AgentService.ProcessDowngrade(l.ctx, req.AgentId, req.ToLevel, req.Remark); err != nil {
+		return nil, errors.Wrapf(xerr.NewErrMsg(err.Error()), "")
+	}
+
+	return &types.AdminDowngradeAgentResp{
+		Success: true,
+	}, nil
+}

app/main/api/internal/service/agentService.go

@@ -876,6 +876,102 @@ func (s *AgentService) ProcessUpgrade(ctx context.Context, agentId string, toLev
 	})
 }
 
+// UpgradeTypeAdminDowngrade 管理端降级
+const UpgradeTypeAdminDowngrade int64 = 4
+
+// ProcessDowngrade 管理端代理降级（仅降低等级，不退款、不收回历史返佣）
+func (s *AgentService) ProcessDowngrade(ctx context.Context, agentId string, toLevel int64, remark string) error {
+	return s.AgentWalletModel.Trans(ctx, func(transCtx context.Context, session sqlx.Session) error {
+		agent, err := s.AgentModel.FindOne(transCtx, agentId)
+		if err != nil {
+			if errors.Is(err, model.ErrNotFound) {
+				return errors.New("代理不存在")
+			}
+			return errors.Wrapf(err, "查询代理失败")
+		}
+
+		fromLevel := agent.Level
+		if fromLevel == 3 {
+			return errors.New("钻石代理不允许降级")
+		}
+		if fromLevel == 1 {
+			return errors.New("普通代理无法降级")
+		}
+		if fromLevel != 2 || toLevel != 1 {
+			return errors.New("仅支持将黄金代理降级为普通代理")
+		}
+
+		if err := s.validateDowngradeDirectChildren(transCtx, agentId, toLevel); err != nil {
+			return err
+		}
+
+		if remark == "" {
+			remark = "管理端降级"
+		}
+
+		upgradeRecord := &model.AgentUpgrade{
+			Id:          uuid.NewString(),
+			AgentId:     agent.Id,
+			FromLevel:   fromLevel,
+			ToLevel:     toLevel,
+			UpgradeType: UpgradeTypeAdminDowngrade,
+			UpgradeFee:  0,
+			Status:      2, // 已完成
+			Remark:      lzUtils.StringToNullString(remark),
+		}
+		if _, err := s.AgentUpgradeModel.Insert(transCtx, session, upgradeRecord); err != nil {
+			return errors.Wrapf(err, "创建降级记录失败")
+		}
+
+		agent.Level = toLevel
+
+		teamLeaderId, err := s.findTeamLeaderId(transCtx, agentId)
+		if err != nil && !errors.Is(err, model.ErrNotFound) {
+			return errors.Wrapf(err, "查找团队首领失败")
+		}
+		if teamLeaderId != "" {
+			agent.TeamLeaderId = sql.NullString{String: teamLeaderId, Valid: true}
+		} else {
+			agent.TeamLeaderId = sql.NullString{Valid: false}
+		}
+
+		if err := s.AgentModel.UpdateWithVersion(transCtx, session, agent); err != nil {
+			return errors.Wrapf(err, "更新代理等级失败")
+		}
+
+		return nil
+	})
+}
+
+// validateDowngradeDirectChildren 校验直接下级是否允许上级降到 toLevel
+func (s *AgentService) validateDowngradeDirectChildren(ctx context.Context, agentId string, toLevel int64) error {
+	builder := s.AgentRelationModel.SelectBuilder().
+		Where("parent_id = ? AND relation_type = ? AND del_state = ?", agentId, 1, globalkey.DelStateNo)
+	relations, err := s.AgentRelationModel.FindAll(ctx, builder, "")
+	if err != nil {
+		return errors.Wrapf(err, "查询直接下级失败")
+	}
+
+	for _, relation := range relations {
+		child, err := s.AgentModel.FindOne(ctx, relation.ChildId)
+		if err != nil {
+			if errors.Is(err, model.ErrNotFound) {
+				continue
+			}
+			return errors.Wrapf(err, "查询下级代理失败")
+		}
+
+		if child.Level > toLevel {
+			return fmt.Errorf("存在等级高于目标等级的直接下级（下级ID: %s），无法降级", child.Id)
+		}
+		if child.Level == toLevel && toLevel >= 2 {
+			return fmt.Errorf("存在与目标等级相同的黄金/钻石直接下级（下级ID: %s），无法降级", child.Id)
+		}
+	}
+
+	return nil
+}
+
 // needDetachFromParent 检查是否需要脱离直接上级关系
 func (s *AgentService) needDetachFromParent(ctx context.Context, agent *model.Agent, newLevel int64) (bool, error) {
 	parent, err := s.findDirectParent(ctx, agent.Id)

app/main/api/internal/types/types.go

@@ -230,6 +230,16 @@ type AdminDeleteUserResp struct {
 	Success bool `json:"success"` // 是否成功
 }
 
+type AdminDowngradeAgentReq struct {
+	AgentId string `json:"agent_id"`        // 代理ID
+	ToLevel int64  `json:"to_level"`        // 目标等级：1=普通，2=黄金，3=钻石（须低于当前等级）
+	Remark  string `json:"remark,optional"` // 备注（可选）
+}
+
+type AdminDowngradeAgentResp struct {
+	Success bool `json:"success"`
+}
+
 type AdminGenerateDiamondInviteCodeReq struct {
 	Count      int64  `json:"count"`                // 生成数量
 	ExpireDays int64  `json:"expire_days,optional"` // 过期天数（可选，0表示不过期）
@@ -870,6 +880,15 @@ type AdminUpdateAgentConfigResp struct {
 	Success bool `json:"success"`
 }
 
+type AdminUpdateAgentMobileReq struct {
+	AgentId string `json:"agent_id"` // 代理ID
+	Mobile  string `json:"mobile"`   // 新手机号
+}
+
+type AdminUpdateAgentMobileResp struct {
+	Success bool `json:"success"`
+}
+
 type AdminUpdateAgentProductConfigReq struct {
 	Id             string   `json:"id"`                       // 主键
 	BasePrice      float64  `json:"base_price"`               // 基础底价
@@ -882,16 +901,6 @@ type AdminUpdateAgentProductConfigResp struct {
 	Success bool `json:"success"`
 }
 
-// 代理手机号修改
-type AdminUpdateAgentMobileReq struct {
-	AgentId string `json:"agent_id"` // 代理ID
-	Mobile  string `json:"mobile"`   // 新手机号
-}
-
-type AdminUpdateAgentMobileResp struct {
-	Success bool `json:"success"`
-}
-
 type AdminUpdateApiReq struct {
 	Id          string `path:"id"`
 	ApiName     string `json:"api_name"`

docs/memo-agent-refund-commission-clawback.md

@@ -0,0 +1,109 @@
+# 备忘录：代理退款扣回佣金/冻结优化（策略 2 + 策略 5 改版）
+
+> 状态：**待实施**  
+> 目的：后续改造 `CancelAgentCommission` 及后台/回调退款链路时，按本文规则实现，避免共享冻结池误扣、部分退款与扣佣口径不一致。
+
+---
+
+## 一、策略 2：按「本笔佣金」扣款，先冻结、再余额
+
+### 1.1 问题（现状）
+
+- 撤销时使用钱包级「先扣总 `FrozenBalance`、再扣 `Balance`」，可能动到**其他订单**的冻结。
+- 解冻任务与提现占用冻结混在同一字段时，易出现对账失败、负冻结等。
+
+### 1.2 目标行为（实施后）
+
+对**单笔订单**下、待冲回的那笔**直推佣金**（`agent_commission`，且状态为已发放、未被整笔撤销）：
+
+1. **若该笔佣金存在仍有效的冻结任务**（与 `commission_id` 关联、`agent_freeze_task.status == 1` 待解冻）：
+   - 先从**该任务对应的冻结金额**（`FreezeAmount`，且只从**本笔佣金归属的冻结额度**扣，见下文物理解耦建议）中扣减，**最多扣 `FreezeAmount`**；
+   - **剩余冲回金额** = 本次要对这笔佣金冲回的总金额 − 已从冻结部分扣掉的部分，**全部从 `Balance`（可用余额）扣**。
+2. **若该笔佣金没有有效冻结任务**（无任务或未达冻结门槛等）：
+   - **本次冲回金额全部从 `Balance` 扣**。
+3. **禁止**再用「整钱包 `FrozenBalance` 池先垫满再扣余额」的方式处理**单笔**佣金冲回（除非产品明确采用单字段且不拆分，也应在文档中标记为技术债）。
+
+### 1.3 工程建议（与策略 2 配套）
+
+- **优先**：将「佣金冻结」与「占用的提现冻结」分字段或子账（如 `commission_frozen` / `withdrawal_frozen`），冲回、到期解冻只动佣金侧。
+- **至少**：冲回前按 `commission_id` + 任务锁定本单冻结份额；扣款顺序仅在本份额与 `Balance` 之间分配，不侵占其他 `agent_freeze_task` 对应额度。
+
+### 1.4 部分冲回后的冻结任务（需定义）
+
+- 若本次只冲回部分金额：是否**调减** `agent_freeze_task.FreezeAmount`、或拆任务、或标记「已部分冲回」，需在开发时定表结构和状态机，避免到期解冻仍按原 `FreezeAmount` 全额解冻。
+
+---
+
+## 二、策略 5 改版：部分退款 **不按比例**，而是 **「退多少扣多少」，且封顶佣金**
+
+### 2.1 规则（用户指定）
+
+- **不按**「退款金额 / 订单金额 × 佣金」这类比例。
+- 设：
+  - `R` = **本笔后台/回调确认的本次退款金额**（元）；
+  - `C_direct` = 代理在该订单上**当前仍有效的直推佣金**可冲回上限（已发放未撤销的 `agent_commission.amount`，或按「剩余未冲回」口径若支持多次退款累计，见 2.3）；
+  - （返佣侧见 2.4）`C_rebate_i` = 各条 `agent_rebate` 可冲回上限。
+
+则 **对直推佣金** 本次应冲回金额：
+
+```text
+ claw_direct = min(R, C_direct)
+```
+
+**示例**：
+
+- 订单 100 元，本次退款 50 → **`claw_direct = min(50, C_direct)`**；若 `C_direct = 80`，则冲 **50**（不是 50%×80）。
+- 订单 100 元，本次退款 95，`C_direct = 80` → **`claw_direct = min(95, 80) = 80`**（封顶佣金）。
+
+### 2.2 与策略 2 的结合
+
+对计算出的 `claw_direct`：
+
+- 再按**第一节**拆成：有冻结任务则先扣满该任务可承担的冻结份额，余下从 `Balance`；无冻结则全部从 `Balance`。
+
+### 2.3 多次退款（累计）
+
+- 若同一订单可**多次退款**：需约定 `C_direct` 是「原始佣金」还是「剩余可冲回」。
+- **建议**：维护「本单已冲回佣金累计」或等价地更新 `agent_commission` 剩余金额/子状态，使每次：
+
+```text
+ claw_direct = min(R, max(0, C_direct - 已累计已冲回))
+```
+
+具体字段是否新增 `revoked_amount`、是否只依赖多条 `order_refund` 汇总，实施时定案。
+
+### 2.4 返佣（`agent_rebate`）
+
+- 用户口头规则主要针对「佣金」；**返佣是否沿用同一公式**需在实施前产品拍板：
+  - **方案 A**：对每条返佣单独 `claw_rebate_i = min(R, cap_i)`，且注意 `R` 与直推已分摊是否重复扣（通常应 **`R` 全局一次，再在直推与多条返佣间分配**，否则 `min(R,C)` 对多受益方会超标）。
+  - **方案 B**：`R` 先在直推与返佣链上按约定顺序分配（例如先扣直推至封顶，再扣上级返佣至各自封顶），总额不超过 `R` 且各方不超过各自佣金上限。
+
+**备忘录约束**：实施前必须写清 **「一笔退款 R 在直推与多返佣之间的分配顺序与上限」**，避免多扣或少扣。
+
+### 2.5 调用链改造要点
+
+- `CancelAgentCommission` 需接收 **`refund_amount`（或累计上下文）**，不能只传 `order_id` 默认全额冲回。
+- 后台 `AdminRefundOrder`、微信退款成功回调等，在退款成功后调用冲回逻辑时传入**本次** `R`。
+- 支付宝/微信**全额**退款：若 `R >=` 订单剩余实付等，则直推/返佣可按封顶一次性冲完（与现有「整单撤销」行为对齐时，等价于 `claw = min(R, C)` 且 `R` 足够大）。
+
+---
+
+## 三、实施检查清单（供开发自用）
+
+- [ ] `giveAgentCommission` / 冻结任务与钱包字段是否需调整以支持「只扣本笔冻结份额」。
+- [ ] `deductCommissionFromWallet` 重写：入参含 `claw_amount` + `freeze_task` + 分桶或任务份额。
+- [ ] 返佣 `deductRebateFromWallet`：是否按 `min(R_remaining, rebate_cap)` 及分配顺序。
+- [ ] 部分冲回后 `agent_commission.status`：仍为已发放 / 部分撤销 / 新状态；与统计、列表过滤一致。
+- [ ] 多次退款与 `order_refund` 记录一一对应，冲回幂等与审计日志。
+- [ ] 提现、定时解冻与冲回共用冻结时的边界用例（负冻结防护）。
+
+---
+
+## 四、参考现状代码（实施时对照）
+
+- 冲回入口：`AgentService.CancelAgentCommission`、`deductCommissionFromWallet`、`deductRebateFromWallet`
+- 退款后调用：`admin_order/adminrefundorderlogic.go`、`pay/wechatpayrefundcallbacklogic.go` 等
+
+---
+
+*文档版本：初稿（按对话需求整理），实施时可增删小节并与产品确认返佣分配。*