DriftLedger/docs/design/ui-redesign-p6-plan.md

UI 重设计 P6：原生浮层（悬浮球/悬浮窗）重设计 Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax. 不执行任何 git add/commit（用户要求，改动留工作区）。不创建额外任务清单。

Goal: 原生浮层（FloatingHelper 悬浮球 / FloatingBillView 浮窗 / FloatingTip 提示）视觉与文案对齐新设计系统：颜色与文案由 JS 层（theme tokens + i18n）通过 bridge 下发，原生不再硬编码中文与旧靛蓝；悬浮球位置持久化；浮窗补币种字段；前台账单 Alert i18n 化并去 emoji。

背景决策（已确认）：

• 原生 View 无法直接用 RN theme，采用 FloatingUiConfig 下发模式：JS 侧从当前 theme + i18n 构建 config → bridge setFloatingUiConfig() → 原生存 SharedPreferences（JSON）→ 三个浮层组件读取。原生保留现有硬编码值作为默认值兜底（JS 未推送时行为不变）。
• 浮窗卡片跟随 App 主题（浅色=白卡近黑 accent，深色=OLED 黑卡白 accent），卡片用实色（不再半透明磨砂），保证在其他 App 上的可读性。
• 浮窗金额校验从 toDoubleOrNull 改正则 + BigDecimal；自动消失 15s → 30s。
• 改动范围：plugins/accessibility/（Kotlin）+ src/services/（bridge/config）+ src/app/_layout.tsx + src/services/automationPipeline.ts + src/i18n/。不碰 domain 写路径。

---

FloatingUiConfig 契约（T1-T5 共同遵守，先读这里）

JS → 原生：setFloatingUiConfig(config: ReadableMap): Promise<boolean>

interface FloatingUiConfig {
  colors: {
    accent: string;      // 按钮/选中态背景（= theme accent：light #111318 / dark #F3F4F6）
    accentFg: string;    // accent 上的文字色（= fgInverse）
    cardBg: string;      // 卡片底色（= bgSecondary）
    inputBg: string;     // 输入框/未选中 chip 底色（= bgTertiary）
    fgPrimary: string;
    fgSecondary: string;
    border: string;
    income: string;      // financial.income
    expense: string;     // financial.expense
    transfer: string;    // financial.transfer
  };
  labels: {
    billTitle: string;        // 浮窗标题
    dirExpense: string; dirIncome: string; dirTransfer: string;
    amountLabel: string; payeeLabel: string;
    narrationLabel: string; narrationHint: string;
    categoryExpense: string;  // 「交易分类」
    categoryIncome: string;   // 「收入分类」
    transferTarget: string;   // 「转入账户」
    accountExpense: string;   // 「资金来源」
    accountIncome: string;    // 「存入账户」
    accountTransfer: string;  // 「转出账户」
    openApp: string; dismiss: string; confirm: string;
    ballOcr: string;          // 悬浮球「识别账单」
    ballRemember: string;     // 「记住此页」
    rememberSuccess: string;  // 记住页面成功提示（不含 emoji）
    rememberFail: string;     // 失败提示前缀（原生拼接 ': ' + e.message）
    pageRemembered: string;   // BillingAccessibilityService Toast「已记住页面签名」前缀
    pageSignatureExists: string; // 「该页面签名已存在」前缀
  };
}

• 颜色一律 "#RRGGBB" 六位数 hex（theme tokens 里有 rgba 的字段不要直接下发——accent/cardBg/fg/border 等都是纯色，确认无 rgba；border 深色主题是 rgba(255,255,255,0.08)，下发前换算为 hex：深色用 #14202429? 不许发明值——正确做法：原生 Color.parseColor 支持 #AARRGGBB，JS 侧把 rgba(255,255,255,0.08) 换算为 #14FFFFFF（alpha 0.08≈0x14）。写一个 rgbaToHex 小工具处理这种情况，纯色 hex 原样通过）。
• 原生端用 Color.parseColor 解析，异常时回退默认值。

原生持久化

• SharedPreferences 文件名：floating_ui_config，单键 config_json 存整个 JSON。
• 新增 FloatingUiConfigStore.kt（object）：save(context, ReadableMap) / load(context): FloatingUiConfig（data class，字段缺省值=现状硬编码值，保证旧 JS 行为不变）。
• FloatingUiConfig data class 字段名与上面契约一致（camelCase）。

事件契约变更（T3+T5）

