fengmengqi 6767dd538a feat: 领域/组件/服务三层目录重构 + 微信无障碍绕过方案 + 新 UI 组件体系 + 账本增删改增强

### 架构重构：三层分层目录化
  - domain 拆分为 8 个子目录（core/pipeline/rules/finance/stats/taxonomy/transaction/platform）
  - components 拆分为 6 个子目录（form/ui/layout/account/category/stats/transaction）
  - services 拆分为 5 个子目录（automation/data/ocr/security），accessibilityParser 从 automationPipeline 提取
  - 新增 ruleConfig.ts — 规则配置唯一数据源（关键词/方向/OCR 模式），与业务逻辑解耦

  ### 微信账单抓取：节点混淆绕过（核心突破）
  - BillingAccessibilityService 重命名为 SelectToSpeakService，完整伪装为系统服务
  - 同时伪装包名+类名为 com.google.android.accessibility.selecttospeak，规避微信 8.0.52+ 白名单校验
  - Config Plugin 重写：8 个 kt 文件整体复制+package 正则替换+Manifest/import 联动
  - 支付宝/微信无障碍文本解析器全面增强（方向推断/账单分类提取/付款方式提取/容错）
  - 补充文档 accessibility-wechat-guide.md（伪装原理、踩坑全记录）

  ### 新 UI 组件体系
  - Toast：全局轻量 toast（Context Provider + 入场动画 + 操作按钮 + 自动消失）
  - ErrorBoundary：React class 错误边界（降级 UI + 重试）
  - EmptyState / ConfirmDialog / SegmentedControl / Skeleton / TimePicker
  - BottomSheet 重写：SafeAreaProvider 修复、手势下滑关闭、键盘响应式避让
  - FormModal 重构：拆出 FormFields 子组件（TextField/SelectField/DropdownField）
  - 新增 PeriodSwitcher、RangeStatsCard 独立组件

  ### 新 Hooks & 工具
  - useBottomInset — 统一底部安全区留白
  - useKeyboardAvoiding — 键盘高度响应式 hook（替代 translateY 方案）
  - sanitize.ts — 日志脱敏工具提取

  ### 账本增删改增强
  - 写锁增加代际计数器（lockGeneration），reset 后旧链 pending 任务自动跳过 set
  - 新增 restoreTransaction — 撤销删除（重新追加 raw 文本到 mobile.bean）
  - 删除交易时清除去重缓存（buildTxKeyFromRaw 重建去重键），支持「删了重记」
  - editTransaction/deleteTransaction 改用 dr-id 精确定位交易块（避免同名交易定位错误）
  - appendTransactionsBatch 改从存储直接读取，避免 zustand state 不一致

  ### OCR 原生模块增强
  - 异步 initEngine 增加 CountDownLatch 等待（最多 15s），解决竞态导致的「引擎未就绪」
  - setModelDir 增加去重判断 + file:// 前缀剥离，避免冗余 reload
  - 推理链路增加分阶段耗时日志（det 推理/det 后处理/rec 识别）
  - 图片缩放策略重命名（scaleDownForOcr → capLongEdge）

  ### OCR 模型按需下载
  - 移除了启动时自动下载 ~30MB OCR 模型的逻辑
  - 改为首次使用 OCR 时才触发下载

  ### 设置页重设计
  - ScrollView → SectionList 分组卡片布局（iOS 风格分组圆角行+右侧箭头）
  - 移除 Card 组件包装，直接使用独立分组头+底部关于卡片

  ### 首页优化
  - ScrollView → FlatList（ListHeaderComponent 承载净资产卡片+待办条）
  - 日期/金额格式化增加 locale 感知（zh/en）

  ### 通知管道增强
  - NotificationChannel MD5 去重改为批量淘汰（80% 阈值），替代逐个删除
  - 增加 debug 日志输出（过滤原因/包名）

  ### ESLint
  - 新增 eslint.config.mjs（typescript-eslint + react-hooks + react-native 规则集）
  - package.json 新增 lint/lint:fix 脚本，引入 5 个 devDependencies

  ### 文档
  - accessibility-wechat-guide.md — 微信无障碍伪装完整方案
  - modal-keyboard-guide.md — 弹窗键盘避让方案
  - ocr-pipeline-guide.md — OCR 三层层级管线
  - OCR及文本模型测试 / 账单元识别及账户分类设计 / 账户分类模型测试

2026-07-28 20:57:37 +08:00

5.8 KiB

Raw Blame History

Repository Guidelines

Project Overview

DriftLedger (浮记) is an offline-first mobile client for Beancount double-entry accounting, built with React Native + Expo (CNG), TypeScript, Zustand, and expo-sqlite. The app treats desktop-maintained .bean files as the read-only source of truth and appends new entries to main.bean.

Project Structure & Module Organization

