# 网上培训课程 — 功能需求

## 1. 文档说明

| 项 | 说明 |
| --- | --- |
| 模块名称 | 网上培训课程（科技平台与服务） |
| 目标 | 在业务后台以**只读目录**方式集中展示可供学习的视频培训课程，便于运营人员检索、核对课程信息；课程主数据在**畜牧科技资源管理 → 视频课程库**维护，本模块不重复建档 |
| 关联系统 | 业务后台；**畜牧科技资源管理**（视频课程库）；移动端「农技课堂」等在线学习场景（展示已发布课程，**本期本模块不负责移动端页面**） |
| 修订依据 | 同目录 `网上培训课程功能需求-草稿.md`、界面原型（`Snipaste_2026-05-21_21-11-25.jpg`） |

本文档**仅描述功能需求与业务规则**，不涉及数据库表结构、接口路径、请求体字段命名、HTTP 报文、权限标识命名及技术栈选型。

---

## 2. 术语与业务对象

### 2.1 培训课程（一条展示记录）

- 表示一条可在本模块**查询、查看**的**网上培训视频课程**。  
- **不**在本模块新增、修改、删除或发布；内容的增删改与上下架均在 **畜牧科技资源管理 → 视频课程库** 完成。  
- 本模块展示的是源库中满足 **§2.2 纳入规则** 的课程在当前时刻的**业务快照**（字段含义与源库「视频课程」一致，见 **§2.3**）。

### 2.2 数据来源与纳入规则

培训课程数据**来自**畜牧科技资源管理中的**视频课程库**，本模块与源库关系如下：

| 规则 | 说明 |
| --- | --- |
| 资源类型 | 仅纳入源库中资源类型为 **视频课程** 的记录 |
| 发布状态 | 仅纳入 **已发布** 的记录（**未发布**、**已下架** 不在本模块列表与详情中展示） |
| 删除状态 | 源库已 **逻辑删除** 的记录不展示 |
| 一致性原则 | 列表、详情所见内容以源库**当前有效数据**为准；源库编辑并再次发布后，本模块再次查询应看到更新后的信息；源库**下架**或**删除**后，该课程从本模块消失，**不宜**继续对外提供查看入口 |

> 原型标注「同步畜牧科技资源中的视频课程库」：业务含义为**按上述规则从源库汇聚展示**，而非在本模块维护一套独立课程台账。是否采用实时查询或定时刷新属实施细节，**对用户**应表现为：打开列表/详情时与源库已发布课程一致。

### 2.3 字段与源库对应关系

本模块界面用语与源库「视频课程」字段对应如下（维护规则以《畜牧科技资源管理 — 功能需求》**§5.7** 为准）：

| 本模块展示名 | 业务含义 | 源库维护要点（摘要） |
| --- | --- | --- |
| **课程标题** | 课程名称 | 必填；**1～20** 字 |
| **课程简介** | 课程说明 | 必填；**1～500** 字 |
| **课程主题** | 分类主题 | 必填；存资讯类别编码（`parentCode=005`、`categoryType=8`）；展示名称由类别接口解析 |
| **视频文件** | 课程视频 | 必填；**mp4**；单文件 **≤ 30MB** |
| **封面** | 课程封面图 | 选填；图片 **jpg/jpeg/png**；**≤ 10MB**（列表可不展示，**详情须展示**若有） |

### 2.4 列表筛选项与匹配关系

| 筛选项 | 与记录字段关系 |
| --- | --- |
| 课程标题 | 对 **课程标题** **模糊**匹配；空则不过滤 |
| 课程主题 | 对 `course_topic` **编码** **精确**匹配；空则不过滤；下拉来自资讯类别 `children`（`parentCode=005`、`categoryType=8`） |

---

## 3. 功能范围

### 3.1 本期实现

| 能力 | 说明 |
| --- | --- |
| 培训课程列表 | 分页；课程标题模糊、课程主题精确筛选；见 **§5.1** |
| 查看培训课程详情 | 只读展示源库全部业务字段（含封面、视频）；见 **§5.2** |

### 3.2 本期不实现（除非后续单独立项）

| 能力 | 说明 |
| --- | --- |
| 新增 / 修改 / 删除培训课程 | 在 **畜牧科技资源管理 → 视频课程库** 完成 |
| 发布 / 下架 | 同上 |
| 本模块「同步」按钮或手工导入 | 数据纳入规则见 **§2.2**，无需运营在本模块触发同步 |
| 视频播放进度、学习人数、收藏、评论 | 属在线学习或运营分析能力 |
| 批量导出、打印、课程推荐排序 | 未在草稿范围 |
| 移动端播放页 | 由移动端/其他模块承担；本模块为后台查阅 |

