HyperCyber 独立代理商管理后台

1. 文档基础信息

1.1 修订历史

2. 需求概述

2.1 问题陈述

代理商目前只能通过原型查看模拟经营数据，缺少可用于真实业务的身份校验、数据隔离、版本化费率、可追溯佣金账本、提现/发放与对账能力。旧 PRD 又把 C 端邀请、代理商端和平台内部审核混在同一范围内，并使用已过期的手续费口径，无法作为本次开发和验收依据。

2.2 解决方案

建设独立域名的代理商管理后台。代理商通过受邀邮箱验证码登录，只能查看本人代理体系；可查看经营总览、提交下级代理申请、管理已核准一级代理、核对每笔手续费佣金和跟单盈利分成佣金、申请手续费佣金提现并追踪发放结果。所有金额都能从汇总下钻到佣金账本，再追溯到用户实付手续费、代理角色、规则版本与支付凭证。

2.3 产品目标

• 代理商登录后 30 秒内看清累计收益、可提现手续费佣金、已发放盈利分成与本期有效客户。
• 任一汇总金额均可下钻到明细，并能解释成交额、费率、优惠、分润基数、代理比例与最终佣金；平台内部可核对 HL 成本、HL 返佣与留存。
• 费率调整只影响生效后的业务事件；历史账本保持原规则版本，不覆盖重算。
• 代理商不能自批下级代理，不能修改已核准费率，不能查看其他代理商数据。
• 提现与发放结果可核验；失败、重复事件和修正不造成重复计提或历史数据被直接篡改。

2.4 目标角色与权限

2.5 范围界定

2.6 核心用户故事

1. 作为已开通代理商，我希望用受邀邮箱验证码登录，以便不依赖钱包签名进入经营后台。
2. 作为代理商，我希望只看到归属于我的客户和下级，以避免跨代理数据泄露。
3. 作为代理商，我希望看到手续费佣金和盈利分成佣金的独立余额，以理解两类收入的不同结算方式。
4. 作为代理商，我希望逐笔查看佣金公式与规则版本，以便自行复核结算。
5. 作为代理商，我希望手续费佣金满 50 USDC 后一次性申请提现，以避免重复提交或遗漏余额。
6. 作为代理商，我希望盈利分成到账后看到支付哈希或真实凭证，以确认确已发放。
7. 作为代理商，我希望提交 L1 申请并查看平台审核结果，以便扩展下级网络但不形成自批权限。
8. 作为代理商，我希望导出当前筛选条件下的明细，以便与自己的财务记录核对。
9. 作为代理商，我希望失败记录显示原因与处理进度，以便知道是否需要补充信息。
10. 作为代理商，我希望页面明确展示自己是联创、LP 还是 IB，以及手续费佣金和跟单盈利分成佣金的两个独立比例。
11. 作为代理商，我希望明细显示用户是默认万7.5、直邀万7.32、专属跟单万5还是盘手净万7.32，以便识别优惠与佣金的计算顺序。
12. 作为平台，我希望重复接收同一交易事件不会重复产生佣金，以控制资金风险。

3. 业务流程与规则

3.1 总体业务链路

3.2 关系层级与代理角色必须分开

• 联创、LP、IB 为互斥角色，同一受益人在同一来源事件中只能命中一个角色比例。
• 角色的“高低”只表示合作档位，不等于 L1/L2 关系，不自动产生差额分佣。
• 代理商页面同时展示“来源层级”、“代理角色”、“有效规则版本”，不能只展示含义不清的“有效比例”。

3.3 七点核心费率说明

1. 默认手续费：基础手续费万4.5 + 平台手续费万3 = 默认最终费率万7.5。
2. 直邀用户优惠：未绑定邀请码时无优惠；绑定直邀后，减免基础手续费万4.5的 4%，即减免万0.18，用户实付万7.32。
3. 推荐人返佣：先扣除用户优惠，再按“用户实付手续费 × 该推荐人当时生效的手续费佣金比例”计算。
4. 专属跟单费率：指定带单员可配置万5最终费率，不再叠加直邀优惠或盘手 4% 返还。
5. 代理角色及分佣：联创股东 ＞ LP 合伙人 ＞ IB 经纪商；手续费佣金比例依次为 35% / 30% / 25%，跟单盈利分成佣金比例依次为 40% / 35% / 30%。
6. 盘手手续费：先按万7.5收取，再返还基础手续费万4.5的 4%，返还万0.18，最终净支出等价于万7.32。
7. 待业务补充：用户提及“7 点核心内容”但本次只提供 6 点。第 7 点及“万5专属跟单是否继续计算代理佣金”、“盘手返还是否可与直邀优惠叠加”一并待确认；未确认前不得在生产中默认叠加。

