P3 知识库/模板/班级管理页 — 验证报告
日期：2026-08-22
目录：/home/zyw/Downloads/ai-lesson-prep
依据：《v0.2修订执行计划》P3 范围/DoD；《设计说明书-v0.2》§2.1 F2/F3/F4、§4.2、§8.1、§9.1
========================================================================
1. 环境
========================================================================
Node：v20.15.1
npm：9.2.0
Prisma：5.22.0
说明：npx/npm 执行前取消 HTTP(S)_PROXY，避免 HttpsProxyAgent 问题。
新增依赖：mammoth（Word .docx → HTML → 大纲 Markdown）
========================================================================
2. Schema（P1 表未改列，仅新增审核台表）
========================================================================
迁移：20260822090000_knowledge_extract_drafts
表：knowledge_extract_drafts（草稿存哪）
source_type / source_name / source_excerpt / batch_id
course_id / lesson_id
title / description / content_depth / bloom_range / misconceptions
status: pending | approved | rejected
knowledge_point_id（通过后回填）
review_note / created_by / reviewed_by / reviewed_at
users / knowledge_points / major_templates / template_rules / classes
等 P1 表结构未改；users 仅增加 Prisma 关系字段（不 ALTER users 列）。
prisma migrate deploy：applied 20260822090000_knowledge_extract_drafts
========================================================================
3. 生产构建（npm run build）
========================================================================
exit 0
Compiled successfully；Linting and checking validity of types 通过；
Generating static pages (28/28) 通过。
新增动态路由（节选）：
/knowledge /templates /classes /classes/[id]
/api/courses /api/chapters /api/lessons /api/knowledge-points
/api/knowledge-points/[id]/prereqs /api/knowledge-points/[id]/misconceptions
/api/course-outcomes /api/knowledge/tree
/api/import/knowledge /api/extract-drafts
/api/templates /api/templates/[id]/rules
/api/classes /api/classes/[id]/verify /api/classes/[id]/revise
tsconfig：补 target=ES2017；exclude seed/scripts（P2 种子类型问题不进入 Next 类型检查，种子文件未改内容）。
========================================================================
4. curl 冒烟（next start :3000，cookie 登录）
========================================================================
登录：POST /api/auth/login {"username":"admin","password":"Admin@123456"}
→ {"ok":true,"user":{"role":"admin",...}}
未登录 GET /knowledge|/templates|/classes → 307 Location=/login
登录后：
GET /knowledge → 200 含「知识库管理」（59877 bytes）
GET /templates → 200 含「模板管理」（87719 bytes）
GET /classes → 200 含「班级管理」（16188 bytes）
GET /classes/2 → 200 种子班「2024级法学1班」
API 抽查：
GET /api/knowledge/tree → course=人工智能基础 chapters=9 kps=17
第七章 3 课时
GET /api/templates → LAW，5 条 template_rules
GET /api/classes → 1 班，verified_at=null（待验证假设）
冒烟写入（提取通过产生 KP、修订 log）已回滚：knowledge_points=17，
extract drafts=0，profile_revision_log 恢复种子 v1，画像 version=1。
========================================================================
5. 拒生成拦截（复用 src/lib/knowledge/teachable.ts）
========================================================================
谓词：shouldRejectGeneration（P2 冻结）
应用层封装：src/lib/knowledge/publish.ts
checkPublishable() 调用同一谓词
用户提示 PUBLISH_BLOCKED_HINT = 「描述过短，未达可教完整度，不可发布」（17 字 ≤40 字）
落点：
POST/PUT /api/knowledge-points
POST /api/extract-drafts/:id action=approve
curl：
PUT /api/knowledge-points/8 description="" → 422 reject=true hint 17 字
PUT /api/knowledge-points/8 description="待录入" → 422 descriptionLength=3
reason 仍为 teachable.ts 完整句（含标题与阈值），error 字段为短提示
审批空描述草稿 → 422，未写入 knowledge_points
合格描述保存/审批通过 → 200
库内第七章知识点未因拦截被改写（422 不落库）。
========================================================================
6. 提取审核台数据形态与审核动作
========================================================================
写入路径：
POST /api/import/knowledge
mode=parse（P3）：Word/Markdown/文本大纲 → knowledge_extract_drafts.status=pending
mode=ai → 501「AI 提取将在 P4 接入，当前请用大纲解析」
禁止提取即入库：import 后 knowledge_points 计数不变（17→17）
草稿字段：见第 2 节。同一次导入共用 batch_id；source_excerpt 上限 800 字。
审核动作：POST /api/extract-drafts/:id { action: "approve" | "reject", lessonId?, reviewNote? }
approve：再跑 teachable 谓词 → 写入 knowledge_points → status=approved 回填 knowledge_point_id
reject ：status=rejected，不入库
curl：解析 1 条 pending（kpId=null）→ 审核通过 kp=18 → 计数 18；
短描述草稿审批 422。随后已删除冒烟知识点，计数回到 17。
大纲解析（src/lib/knowledge/parse-outline.ts）：
Markdown #/## 章课时结构标题跳过，### 或「知识点」行入草稿；
元数据行：深度/布鲁姆/误解/策略。
Word：mammoth.convertToHtml → h1–h3 转 Markdown 再走同一解析器。
========================================================================
7. 三域实现对照 DoD
========================================================================
[x] 知识库：章节→课时→知识点树 CRUD；P2 种子可见可编辑
[x] course_outcomes 增删改、is_core 标记、literacy_dim 五维；core 删除 409
[x] 知识点编辑：content_depth 三档 / bloom_range / misconceptions[] / prerequisites[]（下拉多选）
[x] 空 description 不可发布：保存与审核通过均拦截，提示 ≤40 字
[x] 提取审核台：文件/文本 → 待审核草稿 → 通过才入库；AI 提取 P4 占位
[x] 模板：major_templates CRUD + template_rules 全字段
（literacy_focus[] / omit_items[] / permitted_tools[] /
expected_student_performance / preferred_lesson_type / media_strategy）
[x] 班级 CRUD（专业/年级/人数/套模板）+ chaoxing_course_id / chaoxing_class_id
[x] 学情画像分布表单（metrics 分布、spread_notes、grouping_suggestion、teacher_notes）
[x] 「待验证假设」标注（verified_at 空则展示固定文案）+ 校准入口
[x] 第 4–5 周修订入口：POST /api/classes/:id/revise 追加 profile_revision_log，
teacher_notes 不覆盖
[x] 权限：知识库/模板写操作 admin；班级 teacher 仅自己的、admin 全部
（GET 知识库/模板教师只读，便于套模板）
[x] npm run build 通过；curl 登录后三页 200
========================================================================
8. 权限实现
========================================================================
requireApiUser / requireAdmin / canManageClass（src/lib/api-auth.ts）
- 未登录 API 401、页面 middleware 307 /login
- admin：知识库/模板/课程目标/导入审核 可写
- teacher：上述只读；班级 GET/POST/PUT/DELETE/verify/revise 限 ownerId=自己
种子仅 admin 账号，教师路径用角色字段分支，未新增种子用户。
========================================================================
9. 遗留（不阻塞 P3）
========================================================================
- AI 提取（只送切片/圈选段落）在 P4 接 generation_tasks.type=knowledge_extract；
本阶段 mode=ai 返回 501，审核台与草稿表已就绪。
- 章/课时 objectives[] 结构化编辑未做完整表单（仍存 JSON 列，P2 种子可读）；
本阶段 CRUD 覆盖标题/学时/说明。三级目标第一级 course_outcomes 已管理。
- 班级详情「课时七态徽章 / 学号归集」属后续向导与问卷（P6/P8），本页未做。
- 平行班复制 POST /api/classes/:id/copy 属 P6，未实现。
- Word 解析依赖标题样式（Heading 1–3）；无样式的纯段落 Word 走「空行分块」回退。
- 未种子 teacher 账号；教师只读/班级隔离需用自建 teacher 角色账号验证。
- 工作台质量视图、备课向导仍为后续迭代占位。
========================================================================
10. 结论
========================================================================
P3 DoD 三项满足：三管理域 CRUD 可用；提取走审核台禁止即入库；
画像分布 + 待验证假设 + 第 4–5 周修订入口可用；Word/Markdown 大纲解析最小可用。
拒生成与 P2 共用 teachable.ts，管理保存与审核通过两处落地。