---
name: refund-user-learning-analysis
description: |
  退费用户U0学习数据分析工具。统计指定时间段内购课并退费的用户在U0阶段的学习表现，
  包括课程巩固(Review)正确率与用时、单元强化(Summary)参与与完成、单元挑战(Challenge)各维度成绩。
  支持自动剔除脏数据、生成Excel多Sheet报表。

  **触发场景**: 
  (1) 统计退费用户的学习数据/学习情况
  (2) 分析退费用户在U0阶段的巩固/强化/挑战表现
  (3) 退费用户有多少完成了U0课程
  (4) 退费用户的学习完成率、正确率统计
  (5) 用户提到"退费用户"+"学习数据/巩固/强化/挑战"的组合
---

# 退费用户U0学习数据分析

## 分析流程

### Step 1: 确认参数

向用户确认:
- **时间范围**: 订单付款的起止日期 (默认当月)
- **是否剔除仍有有效订单的用户**: 默认剔除
- **巩固用时异常阈值**: 默认 60 分钟，超过视为脏数据

### Step 2: 执行数据查询

运行查询脚本，传入参数:

```bash
python3 scripts/query_refund_learning.py \
  --start <START_DATE> --end <END_DATE> \
  --output /tmp/refund_learning_report.json \
  --pure <PURE> --outlier <OUTLIER>
```

> **参数说明**: `<START_DATE>` 和 `<END_DATE>` 替换为 Step 1 中用户确认的起止日期（格式 YYYY-MM-DD）；`<PURE>` 替换为是否剔除仍有有效订单的用户（true/false）；`<OUTLIER>` 替换为巩固用时异常阈值（分钟）。

脚本自动完成:
1. 筛选时间段内购课且退费(order_status=4 + refund status=3)的用户
2. 可选剔除仍持有有效订单(order_status=3)的用户
3. 关联角色表找到user_id，查8张分表判断U0五节课完成情况
4. 统计巩固(Review)用时和正确率(从question_list JSON解析isRight)
5. 统计强化(Summary)进入和各知识模块完成情况
6. 统计挑战(Challenge)四维度参与和Perfect/Good/Oops分布
7. 自动识别并剔除巩固用时异常数据

### Step 3: 生成 Excel 报表

```bash
python3 scripts/generate_excel.py \
  --input /tmp/refund_learning_report.json \
  --output /tmp/退费用户U0学习数据统计.xlsx
```

生成5个Sheet: 总览、课程巩固、单元强化、单元挑战、剔除的异常数据。

### Step 4: 发送文件

使用 `feishu-send-file` skill 将 Excel 文件发送给用户。

## 数据口径

- **退费用户**: `bi_vala_order.order_status = 4` 且 `bi_refund_order.status = 3`，通过 `out_trade_no` 关联
- **纯退费用户**: 上述用户中无任何 `order_status = 3` 的有效订单
- **完成U0**: 用户至少完成 L1-U0 或 L2-U0 的全部5节课 (`play_status = 1`)
- **巩固正确率**: `question_list` JSON 中 `isRight=true` 的数量 / 总题数 × 100
- **强化完成**: 做完该单元所有知识模块 (L1=3个, L2=4个)
- **挑战成绩**: 首次各维度的 `score_text` (Perfect/Good/Oops)
- **测试账号**: 通过 `bi_vala_app_account.status = 1` 过滤

## 扩展到其他单元

修改脚本中的 chapter_id 和 story_id 映射即可统计其他单元。
映射关系详见 `references/data-model.md`。

查询 `bi_level_unit_lesson` 表获取任意单元的 chapter_id:
```sql
SELECT * FROM bi_level_unit_lesson WHERE course_unit = 'U01' ORDER BY course_level;
```

查询 story_id:
```sql
SELECT DISTINCT story_id, level FROM bi_user_unit_review_question_result
WHERE chapter_id IN (<target_chapter_ids>) LIMIT 5;
```
