> ⚠️ **本文件已归档**：内容已合并至核心规则文件，此处仅作历史备份。请勿直接引用本文件，请使用 `.claude/rules/` 下的核心规则。

# 批量课评生成规则 v2.0（优化版）

> ⚠️ **注意**：本文档为 v2.0 旧版本归档文件，描述的是"生成-确认-保存"两阶段流程。
> 当前系统已升级为 v3.1 "生成即双轨保存"模式，详见 [20-workflow.md](../20-workflow.md) 第7节和第10节。
> 
> **关键差异**：
> - v2.0：先生成 → 等待教师确认 → 再双轨保存
> - v3.1：生成后立即自动双轨保存，无需确认

---

## 🚀 批量生成流程（v2.0 旧流程 - 仅供参考）

```
输入表格 → AI并行解析每个学生 → 预加载课程/档案 → 
并行生成多份课评 → 质量检查 → 【自动双轨保存】→ 完成
                                          ↓
                                 同步更新出勤统计
```

> **注**：以上为 v3.1 更新后的流程。原 v2.0 流程包含"教师确认"步骤，现已简化为"生成即保存"。

> **核心优势**：8人课评从15-20分钟缩短至**3-5分钟**（效率提升75%）

---

## 📝 批量输入格式

### 标准列表式（推荐）

```
课程：DISC-007
班级：发现世界-周四19点
日期：4月16日

1. 乔乔：gj5→zd3→zt ↑++
2. 昊昊：慢热→zd3→反复调 →
3. 张小明[体验]：搭了3层，开心
4. 李小红[补课]：专注完成，稳定
5. 小强：频换玩法 wb↓--
```

### 简化表格式

```
课程：DISC-007  班级：发现世界-周四19点

学生      核心表现              情绪   对比
─────────────────────────────────────────
乔乔      gj5→zd3→zt            ↑      ++
昊昊      慢热→zd3→反复调        →      渐入佳境
小明[体验] 搭3层参与             ↑      积极
小红[补课] 专注完成              →      稳定
```

### 纯速记式（高效用户）

```
DISC-007 发现世界-周四19点

乔乔 gj5→zd3→zt ↑++
昊昊 慢热→zd3→反复调 →
小明[体验] zd3 ↑
```

---

## ⚡ 批量输出格式（优化）

### 统一展示界面

```
━━━━━━━━━━━━━━━━━━━━━━━
📊 批量生成完成（5份）｜发现世界-周四19点｜DISC-007
━━━━━━━━━━━━━━━━━━━━━━━

✅ 乔乔      198字  正常
✅ 昊昊      205字  正常
⚠️  小强      165字  偏短
✅ 张小明[体验] 192字  体验学生
✅ 李小红[补课] 201字  补课学生

【批量操作】
[全部发送] [逐个查看] [标记修改] [取消]
━━━━━━━━━━━━━━━━━━━━━━━
```

**自动通过条件**（同时满足）：
- ✅ 学生有完整档案
- ✅ 字数在弹性范围内
- ✅ 无敏感词/异常表述
- ✅ 情绪描述合理

**需人工确认条件**（任一满足）：
- ⚠️ 体验/补课学生（无档案）
- ⚠️ 字数偏差>20字
- ⚠️ 检测到负面情绪词
- ⚠️ 与上周表现差异过大
- ⚠️ 内容重复度高

---

## 🔍 自动质量检查

### 检查维度

| 检查项 | 描述 |
|--------|------|
| 字数检查 | 是否符合弹性范围（180-350字） |
| 重复检查 | 开头句式是否差异化 |
| 差异化检查 | 各课评侧重点是否不同 |
| 待关注项 | 特殊情绪/行为标记 |

### 差异化策略

**1. 开头差异化**

| 学生类型 | 开头句式示例 |
|----------|-------------|
| 谨慎型 | "今天[学生]终于主动尝试了..." |
| 活跃型 | "[学生]今天一如既往充满活力..." |
| 进步型 | "和上周相比，[学生]有了明显进步..." |
| 补课型 | "这节课[学生]融入得很好..." |
| 体验型 | "欢迎[学生]第一次来到..." |

