【听见课堂 HarmonyOS NEXT 实战系列 48】复盘页的完成度和掌握度从哪里来：指标口径设计

复盘页最容易出现“数字看起来很专业，实际没人说得清怎么算”的问题。听见课堂把完成度、重点标记率、板书数和待处理数集中在 ClassroomService.getReviewSnapshot() 聚合，但代码审计也暴露出两个需要明确标注的口径边界。

一、指标必须先写分母，再谈百分比

“完成度 80%”没有分母就没有业务含义。它可能是全部候选、已确认任务、今天任务或全部课程任务中的完成比例。

项目当前把主指标命名为“已确认任务完成度”，正常情况下分母是已确认任务数，分子是其中已完成的任务数。

二、完成度的正常计算公式

Service 先从全部任务中过滤 confirmed=true，再从确认集合中过滤 completed=true。只要已确认任务非空，就使用四舍五入后的比例。

const confirmedTasks = tasks.filter((item: TaskItem) => item.confirmed);
const completedTasks = confirmedTasks.filter((item: TaskItem) => item.completed);
const completionPercent = confirmedTasks.length > 0
  ? Math.round(completedTasks.length * 100 / confirmedTasks.length)
  : Math.round(course.progress * 100);

候选任务不会降低正式任务完成度。

三、无已确认任务时并不是返回 0

当前代码在分母为 0 时回退到 course.progress * 100。这能避免首页种子课程没有任务时出现空指标，但与 UI 标签“已确认任务完成度”并不完全一致。

因此文章和验收都应说明这是课程进度兜底，而不能把它解释为“0 个任务中完成了某个比例”。

四、兜底口径应在界面上可辨认

更严谨的设计可以让 Snapshot 同时返回 completionSource，例如 confirmed_tasks 或 course_progress_fallback。页面据此显示“任务完成度”或“课程进度参考”。

只返回一个数字会丢失来源，使用户和测试人员难以判断当前百分比属于哪套口径。

五、当前“掌握度”实际是重点标记率

代码以重点字幕数除以全部字幕数。页面后续已将标签明确为“重点标记率”，这是比泛化的“掌握度”更诚实的表达。

重点标记说明用户认为该字幕重要，不等于经过测验证明已经掌握，也不能作为学习能力评分。

六、没有字幕时为何返回 0

当字幕集合为空时，masteryPercent 返回 0，避免除零。这个 0 表示“没有可计算的字幕证据”，而不应被解释为用户完全未掌握课程。

理想 UI 可以显示“暂无字幕数据”，把缺失证据与真实低比例区分开。

七、keyPointCount 来自人工标记

keyPointCount 统计 TranscriptSegment.isKeyPoint。在当前实现里，这是用户对字幕的人工重点标记，不是模型置信度阈值或自动知识点识别结果。

所以页面文案使用“已从真实课堂记录中标记”，不会虚构自动理解能力。

八、scanCount 只是板书记录数量

scanCount = scans.length，表示当前 Repository 中有多少条扫描记录。它不等于 OCR 正确页数，也不代表每条扫描都已经人工复核。

若以后要展示“已复核板书”，模型必须新增确认状态，而不是复用记录数量。

九、pendingCount 当前包含哪些任务

现有代码直接统计全部任务中 !completed 的记录，没有先过滤 confirmed。因此未完成候选也会进入 pendingCount。

这与“待处理任务”可以相容，因为候选本身也需要处理；但若文案写成“待办任务”，用户可能误以为它只统计任务中心里的正式任务。

十、为什么候选计入待处理需要显式说明

复盘页文案写着“还有若干项任务未完成，确认后可在任务中心持续跟进”，一定程度上承认其中可能有候选。但同一数字还被用于“薄弱”图例时，语义就显得过宽。

更清晰的 Snapshot 应拆成 pendingConfirmedCount 与 candidateCount，让 UI 分别展示。

十一、所有指标必须来自 canonical data

页面不会在完成任务时自行给百分比加一，而是写入 Repository 后重新调用 getReviewSnapshot()。字幕重点、板书和任务变化也都通过同一聚合入口刷新。

这能避免 P07、P09 和首页各自形成不同统计口径。

十二、Snapshot 是页面与规则的契约

ReviewSnapshot 只暴露完成比例、重点比例、重点数、板书数、待处理数和时间线条目。ArkUI 负责卡片、环形进度与说明文案，不重新遍历 Repository 数据。

若指标定义变化，应先修改 Service 和模型，再更新页面标签与测试，而不是只改显示数字。

十三、四舍五入也属于产品规则

当前使用 Math.round()，例如 2/3 显示为 67%。测试用例应验证分子、分母和舍入方式，避免不同端分别使用向下取整或保留小数。

比例只是展示值；原始计数仍应保留用于解释和诊断。

十四、指标不能替代证据时间线

百分比只能回答“整体多少”，不能回答“为什么”。听见课堂允许从复盘总览进入时间线，查看具体字幕、板书和任务来源。

指标与可追溯节点同时存在，才能避免黑箱评分。

十五、建议的验收数据集

至少构造：无任务无字幕、只有课程进度、有候选无确认、有确认无完成、部分完成、全部完成、无字幕、有字幕无重点、多个重点、存在板书等组合。

每组都应核对原始集合、Snapshot 字段、页面标签与空态说明，并特别检查候选是否被计入待处理数。

十六、总结

复盘指标的可信度取决于口径是否可解释。听见课堂已把计算集中到 Service，并把“掌握度”收敛为重点标记率；但无确认任务时的课程进度兜底，以及候选计入待处理数，仍需要在模型和 UI 中更明确地区分。

下一篇继续拆解：字幕、板书和任务如何组成一条可回看的课堂证据时间线。