# ClassFeedback 课评管理规范

本文档规定了课评仓库的统一目录结构和文件格式，供所有老师参考使用。

---

## 一、目录结构规范

```
ClassFeedback/                          # 仓库根目录（命名：ClassFeedback）
├── .claude/                                   # Claude配置目录
│   ├── memory/                                # 记忆数据目录
│   │   ├── class/                             # 【班级数据 - 核心课评目录】
│   │   │   ├── 班级名称/                      # 命名：课程+老师+时间（如：CSP05克力周六1600）
│   │   │   │   ├── summaries/                 # 班级总结/群发文案
│   │   │   │   │   ├── YYYYMMDD_课程编号_班级反馈.md
│   │   │   │   │   └── YYYYMMDD_课程编号_微信群.txt
│   │   │   │   ├── 学生姓名1/                 # 学生个人文件夹
│   │   │   │   │   ├── feedback/              # 【个人课评目录】
│   │   │   │   │   │   ├── YYYYMMDD_课程编号.md          # 正常课评
│   │   │   │   │   │   ├── YYYYMMDD_课程编号(请假).md    # 请假记录
│   │   │   │   │   │   ├── YYYYMMDD_课程编号(补课-去XX).md # 补课追踪
│   │   │   │   │   │   └── ...
│   │   │   │   │   ├── profile.md             # 学生画像
│   │   │   │   │   └── summary/               # 阶段性总结
│   │   │   │   │       └── YYYY-MM_月度总结.md
│   │   │   │   ├── 学生姓名2/
│   │   │   │   │   └── ...
│   │   │   │   ├── 补课/                        # 补课学生专用目录
│   │   │   │   │   └── 学生姓名/               # 来自其他班级的补课学生
│   │   │   │   │       └── feedback/
│   │   │   │   │           └── YYYYMMDD_课程编号.md
│   │   │   │   └── ...
│   │   │   └── 班级名称2/
│   │   │       └── ...
│   │   ├── lesson/                            # 课程大纲资料（可选）
│   │   │   └── CSP01/
│   │   │       └── 课程大纲.md
│   │   └── oj/                                # OJ数据分析（可选）
│   │       └── analysis/
│   └── skills/                                # 技能脚本（可选）
└── README.md                                  # 仓库说明
```

---

## 二、命名规范

### 2.1 课程编号统一规则

**班级文件夹中的课程编号必须与校宝排课系统中的 `class_name` 一致。**

校宝中的课程名格式为 `课程编号+中文描述`，如 `CSP01信息学奥赛01`、`AICODE03AI编程创新课03`。提取编号部分的规则：

| 校宝 class_name | 提取编号 | 说明 |
|-----------------|---------|------|
| CSP01信息学奥赛01 | **CSP01** | C++ 信息学奥赛班 |
| CSP02信息学奥赛02 | **CSP02** | |
| CSP05信息学奥赛05 | **CSP05** | |
| AICODE01代码编程入门课01 | **AICODE01** | AI 代码编程班 |
| AICODE02代码编程入门课02 | **AICODE02** | |
| AICODE03AI编程创新课03 | **AICODE03** | |
| AICODE04AI编程创新课04 | **AICODE04** | |
| AICODE06AI编程创新课06 | **AICODE06** | |

**统一要求**：

1. **C++ 竞赛班统一用 `CSP`**：不得使用 `C++`、`信奥`、`信息学` 等作为课程前缀
2. **AI 编程班统一用 `AICODE`**：不得使用 `AI`、`AI03`、`AI01` 等缩写，必须是完整的 `AICODE01`、`AICODE03` 等
3. **编号必须与校宝一致**：校宝叫 CSP01 就是 CSP01，叫 AICODE03 就是 AICODE03

**当前需整改的目录**：

| 老师 | 当前目录名 | 应改为 |
|------|-----------|--------|
| 杰森 | AI01杰森周六1045 | AICODE01杰森周六1045 |
| 杰森 | AI02杰森周日1400 | AICODE02杰森周日1400 |
| 橙子 | AI03橙子周五1700 | AICODE03橙子周五1700 |
| 橙子 | AI03橙子周六1900 | AICODE03橙子周六1900 |
| 橙子 | AI03橙子周日0845 | AICODE03橙子周日0845 |
| 橙子 | AI03橙子周日1400 | AICODE03橙子周日1400 |
| 欧文 | AI02欧文周三1900 | AICODE02欧文周三1900 |
| 东东 | AI01东东周五1630 | AICODE01东东周五1630 |
| 东东 | AI01东东周日1900 | AICODE01东东周日1900 |
| 东东 | AI东东周六0845 | AICODE01东东周六0845 |

### 2.2 文件夹命名

