集成AI教育方案-Flutter

通用集成

AI 教育场景基于 AliPlayerWidget 组件构建。如果尚未完成通用集成步骤，请先参考：

• 集成指引：组件集成（添加依赖、初始化）。

• 快速开始：组件基础用法。

配置 App Server 与测试媒体

打开 example/lib/pages/ai_education/ai_constants.dart，修改以下两项配置：

static const String appServerBaseUrl = 'http://your-server-host:port';

static const String defaultMediaId = 'your-media-id';

验证集成

示例工程已内置 AI 教育场景页面，入口信息如下：

页面启动后会自动加载播放凭证与AI分析内容并起播。播放后若看到进度条上出现章节标记点、竖屏底部栏上方出现章节条，即表示集成成功；点击示例页面左上角的章节按钮可打开章节与 AI 解析面板。

全局业务流程

全局业务流程描述 AI 分析结果从生产、存储到端侧消费的完整链路。

VOD 负责媒体资产与 AI 分析结果的统一存储；ICE / AI 工作流负责内容理解与结构化分析；App Server 封装服务端能力，向端侧提供统一接口。

端侧分层架构

端侧采用三层设计：场景示例层（example/lib/pages/ai_education/）、组件能力层（aliplayer_widget）与播放器 SDK（flutter_aliplayer）。章节 UI 能力位于组件能力层，只要业务层向 AliPlayerWidgetData.chapters 传入有效数据即可生效，不强制要求页面使用 SceneType.aiVod。

数据与控制在 Flutter 端的分层关系如下图所示：

获取播放凭证

请求示例：

GET http://your-server-host:port/appServer/GetVideoPlayAuth?videoId=201558617a9e71f1bfb9e6e7e5780102

响应示例：

{
  "code": 0,
  "success": true,
  "data": {
    "videoId": "your-video-id",
    "playAuth": "eyJ..."
  }
}

响应字段说明：

获取 AI 分析内容

请求示例：

GET http://your-server-host:port/GetMediaAiAnalysisByResultType?MediaId=201558617a9e71f1bfb9e6e7e5780102

响应示例：

{
  "AiAnalysisResult": [
    {
      "ResultType": "Chapter",
      "Title": "视频章节",
      "chapterContentItems": [
        {
          "ChapterId": 1,
          "StartTime": 0,
          "EndTime": 120000,
          "ChapterTitle": "课程介绍",
          "Summary": "本章节介绍课程的整体框架...",
          "ThumbnailUrl": "https://example.com/thumb1.jpg",
          "KnowledgePoints": [
            { "PointId": 1, "Point": "核心概念", "Description": "描述内容..." }
          ]
        }
      ]
    },
    {
      "ResultType": "Summary",
      "Title": "视频摘要",
      "summaryContent": {
        "ParagraphSummary": "本视频主要讲述了...",
        "MindMapSummary": [
          { "Title": "核心概念", "Topics": [] }
        ],
        "MarkdownContent": "# 课程摘要..."
      }
    }
  ]
}

章节字段说明：

摘要字段说明：

接口约定：

数据映射

展示模型

最终组装产物为 AiContentViewModel，由 AiContentAssembler.buildViewModel(AiAnalysisResponse) 一次性生成，作为 AI 解析面板的唯一数据入口：

AI 解析面板的 Tab 样式不再体现在聚合模型字段上，而是由面板内部根据数据推导：

端侧数据架构

端侧采用数据组装与 UI 渲染分离的分层设计：服务端响应先落地为纯 DTO，再由组装器转换为展示模型，最后交给 UI 层渲染。

数据流转：

服务端 JSON → AiAnalysisResponse（DTO）→ AiContentAssembler → AiContentViewModel → 播放器配置 / AI 解析面板

端侧模型说明：

设计原则：

• 单一职责：DTO 只负责 JSON 映射，组装器只负责数据转换，UI 只负责渲染。

• 三级降级：KnowledgeInfo.contentMarkdown 生成规则为 KnowledgePoints 优先 → Summary 其次 → 两者皆空则为 null。

• 时间有序：章节与知识点列表按时间范围有序且不重叠，findIndexByPosition 以二分查找定位当前项。

替换数据源

示例工程通过 AiContentLoader 加载数据（dio 实现，5 秒连接与接收超时，支持 cancel() 取消）。接入自有数据源时，可参考其流程替换数据加载逻辑，只要最终能产出 AiAnalysisResponse DTO 即可复用整条组装链路：

