WORTHCHAIN · 商城新增功能
入驻商家充值功能需求说明
适用对象:需求方、开发方、平台管理员、入驻商家
已确认:用户支付的 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、小程序及持续代运营。后续新增范围单独评估,详见配套报价单。