安全、测试、可观测性与上线清单

本文面向安全、测试、运维和交付团队，汇总 Topo DApp 上线前需要满足的钱包登录、资产金额、权限暂停、测试矩阵、监控对账、反模式和开发顺序要求。

这份清单既适用于普通 Topo DApp，也适用于接入 POC 的 DApp。涉及 POC 的部分，应额外验证 ContributionEvent、周期结算、staged power 和 committed power 的对账链路。

安全基线

钱包登录

钱包登录必须满足：

1. nonce 由服务端生成，设置短 TTL。
2. nonce 按钱包地址存储，登录成功后一次性消费。
3. 签名消息必须包含域名、chain id、nonce、过期时间和用途。
4. 签名公钥必须能推导出提交的钱包地址。
5. 后台钱包登录不能弱于会员钱包登录。

资产和金额

资产和金额必须满足：

1. 支付资产由链上或配置化注册表管理。
2. decimals 从资产 metadata 读取，并限制边界。
3. 业务价格精度和支付资产精度有明确换算。
4. 小额订单换算不能变成 0。
5. 大额订单和多件商品必须做溢出测试。
6. 前端展示金额、后端校验金额、合约扣款金额必须可对账。

权限和暂停

权限和暂停必须满足：

1. 超级管理员、多签或治理地址初始化明确。
2. 用户、商户、运营、财务、结算、POC 管理权限分离。
3. 敏感参数更新有延迟生效或多签。
4. 高风险模块支持 pause。
5. pause 不应破坏用户提现、退款或必要恢复路径，除非是明确的紧急冻结。

日志和密钥

禁止记录：

1. 完整 Authorization header。
2. 钱包 API key。
3. signedTx 完整原文。
4. nonce 原文。
5. 私钥、管理员密钥或生产 DSN。

测试矩阵

合约测试

必须覆盖：

1. 正常创建、支付、确认、结算、贡献成熟和贡献发放。
2. 金额为 0、换算为 0、溢出、decimals 边界。
3. 库存不足、重复业务项、限购和时间窗口。
4. 退款申请、拒绝、通过、重复处理。
5. 权益锁定、释放、回退。
6. 贡献重复发放、pause、custody 余额不足。
7. 权限不足、错误 signer、错误资产。
8. 事件字段和 view 返回值。

后端测试

必须覆盖：

1. 钱包登录 nonce 过期、重复使用、地址不匹配。
2. signedTx 反序列化失败。
3. sender 不匹配。
4. chain id 错误。
5. 合约地址、module、function 错误。
6. 参数数量和泛型参数错误。
7. 参数语义篡改。
8. tx hash 重复提交和 pending 恢复。
9. 链上成功但本地异步任务写入失败。
10. 链上失败但本地状态已 pending。

消费者测试

必须覆盖：

1. 重复事件。
2. 已处理业务对象。
3. 链上事件缺失。
4. 链上事件字段解析失败。
5. 本地事务失败。
6. handle_status=1 崩溃后 lease 回收。
7. 搜索增量同步和兜底同步。
8. POC ContributionEvent 与 DApp 贡献发放事件对账。

端到端测试

每次重要发版至少跑通：

1. Web3 登录。
2. 业务对象创建。
3. 支付或资产锁定。
4. 确认完成。
5. 退款或异常处理。
6. 结算。
7. 成熟贡献生成。
8. POC 贡献发放。
9. POC staged power 写入。
10. POC committed power 展示。

可观测性

必须观测：

指标	目的
RPC 请求失败率	判断链节点或上游服务状态
交易提交失败率	发现钱包、后端、合约或参数问题
tx pending 数量和时间	发现未确认或待恢复交易
event_bus 积压	发现消费者滞后
链上事件解析失败数	发现 ABI 或事件字段变更
读模型落后时间	衡量用户看到状态的延迟
POC ContributionEvent 数量	衡量 DApp 贡献发放
POC 价格快照失败数	发现 Coinfair 价格输入问题
POC Writer 写回失败数	发现 PowerStore 写回问题
搜索同步失败数	发现查询投影不一致

