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

P8：自动记账可配置化 + 模型按需下载 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 操作。不创建额外任务清单。

Goal: automation 页统一管控所有自动记账能力（规则/OCR/AI Vision 三层独立开关 + 模型下载管理 + AI 配置整合），settings/ai.tsx 删除并重定向；OCR 模型从 APK assets 改为应用内下载（filesystem 路径加载 ONNX）。

背景决策：

• 三层开关默认值：L1 规则 true、L2 OCR true、L3 AI Vision false（需用户配 API Key 后才可开启）
• 模型下载：首次启用 L2 时检查模型是否存在，无则弹出下载提示
• settings/ai.tsx 删除，原入口重定向到 automation 页
• 去重/转账识别两个 setting 字段不动（它们不是「层」而是管道的独立步骤），但在 automation 页加开关
• 模型从 assets 复制到 filesystem：预构建时仍打 APK assets 以兼容旧用户，应用首次启动将模型文件从 assets 拷贝到 documentDirectory，OcrModule 从 filesystem 加载。这样之后卸载 assets 打包就变成了纯删除（未来版本切到纯下载只需移除 assets + app.plugin.js 禁拷贝）。

---

Task 1: settingsStore 新增字段 + 迁移

Files: src/store/settingsStore.ts

• Step 1: 接口 + DEFAULTS + 持久化 + setter

在 SettingsState 接口加 5 个新字段：

/** 自动记账 L1：正则规则匹配 */
layer1RuleEnabled: boolean;
/** 自动记账 L2：本地 OCR 识别 */
layer2OcrEnabled: boolean;
/** 自动记账 L3：云端 AI Vision */
layer3AiEnabled: boolean;
/** OCR 模型版本（已下载），空字符串表示未安装 */
ocrModelVersion: string;
/** OCR 模型下载路径 */
ocrModelDir: string;

DEFAULTS：

• layer1RuleEnabled: true
• layer2OcrEnabled: true
• layer3AiEnabled: false
• ocrModelVersion: ''
• ocrModelDir: ''

PersistableSettings 加对应 5 字段；toPersistable 加 5 行；新增 5 个 setter 函数。现有 aiEnabled 保留作为 LLM 的总开关语义（layer3AiEnabled 是在 automation 页独立控制，「启用」需同时满足 aiEnabled && aiApiKey）。

注意：isNotificationListenerEnabled 这类 bridge 方法在 setFloatingBallEnabled 附近——新字段与它们无关，不加 bridge 方法。

• Step 2: 验证

npm run typecheck → 0 错误；npm test → 全绿

---

Task 2: OcrProcessor 逐级回退逻辑

Files: src/domain/ocrProcessor.ts、src/services/ocrBridge.ts、src/services/automationPipeline.ts

• Step 1: OcrProcessorConfig 扩展

OcrProcessorConfig 接口加：

layer1Enabled: boolean;  // 默认 true
layer2Enabled: boolean;  // 默认 true
layer3Enabled: boolean;  // 默认 false

• Step 2: doProcess() 逐级跳过

在 OcrProcessor.doProcess() 中修改流程（约 :103-162）：

// 1. 横屏 / 图片去重 守卫不变

// 2. L1+L2 需要 OCR 文本
if (config.layer1Enabled || config.layer2Enabled) {
  if (!ocrEngine) 返回 none（引擎不可用）
  ocrText = await ocrEngine.recognizeText(imageBase64)
  if (!ocrText) → 如果 L3 启用则 goto L3，否则返回 none
} else {
  ocrText = ''
}

// 3. Layer 1（仅当启用）
if (config.layer1Enabled && ocrText && !isDetailPage) {
  result = matchOcrRule(ocrText, packageName)
  if (result) return { layer: 'layer1-rule', ... }
}

// 4. Layer 2（仅当启用）
if (config.layer2Enabled && ocrText) {
  result = parseOcrBill(ocrText, packageName)
  if (result) return { layer: 'layer2-ocr', ... }
}

// 5. Layer 3（仅当启用）
if (config.layer3Enabled) {
  return tryLayer3(imageBase64, ocrText)
}

// 6. 全部未命中或全部关闭
return { event: null, layer: 'none', skipped: 'non-bill' }

• Step 3: automationPipeline.ts 的 getOcrProcessor 改读新字段

getOcrProcessor() 约 :116-147 行：从 settingsStore 读取 layer1RuleEnabled / layer2OcrEnabled / layer3AiEnabled 传入 OcrProcessorConfig。

• Step 4: 验证

npm run typecheck → 0 错误；npm test → 全绿

---

Task 3: 模型文件从 assets 拷贝到 filesystem + OcrModule 改路径

Files: plugins/ppocr/android/OcrModule.kt、plugins/ppocr/app.plugin.js、plugins/accessibility/android/AccessibilityBridgeModule.kt（新 bridge 方法）

• Step 1: AccessibilityBridgeModule 加 copyModelFromAssets 方法

