Web3 商城接入参考方案
本文以 Web3 商城作为交易型 DApp 的参考案例，说明支付、履约、退款、结算和贡献成熟如何接入 Topo 链与 POC。
商城只是示例，不是唯一模型。游戏、内容、任务、流动性、供应链或其他 DApp，都可以按自己的业务语义定义成熟贡献事实，再通过可信路径进入 POC。
案例定位
交易型 DApp 通常具备以下特点：
- 用户先产生支付、锁定、预订或参与行为。
- 业务需要等待履约、确认、仲裁、锁定期或结算完成。
- 支付成功不一定代表最终贡献，因为可能发生退款、争议或撤销。
- 成熟贡献应来自链上终态或结算事实，而不是前端展示状态或本地积分。
因此，商城接入 POC 的核心原则是：支付不是贡献，履约完成和结算成熟后才形成贡献；商家资金结算和 POC 贡献发放必须解耦。
核心结论
- 商城不能把本地订单、前端积分或普通异步事件直接作为 POC 输入。
- POC 只应认可链上可信贡献路径产生的 ContributionEvent。
- 商城的 POC 贡献应以链上订单终态为基础，优先在确认收货并结算完成后生成可领取贡献。
- 支付成功事件适合驱动本地订单支付闭环，但不应直接进入 POC power。
- 退款、仲裁和异常处理必须能冻结、回退或修正待成熟贡献。
- POC 发放异常不能阻塞商家资金结算。
- POC Engine 只消费 POC 合约发出的 ContributionEvent；商城事件消费者只做本地状态同步和对账。
贡献语义
交易型 DApp 可以把业务事实分成四类：
| 事实 | 示例 | 是否适合直接进入 POC |
|---|---|---|
| 候选行为 | 下单、支付、锁定库存、创建任务 | 不适合，可作为候选贡献和审计材料 |
| 成熟前置 | 确认收货、任务验收、服务完成 | 可作为成熟条件 |
| 成熟贡献 | 结算完成、锁定期结束、权益释放 | 适合生成可发放贡献 |
| 异常修正 | 退款、仲裁、作弊、撤销 | 用于冻结、扣减或治理修正 |
商城积分、优惠、会员成长值等本地激励可以继续存在，但不能直接等同于 POC power。进入 POC 的必须是 DApp equity token 的真实发放，或者经过 POC 框架认可的可信贡献路径。
目标架构
支付流程
支付阶段要求：
- 钱包签名必须由买家发起。
- 后端必须校验交易目标函数和订单参数。
- 合约必须重新校验金额、库存、限购和支付资产。
- 支付成功只是候选贡献，不进入 POC power。
确认收货、结算和贡献发放
结算阶段要求：
- 结算交易只形成成熟贡献事实，不依赖 POC 发放成功。
- POC 发放入口必须校验成熟贡献、幂等、pause 和 custody 余额。
- POC 异常不能阻塞商家资金结算。
- 退款或仲裁发生在结算前时，必须回退或重算待成熟贡献。
- 贡献已发放后发生争议，需要通过未来贡献抵扣、治理修正或专门 reversal 机制处理。
退款和异常路径
交易型 DApp 必须把异常路径纳入状态机，而不是把退款和争议当作链下客服备注。
| 异常 | 处理原则 | POC 影响 |
|---|---|---|
| 支付后取消 | 链上恢复库存并退回资产 | 不生成成熟贡献 |
| 确认收货前退款 | 订单进入退款或仲裁状态 | 候选贡献作废 |
| 结算锁定期内争议 | 暂停结算或进入仲裁 | 待成熟贡献冻结 |
| 结算完成后争议 | 通过治理、抵扣或 reversal 处理 | 已发放贡献需要可追踪修正 |
| POC 发放失败 | 记录失败并重试或 hold | 不影响商家资金结算 |
| App 暂停 | 停止新贡献发放 | 已生效 committed power 按治理规则处理 |
系统职责
| 系统 | 职责 |
|---|---|
| Web3 前端 | 钱包连接、交易构造、状态展示、贡献状态区分、错误恢复 |
| 商城 Backend | 钱包登录、signedTx 校验、订单草稿、tx 幂等、读 API、异步任务入口 |
| 商城 Admin | 商品、库存、风控、结算、退款、仲裁和异常处理 |
| Move 合约 | 订单、资产、退款、结算、贡献成熟和事件输出 |
| 事件消费者 | 回链上读取事实，更新订单、结算、贡献和 POC 状态读模型 |
| POC Engine | 消费 ContributionEvent，按周期结算 power |
| POC Writer | 写回下一周期 staged power，并与 PowerStore 对账 |
迁移阶段
| 阶段 | 目标 | 验收 |
|---|---|---|
| 阶段 0：契约清单 | 冻结业务状态机、事件、资产、退款和贡献口径 | 业务、合约、后端和测试口径一致 |
| 阶段 1：Topo 合约 | 部署订单、资产、退款和结算基础合约 | Move 测试覆盖支付、确认、退款和结算 |
| 阶段 2：POC 准入 | 注册商城 App、equity token、custody 和权重 | Registry 状态、token 和价格来源可查 |
| 阶段 3：贡献模块 | 上线 contribution_manager | 成熟贡献、重复发放、pause 和余额不足可测试 |
| 阶段 4：读模型和对账 | 建立事件消费者、读模型、搜索和对账链路 | 链上事件可重放，读模型可修复 |
| 阶段 5：POC 结算 | 接入 Engine、Writer 和 PowerStore | ContributionEvent 到 committed power 可追踪 |
| 阶段 6：灰度上线 | 灰度真实订单和贡献发放 | 监控、告警、回滚和 hold 流程演练通过 |
接入验收
- 支付、确认收货、退款、结算和贡献发放都有明确状态机。
- 支付成功不会直接进入 POC power。
- 成熟贡献来源于链上终态或结算事实。
- POC 发放和商家资金结算解耦。
- ContributionEvent 到订单、用户、结算单和 PowerStore 可对账。
- 退款、仲裁、暂停和治理修正路径已覆盖。
- 前端能区分业务完成、贡献成熟、贡献发放、staged power 和 committed power。
- 后端 signedTx 校验覆盖 sender、chain id、合约地址、module、function、参数语义和幂等。
总结
Web3 商城参考案例的核心实现原则是：支付不是贡献，结算成熟后才形成贡献，贡献发放和商家资金结算解耦，POC Engine/Writer 周期性把可信贡献转化为 PowerStore 中的 committed power。
其他交易型 DApp 可以沿用同样思路：先找到不可逆或可治理修正的成熟业务事实，再把它接入 POC 可信贡献路径。