# studycourse-analysis — 角色上课情况分析

## 功能

分析角色上课情况，从四个维度输出详细报告：

1. **基础信息**：角色姓名、年龄、账号、手机号、注册时间、购买渠道、设备信息、首/末次完课
2. **完课耗时分析**：平均/中位数完成时间、异常耗时（<10 分钟或>20 分钟）、耗时趋势
3. **中互动正确率分析**：Perfect/Good/Oops 占比、优良率、趋势变化
4. **知识巩固分析**：巩固练习完成率、得分分布

Markdown 报告末尾提示用户可选择生成 HTML 文件，确认后生成。

## 触发词

`分析角色[ID]的上课情况`

如：`分析角色32009的上课情况`

## 数据源

| 类型 | 库 | 表 |
|------|-----|-----|
| MySQL vala_user | `vala_app_character` | 角色基本信息、purchase_season_package |
| MySQL vala_user | `vala_app_account` | 账号信息、download_channel、key_from |
| MySQL vala | `vala_game_chapter` + `vala_game_season_package` | 章节 Level/Unit/Lesson 映射 |
| PostgreSQL vala | `user_course_detail` | 课程激活时间、到期时间、course_level |
| PostgreSQL vala | `user_login_app_info` | 设备信息（device_name/model/type/os） |
| PostgreSQL vala | `user_chapter_play_record_0~7` | 完课记录（play_status=1） |
| PostgreSQL vala | `user_component_play_record_0~7` | 中互动记录（play_result: Perfect/Good/Oops） |
| PostgreSQL vala | `user_chapter_settlement_data_0~7` | 结算数据（含 practiceSkillPoint/practiceCount） |

## 使用方式

```bash
cd /root/.openclaw/workspace-xiaoban

# 设置环境变量（secrets.md）
source secrets.md

# 生成 Markdown 报告
python3 skills/studycourse-analysis/scripts/studycourse_analysis.py <role_id>

# 生成 HTML 报告
python3 skills/studycourse-analysis/scripts/studycourse_analysis.py <role_id> --format html -o output/studycourse_<role_id>.html
```

## 交互流程

1. 用户发送 `分析角色[ID]的上课情况`
2. 运行 Markdown 分析报告，显示四步分析结果
3. 报告末尾自动提示 `💡 是否需要将以上详细分析报告生成一份 HTML 文件？回复「是」或「需要」即可。`
4. 用户回复「是」或「需要」后，生成 HTML 文件并发送

## HTML 结构

5 个 card 布局 section：

1. **基础信息** — 角色ID、姓名、年龄、账号ID、手机号后4位、注册时间、课程激活/到期、购买渠道、设备、首/末次完课
2. **完课记录明细** — 表格，每行含 Level/Unit/Lesson、开始/完课时间、耗时、中互动汇总、巩固完成/题数/正确率
3. **上课时间分析** — 耗时统计分析
4. **中互动正确率分析** — 正确率趋势
5. **知识巩固正确率分析** — 得分分布

## 关键逻辑

- **章节映射**：复用 studytime-analysis 的 fetch_chapter_info_map()，按 (level, season_of_quarter) 分组计算全局 unit_index
- **巩固判断**：`settlement_data.practiceSkillPoint > 0` 视为已完成巩固（`isPractice` 字段不可靠）
- **中互动**：`user_component_play_record.play_result` 统计 Perfect/Good/Oops/Pass/Failed
- **异常耗时**：<10 分钟为过快，>20 分钟为过慢
- **趋势分析**：将数据按时间分前后两半，对比均值变化

## 凭证

数据库凭证从环境变量注入，不硬编码。配置项与 studytime-analysis 共用：
- `PG_DB_HOST/PORT/USER/PASSWORD/DATABASE`
- `MYSQL_HOST_online/PORT_online/USERNAME_online/PASSWORD_online`

## 版本

v1.0.0 — 2026-05-24 初始版本