---
name: export-user-data
description: |
  用户数据导出技能，支持两种模式：
  1. 按用户维度：导出一个或多个角色的全量行课数据（音频、互动组件、课程巩固、单元挑战、单元总结、汇总统计）
  2. 按组件维度：导出指定组件的所有用户学习记录（用户ID、音频、判定结果等），按时间倒序
  触发词：导出角色/行课数据、导出用户数据、导出组件记录、export user data。
---

# 导出用户数据

## 前置条件

- wrapper 脚本已配置数据库凭证
- 依赖：`python3`, `pymysql`, `psycopg2`, `pandas`, `openpyxl`

---

## 模式一：按用户维度导出（全量行课数据）

### 执行方式

```bash
cd /root/.openclaw/workspace-xiaoban
./scripts/export_user_data.sh <参数>
```

### 参数

| 参数 | 说明 | 示例 |
|------|------|------|
| `--user-id <id>` | 单个角色ID | `--user-id 33123` |
| `--user-ids <id1,id2>` | 多个角色ID，逗号分隔 | `--user-ids 33123,33124` |
| `--account-ids <id1,id2>` | 多个账户ID，逗号分隔 | `--account-ids 2148,2149` |
| `--output-dir <dir>` | 输出目录（默认 `output/`） | `--output-dir /tmp/` |

三种模式互斥，只能传一种 ID 参数。

### 输出

- 默认输出到 `output/` 目录
- 单角色：`角色id_{ID}_导出时间_{YYYYMMDD}.xlsx`
- 账户模式：`账户id_{AID}_角色id_{UID}_导出时间_{YYYYMMDD}.xlsx`

### Excel 包含的 Sheet

1. 全部音频数据（ES `user-audio` 索引）
2. 互动组件学习记录（PG 8张分表 + MySQL 组件配置）
3. 课程巩固记录（PG `user_unit_review_question_result`）
4. 单元挑战记录（PG `user_unit_challenge_question_result`）
5. 单元总结记录（PG）
6. 汇总统计（组件类型统计 / 知识点统计 / 单元时长统计）

---

## 模式二：按组件维度导出（组件学习记录）

### 执行方式

```bash
cd /root/.openclaw/workspace-xiaoban
./scripts/export_component_records.sh --c-type <组件类型> --c-id <组件ID> [可选参数]
```

### 参数

| 参数 | 说明 | 示例 |
|------|------|------|
| `--c-type <type>` | **必填** 组件类型 | `mid_sentence_dialogue` |
| `--c-id <id>` | **必填** 组件ID | `1112315` |
| `--start-date <YYYYMMDD>` | 可选，起始日期 | `--start-date 20260101` |
| `--end-date <YYYYMMDD>` | 可选，截止日期 | `--end-date 20260604` |
| `--output-dir <dir>` | 输出目录（默认 `output/`） | `--output-dir /tmp/` |

### 支持的组件类型（c_type）

> 覆盖 MySQL `middle_interaction_component` 和 `core_interaction_component` 中所有实际 c_type。

**中互动组件（mid_*）：**

| c_type | 组件名称 |
|--------|---------|
| `mid_sentence_dialogue` | 对话互动 |
| `mid_dialog_repeat` | 对话跟读 |
| `mid_dialog_fillin` | 对话挖空 |
| `mid_image_choose` | 图片单选 |
| `mid_dialog_sentence` | 对话组句 |
| `mid_grammar_cloze` | 挖空互动 |
| `mid_vocab_image` | 图片互动 |
| `mid_vocab_item` | 物品互动 |
| `mid_dialog_choose` | 对话选择 |
| `mid_sentence_material` | 材料互动 |
| `mid_dialog_select` | 对话选读 |
| `mid_grammar_sentence` | 组句互动 |
| `mid_image_multiple` | 图片多选 |
| `mid_dialog_express` | 对话表达 |
| `mid_sentence_voice` | 语音互动 |
| `mid_vocab_fillBlank` | 填词互动 |
| `mid_vocab_instruction` | 指令互动 |
| `mid_message_trace` | 消息描红 |
| `mid_sentence_makeSentence` | 造句互动 |
| `mid_message_spell` | 信息拼词 |
| `mid_pron_pron` | 发音互动 |
| `mid_image_sequence` | 图片有序 |
| `mid_image_drag` | 图片拖拽 |
| `mid_message_combine` | 信息组句 |