**2. 侧重点差异化**

同一节课，不同学生类型侧重不同：
- **谨慎型** → 参与度和勇气
- **熟练型** → 创意和拓展
- **困难型** → 过程价值

**3. 建议差异化**

根据学生能力推荐不同课后活动：
- **参与少**：在家可以用纸筒做简单旋转玩具
- **能力强**：可以尝试用不同材料做对比实验
- **坚持短**：可以从5分钟小目标开始练习专注

---

## 📦 存储流程（优化后）

### 存储路径

| 位置 | 路径 | 说明 |
|------|------|------|
| 班级周汇总 | `memory/class-evaluation-summary/第X周/{班级}.md` | 全班汇总，含确认状态 |
| 个人档案 | `memory/student/{班级}/{学生}/历史课评记录.md` | 个人完整轨迹 |
| 跨班级补课 | `memory/student/{原班级}/{学生}/历史课评记录.md` | 档案在原班级，来当前班级补课 |

**跨班级补课存储示例**：
- 林瀚丞档案在"发现世界-周四19点"，来"发现世界-周六09点"补课
- 课评保存到：`class-evaluation-summary/第X周/发现世界-周六09点.md`
- 课评追加到：`student/发现世界-周四19点/林瀚丞/历史课评记录.md`
- 个人档案标注：`【跨班级补课】本节课程在周六09点班完成`

> 完整存储规则和学生类型处理详见 [CLAUDE.md](../../CLAUDE.md) 和 [33-first-class-rules.md](33-first-class-rules.md)

### 并发控制与文件名规范

#### 文件名规范化
```python
# 文件名非法字符处理
invalid_chars = ['/', '\\', ':', '*', '?', '"', '<', '>', '|']
replacement = '_'

def sanitize_filename(filename):
    for char in invalid_chars:
        filename = filename.replace(char, replacement)
    return filename.strip()
```

#### 并发写入策略
| 场景 | 策略 | 说明 |
|------|------|------|
| 同时写入同一班级汇总 | 文件锁 + 合并写入 | 后写入者追加到文件，不覆盖 |
| 同时写入同一学生档案 | 队列化处理 | 串行写入，避免冲突 |
| 班级汇总 + 个人档案同时写入 | 独立事务 | 互不影响，各自重试 |

#### 写入保障
- **原子写入**：先写入临时文件（`.md.tmp`），成功后重命名
- **备份机制**：写入前自动备份上次版本（`.md.bak`）
- **冲突检测**：检测到修改时间变化时自动合并
- **教师协作提示**：当检测到其他教师正在编辑时显示「教师A正在编辑，请稍后」

### 存储失败补偿机制

**场景**：班级汇总保存成功，但个人档案保存失败（磁盘满、权限问题、并发冲突等）

**处理策略**：

| 失败类型 | 处理方式 | 教师感知 |
|----------|---------|---------|
| 磁盘/IO错误 | 加入补偿队列，5分钟后自动重试 | 静默处理，下次生成时提示 |
| 并发冲突 | 自动合并（追加模式），不重试 | 无感知 |
| 权限不足 | 加入补偿队列，提醒教师检查权限 | 显示警告 |
| 路径不存在 | 自动创建路径后重试 | 无感知 |

**补偿队列检查时机**：
1. 每次生成课评前（自动检查并补存）
2. 教师输入`补存`或`同步`指令时
3. 每日定时检查（如每天18:00）

**批量补存界面**：
```
━━━━━━━━━━━━━━━━━━━━━━━━━
📋 待补存课评（2条）

1. 乔乔 - 第7周发现世界
   失败原因：磁盘临时满
   [立即补存] [忽略]

2. 昊昊 - 第7周发现世界  
   失败原因：权限被拒绝
   [立即补存] [忽略]

[全部补存] [稍后提醒]
━━━━━━━━━━━━━━━━━━━━━━━━━
```

---

## 🏷️ 特殊情况批量处理

