推荐与返利

推荐与返利是一套跨业务域的统一能力。启用后，符合资格的成员可以在会员计划、付费内容、实物商品、数字商品、活动和积分补充的详情页直接分享；后台使用同一套归因、裁决、风险、核销和结现账本。

谁可以使用

成员身份	默认比例	详情页分享现金返利
普通用户、月度会员	0%	不开放；仍可使用普通邀请
有效年度会员	20%	开放
创始会员	30%	开放
后台单独确认的伙伴	后台配置	按确认状态和范围执行

后台可以暂停资格、调整比例或限制可推荐分类。规则变化只影响之后形成的归因；已经发生的交易继续使用当时保存的规则快照，不会因为运营改价而改写历史账目。

成员怎么使用

1. 登录后直接打开想推荐的会员计划、内容、实物、数字商品或活动详情页。
2. 点击“分享”后，系统自动取得专属短链接并放入分享卡、复制链接和二维码，不需要先去专门页面创建。
3. 同一成员对同一对象永远只有一条链接；第二次、第三次分享都会复用原来的短码，不会因为入口、渠道、票种或商品档位不同生成多条。
4. /referrals 用于查看可推荐目录、点击、独立访客、有效转化与返利状态，也可以从目录返回对象详情页继续分享。
5. 所有返利先经过退款观察期，观察期结束后才允许人工核销；核销通过后进入可结现状态。实际转账由运营人员线下完成，再用真实付款流水号在后台确认。

数据库使用“伙伴 + 对象类型 + 对象 ID”唯一约束保证链接复用。一个实物商品链接覆盖它的 SKU，一个数字商品链接覆盖当前大版本与终身更新，一个活动链接覆盖它的付费票种；最终选用的档位记录在交易事实中，不改变分享短码。

链接访问会写入短期、签名的归因 Cookie，并按访问当时有效的资格和比例冻结规则快照。归因只在有效期内使用一次，创建交易后即绑定到该交易号；复制 Cookie、重复回调或重复确认支付不会生成第二份奖励。

同一笔订阅不会发两份奖励

订阅同时存在“邀请关系”和“现金返利”两类激励，因此使用固定优先级：

1. 先检查注册时形成的永久邀请关系。
2. 如果邀请人当前是有效年度会员、创始会员或已启用伙伴，则该订单进入现金返利，邀请积分不发放。
3. 如果邀请人不具备现金返利资格，则按原邀请规则发放积分，现金返利不生成。
4. 没有永久邀请关系时，才使用本次推荐链接归因。
5. 自己推荐自己、零元开通、兑换码开通、管理员发放、导入或测试交易均记为“无奖励”。

数据库以“交易类型 + 交易 ID”作为唯一奖励事实。奖励通道只能是现金返利、邀请积分或无奖励之一；服务重复收到支付回调时返回同一结果，不会再次记账。

账户合并也不能绕过这条限制：只要两个账号分别出现在同一奖励事实的推荐方和开通方，系统就会中止自动合并并要求人工财务复核；数据库还会拒绝任何合并后形成的自我推荐记录。

折扣、兑换、积分与退款

• 折扣码可以和推荐链接同时使用，但返利只按折扣后的实际现金金额计算。
• 实物商品不把运费计入返利；购物车只计算链接所指向商品的净收入。
• 兑换码产生的零元订单不返利。
• 积分充值可以返利；之后再用这些积分兑换内容、活动或商品时不重复返利。
• 免费活动、管理员赠送、导入权益和测试订单不返利。
• 观察期内退款会直接减少或撤销返利。管理员不能提前核销、不能用人工操作跳过观察期；返利已进入待结现批次时，批次同步按净额重算。
• 已完成结现后退款会形成“待追偿”明细。后续结现按时间顺序抵扣，每次抵扣都关联具体退款调整和结现批次；一笔追偿可以分批抵扣，但累计不会超过原追偿金额。

后台怎么管理

后台“推荐与返利”包含七个区域：

区域	用途
总览	查看伙伴、链接、点击、风险和各奖励通道数量
伙伴与比例	启用、暂停资格，查看默认与实际比例
规则	按业务分类配置年度/创始比例、归因期、观察期和人工核销
链接与点击	按推荐对象与业务分类查看唯一链接、点击、独立访客和有效转化
交易裁决	查看每笔交易最终命中的唯一奖励通道和原因
人工核销	结合风险、净收入和观察期通过、拒绝或继续复核
结现	选择同一伙伴的可结现明细，生成批次、取消未付款批次或登记真实付款流水

创建结现批次时必须携带幂等键，同一个键不能换伙伴或换明细再次提交；一条返利同一时间只能进入一个有效批次。尚未付款的批次可以取消，取消后明细原子退回可结现状态。伙伴被暂停或关闭后不能创建新批次。

已确认结现的批次和付款流水不可覆盖，同一个付款流水号也不能登记到两个批次。需要纠错时应新增审计记录或退款调整，不要直接修改历史金额。

防止套利的运营检查

系统会自动拦截确定性问题，但人工核销仍应检查：

• 推荐人与开通人是否为同一账号。
• 推荐人与开通人是否来自准备合并的两个账号；存在这种交叉关系时不要直接合并账号。
• 点击 IP、设备和访问节奏是否异常集中。
• 大量新账号是否在短时间内使用同一付款来源或相似身份信息。
• 订单是否使用大额折扣、随后快速退款，或反复创建、取消。
• 伙伴比例和适用范围是否在交易发生时有效。
• 待结现明细金额是否与退款后的净收入一致。

不要只根据点击量自动结现。建议生产环境默认保留人工核销，并让观察期覆盖主要商品的无理由退款窗口。

从早期版本升级时，活动或小铺中已有的推荐历史继续保留查询；新分享统一进入当前推荐账本。一个交易请求不能同时携带两套推荐归因，服务端会直接拒绝这种叠加请求。

启用与生产配置

在 config/community-template.json 中启用：

{
  "modules": {
    "subscriptions": true,
    "referrals": true
  }
}

在未提交的 .env 或部署平台 Secret 中设置独立签名密钥：

SPACE_REFERRAL_TOKEN_SECRET=使用独立的高熵随机值且不少于32位

首次部署和升级都先运行：

pnpm ops:template:preflight

不要与邀请、早期版本的活动/小铺推荐或下载地址共用签名密钥。轮换密钥会让尚未转换的旧推荐 Cookie 失效，应选择低峰期并提前告知伙伴；已经记入账本的奖励不会受影响。

二次开发注意事项

新增可交易对象时，必须同时补齐以下内容：

1. 在统一 contract 中声明对象类型与交易类型。
2. 把详情页分享接入统一的 getOrCreate 链路，并证明同一成员与对象只能返回一条永久链接；不要按渠道或档位另建链接。
3. 在创建交易时一次性占用归因，并固定对象、成交档位和可返利净额。
4. 在真实支付确认后写入唯一奖励事实；兑换、赠送和测试路径写入明确的无奖励原因。
5. 在退款完成后传入累计退款金额，不要按单次退款重复减同一笔返利。
6. 业务中若仍有旧版推荐参数，contract 必须拒绝它与统一推荐 token 同时出现。
7. 同步用户中心目录、后台筛选、模块路由、Mock、真实 PostgreSQL 集成测试与本文档。

AI 协作开发时，应先阅读仓库根目录 AGENTS.md、AI 二次开发和本页。不要为新商品复制一套平行返利表，也不要只在前端隐藏重复链接或奖励；唯一性与互斥必须由数据库唯一键和服务端事务共同保证。