fix: stabilize miniapp transfer flow and UX consistency (#430)

Author: Gaubee

AGENTS.md

@@ -115,6 +115,15 @@ gh pr merge <pr#> --squash --delete-branch
 
 > 目标：避免“围绕 DOM 修修补补”导致的路径爆炸；用可验证的状态机 + 纯函数绑定 DOM。
 
+### 0) 开工前必读（强制）
+
+- 涉及 **状态文案 / 错误文案 / i18n** 的任务，开始编码前必须先阅读：
+  - `docs/white-book/09-i18n-Ref/03-Action-Status-Copy.md`
+- 不得依赖 CI 才发现“语义模糊”问题；开发阶段必须先做文案语义自检：
+  - 当前文案是否准确反映真实阶段（签名 / 广播 / 上链确认）
+  - UI 是否直接透出底层 `error.message`
+  - 是否已有统一错误映射与最小回归测试
+
 ### 1) 状态机优先（State-first）
 
 - 先把“控制层状态”定义清楚（例如：miniapp 是 `active/backgrounded`，sheet 是否 `pending/visible/resolved`）。
@@ -162,5 +171,3 @@ Use `@/openspec/AGENTS.md` to learn:
 - Project structure and guidelines
 
 Keep this managed block so 'openspec update' can refresh the instructions.
-
-<!-- OPENSPEC:END -->

docs/white-book/00-Manifesto/07-Best-Practices.md

@@ -30,4 +30,5 @@
 - CSS Modules 与 Tailwind 混用：`className={cn(styles.header, 'sticky top-0 z-10 px-5')}`
 - 优先级：CSS Modules > globals.css，组件样式应内聚到组件目录
 - ❌ as TypeAssertion → ✅ z.looseObject().safeParse() 验证外部 API 响应
+- ❌ `确认中`（模糊状态） → ✅ 使用阶段化文案（`签名中/广播中/等待上链`），详见 `09-i18n-Ref/03-Action-Status-Copy.md`
 - ❌ z.record(z.record(...)) → ✅ z.record(z.string(), z.record(z.string(), schema))（Zod 4 嵌套 record 需显式 key 类型）

docs/white-book/09-i18n-Ref/03-Action-Status-Copy.md

@@ -0,0 +1,79 @@
+# 动作文案与状态语义规范
+
+> 目标：减少“文案看起来通过了，但语义误导用户”的问题。
+
+---
+
+## 背景
+
+在交易、签名、授权等高风险流程中，`确认中` 这类模糊文案会掩盖真实阶段（例如：实际处于广播中）。
+这类问题通常无法通过 lint / i18n key check 自动发现，必须在开发阶段做语义自检。
+
+---
+
+## 核心原则
+
+### 1) 状态文案必须反映真实阶段
+
+- ❌ 模糊：`确认中`
+- ✅ 明确：`广播中` / `等待上链` / `签名中`
+
+**规则**：文案要回答两个问题：
+1. 当前动作是什么？（签名 / 广播 / 上链确认）
+2. 谁在执行？（本地钱包 / 链网络）
+
+### 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 开发前自检清单
+
+在改动任何状态文案/错误文案前，先逐条确认：
+
+1. 该文案是否准确描述当前真实阶段？
+2. 是否存在更具体的阶段词可用（签名/广播/确认）？
+3. 是否仍有 `error.message` 直出到 UI？
+4. 是否为新增映射补了最小回归测试？
+5. 四语种（zh-CN/en/zh-TW/ar）是否补齐 key？
+

docs/white-book/09-i18n-Ref/README.md

@@ -8,6 +8,7 @@
 |------|------|
 | [01-Language-Support](./01-Language-Support.md) | 支持语言、检测规范、翻译资源 |
 | [02-Localization](./02-Localization.md) | 数字/日期格式化、术语表 |
+| [03-Action-Status-Copy](./03-Action-Status-Copy.md) | 高风险动作文案与错误映射规范 |
 
 ---