@ReactMethod
fun copyOcrModelsFromAssets(promise: Promise) {
    try {
        val assetManager = reactContext.assets
        val destDir = java.io.File(reactContext.filesDir, "ocr_models_v6")
        if (!destDir.exists()) destDir.mkdirs()
        
        val files = listOf("ppocrv6_det.onnx", "ppocrv6_rec.onnx", "ppocrv6_dict.txt")
        for (filename in files) {
            val destFile = java.io.File(destDir, filename)
            if (destFile.exists()) continue  // skip existing
            val input = assetManager.open(filename)
            val output = java.io.FileOutputStream(destFile)
            val buffer = ByteArray(8192)
            var bytesRead: Int
            while (input.read(buffer).also { bytesRead = it } != -1) {
                output.write(buffer, 0, bytesRead)
            }
            input.close()
            output.close()
        }
        promise.resolve(destDir.absolutePath)
    } catch (e: Exception) {
        promise.reject("COPY_MODEL_FAIL", e.message)
    }
}

• Step 2: OcrModule.kt 改为 filesystem 路径加载

读 OcrModule.kt 中 createSession 调用的位置，改从传入路径加载而非 asset 文件名。当前构造可能接受 asset 路径——改为接收 filesystem 绝对路径。新增一个 @ReactMethod setModelDir(dir: String) 存储路径，或直接在 initialize(assetManager: ...) 的参数中改为 initialize(modelDir: String, ...)。

注意：ONNX Runtime Android 的 OrtEnvironment.createSession(filePath) 接受文件系统路径（String），不需要 asset 特殊处理——只需确认 createSession 的参数类支持文件路径，否则改用 OrtEnvironment.createSession(byte[] modelBytes) 从内存加载。最终方案：保持 OrtEnvironment.createSession(filePath) ，将 modelDir + "/ppocrv6_det.onnx" 作为绝对路径传入。

• Step 3: JS 侧 bridge 接口 + modelDownloader 服务

NativeAccessibilityBridge 加 copyOcrModelsFromAssets(): Promise<string> → 返回模型目录绝对路径。

新建 src/services/modelDownloader.ts：

export async function ensureOcrModels(): Promise<string> {
  // 1. 如果 settingsStore.ocrModelDir 有效且文件存在 → 直接返回
  // 2. 尝试从 assets 拷贝到 documentDirectory/ocr_models_v6
  // 3. 返回 modelsDir 绝对路径，存储到 settingsStore.ocrModelDir + ocrModelVersion
}

ocrModelVersion 在从 assets 拷贝成功后写 'v6-assets'（区分下载版本和打包版本）。

• Step 4: automationPipeline.ts 的 OcrProcessor 从 filesystem 初始化

getNativeOcrBridge()或 getOcrProcessor() 中，在初始化 OCR 引擎前调用 ensureOcrModels() 获取模型路径，传入 NativeOcrBridge 构造（或 OcrModule initialize）。

• Step 5: 验证

cd android && ./gradlew :app:compileDebugKotlin → BUILD SUCCESSFUL

---

Task 4: automation 页 UI —— 三层开关 + 模型管理 + AI 配置整合

Files: src/app/automation/index.tsx、src/i18n/zh.ts、src/i18n/en.ts

• Step 1: i18n 新键（zh/en 对等）

在 automation section 加：

autoBookkeeping         自动记账层级 / Auto Bookkeeping Layers
layer1Rule              规则匹配 / Rule Matching
layer1RuleDesc          基于正则规则的快速账单识别 / Fast regex-based bill recognition
layer2Ocr               OCR 识别 / OCR Recognition
layer2OcrDesc           本地 PP-OCRv6 模型识别 / On-device PP-OCRv6 model
layer3Ai                AI 视觉识别 / AI Vision
layer3AiDesc            云端多模态大模型识别 / Cloud multimodal LLM
layer3AiDisabled        请先配置 AI Key / Configure AI Key first
ocrModelTitle           OCR 模型 / OCR Model
ocrModelNotInstalled     未安装 / Not Installed
ocrModelInstalled       已安装 ({version}) / Installed ({version})
ocrModelInstall         安装模型 / Install Model
ocrModelInstalling      安装中... / Installing...
ocrModelCopying         正在复制模型文件... / Copying model files...
dedupSwitch             多通道联合去重 / Cross-channel Dedup
transferSwitch          转账智能识别 / Transfer Recognition

• Step 2: automation 页 UI 重组织

在现有截图监控按钮 Card 之后加以下新 Card 区块：

Card A：「自动记账层级」

• 三行 Switch：L1 规则匹配（always enabled，不依赖外部条件）
• L2 OCR 识别（Switch；开启时检查模型→无模型则弹下载提示 Dialog）
• L3 AI 视觉（Switch；如果 aiEnabled=false 或 aiApiKey 为空则 disabled+提示文字；开启后展开 Provider/Key/Model 输入）

Card B：「OCR 模型」

