推广体系 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
返回当前总代理自己的团队订单归因明细。