# HarmonyPersonalManager

**Repository Path**: sill_lyb/harmony-personal-manager

## Basic Information

- **Project Name**: HarmonyPersonalManager
- **Description**: 鸿蒙个人管家app
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-26
- **Last Updated**: 2026-09-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 鸿蒙个人管家（HarmonyPersonalManager）

纯本地 · 零出网 · 个人生活管理 App —— HarmonyOS NEXT 原生开发（ArkTS + ArkUI，Stage 模型，compat API 12 / target API 23）。

> 依据《鸿蒙个人管家_PRD_v1.0.md》《鸿蒙个人管家_开发技术方案.md》《鸿蒙个人管家_架构与实现.md》《鸿蒙个人管家_进度复盘与下一步计划.md》《鸿蒙个人管家_baseEnglish功能规划.md》等文档开发，**需求 / 技术 / 改造报告统一见 [docs/](./docs/)**。
> 视觉遵循「轻拟物 · 暖白纸感」（2026-08-27 定稿，取代原「方案 B 卡通活泼」）：页面底 `#FAF6F0`、卡片 `#FFFDF9`、主操作色焦糖褐橙 `#C9773C`、双层投影 + 顶部渐变高光。**设计与高保真预览统一见 [design/](./design/)**，基准稿件 `design/ui-preview.html`（浏览器直接打开）。

---

## 一、功能总览

| 模块 | 状态 | 说明 |
| --- | --- | --- |
| 工程脚手架 | ✅ | bundleName `com.yongbin.personalmanager`、22 路由注册、图标生成（scripts/gen_icons.py） |
| 数据底座 | ✅ | 11 张业务表 DDL + 5 索引 + 版本化迁移（preferences schemaVersion）+ rawfile 种子数据 |
| 首页框架 | ✅ | 4-Tab（首页九宫格 / 动态 / 音乐 / 我的） |
| **账务主线（M1）** | ✅ | **BillList（三维度列表）/ BillRecognize（OCR 拍照识别）/ BillStats（分类统计）/ BillDetail（详情编辑）** |
| **基础英语（M2+）** | ✅ | **EnglishHome（词库首页）/ EnglishStudy（随机 10 张翻卡学习）/ EnglishQuiz（测验）** |
| **音乐模块（M4）** | ✅ | **Music（列表 v2）/ MusicPlayer（沉浸式播放页）/ 本地曲库扫描与收藏** |
| 截屏识别 | ✅ | ScreenshotWatcher + OcrConfirmBar（扫描确认条，能力已就绪） |
| 数据备份导出 | ✅ | DataService.buildPayload 校验链 + BackupLocal 入口已就绪 |
| 待办 / 物品 / 动态 / 番茄钟 / 纪念日 | ✅ | TodoService / ItemService / MomentService / PomodoroService / AnniversaryService 全套服务 |

## 二、账务主线功能对照

| 需求 | 实现 |
| --- | --- |
| REQ-B01 账单 CRUD | BillService.save（UPSERT）/ list（时间+类别+金额三维过滤）/ remove；BillList 左滑删除二次确认；BillDetail 编辑预填 |
| REQ-B02 拍照识别 | BillRecognize：相册（PhotoViewPicker）/ 拍照（cameraPicker，均免权限）→ VisionKit 本地识别 → 正则规则表解析金额/日期/商户/类别 → 表单回填确认 → `source='ocr'` 入库（含原图路径） |
| REQ-B03 多维度查询 | 月份切换 + 收支分段 + 类别胶囊 + 金额区间（<100 / 100-500 / >500），SQL 条件组合 |
| REQ-B04 消费统计 | BillStats：`statsByCategory` GROUP BY 分类占比 + 彩色进度条（CategoryService.colorOf/tintOf） |
| G4 零出网 | module.json5 仅声明媒体/相机/后台运行等本地权限，**无 INTERNET 权限** |

## 三、基础英语（baseEnglish）功能

- **词库**：865 词种子数据（rawfile），按「抽象名词 / 具体 / 形容词 / 反义词 / 日常」分类，支持掌握状态持久化
- **翻卡学习**：每次随机抽 10 张批学习（`drawStudyDeck` ORDER BY RANDOM），翻面看释义，标记「认识 / 不认识」落库，末张进小结态
- **词库首页**：总词数 / 已掌握 / 待学习统计卡（@Component + @Prop 保证响应式）+ 分类 Tab + 两种列表视图切换（仅单词 / 单词+例句）+ 点击单词弹「居中卡牌」学习弹层
- **卡片学习弹层**：「单词 / 单词+例句」模式切换；单词与例句行尾喇叭 TTS 朗读；「认识 / 不认识」按钮标记后经 EventBus 广播自动刷新统计
- **测验**：分类/全量出题，即时判分
- **TTS 朗读**：PronounceService 三级降级（en-US person:8 → 兜底 → 中文引擎提示），无英文语音包时降级并 toast 提示

