# 2026-05-24 工作日志

## 新建技能: studytime-analysis

[刘庆逊提出] 创建学习时间分析技能，分析角色完课记录的规律。

### 技能结构
- `skills/studytime-analysis/SKILL.md` — 技能定义
- `skills/studytime-analysis/scripts/studytime_analysis.py` — Python 分析脚本

### 分析维度
1. **一周时间分布**（排除寒暑假1-2月、7-8月）：周一~周日各天完课数、时段分布（上午/中午/下午/晚上）、周末是否上课
2. **跨周学习趋势**（包含寒暑假全部数据）：总周数、周均完课数、连续性、中断周检测、前后半段趋势对比、突增/骤降检测
3. **完课记录明细表**（全部数据）：日期/时间/星期/时段/级别/课程ID

### 数据源
- PostgreSQL Online（vala 库）
- 核心表：`user_chapter_play_record_0~7`（8张分表，无 `bi_` 前缀）
- 筛选：`play_status = 1`
- 注意：表在 PostgreSQL 而非 MySQL，表名无 `bi_` 前缀

### 寒暑假规则
- 一周分布分析时排除 1-2 月（寒假）和 7-8 月（暑假）—— 因为寒暑假作息与平时差异大，混在一起会干扰时段分析
- 跨周趋势和明细表包含全部数据（含寒暑假）
- 报告中区分标注数据范围

### 触发方式
用户说「学习时间分析 [角色ID]」即可触发

### 已测试角色
- 2343、2344：无完课记录（play_status=2，未完成）
- 2840：276条记录，秋季集中型用户
- 25976：265条，246条在W16周一天完成（A2批量），疑似系统批量标记
- 2895：188条，长期稳定学习型用户，36周几乎不间断，非寒暑假晚上为主，寒暑假上午为主

### 技术要点
- psycopg2 的 `%(param_name)s` 命名参数必须正确匹配，UNION ALL 多个子查询需要不同参数名
- PostgreSQL 返回的 `updated_at` 是 tz-aware datetime
- `datetime.fromisocalendar(year, week, 1)` 获取某周周一的日期

### 同步
- 已推送到 SkillHub（`studytime-analysis.xiaoban`）
- 已 commit 到 Git 远程仓库
- 已通知 Cris（李若松）

### 增强: 报告开头加入角色基本信息 (2026-05-24)

[刘庆逊提出] 在 studytime-analysis 输出中加入角色基本信息，包括：
- 角色ID、账号ID、角色名字、性别、年龄、账号手机号后4位

**数据源（新增）**：
- MySQL Online `vala_user` 库
- `vala_app_character` 表：id, account_id, nickname, gender(0=女/1=男), birthday(varchar "YYYY-MM-DD")
- `vala_app_account` 表：id, tel(已脱敏如 186****1625)
- 手机号已脱敏，直接取后4位；年龄从 birthday 计算

**修改文件**：
- `skills/studytime-analysis/scripts/studytime_analysis.py`：新增 MySQL 连接函数 `get_mysql_connection()` 和 `fetch_role_info(role_id)`，更新 `format_report()` 输出基本角色信息
- 已验证 2895 正常运行输出
- 已同步 SkillHub + Git

### Unit 显示修复: 季度名称 → 全局单元编号 (2026-05-24)

[刘庆逊提出] HTML 报告中 Unit 列显示错误——显示的是季度名称（如"小镇时光""钢铁之心"）而非单元数字（0-48）。

**根因分析**：
- `vala_game_chapter`（MySQL）无 `unit_index` 字段
- `big_map_chapter`（PostgreSQL）有 `unit_index` 字段，但仅包含 A1 数据，且与 `vala_game_chapter` 无直接关联键
- 两者 ID 空间不重叠（big_map: ~1720-2070，game_chapter: ~55-399），UUID 也不匹配

**映射方案**：
- 每个 season_package 内，`lesson_type=1` 的章节按 `id` 排序，每 5 个连续章节组成一个单元
- Season 0（序章/L1-U0）：所有章节属于 Unit 0
- Season 1-4：每个 season 有 12 个单元（60 个 lesson 章节）
- 全局 unit_index = base_offset(season_of_quarter) + unit_within_season
  - base_offset: 0→0, 1→1, 2→13, 3→25, 4→37

**关键 Bug**：初版按 `season_of_quarter` 分组时 A1 和 A2 混在一起，因为相同季度值合并了。修复：改为按 `(level, season_of_quarter)` 分组。

**验证结果**：
- A1: Unit 0-48（49 个单元），与 big_map_chapter 的 unit_index 范围一致
- A2: Unit 0-49（50 个单元，比 A1 多 1 个）

**已修改文件**：
- `skills/studytime-analysis/scripts/studytime_analysis.py` — 重写 `fetch_chapter_info_map()`，新增全局 unit_index 计算；HTML 模板更新为 Level/Unit/Lesson 三列
- 已为角色 32009（zyl）重新生成 HTML 并发送
- 已同步 Git + SkillHub