# 教学日程查询 Skill 使用说明

## 功能概述
本技能**直接调用公司API获取实时教学排课数据**，支持查询指定日期或时间段的课程安排，自动生成功能完整的互动网页，帮助老师快速查询授课安排，查看学生名单和出勤情况，支持单天查询和任意时间段查询两种模式。

## 环境配置
### 1. 依赖安装
首次使用前需要安装技能依赖：
```bash
cd .claude/skills/教学日程查询
npm install
```

### 2. API配置
确保项目根目录下的 `.env` 文件包含正确的API配置：
```env
# 公司API地址
API_BASE_URL=https://api.qonnwolf.com/api/v1
# API认证令牌
AUTHORIZATION=Bearer your_token_here
# 默认查询的老师姓名
EMPLOYEE_NAME=橙子(程城)
```

## 快速开始
### 1. 调用技能
在Claude Code对话中输入，支持多种日期格式：
```
# 方式1：查询单天
/教学日程查询                # 查询当天日程
/教学日程查询 2026-04-28   # 标准格式
/教学日程查询 2026/04/28   # 斜杠格式
/教学日程查询 20260428     # 纯数字格式
/教学日程查询 4月28日      # 中文格式
/教学日程查询 04-28        # 短格式（默认当前年份）

# 方式2：查询时间段
/教学日程查询 2026-04-01 2026-04-30  # 查询4月整个月的日程
/教学日程查询 4月24日 4月26日        # 中文格式时间段
/教学日程查询 20260422 20260428      # 纯数字格式时间段
```

### 2. 查看结果
技能执行完成后会返回网页链接，点击链接即可打开互动网页查看详细信息。

## 网页功能说明
### 顶部功能区
- **日期范围显示**：显示当前查询的日期范围和总天数
- **搜索框**：输入日期、班级名称或学生姓名进行全局快速搜索
- **导出按钮**：点击导出整个时间段的课表为Excel文件
- **视图切换**：支持「按日期」和「按班级」两种视图模式一键切换

### 统计面板
- 展示查询范围内的总天数、总课程数、总学生人次
- 汇总出勤人次、缺勤人次，直观展示整体出勤情况

### 课表展示区
#### 按日期视图（默认）
- 按日期分组展示，每天的课程独立排列
- 日期头部粘性定位，滚动时始终可见
- 每个日期组显示当日的课程数量、学生人次和出勤统计
- 课程按时间顺序排列，每个课程以卡片形式展示
- 卡片显示：班级名称、授课时间、授课老师、学生人数、出勤统计
- 点击卡片展开查看该班级的详细学生名单

#### 按班级视图
- 按班级分组展示，同一个班级的所有课程集中排列
- 每个班级组显示课程次数和时间范围
- 方便查看同一个班级在整个时间段内的所有上课情况

### 学生名单
- 表格展示学生姓名和出勤状态
- 出勤状态标识：
  - ✅ 出勤：正常上课
  - ⏸ 请假：已请假
  - ❌ 缺勤：未上课
- 支持按出勤状态筛选学生

### 导出功能
导出的Excel文件包含以下信息：
- 课程日期
- 班级名称
- 授课时间
- 授课老师
- 教室
- 学生姓名
- 出勤状态
- 备注信息
* 时间段查询会导出所有日期的完整数据，自动按日期排序

## 目录结构
```
教学日程查询/
├── index.js          # 主程序文件，处理API调用和网页生成
├── package.json      # 依赖配置文件
├── skill.md          # Claude技能定义文件
├── template.html     # 网页模板文件
└── README.md         # 使用说明文档
```

## 输出目录
生成的文件保存在：
```
# 单天查询
.claude/output/teaching-schedule/2026-04-28/
├── schedule.html    # 互动网页
└── schedule.json    # 原始API数据

# 时间段查询
.claude/output/teaching-schedule/2026-04-01_2026-04-30/
├── schedule.html    # 互动网页
└── schedule.json    # 原始API数据（包含多天的完整数据）
```

## 常见问题
### Q: API调用失败提示认证失败？
A: 请检查项目根目录下 `.env` 文件中的 `AUTHORIZATION` 配置是否正确，令牌是否过期。

### Q: API调用失败提示网络错误？
A: 请检查网络连接是否正常，是否能够访问公司API地址，或者稍后重试。如果问题持续存在，请联系技术支持。

### Q: 为什么没有数据？
A: 可能是查询的日期没有排课，或者API返回数据为空。可以尝试查询其他日期，或者检查 `EMPLOYEE_NAME` 配置是否正确。

### Q: 导出的Excel文件打不开？
A: 请确保使用支持.xlsx格式的办公软件打开，如Microsoft Excel、WPS等。

### Q: 可以查询其他老师的课表吗？
A: 可以修改 `.env` 文件中的 `EMPLOYEE_NAME` 配置为要查询的老师姓名，支持模糊匹配。

## 更新日志
### v1.1.0 (2026-04-28)
- ✨ 新增时间段查询功能，支持查询任意起止日期范围内的所有日程
- ✨ 新增双视图展示模式：按日期视图、按班级视图，一键切换
- ✨ 升级统计面板，展示总天数、总课程数、总学生人次等汇总信息
- ✨ 搜索功能升级，支持按日期、班级、学生姓名全局搜索
- ✨ 导出功能升级，支持导出整个时间段的完整数据
- ✨ 优化界面设计，日期分组头部支持粘性定位，滚动浏览更方便
- ♻️ 重构数据处理逻辑，支持多天数据的合并和展示

### v1.0.0 (2026-04-28)
- 初始版本发布
- 支持基础的单天日程查询功能
- 支持搜索、筛选、导出Excel功能
- 响应式界面设计