Directory	Purpose
`src/domain/`	Pure business logic (ledger parser, bill pipeline, dedup, rules, OCR processor). No React/RN imports.
`src/app/`	Expo Router file-based routes; `(tabs)/` is bottom navigation.
`src/components/`	Reusable React Native UI components and charts.
`src/store/`	Zustand stores (ledger, import, settings, metadata, automation).
`src/services/`	Platform-facing concerns (sync, backup, security, OCR bridge, automation pipeline, accessibility text parser). `src/services/automation/accessibilityParser.ts` parses WeChat/Alipay/bank accessibility node texts into `ImportedEvent`.
`src/storage/`	SQLite read-cache with versioned migrations.
`src/theme/`	Token-based theming system.
`src/i18n/`	zh/en localization dictionaries.
`plugins/`	Expo Config Plugins for native modules (ppocr, accessibility, sms-receiver, etc.).
`tests/`	Vitest unit tests (mock-backed, domain-focused).

Build, Test, and Development Commands

npm install --legacy-peer-deps   # Install dependencies (legacy-peer-deps required)
npm run start                    # Start Metro dev server
npm run android                  # Build & run on Android device/emulator
npm test                         # Run full Vitest suite
npm run typecheck                # TypeScript strict-mode check (tsc --noEmit)

# Run a single test file:
npx vitest run tests/ledger.test.ts

Coding Style & Naming Conventions

TypeScript strict mode is enabled; path alias @/* maps to src/*.
Money math uses string decimals (src/domain/decimal.ts) — never raw JS floats.
Domain layer (src/domain/) must remain pure: no React, RN, or Expo imports. Inject external dependencies via interfaces.
Code comments and plan.md are written in Chinese; match that convention.
New domain modules must be re-exported from src/domain/index.ts.
Native code lives exclusively in plugins/<name>/ as Expo Config Plugins — never edit generated android/ files directly.

Testing Guidelines

Framework: Vitest (no config file; picks up tests/**/*.test.ts by default).
Tests target the domain layer using mock backends (MemoryBackend, MockOcrEngine).
Name test files descriptively: <module-or-feature>.test.ts (e.g., decimal.test.ts, billPipeline.test.ts).
Run npm run typecheck after non-trivial changes to catch type regressions.

Commit & Pull Request Guidelines

Commit messages follow the pattern: feat: <concise summary in Chinese> with a detailed multi-line body listing changes by area.
Example: feat: 品牌重命名为浮记(DriftLedger)，全面升级精度安全与架构
PRs should describe what changed and why; link related issues. Include screenshots for UI changes.

Key Architectural Invariants

.bean files are the source of truth; SQLite is a disposable read-cache.
All bill ingestion funnels through BillPipeline (src/domain/billPipeline.ts) under a serialized mutex.
Every Config Plugin function must return config at the end.
IDs/checksums use FNV-1a hashing (hash() in ledger.ts), not crypto hashes.
Modal 弹窗脱离主窗口 context：Modal 内必须重新包 <SafeAreaProvider>，且键盘避让用响应式 paddingBottom（Math.max(insets.bottom, 24) + kbHeight），不要用 KeyboardAvoidingView 或 translateY 位移。详见 docs/modal-keyboard-guide.md。
改了 TS 后 release 包若不更新：gradle 的 bundle task 会因缓存跳过重打包，Metro 也有 transformer cache。验证 bundle 必须用 grep -a（Hermes 字节码是二进制）。详见 docs/android-build-guide.md §7。
改了原生 .kt 后必须让 android/ 副本同步：Config Plugin 的 withDangerousMod 只在 prebuild 时把 plugins/*/android/*.kt 复制到 android/ 并替换包名，直接 gradle 编译会用旧副本（「改了没生效」的另一类根因，与第 6 条的 TS bundle 缓存并列）。全量 prebuild 或「只改单个 .kt 时手动同步副本」二选一。详见 docs/android-build-guide.md §0 / §5.4。
OCR 的 det 后处理必须用连通域法（OcrModule.kt 的 dbPostprocess：4-连通 BFS + 官方 unclip 外扩 + box_score_fast 过滤），禁止回退到水平/垂直投影切行——投影法会把基线孤立小数点切到文本框外，导致 ¥143.97 识别成 ¥14397。怀疑「模型识别能力不足」前先用官方 PaddleOCR 跑同一对模型对照。详见 docs/ocr-pipeline-guide.md。
无障碍服务伪装必须包名+类名同时匹配：微信 8.0.52+ 按 ComponentName（包名/类名）识别系统服务白名单，只伪装类名无效。8 个 kt 文件整体在 Config Plugin（plugins/accessibility/app.plugin.js）里 rewrite 到 com.google.android.accessibility.selecttospeak 包，Manifest android:name 写成完整全限定名 com.google.android.accessibility.selecttospeak.SelectToSpeakService。kt 的 package 声明、物理路径、Manifest 服务名三者必须逐字一致，否则 ClassNotFoundException。改 package 重写正则时必须精确匹配源码的 com.beancount.mobile.accessibility（含 .accessibility 后缀），漏匹配会多出一段导致编译失败。伪装后 triggerManualExtraction 必须用 dumpAllTexts()（覆盖 WebView 子窗口），不能用只读 rootInActiveWindow 的旧路径。详见 docs/accessibility-wechat-guide.md。

5.8 KiB Raw Blame History Unescape Escape