一、项目概述

1.1 项目名称

基于 OpenHarmony API23 的轻量化笔记管理系统

1.2 开发环境

• 系统：DevEco Studio NEXT Beta
• API 版本：API Version 23
• 开发语言：ArkTS
• 架构模式：四层分层架构（entry + har_base 公共底层 + 业务 HAR + HSP 动态分包）

1.3 功能概述

1. 用户模块：账号本地缓存、登录校验、深色模式切换、退出登录
2. 笔记核心模块：新建、编辑、删除、分页列表、关键词模糊搜索
3. 媒体模块：相册单选 / 多选图片、图片压缩、头像上传、图片缓存清理
4. 本地持久化：RDB 关系数据库存储笔记，Preferences 存储用户配置、登录凭证
5. 通用基础能力：网络请求、全局弹窗、动态权限申请、统一日志、文件缓存管理
6. 性能优化：HSP 按需分包、下拉刷新 + 上拉分页、页面状态兜底视图、全局主题深浅切换

1.4 技术亮点

1. 模块化解耦：HAR 静态复用 + HSP 动态分包，主包轻量化，冷启动速度提升
2. 全套底层工具封装：网络、数据库、存储、路由、弹窗、权限、图片、文件、日志统一工具类
3. 响应式全局状态管理：AppStorage+PersistentStorage 实现持久化全局状态
4. 标准化 UI 体系：统一主题色彩、尺寸、圆角，一键切换深浅两套主题
5. 工程规范约束：单向依赖无循环、资源命名规范、页面生命周期资源自动回收
6. 完善异常处理：网络异常、空数据、加载失败兜底视图，分级日志生产环境屏蔽调试信息

二、总体系统架构设计

2.1 四层分层结构图

1. 入口层 entry 应用启动入口、EntryAbility 全局初始化、首页 / 登录 / 设置常驻页面、HSP 加载调度、路由权限拦截
2. 公共底层层 har_base 所有通用工具类、全局类型常量、通用 UI 组件、主题样式、基础资源，全模块共享无业务耦合
3. 业务静态层 har_user /har_note 用户、笔记独立业务实体、数据库操作、业务专用组件，仅依赖 har_base，业务之间隔离
4. 动态分包层 hsp_note_editor 笔记编辑器重型页面，运行时按需加载，用完卸载释放内存，不打包入主包

2.2 模块依赖约束

单向依赖流向：页面 / HSP → 业务 HAR → har_base

• har_base：无任何依赖
• 业务 HAR：仅依赖 har_base，业务模块禁止互相引用
• HSP：依赖 har_base + 对应业务 HAR，HSP 之间禁止依赖
• entry：依赖全部 HAR、HSP 模块，统一调度所有业务

2.3 技术模块依赖关系图

plaintext

页面业务代码
    ↓
RouterUtil / DialogUtil / PermissionUtil / GlobalStore / ThemeUtil（har_base）
    ↓
底层系统API：router、relationalStore、preferences、net.http、accessToken、file.picker、fileio

三、模块详细设计

3.1 entry 主模块

1. EntryAbility
   • 初始化所有工具上下文（FileUtil、LogUtil、PermissionUtil）
   • 配置生产环境日志等级，屏蔽 DEBUG 调试日志
   • 绑定 PersistentStorage 持久化全局状态
   • 监听应用前后台生命周期，清理缓存、释放资源
2. 常驻页面
   • Index 首页：功能导航、登录状态判断、跳转 HSP 编辑器入口
   • Login 登录页：账号密码登录、本地缓存账号、登录状态写入全局 Store
   • Setting 设置页：深色模式切换、缓存大小查看、一键清理缓存、退出登录
   • Mine 个人中心：展示用户头像、账号信息、退出登录弹窗确认
3. 内置工具
   • HspLoadUtil：HSP 分包加载、防重复加载锁、跳转封装

3.2 har_base 公共底层库

工具类 utils

