动作文案与状态语义规范
目标：减少“文案看起来通过了，但语义误导用户”的问题。
背景
在交易、签名、授权等高风险流程中，确认中 这类模糊文案会掩盖真实阶段（例如：实际处于广播中）。 这类问题通常无法通过 lint / i18n key check 自动发现，必须在开发阶段做语义自检。
核心原则
1) 状态文案必须反映真实阶段
- ❌ 模糊：
确认中 - ✅ 明确：
广播中/等待上链/签名中
规则：文案要回答两个问题：
- 当前动作是什么？（签名 / 广播 / 上链确认）
- 谁在执行？（本地钱包 / 链网络）
2) UI 不直接透出底层硬编码错误
- ❌ 直接显示：
Failed to broadcast transaction - ✅ 映射到 i18n：
transaction:broadcast.failed
规则：底层 error.message 仅用于日志；展示给用户时必须走错误映射层。
3) 一次异步动作只能有一个主状态文案
- 同一时刻只显示一个“主进度词”（例如
广播中）。 - 不得在同一阶段混用
确认中+广播中两套术语。
推荐状态词典（转账示例）
| 阶段 | 推荐 key | 说明 |
|---|---|---|
| 本地签名 | common:signing | 钱包锁/私钥验证与签名中 |
| 广播交易 | transaction:txStatus.broadcasting | 向网络广播交易 |
| 等待区块确认 | transaction:txStatus.confirming | 广播成功后等待上链确认 |
| 失败 | transaction:broadcast.failed / transaction:broadcast.timeout | 用户可理解并可行动 |
开发约束
MUST
- 所有用户可见状态/错误文案必须可 i18n。
- 交易类流程必须区分
签名、广播、确认三阶段。 - 对底层错误进行统一映射（code + message pattern）。
SHOULD
- 使用纯函数做“错误 -> 文案 key”映射，便于测试。
- 为映射层补单测（timeout、broadcast failed、unknown 等）。
MUST NOT
- 在 UI 直接渲染英文异常文本。
- 用“确认中”替代所有异步状态。
AI 开发前自检清单
在改动任何状态文案/错误文案前，先逐条确认：
- 该文案是否准确描述当前真实阶段？
- 是否存在更具体的阶段词可用（签名/广播/确认）？
- 是否仍有
error.message直出到 UI？ - 是否为新增映射补了最小回归测试？
- 四语种（zh-CN/en/zh-TW/ar）是否补齐 key？