### 标记速查

| 标记 | 处理逻辑 | 保存位置 |
|------|---------|---------|
| `[补课]` | 检查档案：①当前班级存在→双轨保存 ②其他班级存在→**自动跨班级双轨保存** ③不存在→询问是否建档 | 班级汇总+个人档案（含跨班级自动保存）|
| `[体验]` | 仅班级汇总，不询问 | 仅班级汇总（标记体验） |
| `[缺课]` | 记录缺席，不生成课评 | 班级汇总（标记缺课） |
| `[new]` | 创建新档案，双轨保存 | 班级汇总+个人档案 |

**[补课]处理详细逻辑**（自动版）：
1. 检查 `memory/student/{当前班级}/{学生名}/` 是否存在
2. 如存在 → 该学生为本班补课 → 双轨保存（班级汇总+个人档案）
3. 如不存在 → 搜索 `memory/student/` 下其他班级是否存在该学生档案
   - 如存在（跨班级补课）→ **自动双轨保存（跨班级模式）**
     - ✅ 自动保存到补课班级周汇总
     - ✅ 自动追加到原班级个人档案（标注补课班级信息）
     - **无需询问，自动完成**
   - 如不存在 → 询问处理方式
     - [1] 仅保存到班级汇总
     - [2] 创建新档案

### 批量处理示例

```
输入：
DISC-007 发现世界-周四19点

1. 乔乔：gj5→zd3→zt ↑++
2. 昊昊：慢热→zd3→反复调 →
3. 张小明[体验]：搭了3层，开心
4. 李小红[补课]：专注完成，稳定
5. 王大力[缺课]

AI处理：
✓ 乔乔、昊昊：正常生成，双轨保存（正式学生，档案在当前班级）
⚠ 张小明[体验]：生成标记为"体验学生"，仅班级汇总
⚠ 李小红[补课]：检查档案 → 在当前班级存在 → 双轨保存（本班补课）
✓ 林瀚丞[补课]：检查档案 → 在周四19点班存在 → **自动跨班级双轨保存**
  → 保存到周六09点班级汇总 + 追加到周四19点个人档案
✓ 王大力[缺课]：记录"王大力：缺课"，不生成课评
```

---

## 💡 效率优化技巧

### 1. 上下文复用

```
/课评 班级：发现世界-周四19点  # 首次指定

# 后续直接输入学生，无需重复班级
乔乔：搭3层
昊昊：慢热
```

### 2. 语音批量录入

语音输入多学生表现，AI自动分段生成课评。

---

## 📊 批量生成检查清单

### 生成前检查
- [ ] 班级信息正确（或已在上下文中）
- [ ] 学生姓名无遗漏
- [ ] 标记使用正确（[补课]/[体验]/[缺课]）

### 生成后检查
- [ ] 全部学生课评已生成
- [ ] 字数符合弹性范围
- [ ] 开头句式差异化
- [ ] 建议内容个性化
- [ ] 特殊学生已标记

### 发送前检查
- [ ] 内容准确无误
- [ ] 称呼正确（小名/去姓）
- [ ] 补课/体验学生处理完毕

---

## 🎯 使用建议

### 推荐工作流程

```
Step 1: 指定班级（一次）
        /课评 班级：发现世界-周四19点
        
Step 2: 批量输入（使用速记）
        乔乔：gj5→zd3→zt ↑++
        昊昊：慢热→zd3→反复调 →
        小明[体验]：zd3 ↑
        
Step 3: AI批量生成（自动质量检查）

Step 4: 查看质量报告，一键确认

Step 5: 自动保存并发送
```

### 不同场景推荐

| 场景 | 推荐方式 | 预计时间 |
|------|---------|----------|
| 常规课后（8人） | 速记批量输入 | 3-5分钟 |
| 重点关注学生 | 自然语言详细描述 | 2-3分钟/人 |
| 边走边记 | 语音转文字 | 实时 |
| 周汇总整理 | 查看班级周汇总文件 | 1分钟 |

---

*核心理念：批量不批量，千人千面不打折*