1. HttpUtil：axios 风格网络请求，拦截器、全局 loading、文件上传、请求销毁
2. RdbUtil：关系数据库通用封装，增删改查、分页、事务批量操作
3. PrefUtil：轻量键值存储，用户配置持久化，多文件隔离存储
4. RouterUtil：路由统一封装、登录拦截、HSP 分包路由、栈清空管理
5. DialogUtil：全局弹窗（提示 / 确认 / 输入 / 加载弹窗）、页面销毁批量关闭
6. PermissionUtil：动态权限申请，区分永久拒绝并跳转系统设置
7. ImagePickerUtil：相册单选多选、相机、图片压缩、图片保存相册
8. FileUtil：沙盒文件读写、目录创建、缓存大小计算、一键清理缓存
9. LogUtil：四级分级日志、敏感信息脱敏、本地日志文件持久化
10. GlobalStore：AppStorage 全局状态管理、持久化绑定、登录状态批量操作
11. ThemeUtil：全局主题色彩、尺寸常量、深浅主题自动切换

通用 UI 组件 components/common

1. StateView：页面四状态视图（加载中 / 空数据 / 错误 / 正常内容）
2. RefreshListView：下拉刷新、上拉分页、请求防抖锁、无更多底部提示

model 全局常量与类型

1. Constant.ets：页面路由常量、HSP 包名常量、全局状态 Key 常量
2. GlobalState.ets：全局状态完整 TS 类型约束、用户信息实体
3. theme.ets：尺寸常量、浅色 / 深色两套色彩、卡片通用样式

3.3 har_user 用户业务 HAR

1. model：UserInfo 用户实体类
2. logic：登录接口请求、头像上传逻辑
3. components：用户头像卡片、个人信息展示组件

3.4 har_note 笔记业务 HAR

1. model：Note 笔记实体类
2. db：笔记数据表创建、RDB 数据库 CRUD、分页模糊查询
3. components：笔记列表条目卡片组件

3.5 hsp_note_editor 动态分包

1. pages：笔记新增 / 编辑页面
2. logic：笔记保存、图片插入业务逻辑
3. components：编辑器输入框、图片预览子组件

四、数据库设计（RDB SQLite）

4.1 用户表（可选拓展，本项目用户数据以 Preferences 存储为主）

4.2 笔记表 note

表格

字段名	类型	约束	说明
id	INTEGER	PRIMARY KEY AUTOINCREMENT	笔记自增主键
title	TEXT	NOT NULL	笔记标题
content	TEXT	NULL	笔记正文内容
create_time	INTEGER	NOT NULL	创建时间戳

建表 SQL：

sql

CREATE TABLE IF NOT EXISTS note (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  title TEXT NOT NULL,
  content TEXT,
  create_time INTEGER
);

五、核心功能流程设计

5.1 用户登录流程

1. 进入 Login 页面，PrefUtil 读取本地缓存账号回填输入框
2. 输入账号密码，点击登录按钮
3. HttpUtil 发起登录 POST 请求，全局 Loading 弹窗展示
4. 请求成功： ① Token、账号存入 Preferences 持久化 ② GlobalStore 批量写入登录状态、用户信息全局状态 ③ RouterUtil.replace 跳转首页，不保留登录返回栈
5. 请求失败：弹窗提示错误信息，保留页面重新输入

5.2 笔记分页加载流程

1. 进入笔记列表页面，页面状态置为 LOADING
2. 调用 har_note 数据库工具分页查询笔记数据
3. 判断返回数组长度：
   • 长度 0 → StateView 展示空数据页面
   • 查询异常 → StateView 展示错误页面，提供重试按钮
   • 正常数据 → 渲染 RefreshListView 分页列表
4. 下拉刷新：重置页码，重新查询第一页数据
5. 上拉触底：查询下一页，数据追加至列表，不足分页条数标记无更多数据

5.3 新建笔记（HSP 分包加载流程）

