督学网站AI交付清单
2026-04-08

下面给你一份可直接给开发落地的最终交付清单。
我按你现在的要求整理：**只做需求 1 和 4；以后端接口为主；尽量不动旧系统和旧表；采用新增 API 文件 + 新表的外挂式方案。**需求 1 和 4 的原始范围来自你上传的需求文档：观看视频中弹出验证码输入框、数据模块增加学员学习统计。

一、最终实施结论

1. 这次建议怎么做

采用：

方案

新增 2 张表
新增 2 个路由文件
新增 3 个 Controller
新增 2 个 Service
新增 2 个 Model
新增 2 个 migration
只改 1 个旧文件：app/Providers/RouteServiceProvider.php

这已经是你当前约束下的最小改动方案了。

2. 这次不建议做的事

为了满足你“不改动现有系统和表”这个前提，这次不建议：

不改旧 courses 表
不改旧 videos 表
不改旧 user_watch_stat 表
不改旧 user_video_watch_records 表
不改旧 StatsController
不改旧 VideoController 学习上报主逻辑

3. 这次方案的能力边界

这个一定要讲清楚：

能做到

后台给课程配置“播放过程验证码规则”
前端按播放进度来问后端“现在要不要弹验证码”
前端提交验证码，后端校验并记录
后台查看年度学习统计、个人学习时长排行、个人年度学习明细

还做不到

后端强制拦截未通过验证码的继续学习

因为旧播放/旧上报链路没动。
这次是外挂增强，不是深改播放器内核。

二、文件级交付清单

下面是你项目里建议新增/修改的真实路径级清单。

2.1 需要新增的文件

1）路由文件

routes/backend-v3-custom.php
routes/frontend-v3-watch-captcha.php

2）后台 Controller

app/Http/Controllers/Backend/Api/V3/VodWatchCaptchaController.php
app/Http/Controllers/Backend/Api/V3/StudyStatsController.php

3）前台 Controller

app/Http/Controllers/Api/V3/VideoWatchCaptchaController.php

4）Service

app/Services/Custom/VodWatchCaptchaService.php
app/Services/Custom/StudyStatsService.php

5）Model

app/Models/VodWatchCaptchaConfig.php
app/Models/VodWatchCaptchaLog.php

6）数据库迁移

database/migrations/2026_04_08_000001_create_vod_watch_captcha_configs_table.php
database/migrations/2026_04_08_000002_create_vod_watch_captcha_logs_table.php

2.2 需要修改的旧文件

只改这一个

app/Providers/RouteServiceProvider.php

修改目的

让 Laravel 能识别你新增的两个路由文件，否则新接口不会生效。

三、每个文件是干什么的

3.1 `routes/backend-v3-custom.php`

作用：后台管理端接口入口。

包含接口

验证码配置

GET /backend/api/v3/vod-watch-captcha/course/{courseId}
PUT /backend/api/v3/vod-watch-captcha/course/{courseId}

学习统计

GET /backend/api/v3/study-stats/years
GET /backend/api/v3/study-stats/overview
GET /backend/api/v3/study-stats/users
GET /backend/api/v3/study-stats/users/{userId}

3.2 `routes/frontend-v3-watch-captcha.php`

作用：前台播放器调用。

包含接口

GET /api/v3/video/{id}/watch-captcha/check
POST /api/v3/video/{id}/watch-captcha/verify

3.3 `VodWatchCaptchaController.php`

作用：后台配置课程验证码规则。

职责

查某课程当前验证码配置
保存某课程验证码配置

3.4 `StudyStatsController.php`

作用：后台学习统计接口。

职责

查有哪些年度
查某年度总览
查某年度个人排行
查某个学员的年度明细

3.5 `VideoWatchCaptchaController.php`

作用：给前台播放器使用。

职责

判断当前播放进度是否需要弹窗
校验学员输入的验证码

3.6 `VodWatchCaptchaService.php`

作用：验证码业务核心服务。

职责

读取课程配置
计算等分触发点
判断当前是否该弹窗
生成验证码
记录 PENDING / PASSED / EXPIRED
校验验证码

3.7 `StudyStatsService.php`

作用：统计业务服务。

职责

复用 user_watch_stat
聚合年度学习秒数
统计个人时长排行
查询个人年度月度明细
查询个人 Top 课程

3.8 `VodWatchCaptchaConfig.php`

作用：课程验证码配置模型。

3.9 `VodWatchCaptchaLog.php`

作用：学员验证码校验记录模型。

四、数据库交付清单

4.1 新表 1：`vod_watch_captcha_configs`

作用

记录某个课程是否开启验证码，及触发规则。

关键字段

course_id
is_enabled
trigger_type
trigger_value
code_length
expire_seconds

4.2 新表 2：`vod_watch_captcha_logs`

作用

记录某个用户某个视频某次触发点的验证码校验情况。

关键字段