3.4 手续费与佣金计算

累计成交额使用全部已成交名义金额，开仓和平仓均计入，不使用保证金。金额单位为 USDC。

3.4.1 当前已确认参数

3.5 代理角色与跟单盈利分成

• 可计提净盈利必须按业务规则扣除费用并补回历史亏损后，由账户维度汇总。
• 净盈利 ≤ 0 时，Q=0，不产生盈利分成费与代理佣金。
• 内部计算保留完整精度；展示保留 2 位小数。逐笔结算舍入规则须在上线前确定。

3.5.1 标准示例（T=100,000 USDC，Q=1,000 USDC）

示例中基础手续费为 45.00 USDC，平台手续费为 30.00 USDC，直邀/盘手的 4% 计算基数是 45.00，因此优惠或返还为 1.80。专属万5与代理佣金是否并存尚未确认，真实计提前必须经利润底线校验和正式规则审批。

3.6 账本与结算规则

• 计算规则与结算规则独立。50 USDC 门槛、实时发放不会改变佣金公式。
• 手续费提现提交时必须在同一事务中锁定余额并生成提现单，避免并发重复申请。
• “已发放”只能由支付系统的真实成功回执或链上最终确认驱动；创建交易不等于发放成功。
• 历史财务记录不可直接编辑或删除。错误通过追加调整/冲正流水修复，并关联原记录。
• 原始计提唯一键：来源系统 + 来源事件 ID + 受益代理 ID + 佣金类型。首次处理时固定规则版本；重放事件即使当前规则已变化，也必须返回原记录，不得新增计提。更正另建调整流水并关联原记录。

3.6.1 余额与收益口径

净佣金收益 = 原始计提 + 正向调整 − 负向调整。提现及支付只改变资金状态，不再次增加或扣减收益。可用余额 = 已确认手续费净应付 − 已占用金额 − 已成功支付金额 − 冻结金额。已占用包含申请中与支付处理中，冻结与占用不得重复。已付款后产生负向更正时形成待抵扣金额，保留历史付款事实；不得自动从客户钱包扣款。

本期佣金和趋势统一按账本入账时间统计，包含当期追加的调整；来源成交时间另列显示。页面展示数据截止时间。日期范围采用左闭右开，结束日包含至次日 00:00 前。原始计提通过来源事件发生时间匹配当时有效的规则，延迟到达不改用当前新规则。

3.7 L1 申请流程

代理商仅能提交申请和查看结果。平台审核在另一个内部后台完成。申请状态为：草稿、已提交、审核中、已通过、已拒绝、已撤回。已通过/已拒绝为终态；规则变更另建变更单，不回写历史申请。

4. 详细功能需求

4.1 信息架构

4.2 登录与访问控制

• 入口为独立域名，由合作负责人私域提供；C 端主站生产环境不展示后台入口。
• 使用已获邀邮箱 + 6 位一次性验证码登录。验证码 5 分钟有效、使用一次即失效、60 秒内不可重复发送。
• 验证码连续错误 5 次，账号与设备组合锁定 30 分钟；发送、校验均需限流。
• 登录成功后服务端校验代理状态和权限。未开通、已暂停、已终止均不得返回经营数据。
• 会话默认 24 小时；高风险操作（提现）需在最近 15 分钟内完成二次验证。
• 原型中的 agent@example.com、验证码 123456 仅用于演示，不进入生产逻辑。

4.3 经营总览

4.3.1 核心卡片

