1. 文档基础信息
| 条目 | 内容 |
|---|---|
| 产品模块 | HyperCyber 邀请码与代理商管理系统（C 端邀请仪表盘 + 代理商管理后台） |
| 文档版本 | v2.0.1 |
| 作者 | kenvenwu（PdM） |
| 更新时间 | 2026-10-04 |
| 阅读对象 | 前端工程师、后端工程师、测试工程师、UI 设计师、商务与运营 |
| 文档状态 | 正式版 已评审通过，作为开发与验收的唯一官方依据 |
| 关联文档 | 系统机制说明（system-mechanism.html）、功能清单（FEATURES.md）、交互原型（hypercyber-referral 原型） |
1.1 修订历史
| 版本 | 日期 | 修订人 | 修订说明 |
|---|---|---|---|
| v1.0.0 | 2026-09-27 | kenvenwu | 初版发布：代理商管理后台（登录、L1 申请、一级管理、佣金记录） |
| v2.0.0 | 2026-10-04 | kenvenwu | 按标准 PRD 框架全量重构；结算机制更新为双轨自动结算（手续费 T+1 / 盈利分成实时）；L1 申请返佣比例更新为 30%-80% 整数并增加低于 30% 拦截规则；登录入口更新为独立域名 agents.hypercyber.vip；新增 C 端邀请仪表盘功能需求、非功能需求、验收标准、依赖与风险 |
| v2.0.1 | 2026-10-04 | kenvenwu | 费率规则修正：新增手续费率结构（平台总费率万6.5 = Hyperliquid 万4.5 + HyperCyber 留存万2）；明确手续费佣金计算基数为 HyperCyber 留存万2（每万刀 2 USDC），非全额手续费；全体系返佣比例上限由利润的 30% 更新为返佣基数的 35%（每万刀最高 0.7 USDC）；L1 申请返佣比例范围由 30%-80% 调整为 30%-35% 整数（低于 30% 拦截规则不变）；同步更新示例数据与计算公式 |
文档使用说明：本 PRD 是本系统开发的唯一官方依据，不解释"为什么做"，只回答"做成什么样"。功能疑问以本文档为准；文档未覆盖的场景由 PdM 补充裁定并同步修订版本号，杜绝新旧文档混用。
2. 需求概述
2.1 需求背景
HyperCyber 是基于 Arbitrum 链的 Web3 跟单交易平台，用户可以通过邀请码加入平台，邀请人从被邀请人的交易手续费和跟单盈利分成中获得佣金。为了规模化拓展市场，平台需要建立代理商体系：合作伙伴（代理商）管理其下的 L1/L2 两级代理商网络，通过独立的管理后台审核 L1 申请、追踪分级佣金收入。
平台已上线 C 端邀请仪表盘（用户连接钱包、绑定邀请码、查看与领取个人佣金），但缺少面向 B 端代理商的运营管理后台——代理商无法高效审核 L1 申请、管理下线网络、追踪分级佣金明细。本需求旨在补齐代理商侧的管理能力，并统一邀请码体系规则，形成完整的「C 端邀请 + B 端代理」双层增长体系。
PM 判断：代理商体系是平台增长的核心杠杆。参考 Trasia 等竞品的代理模式，两级代理 + 双轨自动结算 + 链上透明可显著降低代理商信任成本，加速市场拓展。
2.2 需求目标
业务目标
- 建立两级代理商体系：代理商管理 L1 代理商，L1 代理商发展 L2 用户，形成可扩展的分销网络
- 透明可信的佣金机制：佣金全程系统自动结算、链上发放，交易哈希可在 Arbiscan 验证，消除代理商对结算透明度的顾虑
- 高效的运营管理：代理商通过独立后台审核 L1 申请（含 30% 比例门槛拦截）、查看分级佣金明细，降低运营沟通成本
产品目标
- 代理商登录后 30 秒内可查看核心佣金数据概览
- L1 申请审核流程不超过 3 步操作完成
- 佣金记录支持多维度筛选，查询响应 < 1 秒
- 所有已打款佣金均提供 Arbiscan 跳转链接，100% 可验证
2.3 目标用户与角色
系统包含 6 个角色层级，各角色职责和数据范围如下：
| 角色 | 层级 | 核心职责 | 返佣比例 | 可见数据范围 | 登录方式 |
|---|---|---|---|---|---|
| 平台 | 0 层 | 系统运营、代理商签约（使用邮箱创建账号）、全局配置 | 返佣基数的 65%（留存） | 全部数据 | 平台后台 |
| 代理商（合作伙伴） | 1 层 | 审核 L1 申请、管理 L1 比例、查看全体系佣金 | 最高返佣基数的 35% | 自己体系的 L1/L2 全部数据 | 注册邮箱 + 密码（独立域名后台） |
| L1 代理商 | 2 层 | 发展 L2 用户、获取 L2 交易差额佣金分成 | 30% - 35%（整数，协商） | 自己及下级 L2 数据 | C 端邀请仪表盘；返佣比例 ≥30% 方可开通代理商管理后台权限 |
| L2 用户 | 3 层 | 通过 L1 邀请码加入，进行跟单交易 | 返佣基数的 10%（自返） | 仅自己数据 | C 端邀请仪表盘 |
| 直推用户（邀请人） | C 端 | 邀请好友加入，获取直推佣金 | 返佣基数的 10% | 仅自己及被邀请人数据 | 钱包连接 |
| 被邀请人 | C 端 | 通过邀请码加入平台，进行交易 | 返佣基数的 10%（自返） | 仅自己数据 | 钱包连接 |
注意：全体系返佣比例统一最高设置为返佣基数的 35%（返佣池上限），适用于所有分佣体系。返佣基数 = HyperCyber 留存手续费（万2 加成，每万刀 2 USDC）+ 跟单盈利分成费，不含归 Hyperliquid 所有的万4.5 基础手续费；L1 代理商的申请返佣比例（30%-35% 整数）为协商分配参数，且低于 30% 不能开通代理商管理后台权限。
2.3.1 代理商后台权限矩阵
| 功能模块 | 查看 | 创建 | 编辑 | 审核 | 导出 |
|---|---|---|---|---|---|
| L1 申请管理 | ✅ | 手动添加 ✅ | — | ✅（<30% 拦截） | ✅ |
| 一级代理商管理 | ✅ | — | 比例调整 [待确认] | — | ✅ |
| 佣金与发放记录 | ✅ | — | — | — | ✅ |
2.4 范围界定
本次做
- C 端邀请仪表盘：钱包连接、上级邀请码绑定（5-15 位校验、绑定后不可更改）、个人邀请码自动生成（HK 开头）、未绑定拦截、手续费佣金 50 USDC 累积手动领取、盈利分成佣金实时发放、佣金记录（筛选/汇总）、被邀请人列表
- B 端代理商管理后台（独立域名 agents.hypercyber.vip）：注册邮箱 + 密码登录、L1 申请管理（手动添加 + 审核通过/拒绝 + 低于 30% 拦截）、一级代理商管理、佣金与发放记录（双轨结算：手续费 T+1 自动打款 / 盈利分成实时打款）
本次不做
- 代理商自助注册（账号由平台使用邮箱创建，同一邮箱可同时登录用户端和代理商管理后台）
- L1 审核通过后的返佣比例在线调整 [待确认]
- 第三方社交账号登录、邮箱 + 手机号双因子认证
- 佣金提现至非绑定的钱包地址
- 多语言国际化、原生 App
- 代理层级再下沉（固定为 平台 → 代理商 → L1 → L2，不开放 L3）
3. 业务流程与规则
本章作用：梳理核心业务主流程、分支流程、异常流程与底层业务规则。研发与测试须先吃透本章逻辑再开展开发与用例设计，从根源规避逻辑漏洞与功能缺失。
3.1 邀请码体系
3.1.1 主流程（C 端绑定）
用户连接钱包
→
点击"绑定邀请码"
→
输入上级邀请码
（5-15 位）
（5-15 位）
→
校验通过
绑定成功
绑定成功
→
系统生成个人邀请码
（HK 开头）
（HK 开头）
→
解锁邀请仪表盘
3.1.2 分支流程
- 格式不合法：输入不满足 5-15 位字母/数字 → 前端实时提示，不发起绑定请求
- 重复绑定：已绑定钱包再次访问 → 不再出现绑定入口，上级邀请码只读展示（绑定后不可更改、不可解绑）
- 个人码冲突：系统生成的个人邀请码与上级码相同 → 自动重新生成，直至不一致
3.1.3 业务规则
| 规则项 | 规则说明 |
|---|---|
| 绑定对象 | 用户在绑定弹窗中输入的是上级邀请码，不是自己的码 |
| 邀请码格式 | 5-15 位字母或数字，正则 ^[a-zA-Z0-9]{5,15}$，输入框 maxlength=15 |
| 个人邀请码生成 | 绑定成功后系统自动生成："HK" + 6 位随机字符（字符集 ABCDEFGHJKLMNPQRSTUVWXYZ23456789，已去除易混淆的 I/O/0/1），示例：HKD58A9G |
| 上下级码唯一性 | 个人邀请码与上级邀请码必须不一致，相同则重新生成 |
| 绑定唯一性 | 一个钱包地址仅可绑定一个上级邀请码 |
| 不可更改 | 上级邀请码绑定后不可更改、不可解绑 |
| 邀请链接 | https://hypercyber.vip/join/{个人邀请码} |
| 仪表盘准入 | 只有绑定邀请码后才能进入邀请仪表盘；未绑定时显示黄色横幅警告，仪表盘数据灰化置零 |
| 后台访问隔离 | 代理商管理后台为独立域名系统，访问链接由商务提供；用户仪表盘主体不展示任何后台入口 |
3.2 分钱机制
3.2.1 费用来源
返佣基数来自以下三类费用中归 HyperCyber 所有的部分。平台总手续费率为万6.5（每万刀交易 6.5 USDC），其中万4.5 归底层 DEX Hyperliquid 所有，万2 为 HyperCyber 留存加成；手动/跟单交易手续费仅万2 留存部分计入返佣基数，跟单盈利分成费全额计入：
| # | 费用类型 | 说明 | 计费基础 | 是否计入返佣池 |
|---|---|---|---|---|
| 1 | 手动交易开仓/平仓手续费 | 用户自主下单时，开仓和平仓各收取一次手续费 | 开仓/平仓金额 × 万6.5（仅万2 留存计入） | 计入 |
| 2 | 合约跟单开仓/平仓手续费 | 跟单交易时，开仓和平仓各收取一次手续费 | 跟单开仓/平仓金额 × 万6.5（仅万2 留存计入） | 计入 |
| 3 | 跟单盈利分成费 | 跟单仓位平仓盈利后，从盈利部分按比例收取 | 盈利金额 × 盈利分成比例（全额计入，归 HyperCyber） | 计入 |
3.2.2 返佣池分配
平台留存
65%
返佣基数留存
返佣池
35%
全体系最高上限
返佣池 = 返佣基数 × 35%；返佣基数 = HyperCyber 万2 留存手续费（手动开平仓 + 合约跟单开平仓）+ 跟单盈利分成费，不含归 Hyperliquid 所有的万4.5 基础手续费
3.2.3 代理商体系内部分配
总返佣池
35%
35%
→
代理商
L1 有效比例 25%-30%
L1 有效比例 25%-30%
→
L1 代理商
差额分成
差额分成
→
L2 用户
自返 10%
自返 10%
| 收益方 | 收益来源 | 计算方式 | 备注 |
|---|---|---|---|
| 代理商 | L1 体系交易 | 返佣基数 × L1 有效比例（25% - 30%） | 与 L1 代理商协商确定 |
| 代理商 | L2 体系交易 | 返佣基数 × L2 有效比例（15% - 20%） | 低于 L1 比例，差额为 L1 代理商所得 |
| L1 代理商 | L2 体系交易 | 返佣基数 × (35% - 代理商 L2 有效比例) | 从返佣池差额中获取 |
| L2 用户（自返） | 自身交易 | 返佣基数 × 10% | 直接返还到 L2 钱包 |
示例：某 L2 用户产生返佣基数 $10,000（HyperCyber 万2 留存手续费 + 盈利分成费），返佣池 = $10,000 × 35% = $3,500。
代理商获得 $10,000 × 20%（L2 有效比例）= $2,000，L1 代理商获得 $10,000 × (35%-20%) = $1,500（返佣池差额部分）。
平台留存 $10,000 × 65% = $6,500。合计 $10,000。
3.2.4 C 端直推体系（独立）
C 端直推用户的分钱机制与代理商体系相互独立，不占用代理商 35% 返佣池额度。直推体系中，从被邀请人产生的返佣基数（HyperCyber 万2 留存手续费 + 盈利分成费）中直接扣除 20% 作为直推奖励，其中邀请人分得 10%，被邀请人分得 10%（自返）。剩余 80% 归平台所有。
示例：被邀请人产生返佣基数 $1,000（万2 留存手续费 + 盈利分成费），从中扣除 20% 作为直推奖励。
邀请人获得 $1,000 × 10% = $100，被邀请人自返 $1,000 × 10% = $100，平台留存 $1,000 × 80% = $800。
3.3 双轨结算机制
佣金结算全程无需人工审核，全部由系统自动执行。C 端用户仪表盘与代理商管理后台执行两套不同的领取/打款规则：
| 端 | 佣金类型 | 记账 | 打款 | 领取方式 |
|---|---|---|---|---|
| C 端用户仪表盘 | 手续费佣金 | 实时累积记账 | 累积达到 50 USDC 后，资金直接打到链接的 Web3 钱包 | 手动领取 |
| 盈利分成佣金 | 实时记账 | 实时发放、实时打款 | 自动 | |
| 代理商管理后台 | 手续费佣金 | 实时记账 | 次日 13:00 自动打款（T+1 批量结算） | 自动 |
| 盈利分成佣金 | 实时记账 | 实时结算、实时打款 | 自动 |
3.3.1 代理商后台结算状态流
交易产生费用
（手续费）
（手续费）
→
实时记账
待打款
待打款
→
次日 13:00
批量自动打款
批量自动打款
→
已发放
（生成 txHash）
（生成 txHash）
交易产生费用
（盈利分成）
（盈利分成）
→
实时记账 + 实时打款
→
已发放
（即时生成 txHash）
（即时生成 txHash）
3.3.2 打款时间规则
| 佣金类型 | 打款节点 | 说明 |
|---|---|---|
| 手续费佣金（代理商） | 固定节点：次日 13:00（T+1） | 系统批量自动执行，打款完成后生成交易哈希 |
| 盈利分成佣金 | 无固定节点，实时打款 | 记账即打款，哈希即时生成 |
设计原则：零人工审核、固定节点 + 实时双轨自动执行、全链上可验证。这是 Web3 代理商体系区别于传统中心化分销的核心竞争力。
3.3.3 异常处理
| 异常场景 | 处理方式 | 用户感知 | 优先级 |
|---|---|---|---|
| 链上打款交易失败（gas 不足、网络拥堵） | 自动重试 3 次，间隔指数递增；仍失败则标记为发放失败，后台告警，滚动至下一批次补偿 | 状态显示"发放失败" | P0 |
| 佣金计算错误 | 结算前二次校验计算结果，不一致则阻断发放并告警 | 无感知（系统兜底） | P0 |
| 钱包地址无效 | 打款前校验地址格式，无效则跳过并记录日志 | 状态显示"地址异常" | P1 |
| 13:00 批量任务当日未完成 | 未完成部分自动滚动至下一批次，后台告警提示 | 状态保持"待打款" | P1 |
3.4 L1 申请审核状态流
用户自助申请
+
代理商手动添加
↓
待审核
已通过
自动进入一级管理
自动进入一级管理
已拒绝
- 通过校验：仅当申请返佣比例 ≥30% 时允许通过；低于 30% 的申请点击"通过"将被系统拦截，状态保持"待审核"（不能开通代理商管理后台权限）
- 通过：状态变为已通过，自动进入一级代理商管理列表，系统自动发送开通通知邮件
- 拒绝：需填写拒绝原因，状态变为已拒绝，系统自动发送通知邮件
- 终态：已通过 / 已拒绝均为终态，仅支持查看
3.5 佣金计算规则汇总
| 计算项 | 公式 / 规则 |
|---|---|
| 返佣基数 | HyperCyber 万2 留存手续费（手动开平仓 + 合约跟单开平仓，每万刀交易量留存 2 USDC）+ 跟单盈利分成费；不含归 Hyperliquid 所有的万4.5 基础手续费 |
| 代理商 L1 来源佣金 | L1 下级返佣基数 × L1 有效比例（25%-30%） |
| 代理商 L2 来源佣金 | L2 下级返佣基数 × L2 有效比例（15%-20%） |
| L1 代理商佣金（L2 来源） | L2 下级返佣基数 × (35% − 代理商 L2 有效比例) |
| C 端直推奖励 | 从被邀请人返佣基数中直接扣除 20%（邀请人 10% + 被邀请人自返 10%） |
| L2 用户自返 | 自身返佣基数 × 10% |
| 比例上限 | 全体系返佣比例统一不超过返佣基数的 35%（后端二次校验拦截） |
4. 详细功能需求
本章结构：按页面/模块逐一拆解，统一标准维度——功能简述 → 原型链接 → 页面元素 → 正常交互 → 加载状态 → 空数据状态 → 报错提示 → 异常兜底。这是 UI 出图、前后端开发、功能自测的核心依据。
4.1 C 端邀请仪表盘（index.html）
4.1.1 功能简述
用户通过邀请宣传页右上角「我的邀请」按钮（金色渐变背景，未绑定时灰色半透明禁用）进入邀请仪表盘。仪表盘承接钱包连接、邀请码绑定、佣金查看与领取、被邀请人管理。只有绑定邀请码后才能进入仪表盘，未绑定用户被拦截在绑定流程。
4.1.2 页面元素
- 顶部导航：品牌标识、周期筛选（全部时间/今日/本周/本月）、「模拟入口」胶囊按钮（仅原型演示）
- 未绑定横幅：黄色警告"您还未绑定邀请码 / 绑定邀请码后即可解锁 HyperCyber 专属交易权益，立即绑定吧！" + 绑定按钮
- 统计概览：总佣金收益、被邀请人数、活跃被邀请人、被邀请人交易量（联动周期筛选）
- 邀请信息卡：上级邀请码（只读）、个人邀请码（一键复制）、邀请链接（
https://hypercyber.vip/join/{个人邀请码}） - 佣金双卡：手续费佣金卡、盈利分成佣金卡（各含目标钱包地址）
- 数据 Tab：佣金记录、被邀请人
4.1.3 邀请码绑定（正常交互）
点击"绑定邀请码" → 弹窗打开（标题"绑定邀请码"，副标题"为当前钱包绑定邀请码，解锁 HyperCyber 专属交易权益"，自动聚焦输入框） → 输入上级邀请码，实时格式校验 → 点击"确定" → 绑定成功：Toast 提示、仪表盘数字从 0 滚动增长、权益卡光晕动画、上级码与个人码展示。
| 字段 | 必填 | 规则 | 校验提示（输入框下方实时显示） |
|---|---|---|---|
| 邀请码（上级码） | 是 | 5-15 位字母或数字，maxlength=15，正则 ^[a-zA-Z0-9]{5,15}$ |
不足 5 位："邀请码至少5位"；含非法字符："邀请码只能包含字母和数字"；合法："邀请码格式正确" |
绑定成功反馈：Toast "🎉 邀请码绑定成功！已解锁专属权益"；系统生成 HK 开头的个人邀请码（与上级码不同），并同步生成个人邀请链接。
4.1.4 手续费佣金卡
- 元素：待领取金额、橙黄色调进度条（当前值 / 目标 50.00 USDC）、领取按钮、"领取到"目标钱包地址
- 未达标（<50 USDC）：领取按钮置灰，显示"未达到领取阈值"
- 达标（≥50 USDC）：显示"可领取"徽章，按钮高亮为"立即领取佣金"
- 正常交互：点击领取 → 资金直接打到链接的 Web3 钱包 → Toast "🎉 领取成功！{金额} USDC 已发放至您的钱包" → 待领取金额清零，对应记录状态变为"已领取"并生成可跳 Arbiscan 的交易哈希
- 规则说明：hover 佣金卡显示规则说明（累积 50 USDC 方可领取）
4.1.5 盈利分成佣金卡
- 元素：累计发放金额、青绿色调、绿色脉冲动画、"实时发放"徽章
- 规则文案："盈利分成佣金实时结算，产生后立即发放至您的钱包，无需手动领取"
- 正常交互：点击"查看发放记录" → 页面自动滚动至佣金记录表并筛选为"盈利分成"类型
4.1.6 佣金记录 Tab
- 表格列顺序：时间 → 钱包地址 → 备注 → 费用类型 → 利润 → 佣金 → 状态 → 交易哈希
- 费用类型：蓝色 Badge（手续费）、绿色 Badge（盈利分成）
- 状态：待领取（手续费累积中，哈希列显示"累积中 · 待领取"）、已领取（手续费已打款，显示哈希；无哈希时显示"处理中"）、已发放（盈利分成实时发放，显示哈希）
- 备注样式：有备注显示深色加粗文字 + hover 编辑图标；无备注显示灰色斜体占位符
- 类型筛选：胶囊按钮（全部 / 手续费 / 盈利分成），每个带记录数徽标，切换时 Toast 反馈
- 统计汇总栏：三张卡片（记录数、利润合计、佣金合计）；筛选非"全部"时标签联动为"{类型}记录数 / {类型}利润合计 / {类型}佣金合计"且卡片绿色高亮
- 交易哈希：显示哈希 + 复制按钮 + Arbiscan 跳转链接（新标签页打开）
- 空数据状态："暂无{类型}佣金记录"
4.1.7 被邀请人 Tab
- 表格列顺序：加入时间（精确到秒）→ 钱包地址 → 备注 → 状态（活跃）→ 累计交易量 → 累计佣金
- 备注编辑：点击备注可编辑保存
4.1.8 原型演示说明（不进入生产需求）
模拟入口：顶部导航右侧琥珀色虚线胶囊按钮"模拟入口"，hover 提示模拟商务提供的独立后台链接，点击直接跳转代理商登录页——仅用于原型演示后台访问方式，生产环境不存在此按钮；演示快捷键
u（切换绑定状态）、w（增加 30 USDC 手续费佣金）同为演示功能。
4.2 代理商登录（pages/agent-login.html）
4.2.1 功能简述
代理商管理后台为独立域名系统（agents.hypercyber.vip），访问链接由商务提供，不在用户仪表盘中暴露，无中间页，直接进入登录页。登录使用注册邮箱 + 注册密码。
4.2.2 页面元素
- 居中卡片布局：Logo 标识 H、标题"HyperCyber 合作伙伴"、副标题"管理您的 L1 申请、返佣和结算"
- 登录提示条：橙色提示"使用您的注册邮箱和注册密码登录"
- 表单：邮箱输入框、密码输入框（带可见性切换按钮）
- 底部独立域名胶囊："agents.hypercyber.vip — HyperCyber 合作伙伴独立后台"，标识独立域名系统
4.2.3 正常交互与业务规则
- 账号体系：代理商账号由平台使用邮箱创建，不支持自助注册；同一邮箱账号可同时登录用户端和代理商管理后台
- 正常交互：输入注册邮箱 + 密码 → 点击"登录" → 按钮进入 loading 态"登录中..." → 校验通过跳转 L1 申请管理页
- 登录态：登录成功后写入 session，有效期 24 小时，超时自动登出
- 安全规则：密码连续错误 5 次锁定账号 30 分钟；忘记密码通过注册邮箱接收重置链接，有效期 24 小时且一次性使用
- 页面跳转：登录成功 → admin-l1.html；顶部侧边导航在后台三个模块间切换
4.2.4 字段规则与报错提示
| 字段 | 类型 | 必填 | 规则 | 报错提示 |
|---|---|---|---|---|
| 邮箱 | 是 | 标准邮箱格式（与注册邮箱一致） | 空值："请填写邮箱和密码"；格式错误：浏览器原生校验提示 | |
| 密码 | password | 是 | 8-20 位，含字母和数字（生产校验规则）；支持可见性切换 | 空值："请填写邮箱和密码"；账号密码不正确："邮箱或密码不正确" |
4.3 L1 申请管理（pages/admin-l1.html）
4.3.1 功能简述
L1 申请管理是代理商后台的核心审核模块。有意成为 L1 代理商的用户提交申请后（或代理商手动添加），代理商可在此页面查看全部申请记录，执行审核（通过/拒绝）并管理返佣比例。核心硬性规则：返佣比例低于 30% 不能开通代理商管理后台权限。
4.3.2 页面元素
- 顶部统计栏：总计、待审核、已通过三个核心指标，随筛选结果联动
- 筛选工具栏：申请日期范围（起止）、L1 钱包地址/名称搜索、状态筛选（全部状态/待审核/已通过/已拒绝）、重置、刷新
- 操作按钮：「添加L1」主按钮、导出
- 数据表格列：名称、地址、用户类型、申请比例、状态、提交时间、操作（查看 / 通过 / 拒绝——仅待审核状态显示）
4.3.3 手动添加 L1（表单弹窗）
| 字段 | 必填 | 类型 | 规则 |
|---|---|---|---|
| L1 钱包地址 | 是 | 文本 | 0x 开头的 42 位以太坊/Arbitrum 地址，前端校验格式；同一地址不可重复提交 |
| L1 名称 | 是 | 文本 | 2-30 字符 |
| 用户类型 | 是 | 下拉选择 | 关键意见领袖 / 下级代理 / 社区 / 其他 |
| 申请返佣比例(%) | 是 | 数字 | 30%-35% 之间的整数（step=1，min=30，max=35）；提示文案："请输入30%-35%之间的整数返佣比例；返佣比例低于30%不能开通代理商管理后台权限" |
| 预期交易量 | 否 | 文本 | 最多 128 字符，自由填写，如 "$120M / 14D"，带字数统计 |
| 来源说明 | 否 | 多行文本 | 最多 512 字符，描述该 L1 的获客渠道或背景，带字数统计 |
| 备注 | 否 | 多行文本 | 最多 512 字符，代理商内部备注信息，带字数统计 |
业务规则与报错提示：
- 手动添加的申请，提交来源标记为「代理商手动添加」，与用户自助申请区分；提交后进入「待审核」状态，需代理商自行审核
- 比例越界拦截：输入 <30 或 >35 → Toast 报错"返佣比例必须在30%-35%之间，低于30%无法开通代理商管理后台权限"，表单不提交
- 提交成功：Toast "L1申请已提交成功"，弹窗关闭，表单重置，列表刷新
- 加载状态：提交按钮变为旋转图标 + "提交中..."，期间禁用防重复提交
4.3.4 审核流程
- 通过：点击"通过" → 系统校验申请比例：≥30% 则审核通过，Toast "已通过 {名称} 的申请"，申请自动进入一级代理商管理，系统发送开通通知邮件；<30% 则拦截，Toast 报错"无法通过：{名称} 的申请返佣比例为 {比例}%，低于30%不能开通代理商管理后台权限"，状态保持待审核
- 拒绝：点击"拒绝" → 填写拒绝原因（必填，最多 200 字）→ 状态变为已拒绝，Toast "已拒绝 {名称} 的申请"，系统发送通知邮件
- 查看：点击"查看"可查看申请人详细资料，包括历史交易数据（如有）
- 异常兜底：后端对审核操作做二次比例校验，防止前端绕过；操作记录审计日志
4.3.5 低比例标识规则
申请列表中，返佣比例低于 30% 的记录，申请比例列以红色加粗显示并附 ⚠ 标识，hover 提示"返佣比例低于30%，不能开通代理商管理后台权限"。
4.3.6 状态流转
| 当前状态 | 允许操作 | 下一状态 | 触发条件 |
|---|---|---|---|
| 待审核 | 通过（≥30%）/ 拒绝 / 查看 | 已通过 / 已拒绝 | 代理商审核操作；<30% 的"通过"被系统拦截 |
| 已通过 | 查看 | — | 终态，自动进入一级管理 |
| 已拒绝 | 查看 | — | 终态 |
4.3.7 空数据状态
暂无申请记录时显示空状态引导："暂无L1申请记录 / 添加你的第一个L1级代理商，开始管理你的返佣网络"，并提供「添加L1」快捷按钮。
4.4 一级代理商管理（pages/admin-level1.html）
4.4.1 功能简述
展示所有已通过审核的 L1 代理商列表，代理商可在此查看每个 L1 的业绩数据、返佣比例和下级 L2 情况。通过 L1 申请审核的记录自动出现在此列表。
4.4.2 页面元素与数据规则
- 顶部统计栏：L1 总数、总交易量（L1+L2 合计），随筛选联动
- 筛选工具栏：日期范围（起止）、搜索 L1 名称或地址（模糊匹配，不区分大小写）、重置
- 数据表格列：L1 名称、L1 钱包地址、用户类型、L1 交易量、L2 交易量、返佣比例、创建时间
- 数据范围：仅展示代理商自己体系内已通过的 L1，按创建时间倒序排列
- 交易量统计：L1 交易量为该 L1 自身产生的交易费用总和；L2 交易量为其下线所有 L2 用户产生的交易费用总和
- 返佣比例：审核通过时确认的比例，显示为整数百分比
- 空数据状态："暂无一级代理商 / 通过L1申请审核后，代理商将自动出现在这里"
4.4.3 字段格式
| 字段 | 类型 | 格式/单位 | 说明 |
|---|---|---|---|
| L1 交易量 / L2 交易量 | 金额 | USD，保留 2 位小数，千分位 | ≥100 万显示 M（$X.XXM），≥1000 显示 K（$X.XK） |
| 返佣比例 | 百分比 | 整数 % | 30% - 35%，审核通过时确定 |
| 创建时间 | 日期 | YYYY-MM-DD | 审核通过日期 |
4.5 佣金与发放记录（pages/admin-commission.html）
4.5.1 功能简述
代理商查看收入明细的核心页面。系统采用双轨自动结算，佣金记录与发放记录合二为一：每条记录同时包含佣金明细与发放信息（状态、预计打款时间、交易哈希）。
4.5.2 页面元素
- 双轨结算卡：左侧"手续费佣金 T+1 · 自动——实时记账，次日 13:00 自动打款"；右侧"盈利分成佣金 实时 · 自动——实时记账，实时结算，实时打款"
- 统计栏（五项，随筛选联动）：手续费佣金（蓝）、盈利分成佣金（绿）、待打款(手续费)（橙，hover 提示"手续费实时记账，次日13:00自动打款"）、总佣金、总笔数
- 筛选工具栏：日期范围、来源钱包地址搜索（匹配地址或名称，不区分大小写）、来源体系（全部/L1/L2）、费用类型（全部/手续费/盈利分成）、交易量范围（最小/最大）、重置、刷新
- 数据表格列：成交时间、来源钱包地址、来源名称、来源体系、费用类型、利润、有效比例、佣金金额、状态、交易哈希
- 导出：导出当前筛选结果为 CSV，字段与表格列一致，用于财务对账
4.5.3 状态规则
| 状态 | 适用记录 | 展示规则 |
|---|---|---|
| 待打款 | 手续费佣金（T+1 阶段） | 橙色徽章；hover 提示"实时记账，{预计打款时间} 自动打款"（默认次日 13:00） |
| 已发放 | 盈利分成佣金（即时）+ 已完成打款的手续费佣金 | 绿色徽章；hover 提示"已打款至钱包" |
| 发放失败 | 链上打款失败的记录（异常态） | 红色徽章，进入自动重试与告警流程 |
4.5.4 交易哈希规则
| 场景 | 展示规则 |
|---|---|
| 已打款（有 txHash） | 显示前 10 后 8 位缩略哈希，hover 显示完整哈希，点击跳转 Arbiscan（https://arbiscan.io/tx/{txHash}，新标签页打开） |
| 手续费待打款（无 txHash） | 灰色占位"— 打款后生成"，hover 提示"{打款时间} 自动打款后生成" |
4.5.5 显示格式规则
- 金额：$ 千分位 + 2 位小数（如 $3,750.00）；交易量 ≥100 万显示 $X.XXM、≥1000 显示 $X.XK
- 钱包地址：显示前 6 后 4 位，hover 显示完整地址
- 有效比例：整数百分比（如 30%）
- 费用类型 Badge：蓝色 = 手续费（含手动交易和跟单交易的开平仓手续费），绿色 = 盈利分成（跟单盈利的分成费用）
- 来源体系 Badge：L1（蓝）/ L2（灰）
4.5.6 数据来源与空数据状态
每条记录对应一笔产生费用的交易（手动开平仓、跟单开平仓或跟单盈利分成）。手续费佣金实时入账后状态为"待打款"，次日 13:00 批量打款后生成哈希；盈利分成佣金记账即打款。无记录时显示空状态："暂无佣金记录 / 当你的下级代理产生交易时，佣金记录将显示在这里"。
5. 非功能需求
5.1 性能要求
| 指标 | 目标值 | 说明 |
|---|---|---|
| 登录接口响应 | ≤ 2 秒 | 含账号密码校验 |
| L1 申请列表查询 | ≤ 1 秒 | 含筛选、统计汇总 |
| 佣金记录查询 | ≤ 1 秒 | 含多维筛选与五项统计联动 |
| 实时记账延迟 | ≤ 5 秒 | 链上交易确认后完成入账 |
| 盈利分成实时打款 | 实时 | 记账后立即发起链上打款 |
| 手续费 T+1 批量打款 | 13:00-13:30 | 当日批次全部待打款记录完成打款并生成哈希 |
| 页面首屏加载 | ≤ 3 秒 | 桌面端宽带网络环境 |
5.2 兼容性
| 类别 | 要求 |
|---|---|
| 浏览器 | Chrome 100+、Edge 100+、Safari 15+，桌面端为主 |
| 钱包插件 | MetaMask、Rabby 等主流 EVM 钱包，连接 Arbitrum 网络 |
| 分辨率 | 桌面 ≥1280px 为主，兼容移动端 375px 起自适应布局 |
| 链网络 | Arbitrum One（打款与哈希验证均在该链） |
5.3 数据安全
- 传输加密：全站 HTTPS，敏感字段不在 URL 明文传输
- 密码存储：不可逆加密存储（bcrypt/argon2），前端不缓存明文密码；密码连续错误 5 次锁定 30 分钟；重置链接 24 小时有效且一次性
- 登录态：session 有效期 24 小时，超时自动登出
- 打款安全：佣金仅可打款至绑定/审核通过的钱包地址，打款前做格式与归属双重校验；发放前对计算结果二次校验
- 账本可信：佣金发放以链上交易为准，txHash 全量可在 Arbiscan 验证，记录不可篡改
- 操作审计：L1 审核、导出等敏感操作记录操作日志（操作人、时间、前后状态）
5.4 埋点需求
| 端 | 埋点事件 | 用途 |
|---|---|---|
| C 端 | 绑定弹窗曝光/提交/成功/失败；手续费领取按钮曝光/点击/成功；盈利分成"查看发放记录"点击；类型筛选切换 | 绑定转化率、领取转化率 |
| B 端 | 登录成功/失败；添加 L1 提交/拦截；审核通过/拒绝/低比例拦截；导出点击；筛选使用 | 审核效率、拦截率监控 |
| 转化指标 | 邀请码绑定转化率、50 USDC 达标领取率、L1 审核通过率、低比例拦截次数 | 增长与风控双监控 |
6. 验收标准
验收原则：每条功能需求配套可量化、可落地、可复现的验收规则，杜绝"正常完成"类模糊描述。本表是测试用例编写、线上验收与需求复盘的唯一标准。
6.1 C 端邀请仪表盘
| 编号 | 验收项 | 验收规则（操作步骤 → 预期结果） |
|---|---|---|
| AC-01 | 未绑定拦截 | 未绑定钱包访问仪表盘 → 显示"您还未绑定邀请码"黄色横幅，统计数据为 0 且灰化，可见绑定按钮 |
| AC-02 | 格式校验-过短 | 绑定弹窗输入"ABC" → 提示"邀请码至少5位"，不发起绑定请求 |
| AC-03 | 格式校验-非法字符 | 输入"AB@12" → 提示"邀请码只能包含字母和数字"，不发起绑定请求 |
| AC-04 | 绑定成功 | 输入合法码"BRAVO88"提交 → Toast"🎉 邀请码绑定成功"；个人邀请码以 HK 开头共 8 位且 ≠ BRAVO88；邀请链接格式为 https://hypercyber.vip/join/{个人码}；数字滚动动画正常 |
| AC-05 | 不可重复绑定 | 已绑定钱包再次访问 → 不出现绑定入口，上级邀请码只读展示，无"更换"操作 |
| AC-06 | 手续费阈值-未达标 | 待领取金额 49.99 USDC → 领取按钮置灰显示"未达到领取阈值"，不可点击 |
| AC-07 | 手续费领取成功 | 待领取 ≥50 USDC → 按钮高亮"立即领取佣金"；点击后资金打到连接的 Web3 钱包，Toast 显示实际金额，记录状态变"已领取"且哈希可跳 Arbiscan |
| AC-08 | 盈利分成实时发放 | 产生盈利分成佣金 → 实时到账，状态"已发放"，哈希即时生成且可跳 Arbiscan，无需任何手动操作 |
| AC-09 | 类型筛选联动 | 点击"盈利分成"胶囊 → 列表仅显示盈利分成记录，汇总标签变为"盈利分成记录数/利润合计/佣金合计"且三卡绿色高亮，胶囊带正确记录数徽标 |
| AC-10 | 查看发放记录联动 | 点击盈利分成卡"查看发放记录" → 页面滚动至佣金记录表并自动筛选为"盈利分成" |
6.2 代理商登录
| 编号 | 验收项 | 验收规则（操作步骤 → 预期结果） |
|---|---|---|
| AC-11 | 空值拦截 | 邮箱或密码为空点击登录 → 红字提示"请填写邮箱和密码"，不发起跳转 |
| AC-12 | 登录成功 | 输入注册邮箱 + 正确密码 → 按钮变为"登录中..."loading 态 → 校验通过跳转 L1 申请管理页，侧边导航激活正确 |
| AC-13 | 登录失败锁定 | 连续输错密码 5 次 → 账号锁定 30 分钟，期间正确密码也无法登录，提示剩余锁定时间 |
| AC-14 | 独立域名标识 | 登录页底部显示胶囊"agents.hypercyber.vip — HyperCyber 合作伙伴独立后台"；页面内无任何用户仪表盘入口 |
6.3 L1 申请管理
| 编号 | 验收项 | 验收规则（操作步骤 → 预期结果） |
|---|---|---|
| AC-15 | 添加-比例越界拦截 | 添加 L1 表单输入比例 25（或 36）→ Toast"返佣比例必须在30%-35%之间，低于30%无法开通代理商管理后台权限"，申请不提交 |
| AC-16 | 添加成功 | 填写合法数据（比例 30-35 整数）提交 → 按钮显示"提交中..." → Toast"L1申请已提交成功"，列表新增"待审核"记录且统计 +1 |
| AC-17 | 审核-低比例拦截 | 对比例 20% 的待审核申请点击"通过" → Toast"无法通过：{名称} 的申请返佣比例为 20%，低于30%不能开通代理商管理后台权限"，状态保持"待审核" |
| AC-18 | 审核-通过 | 对比例 ≥30% 的待审核申请点击"通过" → 状态变"已通过"，Toast 成功提示，该 L1 自动出现在一级代理商管理列表，通知邮件发送 |
| AC-19 | 审核-拒绝 | 点击"拒绝"并填写原因 → 状态变"已拒绝"，Toast 反馈，通知邮件发送 |
| AC-20 | 低比例红色标识 | 列表中比例 <30% 的记录 → 申请比例列红色加粗并带 ⚠，hover 显示"返佣比例低于30%，不能开通代理商管理后台权限" |
| AC-21 | 空数据状态 | 无申请记录 → 显示"暂无L1申请记录"空状态及"添加L1"快捷按钮，表格隐藏 |
6.4 佣金与发放记录
| 编号 | 验收项 | 验收规则（操作步骤 → 预期结果） |
|---|---|---|
| AC-22 | 手续费待打款 | 当日产生的手续费佣金 → 状态橙色"待打款"（hover 显示预计打款时间"次日 13:00"），哈希列显示"— 打款后生成"，计入"待打款(手续费)"统计 |
| AC-23 | 次日自动打款 | 次日 13:00 批量任务执行后 → 该记录状态变"已发放"，哈希生成且点击跳转 Arbiscan 对应交易页，"待打款(手续费)"统计相应减少 |
| AC-24 | 盈利分成即时发放 | 产生盈利分成佣金 → 状态即时为"已发放"，哈希即时生成可跳 Arbiscan，无"待打款"中间态 |
| AC-25 | 统计联动 | 筛选费用类型=手续费 → 手续费佣金、待打款(手续费)、总佣金、总笔数仅统计手续费记录；筛选来源体系=L1 → 仅统计 L1 记录 |
| AC-26 | 哈希跳转 | 点击任一已发放记录的哈希 → 新标签页打开 arbiscan.io/tx/{txHash}，地址栏哈希与记录一致 |
| AC-27 | 导出 | 设置筛选条件后点击导出 → 下载 CSV 文件，字段与当前筛选结果表格列一致，金额与统计一致 |
7. 依赖与风险
7.1 外部依赖
| 依赖项 | 用途 | 不可用时的影响 |
|---|---|---|
| Arbitrum 链 + 佣金发放智能合约 | 佣金链上打款、交易哈希生成 | 打款失败/延迟，进入重试与告警流程（P0） |
| Arbiscan 区块链浏览器 | 交易哈希验证跳转 | 哈希不可跳转验证，体验降级（P2，外链服务） |
| 邮件服务 | L1 审核通知、密码重置链接 | 通知无法送达，需备用通道（P1） |
| 钱包插件（MetaMask 等） | C 端钱包连接与佣金领取 | 用户无法连接与领取（P1，引导安装） |
| 定时任务调度系统 | 每日 13:00 手续费佣金批量打款 | T+1 打款延迟，滚动至下一批次（P1） |
| 用户/账务数据库 | 绑定关系、L1 申请、佣金账本 | 核心功能不可用（P0） |
7.2 风险与应对
| 风险 | 影响 | 应对措施 | 等级 |
|---|---|---|---|
| 链上拥堵 / gas 价格波动 | 打款延迟或失败，代理商信任受损 | 自动重试 3 次 + 指数退避；失败告警；滚动至下一批次补偿 | 高 |
| 佣金计算精度问题（小数） | 金额误差累积，对账不一致 | 定点数/整数化计算，结算前二次校验，不一致阻断发放 | 高 |
| 比例配置越界（超 35% 返佣池） | 超发佣金，平台亏损 | 前后端双重校验：L1 申请限 30%-35% 整数，全体系上限 35% 由后端拦截 | 高 |
| 用户误绑邀请码（绑定后不可更改） | 绑定错误无法自助修复，客诉 | 绑定前弹窗二次确认；客服工单通道处理 exceptional 解绑 | 中 |
| 多级分销合规风险 | 部分地区分销层级限制 | 上线前法务合规评估 [待确认] | 中 |
| 恶意刷邀请 / 自我邀请套利 | 返佣池被套取 | 绑定与领取频控、地址风控规则 [待确认] | 中 |
8. 附录：术语表
| 术语 | 定义 |
|---|---|
| 代理商 / 合作伙伴 | 与平台签约的 B 端合作伙伴，拥有独立域名管理后台（agents.hypercyber.vip），可审核 L1 申请、管理 L1 代理商、查看全体系佣金 |
| L1 代理商 | 一级代理商，由代理商审核通过（返佣比例 ≥30% 方可开通管理后台权限），可发展 L2 用户，从 L2 交易差额中获取佣金 |
| L2 用户 | 二级用户，通过 L1 代理商的邀请码加入，进行跟单交易，享受 10% 自返佣金 |
| 上级邀请码 | 用户在绑定弹窗中输入的邀请码，即其上级（邀请人/代理商）的个人邀请码；绑定后不可更改 |
| 个人邀请码 | 绑定上级邀请码成功后，系统自动生成的专属邀请码，"HK"+6 位随机字符（去除易混淆字符），与上级邀请码必然不同 |
| 利润 | 用户交易产生的全额费用总和（万6.5 口径），包括手动开平仓手续费、跟单开平仓手续费、跟单盈利分成费；返佣计算不直接以利润为基数 |
| 返佣基数 | 返佣计算的实际基数：HyperCyber 万2 留存手续费（手动开平仓 + 合约跟单开平仓，每万刀交易量留存 2 USDC）+ 跟单盈利分成费，不含归 Hyperliquid 所有的万4.5 基础手续费 |
| 返佣池 | 从返佣基数中划出的、用于分配给代理商体系的部分，全体系上限为返佣基数的 35% |
| 有效比例 | 代理商在某笔交易中实际获得的返佣比例，L1 有效比例通常高于 L2 有效比例 |
| 申请返佣比例 | L1 申请时协商设定的独立返佣比例，30%-35% 整数；低于 30% 不能开通代理商管理后台权限 |
| 双轨结算 | 两类佣金按不同轨道自动结算：手续费佣金实时记账、次日 13:00 自动打款（T+1）；盈利分成佣金实时记账、实时结算、实时打款。全程无需人工审核 |
| 待打款 | 手续费佣金已实时记账但未到达打款节点的中间状态，到达次日 13:00 后系统批量自动打款并生成交易哈希 |
| T+1 | 打款周期描述：交易日实时记账，次一自然日 13:00 自动批量打款 |
| Arbiscan | Arbitrum 区块链浏览器，用于查询交易详情、验证链上发放记录 |
| 交易哈希 (txHash) | 链上交易的唯一标识，可通过 Arbiscan 查询交易详情；打款完成后生成 |
| 用户类型 | L1 代理商的分类标签，包括关键意见领袖（KOL）、下级代理、社区、其他，用于运营分类管理 |