WorthChain功能需求文档

WORTHCHAIN · 商城新增功能

入驻商家充值功能需求说明

V1.02026年11月20日需求说明

适用对象:需求方、开发方、平台管理员、入驻商家

已确认:用户支付的 BNB 总额 × 付款时 BNB 的实时人民币价格=充值积分。按 1 元=1 积分计算,保留两位小数;分佣、返利和购买 Token A 的部分不从计算基数扣除。

查看文档目录

01业务目标与范围

在现有 WorthChain 商城底部新增“充值”入口。用户选择管理员配置的入驻商家,填写充值账号和备注,支付 BNB;平台按人民币等值计算充值积分,供商家在自己的商城手动入账并标记处理结果。

已确认的核心规则

  • 只有已在当前平台开通商家身份、已有本平台收款合约的商家,才能由管理员配置为“入驻商家”并出现在充值页面。
  • 充值直接调用该商家现有收款合约,继续使用现有分佣、返利、Token A 购买和分配规则。
  • 积分按用户实际支付的 BNB 总额计算,不扣商家分佣/返利部分,不计网络手续费;1 元人民币=1 积分,保留两位小数。该规则已由需求方确认。
  • 积分是商家外部商城的待入账凭据。本平台自动计算积分,商家在自己的商城手动加分后,将对应充值单标记为“已入账”。

角色和职责

角色和职责
角色 主要操作 数据范围
充值用户选商家、填账号和备注、支付 BNB、查看自己的充值结果本人充值订单
平台管理员从现有商家中办理入驻、上下架、查看订单及异常核对本平台充值业务
入驻商家钱包签名登录独立后台、查看充值单、人工加分并标记本商家的充值订单

完整业务流程

开通现有商家身份 → 管理员配置入驻 → 用户选择商家并提交充值资料 → 钱包支付到商家合约 → 后台核验链上交易 → 自动换算积分并生成待入账记录 → 商家在自己的商城加积分 → 标记该充值单已入账。

名词统一使用“入驻商家”。原有商家收款、预售、质押等页面继续保留;本次新增一条充值业务流程。

02用户充值页面与支付流程

充值入口与表单

商城底部新增“充值”按钮,打开独立充值页面或对应页面标签。列表仅展示管理员已上架的入驻商家,并显示商家名称和必要的收款说明。

充值入口与表单
字段 填写与展示规则
选择入驻商家必选;禁止用户随意输入其他收款地址;合约地址由已注册商家数据关联取得。
充值金额以 BNB 输入,必须大于 0,最多 18 位小数;另提示需要预留 Gas。
账号 手机号必填,按字符串保存;默认支持中国大陆 11 位手机号。该账号是商家外部商城的入账目标。
备注内容默认选填,最多 200 字;由用户自定义,提交后按文本安全展示。
预计积分显示参考 BNB/人民币价格、价格时间和预计积分;说明最终金额以付款时对应价格为准。

提交和确认

  • 连接钱包并确认 BSC 主网。首次需要时签名建立充值业务会话,用于保护订单资料;钱包签名与 BNB 付款分别展示。
  • 先在服务器保存待支付订单、充值账号、备注、商家与付款钱包,再发起付款;订单创建失败时不引导用户继续付款。
  • 付款前确认商家、手机号、备注、BNB 数量和预计积分,并提示手机号填错可能影响商家人工入账。
  • 调用现有商家付款流程完成交易预检查、兑换报价、Gas 预估和钱包付款;不可把充值改成普通转账绕开商家合约。

结果和订单查询

用户可查看本人充值订单、支付进度、交易哈希、最终积分以及待入账/已入账状态。取消签名、付款失败、链上确认中、服务暂不可用时给出明确提示。刷新或返回页面后可继续查询,查询超时不直接判定付款失败。

本期不包含短信验证码、手机号实名或外部商城账号存在性校验。手机号仅用于商家找到正确的积分账号,不作为钱包登录凭证。

03管理员配置与商家独立后台

管理员办理入驻

在现有管理员后台新增“入驻商家”管理。管理员从当前平台已注册商家中选择对象,系统核验商家钱包、工厂登记和收款合约的对应关系。禁止为未开通商家身份的钱包直接创建充值收款对象。

  • 配置展示名称、充值说明、展示排序和上架状态。优先复用现有商家名称和资料,避免维护两套相互冲突的身份数据。
  • 商家钱包、商家收款合约和工厂归属从现有登记读取,不允许在充值配置中改为任意第三方地址。
  • 同一商家只建立一条入驻配置。下架后不再接受新的充值订单,历史订单和已广播交易继续核对处理。
  • 管理员可查询全平台充值订单,按商家、手机号、钱包、订单号、状态和时间筛选,查看交易及入账操作记录。