推荐对账视图：

wallet address
  -> local member
  -> business object id
  -> tx hash
  -> chain event
  -> read model state
  -> mature contribution
  -> ContributionEvent
  -> POC period
  -> staged power
  -> committed power

上线检查清单

配置

• chain id 与目标 Topo 网络一致。
• RPC 和 Indexer endpoint 配置化。
• 合约地址配置化。
• 支付资产 metadata 和 symbol 配置一致。
• DApp equity token 的 Coinfair 市场已建立。
• POC Registry 中 App 已注册、白名单、custody 和权重已确认。
• custody 地址和 DApp 贡献模块使用地址一致。
• Gateway Host/Profile 已区分公网、Web3、管理和 internal 入口。
• 生产环境没有前端 API key、私钥和管理员密钥。

安全

• 会员和后台钱包登录都有 nonce 一次性消费。
• 所有 signedTx API 有 ABI 清单。
• 日志脱敏 Authorization、signedTx、API key、nonce。
• 内部路径不能公网访问。
• 链上管理入口只开放给管理 Profile。
• 关键合约参数更新需要多签或治理延迟。
• pause 和恢复流程已演练。

数据和运维

• event_bus.handle_status 语义未改变。
• 消费者有 lease 回收。
• tx pending 扫描已启用。
• 链上事件到读模型可对账。
• 搜索增量同步和兜底同步都已验证。
• POC ContributionEvent 到周期账本和 PowerStore 可对账。
• 异常周期、价格快照失败和 Writer 失败有 hold 流程。

常见反模式

反模式	风险	正确做法
前端直连多个内部服务	CORS、密钥、路径和限流失控	统一走 Gateway
后端只转发 signedTx	错误交易可进入链上	后端做入口校验和参数语义校验
只验证交易可解析	合法交易仍可能篡改业务参数	校验 module、function、sender、参数语义
本地 DB 状态当链上真相	本地状态可能落后或被修复	链上事件和 view 是最终事实
event payload 直接写搜索文档	字段不完整或过期	回源查询完整读模型
支付成功立即给 POC power	退款和未履约订单会膨胀贡献	结算成熟后发 POC 贡献
把本地积分当 POC power	破坏 POC 可信边界	equity token 可信发放后进入 POC
POC 发放阻塞业务结算	POC 异常影响资金结算	结算状态和 POC 发放状态解耦
前台和管理后台入口混用	高风险链上入口误开放	Profile、权限和后台入口分离

推荐开发顺序

步骤	产物	验收
步骤 0	状态机、事件清单、资产和贡献口径	业务、合约、后端和测试口径一致
步骤 1	Move 合约、事件、view、初始化脚本	Move 测试覆盖关键路径
步骤 2	API 到 ABI 清单	每个 signedTx 入口有 sender、function、参数语义说明
步骤 3	后端入口、tx log、pending 恢复	重复提交和失败恢复可验证
步骤 4	Consumer、读模型、搜索投影	链上事件可重放、读模型可对账
步骤 5	Registry、equity token、custody、价格来源	App POC 资格和价格输入可查
步骤 6	contribution_manager	成熟贡献、重复发放、pause、余额不足均可测试
步骤 7	Engine/Writer 对账	staged 和 committed power 可追踪
步骤 8	灰度、监控、回滚和 hold 流程	异常处理流程演练通过

总结

上线前最重要的是证明三件事：

1. 链上事实可验证：资产、权限、状态机和事件由合约保护。
2. 链下系统可恢复：交易入口、消费者、读模型和搜索投影可以重放、修复和对账。
3. POC 链路可审计：ContributionEvent、周期结算、staged power 和 committed power 可以完整追踪。

只有这三件事都成立，DApp 才具备对外发布和接入 POC 的基础。