| 层级 | 命名规则 | 示例 |
|------|---------|------|
| 班级文件夹 | 课程编号+老师+星期时间 | `CSP05克力周六1600`、`AICODE03东东周五1630`、`K2菠萝周六1045` |
| 学生文件夹 | 学生姓名 | `黄振轩`、`刘浩宇`、`李梓宁` |
| 课评子目录 | 固定名称 | `feedback`（课评）、`summary`（总结）、`补课`（补课学生） |

### 2.3 文件命名

| 类型 | 命名规则 | 示例 |
|------|---------|------|
| 单次课评 | `YYYYMMDD_课程编号-课次.md` | `20260418_CSP05-07.md`、`20260330_AICODE03-02.md` |
| 请假记录 | `YYYYMMDD_课程编号-课次(请假).md` | `20260505_CSP05-10(请假).md` |
| 补课追踪 | `YYYYMMDD_课程编号-课次(补课-去班级名).md` | `20260505_CSP05-10(补课-去AICODE03茄子周六1600).md` |
| 班级反馈 | `YYYYMMDD_课程编号-课次_班级反馈.md` | `20260418_CSP05-07_班级反馈.md` |
| 群发文本 | `YYYYMMDD_课程编号-课次_微信群.txt` | `20260418_CSP05-07_微信群.txt` |
| 月度总结 | `YYYY-MM_月度总结.md` | `2026-04_月度总结.md` |
| 学生画像 | 固定名称 | `profile.md` |

> **注意**：课程编号中的 `AI` 统一写 `AICODE`，如 `AICODE03-05` 而非 `AI03-05`。

### 2.4 日期规范（关键）

**课评文件名中的日期 YYYYMMDD 必须与校宝 `teaching_date` 完全一致。**

校宝排课是课评统计的唯一基准。课评完成率自动化统计时，以校宝记录的上课日期精确匹配文件名。

| 校宝 teaching_date | 正确文件名 | 错误文件名 | 原因 |
|-------------------|-----------|-----------|------|
| 2026-05-10（周六） | `20260510_CSP01-10.md` | `20260511_CSP01-10.md` | 05-11 是周日，非上课日 |
| 2026-05-09（周五） | `20260509_AICODE04-09.md` | `20260510_AICODE04-09.md` | 应取校宝日期而非提交日期 |

**常见错误**：
- 用课评**编写/提交日期**而非**实际上课日期**
- 周六上课但文件标周日日期
- 用课次所属周的周一/周日日期

**正确做法**：上完课当天就写完课评，文件名日期取校宝排课日期。

---

## 三、课评文件内容格式

### 3.1 标准课评模板

```markdown
# 课程名称：CSP05-07 初等数论2

**授课日期**: 2026-04-18

**课评内容**：
学生今天课堂非常认真，三类作业全部完成。但课堂练习调试12次（2次运行错误、3次答案错误、2次编译错误），说明边界条件和代码规范性还需加强。建议每道题重新手写框架，减少复用旧代码，这样基础更扎实。

课后整理埃氏筛法模板，记录今天的坑点。

---
**老师签名：XXX**
```

### 3.2 课评汇总模板（按学生汇总）

```markdown
# 学生姓名 - 课评汇总

---

## 第1节课：课程名（2026-03-07）

家长好，本周学习的内容是《XXX》：
1. 知识点1
2. 知识点2

学生今天表现...（详细课评内容）

—— 穹狼科创 XXX老师

---

## 第2节课：课程名（2026-03-14）

...

---
```

### 3.3 班级群发文案模板

```markdown
# CSP05-07 班级反馈（2026-04-18）

各位家长好，本周CSP05-07课程已结束。

## 课程内容
- 初等数论2：埃氏筛法、质因数分解

## 班级整体情况
- 课堂练习完成率：90%
- 课后作业提交率：85%

## 共性问题
1. 边界条件处理不够严谨
2. 代码规范性需要加强

请各位家长督促孩子完成课后作业，整理本周错题。

—— 克力老师
```

---

## 四、课评完成率统计规则

课评完成率由自动化系统按以下规则计算，请确保目录和文件符合规范以便被正确统计。

### 4.1 数据来源

- **出勤基准**：校宝 API 排课数据（`teaching-schedule`），以校宝为准
- **统计范围**：仅统计 CSP 和 AICODE 班级
- **时间范围**：默认上周三到本周二

### 4.2 出勤状态判定

| 校宝 attendance_status | 判定 | 课评要求 |
|----------------------|------|---------|
| 含 `到课`/`出勤`/`签到` | **到课** | 必须有课评文件 |
| 含 `请假` | **请假** | 当天不要求课评 |
| 其他 | **缺勤** | 不要求 |

- 补课学生（`student_identity = 补课`）按到课处理，必须有课评
- 试听学生（`student_identity = 试听`）按到课处理，必须有课评

### 4.3 课评文件查找规则（三级查找）

对校宝中每个到课学生，系统按以下优先级查找课评文件：

