简介

本开发文档围绕 DouPHP 的课程管理模块，系统阐述课程的增删改查、分类体系、章节管理、学习进度跟踪、发布与审核、版本控制、视频集成、在线学习与测验等教育功能的技术实现。文档面向开发者，提供从控制器到服务、模型、请求校验的完整链路说明，并给出可操作的代码路径引用、流程图与时序图，帮助快速定位与扩展。

项目结构

课程模块采用前后端分离的职责划分：

• 后台管理（Admin）：负责课程与分类的创建、编辑、删除、批量操作与列表展示。
• 前台展示（Front）：负责课程列表、详情展示、SEO、导航与访问统计。
• API（Api）：对外暴露课程相关接口（路由已定义）。
• 模型（Model）：数据表映射、关联查询、多语言与附件处理。
• 服务（Service）：业务规则封装（如构建列表数据、插入更新、删除、统计等）。
• 请求校验（Request）：字段白名单与校验规则集中管理。
• 路由（Route）：URL 到控制器的映射。
• 配置（Config）：分页、站点全局配置等。

graph TB
subgraph "后台管理"
AC["CourseController"]
CC["CategoryController"]
ASvc["CourseService"]
CSvc["CategoryService"]
AReq["CourseFormRequest / CategoryFormRequest"]
AModel["Course / CourseCategory(Admin)"]
end
subgraph "前台展示"
FC["CourseController(Front)"]
FModel["Course / CourseCategory(Front)"]
FRoute["front/route/course.php"]
end
subgraph "API"
AR["api/route/course.php"]
end
subgraph "配置"
CFG["Config"]
end
AC --> ASvc
CC --> CSvc
AC --> AReq
CC --> AReq
ASvc --> AModel
CSvc --> AModel
FC --> FModel
FC --> CFG
AR --> FC

核心组件

• 后台课程控制器：提供课程列表、新增、编辑、删除、批量操作；表单校验由 Request 完成；业务逻辑委托 Service。
• 后台分类控制器：提供分类树形列表、新增、编辑、删除；同样遵循 Request + Service + Model 分层。
• 前台课程控制器：课程列表与详情展示、SEO 元信息、导航、访问统计。
• 模型层：Admin/Front 两套模型分别承载后台与前台的数据访问与格式化；支持多语言、附件、时间格式化等。
• 服务层：封装课程与分类的业务流程（构建默认数据、列表数据、插入更新、删除、统计等）。
• 请求校验：统一字段白名单与校验规则，失败时抛出领域异常，由入口统一捕获并返回友好提示。
• 路由：后台、前台、API 三套路由分别指向对应控制器。

架构总览

课程模块遵循“控制器-服务-模型”的分层架构，配合请求校验与路由分发，形成清晰的职责边界。前台侧重展示与 SEO，后台侧重管理与数据维护，API 用于外部系统集成。

sequenceDiagram
participant Admin as "管理员"
participant AC as "后台课程控制器"
participant AReq as "课程表单请求"
participant ASvc as "课程服务"
participant AModel as "课程模型"
Admin->>AC : 提交新增/编辑
AC->>AReq : 注入并校验
AReq-->>AC : 校验通过的数据
AC->>ASvc : insert/update
ASvc->>AModel : 持久化
AModel-->>ASvc : 成功/失败
ASvc-->>AC : 结果
AC-->>Admin : 重定向或响应

详细组件分析

后台课程控制器（CourseController）

• 列表：支持按分类、关键词、分页查询，渲染课程列表页。
• 新增：清理草稿、生成草稿令牌、构建默认数据，渲染表单。
• 提交新增：使用表单请求校验后调用服务插入，成功后跳转编辑页。
• 编辑：根据 ID 加载课程数据，渲染编辑表单。
• 提交更新：校验后调用服务更新，成功后跳转编辑页。
• 删除：参数校验后调用服务删除，返回统一删除结果。
• 批量操作：调用服务执行批量动作。

flowchart TD
Start(["进入控制器方法"]) --> Validate["参数校验<br/>ID/分页/关键词"]
Validate --> |合法| BuildData["构建列表/默认/编辑数据"]
Validate --> |非法| ThrowErr["抛出领域异常"]
BuildData --> Render["渲染视图"]
Render --> End(["结束"])
ThrowErr --> End

后台分类控制器（CategoryController）

• 列表：渲染分类树，支持新增入口。
• 新增：构建默认数据，渲染表单。
• 提交新增：校验后插入分类，成功后跳转编辑页。
• 编辑：根据 ID 加载分类数据，渲染编辑表单。
• 提交更新：校验后更新分类，成功后跳转编辑页。
• 删除：参数校验后调用服务删除，返回统一删除结果。

前台课程控制器（CourseController）

• 列表：解析路由参数（分类、归档），读取分页配置，构建列表数据，渲染分类页。
• 详情：解析路由参数获取课程 ID，加载详情，记录访问统计，构建 SEO 与面包屑，渲染详情页。
• 辅助：构建分类信息，包含多语言与 URL。