• showFloatingBill 增加参数 currency: String（放在 direction 之后、draftId 之前）。
• billingConfirmed / billingOpenApp 事件 map 增加 putString("currency", currentCurrency)。
• 浮窗金额行左侧显示当前币种 chip，点击在 listOf("CNY","USD","HKD","JPY","EUR","GBP") 中循环切换；初始值 = 传入 currency（不在列表则插入到首位）。

---

Task 1: JS 侧 — i18n 键 + floatingUiConfig 服务 + bridge 接口 + 推送接线 + 前台 Alert i18n

Files:

• Modify: src/i18n/zh.ts、src/i18n/en.ts、src/services/accessibilityBridge.ts、src/app/_layout.tsx、src/services/automationPipeline.ts

• Create: src/services/floatingUiConfig.ts、tests/floating-ui-config.test.ts

• Step 1: i18n 新增 floating.* 键组（zh/en 对等，%{name} 插值语法）

floating.billTitle        调整交易草稿 / Adjust Draft
floating.dirExpense       支出 / Expense        （复用现有方向键也行，但浮层独立一组避免耦合）
floating.dirIncome        收入 / Income
floating.dirTransfer      转账 / Transfer
floating.amountLabel      金额 / Amount
floating.payeeLabel       交易对手 / Payee
floating.narrationLabel   描述/备注 / Narration
floating.narrationHint    输入交易叙述 / Enter narration
floating.categoryExpense  交易分类 / Category
floating.categoryIncome   收入分类 / Income Category
floating.transferTarget   转入账户 / To Account
floating.accountExpense   资金来源 / From Account
floating.accountIncome    存入账户 / To Account
floating.accountTransfer  转出账户 / From Account
floating.openApp          打开应用 / Open App
floating.dismiss          忽略 / Dismiss
floating.confirm          确认入账 / Confirm
floating.ballOcr          识别账单 / Scan Bill
floating.ballRemember     记住此页 / Remember Page
floating.rememberSuccess  已将当前页面加入识别白名单 / Page added to recognition whitelist
floating.rememberFail     记录失败 / Failed to save
floating.pageRemembered   已记住页面签名 / Page signature saved
floating.pageSignatureExists 该页面签名已存在 / Page signature already exists

（若现有键已有同文案可复用，但键组保持独立 floating.*；先 grep 避免重复键名。）

同时给前台 Alert 加键（放 automation.* 下，先读现有 automation 节）：

automation.billDetectedTitle     识别到新账单 / New Bill Detected   （无 emoji）
automation.billDetectedReject    拒绝/丢弃 / Discard
automation.billDetectedEdit      修改并入账 / Edit & Save
automation.billDetectedConfirm   确认入账 / Confirm

Alert 的多行消息体（日期/商户/金额/分类/账户/叙述）逐行用既有标签键拼，不为每行加新键（行标签可复用表单/详情现有键，先 grep transaction.payee 之类；没有合适的就在 automation 节加 billDetectedLine* 键）。

• Step 2: src/services/floatingUiConfig.ts

export interface FloatingUiConfig { colors: {...}; labels: {...} }  // 按契约

/** rgba(r,g,b,a) → #AARRGGBB；#RRGGBB 原样返回。 */
export function colorToHex(color: string): string;

/** 从 theme tokens + t() 构建完整 config。 */
export function buildFloatingUiConfig(theme: ThemeTokens, t: TranslateFn): FloatingUiConfig;

/** 构建并推送到原生（bridge 不可用时静默返回 false）。 */
export async function pushFloatingUiConfig(theme: ThemeTokens, t: TranslateFn): Promise<boolean>;

• Step 3: bridge 接口扩展

accessibilityBridge.ts：NativeAccessibilityBridge 加 setFloatingUiConfig(config: FloatingUiConfig): Promise<boolean>;，文件头注释方法清单补一行。showFloatingBill 签名加 currency: string（direction 之后、draftId 之前）。

• Step 4: _layout.tsx 推送接线

• 启动时（setFloatingBallEnabled 同一处，src/app/_layout.tsx:139 附近）也 pushFloatingUiConfig(...)。注意此处拿不到 useTheme 的 theme（在 ThemeProvider 外层？先读 _layout 结构确认）——若拿不到，启动这次推送可移到下一步的组件里统一做，避免重复。

