bf04400852
OCR 模型按需下载（P8 瘦身）： - 移除 plugins/ppocr/assets/ 内置模型（det 9.8MB + rec 21MB + dict），APK 减包 ~31MB - 新增 modelDownloader.ts：优先从 HuggingFace/CDN 下载，兜底从 APK assets 拷贝 - OcrModule.kt 新增 setModelDir，支持从 filesystem 加载模型，回退 assets 兼容旧用户 - settingsStore 持久化 ocrModelVersion / ocrModelDir - 自动化页集成模型状态检查与一键下载 UI OCR 三层独立控制： - OcrProcessorConfig 从单一 aiVisionEnabled 拆分为 layer1/2/3 三个独立开关 - 设置页可按层启停（L1 正则规则 / L2 本地 OCR / L3 AI Vision） - OCR 处理增加耗时与字符数日志 日志系统升级： - logger.ts 新增 LogFileBackend 抽象，支持磁盘持久化（按日期 app-YYYY-MM-DD.log） - 新增 logBackend.ts（ExpoLogFileBackend）+ 日志中心页 settings/logs.tsx - 日志中心：实时缓冲 + 历史文件、4 级过滤、Tag/关键词搜索、JSON 展开、分享导出、7 天过期清理 - _layout.tsx 启动时初始化文件后端 + 日志脱敏（验证码/卡号） 原生浮层 UI 主题同步（P6）： - 新增 floatingUiConfig.ts：JS 侧从 theme tokens + i18n 构建 FloatingUiConfig 推送原生 - 新增 FloatingUiConfigStore.kt：SharedPreferences 存储，三浮层组件读取 - FloatingBillView 重设计：颜色/文案走配置、新增币种 chip、金额校验改 BigDecimal - FloatingHelper / FloatingTip 同步适配 - _layout.tsx 新增 FloatingUiConfigSyncer，主题/语言切换自动推送 UI 与组件增强： - FormModal 新增 select/dropdown 控件、行内布局（row/flex）、联动回调 onValuesChange - 新增 Touchable 通用触摸组件、AccountCreateModal 快速建账弹窗 - 信用卡页展示账单周期/到期还款日/本期应还/剩余可用额度，关联账户改下拉选择 - AI 设置页重做：OpenAI/Gemini/DeepSeek 预设 + 默认 URL/模型 - 引导页新增 Android 权限检查步骤（无障碍/通知/短信/存储/悬浮窗） 去重优化： - 对手方匹配改为模糊包含（includes），双方均无对手方时判定低置信度重复 - DedupResult 新增 matchedItem 返回匹配对比项 文档重构： - README.md 重写为入口索引（品牌更新 + 模块概览 + 文档导航表） - 新增 AGENTS.md（AI 助手贡献指南）、docs/architecture.md（Mermaid 数据流/分层/OCR 级联图） - 新增 docs/development.md（环境/命令/编码规范/测试/提交规范）、plugins/README.md - UI 重设计文档（design spec + p1-p8）移入 docs/design/ 其他： - i18n 新增权限/信用卡详情/日志中心/AI 设置等翻译键 - ppocr Config Plugin 修复 import 注入去重；size-optimization 增强 - 新增测试：logger.test.ts、floating-ui-config.test.ts
63 lines
3.4 KiB
Markdown
63 lines
3.4 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). |
|
|
| `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.
|