# 记账小助手 — 项目文档

## 项目概述

| 项目 | 说明 |
|------|------|
| **应用名称** | 记账小助手（keeping_accounts） |
| **平台** | HarmonyOS (API 6.1 / Stage 模式) |
| **Bundle Name** | `com.example.keeping_accounts` |
| **版本** | 1.0.0 (versionCode: 1000000) |
| **开发框架** | ArkTS + ArkUI 声明式 UI |
| **构建工具** | Hvigor |
| **目标设备** | 手机 (phone) + 手表（通过蓝牙同步） |
| **跨平台** | 支持 Android / iOS（通过 ArkUI-X） |

---

## 目录结构

```
keeping_accounts/
├── AppScope/                          # 应用全局配置
│   ├── app.json5                      # Bundle 名称、图标、版本号
│   └── resources/                     # 全局资源（图标、背景、字符串）
├── build-profile.json5                # 签名配置、SDK 版本、模块列表
├── hvigorfile.ts                      # Hvigor 构建入口
├── code-linter.json5                  # 代码检查规则
├── lodefusi/                          # 主模块（entry）
│   ├── build-profile.json5            # 模块构建配置
│   ├── oh-package.json5               # 模块依赖声明
│   ├── hvigorfile.ts                  # 模块构建脚本
│   ├── obfuscation-rules.txt          # 代码混淆规则
│   ├── src/
│   │   ├── main/
│   │   │   ├── module.json5           # 模块清单（权限、Ability、页面路由）
│   │   │   ├── ets/
│   │   │   │   ├── pages/
│   │   │   │   │   └── Index.ets          # 主页面（启动页 + Tab 导航）
│   │   │   │   ├── lodefusiability/
│   │   │   │   │   └── LodefusiAbility.ets # UIAbility 入口
│   │   │   │   ├── components/
│   │   │   │   │   ├── Overview.ets        # 总览页面（月度统计）
│   │   │   │   │   ├── AddExpense.ets      # 记账页面（手动 + AI）
│   │   │   │   │   ├── ExpenseRecords.ets  # 记录列表（按日期分组）
│   │   │   │   │   ├── Device.ets          # 设备页面（蓝牙手表同步）
│   │   │   │   │   └── BluetoothTransfer.ets # 蓝牙传输模态页
│   │   │   │   └── model/
│   │   │   │       ├── ExpenseModel.ets     # 数据模型 + 本地持久化
│   │   │   │       ├── ApiService.ets       # HTTP API 服务
│   │   │   │       ├── ApiConfig.ets        # 服务器地址配置
│   │   │   │       └── BluetoothService.ets  # 蓝牙 SPP 传输服务
│   │   │   └── resources/                # 模块资源（颜色、字符串、图标）
│   │   ├── mock/                         # Mock 数据配置
│   │   ├── ohosTest/                     # 自动化测试
│   │   └── test/                         # 本地单元测试
│   └── ...
└── .arkui-x/                          # ArkUI-X 跨平台配置（Android/iOS）
    ├── android/                        # Android 工程
    └── ios/                            # iOS 工程
```

---

## 架构设计

```
┌─────────────────────────────────────────────────┐
│                  Index.ets (主入口)                │
│         启动页 → Tab 导航 (总览/记账/设备)           │
├──────────┬──────────────────┬───────────────────┤
│ Overview │   AddExpense     │    DevicePage      │
│ 月度统计  │  手动记账+AI分类  │  蓝牙设备管理+同步   │
├──────────┴──────────────────┴───────────────────┤
│              ExpenseRecords (记录列表)             │
│         按日期分组、分类筛选、长按删除               │
├─────────────────────────────────────────────────┤
│              BluetoothTransfer (蓝牙传输)          │
│          发送选择 → 搜索设备 → 连接 → 传输          │
├──────────┬──────────────────┬───────────────────┤
│ExpenseModel│   ApiService   │ BluetoothService  │
│ 本地存储   │  HTTP 同步     │  SPP 串口蓝牙      │
│Preferences│  /api/bills    │  RFCOMM 通道       │
└──────────┴──────────────────┴───────────────────┘
```

**数据流**：
1. 用户在记账页添加记录 → `ExpenseModel.addExpense()` 写入本地 Preferences
2. 同时异步调用 `ApiService.submitBill()` 同步到远端服务器（失败则静默降级，仅保存本地）
3. 总览页通过 `@Consume` 获取全量数据，按月筛选后计算分类汇总
4. 设备页通过 `BluetoothService.connectAndSend()` 将选中数据以 JSON 形式 SPP 传输给手表

---

## 模块详解

### 1. 主入口 — `Index.ets`

