网站分销（邀请）系统的开发及Bug修复指南

在 OPCwiki 多用户 AI 平台中，邀请返佣系统的设计经历多次迭代。本文总结从零搭建到稳定运行的核心经验。

一、完整数据流

邀请人复制链接 https://wiki.opcgrow.org/?ref=54d59269
  ↓
好友打开 → Login.tsx 用 useSearchParams 提取 ref=54d59269
  ↓
存入 cookie: opc_ref=54d59269 (max-age=30天)
  ↓
好友注册 → body.ref_code = 54d59269
  ↓
后端 auth.py → register 端点接收 Cookie + ref_code
  ↓
写入 referred_by → 触发 process_referral_registration
  ↓
stats[ref_code].count += 1  (注册时触发统计)
  ↓
好友充值 → payment.py 回调 → process_referral_reward
  ↓
邀请人 balance += amount × 10%  (充值回调触发奖励)

二、关键架构

2.1 邀请追踪

邀请链接通过 URL 参数传递 ?ref=CODE，前端用 useSearchParams 提取后存入 document.cookie（30 天有效）。注册时自动填入 body.ref_code，确保无论好友何时注册都能追踪到。

2.2 统计与奖励分离

统计触发（注册时）：process_referral_registration(ref_code) —— 仅更新 count，不涉及金额。

奖励触发（充值到账时）：process_referral_reward(payer_user_id, amount) —— 查邀请人 + 余额 +10% 奖励。

2.3 API 端点

三、三个关键 Bug 及修复

Bug 1：邀请客户数始终为 0

根因：get_invite_info 用 user["user_id"]（全长度 UID）查 referrals.json 的 stats，但 stats 的 key 是 ref_code（前 8 位）。字段不匹配 → 永远查不到。

ref_code = db_user.get("ref_code", user["user_id"][:8])
stats = ref_data.get("stats", {}).get(ref_code, {})

Bug 2：注册时 ref_code 未传递

根因：前端 Login.tsx 的 handleSubmit 中，注册和登录共用 /auth/login 端点，ref_code 没被 register 端点接收。

Bug 3：Docker 构建缓存导致修不生效

根因：前端代码修改后 docker compose up --build backend 仍加载旧版本 dist。

cd /www/opcwiki/web/frontend && rm -rf dist node_modules/.vite && npm run build && cd /www/opcwiki && docker compose -f docker-compose.full.yml build --no-cache backend && docker compose -f docker-compose.full.yml up -d backend

四、数据文件结构

五、部署检查清单

1. 所有用户均有 ref_code（UID 前 8 位）
2. 被邀请用户 referred_by 非空
3. referrals.json 的 stats key 与 ref_code 一致
4. 前端 Login.tsx 注册调 /auth/register（非 /auth/login）
5. Docker 部署使用 --no-cache 构建

—— 基于 OPCwiki v6 商业版实战经验整理 ——