独立后台与钱包登录

新增独立访问页面,建议路径为 /merchant-recharge.html。商家连接钱包并签名登录,服务器验证其属于当前工厂登记的商家。登录钱包应为收款合约对应的商家钱包,即该商家实际接收 BNB 的钱包;收款合约地址本身不能进行普通钱包签名。

默认一个商家钱包管理自己的充值订单,不设员工子账号或额外授权钱包。下架商家仍可登录处理历史订单;其合约收款状态继续由原平台机制管理。

充值列表与入账标记

列表分页展示订单号、充值时间、付款钱包、充值手机号、备注、BNB 金额、折合人民币、积分、交易哈希和入账状态。支持按手机号、付款钱包、时间和状态查询;手机号供有权限的商家查看,不公开展示。

  • 默认显示“待入账”。商家在外部商城完成加分后,点击“标记已入账”,二次确认该笔订单及积分数。
  • 保存操作钱包、处理时间和可选处理备注。重复点击或多窗口同时操作只允许成功一次,避免重复处理。
  • 支持误标后“撤销入账标记”,必须填写原因并保留历史。撤销只修改平台标记,不会回收外部商城中已加的积分。

入账操作针对每笔充值订单。相同手机号或钱包可以有多笔充值,不能按地址整体标记为已处理。

04人民币折算与积分计算规则

计算口径

人民币等值金额=链上确认的充值 BNB 总额 × 本笔订单适用的 BNB/人民币价格。充值积分=人民币等值金额,按十进制定点运算四舍五入保留两位小数。Gas 不参与换算。

分佣、返利、Token A 购买和代币分配仍由现有合约执行;积分以用户的充值总额为基数,不能改用商家实际收到的 BNB 净额。人民币折算仅用于积分记账,不发生人民币收付或法币兑换。

计算示例

计算示例
项目 示例数值
用户充值0.1 BNB
示例价格1 BNB=4,200.00 元人民币
人民币等值及积分420.00 元;420.00 积分
假设现有折扣为 10%商家 BNB 净收约 0.09 BNB,另外 0.01 BNB 按现有规则购买并分配 Token A;充值积分仍为 420.00。

上述价格仅用于演示,不代表当前实时行情;实际分账以现有合约配置及链上结果为准。

价格获取与固定时间

  • 价格由后台从自动行情服务获取,不信任前端提交的价格。可直接获取 BNB/人民币,或用 BNB/美元与美元/人民币组合计算;如使用 USDT 报价,应明确转换口径,不能默认等于人民币或美元。
  • 建议后台每 60 秒更新并保存行情。本单按付款交易所在区块时间前最近一份有效价格计算,价格距该区块时刻原则上不超过 5 分钟。用户确认页显示的是预估数。
  • 保存原始价格、来源、报价时间、计价时间、人民币金额、积分和计算规则版本。已确定积分的历史订单不随实时价格变化而重新计算。

行情服务异常

创建订单前没有有效价格时暂停新充值并提示稍后重试。若交易已成功但对应时刻价格缺失,订单进入“待核价”,不得进入可入账列表;后台优先恢复该时刻有效价格,仍无法恢复时由管理员说明依据并核定,记录操作后才进入待入账。不能直接使用恢复服务时的新价格覆盖历史付款时点。

05链上核验与订单状态

支付核验原则

后台独立核验 BSC 主网交易回执、成功状态和商家合约 Paid 事件,校对付款钱包、目标合约、BNB 总额以及当前工厂登记关系。只上报交易哈希、前端显示成功或看到钱包扣款,都不能单独作为积分入账依据。

  • 建议达到 15 个区块确认后进入可处理状态,确认数可配置。发现区块重组或确认异常时继续核对,不能先让商家处理存在争议的订单。
  • 通过链 ID、交易哈希和事件序号建立唯一记录;同一支付事件只能绑定一笔充值订单,不能被不同账号或商家重复使用。
  • 服务端创建订单时已固定充值账号、备注、商家、金额和付款钱包;付款后不允许用户修改这些核心内容来挪用其他交易。

订单状态定义

订单状态定义
状态 进入条件 商家能否标记入账
待支付充值资料已保存,尚无已确认付款否
支付确认中已取得交易哈希,等待核验及区块确认否
待核价付款核验通过,但对应价格尚未确定否
待入账付款和价格均核验完成,积分已固定是
已入账商家确认已在自己的商城完成加分已处理
已取消/支付失败用户取消且未发送,或链上交易明确失败否
待人工核对发现付款但无法安全关联订单,或核验有冲突否

