代理资格售卖插件 (AgentVIP)

📖 插件介绍

AgentVIP 是一款虚拟产品插件，允许将「代理资格」作为商品进行售卖。用户购买后，系统自动为其开通代理身份，无需人工审核。

核心功能

• ✅ 自动开通代理身份（修改用户 agent_id）
• ✅ 支持多种返佣模式（按比例/固定金额/不返佣）
• ✅ 续费时可配置是否再次返佣
• ✅ 支持代理组升降级
• ✅ 完全自动化，无需人工干预

🚀 安装方法

1. 上传插件

将插件文件夹 agentvip 上传至：

public/plugins/host/agentvip/

2. 创建代理组（如尚未创建）

后台路径：用户管理 → 代理分组 → 添加

创建至少一个代理组，例如：

• 金牌代理（折扣 20%）
• 银牌代理（折扣 15%）
• 普通代理（折扣 10%）

3. 配置商品

后台路径：产品设置 → 产品管理 → 添加商品

⚙️ 配置选项详解

代理组

从 sib_user_agent 表中读取所有代理组，选择用户购买后将被赋予的代理组。

返佣模式

返佣比例

• 当返佣模式为"按比例"时生效
• 示例：填 10 表示返还订单金额的 10%
• 订单金额 100 元 → 返 10 元

固定返佣金额

• 当返佣模式为"固定金额"时生效
• 示例：填 20 表示固定返 20 元
• 无论订单金额多少，都返 20 元

续费返佣

• 续费不返佣：仅首次购买返佣（推荐）
• 续费也返佣：每次续费都按配置返佣

📖 使用教程

场景一：开通代理资格

1. 用户购买
      - 用户在前台购买代理资格商品
      - 支付完成后系统自动处理
2. 系统自动处理
      `
      支付成功
          ↓
      调用 CreateAccount
          ↓
      ① 修改 user.agent_id = 配置的代理组ID
      ② 根据配置计算返佣金额
      ③ 返佣金额添加到用户余额（如配置）
      ④ 记录开通时间到 host_meta
          ↓
      返回成功：代理开通成功，返佣XX元已到账
      `
3. 用户成为代理
      - 用户立即获得代理身份
      - 购买其他商品时自动享受代理折扣
      - 可在会员中心查看代理状态

场景二：代理资格续费

1. 用户在产品详情页点击「续费」
2. 支付成功后根据配置决定是否返佣
3. 代理身份继续保持

场景三：代理组升降级

1. 管理员创建新的代理资格商品（不同代理组）
2. 用户购买后系统自动切换代理组
3. 享受新代理组的折扣权益

场景四：暂停/恢复代理

• 暂停：管理员在后台暂停业务，user.agent_id 设为 0，用户暂时失去代理权限
• 恢复：解除暂停后，user.agent_id 恢复为配置的代理组ID
• 终止：删除业务，user.agent_id 设为 0，永久取消代理权限

🎨 前台展示

代理状态页面

用户可在产品详情页查看：

• 当前代理组
• 代理状态（生效/暂停）
• 代理权益说明

样式完全独立，不依赖主题，切换主题后显示正常。

🔧 技术说明

数据表操作

返佣计算逻辑

// 按比例返佣
$rebateMoney = $orderAmount * ($rebateRate / 100);


// 固定金额返佣
$rebateMoney = $rebateAmount;


// 使用 User::money() 方法添加到余额
User::money($rebateMoney, $userId, $memo);

插件钩子

❓ 常见问题

Q1: 用户购买后没有返佣？

排查步骤：

1. 检查返佣模式是否设置为"不返佣"
2. 检查返佣比例/金额是否为 0
3. 查看日志文件 runtime/log/ 中的 [AgentVip] 日志
4. 确认订单已支付成功

Q2: 用户已经是代理，购买新的代理资格会怎样？

答： 用户的 agent_id 会被更新为新商品配置的代理组ID，享受新代理组的折扣。

Q3: 可以限制每人只能购买一次吗？

答： 在商品配置中设置「单账号最大订购量」为 1 即可。

Q4: 返佣是返给购买者还是推荐人？

答： 返给购买者自己。如需返给推荐人，需要额外开发。

Q5: 代理资格到期后会怎样？

答： 到期后代理身份会被暂停（agent_id 设为 0），续费后可恢复。

Q6: 如何查看返佣记录？

答： 在后台 会员管理 → 余额日志 中查看，备注包含「开通代理资格返佣」。

📝 更新日志

v1.0.0 (2026-02-24)

• ✅ 初始版本发布
• ✅ 支持自动开通代理
• ✅ 支持多种返佣模式
• ✅ 支持续费返佣配置
• ✅ 独立样式模板

💡 最佳实践

1. 代理组设计建议

金牌代理 - 月付 99 元 - 折扣 30% - 返佣 20%
银牌代理 - 月付 49 元 - 折扣 20% - 返佣 15%  
普通代理 - 月付 19 元 - 折扣 10% - 返佣 10%

2. 促销活动建议

• 拉新活动：设置固定返佣 30 元，吸引新用户
• 充值激励：按比例返佣，鼓励用户大额充值
• 限时免费：设置返佣 100%，相当于首月免费

3. 代理权益设置

在 用户管理 → 分组折扣 中设置：

• 客户组：选择代理组
• 商品组：选择适用折扣的商品
• 折扣类型：比例/固定金额/优惠

📞 技术支持

如有问题，请联系技术支持或查看系统日志。

日志位置： runtime/log/  
日志标识： [AgentVip]

© 2026 AgentVIP Plugin - 让代理管理更简单