# 开发指南

## 环境要求

- Node.js 18+
- JDK 21 + Android SDK 35 + NDK 27.1.12297006（仅 Android 构建需要）
- 详见 [android-build-guide.md](android-build-guide.md)

## 常用命令

```bash
npm install --legacy-peer-deps   # 安装依赖（必须带 --legacy-peer-deps）
npm run start                    # 启动 Metro 开发服务器
npm run android                  # expo run:android（设备/模拟器）
npm test                         # Vitest 全量测试
npm run typecheck                # tsc --noEmit 类型检查

# 单文件测试
npx vitest run tests/ledger.test.ts

# 按名称运行测试
npx vitest run -t "拒绝不平衡交易"

# 重新生成原生项目
npx expo prebuild --platform android
```

## 编码规范

### TypeScript

- **strict 模式**已开启，路径别名 `@/*` → `src/*`
- 非平凡改动后必须运行 `npm run typecheck`

### 金额计算

- 使用字符串十进制运算（`src/domain/decimal.ts`），**禁止**用 JS 浮点数处理金额
- 关键 API：`addDecimals`、`subtractDecimals`、`multiplyDecimal`、`divideDecimals`、`negateDecimal`

### 领域层纯净性

- `src/domain/` 禁止导入 React / React Native / Expo 任何模块
- 外部依赖通过接口注入：`MobileBeanBackend`、`OcrEngine`、`AiVisionProvider`
- 新模块必须在 `src/domain/index.ts` 重导出

### 原生代码

- 原生 Kotlin/XML 只能放在 `plugins/<name>/` 下，不可直接编辑 `android/`
- 每个 Config Plugin 函数**必须 `return config`**
- `expo prebuild` 后检查 `onnxruntime-android:1.20.0` 版本

### 注释与文档

- 代码注释和 `plan.md` 使用**中文**
- ID/校验和使用 FNV-1a 哈希（`hash()` in `ledger.ts`），不用加密哈希

## 测试

- 框架：**Vitest**（无配置文件，默认拾取 `tests/**/*.test.ts`）
- 测试对象：主要覆盖 `src/domain/` 层，使用 mock 后端（`MemoryBackend`、`MockOcrEngine`）
- 命名：`<模块或功能>.test.ts`，如 `decimal.test.ts`、`billPipeline.test.ts`
- 新增 domain 逻辑时必须同步添加测试

## 提交规范

- 提交消息格式：`feat: <中文摘要>`，多行 body 按模块分区列举变更
- 示例：`feat: 品牌重命名为浮记(DriftLedger)，全面升级精度安全与架构`
- PR 需描述变更内容与原因，UI 变更附截图，关联相关 issue