• 趋势图按账本入账日期展示每日应计佣金，图表合计必须等于“本期合作佣金”。
• 当前规则卡展示代理角色、手续费佣金比例、跟单盈利分成佣金比例、佣金基数“用户实付手续费”、规则版本和生效时间。
• 存在发放失败、规则未确认或对账差异时，首屏显示明确告警并可跳转对应记录。

4.4 L1 申请

4.4.1 列表

筛选项：提交日期、名称/邮箱、状态、用户类型。列：申请编号、名称、邮箱、用户类型、建议代理角色、建议手续费/跟单盈利佣金比例、状态、提交时间、平台审核结果、操作。

4.4.2 新增申请字段

• 提交成功后进入“已提交”，代理商不能执行通过/拒绝。
• 平台未受理前允许撤回；审核中及终态不可撤回。
• 通过后自动进入一级管理，并展示平台核准的代理角色、两类佣金比例、规则版本和生效时间。
• 拒绝必须显示平台给代理商可见的拒绝原因；内部风控细节不向代理商泄露。

4.5 一级管理

顶部展示 L1 总数、当前有效 L1、本期 L1 交易额、本期 L2 交易额、本期贡献佣金。列表列：L1 名称、邮箱、用户类型、状态、L1 交易额、L2 交易额、代理角色、手续费佣金比例、跟单盈利分成佣金比例、规则版本、生效时间。

• 点击 L1 进入详情：基本资料、归属关系、规则历史、L1/L2 业绩、佣金贡献。
• 代理商不可直接改比例。需要变更时提交申请，由平台核准并生成新规则版本。
• 交易额均为已成交名义金额，开平仓均计入；页面须显示口径说明。
• 导出内容与当前筛选一致，包含规则版本但不包含平台内部风控字段。

4.6 佣金与发放

4.6.1 筛选与汇总

筛选项：入账时间、来源名称/邮箱、来源层级、代理角色、最终费率类型（默认/直邀/专属跟单/盘手）、佣金类型、账本状态、发放状态、规则版本、金额范围。汇总展示手续费佣金、跟单盈利分成佣金、可用余额、申请中、已发放、失败、总笔数。

4.6.2 明细列

入账时间、来源业务单号、来源名称/邮箱、来源层级、代理角色、佣金类型、成交额/可计提净盈利、基础手续费率、平台手续费率、最终费率类型、优惠/返还基数、优惠/返还金额、用户实付手续费、佣金比例、佣金金额、规则版本、账本状态、发放状态、提现单号/支付哈希。

4.6.3 计算详情抽屉

点击一条佣金记录后展示基础万4.5、平台万3、最终费率类型、优惠/返还计算、用户实付手续费 P、代理角色、佣金比例、舍入前金额、展示金额、来源事件时间、归属关系、生效规则版本和调整/冲正记录。任何数字不得只以不可解释的“利润”字段呈现。

4.6.4 手续费佣金提现

• 可用余额 <50 USDC：按钮禁用，显示距离门槛的金额。
• 可用余额 ≥50 USDC：点击“申请提现”后展示金额、绑定收款账户、费用与预计处理时间，二次验证后提交。
• 提交成功后相关账本从“可用”原子迁移为“已占用”，不得再次参与可提现余额。
• 提现失败若资金未转出，解锁回可用余额；若链上状态不确定，保持处理中并进入人工对账，不得直接解锁。

4.6.5 盈利分成发放

• 入账后自动创建发放指令，无需代理操作。
• 展示处理中、已发放、失败。已发放必须有真实支付凭证；链上模式展示完整 txHash 与区块浏览器链接。
• 自动重试采用幂等支付指令，禁止每次重试创建新的业务付款。

4.7 空、错、加载状态

4.8 页面线框与状态交付

以下新增交互为本次优化建议，待本稿评审后进入开发：申请撤回、草稿/审核中状态、二次验证、规则详情、异常下钻及规则变更申请。现有原型仅验证了基本页面与模拟交互。

4.9 代理可见数据与字段补充

邮箱用于登录及识别客户，不能充当链上收款地址。代理开通时必须由平台核验收款钱包及网络；提现快照保存收款地址、网络、币种和核验版本，页面不能临时输入其他地址。