biz_no
user_id
course_id
video_id
trigger_order
trigger_second
verify_code
input_code
status
fail_count
passed_at
expired_at

五、接口交付清单

5.1 后台：课程验证码配置

1）查询配置

GET /backend/api/v3/vod-watch-captcha/course/{courseId}

返回示例

{
  "code": 0,
  "message": "success",
  "data": {
    "course_id": 12,
    "is_enabled": 1,
    "trigger_type": "equal_parts",
    "trigger_value": 3,
    "code_length": 4,
    "expire_seconds": 300,
    "remark": ""
  }
}

2）保存配置

PUT /backend/api/v3/vod-watch-captcha/course/{courseId}
Content-Type: application/json

请求体

{
  "is_enabled": 1,
  "trigger_type": "equal_parts",
  "trigger_value": 3,
  "code_length": 4,
  "expire_seconds": 300,
  "remark": "录播防挂机验证码"
}

5.2 前台：视频播放验证码

1）检查是否需要弹窗

GET /api/v3/video/{videoId}/watch-captcha/check?duration=360

返回示例

{
  "code": 0,
  "message": "success",
  "data": {
    "need_popup": 1,
    "course_id": 12,
    "video_id": 101,
    "trigger_order": 1,
    "trigger_second": 300,
    "display_code": "4821",
    "biz_no": "A8C9F0D4E12B..."
  }
}

2）提交验证码校验

POST /api/v3/video/{videoId}/watch-captcha/verify
Content-Type: application/json

请求体

{
  "biz_no": "A8C9F0D4E12B...",
  "input_code": "4821"
}

返回示例

{
  "code": 0,
  "message": "success",
  "data": {
    "is_passed": 1,
    "message": "验证通过"
  }
}

5.3 后台：学习统计

1）查可选年份

GET /backend/api/v3/study-stats/years

2）查年度总览

GET /backend/api/v3/study-stats/overview?year=2026

3）查个人排行

GET /backend/api/v3/study-stats/users?year=2026&page=1&size=20&keywords=

4）查某人年度明细

GET /backend/api/v3/study-stats/users/{userId}?year=2026

六、开发实施顺序

这个顺序你可以直接给后端同事照着做。

第一步：建表

先执行 migration，创建：

vod_watch_captcha_configs
vod_watch_captcha_logs

第二步：加 Model

新增：

VodWatchCaptchaConfig
VodWatchCaptchaLog

第三步：加 Service

新增：

VodWatchCaptchaService
StudyStatsService

先把核心逻辑写完。

第四步：加 Controller

新增：

后台 VodWatchCaptchaController
后台 StudyStatsController
前台 VideoWatchCaptchaController

第五步：加路由文件

新增：

routes/backend-v3-custom.php
routes/frontend-v3-watch-captcha.php

第六步：改 `RouteServiceProvider.php`

把两个新路由文件挂进去。

第七步：联调

联调顺序建议：

联调 A：验证码配置链路

后台保存课程验证码配置
后台读取课程验证码配置

联调 B：播放验证码链路

学员看视频
前端传 duration
后端判断是否需要弹窗
返回验证码
提交校验
校验通过

联调 C：学习统计链路

查年度列表
查年度总览
查个人排行
查个人年度明细

七、上线前检查清单

7.1 数据库检查

两张新表是否建成功
course_id 唯一索引是否存在
biz_no 唯一索引是否存在
组合索引是否存在

7.2 路由检查

执行：

php artisan route:list

确认出现这些接口：

/backend/api/v3/vod-watch-captcha/course/{courseId}
/backend/api/v3/study-stats/years
/backend/api/v3/study-stats/overview
/backend/api/v3/study-stats/users
/backend/api/v3/study-stats/users/{userId}
/api/v3/video/{id}/watch-captcha/check
/api/v3/video/{id}/watch-captcha/verify

7.3 权限检查

这里有个待确认点：

待确认

你们后台 V2 现有接口很多都挂了 mbp: 权限中间件。
我这次给的是最小方案，只挂了 auth:administrator。

如果你们线上后台接口必须走权限点，那你还需要补：

BackendPermission 常量
对应菜单权限配置

否则管理员只要登录就能调这些接口。

7.4 统计数据检查

确认现网里这些表字段真实存在：

user_watch_stat.year
user_watch_stat.month
user_watch_stat.seconds
user_watch_stat.user_id
user_video_watch_records.watch_seconds
user_video_watch_records.updated_at

7.5 部门统计检查

当前状态

本版接口里 department_name 先返回 null

原因

因为你要求：

不改旧表
新做接口和表

而现有 users 表没有现成部门字段可直接用。
所以“按部门统计”这部分这次只能先留兼容位，不能真聚合。

八、你现在可以直接交付给开发的任务拆分

后端任务 1：录播验证码配置

目标

完成课程级验证码配置接口。

输出物

新表 vod_watch_captcha_configs
后台查询/保存接口

后端任务 2：录播验证码校验