• 在 ThemeProvider 内部挂一个小组件（如 FloatingUiConfigSyncer，可直接写在 _layout.tsx 里）：const { theme } = useTheme(); const t = useT(); useEffect(() => { pushFloatingUiConfig(theme, t); }, [theme, t]) —— 主题切换/语言切换/启动都会重推。t 引用随 locale 变化（确认 useT 返回的 t 在语言切换时引用变化，先读 src/i18n 实现；若 t 引用稳定，则依赖里加 locale）。

• Step 5: automationPipeline.ts 前台 Alert i18n + 去 emoji

src/services/automationPipeline.ts:298 的 Alert.alert('🌟 识别到新账单', ...)：标题/按钮全部改 t()；消息体保留原信息结构。该文件是 service 层非组件——确认文件里如何拿 t（若没有，用 i18n.t(...) 直接调，读 src/i18n/index.ts 导出了什么）。showFloatingBill 调用处（:262）传第 7 个参数 currency（用 :225 已提取的 currency 变量）。

• Step 6: 测试 + 验证

tests/floating-ui-config.test.ts：

• colorToHex：'#111318' 原样；'rgba(255,255,255,0.08)' → #14FFFFFF；'rgba(17,19,24,0.4)' → #66111318（alpha 四舍五入 Math.round(a*255)）
• buildFloatingUiConfig：用 lightTheme + 真实 zh t() 构建，断言 colors.accent === '#111318'、labels.billTitle === '调整交易草稿'、所有契约字段非空（遍历 keys）

Run: npm run typecheck && npm test → 全绿（i18n parity 测试覆盖新键）

---

Task 2: 原生 config 基础设施（FloatingUiConfigStore + bridge 方法 + FloatingTip/Toast 改读）

Files:

• Create: plugins/accessibility/android/FloatingUiConfigStore.kt

• Modify: plugins/accessibility/android/AccessibilityBridgeModule.kt、plugins/accessibility/android/FloatingTip.kt、plugins/accessibility/android/BillingAccessibilityService.kt

• Step 1: FloatingUiConfigStore.kt

• data class FloatingUiConfig(...)：colors/labels 全部字段，默认值 = 现状硬编码（accent #5E6AD2、cardBg #FF050506? —— 不：默认值应是「现状视觉」，但现状 cardBg 是 0x8C050506 半透明。默认 cardBg 用 #F2050506? 简化：默认值就用现状各硬编码颜色换算成 #AARRGGBB/#RRGGBB 字符串，逐字段列注释对应原 Kotlin 常量）。labels 默认值 = 现状中文硬编码文案（去 emoji）。

• object FloatingUiConfigStore：private const val PREFS = "floating_ui_config"；fun save(context: Context, map: ReadableMap)（遍历契约字段，缺失字段跳过不覆盖，JSONObject 组装后写入）；fun load(context: Context): FloatingUiConfig（JSONObject 读取，缺失/解析失败逐字段回退默认；optString）。颜色字段提供 fun parseColorOr(value: String, fallback: Int): Int 工具（Color.parseColor try/catch）。

• org.json 可用（Android 内置），无需新依赖。

• Step 2: AccessibilityBridgeModule.setFloatingUiConfig

@ReactMethod
fun setFloatingUiConfig(config: ReadableMap, promise: Promise) {
    try {
        FloatingUiConfigStore.save(reactContext, config)
        promise.resolve(true)
    } catch (e: Exception) {
        promise.reject("CONFIG_SAVE_FAIL", e.message)
    }
}

• Step 3: FloatingTip/RepeatToast 改读 config

• FloatingTip.show()：背景色 0xF0333333 → config accent（不透明化：解析后 or 0xFF000000.toInt()），文字色 → accentFg，ProgressBar progressTintList 设 accentFg。构造签名加可选 config: FloatingUiConfig? = null，null 时内部 FloatingUiConfigStore.load(context)。

• RepeatToast 的 "⚠ $message" 前缀 emoji 去掉，只留 message（⚠ 属 emoji 审计范围）。

• FloatingTip 调用处（FloatingHelper.kt:209/211）改传 config 文案：labels.rememberSuccess、"${labels.rememberFail}: ${e.message}"（T4 做也可以，此处先改文案读取，FloatingHelper 的彻底重设计在 T4）。

• Step 4: BillingAccessibilityService 两处 Toast 文案

:387 "已记住页面签名:\n$sig" 与 :419 "该页面签名已存在:\n$sig" → 改读 FloatingUiConfigStore.load(this).labels 的 pageRemembered / pageSignatureExists + ":\n$sig"。

