# 课程作业模块 · 功能清单与原型说明（v1 / 任课教师视角 · 核心闭环）

> 说明：本模块只复用校园公告模板的**外壳**——顶栏 + 左栏菜单机制、登录/SSO、班级树选人、富文本、附件上传、列表分页、统计页骨架。内部页面与数据按“课程作业”真实业务重搭，不再套用公告的“发布→接收→已读→审批”模型。
>
> v1 范围：**仅任课教师端核心闭环** = 布置作业 → 我布置的 → 提交情况（已交/未交） → 批改中心 → 作业统计。
> v1 暂不做：作业审核（审批流）、分层/周期性作业、学生端与家长端、拍照/附件真实上传（批改读取用 mock）。

---

## 0. 角色与左栏菜单（v1 = 教师视角）

登录身份 = 任课教师（沿用 `GetUserMod` 数据驱动左栏）。左栏菜单项：

| 序号 | 菜单名 | 路由 | 对应页面 | 复用/新建 |
|---|---|---|---|---|
| 1 | 布置作业 | `/assign` | 新建/编辑作业表单 | 改造自现 `NewHomework.vue` |
| 2 | 我布置的 | `/list` | 作业列表（按状态分组） | 改造自现 `HomeworkList.vue` |
| 3 | 提交情况 | `/submissions` | 单作业的已交/未交名单 | 新建（可并入详情） |
| 4 | 批改中心 | `/grade` | 逐份批改工作台 | 新建 |
| 5 | 作业统计 | `/stats` | 提交率/正确率/分布 | 改造自现 `HomeworkStats.vue` |

> “我布置的”行内入口：查看详情、编辑、复制、置顶、撤回、催交；从某条作业进入「提交情况」和「批改中心」。

---

## 1. 核心业务闭环（状态机）

```
                ┌──────────── 我布置的（列表，筛选/状态标签） ────────────┐
                │                                                        │
  布置作业(草稿) ─发布→ 收集中 ──到截止──> 已截止 ──全部批改完──> 已完成
                │            │                      │
                │        催交(未交)               批改中心(逐份 打分/评语/驳回)
                │            │                      │
                └──── 编辑/复制/置顶/撤回           订正 ── 学生重交 ── 再批改
```

- **作业状态**：草稿 / 收集中 / 已截止 / 已完成（v1 去掉 pending/rejected 审批态）。
- **提交状态**（每个学生×每份作业）：未交 / 已交（待批改） / 已批改 / 待订正 / 已订正。

---

## 2. 页面详规

### 2.1 布置作业（`/assign`）
目的：教师创建并即时发布一份作业给若干班级。

表单项：
- 学科（下拉，来自作业设置/字典）
- 作业标题（必填）
- 布置班级（多选，复用 `ClassCheckInput` 班级树；支持“全部班级”）
- 截止时间（日期时间；用于“已截止”判定与倒计时）
- 提交方式（多选/单选：文本、图片、附件、无需提交仅查阅）——决定学生端能力与批改界面
- 作业正文（富文本，复用 `@wangeditor`）
- 附件/题目（复用现附件上传组件 `HomeworkUpload`）
- 是否开启短信提醒（复用 `smsFlag`）
- 操作：保存草稿 / 发布

交互要点：发布即进入“收集中”，生成面向所选班级的可见作业；编辑草稿不改变状态。v1 无审批直发。

API：`POST /api/homework/Create`、`POST /api/homework/Edit`（复用，字段扩展见 §3）。

### 2.2 我布置的（`/list`）
目的：教师管理自己发布的所有作业。

- 顶部状态标签页：全部 / 收集中 / 已截止 / 已完成 / 草稿
- 列表列：标题、学科、布置班级、截止时间、提交进度（已交 x/应交 y）、批改进度（已批 m/已交 n）、状态、操作
- 操作：查看详情、编辑、复制、置顶、撤回、催交、进入批改
- 支持关键词/学科/时间筛选（复用 `applyFilters` 思路）

API：`GET /api/homework/SendList?scope=user`（改造为“我布置的”，返回体新增 progress 字段）。

### 2.3 提交情况（`/submissions?serid=`）
目的：看某份作业的收交名单。

