企业官网建设流程全解析

• 教育
• 后端
• 前端

本指南以 Oppia 仓库中 core/templates/pages/exploration-player-page/services/README.md 为核心骨架，结合该目录下 39 个 Angular 服务实现与配套测试，系统讲解共享服务层在“现有 Lesson Player”与“新 Lesson Player”双实现共存架构中的定位、职责划分、编码规范与测试方法。读完本文，你将掌握该目录内每个核心服务的功能边界、它们之间的调用关系，以及如何安全地新增或修改一个被多页面共享的 Angular 服务。

一、背景：为什么需要一个“共享服务层”

在 Oppia 中，学习者与“探索（Exploration）”交互的页面统称为 Lesson Player。目前仓库中存在两套并行的播放器实现：

• current-lesson-player：现有播放器，按其目录内 README.md 的说明，该实现已被标记为deprecated，待新播放器完全上线后将整体移除；
• new-lesson-player：新播放器，目标是更好的用户体验与可访问性、更强的移动端响应式表现，以及更清晰的模块化代码架构，其推进状态跟踪见 README.md。

两套播放器虽然 UI 与组件树不同，但底层有一大批业务逻辑是完全一致的：答案判定、卡片流转、提示/解答管理、进度统计、音频图片预加载……如果各自复制一份，必然导致行为漂移与维护灾难。因此 exploration-player-page 目录 下的 services 目录专门存放被两套播放器共享的服务文件，从源码结构看，它是整个播放器模块的“公共业务内核”，也是原 README 定义本文主题的出发点。

从目录级 README（exploration-player-page/README.md）可以确认这一分层决策：current-lesson-player与new-lesson-player各管各的组件，/services则承载两者共用的逻辑。

二、服务清单：39 个共享服务一图览

目录下共有 39 个*.service.ts文件，且每个服务都配有同名*.spec.ts单元测试（共 39 个），形成“一服务一测试”的强约束。按职责可划分为如下几组：

1. 引擎与模式（播放器的“大脑”）

2. 会话状态与流转（卡片、转录、位置）

3. 检查点（Checkpoint）与进度持久化

4. 内容辅助：提示、解答、概念卡、模态框

5. 资源预加载：图片、音频、翻译

6. 答案与学习行为数据

7. 后端 API 封装与杂项

8. 初始化

从依赖方向上看，目录内存在清晰的分层结构：底层是AnswerClassificationService、PlayerTranscriptService、NumberAttemptsService等无副作用的基础服务；中间是ExplorationEngineService、QuestionPlayerEngineService、DiagnosticTestPlayerEngineService三个引擎；顶层是ConversationFlowService、ExplorationInitializationService与CurrentEngineService/ExplorationModeService组成的调度层。新播放器可以复用除顶层 UI 状态之外的几乎所有服务。

三、编码规范：README 的两条硬性要求

原 README 在 Guidelines 一节给出了两条必须遵守的开发准则，结合源码可以进一步明确其执行标准：

1. 为所有新增服务/新方法编写规范的 JsDoc

查看目录内的服务实现，可以看到每一处公开方法都有标准的 JsDoc 注释，例如 answer-classification.service.ts 中的classifyAnswer注释清晰说明了参数类型与返回值；image-preloader.service.ts 对kickOffImagePreloader(sourceStateName)的参数含义也做了逐行说明。

实践要点：

• 每个服务文件头部必须有@fileoverview注释，一句话概括该服务的职责（本目录所有文件均遵守）；
• 每个公开方法写清参数类型、返回值类型与副作用；
• 如果属性初始化依赖 Angular 生命周期或init方法，需要使用非空断言（!），并在注释中说明原因——这是 exploration-engine.service.ts 等文件的既有模式。

2. 服务被多组件、多页面共享，改动必须谨慎

从服务构造函数可以直观看到共享程度：例如 conversation-flow.service.ts 注入了 30 余个依赖，exploration-engine.service.ts 同样注入十余个服务。任何一个服务的签名或行为变化，都可能沿着依赖图波及其余数十个服务与组件。README 要求：