## 四、音乐模块（M4）技术要点

- **曲库来源双通道**：媒体库扫音频（`photoAccessHelper.getAssets` MEDIA_TYPE=AUDIO，UI 层动态申请 READ_MEDIA）+ 文件夹扫描（DocumentViewPicker 选目录 + 递归白名单），目录授权 `persistPermission` 保活
- **播放器架构**：静态单例常驻 + `AppStorage(nowPlayingId / playPaused / playProgress / playDuration / loopMode)` 跨页同步；页面销毁不 release，回列表/首页迷你条仍真实控制；EntryAbility.onDestroy 统一 release
- **沉浸式播放页**：黑胶旋转 / 频谱波动 / 进度可拖（注意：timeUpdate 回调是秒，seek 参数是毫秒 ×1000）/ 歌词高亮 / 列表-单曲循环 / 睡眠定时
- **列表页 v2**：渐变 Banner + 为你推荐横滑 + 迷你播放条 + 分组列表 / 收藏筛选；播放列表弹层（MusicPlaylistSheet）
- **去重与过滤**：按 file_uri 唯一键 upsert；加密/不支持格式（kgm/kgma/mflac/qmc* 等）三层过滤（选后过滤 + 扫描排除 + 列表加载兜底）
- **系统联动**：实况窗（Live View）与通知栏媒体控制

## 五、技术要点（项目铁律）

- **金额以分（int）存储**：MoneyUtil.yuanToFen / fenToYuan / formatWithComma，杜绝浮点误差
- **页面根结构统一**：`Column` 根 + NavHeader 固定顶部 + 可滚动区 `layoutWeight(1)` 撑满（禁用 Scroll 直接做 @Entry 根）
- **弃用 `expandSafeArea(TOP)`**：EntryAbility `setWindowBackgroundColor('#EAF2FF')` 铺窗口背景，视觉等效且不遮挡顶部按钮命中
- **弹层契约**：`$$this.x` 双向绑定 + `bindSheet` 挂宿主节点属性链尾部（一宿主一弹层）；`BottomSheetForm` 用 `@Prop isShow` + `onClose` 回调
- **防冒泡**：子元素 `onClick` 做业务 + `.onTouch(e => e.stopPropagation())` 阻断向父级冒泡（`ClickEvent.stopPropagation()` 本项目 SDK 编译不过）
- **跨页刷新双保险**：EventBus 主题广播 + onPageShow 重载
- **OCR 降级**：识别失败不阻塞主流程，提示后仍可手动填写
- **统一日期规范**：`2026年8月20日`（跨年补年份）/ `8月20日` / 列表副标题 `8月20日 · 周三`

## 六、工程结构

```
entry/src/main/ets/
├── entryability/      入口（LocalDatabase.init）
├── pages/
│   ├── bills/         BillList · BillRecognize · BillStats · BillDetail（账务主线）
│   ├── english/       EnglishHome · EnglishStudy · EnglishQuiz（基础英语）
│   ├── music/         Music（列表 v2） · MusicPlayer（播放动效页）
│   ├── items/         todo/  moments/  learning/  timer/  me/   其余模块页
│   └── Index.ets / Home.ets  4-Tab 框架
├── components/        BottomSheetForm · NavHeader · MusicPlaylistSheet · MiniPlayerBar · SleepTimerSheet 等
├── models/            数据模型（含 EnglishWordModel）
├── database/          Schema.ets（DDL 集中管理）+ LocalDatabase.ets（建表/迁移/种子）
├── services/          BillService · MusicService · MusicScanner · EnglishWordService · PronounceService 等 20 个服务
└── utils/             Constants · DateUtil · MoneyUtil · EventBus · PermissionUtil · Uuid
```

## 七、构建与运行

1. DevEco Studio（API 12+ / HarmonyOS 5.0.0 SDK）打开 `HarmonyPersonalManager` 工程
2. 真机（需 HarmonyOS NEXT）或模拟器运行；无网络权限依赖，无需申请联网
3. OCR 依赖 VisionKit 真机识别、音乐依赖本地音频文件，建议真机验证

## 八、里程碑路线

- **M1（已交付）**：数据底座 + 账务主线
- **M2+（已交付）**：基础英语 baseEnglish 离线学习（取代已下线的「日历」模块）
- **M4（已交付）**：音乐模块 v2（列表页 + 沉浸播放页 + 系统媒体控制）
- **M3（能力就绪）**：数据备份导出导入
- **待办**：我的物品 / 待办 / 学习进度 / 番茄钟 / 纪念日页面的 UI 落地收口

> 踩坑与设计决策详见项目 `.workbuddy/memory/MEMORY.md` 与 docs/ 文档索引。