• Step 5: 编译验证

android/ 已生成。把改动的 .kt 手动拷到 android/app/src/main/java/com/beancount/mobile/accessibility/（与 plugins 目录同名文件覆盖），然后： Run: cd android && ./gradlew :app:compileDebugKotlin -q → BUILD SUCCESSFUL （若编译环境不可用，记录为设备验证项并在报告中说明。）

---

Task 3: FloatingBillView 重设计 + 币种

Files:

• Modify: plugins/accessibility/android/FloatingBillView.kt、plugins/accessibility/android/AccessibilityBridgeModule.kt（showFloatingBill 加 currency 参数透传）

视觉规格（对齐 docs/ui-redesign-design.md §3 Bento）：

• 卡片：实色 cardBg、圆角 16dp、1dp border 描边、padding 16dp（原 12/8 加宽）

• 标题：fgPrimary 13sp bold；分段选择器：选中=accent 底 accentFg 字，未选中=透明 fgSecondary 字，圆角 6dp

• 字段标签：fgSecondary 10sp bold；输入框：inputBg 底、圆角 10dp、1dp border、fgPrimary 字、hint fgSecondary

• chips：圆角 999（用 dp(14f) 近似胶囊）、未选中=inputBg+border 描边+fgSecondary 字、选中：分类行支出/收入=accent；转账方向第一行=transfer 色；账户行按方向=income/expense 色（语义色保留，但改从 config 读）

• 按钮：高 40dp、圆角 12dp；confirm=accent 底 accentFg 字 bold；openApp/dismiss=inputBg 底 fgPrimary 字

• 所有颜色经 FloatingUiConfigStore.load(context) + parseColorOr 兜底；所有文案经 labels

• Step 1: 构造签名 + showFloatingBill 参数

FloatingBillView 构造加 initialCurrency: String = "CNY"；AccessibilityBridgeModule.showFloatingBill 加 currency: String 参数（direction 后 draftId 前）并透传。

• Step 2: 币种 chip

金额行：水平布局，左侧币种 chip（inputBg+border，fgPrimary 字，显示 currentCurrency），右侧金额输入框（weight 1）。点击 chip 在 listOf("CNY","USD","HKD","JPY","EUR","GBP") 循环（initialCurrency 不在列表则临时插到首位）。sendSaveEvent/sendOpenAppEvent 的 map 加 putString("currency", currentCurrency)。

• Step 3: 金额校验改正则 + BigDecimal

afterTextChanged：Regex("^\\d+(\\.\\d{1,2})?$") 匹配且 BigDecimal(text) > BigDecimal.ZERO 才启用保存（BigDecimal 构造 try/catch）。禁用时按钮底色 inputBg + fgSecondary 字。

• Step 4: 全面替换颜色与文案 + 自动消失 30s

逐段按上面视觉规格重写 show() 与 rebuildChips()（结构不变，只换色值来源、文案来源、尺寸）；15000L → 30000L。标签按方向切换的文案（交易分类/收入分类/转入账户、资金来源/存入账户/转出账户）全部走 labels。

• Step 5: 编译验证（同 T2 Step 5 流程）

---

Task 4: FloatingHelper 重设计 + 位置持久化

Files:

• Modify: plugins/accessibility/android/FloatingHelper.kt

• Step 1: 颜色与文案走 config

• 指示竖线：accent（保持 70% 透明度：解析后 alpha 设为 0xB0）

• 菜单：实色 cardBg、圆角 12dp、1dp border

• 「识别账单」按钮：accent 底 accentFg 字（主操作）；「记住此页」：inputBg 底 fgPrimary 字；按压态透明度变化保留（按下时 alpha 0.8）

• ScanIconDrawable/PinIconDrawable 颜色：Scan 用 accentFg（在 accent 底按钮上），Pin 用 fgSecondary

• 文案 labels.ballOcr / ballRemember / rememberSuccess / rememberFail（带 ': ' + message 拼接）

• Step 2: 位置持久化

• SharedPreferences 复用 billing_accessibility_prefs：键 floating_ball_x / floating_ball_y

• show() 初始化：params.x/y = prefs.getInt(...)，无键时用现状默认（0/400）；拖动抬起（吸附后）写 prefs