**核心互动组件（core_*）：**

| c_type | 组件名称 |
|--------|---------|
| `core_listening_choose` | 听力选择 |
| `core_listening_drag` | 听力拖拽 |
| `core_listening_order` | 听力排序 |
| `core_reading_imageDrag` | 阅读图片拖拽 |
| `core_reading_order` | 阅读排序 |
| `core_speaking_explore` | 口语探讨 |
| `core_speaking_image` | 看图说话 |
| `core_speaking_inquiry` | 口语妙问 |
| `core_speaking_monologue` | 口语独白 |
| `core_speaking_reply` | 口语快答 |
| `core_writing_imgMakeSentence` | 写作看图组句 |
| `core_writing_imgMakeWord` | 写作看图组词 |
| `core_writing_imgWrite` | 写作看图撰写 |
| `core_writing_questionMakeSentence` | 写作问题组句 |
| `core_writing_questionWrite` | 写作问题撰写 |

### 输出

- 默认输出到 `output/` 目录
- 文件名：`组件_{组件名称}_{c_id}_导出时间_{YYYYMMDD}.xlsx`
- 示例：`组件_对话互动-表达_1112315_导出时间_20260604.xlsx`

### Excel 包含的字段

| 字段 | 说明 | 来源 |
|------|------|------|
| `user_id` | 用户角色ID | PG |
| `session_id` | 会话ID | PG |
| `component_unique_code` | 组件唯一标识 | PG |
| `c_type` | 组件类型编码 | PG |
| `c_id` | 组件ID | PG |
| `组件名称` | 中文组件名称（对话互动自动追加 -表达/-朗读） | MySQL映射 |
| `组件标题` | 组件配置标题 | MySQL |
| `mode` | 模式（表达/朗读，仅对话互动有值） | MySQL component_config |
| `参考文本` | 组件配置中的参考文本 | MySQL component_config |
| `play_result` | 判定结果（Perfect/Good/Pass/Oops/Failed） | PG |
| `发音评分` | 发音评分 | PG user_behavior_info |
| `音频URL` | 用户录音文件地址 | PG user_behavior_info |
| `朗读内容` | 用户实际朗读内容 | PG user_behavior_info |
| `user_behavior_info` | 原始用户行为数据 JSON | PG |
| `updated_at` | 更新时间（倒序排列） | PG |

### 数据来源

- **PG** `user_component_play_record_0~7`（8张分表）：主数据源，按 c_type + c_id 过滤
- **MySQL** `middle_interaction_component` / `core_interaction_component`：组件配置（标题、mode、参考文本）

---

## 快速查组件类型

如果只知道 `c_id` 不知道 `c_type`，先查 MySQL：

```bash
cd /root/.openclaw/workspace-xiaoban
source scripts/export_component_records.sh --help  # 仅加载环境变量
python3 -c "
import pymysql, os
conn = pymysql.connect(
    host=os.getenv('MYSQL_HOST'), user=os.getenv('MYSQL_USERNAME'),
    password=os.getenv('MYSQL_PASSWORD'), database='vala_test',
    port=int(os.getenv('MYSQL_PORT',3306)), charset='utf8mb4')
for t in ['middle_interaction_component','core_interaction_component']:
    cur = conn.cursor()
    cur.execute(f'SELECT c_id,c_type,title FROM {t} WHERE c_id=%s', ('<c_id>',))
    for r in cur.fetchall():
        print(f'{t}: c_id={r[0]} c_type={r[1]} title={r[2]}')
    cur.close()
conn.close()
"
```

## 实际用例

### 导出"看图说话"组件 1000516 的所有学习记录

```bash
cd /root/.openclaw/workspace-xiaoban
./scripts/export_component_records.sh --c-type core_speaking_image --c-id 1000516
```

输出：`output/组件_看图说话_1000516_导出时间_YYYYMMDD.xlsx`

包含字段：user_id、session_id、play_result（判定结果）、音频URL、朗读内容（ASR文本识别）、发音评分、user_behavior_info（完整行为数据）等，按 updated_at 倒序排列。

## 完成后

如果是从飞书对话触发的导出，导出完成后通过 `lark-send-message-as-bot` 技能将文件发送给请求用户。