# 课评保存自动化工具使用说明

## 工具概述

`evaluation_saver.py` 是一个自动化工具，用于帮助教师按照课评规范V1.0的要求保存学生课评，实现双轨保存机制。

**功能特性**：
- ✅ 自动创建标准目录结构
- ✅ 智能识别学生档案位置
- ✅ 支持补课学生跨班级双向记录
- ✅ 自动计算学期周数和课程主题
- ✅ 交互式输入模式（适合单次生成）
- ✅ 配置文件批量处理模式（适合批量保存）
- ✅ 完整的错误处理和提示

## 快速开始

### 前置条件

- Python 3.7 或更高版本
- 项目根目录为 `e:\classfeedback`（或你的实际位置）

### 基本用法

#### 1. 交互式模式（推荐新手使用）

在项目根目录下运行：

```bash
cd e:\classfeedback
python src\evaluation_saver.py
```

按照提示依次输入：

1. 班级名称（如：`AICODE03小Q周五1900`）
2. 授课日期（如：`2026-05-16`，默认是今天）
3. 课程代码（如：`AICODE03-011`）
4. 学生姓名（如：`谢善诺`）
5. 课评内容（可以粘贴多行文本，用空行结束）
6. 是否是补课学生（y/n）
7. 如果是补课，输入原班级名称

工具会自动处理保存，并告诉你保存的文件位置。

#### 2. 配置文件批量模式（推荐批量使用）

1. 复制配置示例文件：

```bash
copy src\config_example.json src\my_config.json
```

2. 编辑 `my_config.json`，填入你的班级信息和学生课评

3. 运行批量保存：

```bash
python src\evaluation_saver.py --config src\my_config.json
```

## 配置文件说明

配置文件是 JSON 格式，包含以下字段：

| 字段 | 类型 | 必填 | 说明 | 示例 |
|------|------|:----:|------|------|
| `class_name` | string | ✅ | 班级名称 | `"AICODE03小Q周五1900"` |
| `teaching_date` | string | ✅ | 授课日期（格式：YYYY-MM-DD） | `"2026-05-16"` |
| `course_code` | string | ✅ | 课程代码 | `"AICODE03-011"` |
| `students` | array | ✅ | 学生列表 | - |
| `students[].name` | string | ✅ | 学生姓名 | `"谢善诺"` |
| `students[].evaluation_text` | string | ✅ | 课评内容 | `"..."` |
| `students[].is_makeup` | boolean | ❌ | 是否是补课学生（默认false） | `false` |
| `students[].original_class` | string | ❌ | 原班级名称（仅补课学生需要） | `"AICODE03小Q周六1400"` |

### 配置示例

#### 示例1：单个正式学生

```json
{
    "class_name": "AICODE03小Q周五1900",
    "teaching_date": "2026-05-16",
    "course_code": "AICODE03-011",
    "students": [
        {
            "name": "谢善诺",
            "evaluation_text": "谢善诺本节课学习了\"超能力抽签机\"项目...",
            "is_makeup": false
        }
    ]
}
```

#### 示例2：混合正式学生和补课学生

```json
{
    "class_name": "AICODE03小Q周六1400",
    "teaching_date": "2026-05-17",
    "course_code": "AICODE03-011",
    "students": [
        {
            "name": "黄榆斐",
            "evaluation_text": "黄榆斐本节课学习了\"超能力抽签机\"项目...",
            "is_makeup": false
        },
        {
            "name": "谢善诺",
            "evaluation_text": "谢善诺本节课学习了\"超能力抽签机\"项目...",
            "is_makeup": true,
            "original_class": "AICODE03小Q周五1900"
        }
    ]
}
```

## 目录结构规范

工具会自动创建和管理以下目录结构（符合课评规范V1.0）：

```
.claude/memory/class/
├── {班级名称}/
│   ├── summaries/                          # 班级总结目录
│   │   └── YYYYMMDD_课程编号-课次_班级反馈.md
│   ├── {学生姓名}/                        # 正式学生目录
│   │   ├── feedback/                      # 个人课评目录
│   │   │   ├── YYYYMMDD_课程编号-课次.md
│   │   │   ├── YYYYMMDD_课程编号-课次(请假).md
│   │   │   └── YYYYMMDD_课程编号-课次(补课-去班级名).md
│   │   └── profile.md                     # 学生画像
│   └── 补课/                              # 补课学生专用目录
│       └── {学生姓名}/
│           └── feedback/
│               └── YYYYMMDD_课程编号.md
└── ...
```