支付恢复和差错处理

交易哈希须及时保存在服务端,并在本机保留恢复信息。后台持续核对已知待确认交易;页面关闭、网络中断或接口超时后,用户可重新登录继续查询,不自动重新发起付款。

当前商家合约事件不含充值订单号、手机号或备注。若钱包已经广播交易但哈希未成功回传,后台只能依据已保存订单和链上事实尝试关联;同一钱包、商家和金额存在多笔候选时进入人工核对,不按金额猜测归属。核对和绑定必须验证该付款钱包权限。

06数据权限与运行要求

订单和操作记录

订单和操作记录
记录类型 至少保存的内容
订单身份订单号、商家钱包、收款合约、付款钱包、工厂地址、链 ID、创建时间。
用户资料充值手机号、用户备注;仅限本人、对应商家和平台管理员访问。
支付凭据BNB 总额、交易哈希、事件序号、区块号、区块时间、核验结果及确认进度。
积分凭据价格来源、报价时间、计价时间、适用价格、人民币金额、积分、计算规则版本。
操作历史入驻上下架、价格人工核定、入账/撤销操作的钱包、时间、原因或备注。

权限和隐私

  • 服务器逐次校验订单归属。商家 A 即使修改网页参数或直接请求接口,也不能读取或修改商家 B 的充值资料。
  • 签名包含站点、链、用途、钱包、随机数和有效期,随机数一次性消费。登录不需要私钥,切换钱包后重新确认权限。
  • 新增配置、订单和入账操作使用明确的业务授权范围。现有后台仅用于读取商家列表的签名,不能直接扩大为新增写操作权限。
  • 手机号和备注仅保存在后台数据库,不写入链上事件或公开 URL;启用 HTTPS,列表按权限展示,访问和修改均由后台执行校验。

兼容性和数据保护

复用现有移动端视觉和钱包连接方式,覆盖主流手机钱包内置浏览器;继续采用兼容的请求超时处理。订单和历史记录持久化保存,服务重启后可恢复。部署包含数据库变更说明、备份与恢复步骤,不以浏览器缓存作为唯一订单存储。

原有付款和下架边界

只有从本次充值入口创建并正确关联的订单,才有对应的手机号和充值积分记录。原有二维码付款和手动向合约付款不自动转成充值单。管理员下架只关闭新的充值入口,不追溯取消已发送交易,也不改变原商家合约的收款权限。

07验收标准与交付边界

主要验收场景

主要验收场景
编号 通过标准
01未注册商家不能办理入驻;已注册商家经管理员上架后才出现在充值列表。
02用户可填写手机号、备注及 BNB 金额;缺失必填项或金额无效时不能继续付款。
03充值调用原商家合约 pay 方法,分佣、返利、Token A 购买与分配行为与现有商家付款一致。
04示例价 4,200 元/BNB、充值 0.1 BNB 时生成 420.00 积分,分佣不扣积分。
05失败交易、假哈希、他人交易、错误合约和重复提交不会生成可入账积分。
06达到确认数且价格确定后进入待入账;行情缺失、链上确认中均不能标记入账。
07商家使用对应钱包签名登录,只能查看自己的充值资料;跨商家接口访问被拒绝。
08重复点击和并发标记只生效一次;撤销需原因,并保存完整操作历史。
09关闭页面、刷新和服务重启后订单仍可恢复;不确定是否付款时不引导重复付款。
10商家下架后不再接受新订单,历史待处理订单可继续核对和标记。
11实时价格变化不改变已确认订单的积分;手机号和备注不出现在公开链上数据中。
12移动端关键流程可用,原有商家收款、预售和质押流程通过回归检查。

本期交付

交付新增功能源码、前端构建包、后端与数据库变更、部署配置说明、管理员和商家使用说明、测试验收清单;在现有部署环境完成一次发布协助。

范围及默认项

本期采用单一平台及 BSC 主网,不开发新智能合约、不迁移现有商家合约。备注选填且最多 200 字、手机号默认大陆格式、积分四舍五入、行情每 60 秒更新、15 个区块确认和商家可撤销误标均为本版建议默认项;开发启动时统一确认。

不含外部商城 API 自动加积分、短信或实名验证、员工子账号、批量导出、自动退款/提现、人民币收付、积分消费或转让、新 App、小程序及持续代运营。后续新增范围单独评估,详见配套报价单。