```
校宝记录：学生S 在日期D 到课，排课老师为T，班级编号为B

第1级 → 去老师T的仓库，在班级B对应目录下查找
  路径：T仓库/.claude/memory/class/{含B的目录}/S/feedback/
  文件：YYYYMMDD(D)_*.md（排除汇总/登记/总结/班级反馈）
  找到 → 匹配成功 ✓
  未找到 → 进入第2级

第2级 → 去老师T的仓库，在其他所有班级的 补课/ 目录下查找
  路径：T仓库/.claude/memory/class/{其他班级}/补课/S/feedback/
  找到 → 匹配成功 ✓
  未找到 → 进入第3级

第3级 → 去其他所有老师的仓库，在所有班级的 补课/ 目录下查找
  路径：其他老师仓库/.claude/memory/class/{任意班级}/补课/S/feedback/
  找到 → 匹配成功 ✓
  未找到 → 标记为「缺失」✗
```

### 4.4 日期匹配

**严格匹配**：文件名中的 `YYYYMMDD` 必须与校宝 `teaching_date` 完全一致。不一致的课评不计入完成率，会被标注为「日期偏移」。

### 4.5 学生名匹配

- 去除空格后比较
- 支持包含匹配（如仓库 `梁铭轩` 可匹配校宝 `梁铭轩（大）`）
- 去除后缀标记如 `(am)`、`1` 等再尝试

### 4.6 完成率计算

```
应发总数 = 到课学生数（本班到课 + 补课到课 + 试听到课）
已完成   = 按三级查找规则匹配到的学生数
完成率   = 已完成 / 应发总数 × 100%
```

请假学生**不纳入**应发总数。如果请假学生后续在其他课堂补课（校宝中以补课身份出现），按到课学生处理。

### 4.7 上课后必须完成

- [ ] 为每位**到课**学生编写个人课评（保存到 `feedback/YYYYMMDD_课程编号.md`）
- [ ] 日期取校宝排课日期，不是编写日期
- [ ] 补课学生也必须有课评（放在补课班级的 `补课/学生名/feedback/` 下）
- [ ] 编写班级总结（保存到 `summaries/YYYYMMDD_课程编号_班级反馈.md`）

---

## 五、各老师当前格式对照

| 老师 | 当前路径 | 建议调整为 |
|------|---------|-----------|
| 19163520381 | `.claude/memory/student/班级/学生/课评反馈/课评汇总.md` | `.claude/memory/class/班级/学生/feedback/YYYYMMDD_课程.md` |
| 13711179294 | `ClassFeedback/学生姓名.md` | `.claude/memory/class/班级/学生/feedback/YYYYMMDD_课程.md` |
| 13202777474 | `reviews/班级/学生日期.md` | `.claude/memory/class/班级/学生/feedback/YYYYMMDD_课程.md` |
| 13974188170 | `.claude/memory/student/班级/学生/课评/第X周课程.md` | `.claude/memory/class/班级/学生/feedback/YYYYMMDD_课程.md` |
| 18576526757 | `.claude/memory/student/班级/学生/课评反馈/课评汇总-2026春季.md` | 保持汇总格式，增加单次课评文件 |
| **17788733242** | **`.claude/memory/class/班级/学生/feedback/YYYYMMDD_课程.md`** | **✅ 标准格式** |
| 13108110172 | `.claude/student/班级/学生/历史课评.md` | `.claude/memory/class/班级/学生/feedback/YYYYMMDD_课程.md` |

### 非标准结构（无法自动统计课评率）

| 老师 | 当前结构 | 问题 |
|------|---------|------|
| 大橘 | `课堂记录/` | 课评不在 `.claude/memory/class/`，无法自动扫描 |
| 小Q | `memory/class-evaluation-summary/` | 按周汇总而非按次按学生，无法自动统计 |
| 南瓜 | `ClassFeedback/` | 全班课评模式，无个人课评文件 |

---

## 六、快速开始

### 6.1 新建班级

```bash
mkdir -p ".claude/memory/class/课程老师星期时间/学生姓名/feedback"
mkdir -p ".claude/memory/class/课程老师星期时间/学生姓名/summary"
mkdir -p ".claude/memory/class/课程老师星期时间/summaries"
```

### 6.2 创建课评文件

```bash
# 创建单次课评
touch ".claude/memory/class/班级/学生/feedback/$(date +%Y%m%d)_课程编号.md"

# 创建学生画像
touch ".claude/memory/class/班级/学生/profile.md"
```

---

## 七、注意事项

