课程管理API | DouPHP 开发手册 | 文档中心 | DouPHP企业建站系统

课程管理API

简介

本文件面向在线教育平台开发者，提供“课程管理模块”的完整API参考。内容覆盖课程创建、编辑、上下架、批量操作；课程章节管理与课时安排；课程内容类型（视频、图文、直播等）；学习进度跟踪；课程评价与评分；权限控制（免费、付费、会员专享）；推荐与个性化学习路径；以及课程数据统计分析（报名人数、完成率、满意度等）。文档基于仓库中现有代码进行梳理，对尚未实现的能力给出扩展建议与落地方案。

项目结构

课程能力由前台API、后台管理、服务层与模型层共同构成：

前台API控制器：提供课程列表与详情查询
后台管理控制器：提供课程的CRUD、分类管理、批量操作
路由：声明式注册前后端路由
服务层：封装业务逻辑（列表构建、详情构建、统计、评论集成等）
模型层：数据访问与字段映射、多语言、附件处理等

graph TB
subgraph "前台API"
A["api/controller/course/CourseController"]
R1["api/route/course.php"]
end
subgraph "后台管理"
B["admin/controller/course/CourseController"]
C["admin/controller/course/CategoryController"]
R2["admin/route/course.php"]
end
subgraph "服务层"
S1["front/service/course/CourseService"]
S2["admin/service/course/CourseService"]
end
subgraph "模型层"
M1["front/model/course/Course"]
end
R1 --> A
R2 --> B
R2 --> C
A --> S1
B --> S2
C --> S2
S1 --> M1

核心组件

前台课程控制器：提供课程列表与详情接口，支持分类、归档、分页、点击量记录与评论聚合
后台课程控制器：提供课程新增、编辑、删除、批量操作，表单校验通过请求对象完成
后台课程分类控制器：提供分类的增删改查
服务层：
- 前台CourseService：构建课程列表数据、详情数据、分类信息、访问统计、评论聚合
- 后台CourseService：课程CRUD、批量动作、默认数据构建、编辑数据构建
模型层：课程模型定义表名、字段映射、多语言、附件、时间格式化及列表展示附加字段

架构总览

前后端分离的REST风格设计：

前台API：只读为主，提供课程列表与详情
后台管理：完整的CRUD与批量操作
服务层：统一业务编排，屏蔽底层细节
模型层：数据访问与属性转换

sequenceDiagram
participant Client as "客户端"
participant API as "前台CourseController"
participant Svc as "前台CourseService"
participant Model as "Course模型"
participant Comment as "评论模块"
Client->>API : GET /api/?route=course (列表/详情)
API->>Svc : buildCourseListData()/buildCourseShowData()
Svc->>Model : 查询课程/分类/附件/多语言
Model-->>Svc : 课程数据
Svc->>Comment : 获取课程评论(可选)
Comment-->>Svc : 评论列表
Svc-->>API : 组装后的数据
API-->>Client : JSON响应

详细组件分析

前台课程API

课程列表
- 功能：按分类或归档获取课程列表，支持分页
- 关键参数：id/category_slug（分类）、year/month（归档）、page（页码）
- 返回：标题、分类树、课程列表、分类信息
课程详情
- 功能：根据id/slug获取课程详情，累计点击量，附带评论列表
- 关键参数：id/category_slug/slug、page（评论分页）
- 返回：课程详情、自定义字段、评论列表

flowchart TD
Start(["进入课程列表/详情"]) --> Parse["解析分类/归档/分页参数"]
Parse --> BuildList{"是否列表?"}
BuildList -- 是 --> ListData["调用服务构建列表数据"]
ListData --> ReturnList["返回课程列表与分类树"]
BuildList -- 否 --> ShowData["调用服务构建详情数据"]
ShowData --> RecordView["记录访问统计"]
RecordView --> FetchComments["获取评论列表"]
FetchComments --> ReturnDetail["返回课程详情与评论"]

后台课程管理

课程列表
- 功能：按分类、关键词、分页查询课程
新增/编辑
- 功能：表单渲染与提交，字段校验由请求对象完成
- 流程：store/update -> Service.insert/update -> 重定向并提示
删除
- 功能：单条删除，返回统一删除结果
批量操作
- 功能：批量上下架、移动分类等，由Service.action统一处理

sequenceDiagram
participant Admin as "管理员"
participant Ctrl as "后台CourseController"
participant Req as "CourseFormRequest"
participant Svc as "后台CourseService"
Admin->>Ctrl : POST 新增/更新
Ctrl->>Req : validated()
Req-->>Ctrl : 校验通过的数据
Ctrl->>Svc : insert()/update()
Svc-->>Ctrl : 持久化结果
Ctrl-->>Admin : 重定向+成功消息

课程分类管理

分类列表：扁平树展示
新增/编辑/删除：标准CRUD
关联：课程与分类一对多，课程列表可过滤分类

课程内容类型与章节管理

内容类型
- 通过模型的“自定义字段”机制（defined_pairs）与内容字段（content）承载不同格式（视频、图文、直播等）
- 列表与详情均会输出自定义字段，便于前端按类型渲染
章节与课时
- 建议在自定义字段中维护章节数组（如章节标题、顺序、课时列表），或通过扩展表关联章节实体
- 排序可通过章节数组的order字段实现
课时安排
- 可在课时项中设置开始/结束时间、是否必修、是否解锁等规则

