6767dd538a
### 架构重构：三层分层目录化 - 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及文本模型测试 / 账单元识别及账户分类设计 / 账户分类模型测试
68 lines
5.8 KiB
Markdown
68 lines
5.8 KiB
Markdown
# Repository Guidelines
|
||
|
||
## Project Overview
|
||
|
||
DriftLedger (浮记) is an offline-first mobile client for [Beancount](https://beancount.github.io/) 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
|
||
|
||
```bash
|
||
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
|
||
|
||
1. `.bean` files are the source of truth; SQLite is a disposable read-cache.
|
||
2. All bill ingestion funnels through `BillPipeline` (`src/domain/billPipeline.ts`) under a serialized mutex.
|
||
3. Every Config Plugin function **must `return config`** at the end.
|
||
4. IDs/checksums use FNV-1a hashing (`hash()` in `ledger.ts`), not crypto hashes.
|
||
5. **Modal 弹窗**脱离主窗口 context：Modal 内必须重新包 `<SafeAreaProvider>`，且键盘避让用**响应式 paddingBottom**（`Math.max(insets.bottom, 24) + kbHeight`），不要用 `KeyboardAvoidingView` 或 `translateY` 位移。详见 `docs/modal-keyboard-guide.md`。
|
||
6. **改了 TS 后 release 包若不更新**：gradle 的 bundle task 会因缓存跳过重打包，Metro 也有 transformer cache。验证 bundle 必须用 `grep -a`（Hermes 字节码是二进制）。详见 `docs/android-build-guide.md §7`。
|
||
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`。
|
||
8. **OCR 的 det 后处理必须用连通域法**（`OcrModule.kt` 的 `dbPostprocess`：4-连通 BFS + 官方 unclip 外扩 + box_score_fast 过滤），**禁止回退到水平/垂直投影切行**——投影法会把基线孤立小数点切到文本框外，导致 `¥143.97` 识别成 `¥14397`。怀疑「模型识别能力不足」前先用官方 PaddleOCR 跑同一对模型对照。详见 `docs/ocr-pipeline-guide.md`。
|
||
9. **无障碍服务伪装必须包名+类名同时匹配**：微信 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`。
|