146 lines
5.4 KiB
Markdown
146 lines
5.4 KiB
Markdown
# 教学日程查询 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功能
|
||
- 响应式界面设计
|