目标

完成播放器调用的验证码判断与校验接口。

输出物

新表 vod_watch_captcha_logs
前台 check / verify 接口

后端任务 3：学习统计

目标

完成年度学习统计接口。

输出物

年份列表
年度总览
个人排行
个人年度明细

前端任务 1：后台课程编辑页

目标

在“编辑录播课程”里补验证码配置项。

前端需要接的字段

is_enabled
trigger_type
trigger_value
code_length
expire_seconds
remark

前端任务 2：播放器

目标

播放过程中按进度问后端是否需要弹验证码。

前端流程

轮询或进度回调
调 check
若 need_popup = 1，弹窗
输入验证码
调 verify
成功后继续播放

前端任务 3：数据统计页面

目标

新增“学员学习统计”页面。

页面建议

顶部：年份切换
中间：总时长 / 学员数 / 学习第一名
下方：个人学习排行
详情弹层：个人年度月度明细 + Top 课程

九、我建议你对开发再补一句话

你可以直接发给开发：

本次只做需求 1 和 4，后端采用外挂式最小改动方案：
1）不改旧表；
2）新增 2 张表承接验证码配置和验证码日志；
3）新增 backend/api/v3 和 api/v3 的路由与控制器；
4）学习统计复用现有 user_watch_stat，不做历史迁移；
5）部门统计先预留字段，当前返回 null；
6）本期不做后端硬拦截播放，仅提供验证码判定与校验能力。

十、最后再帮你压一句最关键的话

这次真正要落地的文件就是这些

新增：
routes/backend-v3-custom.php
routes/frontend-v3-watch-captcha.php

app/Http/Controllers/Backend/Api/V3/VodWatchCaptchaController.php
app/Http/Controllers/Backend/Api/V3/StudyStatsController.php
app/Http/Controllers/Api/V3/VideoWatchCaptchaController.php

app/Services/Custom/VodWatchCaptchaService.php
app/Services/Custom/StudyStatsService.php

app/Models/VodWatchCaptchaConfig.php
app/Models/VodWatchCaptchaLog.php

database/migrations/2026_04_08_000001_create_vod_watch_captcha_configs_table.php
database/migrations/2026_04_08_000002_create_vod_watch_captcha_logs_table.php

修改：
app/Providers/RouteServiceProvider.php

督学网站AI交付清单 2026-04-08

一、最终实施结论

1. 这次建议怎么做

方案

2. 这次不建议做的事

3. 这次方案的能力边界

能做到

还做不到

二、文件级交付清单

2.1 需要新增的文件

1）路由文件

2）后台 Controller

3）前台 Controller

4）Service

5）Model

6）数据库迁移

2.2 需要修改的旧文件

只改这一个

修改目的

三、每个文件是干什么的

3.1 routes/backend-v3-custom.php

包含接口

验证码配置

学习统计

3.2 routes/frontend-v3-watch-captcha.php

包含接口

3.3 VodWatchCaptchaController.php

职责

3.4 StudyStatsController.php

职责

3.5 VideoWatchCaptchaController.php

职责

3.6 VodWatchCaptchaService.php

职责

3.7 StudyStatsService.php

职责

3.8 VodWatchCaptchaConfig.php

3.9 VodWatchCaptchaLog.php

四、数据库交付清单

4.1 新表 1：vod_watch_captcha_configs

作用

关键字段

4.2 新表 2：vod_watch_captcha_logs

作用

关键字段

五、接口交付清单

5.1 后台：课程验证码配置

1）查询配置

返回示例

2）保存配置

请求体

5.2 前台：视频播放验证码

1）检查是否需要弹窗

返回示例

2）提交验证码校验

请求体

返回示例

5.3 后台：学习统计

1）查可选年份

2）查年度总览

3）查个人排行

4）查某人年度明细

六、开发实施顺序

第一步：建表

第二步：加 Model

第三步：加 Service

第四步：加 Controller

第五步：加路由文件

第六步：改 RouteServiceProvider.php

第七步：联调

联调 A：验证码配置链路

联调 B：播放验证码链路

联调 C：学习统计链路

七、上线前检查清单

7.1 数据库检查

7.2 路由检查

7.3 权限检查

待确认

7.4 统计数据检查

7.5 部门统计检查

督学网站AI交付清单
2026-04-08

3.1 `routes/backend-v3-custom.php`

3.2 `routes/frontend-v3-watch-captcha.php`

3.3 `VodWatchCaptchaController.php`

3.4 `StudyStatsController.php`

3.5 `VideoWatchCaptchaController.php`

3.6 `VodWatchCaptchaService.php`

3.7 `StudyStatsService.php`

3.8 `VodWatchCaptchaConfig.php`

3.9 `VodWatchCaptchaLog.php`

4.1 新表 1：`vod_watch_captcha_configs`

4.2 新表 2：`vod_watch_captcha_logs`

第六步：改 `RouteServiceProvider.php`