• 谨慎改动：优先保持方法签名兼容，新增行为而不是修改既有行为；
• 彻底测试：按下一节的流程执行完整验证。

四、测试策略：三层验证流程

原 README 在 Testing Recommendations 中给出了三层测试流程，以下是结合仓库实际的展开：

第一层：单元测试（Unit Tests）

每个服务都必须有配套的*.spec.ts，覆盖预期行为、边界情况与错误处理。目录内 39 个服务与 39 个测试文件一一对应。

以 answer-classification.service.spec.ts 为例，测试应至少覆盖：

• 正常命中：答案命中某个答案组的规则时，返回正确的AnswerClassificationResult（含分组索引、规则索引）；
• 回退行为：所有规则均未命中时，返回默认结果；
• 错误处理：defaultOutcome缺失时抛出异常，并触发AlertsService警告；
• 边界情况：空答案组列表、空规则列表、特殊类型答案等。

对于有内部状态的服务（如 player-transcript.service.ts），还需覆盖状态恢复、重复添加卡片、首卡回退抛错等场景。

第二层：依赖组件测试（Dependent Component Tests）

由于服务被多个组件共享，单测通过不代表集成安全。需要运行所有依赖该服务的组件测试，检查是否产生非预期的副作用。在仓库中，播放器相关组件测试位于：

• exploration-player-page.component.spec.ts（现有播放器）
• lesson-player-page.component.spec.ts（新播放器）

修改任何共享服务后，建议同时跑通这两个播放器的组件测试，以及所有依赖注入链上的服务测试。

第三层：手动验证（Manual Verification）

自动化测试无法覆盖真实交互体验，README 特别强调手动走查应用，确认所有使用该服务的功能按预期工作。这对“新旧播放器共享”的服务尤其重要。建议手动验证的路径包括：

1. 以/explore/:id进入现有播放器完成一次完整探索（作答→反馈→提示→解答→下一卡）；
2. 开启新播放器特性开关后以/lesson/:id重复上述流程（开关方式见 new-lesson-player/README.md）；
3. 验证编辑器预览模式（/create/:id）、练习题会话与诊断测试模式下的服务行为；
4. 验证弱网/慢加载场景下图片与音频预加载的降级表现。

注：新播放器通过new_lesson_player特性开关控制，开启后所有/explore/:id链接会自动重定向至/lesson/:id。因此双实现验证可以高效合并：开关开启时走新播放器，关闭时走旧播放器，手动确认两套 UI 下共享服务行为一致。

五、新增共享服务的完整实践路径

结合 README 规范与仓库既有实现，新增一个共享服务的推荐流程如下：

1. 先评估共享必要性：确认该逻辑确实会被两套播放器共用；若仅属于某一套播放器的 UI 表现，应放入对应播放器目录（current-lesson-player/或new-lesson-player/）而非 services 目录；
2. 创建服务文件：参照 number-attempts.service.ts 的最小实现范式——文件头版权声明与@fileoverview、@Injectable({providedIn: 'root'})、公开方法带完整 JsDoc；
3. 编写单元测试：创建同名.spec.ts，覆盖预期行为、边界与错误分支；
4. 接入依赖注入：在需要处注入服务；若服务间有循环依赖风险，参照ExplorationInitializationService的“临时服务解耦”思路拆分；
5. 跑依赖测试：执行依赖该服务的组件测试（新旧播放器两侧）；
6. 手动走查：在真实页面中验证新旧播放器下的行为一致性。

六、总结

exploration-player-page/services目录是 Oppia 播放器前端的“公共内核”：39 个共享服务以 Angular 依赖注入组织成“基础服务 → 三大引擎 → 调度层”的清晰层次，支撑着现有与新两代 Lesson Player。其 README 强调的两条准则——规范 JsDoc、谨慎改共享代码——以及“单元测试 → 依赖组件测试 → 手动验证”的三层流程，正是保障这套被多页面共用的服务层长期稳定演进的工程基石。对于计划向播放器新增能力的开发者，本文的服务清单、调用链分析与测试路径可作为直接的手册与查漏工具。

• 教育
• 后端
• 前端