- **启动页**：显示深蓝渐变背景 + "¥" 图标 + "这个月你省钱了吗？" slogan，带有淡入动画（1s）+ 2.2s 后淡出
- **主界面**：3 个 Tab 页切换（底部导航栏），每个 Tab 有自定义图标：
  - 总览（环形图标）
  - 记账（"+" 图标）
  - 设备（手表图标）
- 页面级别的 `@Provide expenses` 将消费数据共享给所有子组件

### 2. 总览页 — `Overview.ets`

- **环形进度卡片**：总收入（绿）、总支出（红）、结余（蓝），显示当月合计金额
- **消费分类网格**：按金额降序排列，每个分类显示颜色圆点、金额、线性进度条
- **收入来源网格**：同理展示收入分类
- **空状态**：当月无记录时显示 "💰 本月暂无记录"
- **刷新按钮**：从本地存储重新加载数据

### 3. 记账页 — `AddExpense.ets`

- **类型切换**：消费（红色主题）/ 收入（绿色主题），切换时重置分类选择
- **金额输入**：仅允许数字和小数点，自动过滤非法字符，显示 "¥" 前缀
- **分类选择**：
  - **手动模式**：4 列 Grid 展示分类色块，选中项高亮 + 阴影
  - **AI 智能分类模式**（仅消费类型可用）：
    - 用户输入消费内容描述，开启 Toggle 开关
    - 调用 `/api/transfer` 接口进行 AI 分类
    - 显示加载动画 "AI 正在识别..."
    - 识别结果以蓝色标签展示，自动填充分类
    - 分类完成后自动调用 `/api/bills` 同步到服务器
- **备注输入**：选填文本，AI 模式下替代为描述输入框
- **提交按钮**：带 loading 状态，成功后显示 "✓ 添加成功" 浮层 Toast（1.8s 自动消失）
- **服务端同步**：静默失败策略，服务器不可用时 Toast 提示但数据已保存在本地

### 4. 记录列表 — `ExpenseRecords.ets`

- **按日期分组**：`yyyy-MM-dd` 为 key，每日显示日期标题 + 当日收支汇总
- **记录行**：
  - 左侧：分类颜色圆点 + 分类名 + AI 标签（蓝色胶囊）+ 备注
  - 右侧：金额（消费红/收入绿）+ 格式化时间 `MM-dd HH:mm`
- **长按删除**：触发确认对话框，确认后从本地存储删除
- **分类筛选**：支持按分类过滤，顶部显示筛选标签 + 记录数量 + 返回按钮
- **空状态**：无记录时显示 "📋 暂无消费记录"

### 5. 设备页 — `DevicePage.ets`

- **蓝牙状态栏**：显示蓝牙开关状态（绿点/灰点），刷新按钮
- **已配对设备列表**：
  - 显示设备名称、连接状态（绿点/灰点）、上次同步时间、已同步条数
  - 点击"连接"按钮模拟连接
  - 点击"同步"按钮将选中数据通过蓝牙发送
- **同步设置**：
  - 发送消费记录（Toggle 开关）
  - 发送收入记录（Toggle 开关）
- **手表应用设置**：
  - 手表端显示消费明细 / 收入明细 / 震动提醒（预留 UI）
- **同步结果**：顶部显示同步进度/结果横幅

### 6. 蓝牙传输 — `BluetoothTransfer.ets`

这是一个模态弹窗组件，支持发送和接收两种模式：

**发送流程**：
1. 选择记录（Checkbox 多选 + 全选）
2. 搜索附近的蓝牙设备（12s 超时）
3. 显示设备列表（设备名 + 地址 + 连接按钮）
4. 连接设备并通过 SPP 传输选中的 JSON 数据
5. 显示传输进度百分比

**接收流程**：
1. 等待发送方连接（显示本机蓝牙名称）
2. 自动接收数据（`__BT_EOF__` 标记结束）
3. 接收完成后显示记录数，提供"导入数据"按钮
4. 导入将数据合并到本地存储

**状态机**：`IDLE → SELECTING → SCANNING → CONNECTING → TRANSFERRING → COMPLETE / ERROR`
（接收时：`IDLE → WAITING → TRANSFERRING → COMPLETE / ERROR`）

---

## 数据模型

### ExpenseItem

```typescript
interface ExpenseItem {
  id: string;           // 唯一标识（时间戳+计数器+随机数）
  type: '消费' | '收入'; // 交易类型
  category: string;     // 分类名称（餐饮、工资等）
  amount: number;       // 金额
  remark: string;       // 备注
  message: string;      // AI 分类返回的建议消息
  createTime: string;   // ISO 时间字符串
}
```

