一、先定义目录规划要解决的冲突训练目录同时面对三种变化课程条目会持续增加首页只需要少量摘要详情页却需要步骤、器材和场地等完整信息。如果把数组、筛选条件、收藏标记和详情跳转全部放在一个页面里新增分类会迫使多个视图一起改动数据异常也只能退化成空白列表。这份规划把目录能力限定为“本地课程读模型”负责提供稳定的分类、列表和详情查询不包含云端内容管理、付费课程、账号同步与训练计时。页面只消费查询结果不直接遍历原始常量。这样的边界既能承接现有本地课程也为以后增加远端数据源保留替换点。使用场景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(): PromiseReadonlyArrayTrainingModule queryCourses(query: CatalogQuery): PromiseReadonlyArrayCourseSummary getCourse(courseId: string): PromiseTrainingCourse | null resolveCourse(courseId: string): PromiseTrainingCourse } export class CourseNotFoundError extends Error { constructor(public courseId: string) { super(Course unavailable: ${courseId}) } }getCourse()允许详情页展示“课程已不可用”的温和状态resolveCourse()则适合训练启动前的强校验找不到课程就中止进入计时页。两个入口看似重复却能避免所有调用方用同一种异常策略。四、本地仓库负责校验、索引与版本迁移本地仓库在启动时建立courseId - course索引同时验证重复标识、空步骤和非法时长。校验失败时保留上一版有效快照并把错误转换成可记录的诊断结果。页面不会看到半份目录也不会因为一条坏数据导致全部课程不可用。export class LocalCourseRepository { private courses: Mapstring, TrainingCourse new Map() load(items: TrainingCourse[]): CatalogLoadResult { const next new Mapstring, 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): Promisevoid { 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 转换为稳定结果最后一类由请求令牌或页面生命周期取消处理。任何错误都不应触发删除收藏、重置计划或清空训练记录。失败条件默认行为用户可见反馈恢复动作新目录校验失败继续使用上一版快照顶部提示内容更新失败修复资源后重新加载未知模块返回空结果展示“暂无此分类”回到全部分类课程标识失效保留计划占位项标记课程待替换选择同模块替代课查询被新输入覆盖丢弃旧响应不显示额外错误展示最新关键词结果页面退出停止写入页面状态无提示重新进入后新建查询七、实施顺序从抽模型开始第一步把课程与模块接口移出页面保持原有数据和 UI 不变第二步建立本地仓库与索引校验第三步让列表、详情、今日推荐逐一改用 Service第四步加入失效标识和版本迁移最后才考虑 JSON 资源或远端数据源。每一步都必须保持旧入口可用不能一次性同时改数据、路由和视觉。迁移期间可以保留兼容适配器把旧数组包装成TrainingCatalogService。当列表、详情和计划三个消费者都不再直接读取旧数组后再删除适配器。这样回归范围清楚出现问题也能回滚到上一个边界。八、验收条件与后续证据计划静态验收包括所有课程标识唯一、时长和步骤合法、Service 不返回共享可变数组、页面不再直接读取原始目录。交互验收包括切换模块、连续输入关键词、从计划进入详情、打开失效课程、返回后恢复筛选条件。异常验收需要注入损坏资源、重复标识和空目录。后续证据应包含四组材料构建通过记录目录页、空结果页和失效课程页的真机截图连续搜索时旧请求不覆盖新结果的日志升级前后计划标识迁移对照。只有这些证据齐全后才适合把该主题改写为实现或实战文章。九、总结训练目录模块化的关键不是新增一个名为 Service 的文件而是让课程标识、查询契约、错误策略和页面状态各有明确归属。以本地读模型为起点可以在不承诺云端能力的前提下先解决可维护性并让未来的数据源替换、版本迁移与异常验收都有稳定接口可依赖。