推广体系 API

本文档描述 promo 模块的后台接口。这些接口均需要管理员鉴权。

后台接口

推广概览

接口地址: GET /api/admin/promo/overview

返回推广总览指标、最近代理、最近归因订单与最近收益流水。

响应示例:

{
  "overview": {
    "members": 12,
    "agents": 4,
    "masterAgents": 1,
    "commissionAmount": 128.5,
    "attributedOrders": 20
  },
  "agents": [],
  "attributions": [],
  "commissions": []
}

推广配置

接口地址: GET /api/admin/promo/settings

返回已保存的推广配置。

响应示例:

{
  "promo_invite_reward_amount": "10"
}

接口地址: POST /api/admin/promo/settings

请求体示例:

{
  "promo_invite_reward_amount": "10"
}

代理等级

接口地址: GET /api/admin/promo/tiers

返回全部代理等级配置。

接口地址: POST /api/admin/promo/tiers

用于新增或更新代理等级。

请求体示例:

{
  "code": "master-default",
  "name": "总代理",
  "roleScope": "master_agent",
  "level": 100,
  "discountRate": 0.8,
  "salesThreshold": 0,
  "isFixed": true,
  "isActive": true,
  "description": "总代理固定折扣"
}

代理成员

接口地址: GET /api/admin/promo/agents?page=1&pageSize=15

返回分页的代理与总代理成员列表。

接口地址: POST /api/admin/promo/agents

按邮箱把现有用户设置为 master_agent 或 agent。

请求体示例:

{
  "email": "agent@example.com",
  "role": "agent",
  "parentAgentUserId": 12
}

代理关系

接口地址: GET /api/admin/promo/relations

返回当前代理层级关系记录,包括直属上级与总代理绑定信息。

接口地址: PUT /api/admin/promo/relations/:id

更新现有子代理关系的所属总代理。

请求体示例:

{
  "parentAgentUserId": 12
}

接口地址: DELETE /api/admin/promo/relations/:id

禁用该代理关系,并把成员降级为普通会员。若该成员仍是带有下级的总代理,则禁止解绑。

收益流水

接口地址: GET /api/admin/promo/commissions?page=1&pageSize=15

返回分页的推广收益流水列表。

用户接口

推广概览

接口地址: GET /api/users/promo/overview

返回当前用户的推荐概览、专属链接、推广码,以及 isAgent / isMasterAgent 等代理身份标记。 当用户首次访问该接口时,后端会按需自动创建 promo member 记录,并生成邀请相关编码与邀请链接。 若用户通过总代理 agent 链接注册,系统会先创建一条 promo_agent_relations.status = pending 的待审核关系;只有总代理通过后,才会进入正式团队统计。

邀请记录

接口地址: GET /api/users/promo/invites

返回当前用户发起的邀请记录。

团队成员

接口地址: GET /api/users/promo/team

返回当前用户可见的正式子代理团队记录,仅包含 status = active 的成员。

待审核代理

接口地址: GET /api/users/promo/pending

返回当前总代理名下待审核的代理申请列表,仅包含 status = pending 的记录。

接口地址: POST /api/users/promo/pending/:id

用于总代理审核待加入代理申请。

请求体示例:

{
  "action": "approve"
}

action 支持:

  • approve:通过申请,并把该成员转为正式子代理
  • reject:拒绝申请,并把该待审核关系置为 disabled

收益明细

接口地址: GET /api/users/promo/commissions

返回当前用户拥有的推广收益流水。

团队报表

接口地址: GET /api/admin/promo/team-report?masterAgentUserId=12

返回指定总代理视角下的团队汇总与直属子代理销售报表。

接口地址: GET /api/users/promo/team-report

返回当前总代理自己的团队汇总与直属子代理销售报表。

团队订单明细

接口地址: GET /api/admin/promo/team-orders?masterAgentUserId=12

返回指定总代理视角下的团队订单归因明细。

接口地址: GET /api/users/promo/team-orders

返回当前总代理自己的团队订单归因明细。