1. **日期格式统一**：使用 `YYYYMMDD` 格式（如 20260418），**必须与校宝排课日期一致**
2. **课程编号规范**：C++ 班用 `CSP`，AI 班用 `AICODE`，与校宝保持一致，不得使用 `AI`、`C++` 等缩写
3. **文件名禁用字符**：避免使用 `/\:*?"<>|`
4. **中文命名**：学生姓名和班级名称使用中文，保持可读性
5. **及时提交**：每次上完课后当天完成课评并提交到 git，确保文件日期与校宝排课日期一致
6. **补课必须记录**：补课学生的课评放在补课班级的 `补课/学生名/feedback/` 下，否则统计不到
7. **不要汇总代替单次**：课评必须按次按学生单独文件，不能只有汇总文件

---

## 八、考勤状态记录规范

### 8.1 三种状态

每次课后，每位学生必须有且仅有一条记录，对应三种状态：

| 状态 | 文件名格式 | 说明 |
|------|-----------|------|
| 正常上课 | `YYYYMMDD_课程编号.md` | 包含完整课评内容 |
| 请假 | `YYYYMMDD_课程编号(请假).md` | 简要记录请假原因 |
| 补课 | `YYYYMMDD_课程编号(补课-去班级名).md` | 记录去了哪个班补课 |

### 8.2 请假记录模板

文件名：`20260505_CSP05-10(请假).md`

```markdown
# 请假记录

**日期**: 2026-05-05
**课程**: CSP05-10
**学生**: 刘毅潇
**状态**: 请假
**原因**: （如有）
```

### 8.3 补课追踪（双向记录）

补课产生**两条**记录，分别在原班级和补课班级：

**场景**：洋芋老师的学生王五，到茄子老师的 AICODE03 班补课

**1) 原班级（洋芋老师）— 学生 feedback/ 下**：
- 文件名：`20260510_AICODE06-03(补课-去AICODE03茄子周六1600).md`
- 内容：简要说明去哪补课

```markdown
# 补课记录

**日期**: 2026-05-10
**原课程**: AICODE06-03
**学生**: 王五
**状态**: 补课
**补课班级**: AICODE03茄子周六1600
**补课老师**: 茄子
```

**2) 补课班级（茄子老师）— 补课/学生名/feedback/ 下**：
- 文件名：`20260510_AICODE03-05.md`
- 内容开头注明：`（补课，来自 AICODE06洋芋周日1400）`，后续正常写课评

### 8.4 AI 读取逻辑

AI 扫描 `feedback/` 目录时，通过文件名后缀判断状态：

| 文件名匹配 | 判定 |
|-----------|------|
| `YYYYMMDD_课程编号.md` | 正常课评 |
| `YYYYMMDD_课程编号(请假).md` | 请假，无需课评 |
| `YYYYMMDD_课程编号(补课-去...).md` | 补课，课评在补课班级 |

---

## 九、课程大纲同步规范

### 9.1 大纲来源

课程大纲从两个独立仓库同步，**不提交到老师自己的仓库**：

| 课程线 | 同步源 |
|--------|--------|
| CSP 课程 | `https://git.qonnwolf.com/17788733242/CSP2026` |
| AICODE 课程 | `https://git.qonnwolf.com/18675193675/AICODE2026` |

### 9.2 本地存放位置

```
.claude/memory/lesson/
├── CSP/                    ← 从 CSP2026 仓库同步
│   ├── CSP01/
│   ├── CSP02/
│   └── ...
└── AICODE/                 ← 从 AICODE2026 仓库同步
    ├── AICODE01/
    ├── AICODE03/
    └── ...
```

### 9.3 同步方式

```bash
# 首次克隆到临时目录
git clone https://git.qonnwolf.com/17788733242/CSP2026 /tmp/CSP2026
git clone https://git.qonnwolf.com/18675193675/AICODE2026 /tmp/AICODE2026

# 复制大纲到 lesson 目录
cp -r /tmp/CSP2026/* .claude/memory/lesson/CSP/
cp -r /tmp/AICODE2026/* .claude/memory/lesson/AICODE/

# 后续更新：拉取后覆盖
cd /tmp/CSP2026 && git pull
cp -r /tmp/CSP2026/* .claude/memory/lesson/CSP/
```

### 9.4 .gitignore 配置

在老师的仓库 `.gitignore` 中添加，避免大纲被推送到远端：

```gitignore
# 课程大纲从独立仓库同步，不提交到本仓库
.claude/memory/lesson/
```

### 9.5 来源标记

在 `.claude/memory/lesson/` 下放置 `README.md` 记录来源：

```markdown
# 课程大纲

本目录从独立仓库同步，不提交到老师自己的远端仓库。

| 目录 | 来源仓库 |
|------|---------|
| CSP/ | https://git.qonnwolf.com/17788733242/CSP2026 |
| AICODE/ | https://git.qonnwolf.com/18675193675/AICODE2026 |

更新方式：执行"同步课程大纲"技能
```

---

*规范制定日期：2026-04-21*
*最后更新：2026-05-13*
*参考模板：ClassFeedback_17788733242*