说明：当前代码未直接暴露章节管理的控制器与路由，可按以下模式扩展：

新增后台控制器与方法：章节CRUD、排序、课时管理
在CourseService中增加章节序列化/反序列化方法
在前台CourseService中提供章节与课时访问接口

学习进度跟踪

现状：课程详情包含点击量统计，用于访问计数
建议扩展：
- 学员维度学习状态：已报名、进行中、已完成
- 完成度统计：按章节/课时粒度计算完成比例
- 学习记录：记录观看/阅读行为（开始、暂停、完成、停留时长）
实现思路：
- 新增“学习记录”表与对应服务
- 在课程播放/阅读入口埋点写入记录
- 提供接口查询个人进度与统计

课程评价与评分系统

现状：课程详情聚合评论列表（通过模块注入comment）
建议扩展：
- 评分：为每条评论或独立评分记录打分
- 评分统计：平均分、星级分布
- 评论管理：审核、置顶、举报
实现思路：
- 复用评论模块或新建评分子模块
- 在服务层聚合评分统计
- 提供接口供前端展示评分与评论

课程权限控制

现状：课程模型支持自定义字段，可用于标记免费/付费/会员专享
建议扩展：
- 在课程元数据中标记访问模式
- 前台接口根据用户身份与会员状态决定是否放行
- 付费课程对接订单/支付流程，完成后授予访问权限
实现思路：
- 在CourseService中增加权限校验方法
- 结合vip/order模块完成授权判断

课程推荐与个性化学习路径

现状：未实现推荐算法
建议扩展：
- 基于用户历史学习、收藏、搜索、评分等行为生成推荐
- 提供“为你推荐”“继续学习”“相似课程”等接口
- 结合标签、分类、难度、热度等多维特征
实现思路：
- 新增推荐服务，离线或在线计算候选集
- 提供接口返回推荐课程列表

课程数据统计分析

现状：课程详情包含点击量
建议扩展：
- 报名人数：统计购买/报名订单数
- 完成率：基于学习记录计算
- 满意度：基于评分统计
- 趋势分析：按日/周/月统计关键指标
实现思路：
- 新增统计服务，聚合订单、学习、评分数据
- 提供报表接口

依赖关系分析

控制器依赖服务层，服务层依赖模型与外部模块（如评论）
路由将URL映射到控制器方法
表单请求对象负责字段白名单与校验

graph LR
Route_API["api/route/course.php"] --> Ctrl_API["api/controller/course/CourseController"]
Route_Admin["admin/route/course.php"] --> Ctrl_Admin["admin/controller/course/CourseController"]
Route_Admin --> Ctrl_Category["admin/controller/course/CategoryController"]
Ctrl_API --> Svc_Front["front/service/course/CourseService"]
Ctrl_Admin --> Svc_Admin["admin/service/course/CourseService"]
Svc_Front --> Model_Course["front/model/course/Course"]
Ctrl_Admin --> FormReq["admin/request/course/CourseFormRequest"]

性能考虑

列表分页：使用分页参数避免全量加载
缓存：对课程分类树、热门课程列表做缓存
懒加载：详情中的评论按需加载
索引优化：为常用查询字段建立索引（如category_id、created_at）
并发：批量操作采用事务保证一致性

故障排查指南

页面错误：当分类或课程不存在时抛出领域异常，检查路由参数与ID有效性
表单校验失败：由CourseFormRequest校验规则拦截，检查字段白名单与必填项
评论为空：确认评论模块是否启用且存在评论数据
批量操作失败：检查传入的IDs与动作类型是否正确

结论

当前仓库提供了课程的前台读取与后台管理基础能力，包括课程列表、详情、分类管理与CRUD。针对章节管理、学习进度、评价评分、权限控制、推荐算法与统计分析等高级能力，建议基于现有服务与模型进行扩展，保持前后端职责清晰、服务层集中编排、模型层专注数据访问。

附录：接口清单与数据模型

前台API

课程列表
- 方法：GET
- 路径：/api/?route=course
- 参数：id/category_slug、year/month、page
- 返回：title、category_id、course_list、course_category、cate_info
课程详情
- 方法：GET
- 路径：/api/?route=course/{id}
- 参数：id/category_slug/slug、page
- 返回：course、defined、comment、title

后台管理

课程列表
- 方法：GET
- 路径：?route=course
- 参数：category_id、keyword、page
新增课程
- 方法：POST
- 路径：?route=course/create
- 校验：CourseFormRequest
编辑课程
- 方法：POST
- 路径：?route=course/edit
- 校验：CourseFormRequest
删除课程
- 方法：POST
- 路径：?route=course/destroy
批量操作
- 方法：POST
- 路径：?route=course/action
分类管理
- 方法：GET/POST/PUT/DELETE
- 路径：?route=course/category[/<action>]

数据模型（课程）

表名：course
关键字段：
- category_id：分类ID
- click：点击量
- image：封面图（附件）
- defined：自定义字段对（用于内容类型、权限等）
- created_at：创建时间
列表附加字段：add_time_short、time、name、description、url、favorites、cate_info
多语言：title/content/description随当前语言覆写

添加日期：2026-10-05