• companion 的 lastX/lastY 保留为进程内缓存但初始从 prefs 读（或直接用局部变量+prefs，简化则删 companion——注意多实例语义，BillingAccessibilityService 单例，安全）

• Step 3: 编译验证（同 T2 Step 5 流程）

---

Task 5: 币种链路 JS 消费侧

Files:

• Modify: src/services/automationPipeline.ts、src/app/_layout.tsx

• Step 1: billingConfirmed 处理器用 res.currency

读 src/services/automationPipeline.ts:50-110 的 handleBillingConfirmed：const currency = pending?.event?.currency || 'CNY'（:78）→ 优先 res.currency（浮窗用户改过），res.currency || pending?.event?.currency || 'CNY'。确认 res 类型定义处加 currency 字段（NativeOpenAppEvent 之类，grep 类型声明一起改）。

• Step 2: billingOpenApp 处理器

src/app/_layout.tsx:255 const currency = 'CNY' → const currency = res.currency || 'CNY'。

• Step 3: 验证

Run: npm run typecheck && npm test → 全绿

---

Task 6: P6 审计 + 验收

• Step 1: 审计

grep -rn "0xFF5E6AD2\|0x995E6AD2\|0xB05E6AD2\|0x1F5E6AD2\|0x405E6AD2" plugins/accessibility/android/   # 无输出（旧靛蓝清零，默认值除外——FloatingUiConfigStore 默认值允许保留并注释）
grep -rn '"[^"]*[一-鿿]' plugins/accessibility/android/*.kt | grep -v "FloatingUiConfigStore\|//"      # 除 Store 默认值与注释外无硬编码中文 UI 字符串
grep -rn "⚠\|📌\|🌟" src/ plugins/                                                                     # 无输出
grep -n "currency" src/services/accessibilityBridge.ts                                                  # showFloatingBill 含 currency

• Step 2: 全量测试 + typecheck + Kotlin 编译

Run: npm test → 全绿；npm run typecheck → 无错误；cd android && ./gradlew :app:compileDebugKotlin -q → 成功

• Step 3: 手工走查（需设备）

Run: npm run android

1. 设置里切换 浅/深主题 → 触发一次浮窗（可用 automation 页调试入口或真实账单）→ 浮窗颜色跟随主题
2. 切换英文 → 浮窗/悬浮球/提示文案全英文
3. 拖动悬浮球 → 杀进程重启无障碍服务 → 位置保持
4. 浮窗点币种 chip 切换 USD → 确认入账 → 交易币种为 USD
5. 金额输入 1e10 / 0 / 0.005 → 保存按钮禁用；12.50 → 可用
6. 浮窗 30 秒无操作自动消失；触摸后不消失

---

终审修订（已实施，以实际代码为准）

终审日期：2026-07-22，审计 598 测试全绿、typecheck 干净、Kotlin BUILD SUCCESSFUL。

#	级别	问题	修复
C1	Critical	FloatingBillView 标题 setTextColor(colorAccentFg) — 浅色主题下白卡白字、深色主题下黑底黑字，标题不可见	改为 colorFgPrimary
I1	Important	容器边框从 accent 派生 alpha 而非用 config.border	删除 colorContainerBorder，直接使用 colorBorder
I2	Important	FloatingHelper btnRemember 背景从 fgPrimary 派生，计划要求 inputBg	加 colorInputBg 解析，btnRemember 改从 inputBg 派生
I3	Important	悬浮球菜单背景半透明（65% cardBg），计划要求实色	菜单背景直接使用 colorCardBg（full opacity），仅描边保留半透明
M1	Minor	FloatingTip 背景未强制不透明化（plan §T2 Step 3）	加 or 0xFF000000.toInt() 保护
M2	Minor	金额校验先 BigDecimal 解析再正则，正则先匹配可早期短路	调整为先 pattern.matches(text) 再 value != null && value > BigDecimal.ZERO

偏差说明（无需修复）：

• FloatingHelper 菜单背景 / 按钮背景 / 指示线的 alpha 分量组合（(colorX and 0x00FFFFFF) or alpha）是原生浮层叠加其他 App 所必需的透明度控制，不是颜色硬编码。颜色 RGB 分量完全来自 config。
• FloatingTip 默认 fallback #FF000000 是纯黑（非靛蓝），因为 accent 在极浅色主题下是 #111318（近黑），fallback 用黑色是安全的极限退化。
• ScanIconDrawable laserColor 0xFFF87171 保留为语义色（扫描红光），不受主题控制。