【社区代理推荐推广（劳务费）模块 PRD】

核心约定： 社区代理 3980 终身席位；成功推荐成交 1 位社区代理，平台发放劳务费 900 元（业务名称统一叫劳务费，不叫佣金，用于线下推广劳务补贴） 载体：专属推荐码 + 专属推荐海报链接，代理在 APP 内获取，分享给意向人；意向人通过该码 / 链接下单开通社区代理，自动归属推荐人，满足条件后发放劳务费 角色：城主、社区代理都拥有推荐码、推荐海报分享能力，都可以拿这份 900 劳务费；城主额外还有区域管理分润（两套独立体系，互不干扰） 前置依赖：用户表、社区代理订单表、钱包 / 资金流水表、社区代理权益表、城主表

业务边界： ✅ 只有【社区代理开通订单】才触发 900 劳务费 ✅ 城主招募社区代理的区域管理分润，单独一套逻辑，不在这个模块里实现 ✅ 劳务费是平台发放的推广劳务补贴，不是商品交易抽成 ✅ 支持分享：海报 H5 链接、带推荐码的落地页、复制推荐码 ✅ 防刷单、风控、结算状态、申诉流程全部内置

1、业务流程

1. 已开通社区代理 / 城主，登录 APP → 【我的推广】页面
2. 系统自动生成该用户唯一推荐码（短码，6 位数字 + 字母）、带推荐码的 H5 落地页链接、专属推广海报
3. 代理选择：复制链接 / 复制推荐码 / 保存海报，发给意向客户
4. 意向客户点开链接 / 扫码海报，落地页自动带上 invite_code=xxx；也可以手动录入推荐码
5. 意向客户在落地页提交社区代理 3980 订单、支付成功
6. 订单校验：校验推荐码有效、推荐人是已激活【社区代理 / 城主】、被推荐人之前没有社区代理资格、非同一用户、不在黑名单
7. 订单支付成功 → 生成劳务费待结算记录（状态：待结算）
8. 结算规则（后台可配置）：
   • 方案 A（推荐，稳妥）：T+N 结算，例如：订单支付成功，7 天冷静期无退款、无投诉，自动结算劳务费 900 到推荐人钱包
   • 方案 B：即时结算（后台开关控制，不建议默认开启）
   • 一旦订单退款、取消、判定刷单，劳务费直接作废，不发放，已发放的支持追回
9. 推荐人在【我的推广】可以看到：推荐记录、待结算劳务费、已结算劳务费、作废记录、流水明细
10. 钱包里的劳务费，和拓客佣金、门店分润共用同一套提现逻辑

2、页面清单（APP 端）

页面 1：我的推广（入口放在【我的】里面，仅城主 / 社区代理可见；普通用户看不到入口）

顶部：

• 我的推荐码：XXXXXX 【一键复制】
• 我的推广链接：https://xxx.com/agent?invite_code=XXXXXX【一键复制】
• 按钮：【生成推广海报】（生成带推荐码、二维码的分享海报） 统计卡片：
• 累计推荐人数：xx
• 待结算劳务费：¥xx
• 已结算劳务费：¥xx 标签页切换：【推广数据】【推荐记录】【我的收益流水】

推荐记录列表字段： 被推荐人昵称 / 手机号（脱敏）、下单时间、订单号、应付金额 3980、劳务费 900、状态（待结算 / 已结算 / 已退款作废 / 风控驳回）

页面 2：社区代理招募落地 H5（带推荐码参数）

参数：invite_code 逻辑：

1. 打开链接自动读取 invite_code，校验推荐码是否存在、推荐人是否有效（是城主 / 社区代理，状态正常、未封禁）
2. 校验通过：页面顶部小字提示【推荐人：XXX】（脱敏展示）
3. 校验失败（推荐码不存在、推荐人失效）：提示推荐码无效，可继续下单，但不产生劳务费
4. 页面内容：社区代理 3980 权益、可转让、平台兜底回购、全套 AI 工具、门店流水分润、推荐别人拿 900 劳务费
5. 下单按钮 → 跳转下单支付页面，下单时绑定 invite_code 存入订单

页面 3：后台管理页（运营后台）

1. 推广记录总表：全部推荐订单、推荐人、被推荐人、推荐码、劳务费金额、状态、创建时间、结算时间
2. 劳务费结算管理：支持手动审核、批量结算、驳回、备注原因
3. 推荐码管理：查看用户推荐码、冻结推荐码（违规时）
4. 风控黑名单：用户 ID 黑名单，黑名单用户不能拿劳务费、不能被推荐
5. 配置项：劳务费金额（默认 900，后台可改）、冷静期天数、是否开启自动结算开关
6. 流水导出：劳务费流水导出 Excel

3、数据库表设计（新增表，原有 user、wallet、agent_order 复用）

说明： agent_order：社区代理订单表（已有，3980 订单） user_wallet：用户钱包（已有） user_wallet_log：钱包流水（已有，增加 type 类型）

表 1：user_invite_code 推荐码主表

表格

字段	类型	说明
id	bigint	主键
user_id	bigint	推荐人 ID（城主 / 社区代理），唯一，一个用户一条
invite_code	varchar(16)	6 位推荐短码，唯一索引
qrcode_url	varchar	生成海报二维码地址
status	tinyint	状态：1 正常 0 冻结
create_time	datetime	创建时间
update_time	datetime	更新时间

约束：一个用户只生成一条推荐码，永久不变；冻结后，新订单不再产生劳务费，历史订单按原有规则结算