sequenceDiagram
participant User as "访客"
participant FR as "前台路由"
participant FC as "前台课程控制器"
participant FSvc as "课程服务"
participant FModel as "课程模型"
User->>FR : 访问课程列表/详情
FR->>FC : 路由分发
FC->>FSvc : 构建列表/详情数据
FSvc->>FModel : 查询课程/分类
FModel-->>FSvc : 数据
FSvc-->>FC : 组装后的数据
FC->>FC : 记录访问统计/SEO
FC-->>User : 渲染页面

模型层（Admin/Front）

• 后台模型：用于管理界面数据访问与格式化。
• 前台模型：用于前端展示，包含多语言、附件、时间格式化、列表附加字段等。
• 分类模型：提供扁平树与层级树查询，便于后台选择与前台导航。

服务层（CourseService/CategoryService）

• 课程服务：构建课程列表数据、默认数据、编辑数据；执行插入、更新、删除、批量操作；记录访问统计。
• 分类服务：构建分类默认数据、编辑数据；执行插入、更新、删除。

请求校验（CourseFormRequest/CategoryFormRequest）

• 集中定义字段白名单与校验规则，按 Action 自动绑定场景。
• 校验失败抛出领域异常，由入口统一捕获并输出友好消息。

路由（Admin/Front/API）

• 后台路由：将课程与分类的管理操作映射到控制器方法。
• 前台路由：将课程列表与详情映射到前台控制器。
• API 路由：为外部系统提供课程相关接口（具体实现以实际路由为准）。

依赖关系分析

• 控制器依赖服务进行业务处理，服务依赖模型进行数据访问。
• 前台控制器依赖配置获取分页大小等系统设置。
• 请求校验器在控制器构造时注入，确保输入合法性。
• 路由文件将 URL 映射到控制器方法，形成请求入口。

graph LR
Route["路由"] --> Ctl["控制器"]
Ctl --> Req["请求校验"]
Ctl --> Svc["服务"]
Svc --> Mod["模型"]
Ctl --> Cfg["配置"]

性能与缓存

• 列表分页：前台通过配置项控制每页数量，避免一次性加载过多数据。
• 访问统计：详情页记录点击量，建议异步写入以降低首屏延迟。
• 多语言与附件：模型层对多语言字段与附件进行格式化，减少重复计算。
• 缓存策略建议：
  • 分类树：分类结构变化不频繁，可在服务层增加缓存键，命中则直接返回。
  • 课程列表：可按分类与分页维度缓存，结合失效策略（如课程更新时清除）。
  • SEO 元信息：可由服务层缓存并按分类/课程维度组织。
• 数据库优化：
  • 列表查询使用 with 预加载分类，减少 N+1 查询。
  • 合理索引 category_id、slug、created_at 等常用过滤与排序字段。

故障排查

• 参数非法：控制器对 ID、分页等参数进行校验，非法时抛出领域异常，统一返回错误页面或消息。
• 表单校验失败：请求校验器抛出异常，由入口捕获并提示用户修正。
• 数据不存在：编辑/删除时若 ID 无效或服务返回空，抛出异常并引导回列表。
• 常见问题定位：
  • 列表为空：检查分类筛选、关键词、分页参数是否正确。
  • 详情页报错：确认路由参数解析是否成功，课程是否存在。
  • 访问统计不更新：检查记录访问统计的服务调用是否被触发。

结论

课程管理模块通过清晰的分层架构与严格的请求校验，实现了稳定的 CRUD、分类体系、列表与详情展示、SEO 与访问统计等功能。服务层封装了主要业务规则，模型层提供了灵活的数据访问能力。建议在后续扩展中继续遵循此分层模式，并结合缓存与索引优化提升性能。

附录：API参考与扩展指南

API 路由概览

• 后台路由：课程与分类的管理接口（列表、新增、编辑、删除、批量）。
• 前台路由：课程列表与详情展示。
• API 路由：对外暴露课程相关接口（具体方法与实现需结合 api/route/course.php 与实际控制器/服务）。

典型操作流程（示例路径）

• 创建课程：
  • 后台控制器：admin/controller/course/CourseController.php:125-135
  • 表单校验：admin/request/course/CourseFormRequest.php
  • 服务插入：admin/service/course/CourseService.php
  • 模型持久化：admin/model/course/Course.php
• 管理章节：
  • 当前模块未提供独立章节控制器；可在课程详情或内容字段中组织章节结构，或通过扩展模型/服务添加章节关联与排序。
• 跟踪学习进度：
  • 当前模块未提供学习进度模型与服务；可通过扩展课程模型与用户模型建立“课程-用户-进度”关系，并在前台控制器中记录观看节点。
• 发布与审核：
  • 当前模块未提供审核状态字段；可在课程模型中添加 status 字段，并在服务层实现发布/下架逻辑。
• 版本控制：
  • 当前模块未提供版本表；可通过扩展课程模型与版本表记录变更历史，在服务层实现版本切换与回滚。
• 视频集成：
  • 当前模块未提供视频播放器集成；可在课程详情模板中嵌入第三方播放器，并通过附件字段存储视频链接。
• 在线学习与测验：
  • 当前模块未提供测验系统；可扩展课程模型与测验模型，建立题目、选项、答案与用户作答记录，并在前台控制器中记录答题进度。