---
name: phone-chapter-query
description: |
  通过手机号文件查询用户课时完成记录。从 Excel/CSV 文件中提取手机号，匹配瓦拉账号，
  查询指定课时的首次完成记录（含课程耗时），输出带手机号明文的 xlsx 报表，
  并自动发送到指定飞书群。未匹配到账号的手机号追加在表尾。

  **触发场景**:
  (1) 用户发送包含手机号的 Excel/CSV 文件，要求查询课时完成记录
  (2) 用户提到"手机号"+"课时"/"学习记录"/"完成记录"的组合
  (3) 需要批量通过手机号关联账号并查询学习数据
---

# 手机号课时完成记录查询

## 完整流程

1. 用户发送包含手机号的 Excel(.xlsx) 或 CSV(.csv) 文件
2. 运行脚本：提取手机号 → 脱敏匹配账号 → 查询课时记录 → 生成 xlsx
3. 将生成的 xlsx 文件发送到飞书群 `oc_616882799f1910b85a248b74f44c3be5`
4. 同时回复用户确认结果

## 步骤1: 运行查询脚本

```bash
python3 skills/phone-chapter-query/scripts/phone_chapter_query.py <input_file> [--output <path>]
```

- `input_file`: 包含手机号的文件路径（支持 .xlsx 和 .csv）
- `--output`: 可选，指定输出路径，默认 `output/phone_chapter_query_时间戳.xlsx`

## 步骤2: 发送结果到飞书群

脚本执行完成后，使用 `lark-send-message-as-bot` skill 将生成的 xlsx 文件发送到目标群：

- **目标群 chat_id**: `oc_616882799f1910b85a248b74f44c3be5`
- **发送方式**: Bot 身份发送文件消息

## 输出字段

| 字段 | 说明 |
|------|------|
| 账号ID | bi_vala_app_account.id |
| 手机号 | 明文手机号（来自输入文件） |
| 角色ID | bi_vala_app_character.id |
| 注册日期 | 角色创建时间 |
| 最近登录时间 | user_detail_info.latest_active_time |
| 课程名称 | 等级-季-单元-课时 格式 |
| 课程完成时间 | 首次完成日期 |
| 课程耗时 | 分:秒 格式 |

未匹配到账号的手机号追加在表尾，仅手机号列有值。

## 匹配规则

- 自动识别文件中所有 `1` 开头的 11 位数字作为手机号
- 使用 XXTEA 加密后与 `bi_vala_app_account.tel_encrypt` 字段精确匹配
- 仅匹配 `status = 1` 且 `deleted_at IS NULL` 的账号
- 加密规则：XXTEA(key="K1pNOZ5O5+ZqTPSHA2kzPdoNOMOGcv6g") → Base64 → 替换 +-/= 为 -_.

## 可配置项

脚本顶部的 `CHAPTER_IDS` 变量控制查询的课时范围，按需修改。