1. 首页点击新建笔记按钮
2. RouterUtil 内置登录拦截，未登录弹窗提示跳转登录
3. HspLoadUtil 校验分包未加载，执行 loadPackage 加载 hsp_note_editor
4. 分包加载完成，pushHsp 跳转编辑器页面
5. 编辑器可唤起相册选择图片，自动校验媒体动态权限、压缩图片存入缓存目录
6. 保存笔记调用 har_note 数据库插入方法
7. 返回列表页，unloadPackage 卸载 HSP 分包释放内存，下拉刷新列表展示新增笔记

5.4 深色模式切换流程

1. 设置页读取 GlobalStore 全局 darkMode 状态赋值页面 @State
2. 切换 Toggle 开关，GlobalStore 修改深色全局变量
3. PersistentStorage 自动同步写入 Preferences，重启 APP 配置不丢失
4. ThemeColor () 自动读取全局状态切换深浅两套色值，页面所有 UI 实时刷新配色

5.5 缓存清理流程

1. 设置页加载时调用 FileUtil 计算 cacheDir 缓存大小，格式化单位展示
2. 点击一键清理弹窗二次确认
3. 确认后递归删除全部缓存目录，重新计算缓存大小更新页面

六、关键工具类功能说明

6.1 HttpUtil 网络工具

• 统一请求头自动携带 token
• 全局自动 loading 弹窗，请求结束自动关闭
• 401 登录失效自动清空登录状态跳转登录页
• 页面销毁批量 abort 中断所有请求，防止内存泄漏
• 支持图片表单上传，自动压缩图片后上传接口

6.2 RdbUtil 数据库工具

• 单例封装，页面注入上下文初始化、退出关闭数据库释放文件锁
• 支持单条增删改查、关键词模糊分页查询
• 批量事务插入，异常自动回滚保证数据完整性
• ResultSet 使用完毕自动关闭，避免内存占用

6.3 GlobalStore 全局状态

• 区分持久化状态（登录、深色模式）、临时内存状态（用户信息）
• watch 监听状态变化，页面销毁解绑监听，杜绝回调报错
• 封装登录 / 退出批量操作方法，统一管理登录相关全局变量

6.4 DialogUtil 弹窗工具

• 统一缩放淡入动画、遮罩拦截底层点击
• 页面退出批量关闭所有弹窗，遮罩不残留阻塞页面交互
• 加载弹窗、确认删除弹窗、输入弹窗一行代码调用

七、UI 设计规范

7.1 主题色彩两套体系

1. 浅色主题：白底卡片、深黑色文字、蓝色主色调
2. 深色主题：深色页面背景、灰色卡片、浅白色文字、亮蓝色主色调
3. 统一功能色：成功绿、警告橙、危险红，两套主题独立适配

7.2 尺寸规范统一

• 间距：4/8/12/16/24 五级间距
• 圆角：4/8/12/16 / 全圆角五级圆角
• 字号：12 提示字、14 辅助字、16 正文、18 副标题、22 标题、26 大标题
• 控件高度：36 小按钮、44 标准按钮、48 输入框

7.3 页面通用布局规范

1. 页面统一外边距 12px
2. 列表卡片统一 12px 内边距、12px 圆角、轻微阴影
3. 按钮统一标准高度 44px，主色填充圆角按钮

八、性能优化方案

1. 分包体积优化：编辑器重型页面拆分 HSP 动态分包，主包仅保留核心页面，安装包体积大幅缩小
2. 内存优化
   • HSP 页面退出调用 unloadPackage 卸载分包释放代码与资源
   • RDB、文件句柄页面销毁统一 close 释放
   • 网络请求页面销毁全部 abort 中断，避免无效回调
   • 图片 PixelMap、ImageSource 使用完毕主动 release 释放图像内存
   • 全局状态监听页面销毁解绑，动画组件销毁停止无限循环动画
3. 列表渲染优化
   • 分页加载，不一次性查询全部数据库数据
   • RefreshListView 内置请求锁，防止快速滑动重复发起分页请求
   • BuilderParam 插槽局部刷新，数据更新不重绘整个页面