---

## 4. 业务流程概览

### 4.1 模块内流程（只读）

```mermaid
flowchart TD
    A[进入网上培训课程] --> B[培训课程列表]
    B --> C{筛选?}
    C -->|课程标题/课程主题| B
    C -->|重置| B
    B --> D[查看详情]
    D --> E[只读展示全部字段]
    E --> B
    B --> F[返回列表继续检索]
```

### 4.2 与源库协同流程（跨模块）

```mermaid
flowchart LR
    subgraph 源库维护
        M1[畜牧科技资源管理-视频课程库]
        M2[新增/编辑-未发布或已下架]
        M3[发布]
        M4[下架或删除]
        M1 --> M2
        M2 --> M3
        M3 --> M4
    end
    subgraph 本模块展示
        N1[网上培训课程列表/详情]
    end
    M3 -->|已发布且未删除| N1
    M4 -->|不再纳入| N1
```

**典型使用顺序：**

1. 内容人员在 **视频课程库** 维护课程标题、简介、主题、视频与封面，**发布**后对外生效。  
2. 运营或管理人员进入 **网上培训课程**，按标题或主题检索，在列表核对信息，必要时 **查看** 详情确认视频与文案。  
3. 若需修改课程内容或下线，须回到 **视频课程库** **下架 → 编辑 → 再发布**（规则见源库需求 **§5.8、§5.11**）；本模块不提供编辑入口。

---

## 5. 详细功能需求

### 5.1 查询培训课程列表

#### 5.1.1 筛选区

| 条件 | 规则 |
| --- | --- |
| 课程主题 | 选填；**下拉选择**；选项与 **§2.4** 一致；选定后与记录 **课程主题** **完全一致** 才命中 |
| 课程标题 | 选填；文本输入；对 **课程标题** **包含** 关键词即命中（忽略首尾空白后参与匹配） |
| 搜索 | 按当前条件刷新列表，**从第 1 页** 开始 |
| 重置 | 清空课程主题、课程标题，恢复默认列表 |

#### 5.1.2 列表规则

| 项 | 规则 |
| --- | --- |
| 数据范围 | 仅 **§2.2** 纳入的记录 |
| 默认每页条数 | **20** 条（与平台列表惯例一致） |
| 默认排序 | **创建时间倒序**（同批课程以源库登记先后展示；若产品统一按发布时间排序，须与源库发布日期字段对齐后全文一致） |
| 无数据 | 展示空状态提示，如「暂无培训课程」；区分「无已发布课程」与「筛选无结果」时宜用不同提示（可选） |

#### 5.1.3 展示列（与原型一致）

| 列名 | 展示说明 |
| --- | --- |
| 课程标题 | 全文展示；过长时列表可省略号，**详情见完整标题** |
| 课程简介 | 列表可 **摘要**（如前 50 字 + 省略号）；完整内容在详情 |
| 课程主题 | 全文展示 |
| 视频文件 | 展示**可识别的文件名称**或「已上传」等状态文案；**不在列表内嵌播放**；播放与下载在 **详情** 进行 |
| 操作 | 仅 **查看** |

#### 5.1.4 列表不提供的能力

- **无** 新增、编辑、删除、发布、下架按钮。  
- **无** 行内跳转至源库编辑（若需联动，可作为后续增强：从详情提供「前往视频课程库维护」说明性链接，**本期可不实现**）。

---

### 5.2 查看培训课程详情

#### 5.2.1 入口

- 列表行 **查看**。  
- 进入后为**只读**页或弹窗，**无** 保存、发布、删除等写操作按钮。

#### 5.2.2 展示内容

须展示该课程在源库中的**全部业务字段**（**§2.3**），至少包括：

| 内容 | 要求 |
| --- | --- |
| 课程标题 | 全文 |
| 课程简介 | 全文；保留换行 |
| 课程主题 | 全文 |
| 视频文件 | 提供 **在线预览播放** 或 **可打开的访问方式**（与平台文件服务策略一致）；若文件不可用，明确提示「视频不可用，请联系管理员」 |
| 封面 | 若源库有封面则展示预览；无封面则展示占位或「—」 |
| 辅助信息（建议） | 源库 **发布状态** 在本模块恒为已发布，可不重复强调；可选展示源库 **创建时间 / 最近更新时间**，便于运营核对版本 |

#### 5.2.3 详情约束