## 文件命名规范

| 文件类型 | 命名格式 | 示例 |
|---------|---------|------|
| 正常课评 | `YYYYMMDD_课程编号-课次.md` | `20260516_AICODE03-011.md` |
| 请假记录 | `YYYYMMDD_课程编号-课次(请假).md` | `20260516_AICODE03-011(请假).md` |
| 补课追踪 | `YYYYMMDD_课程编号-课次(补课-去班级名).md` | `20260516_AICODE03-011(补课-去AICODE03小Q周六1400).md` |
| 补课班级课评 | `YYYYMMDD_课程编号.md`（放在 `补课/{学生}/feedback/`） | `20260516_AICODE03-011.md` |

## 补课学生处理规则

### 场景1：本班学生补课

**条件**：学生档案在当前班级 `{班级}/{学生}/` 存在

**处理**：
- 课评保存到：`{班级}/{学生}/feedback/YYYYMMDD_课程编号-课次.md`
- 不需要在 `补课/` 目录保存

### 场景2：跨班级补课（档案在其他班级）

**条件**：学生档案在其他班级存在

**处理**（双向记录）：
1. **补课班级侧**：保存到 `{补课班级}/补课/{学生}/feedback/YYYYMMDD_课程编号.md`
   - 文件开头会自动添加：`（补课，来自{原班级}）`
2. **原班级侧**：保存到 `{原班级}/{学生}/feedback/YYYYMMDD_课程编号-课次(补课-去{补课班级}).md`
   - 内容是简洁的补课追踪记录

### 场景3：完全无档案的新学生

**条件**：任何班级都没有学生档案

**处理**：
- 询问用户选择：
  1. 仅保存到当前班级的 `补课/` 目录
  2. 创建新档案（在当前班级创建 `profile.md`）

## 命令行参数

| 参数 | 说明 | 示例 |
|------|------|------|
| `--config <file>` | 使用配置文件批量处理 | `--config src\my_config.json` |
| `--help` | 显示帮助信息 | `--help` |

## 常见问题

### Q: 如何获取课评内容？

A: 你可以先使用 `/课评` 指令让 Claude 生成课评，然后把生成的课评内容复制到工具中。

### Q: 工具会覆盖已存在的课评文件吗？

A: 是的，如果文件已存在会被覆盖。建议在运行前备份重要文件。

### Q: 课程代码如何确定？

A: 课程代码必须与校宝排课系统中的 `class_name` 一致。常见格式：
- `CSP01-07`、`CSP02-05`、`CSP05-10`（C++信息学奥赛）
- `AICODE01-01`、`AICODE03-011`、`AICODE04-08`（AI编程）
- `DISC-007`、`SPIKE-011`（乐高课程，暂不纳入自动统计）

### Q: 学期周数是如何计算的？

A: 学期从2026年3月2日（第1周）开始，工具会根据授课日期自动计算：
- 2026-03-02 ~ 2026-03-08 → 第1周
- 2026-03-09 ~ 2026-03-15 → 第2周
- ...
- 2026-05-11 ~ 2026-05-17 → 第11周

### Q: 遇到错误怎么办？

A: 工具会显示友好的错误提示，常见错误：
- 班级目录不存在 → 工具会自动创建
- JSON配置格式错误 → 检查括号、逗号、引号是否匹配
- 日期格式错误 → 确保使用 YYYY-MM-DD 格式

## 实际工作流程建议

### 课后快速保存流程

1. 使用 `/课评` 指令让 Claude 批量生成课评
2. 复制生成的课评内容
3. 运行 `python src\evaluation_saver.py`
4. 按照提示输入班级信息和粘贴课评
5. 重复步骤3-4直到所有学生保存完成

### 批量处理流程（推荐）

1. 使用 `/课评` 指令让 Claude 批量生成课评
2. 把所有课评整理到一个 JSON 配置文件中
3. 运行 `python src\evaluation_saver.py --config src\my_config.json`
4. 检查保存结果

## 技术支持

如有问题，请检查：
1. Python 版本是否 >= 3.7
2. 当前工作目录是否在项目根目录
3. JSON 配置文件格式是否正确
4. 班级名称、课程代码是否符合规范
