陶嘉恒这个项目的起因其实特别朴素：家里的老人每个月都要跑社区医院测血压、量血糖，纸质记录单攒了一抽屉，想找个能长期看趋势的App又找不到顺手的。恰逢团队在评估OpenHarmony上的应用方案，我就拿Flutter先把这套健康记录App写了出来，其中最花精力、也最容易被忽略的，就是健康报告模块。
这里说的健康报告，不是简单把若干条记录摆出来，而是要把血压、心率、睡眠、运动、用药这些分散的数据，经过聚合、计算、评判，压缩成一页让用户能快速看懂的报告。整个实现牵扯到嵌入式数据库设计、SQL聚合、趋势算法、跨端图表绘制、PDF导出，还要在OpenHarmony上处理不少独有的适配问题。这篇文章我把完整思路和踩坑过程整理出来，适合正在做Flutter跨端应用、或者想把本地数据做可视化呈现的开发者参考。
1. 健康报告模块的定位与Flutter + OpenHarmony选型背景
1.1 报告模块不是一个页面，而是一套数据出口
很多健康类App开发者的第一反应是：报告不就是把记录查出来画个图嘛。实际接入之后你会发现，报告模块是整个项目里牵涉面最广的部分。它要读数据库里所有类型的记录，要做时间范围过滤，要做统计口径统一，还要兼顾展示、导出、分享三条输出链路。我在项目里把报告模块拆成了独立的数据出口，输入是原始记录，输出是一份结构化的ReportModel，页面展示、PDF生成、JSON导出都从这个Model来，谁都不直接碰SQL。
这么设计的好处很明显。一是报告生成逻辑可以脱离UI单独测试，我在Dart侧写了一套报告引擎的单元测试，喂进去模拟数据，直接校验统计结果对不对；二是后续加新指标类型，只需要改报告引擎，不用动页面。真实项目里报告逻辑会持续迭代，如果一开始就把它揉在Widget里，后期改一次统计规则就要改三处地方，很痛。
1.2 为什么不用ArkUI原生，而选Flutter
团队当时评估OpenHarmony应用方案时，摆在面前的选项其实有两个：ArkUI原生开发，或者Flutter跨端。我们最终选了Flutter，核心原因是团队已经积累了一套Flutter组件库和状态管理方案，而且是拿这套健康记录App同时面向OpenHarmony和Android/iOS的，纯Dart写业务逻辑能最大程度复用代码。健康报告这种重算法、重数据的模块，Dart的表达能力和生态明显更合适。
当然，跨端是有代价的。OpenHarmony上的Flutter适配目前主要靠社区维护的flutter_flutter仓库，稳定性是逐渐爬坡的，部分系统能力不能直接通过plugin调用，比如系统分享、相册、文件选择，这些我们是通过MethodChannel桥接到原生侧实现的。要说建议的话，如果你团队从零开始且只做OpenHarmony，ArkUI确实更省事；如果已经有Flutter技术积累，或者要一套代码跑多端，Flutter这条路线值得投入。
1.3 模块边界和数据流向
整个健康报告模块的数据流向是清晰的一条线：录入穿戴设备数据后写入SQLite，报告引擎在收到生成指令时从数据库拉取时间范围内的原始记录，做聚合计算得到ReportModel，UI层负责渲染图表卡片，导出层负责把同一份Model转成PDF或JSON。这里有个关键点，报告引擎必须与UI完全解耦，因为它不止在用户点击生成时运行，我还做了一个定时生成逻辑，每天早上自动把昨天的数据聚合成简报，推送到通知栏，这套逻辑跑在后台，完全没有UI依赖。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 健康数据落库：表结构设计与本地存储方案
2.1 为什么选sqflite而不是Hive或Isar
健康报告的核心动作是“按时间范围聚合”，这恰恰是SQL最擅长的。Hive和Isar虽然读写快，但要做AVG、MAX、MIN、GROUP BY这类统计，要么把所有数据捞到内存里算，要么用Isar的collection查询绕来绕去，效率都不如直接写一句SQL来得干净。所以我最终选的是sqflite。
这里要特别提一个OpenHarmony上的兼容问题。sqflite作为一个成熟的Flutter插件，底层依赖系统SQLite能力，但OpenHarmony镜像里的SQLite动态库和Android不完全一样，真机上经常出现加载不到libsqlite3.so的诡异问题。我的做法是配合sqflite_common_ffi，把sqlite3的动态库直接打包进应用，通过FFI方式调用，绕开系统库依赖，这一招在OpenHarmony上实测非常稳。代价是打出来的包会大一点，但比起排查系统环境问题，这点体积完全值得。
2.2 四张核心表的结构设计
健康记录不是一张表能搞定的。我在项目里拆了四张表，分别是通用指标记录、睡眠记录、运动记录、用药记录。通用指标表用来存血压、心率、体重、血糖这类单值或多值指标，结构设计成下面这样：
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER PRIMARY KEY | 主键自增 |
| record_type | INTEGER | 指标类型：1血压 2心率 3体重 4血糖 |
| value | REAL | 主数值，血压存收缩压 |
| value2 | REAL | 副数值，血压存舒张压，其他指标为空 |
| unit | TEXT | 单位，冗余存储便于显示 |
| measure_time | INTEGER | 测量时间，毫秒时间戳 |
| note | TEXT | 备注 |
睡眠、运动、用药三张表是各自独立的。睡眠表记录入睡时间、醒来时间、深睡分钟数、浅睡分钟数；运动表记录运动类型、时长、消耗千卡；用药表记录药名、剂量、服药时间。每张表都有单独的start_time或schedule_time字段，并在这些时间字段上建了索引。
2.3 时间字段、单位规范这些隐形坑
表结构看起来简单，但有几个隐形坑必须在建表阶段就定死。时间字段统一用毫秒时间戳，别用字符串，不然SQL里做范围查询和按天分组的性能会很难看。单位字段必须在写入时就标准化，比如体重统一存千克，血压统一存毫米汞柱，显示层再根据用户习惯做转换，千万不要把“用户界面上显示什么单位”和“数据库里存什么单位”混在一起。
还需要留一手数据库版本迁移。健康App的指标类型很可能后续会加，比如血氧、体温、体脂率，如果不在onUpgrade里做兼容，老用户升级App后一查数据库就崩。我在迁移逻辑里做了通用处理，新版本需要加字段时，检测到旧版本号后执行ALTER TABLE，并给新字段设置默认值。
3. 报告聚合计算：从原始记录到健康评分
3.1 先统一指标口径，再谈统计
报告模块最狠的坑不是算法难，而是口径不统一。比如生成周报时，血压是取一周内所有测量的平均值，还是只取每天早上空腹那次？心率是取静息心率还是任意时刻心率？这些口径不定义清楚，报告数据就是乱的。
我在报告引擎里单独做了一个NormalizationService，负责在做聚合之前统一口径。血压指标只取“上午6点到10点之间”的测量记录参与周均值计算，心率指标只标记为“静息状态”的记录参与统计，体重取最近7天的日均值。每个指标在代码里有明确的过滤条件注释，这些规则是跟医生朋友确认过的，尽量贴近临床习惯，而不是单纯按技术方便来。
3.2 SQL聚合加Dart二次加工的组合拳
报告生成时第一步是SQL聚合，把原始记录压缩成每天一组，减少Dart侧的计算量。比如生成血压趋势数据时，我用类似下面的查询：
sql复制SELECT
record_type,
strftime('%Y-%m-%d', measure_time / 1000, 'unixepoch', 'localtime') AS day,
AVG(value) AS avg_value,
MAX(value) AS max_value,
MIN(value) AS min_value
FROM health_records
WHERE record_type = 1
AND measure_time BETWEEN ? AND ?
GROUP BY record_type, day
ORDER BY day ASC;
SQL负责把一天内几十条血压记录压缩成三条数，Dart侧拿到这个结果后再做环比、同比计算，比如最近7天均价对比前7天均价，判断血压是升了还是降了。这种“SQL聚合+Dart计算”的组合方式，既省内存又灵活，比纯SQL硬写出所有复杂统计要清晰得多。
3.3 用最小二乘法判断趋势方向
报告中一个很直观的需求是：这周血压趋势是上升还是下降。最简单可靠的办法是用线性回归算斜率。对一组按时间排序的数值，用最小二乘法拟合一条直线，斜率正负代表方向，斜率绝对值大小代表趋势强弱。Dart实现很简洁：
dart复制double calcSlope(List<double> values) {
if (values.length < 2) return 0;
int n = values.length;
double sumX = 0, sumY = 0, sumXY = 0, sumX2 = 0;
for (int i = 0; i < n; i++) {
sumX += i;
sumY += values[i];
sumXY += i * values[i];
sumX2 += i * i;
}
return (n * sumXY - sumX * sumY) / (n * sumX2 - sumX * sumX);
}
实际操作中，我还会给斜率加一个阈值过滤。比如斜率为负但绝对值小于0.1，就判定为“基本平稳”，而不是一有负数就说“下降”，避免给用户制造没必要的焦虑。这个阈值是根据真实数据分布调出来的，不同指标可以分别配置。
3.4 健康评分的权重模型与免责提醒
为了让用户一眼看懂报告，我做了一个0到100的健康评分。评分由四部分加权合成：收缩压达标率占30%，心率稳定度占20%，睡眠时长质量占25%，运动达标率占25%。每个子项先独立换算成百分制，再按权重相加。
这套评分模型只能算生活参考，不能当医疗诊断。我一开始忽略了这一点，差点把“健康评分75分”这种结论直接甩给用户，后来觉得太危险了。在报告页面和PDF导出里都加了固定文案：本报告仅供参考，不构成医疗建议，如有不适请及时就医。这个不是可有可无的免责声明，做健康类App这是底线。
4. 报告的可视化实现与PDF导出
4.1 fl_chart绘制血压与睡眠趋势图
图表是报告的门面。我选的是fl_chart这个库，它在Flutter生态里用得多，维护活跃，支持折线图、柱状图、饼图。血压趋势用折线图，横轴是日期，纵轴是毫米汞柱；睡眠情况用横向柱状图，每条表示一天的总睡眠时长。折线图的核心配置是必须手动设好minY和maxY，否则默认范围会把数据波动拉平，趋势看起来不明显。我按血压的临床参考范围设置了60到180，心率设置了40到120，这样图表上的波动才有参考意义。
图表还有一个容易被忽略的点：当数据跨越几个月时，横轴日期的刻度标签不能全显示，否则会挤成一团。我用了一个简单策略，只显示每周第一个数据点的日期作为横轴标签，其余点只画线不标日期，既保证信息量又不糊。
4.2 报告页面的组合方式
报告页面整体是三个区块的纵向组合：概览卡、趋势卡、异常提醒卡。概览卡展示本周健康评分、血压均值、睡眠时长均值这三个核心数字；趋势卡放图和简要的文字结论；异常提醒卡列出超出参考范围的日期和数值，比如某天收缩压超过140，就单独列一条提醒。整页数据全部来自ReportModel，Widget本身不关心数据怎么来的，这是一个纯展示层。
用这种组合设计，页面扩展起来也很省事。后来我想加一个“体重变化”卡片，只需要在Model里新增一块数据结构，页面上加一个区块，报告引擎里加一段聚合逻辑，整个链路不需要动其他部分。
4.3 PDF导出时的中文字体是个大坑
pdf这个包生成PDF本身不难，难的是中文。默认字体不支持中文，生成的报告里所有中文都是方块。解决方法是打包一个中文字体文件到assets里，加载后手动注册给pdf包使用。我用的是NotoSansSC，注意字体文件体积不小，完整版有十几兆，放进App里太占空间。最后我裁减了字库，只保留报告页面用到的常用汉字，大小压到了两兆以内。
注册字体的关键代码很简单，但必须确保ByteData正确传给pdf包的Font.ttf方法，否则导出时会直接抛异常。另外，PDF导出后我还会额外生成一份JSON数据文件，方便用户未来做更精细的数据分析或迁移，而不只是拿到一张图片式的PDF。
4.4 导出后的文件保存与分享
文件导出路径我选了应用文档目录，用path_provider获取。保存文件名带上日期，比如health_report_2026-01-15.pdf。分享到微信或系统邮件时，需要调用系统分享能力，Android上可以直接用share_plus插件，但OpenHarmony上这个插件不一定兼容。我最后是通过MethodChannel在原生侧拉起系统分享Ability，把PDF文件的URI传过去。这块属于平台差异较大的部分，建议提前预研，别等到提测了才暴露。
5. OpenHarmony适配踩坑：路径、依赖与渲染性能
5.1 沙箱路径和Android完全不一样
OpenHarmony的文件目录结构跟Android的data目录不是一回事，实际拿到的路径风格是/data/storage/el2/base/haps/entry/files/这种形式。path_provider插件在OpenHarmony上不一定能正确返回所有目录，我遇到的情况是getApplicationDocumentsDirectory返回的路径创建文件失败，没有任何报错，排查了半天。
最后我采用了一个双保险策略：优先用path_provider的接口拿路径，如果拿到的路径不存在或者创建文件失败，就通过MethodChannel调用OpenHarmony原生的AbilityContext来获取filesDir，然后手动拼接子目录。这两条路总有一条能通，也是项目里处理路径类问题的通用兜底方案。遇到OpenHarmony上的插件问题，不要死磕一个入口。
5.2 SQLite原生库加载失败与FFI兜底
前面提到过sqflite在OpenHarmony上可能遇到libsqlite3.so加载失败的问题，这里展开说下。症状是App一打开数据库就报Failed to load libsqlite3.so，因为系统镜像里没有这个动态库，或者路径跟Android的不同。sqflite_common_ffi解决了这个问题，它允许通过FFI直接加载你打包进App的sqlite3动态库，不再依赖系统库。
但FFI方案也有坑，打包的sqlite3版本需要和OpenHarmony的libc++运行库兼容，版本不匹配会随机崩溃。我踩过一次之后，就固定在CI流水线里锁死sqlite3预编译版本，升级Flutter SDK或OpenHarmony SDK时重新跑一遍真机冒烟测试，避免兼容性问题隐性回归。
5.3 图表数据量大时的掉帧与内存抖动
第一个版本的周报图表直接查了整周的原始记录，每天几十条血压数据全部画到折线图上，真机上滑动报告页时明显掉帧。优化做了三件事：第一，图表只吃聚合后的数据，血压从一天几十条压成一天一条均值，整周最多7个点；第二，图表区域包了一层RepaintBoundary，避免图表重绘时波及整个页面；第三，报告页的长列表统一用ListView.builder，并在固定高度的地方直接给itemExtent，减少布局计算。
性能优化这件事在模拟器上基本看不出来，rk3568开发板上跑一遍原形毕露。我的经验是图表展示层必须做数据压缩，展示几十个点和展示几千个点的性能差距是数量级的，健康报告这种场景绝大多数情况下根本不需要展现全部原始数据。
5.4 多分辨率设备上的布局适配
OpenHarmony会跑在各种设备上，从几寸的开发板屏幕到手机都有。报告页的Card如果写死宽度，到小屏设备上直接溢出。我统一改用Flexible和Expanded做横向自适应，文本加maxLines和overflow控制，避免文案过长撑破布局。字体方面不要硬编码固定字号，跟随系统字体缩放比例，用户开了大字模式后，报告页至少不能乱掉。
6. 本地优先的数据同步：备份与多端兼容设计
6.1 离线优先：写入先行，同步排队
健康记录App有个特殊性，用户可能在电梯里、地铁上、医院走廊里记录数据，网络很差甚至没有。所以整个同步架构必须离线优先。所有写操作先落本地SQLite，同时往sync_queue表里插一条待同步操作，网络恢复后由同步引擎逐个执行。
健康报告的生成也完全走本地聚合，不依赖服务端。也就是说，即使设备全程断网，报告、图表、评分、PDF导出一样不少。云同步只是备份和多端拉取的手段，绝不做成功能的前置条件。
6.2 增量同步与冲突处理
同步实现上，每张数据表都有一个updated_at字段，同步引擎每次只拉取服务端updated_at大于本地游标的记录。上传方向，sync_queue表记录了新增、修改、删除三类操作，按时间顺序依次执行。冲突处理策略比较朴素：相同编号的记录以updated_at较新的为准，同时被覆盖掉的旧值会写入shadow表，这个表不参与业务查询，只在极端情况需要人工回溯时使用。
这套方案实现成本不高，但能把“换手机数据全没了”这种事故概率降到最低。健康数据的连续性太重要了，这些数据是用户几个月甚至几年的积累，一旦丢失，产品口碑直接崩掉。
6.3 导出JSON和数据库备份的兜底能力
除了端到端同步，我还保留了最原始的数据导出功能。在设置页里提供一个“导出全部数据”按钮，一键生成两个文件：一个JSON格式的完整数据导出，包含所有记录和元数据；一个是当前SQLite数据库文件的直接拷贝。JSON文件主要是给用户自己留存的，数据库文件则是给技术用户做深度分析用的。恢复时同样支持从JSON重建整个数据库，这个功能在换机和迁移场景下非常实用。
健康数据属于隐私敏感数据，同步通道必须走HTTPS，敏感字段在传输层之外再加密一层，数据库文件导出时也强制用用户设置的PIN码做加密，避免备份文件泄漏导致数据裸奔。
最后聊一点我个人在整个项目里的体会。健康报告这个模块，技术点拆开看都不新，SQL、图表、PDF、文件读写，每一样单独拿出来都是老掉牙的东西，但真把它们组织成一个能稳定跑在OpenHarmony上的闭环，最缺的不是技巧，而是把数据口径当成一等公民来对待的态度。单位不统一、时区不处理、空值不兜底，这些问题在Demo里藏得住，一旦跑上一周真实数据就全冒出来了。
另外一个经验是，跨端项目里不要迷信模拟器，我在rk3568开发板和手机上分别跑同一套导出代码，PDF表现差异肉眼可见，字体渲染和路径行为都以真机为准。如果你也在做类似的健康类应用，报告模块建议早做、独立做，别等到记录功能堆完再补，否则SQL层的数据质量会让你返工到怀疑人生。