### 预设分类

| 类型 | 分类项 |
|------|--------|
| **消费** | 餐饮、医药、数码、还款、购物、交通、娱乐、住房、日用、服饰、教育、人情、其他 |
| **收入** | 工资、奖金、理财、兼职、报销、退款、红包、其他收入 |

每个分类有对应的颜色值，用于 UI 中的圆点和进度条等元素。

### 数据持久化

- **本地存储**：使用 HarmonyOS `preferences` API，键值对存储在 `expense_store`，key 为 `expenses`
- **数据迁移**：`migrateItem()` 函数兼容旧版数据结构（如 `mash` → `amount`、`name` → `category`、`text/note` → `remark` 等字段映射）
- **生成 ID**：`Date.now().toString(36) + 计数器.toString(36) + 随机数`

---

## API 服务

### 服务器配置

- 配置文件存储在 `app_config` preferences 中，key 为 `server_url`
- 默认地址：`http://192.168.1.1:9255`

### 接口列表

| 接口 | 方法 | 路径 | 说明 |
|------|------|------|------|
| 提交账单 | POST | `/api/bills` | 将消费/收入记录同步到服务器 |
| AI 分类 | POST | `/api/transfer` | 根据消费描述自动推荐分类 |
| 查询账单 | GET | `/api/bills?type=&category=` | 按类型和分类筛选查询 |

### 错误处理

- 网络不可用、超时（连接 5s / 读取 10s）、服务端异常均返回 `{ code: -1, msg: '...' }`
- 调用方采用静默降级策略，不影响本地数据保存

---

## 蓝牙服务 — `BluetoothService`

### 技术方案

- 使用 **SPP（Serial Port Profile）** 基于 RFCOMM 通道传输
- UUID：`00001101-0000-1000-8000-00805F9B34FB`
- 数据格式：JSON 字符串 + `__BT_EOF__` 结束标记
- 分块传输：每块 512 字节

### 主要功能

| 方法 | 说明 |
|------|------|
| `isBluetoothEnabled()` | 检查蓝牙是否开启 |
| `enableBluetooth()` | 打开蓝牙 |
| `waitForBluetoothOn(timeoutMs)` | 等待蓝牙开启（监听 `stateChange` 事件） |
| `getLocalDeviceName()` | 获取本机蓝牙名称 |
| `getPairedDevices()` | 获取已配对设备列表 |
| `startDiscovery(cb)` | 搜索附近蓝牙设备 |
| `stopDiscovery()` | 停止搜索 |
| `startServer(onResult, onProgress)` | 启动 SPP 服务端监听（接收模式） |
| `connectAndSend(deviceId, data, onResult, onProgress)` | 连接设备并发送数据 |
| `stopServer()` / `cancelTransfer()` / `destroy()` | 终止/清理资源 |

### UTF-8 编解码

- 内建 `strToBytes()` 和 `bytesToStr()` 实现 UTF-8 编解码（支持中文），不依赖外部库

---

## 权限列表

| 权限 | 用途 |
|------|------|
| `ohos.permission.INTERNET` | HTTP API 通信 |
| `ohos.permission.USE_BLUETOOTH` | 蓝牙数据传输 |
| `ohos.permission.DISCOVER_BLUETOOTH` | 搜索附近蓝牙设备 |

---

## 离线策略

整体采用 **本地优先（Local-First）** 架构：

1. 用户操作直接写入本地 Preferences，操作体验不受网络影响
2. 服务器同步为异步旁路流程，成功/失败均不影响本地数据完整性
3. 蓝牙传输同样先将接收数据合并到本地存储，再触发 UI 刷新
4. 总览页刷新按钮从本地存储重新读取，确保数据一致性

---

## 跨平台支持（ArkUI-X）

项目包含 `.arkui-x/` 目录，配置了 Android 和 iOS 的原生工程：
- **Android**：Gradle 构建，包含 `arkui_android_adapter.jar` 和相关 `.so` 库
- **iOS**：Xcode 工程（`app.xcodeproj`），包含 `AppDelegate` 和 `LodefusiLodefusiAbilityViewController`

这意味着同一套 ArkTS 代码可以编译为 HarmonyOS / Android / iOS 三端应用。

---

## 测试

| 测试类型 | 路径 | 说明 |
|----------|------|------|
| 本地单元测试 | `src/test/List.test.ets`、`LocalUnit.test.ets` | 逻辑层测试 |
| 自动化测试 | `src/ohosTest/ets/test/Ability.test.ets`、`List.test.ets` | 设备上运行的 UI 测试 |
| Mock 配置 | `src/mock/mock-config.json5` | 模拟数据配置 |