final loader = AiContentLoader();
loader.loadPlayAuth(vid, (playAuth) {
  // 获取到 playAuth 后，继续加载 AI 分析内容
  loader.loadAiAnalysis(vid, (response) {
    // response 为纯 DTO，消费方需显式调用 AiContentAssembler 组装
    final content = response != null
        ? AiContentAssembler.buildViewModel(response)
        : null;
    // 配置播放器，详见 8.3
  });
});

自定义 UI

• 替换 AI 解析面板样式：复制 example/lib/pages/ai_education/chapter_content_panel_widget.dart 后按需修改布局与样式，面板对外仅暴露 showChapterContentPanel(...) 一个入口。

• 扩展插槽：通过 AliPlayerWidget 的 slotBuilders 注册自定义插槽。示例工程使用自定义插槽实现左上角章节按钮：

static const _slotTypeChapterShow = SlotType(
  'chapterShowButton',
  defaultOrder: 55,
);

AliPlayerWidget(
  _controller,
  slotBuilders: {
    _slotTypeChapterShow: (context) => ChapterButtonWidget(
      controller: _controller,
      onTap: () => _showChapterContentPanel(context),
    ),
  },
);

• 复用章节列表面板：组件内置的右侧滑入章节列表面板可独立唤起：

ChaptersPanelManager.showChaptersPanel(
  context: context,
  chapters: chapters,
  currentIndex: currentIndex,
  onChapterSelected: (index) {
    _controller.seek(Duration(milliseconds: chapters[index].startMs));
  },
);

• 插槽机制的详细说明见插槽系统，场景能力说明见场景类型。

接入自有页面

如果不使用示例页面，可参考其实现在自己的页面中完成以下步骤：

1. 创建 AliPlayerWidgetController。

2. 请求播放凭证与 AI 分析内容。

3. 组装 AiContentViewModel，配置 AliPlayerWidgetData（chapters 必填；sceneType 按需设置，示例使用 SceneType.aiVod）。

4. 注册章节按钮等自定义插槽。

5. 点击章节时调用 showChapterContentPanel 展示 AI 内容。

6. 页面销毁时取消加载任务并销毁控制器。

示例骨架：

class AiEducationPage extends StatefulWidget {
  const AiEducationPage({super.key});

  @override
  State<AiEducationPage> createState() => _AiEducationPageState();
}

class _AiEducationPageState extends State<AiEducationPage> {
  late final AliPlayerWidgetController _controller;
  AiContentLoader? _contentLoader;
  AiContentViewModel _content = const AiContentViewModel(
    chapters: [],
    knowledgeItems: [],
  );

  static const _slotTypeChapterShow = SlotType(
    'chapterShowButton',
    defaultOrder: 55,
  );

  @override
  void initState() {
    super.initState();
    _controller = AliPlayerWidgetController();

    const vid = AiContentConstants.defaultMediaId;
    final loader = AiContentLoader();
    _contentLoader = loader;

    // 链式加载：PlayAuth → AI 内容 → 配置播放器
    loader.loadPlayAuth(vid, (playAuth) {
      if (playAuth == null || playAuth.isEmpty) return;
      loader.loadAiAnalysis(vid, (response) {
        if (response != null) {
          _content = AiContentAssembler.buildViewModel(response);
        }
        _configure(vid, playAuth);
      });
    });
  }

  void _configure(String vid, String playAuth) {
    final source = VideoSourceFactory.createVidAuthSource(
      vid: vid,
      playAuth: playAuth,
    );
    _controller.configure(
      AliPlayerWidgetData(
        videoSource: source,
        sceneType: SceneType.aiVod,
        chapters: _content.chapters,
      ),
    );
  }

  void _showChapterContentPanel(BuildContext context) {
    if (!_content.hasAnyContent) return;
    final position = _controller.currentPositionNotifier.value;
    final currentIndex = ChapterInfo.findIndexByPosition(
      _content.chapters,
      position.inMilliseconds,
    );
    showChapterContentPanel(
      context: context,
      content: _content,
      currentIndex: currentIndex,
      onChapterSelected: (index) {
        final chapter = _content.chapters[index];
        _controller.seek(Duration(milliseconds: chapter.startMs));
      },
      onSegmentSelected: (startMs) {
        _controller.seek(Duration(milliseconds: startMs));
      },
    );
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: AliPlayerWidget(
        _controller,
        slotBuilders: {
          _slotTypeChapterShow: (context) => ChapterButtonWidget(
            controller: _controller,
            onTap: () => _showChapterContentPanel(context),
          ),
        },
      ),
    );
  }

  @override
  void dispose() {
    _contentLoader?.cancel();
    _controller.destroy();
    super.dispose();
  }
}