From fc9d7983b76793e8101515e5464510e43d6f678b Mon Sep 17 00:00:00 2001 From: liangzai <2440983361@qq.com> Date: Tue, 19 May 2026 20:30:32 +0800 Subject: [PATCH] f --- app/main/api/desc/admin/admin_agent.api | 13 +++ .../admin_agent/admindowngradeagenthandler.go | 29 +++++ app/main/api/internal/handler/routes.go | 15 ++- .../admin_agent/admindowngradeagentlogic.go | 51 ++++++++ app/main/api/internal/service/agentService.go | 96 +++++++++++++++ app/main/api/internal/types/types.go | 29 +++-- docs/memo-agent-refund-commission-clawback.md | 109 ++++++++++++++++++ 7 files changed, 327 insertions(+), 15 deletions(-) create mode 100644 app/main/api/internal/handler/admin_agent/admindowngradeagenthandler.go create mode 100644 app/main/api/internal/logic/admin_agent/admindowngradeagentlogic.go create mode 100644 docs/memo-agent-refund-commission-clawback.md diff --git a/app/main/api/desc/admin/admin_agent.api b/app/main/api/desc/admin/admin_agent.api index 5550f04..bf856da 100644 --- a/app/main/api/desc/admin/admin_agent.api +++ b/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"` + } ) diff --git a/app/main/api/internal/handler/admin_agent/admindowngradeagenthandler.go b/app/main/api/internal/handler/admin_agent/admindowngradeagenthandler.go new file mode 100644 index 0000000..825107e --- /dev/null +++ b/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) + } +} diff --git a/app/main/api/internal/handler/routes.go b/app/main/api/internal/handler/routes.go index 3301740..62b533c 100644 --- a/app/main/api/internal/handler/routes.go +++ b/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", diff --git a/app/main/api/internal/logic/admin_agent/admindowngradeagentlogic.go b/app/main/api/internal/logic/admin_agent/admindowngradeagentlogic.go new file mode 100644 index 0000000..c0e782e --- /dev/null +++ b/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 +} diff --git a/app/main/api/internal/service/agentService.go b/app/main/api/internal/service/agentService.go index 9fa5b77..9dd82c1 100644 --- a/app/main/api/internal/service/agentService.go +++ b/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) diff --git a/app/main/api/internal/types/types.go b/app/main/api/internal/types/types.go index f62f93e..362b326 100644 --- a/app/main/api/internal/types/types.go +++ b/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"` diff --git a/docs/memo-agent-refund-commission-clawback.md b/docs/memo-agent-refund-commission-clawback.md new file mode 100644 index 0000000..9b4a4a1 --- /dev/null +++ b/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` 等 + +--- + +*文档版本：初稿（按对话需求整理），实施时可增删小节并与产品确认返佣分配。*