4. 启动优化
   • 冷启动仅加载 entry+har_base 核心模块，HSP 按需延迟加载
   • 页面 onLoad 不自动预加载分包，用户点击后再加载
5. 存储优化
   • 临时图片存入 cacheDir，支持一键清理缓存
   • 大体积结构化数据使用 RDB，简单配置使用 Preferences 分开存储

九、异常处理机制

1. 网络异常：请求捕获异常，页面切换 ERROR 状态，提供重试按钮；分级 ERROR 日志记录报错详情
2. 权限异常：无对应权限弹窗提示，永久拒绝跳转系统设置页面手动开启
3. 数据库异常：数据库操作捕获异常，日志记录 SQL 错误，页面弹窗提示操作失败
4. 文件 IO 异常：文件读写失败弹窗提示，自动关闭文件句柄防止占用
5. 空数据异常：列表长度为 0 自动展示空页面视图，友好提示用户暂无数据
6. 分包加载异常：HSP 加载失败弹窗提示，清除加载锁允许重新点击加载

十、测试方案

10.1 功能测试

1. 用户登录：正确账号登录成功、错误账号提示失败、重启保留登录状态
2. 笔记 CRUD：新增、编辑、删除、模糊搜索、分页加载全部正常
3. 媒体功能：相册单选 / 多选图片、图片压缩、保存至系统相册无崩溃
4. 设置功能：深浅模式切换实时生效、缓存计算、一键清理缓存
5. 分包测试：首次点击编辑器加载分包，返回卸载，重复打开可重新加载

10.2 兼容性与性能测试

1. 低配置设备：滑动列表无卡顿、下拉刷新动画流畅
2. 内存测试：反复进出 HSP 分包，内存无持续上涨、无内存泄漏
3. 重启测试：深色模式、登录账号重启 APP 配置不丢失
4. 弱网测试：网络断开展示错误页面，恢复网络点击重试正常加载

10.3 异常测试

1. 永久拒绝相册 / 相机权限，弹窗引导跳转设置
2. 快速重复点击按钮，防抖锁拦截重复请求，数据不重复新增
3. 页面中途退出，后台无残留弹窗、无持续执行网络请求、无动画后台运行

十一、项目部署与打包说明

1. 开发调试：DevEco Studio 连接真机 / 模拟器直接运行
2. 打包配置：HSP 模块 deliveryWithInstall=true，打包自动拆分动态分包
3. 发布环境配置：
   • EntryAbility 设置日志等级LogLevel.INFO，屏蔽所有 DEBUG 调试日志
   • 关闭本地文件日志输出，减少存储空间占用
   • 关闭 http 明文访问 cleartextTraffic，仅使用 HTTPS 接口
4. 打包产物：hap 主包 + 独立 hsp 分包，设备安装时自动合并

十二、项目总结

本项目基于 OpenHarmony API23 搭建标准化四层分层架构笔记管理系统，实现用户登录、笔记增删改查、图片媒体处理、本地持久化存储、全局主题切换等完整业务功能。 项目实现工程化标准封装，将网络、数据库、存储、路由、弹窗、权限、文件、日志等底层能力统一封装为复用工具类，通用 UI 组件解耦复用，利用 HSP 动态分包实现安装包体积与内存占用优化，配套完整的异常兜底视图、深浅双主题、生命周期资源回收机制。 整套代码严格遵循单向依赖分层规范，代码复用率高、耦合度低、易拓展维护，可作为鸿蒙课程设计、毕业设计完整交付项目，同时架构可拓展至商城、资讯、备忘录等各类鸿蒙应用开发。

十三、拓展优化方向（可选加分项）

1. 新增笔记标签分类、笔记排序功能
2. 新增本地笔记数据导出为文件、导入恢复功能
3. 新增云同步模块，对接后端实现多设备笔记同步
4. 新增字体大小调节、多套主题色自定义换肤
5. 新增消息通知模块，笔记定时提醒功能
6. 新增数据加密，对本地 RDB 笔记内容加密存储保护隐私