代理默认看到与本人收益有关的成交额、基础手续费、平台手续费、优惠/返还金额、用户实付手续费、代理角色、两类佣金比例、本人佣金、规则生效时间和发放结果。平台内部成本与留存是否对代理公开为待评审权限，不默认通过代理接口返回。

手续费和跟单盈利分成分别展示“手续费佣金比例”和“跟单盈利分成佣金比例”，申请表中的建议比例也拆为两个字段。代理角色只能为联创、LP 或 IB；L1/L2 是关系层级，不自动映射代理角色。

5. 非功能需求

5.1 性能与可用性

5.2 安全与数据隔离

• 所有查询必须从服务端会话取得 agent_id，不得信任前端传入的 owner_agent_id。
• 邮箱、收款账户、交易哈希等敏感字段按最小化原则展示和导出；日志不得记录验证码或完整认证令牌。
• 验证码、提现、导出执行频控与审计；高风险操作需要最近一次二次验证。
• 金额使用 DECIMAL/定点数；禁止二进制浮点直接参与财务结算。
• 生产接口必须鉴权；独立域名、noindex、隐藏入口不构成安全措施。

5.3 数据一致性与审计

• 来源事件、归属关系、规则版本、佣金账本、提现单、支付指令形成完整证据链。
• 汇总由账本聚合，不维护无法对账的独立余额；余额变化记录前值、变动额、后值。
• 每次规则变更、L1 申请提交/撤回、提现申请、导出均记录操作人、时间、目标、前后状态和原因。
• 时区显示采用 Asia/Shanghai；服务端时间存 UTC，导出中同时提供 ISO 时间或明确时区。

5.4 兼容性与可访问性

• Chrome/Edge 近两个主版本、Safari 16+；桌面 1280px 优先，最小支持 375px。
• 键盘可完成登录、筛选、查看详情和提现确认；状态不只依赖颜色表达。
• 金额、比例、日期、层级均有表头或辅助说明；重要操作具备 loading、成功、失败反馈。

6. 验收标准

7. 依赖与风险

7.1 外部依赖

7.2 主要风险与应对

7.3 实施决策

• 前台后台分离部署；代理端只消费经授权的查询与申请接口。
• 建立版本化 PricingRule，不把比例硬编码在页面或交易代码中。
• 费率引擎先确定单一有效费率类型与用户实付 P，再计算代理佣金；同一事件的计算快照不可后置改写。
• 佣金账本为追加式事实表；余额是账本聚合/物化结果，可重建、可对账。
• 先上线影子账本，与新规则标准样例和真实历史样本并行核对；验证通过后再开放真实提现/自动发放。
• P0 阶段建议：影子计算 → 白名单代理查看 → 手续费提现人工复核 → 跟单盈利分成小额白名单自动发放 → 扩量。

7.4 上线前待确认

1. 用户所述“7 点核心内容”的第 7 点具体内容。
2. 万5专属跟单费率下是否继续按用户实付 5 个点计算代理手续费佣金；若是，需确认特殊补贴或利润底线。
3. 盘手 4% 返还是否可与直邀 4% 优惠叠加；未确认前默认互斥。
4. 跟单盈利分成费 30% 的具体高水位/亏损补回与逐笔舍入规则。
5. 手续费提现审核时效、链上网络、gas 承担方和最低发放金额。
6. 联创/LP/IB 与代理商/L1/L2 的实际映射及是否存在上下级二次拆分。

8. 附录

8.1 核心数据模型

8.2 核心接口

• POST /agent/auth/otp/send、POST /agent/auth/otp/verify、POST /agent/auth/logout
• GET /agent/overview、GET /agent/rules/current
• GET/POST /agent/l1-applications、POST /agent/l1-applications/{id}/withdraw
• GET /agent/l1、GET /agent/l1/{id}
• GET /agent/commissions、GET /agent/commissions/{id}、POST /agent/commissions/export
• GET /agent/withdrawals、POST /agent/withdrawals

8.3 术语

8.4 新旧规则对照

8.5 新口径与 Excel 差异索引

8.6 参考资料

• HyperCyber 邀请返佣原型
• HyperCyber 独立代理商后台原型
• 旧版代理商管理系统 PRD 模版
• 附件：《交易平台手续费与盈利分润测算_万7.5-new.xlsx》