• 状态行：版本号（未安装显示灰色「未安装」；已安装显示绿色「已安装 (v6-assets)」）
• 操作按钮：安装/重新安装（从 assets 拷贝 → 进度状态 → 完成）

Card C：「管道设置」（复用现有 Card B 和 C 部分）

• dedupEnabled Switch

• transferRecognitionEnabled Switch

• Step 3: 操作逻辑

// 模型安装
const handleInstallModel = async () => {
  setModelStatus('installing');
  try {
    const bridge = getAccessibilityBridge();
    if (!bridge) throw new Error('Bridge unavailable');
    const modelDir = await bridge.copyOcrModelsFromAssets();
    setOcrModelVersion('v6-assets');
    setOcrModelDir(modelDir);
    setModelStatus('done');
  } catch (e) {
    setModelStatus('error');
    Alert.alert('安装失败', String(e));
  }
};

// L2 开关变化时检查模型
const handleL2Toggle = (val: boolean) => {
  setLayer2OcrEnabled(val);
  if (val && !ocrModelVersion) {
    Alert.alert(t('automation.ocrModelTitle'), t('automation.ocrModelNotInstalled'), [
      { text: t('common.cancel'), onPress: () => setLayer2OcrEnabled(false) },
      { text: t('automation.ocrModelInstall'), onPress: handleInstallModel },
    ]);
  }
};

// L3 开关变化时检查 AI Key
const handleL3Toggle = (val: boolean) => {
  if (val && (!aiEnabled || !aiApiKey)) {
    Alert.alert(t('automation.layer3Ai'), t('automation.layer3AiDisabled'));
    return;
  }
  setLayer3AiEnabled(val);
};

• Step 4: AI 配置内联

L3 启用时展开的子区域：

• aiProviderId：三选一 chip（openai/gemini/deepseek）

• aiApiKey：输入框（secureTextEntry）

• aiBaseUrl：输入框（默认值 placeholder）

• aiModel：输入框（默认值 placeholder）

• aiEnabled：Switch（总开关，控制 L3 的实际可用性）

• Step 5: 验证

npm run typecheck → 0 错误；npm test → 全绿

---

Task 5: AI 设置页清理 + settings 导航更新

Files: src/app/settings/ai.tsx（重写为跳转）、src/app/(tabs)/settings.tsx（更新入口文案）

• Step 1: settings/ai.tsx 改为 redirect

不删除文件（保留路由），但内容改为：useEffect(() => { router.replace('/automation'); }, []) 跳转到 automation 页，期间显示 loading。

• Step 2: settings.tsx 入口文案

src/app/(tabs)/settings.tsx 中「智能记账 & AI」入口的文案保持不变，但实际点击跳转已由 expo-router 自动处理（ai.tsx → redirect → automation），不需要改路由注册。

• Step 3: 验证

npm run typecheck → 0 错误；npm test → 全绿 grep -rn "settings/ai" src/app/(tabs)/settings.tsx → 确认无需改动即可跳转

---

Task 6: 编译 + 测试 + 终审

• Step 1: Kotlin 编译

cd android && ./gradlew :app:compileDebugKotlin → BUILD SUCCESSFUL

• Step 2: 全量测试

npm test → 全绿；npm run typecheck → 0 错误

• Step 3: 审计

grep -rn "#[0-9A-Fa-f]\{6\}" src/ --include="*.ts" --include="*.tsx" | grep -v "theme/presets.ts\|theme/palette.ts"   # 无输出
grep -rn "fontFamily" src/app/automation/index.tsx                                                               # 无输出
grep -rn "📊|💰|💸|📝" src/app/automation/                                                                       # 无输出

• Step 4: 手工走查清单

1. settings 页点「智能记账」→ 跳转到 automation 页
2. automation 页看到三个层级开关（L1 默认开 / L2 默认开 / L3 默认关灰）
3. 关闭 L1 → 仍可记账（走 L2 OCR）
4. 关闭 L2 → L1 失败不再调用 OCR
5. 开启 L3 → 提示配 AI Key → 配置后可用
6. OCR 模型未安装 → 点安装 → 从 assets 拷贝 → 显示绿色已安装
7. L2 开关关闭再打开 → 已有模型直接可用，不再提示
8. AI Provider 切换 openai/gemini/deepseek → 对应的 baseUrl 默认值变化

---

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

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

#	级别	问题	处理
—	—	无 Critical / Important 发现	—

偏差说明：

1. 管道设置 Card 复用现有 settings.dedupLabel/settings.transferLabel i18n 键（已在 settings/ai.tsx 中使用），未新键 dedupSwitch/transferSwitch——避免重复键。
2. OcrModule.kt 从 assets 加载路径改为 modelDir 字段 + setModelDir 方法——保留原 assets 加载作为兜底（modelDir 为空时走原路径），保证向后兼容。
3. ensureOcrModels() 在 _layout.tsx ready 前调用一次（异步非阻塞），getOcrProcessor() 中也传 ocrModelDir 作为安全网。