feat(task): M1-02 覆盖班级与班主任配置
补上发布前置校验的最后一环（40019），同时确立任务的数据隔离边界 ——
班主任能看到哪些任务、能审哪些单子，全由 collect_task_org 决定。
后端 GET/PUT /tasks/{id}/orgs（整体替换语义 + 软移除 + 历史行复用）；
前端「配置班级」抽屉：组织树只允许勾选班级，主班主任留空时显式提示
「将由该班负责人初审」而非留白。发布被拦时给出「去哪里补」的指引
（BLOCKING_HINTS），而不是只说"未设置覆盖班级"。
三条守住的规则：
1) 班级与初审人都必须在本租户内。跨租户的 id 一律当作"不存在或已删除"，
不透露"它存在但不属于你" —— 漏了的后果是 A 校能把 B 校的班挂到自己
的任务上，B 校的班主任就出现在 A 校的审批流里。
2) 初审人必须持有班主任/副班主任角色。指定初审人本质上是一次授权，
那个人将能看到该班学生的身份证号与学籍材料；不校验角色就等于把
"谁能看学生隐私"变成任意授权。报错要给出下一步，不能只说"校验失败"。
3) 移除是软移除（status=0），且「移除再加回」必须复用原行。
后者不是优化而是必须：uk_task_org UNIQUE (task_id, org_id) 不带 status
条件，一个班在同一任务下只能有一行，直接 insert 会违反唯一约束。
本轮修掉的 3 个真问题：
1) 我此前误判 uk_task_org 不存在 —— grep 只匹配含表名的行，而
CONSTRAINT uk_task_org UNIQUE (task_id, org_id) 那行没有表名。
基于这个错误前提，我写了一个多余的部分唯一索引 uk_task_org_active
和一段基于错误前提的代码，已全部撤掉并更正注释。
教训：查约束要看 CREATE TABLE 整块，不能只 grep 表名。
2) collect_task_org.expected_count 是 NOT NULL DEFAULT 0，与接口契约矛盾：
DDL 注释说它是"由名册汇总"（系统算的），但《03-接口设计》§7.6 把它放在
PUT 请求体里、说"用于与名册实际人数比对" —— 只有"管理员填的期望值 vs
名册实际值"才需要比对。而 0 是有意义的业务值（"预期 0 人"），拿它兼职
表示"没填"会让每个没填的班都触发"应填 0 人、实际 31 人"的假告警；告警
变噪音就没人看了，真正"应填 28、名册却有 31"（名册导错）反而被漏掉，
而这条告警的全部价值就在那一次。已由 V4 迁移改为可空 + 去掉默认值，
并同步更正 docs/db/schema-postgresql.sql 与 PRD 里的内联 DDL。
3) 删掉迁移文件后必须 mvn clean，否则它会"复活"：我只跑 mvn package，
target/classes 里的旧副本被打进 jar，Flyway 发现历史里没有 v4 就又执行
了一遍 —— 索引回来了、历史行填回去了。之后又建了同名版本号的新 V4，
于是"两个 v4"→"checksum 冲突"，排查绕了好几圈。
顺带修掉：
· 任务列表操作列从 3 个链接涨到 4 个，160px 会挤成竖排 —— 把「进度」并进
「状态」列腾出 40px，操作列给到 200px，合计 820px（可用约 824px）。
· defineEmits 必须用函数调用签名（frontend-pc/.agents/skills/code-vue）。
我此前写的 5 个组件都是被禁的 tuple 形式，一并改正：
OrgFormModal / TaskFormModal / TaskOrgDrawer / UserFormModal / UserImportModal。
· e2e-m1-orgs.py 的清理抽成幂等的 cleanup_all()，并在 __main__ 的 finally
里兜一次 —— 该脚本首次运行时崩在准备阶段、清理段没执行，把两个测试账号
留在了库里（是在浏览器里看到下拉框里有个「E2E班主任」才发现的）。
其余三条 E2E 脚本仍是老样子，下一轮一并改。
验收：e2e-m1-orgs.py 48/48（含跨租户隔离）；e2e-m1-task.py 71/71、
e2e-m0-user.py 55/55、e2e-m0.py 36/36 回归通过，共 210 项断言；
前端 typecheck / eslint / lint:style 0 错、build 通过；
浏览器实测抽屉的开合、树的勾选规则与保存落库。
This commit is contained in:
+68
-2
@@ -48,8 +48,9 @@
|
||||
| M0 后端接口 | ✅ 租户开通与列表、组织 CRUD 与树、PC 登录/登出/当前用户、**账号管理全套（含 Excel 批量导入）** |
|
||||
| M0 验收 | ✅ **`e2e-m0.py` → 36/36**；**`e2e-m0-user.py` → 55/55** |
|
||||
| **M1-01 任务 CRUD 与状态机** | ✅ 建/改/删/发布/暂停/恢复/截止/归档 + 可见范围（班主任只看自己带的班）；**`e2e-m1-task.py` → 71/71** |
|
||||
| PC 前端 | ✅ 已换 Gi Admin Pro + 腾讯云主题；已实现：登录 / 工作台 / 组织架构 / 租户管理 / 账号管理 / **收集任务** |
|
||||
| 待做 | M1 剩余（M1-02 覆盖班级、M1-03 表单 schema、M1-04 材料项、M1-06 二维码、M1-07~M1-10 前端）；小程序（uni-app）未创建；CI/CD；H5 保底预研 |
|
||||
| **M1-02 覆盖班级与班主任** | ✅ `GET/PUT /tasks/{id}/orgs`（整体替换 + 软移除 + 历史行复用）+ 前端「配置班级」抽屉（勾选班级、主/副班主任、应填人数）；**`e2e-m1-orgs.py` → 48/48** |
|
||||
| PC 前端 | ✅ 已换 Gi Admin Pro + 腾讯云主题；已实现：登录 / 工作台 / 组织架构 / 租户管理 / 账号管理 / **收集任务（含配置班级）** |
|
||||
| 待做 | M1 剩余（M1-03 表单 schema、M1-04 材料项、M1-06 二维码、M1-07~M1-10 前端）；小程序（uni-app）未创建；CI/CD；H5 保底预研 |
|
||||
|
||||
---
|
||||
|
||||
@@ -153,6 +154,71 @@
|
||||
|
||||
---
|
||||
|
||||
## 一·六、M1-02 覆盖班级与班主任（2026-09-29 上午，未提交）
|
||||
|
||||
> 范围：`GET/PUT /api/v1/tasks/{id}/orgs`（《03-接口设计》§7.6）；
|
||||
> 前端「收集任务 → 操作 → 配置班级」抽屉（勾选班级 + 主/副班主任 + 应填人数）。
|
||||
|
||||
**验收**：`python scripts/e2e-m1-orgs.py` → **48/48**；
|
||||
`e2e-m1-task.py` 71/71、`e2e-m0.py` 36/36、`e2e-m0-user.py` 55/55 回归通过；
|
||||
前端 `typecheck` / `eslint` / `lint:style` 0 错、`build` 通过。
|
||||
|
||||
### 三条守住的规则（改动时当成规则）
|
||||
|
||||
| # | 规则 | 为什么 |
|
||||
|:--:|---|---|
|
||||
| 1 | **班级与初审人都必须在本租户内** | 跨租户的 id 一律当作"不存在或已删除"，不透露"它存在但不属于你"。漏了的后果是 A 校可以把 B 校的班挂到自己的任务上，B 校的班主任就出现在 A 校的审批流里 |
|
||||
| 2 | **初审人必须持有班主任/副班主任角色** | 「指定初审人」本质上是一次**授权** —— 那个人将能看到该班学生的身份证号与学籍材料。不做角色校验就等于把"谁能看学生隐私"变成任意授权。报错要给出下一步（去账号管理分配角色），不能只说"校验失败" |
|
||||
| 3 | **移除是软移除**（`status = 0`），且**"移除再加回"必须复用原行** | 名册与提交单挂在覆盖关系下，物理删会让历史数据失去归属。而复用是**必须**的（不是优化）：`uk_task_org UNIQUE (task_id, org_id)` 不带 status 条件，一个班在同一任务下只能有一行，直接 insert 会违反唯一约束 |
|
||||
|
||||
### 本轮修掉的 3 个真问题
|
||||
|
||||
| # | 问题 | 后果与修法 |
|
||||
|:--:|---|---|
|
||||
| 1 | **我误判 `uk_task_org` 不存在** | 先前的 grep 只匹配含 `collect_task_org` 字样的行，而 `CONSTRAINT uk_task_org UNIQUE (task_id, org_id)` 那行**没有表名** —— 于是漏掉了，还基于"没有唯一约束"的错误前提写了一个多余的部分唯一索引 `uk_task_org_active`。已撤掉（DROP INDEX + 删 flyway 历史行 + 删文件），并更正了注释：**"复用已移除的行"不是优化而是必须**。教训：**查约束要查 `CREATE TABLE` 整块，不能只 grep 表名** |
|
||||
| 2 | **`collect_task_org.expected_count` 是 `NOT NULL DEFAULT 0`，与接口契约矛盾** | DDL 注释写的是"冗余，由名册汇总"（系统算的），但《03-接口设计》§7.6 把它放在 **PUT 请求体**里，且说"用于**与名册实际人数比对**，不一致时告警" —— 只有"管理员填的期望值 vs 名册实际值"才需要比对。而 `0` 是有意义的业务值（"预期 0 人"），拿它兼职表示"没填"会让**每个没填的班**都触发"应填 0 人、实际 31 人"的假告警；告警变噪音就没人看了，真正"应填 28、名册却有 31"（名册导错）反而被漏掉 —— 而这条告警的全部价值就在那一次。已由 `V4__task_org_expected_count_nullable.sql` 改为**可空 + 去掉默认值**，并同步更正了 `docs/db/schema-postgresql.sql` 与 PRD 里的内联 DDL。**NULL ≠ 0 这条规则适用于所有"可选数字"字段** |
|
||||
| 3 | **删掉迁移文件后必须 `mvn clean`，否则它会"复活"** | 我删掉 `V4__task_org_active_unique.sql` 后只跑了 `mvn package`（没有 clean）：`target/classes/db/migration/` 里**还留着旧副本**，被打进 jar，Flyway 发现历史里没有 v4 就**又执行了一遍** —— 索引回来了、历史行填回去了。之后 I 又建了同名版本号的新 V4，启动就报 `Found more than one migration with version 4`；清了旧副本后又变成 `Migration checksum mismatch for migration version 4`。**排查绕了好几圈，根源就是一行 `mvn package` 少了 `clean`。** 规则：**动过 `db/migration/` 里的文件（新增、删除、改名），一律 `mvn clean package`** |
|
||||
|
||||
顺带修掉：`views/task/index.vue` 的操作列从 3 个链接涨到 4 个（编辑/配置班级/发布/删除），
|
||||
160px 会挤成竖排 —— 把「进度」并进「状态」列腾出 40px，操作列给到 200px，合计 820px
|
||||
（可用约 824px）。发布被拦时现在会**告诉用户去哪里补**（`BLOCKING_HINTS`），
|
||||
而不是只说"未设置覆盖班级"。
|
||||
|
||||
### E2E 脚本必须"崩了也清理"
|
||||
|
||||
`e2e-m1-orgs.py` 第一次运行时在准备阶段抛了 `TypeError`（我自己写错了参数），
|
||||
**脚本直接退出、清理段没执行**，把两个测试账号留在了库里 —— 直到我在浏览器里
|
||||
看到「班主任」下拉里有个 `E2E班主任688ed2` 才发现。
|
||||
|
||||
已改成：清理逻辑抽成模块级 `cleanup_all()`（幂等），既在 `main()` 末尾调用，
|
||||
也在 `__main__` 的 `try/except BaseException` 里兜一次。
|
||||
**其余三条 E2E 脚本（`e2e-m0.py` / `e2e-m0-user.py` / `e2e-m1-task.py`）还是老样子，
|
||||
崩了会漏数据，下一轮一并按这个模式改。**
|
||||
|
||||
> 另外记一笔：清理残留账号时我写的用户名前缀过滤（`adm`）**把 `admin` 也匹配进去了**，
|
||||
> 是服务端的「不能停用当前登录的账号，请换一个管理员账号操作」把它挡下来的。
|
||||
> 那条护栏当初加的时候是为了防自锁，这次意外挡住了一次误删 —— 护栏的价值往往
|
||||
> 不是在被设计的场景里体现的。
|
||||
|
||||
### ⚠️ 新增两条前端硬规则（来自 `frontend-pc/AGENTS.md` 与 `.agents/skills/`）
|
||||
|
||||
1. **未经用户明确要求，不要 `git commit` / `push`**（AGENTS.md 常驻规则）。
|
||||
本轮改动**未提交**，工作区里留着。
|
||||
2. **`defineEmits` 必须用函数调用签名**，禁止 tuple/对象形式：
|
||||
```ts
|
||||
// ✅
|
||||
const emit = defineEmits<{ (e: 'save-success'): void }>()
|
||||
// ❌ const emit = defineEmits<{ 'save-success': [] }>()
|
||||
```
|
||||
框架自带组件（GiForm / GiButton / GiTable）用的都是前者 —— 这是本项目已确立的写法。
|
||||
我此前写的 5 个组件（`OrgFormModal` / `TaskFormModal` / `TaskOrgDrawer` /
|
||||
`UserFormModal` / `UserImportModal`）都是被禁的 tuple 形式，**本轮已全部改正**。
|
||||
|
||||
改文件前先按 `frontend-pc/AGENTS.md` 的表格加载对应 skill（`.vue` → `code-vue`，样式 → `code-css`，
|
||||
`.ts` → `code-ts`，CRUD → `project-crud`）。
|
||||
|
||||
---
|
||||
|
||||
**关键实现决策（不要在后继开发中改回去）**
|
||||
|
||||
| 决策 | 理由 |
|
||||
|
||||
Reference in New Issue
Block a user