4.3 KiB
完成页「统一分页架构」— 审查报告(禁止应用)
审查对象:虚拟节点 (PlayerItem.completion) 作为 TabView 最后一页,CompletionView 内嵌于播放器;是否导致「完成小节统计虚高」。
结论:仅审查,不修改仓库内任何文件。
一、核心问题:会不会导致完成小节统计虚高?
结论:不会。
1.1 数据流梳理
| 环节 | 来源 / 行为 | 是否计入「完成小节」 |
|---|---|---|
| 展示数字 | CompletionView 显示的 completedLessonCount 来自 UserManager.shared.studyStats.lessons |
仅展示,不写入 |
| 统计来源 | studyStats.lessons 由后端/用户接口(如 completed_lessons)拉取并写入 UserManager |
后端口径为真实完课数 |
| 完课上报 | 仅在 LessonPageView 内,当该节进度 ≥ 1.0 时调用 LearningService.shared.completeLesson(nodeId: ...) |
只对真实课程节点上报 |
| 虚拟节点 | PlayerItem.completion 仅存在于前端的 allItems,id 为 "COMPLETION_PAGE" |
不参与任何完课 API,无 nodeId |
1.2 为何不会虚高
- 总结页不是一节课:虚拟节点只用于 TabView 的「最后一页」展示,没有对应的
MapNode,也不会调用completeLesson(nodeId:)。 - 完课只发生在 LessonPageView:只有渲染
PlayerItem.lesson(node)时才会加载该节的进度、在达到条件时上报完课;渲染PlayerItem.completion时只渲染 CompletionView,没有任何完课或统计写入逻辑。 - 展示用既有统计:CompletionView 只是读取并展示
UserManager.shared.studyStats.lessons,不修改该值;该值的增加只来自真实小节在 LessonPageView 中的完课上报与后端同步。
因此:把总结页当作 TabView 最后一页、用虚拟节点渲染 CompletionView,不会把总结页算成一节,也不会导致完成小节统计虚高。
二、方案本身审查(与当前实现对比)
2.1 优点
- 交互统一:左滑/右滑完全由 TabView(UIScrollView)负责,无需自定义 DragGesture、无需 SwipeBackEnabler。
- CompletionView 职责单一:只做 UI 与「回到技能页根」按钮,不碰 navigationPath、不碰侧滑 Hack。
- 状态集中:完结页是
PlayerItem枚举的一支,与课程节点同属一个数据源,逻辑清晰。
2.2 需注意的改动(若将来应用)
-
VerticalScreenPlayerView 的 init
方案中去掉了navigationPath、isLastNode、courseTitle。当前 GrowthView / ProfileView / DiscoveryView 的.player分支会传这三个参数;若直接按方案改 init,调用方会报错。需要二选一:- 保留这三个参数(兼容现有调用),或
- 同时改三处调用方,不再传这些参数。
-
CompletionView 的接口
方案中 CompletionView 只有courseTitle和completedLessonCount(无courseId)。若项目中别处仍通过CourseNavigation.completion(courseId: ...)等 push 进 CompletionView,则需保留courseId或同步改那些入口。 -
进度条与 TabBar
当前实现有currentPositionProgress(不含占位页)、hideTabBar/showTabBar、loadError、toast 等。方案里进度条在currentNodeId == "COMPLETION_PAGE"时隐藏,其余若省略需确认是否要保留(如错误态、toast、tabBar 隐藏)。 -
笔记流
NoteTreeView / NoteListView 里用的 VerticalScreenPlayerView 目前传的是NoteNavigationDestination.player,不传 navigationPath。若播放器 init 去掉 navigationPath,笔记流不受影响;若保留可选 navigationPath 以兼容,也需在方案里写明。
三、审查结论汇总
| 问题 | 结论 |
|---|---|
| 会不会导致完成小节统计虚高? | 不会。总结页只是虚拟的一页,用于展示;完课统计只由 LessonPageView 对真实节点调用 completeLesson 产生,CompletionView 仅读取 studyStats.lessons 做展示。 |
| 统一分页架构本身 | 交互简单、无需手势与侧滑 Hack,CompletionView 可做纯 UI;若应用需处理 init 与调用方兼容、以及错误/toast/tabBar 等现有能力是否保留。 |
未对仓库内任何文件进行修改。