# 项目记忆文件

## 课评工作流优化框架（v4.5）
> 创建日期：2026-05-16 | 基于实际跑流度的经验总结
> 更新日期：2026-05-20

### v4.5 更新内容
- **表单直连提交**：网页表单直接 POST 到本地服务器（`src/form_server.py`），AI 通过检测 `.claude/.tmp/EVALUATION_READY.txt` 信号文件自动触发课评生成，彻底取消「复制→粘贴」步骤
- **补课存储规则简化**：取消补课专用目录和双向记录，补课记录统一保存在学生原班级，文件名加 `_补课` 后缀
- **体验课记录扁平化**：体验课记录统一放在 `体验课记录/` 目录，命名格式 `日期-班级-课程主题.md`，一个文件可包含多个学生
- **临时数据清理**：课评保存完成后自动清理 `.claude/.tmp/` 下的 JSON 和信号文件

---

## 课评工作流优化框架（v4.4）
> 创建日期：2026-05-16 | 基于实际跑流度的经验总结

### 优化核心：「Form-First」三步式

```
/周几 → 选班级 → 自动打开网页表单 → 填表提交 → 自动生成保存
```

> **适用范围**：所有上课日（周一~周日），`/周六`、`/周日`、`/周四`、`/周五` 等均按此流程执行

### 关键规则

#### 规则1：自动推演课程进度
选择班级后，系统自动从 `summaries/` 读取最新课次，推算当前课次：
- 若上次课距当前日期>1周且全班请假 → 提示"需补课吗？"供确认
- 否则直接使用下一课次
- **目标：减少1轮"确认课程"的交互**

#### 规则2：默认网页表单输入（Form-First）
选择班级后**默认直接创建并打开网页表单**，不先展示文本输入：
- 表单包含每个学生的：状态按钮（出勤/请假/体验/补课）+ 独立文本区
- 表单显示学生画像摘要（性格特点、上次表现）
- 显示速记符号参考
- **目标：消除"需要输入框→创建表单"的切换摩擦**

#### 规则3：表单直连提交 + 输出头信息
网页表单增加"直接提交"功能，提交后：
- 后台自动接收数据
- 输出内容头部自动包含：班级名称、课程编号·主题、日期
- 系统可自动识别班级和课次，不会搞错
- **目标：消除"复制粘贴回聊天"的中间步骤 + 消除班级/课次识别错误**

#### 规则4：表单辅助功能
- 填写进度条：实时显示已填写/总人数（含补课学生）
- 待填写提示：红色标记未填写的学生
- 输入框状态：填写后自动变绿，视觉反馈
- 一键复制：复制到剪贴板，带成功提示
- **补课/体验学生区** 🆕：虚线边框独立区域，可动态添加多个补课学生，含姓名输入、状态（补课/体验）、表现描述，进度条自动计算在内

#### 规则5：年级感知
根据班级课程类型自动选择输出模板：
- 学龄前（TUBE/DISC/INVENT/CREATE）→ 学龄前格式
- 小学（SPIKE/AICODE03）→ 小学格式

### 已确认优化效果
- 交互轮数：5轮 → 3轮
- 输入方式：聊天文本→临时表单 → **默认网页表单**
- 课程确认：需人工回答 → **自动推算**
- 数据提交：手动复制粘贴 → **一键提交**

### 规则6：课评文字代码块包裹（便于预览复制）
班级总结文件（`*_班级反馈.md`）中，每位学生的课评正文必须用**代码块 ` ``` ` 包裹**，而非引用块 `>` 或纯文本：
- 代码块在 VS Code 预览时右上角显示**复制按钮**，方便一键复制课评文字
- 格式示例：
  ```markdown
  **课评内容**

  ```
  {课评正文}
  ```
  ```
- 请假/体验等无课评正文的学生，用 `**状态**：` 描述即可，无需代码块

## Hard Constraints
- All class days (Monday-Sunday) must follow the Form-First workflow
- Course progress must be automatically matched based on current week's date using semester week mapping (NOT inferred from last session progress)
- Web forms must be created by default for student performance input, no manual text input first
- Web forms must support direct POST submission to local server (`src/form_server.py`) — **no copy-paste required**
- AI detects `.claude/.tmp/EVALUATION_READY.txt` signal file to auto-trigger evaluation generation
- Temporary JSON and signal files in `.claude/.tmp/` are auto-cleaned after save completion
- **补课记录存储规则（v4.5）**：跨班级补课学生，课评文件保存在学生原班级 `feedback/` 目录，文件名加 `_补课` 后缀（如 `20260505_DISC-009_补课.md`），不再创建补课专用目录或双向记录
- **体验课记录规则（v4.5）**：体验课记录统一放在 `.claude/memory/class/体验课记录/` 目录，命名格式 `日期-班级-课程主题.md`（如 `2025-05-17-SPIKE-电动螺丝刀.md`），一个文件可包含多个体验学生

## Engineering Conventions
- Class selection is triggered by "/weekday" (e.g., "/周六", "/周四")
- Class lists display current week's course theme based on semester week number (e.g., Week 11 → DISC-011 鳄鱼)
- Student input forms include individual text areas and attendance status buttons
- Form data is saved as JSON to `.claude/.tmp/evaluation_input_{class}.json` via POST to local server
- Signal file `.claude/.tmp/EVALUATION_READY.txt` triggers AI to read JSON and generate evaluations
- Temporary JSON files and signal files are auto-cleaned after evaluation saving is complete
- **补课记录命名（v4.5）**：`YYYYMMDD_课程编号-课次_补课.md`，保存在学生原班级 `feedback/` 目录
- **体验课记录命名（v4.5）**：`日期-班级-课程主题.md`（如 `2025-05-17-SPIKE-电动螺丝刀.md`），保存在 `.claude/memory/class/体验课记录/` 目录

## Lessons Learned
- Manual course confirmation caused unnecessary interaction rounds; automatic inference saves time
- Chat-based text input was replaced with web forms due to user preference for dedicated input fields
- Course theme should be determined by current week's scheduled theme, not by tracking last session's progress
- Copy-paste from web form to chat was the #1 friction point; local server POST + signal file eliminates it entirely
- Generated form files must be auto-cleaned after use to avoid project directory clutter
- **补课记录简化（v4.5）**：双向记录和补课专用目录造成文件冗余，改为单记录保存在原班级更简洁
- **体验课扁平化（v4.5）**：多层嵌套目录不利于快速查看，扁平化结构更符合使用习惯