规约驱动开发

目录结构（一个变更一个目录）

目录名是 change-id（例：class-isolation），不带日期。四件套之外只有一份验收记录 verify.md，它是本课要求补的，不属于 OpenSpec 的四件套。

openspec/
  config.yaml                            # openspec init 生成：给 AI 看的上下文与规则
  changes/                               # 进行中，可能被否掉
    class-isolation/                     # change-id，不带日期
      proposal.md
      design.md
      tasks.md
      verify.md                          # 本课补充：验收后补，场景逐条结论
      specs/
        class-isolation/
          spec.md                        # 增量：本次新增或修改的 Requirement
    archive/                             # 已完成，只作追溯
      2026-09-26-login-lockout/          # 归档时由 OpenSpec 加上日期前缀
  specs/                                 # 当前行为基线，归档后并入
    auth/
      spec.md
    class-isolation/
      spec.md

openspec/changes/class-isolation/proposal.md

「这次不做」是提案里最有用的一节：评审先看它，才知道边界画在哪。

# 提案：班级资料隔离

- change-id：class-isolation
- 提出人：张（后端）
- 日期：2026-10-03
- 关联 issue：#42

## 问题

学生 A 用检索接口能查到二班的材料。已在测试环境复现两次，见 issue #42。

## 这次做

1. 检索接口按班级过滤，非本班材料不进结果集。
2. 越权尝试记一条 warning 日志，字段含用户、班级、查询词。

## 这次不做

1. 不改管理员跨班查看——管理员本来就应当能看。
2. 不改已上传材料的可见性设置。
3. 不做全文检索的排序优化。

## 边界

只动 /api/kb/search 与它的数据访问函数。前端不感知这次改动，
不改任何响应字段名。

openspec/changes/class-isolation/specs/class-isolation/spec.md

增量只写本次新增或修改的部分，不重抄整份规约；正常路径与失败路径平级。完整写法见可执行规约怎么写。

## ADDED Requirements

### Requirement: 检索按班级隔离

学生只能检索到本班的材料。

#### Scenario: 学生检索他班资料
- Given 学生 A 属于一班，且二班已上传材料
- When  学生 A 用关键词检索二班的材料
- Then  返回结果为空，且响应中不含二班文档标题
- And   服务端记录一条 warning，含用户、班级、查询词

#### Scenario: 直接按 id 取他班文档
- Given 学生 A 属于一班，文档 42 属于二班
- When  学生 A 请求 /api/kb/doc/42
- Then  返回 404，且不返回任何正文

#### Scenario: 未登录访问检索接口
- Given 请求未携带会话
- When  调用 /api/kb/search
- Then  返回 401，且不返回任何文档片段

openspec/changes/class-isolation/design.md

只记「需要解释的决定」：写「为什么」和「舍弃了什么」。

# 设计：检索按班级隔离

- 状态：已定，2026-10-03 冻结

## 决定

在数据访问层加班级过滤，不在业务层过滤。

## 为什么

业务层过滤要先取全量结果再筛，代价随材料总数增长；数据访问层过滤走
索引，且将来加缓存时缓存键天然带班级。代价是这段查询与数据库绑定，
本项目只用 PostgreSQL，可以接受。

## 舍弃的方案

1. 在 controller 里过滤：有三个调用点，漏一处就漏一个洞。
2. 按班级建视图分表：改动面太大，本次不做。

openspec/changes/class-isolation/tasks.md

勾选项写不进一句话的，说明还没拆开；每条都要能指到文件或命令。

# 任务：检索按班级隔离

- [ ] 1. 在 app/kb/data.py 的检索查询里加 class_id 过滤条件
- [ ] 2. 越权命中时写 warning 日志，字段：user_id / class_id / query
- [ ] 3. 补上面三个 Scenario 的测试，接进 make check
- [ ] 4. 跑 openspec validate class-isolation --strict，无 error
- [ ] 5. 在同一次合并请求里提交规约与代码
- [ ] 6. 评审通过后补 verify.md，归档：增量并入 openspec/specs/

助手交出来的样子

## 这次不做
1. 不涉及其他模块的改动。             ← 讲了等于没讲

### Scenario: 检索结果正确
- Given 用户发起检索
- When  调用 /api/kb/search
- Then  返回正确的检索结果             ← 不可判

$ git log --oneline -2
7c2e4f3 实现按班级过滤检索             ← 实现在前
b41d90a 补规约                         ← 规约在后