- 头部：作业标题、截止倒计时、提交率、已交/未交/待订正 汇总
- 名单（按班级分组，复用 `ReadDetail` 的年级→班级分组）：每个学生 提交时间 / 状态 / 快捷“批改”“催交”
- 批量：对未交一键催交（短信/站内）

API：`GET /api/homework/Submissions?serid=`（新增，替代现 `ReadDetail` 的“已读/未读”语义）。

### 2.4 批改中心（`/grade?serid=&subId=`）
目的：逐份高效批改。

- 左：提交列表（已交待批优先）；右：某学生提交内容（文本/图片/附件预览，复用 `@open-file-viewer`/pdfjs）
- 批改区：评分方式二选一——分数（0–100）或等级（A/B/C 或 优/良/待改进）；文字评语；（可选）图片圈划标注
- 动作：保存批改、标为优秀作业、驳回要求订正、（批量）一键通过
- 键盘快捷键上一条/下一条，提升批改效率

API：`GET /api/homework/SubmissionDetail?subId=`、`POST /api/homework/Grade`（新增）。

### 2.5 作业统计（`/stats`）
目的：教师看学情。

- 单作业维度：提交率、按时率、批改进度、分数/等级分布、订正完成率、共性易错点（v1 可仅展示分布）
- 总览维度：我布置的作业数、平均提交率、待批改数量
- 图表复用现统计页骨架

API：`GET /api/homework/Statis`（改造为作业口径）。

---

## 3. 数据模型（v1 新增字段，mock 需对齐）

**Homework（作业）**
- 新增：`subject`（学科）、`deadline`（截止）、`submitType`（提交方式数组）、`status ∈ {draft, collecting, closed, done}`
- 去除/停用：`approvalEnabled/approvalStatus/approvalFlow`（v1 不用）、`classRead`（改为按提交统计）

**Submission（提交）** — 新概念
```
{ id, homeworkId, studentId, studentName, classId, className,
  submittedAt|null, submitStatus: 'unsubmitted'|'submitted'|'graded'|'needRedo'|'redone',
  text, images[], attachments[],
  grade: { score|null, level|null, comment, isExcellent, markedImages[] } }
```

学生名单来源：班级 → 学生（现 mock 只有班级维度 `studentCount`，v1 需扩到**学生个体**才能做提交/批改；生成每班的 N 个 mock 学生即可）。

**统计**：提交率=已交/应交；按时率=截止前交/应交；批改进度=已批/已交；分数分布分桶。

---

## 4. 与现有“公告换皮”代码的差异（改造清单）

| 现有（公告语义） | v1 课程作业 | 处理 |
|---|---|---|
| 已收到 / 已发送 | 我布置的（+提交情况） | 改列表口径与字段 |
| 已读 / 未读（班级维度） | 已交 / 未交（学生个体维度） | 提交名单需下到学生 |
| 审批 pending/rejected | v1 不做 | 关闭审批入口与状态 |
| 收件箱(学生视角) | v1 不做（属学生端） | 暂隐藏 |
| NewHomework/Detail/Stats | 布置作业/详情/统计 | 改造复用 |
| ClassCheckInput/富文本/附件/TablePage | 同名复用 | 直接用 |

Mock 层：在 `src/assets/mock/homeworkapi.ts` 里 ①补 `subject/deadline/submitType`；②加学生个体表；③新增端点 `Submissions / SubmissionDetail / Grade / Remind`；④`Statis` 改作业口径；⑤去掉 `SeedFlows/approval` 相关种子与分支（或保留但不进菜单）。

---

## 5. v1 之后（预留，不实现，仅登记）

- 学生端 / 家长端（今日作业、提交、看批改、订正补交、提醒）
- 作业审核（教研组/教务抽查，复用现审批流，可选开启）
- 分层作业（A/B 组不同题量）、周期性作业（每周固定模板自动生成）
- 拍照提交 + 手写圈划批改、错题本、年级作业负担看板、优秀作业库

---

## 6. 建议下一步

1. 你按本页圈改功能/字段（尤其 §2 每页要哪些、§3 提交/批改字段够不够）。
2. 确认后我先改造 `mock`（补学生与提交/批改数据 + 新端点），再逐页替换 `views`。
3. 先做「布置作业 → 我布置的 → 提交情况」这条能看到数据的链，批改中心随后。