# 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`。