| 场景 | 行为 |
| --- | --- |
| 记录仍在纳入范围 | 正常展示 **§5.2.2** |
| 打开详情时源库已下架或已删除 | **不宜** 继续展示有效内容；提示如「该课程已下线或不存在」，并提供返回列表 |
| 从书签/历史入口访问已失效 id | 同上 |

#### 5.2.4 与列表的差异

- 详情展示 **视频可播放** 及 **封面**（若有）；列表 **视频文件** 列仅作标识，不强制播放。  
- 详情 **课程简介** 为全文；列表可为摘要。

---

## 6. 操作与权限（业务层）

在**已授权**前提下：

| 操作 | 本模块 |
| --- | --- |
| 查询列表 | ✓ |
| 查看详情 | ✓ |
| 新增 / 修改 / 删除 | ✗（在源库完成） |
| 发布 / 下架 | ✗（在源库完成） |

权限宜按「查询」「查看」拆分控制；无权限时不展示菜单或禁用 **查看**。具体权限编码由实施配置，**本文档不命名**。

---

## 7. 纳入与剔除示例（自查）

| 源库状态 | 源库类型 | 逻辑删除 | 本模块列表 | 本模块详情 |
| --- | --- | --- | --- | --- |
| 已发布 | 视频课程 | 否 | 可见 | 可查看 |
| 未发布 | 视频课程 | 否 | 不可见 | 不可查看（无入口） |
| 已下架 | 视频课程 | 否 | 不可见 | 不可查看 |
| 已发布 | 专家/成果/仪器 | 否 | 不可见 | 不可见 |
| 已发布 | 视频课程 | 是 | 不可见 | 不可查看 |

---

## 8. 错误与提示约定

面向使用方的提示宜语义明确，例如：

| 场景 | 提示方向（示例） |
| --- | --- |
| 列表无数据 | 「暂无已发布的培训课程」 |
| 筛选无结果 | 「未找到符合条件的培训课程」 |
| 详情记录已失效 | 「该课程已下线或不存在」 |
| 视频无法加载 | 「视频暂时无法播放，请稍后重试或联系管理员」 |
| 无查看权限 | 「无权限查看该课程」 |

本文档**不约定** HTTP 状态码、错误码字段名及接口报文结构。

---

## 9. 非功能需求（建议）

| 类别 | 建议 |
| --- | --- |
| 权限 | 列表查询、详情查看分权；与源库维护权限分离 |
| 性能 | 列表分页；纳入规则过滤宜在服务端完成，避免先取全量再筛选 |
| 一致性 | 与源库发布时间、下架、删除的生效时机保持一致，避免本模块长期展示已下线课程 |
| 文件安全 | 视频、封面访问遵循平台上传与鉴权策略 |
| 国际化 | 界面 i18n（汉语 + 藏文，若适用） |

---

## 10. 与畜牧科技资源管理的衔接

| 事项 | 约定 |
| --- | --- |
| 维护入口 | 课程内容的唯一维护入口为 **畜牧科技资源管理 → 视频课程库** |
| 发布生效 | 仅源库 **已发布** 课程进入本模块；运营在本模块看到的即为「已对移动端/学习场景生效」的课程目录 |
| 字段口径 | 课程标题、简介、主题、视频、封面的校验与长度以源库 **§5.7** 为准，本模块**不另设**更宽或更窄规则 |
| 下线影响 | 源库 **下架** 或 **删除** 后，本模块立即（或准实时）不再展示；已收藏的本模块详情链接应失效并提示 |
| 下游学习 | 移动端在线学习使用同源 **已发布** 视频课程；本模块侧重后台查阅与核对，**不替代** 移动端播放体验 |

---

## 11. 相对草稿的修订说明

| 草稿内容 | 处理 |
| --- | --- |
| 技术栈、MySQL、RuoYi | 已移除 |
| `code`、`msg`、`data` 统一返回 | 已移除 |
| 列表字段编号重复（2 与 6） | 整理为 **§5.1.3** |
| 「数据来自视频课程库」 | 展开为 **§2.2 纳入规则**、**§4.2 跨模块流程**、**§10** |
| 仅列查询与查看 | 补充范围边界、列表/详情差异、失效场景、操作矩阵、自查表 |
| 未说明能否在本模块改课 | 明确 **只读**，维护在源库（**§3.2**） |

---

## 12. 需求追溯

| 能力 | 章节 |
| --- | --- |
| 数据来源与纳入 | §2.2、§7、§10 |
| 列表筛选与展示 | §5.1 |
| 查看详情 | §5.2 |
| 模块内 / 跨模块流程 | §4 |
| 权限与范围 | §3、§6 |
| 提示语 | §8 |
