当前位置：首页 > news >正文

足球口袋教练 HarmonyOS 规划（22）：训练目录 Service 与本地课程模型边界

news 2026/7/25 2:23:55

一、先定义目录规划要解决的冲突

训练目录同时面对三种变化：课程条目会持续增加，首页只需要少量摘要，详情页却需要步骤、器材和场地等完整信息。如果把数组、筛选条件、收藏标记和详情跳转全部放在一个页面里，新增分类会迫使多个视图一起改动，数据异常也只能退化成空白列表。

这份规划把目录能力限定为“本地课程读模型”：负责提供稳定的分类、列表和详情查询，不包含云端内容管理、付费课程、账号同步与训练计时。页面只消费查询结果，不直接遍历原始常量。这样的边界既能承接现有本地课程，也为以后增加远端数据源保留替换点。

使用场景	Service 输入	页面得到的结果	不在本期范围
首页推荐	日期、画像摘要	一条可进入的课程摘要	自动生成完整训练计划
分类浏览	模块标识、关键词	排序后的课程卡片	云端搜索与推荐算法
课程详情	课程标识	完整步骤与安全提示	视频下载与版权管理
计划回看	计划中的课程标识	可恢复的课程摘要	多账号跨端同步

二、用读模型隔离页面和原始数据

目录模型需要区分“可存储的领域数据”和“直接展示的派生字段”。颜色、选中态、是否为今日任务都属于页面派生结果，不应混入课程主数据；课程时长、难度、步骤和所属模块则需要稳定标识，才能被计划与训练记录引用。

export interface TrainingCourse { id: string moduleId: string title: string subtitle: string durationMinutes: number difficulty: '入门' | '进阶' | '挑战' focus: string steps: string[] scenario?: string equipment?: string venue?: string version: number } export interface CourseSummary { id: string moduleId: string title: string durationMinutes: number difficulty: string matchedKeyword: boolean }

稳定的id是计划、收藏和记录之间的连接点。标题可以修改，模块可以重新排序，但历史记录不能因为文案变化而失去关联。version用于本地目录升级：旧计划引用已下架课程时，可以按版本映射到替代课程，而不是直接删除用户的计划项。

三、Service 契约只暴露业务查询

页面不应该知道课程来自常量、JSON 资源还是本地数据库。Service 对外只提供查询语义，并统一处理空关键词、未知模块和失效课程标识。接口返回只读数组或新对象，避免页面修改共享数据后影响其他页面。

export interface CatalogQuery { moduleId?: string keyword?: string limit?: number } export interface TrainingCatalogService { listModules(): Promise<ReadonlyArray<TrainingModule>> queryCourses(query: CatalogQuery): Promise<ReadonlyArray<CourseSummary>> getCourse(courseId: string): Promise<TrainingCourse | null> resolveCourse(courseId: string): Promise<TrainingCourse> } export class CourseNotFoundError extends Error { constructor(public courseId: string) { super(`Course unavailable: ${courseId}`) } }

getCourse()允许详情页展示“课程已不可用”的温和状态；resolveCourse()则适合训练启动前的强校验，找不到课程就中止进入计时页。两个入口看似重复，却能避免所有调用方用同一种异常策略。

四、本地仓库负责校验、索引与版本迁移

本地仓库在启动时建立courseId -> course索引，同时验证重复标识、空步骤和非法时长。校验失败时保留上一版有效快照，并把错误转换成可记录的诊断结果。页面不会看到半份目录，也不会因为一条坏数据导致全部课程不可用。

export class LocalCourseRepository { private courses: Map<string, TrainingCourse> = new Map() load(items: TrainingCourse[]): CatalogLoadResult { const next = new Map<string, TrainingCourse>() const errors: string[] = [] for (const item of items) { if (!item.id || next.has(item.id)) { errors.push(`duplicate id: ${item.id}`) continue } if (item.durationMinutes < 5 || item.steps.length === 0) { errors.push(`invalid course: ${item.id}`) continue } next.set(item.id, { ...item, steps: item.steps.slice() }) } if (next.size > 0) { this.courses = next } return { accepted: next.size, errors } } }

版本迁移不应在页面渲染时临时判断。计划仓库读取旧任务后先执行标识映射，再交给目录 Service 解析。映射失败的任务保留标题与时长，并标记为“待替换”，这样用户仍能理解原计划发生了什么。

五、页面状态只保留一次查询的生命周期

目录页需要明确区分首次加载、已有数据刷新、空结果和加载失败。把它们压缩成一个items.length === 0会混淆“没有匹配课程”和“数据源不可用”。ViewModel 保存查询条件与请求序号，较早请求返回时不能覆盖较新的关键词结果。

export type CatalogPhase = 'idle' | 'loading' | 'ready' | 'empty' | 'error' export class CatalogViewModel { phase: CatalogPhase = 'idle' items: CourseSummary[] = [] message: string = '' private requestToken: number = 0 async search(service: TrainingCatalogService, query: CatalogQuery): Promise<void> { const token = ++this.requestToken this.phase = 'loading' try { const result = await service.queryCourses(query) if (token !== this.requestToken) return this.items = result.slice() this.phase = result.length === 0 ? 'empty' : 'ready' } catch (error) { if (token !== this.requestToken) return this.phase = 'error' this.message = '目录暂不可用，请稍后重试' } } }

ArkUI 组件绑定phase、items和查询条件，点击课程后只传递courseId。详情页重新调用 Service 获取完整模型，避免把一个可能过期的大对象塞进路由参数。状态管理的基础约束可参考华为开发者文档。

六、失败和降级路径要先于远端扩展

目录设计至少覆盖四类失败：资源文件损坏、课程标识重复、计划引用失效、查询期间页面退出。前三类由仓库与 Service 转换为稳定结果，最后一类由请求令牌或页面生命周期取消处理。任何错误都不应触发删除收藏、重置计划或清空训练记录。

失败条件	默认行为	用户可见反馈	恢复动作
新目录校验失败	继续使用上一版快照	顶部提示内容更新失败	修复资源后重新加载
未知模块	返回空结果	展示“暂无此分类”	回到全部分类
课程标识失效	保留计划占位项	标记课程待替换	选择同模块替代课
查询被新输入覆盖	丢弃旧响应	不显示额外错误	展示最新关键词结果
页面退出	停止写入页面状态	无提示	重新进入后新建查询