# 《人工智能基础》AI 备课工作台 — 详细设计说明书 v0.2

| 项目 | 内容 |
|---|---|
| 版本 | v0.2（按《v0.2修订执行计划》P0 修订稿） |
| 日期 | 2026-08-21 |
| 状态 | 已吸收四份专家审查意见（68 条裁决）与 Grok 复审意见；待 P1 表结构落地 |
| 配套文档 | 《修改说明文档.md》（裁决依据）·《v0.2修订执行计划.md》（执行依据）·《v0.2样例JSON.md》（第七章样例与问卷蓝图样例） |

---

## 目录

1. [项目概述](#1-项目概述)
2. [需求规格](#2-需求规格)
3. [系统架构](#3-系统架构)
4. [数据模型设计](#4-数据模型设计)
5. [核心流程设计](#5-核心流程设计)
6. [AI 生成引擎设计](#6-ai-生成引擎设计)
7. [导出设计](#7-导出设计)
8. [界面与交互设计](#8-界面与交互设计)
9. [API 设计](#9-api-设计)
10. [开发计划](#10-开发计划)
11. [部署与运维](#11-部署与运维)
12. [风险与开放问题](#12-风险与开放问题)

---

## 1. 项目概述

### 1.1 背景与问题

《人工智能基础》是面向全校所有专业的通识课程，教学中存在两个核心矛盾：

1. **内容深度与学生背景的矛盾**：讲深（神经网络、Python）非计算机专业学生学不动、不愿学；讲浅学生觉得无含金量、无必要学。解法是**因班施教**——针对不同专业班级设计不同深度、不同案例的教学内容。
2. **教材迭代跟不上 AI 发展**：自制教材出版周期长（2 年一大改），而 AI 领域迭代以季度计。需要**活页式教材机制**（知识补丁）随时为课程打补丁。

### 1.2 目标与定位

**定位**：面向教师的备课辅助平台（**非学习平台**，在线教学仍使用学习通），将"一门通用课程"快速转化为"某个专业班级的个性化教学包"。

**第一约束（v0.2 明确）**：生成的第一约束是 **AI 素养**（理解、使用、评价、与 AI 共处、伦理与治理）在本专业情境中的可观察表现，**而不是把计算机专业目录按深浅裁剪**。因班施教 = **班级分布 × 素养目标 × 专业模板规则**（含不讲清单与课型），不是"换案例 + 降难度"。

**两大能力**：
- **备课生成**：班级画像分布 × 素养目标 × 知识点 × 专业模板 → 教案 / PPT / 案例 / 习题 / 大纲（两段式：课程设计 → 课时开发）
- **内容更新**：热点案例采集、知识补丁与思政融合，为教材持续打补丁

### 1.3 用户与规模

- 教师用户 ≤ 10 人，使用相同教材与教学大纲
- 公共课程层（教材、大纲、知识点体系、公共案例库）多人共建；**公共案例可浏览、可引用（复制并记来源 source_case_id），不可直接改公共库；写入公共库须 admin 或投稿审核**
- 教师个人层（班级画像、定制案例、备课记录）各自私有
- 首批深度打磨模板：**法学类**，架构上可扩展其他大类
- 当前版本单课程《人工智能基础》，模型保留 course 字段

### 1.4 术语表（v0.2 扩充）

| 术语 | 含义 |
|---|---|
| 建设性对齐 | 学习目标、教学活动、评估证据三者显式挂接（objective_ids），任何一方不可脱离目标 |
| 素养地图 | 五维素养框架：概念理解 / 应用与人机协作 / 批判评价 / 伦理与治理 / 专业情境迁移（维不可缺，名称可微调） |
| content_depth | 内容技术深度（原"深度档位"改名）：popular / applied / technical；**不等于教学目标** |
| cognitive_level | 认知层级（布鲁姆）：记忆/理解/应用/分析/评价/创造，每知识点可配 bloom_range |
| 闭集引用 | 引用只能来自白名单来源类型 + source_id；模型禁止自拟文献名与 URL |
| claim_unverified | 无法对应闭集来源的事实主张标记；确认清单必勾"已核验或已删除" |
| 认知负荷自检 | 生成产物的信息密度/术语密集度/先修需求自检输出 |
| 学习通交换物 | 平台导出、由教师导入学习通的产物：课件包 / 活动清单 / 题库文件 |
| generation_meta | 生成元数据：模型、时间、确认人；导出强制附"AI 辅助生成，经××教师确认"标识 |
| 核心/支架/拓展 | 班内分层三路径：核心（全体达成）、支架（困难学生的支撑）、拓展（学有余力的深化） |
| 课型 lesson_type | 讲授 / 案例讨论 / 辩论 / 模拟法庭 / 项目等，决定时间轴结构与 PPT 版式 |
| 知识补丁 | knowledge_patches：对知识点的概念更新/风险提示/案例替换/废弃标记 |
| adaptation_log | 生成决策日志：输入证据 → 设计决策，确认页只读展示，使画像影响可解释 |
| 六条质量标准 | "好教案"六条（见 5.6），模型生成与教师确认共用 |
| 主案例 | 每课时先选的、带决策困境与 teaching_note 的核心案例（AI 推荐 3 选 1） |
| 学情画像 | 班级分布（非单值概括），含"待验证假设"标注，教师确认后才被备课引用 |

---

## 2. 需求规格

### 2.1 功能需求

#### F1 用户系统
- F1.1 教师账号注册/登录（用户名+密码，≤10 用户）
- F1.2 角色：admin（管理知识库/模板/公共库发布）、teacher（备课/投稿）
- F1.3 公共层共享（浏览/引用），个人层数据隔离；**不新增独立 contributor 角色**（teacher 提交 + admin 发布）

#### F2 课程知识库
- F2.1 三级结构化目标：课程目标 `course_outcomes`（编码/表述/素养维/core）→ 章目标 → 课时目标（id/text/type/bloom/success_criteria/course_outcome_ids），**禁止纯自由文本作为唯一目标存储**
- F2.2 素养地图五维（见术语表），进入生成提示词硬上下文
- F2.3 知识点必含可教字段：description（可教最小完整度）、content_depth 基准、bloom_range、misconceptions[]（典型表述+冲突策略）、prerequisites[]；**空/过短 description 拒生成**
- F2.4 思政元素库：按价值主题（公平/责任/安全/创新/理性/法治）组织，含 natural_example / forbidden_example
- F2.5 案例库：案例教学结构（case_type/dilemma/stakeholders/teaching_note/time_needed/literacy_focus）；案例—知识点、案例—模板用**关联表**（JSON 不承担参照完整性）
- F2.6 多种录入方式：手工输入、文件导入（Word/Markdown 大纲解析）、**AI 辅助提取（只送切片/圈选段落，提取必入审核工作台，禁止提取即入库）**、批量模板导入

#### F3 专业模板
- F3.1 模板字段：default content_depth、literacy_focus[]、omit_items[]（不讲清单）、permitted_tools[]、expected_student_performance、preferred_lesson_types、pedagogy_preferences（法学默认：案例讨论/辩论/模拟法庭）、media_strategy（popular=类比单图；applied=决策树/案例；technical=切块流程，禁单页堆算法）、default_ppt_theme（**仅皮肤，不作为主差异化**）
- F3.2 模板-知识点规则（template_rules）承载上学期法学班实战经验（"何处过深、何例有效"），作为可执行 PCK 而非备注

#### F4 班级管理
- F4.1 班级 CRUD：名称、专业、年级、人数；可选 chaoxing_course_id / chaoxing_class_id（仅命名用）
- F4.2 学情画像：**输出分布**（数学/编程/AI 经验/伦理兴趣等人数或比例）、spread_notes、grouping_suggestion，**禁止单值概括全班**；表述用支架语言，禁止贬义定性；标注"基于问卷的待验证假设，需首月课堂观察修正"；预留第 4–5 周修订入口
- F4.3 班级套用专业模板
- F4.4 学情问卷：见 F9

#### F5 热点采集与审核
- F5.1 手动粘贴：AI 提炼事件要素（时间/主体/经过/争议点）——**知识点优先原则：先定知识点目标，再找匹配案例；弱匹配默认不推荐进备课**
- F5.2 时间窗设定（如"最近 30 天"）
- F5.3 三维匹配：知识点（含"是否暴露现有知识点过时"→建议知识补丁）、专业模板、思政角度（**低置信度默认不写入教案，不可硬配**）
- F5.4 案例卡审核工作台：采纳 / 修改 / 驳回；采纳后转述提炼入案例库；审核含合规表（导向/敏感个案/刻板印象/是否适合本班/是否需匿名化）
- F5.5 **经典案例与热点双轨**：时间窗不是案例库唯一来源；经典案例（算法歧视、生成内容责任、人脸识别等）预置
- F5.6 RSS 订阅（阶段 2）：不得替代知识点优先原则
- F5.7 hotspots.raw_text 改为短摘录上限（500–800 字）+ 链接，入库后可删原文

#### F6 分步生成引擎（两段式 + 按课时确认）
- F6.1 **课程设计段**（班级粒度）：画像确认 → 本班课程目标与考核方案 → 周进度草稿（`course_outlines` 可课前 confirmed）
- F6.2 **课时开发段**：本课目标确认（从课程目标分解，3–5 条）→ 评价任务草案 → **主案例选择（AI 推荐 3 选 1，无主案例不得生成案例型教案）** → 教案 → PPT → 案例与习题
- F6.3 每步生成后人工确认，可修改、可**按失败条目**重新生成；**无 objectives[] 不得确认**
- F6.4 生成自动融入：班级画像分布、素养目标、专业模板、思政元素（争议绑定）、案例库、**已确认本班大纲/目标、未过期知识补丁、教师历史改动、最小反馈、错误清单**
- F6.5 来源引用：**闭集**（见 5.4）
- F6.6 平行班复制：从班级 A 复制骨架到 B，默认只重生案例、习题、relevance_to_major

#### F7 导出中心
- F7.1 Word：教案（课前—课中—课后结构）、案例与习题（**教师版/学生版分套**）、课程大纲与进度表；**导出强制 AI 标识**（模型/时间/确认人）
- F7.2 PPT：直接生成 .pptx；slide_type 版式类型 + 页级硬约束 + diagram_spec 可渲染
- F7.3 学习通交换物：题库导入文件（Excel）、活动清单、课件包（见 F10）
- F7.4 下载记录管理

#### F8 课后反馈
- F8.1 **阶段 1 最小集**：四字段（目标达成 高/中/低、难度、案例是否引发讨论、下节建议），写入后注入同班后续生成
- F8.2 阶段 3 完整模块：班内两端反应、匿名学生证据、学期教学改进报告；**禁止长期只有 1–5 分开放文本**

#### F9 学情问卷
- F9.1 **蓝图约束**：AI 仅依据固化蓝图生成表述，**禁止自由增构念、禁止删必测模块**；必测模块：A 迷思概念情景判断 / B 工具使用经验 / C 行为化描述的量化与编程准备度 / D 专业先行 / E 态度（兴趣、焦虑、伦理、讨论接受度）/ F 开放期望；15–20 分钟内可作答
- F9.2 发布：匿名链接/二维码，**可选手填学号**（独立列，自报未核验，仅教师可见，见 5.5）；token 限期/限次；作答页首屏隐私说明（目的/匿名/学号自愿/不用于成绩/不用于模型训练）
- F9.3 作答收集：回收进度；样本量/完成率展示；**完成率过低只出"供参考"报告，不自动改深度档位**
- F9.4 画像分析：AI 出分布 + 理由，**教师确认后才写回 profile**（不覆盖教师手工层）；问卷不声称测能力
- F9.5 **第一课是教学包**：问卷 15–20 分钟 + 迷思小案例 + 素养目标解说 + 本班差异化说明；禁止把开学第一课等同于"发问卷"

#### F10 学习通交接（新增）
- F10.1 **集成边界**：本平台负责"生成与导出"，学习通负责"发布与回收"；**不承诺 API 一键同步与成绩回传**（阶段 2 仅做可行性评估）
- F10.2 三类交换物：（1）课件包（目录对齐章节—课时）；（2）每课时学习通活动清单（讨论/作业/测验/资料）；（3）题库导入文件（Excel 或平台公布模板 + 列映射说明）
- F10.3 课时完成后"去学习通五步"（对章节/传课件/发讨论/发作业/发测验）可勾选记录

### 2.2 非功能需求

| 类别 | 要求 |
|---|---|
| 性能 | ≤10 用户，常规操作 < 1s；AI 生成单步异步任务 + 进度提示 |
| 安全 | 密码哈希；教师数据按用户隔离；API Key 仅存服务端；**上线安全基线**：HTTPS 或 cookie secure 前提、token 熵/过期/限次、管理操作审计（谁确认思政/谁采纳热点）、备份访问控制 |
| 合规 | 热点转述提炼不转载；**生成内容与学生作答不得用于第三方模型训练**；**导出强制 AI 标识**；教材/热点默认不出全文（切片）；学号属个人信息，保留期/删除/导出明确 |
| 成本 | 生成结果持久化（确认后不重复调用）；**成本叙述以教师时间为准**（重生成提示、每课次数统计、平行班复制节省时间） |
| 可维护 | 知识点体系与模板分离；**配置项可调**（学时长度/导出栏目/文件命名，见 11.2），外部信息不阻塞开工 |
| 可访问 | PPT 正文 ≥20pt、高对比默认主题、不用唯色彩编码（WCAG 底线） |

---

## 3. 系统架构

### 3.1 技术选型（保持不变）

Next.js 14（App Router）+ TypeScript · SQLite（Prisma）· DeepSeek API（JSON 结构化输出）· pptxgenjs · docx · rss-parser（阶段 2）· Tailwind + shadcn/ui · 单机 Linux 部署（systemd/PM2，Docker 可选）

### 3.2 总体架构

同 v0.1：Web 前端 → Next.js API 路由（认证/业务/生成任务队列）→ SQLite + DeepSeek API + 文件存储。`generation_tasks.type` 扩充：lesson_plan / ppt / materials / outline / **questionnaire / profile_report / knowledge_extract**。

### 3.3 项目目录结构（更新）

```
ai-lesson-prep/
├── prisma/                  # 数据模型与迁移（v0.2 全表）
├── seed/                    # 第七章种子、法学模板、问卷蓝图、第一课包
├── src/
│   ├── app/
│   │   ├── (auth)/login/
│   │   ├── dashboard/       # 工作台（质量视图：完成率/重生成次数/待审/修改率）
│   │   ├── classes/         # 班级管理（画像分布/修订入口）
│   │   ├── prepare/         # 备课向导（课程设计段 + 课时开发段 + 主案例步）
│   │   ├── questionnaires/  # 问卷管理（蓝图/发布/统计/校准）
│   │   ├── q/               # 学生作答页（公开，限次/过期）
│   │   ├── hotspots/        # 热点工作台（阶段 2）
│   │   ├── cases/           # 案例库（浏览/引用记来源/投稿）
│   │   ├── knowledge/       # 知识库管理（目标/误解/先修/提取审核）
│   │   ├── templates/       # 模板管理（PCK 全字段）
│   │   ├── patches/         # 知识补丁
│   │   ├── exports/         # 导出中心（含学习通交换物）
│   │   └── api/
│   ├── lib/
│   │   ├── ai/              # 客户端 + 提示词 + Schema + 自检 + 错误清单
│   │   ├── exporters/       # pptxgenjs / docx / 交换物
│   │   ├── config/          # sys_config 读取（只读）
│   │   └── db.ts
│   └── components/
└── docs/                    # 设计文档与样例
```

---

## 4. 数据模型设计

### 4.1 实体关系总览（v0.2 新增/调整以 ★ 标注）

```
User 1──N ClassGroup N──1 MajorTemplate
Course 1──N Chapter 1──N Lesson 1──N KnowledgePoint
★CourseOutcome（课程目标）1──N 章/课时目标（挂 course_outcome_ids）
★KnowledgePrereq（先修关联表）
KnowledgePoint N──N SizhengElement（★含 role: content|infusion）
MajorTemplate 1──N TemplateRule（★PCK 全字段）
ClassGroup 1──N LessonPlan N──1 Lesson（★七态状态机 + 草稿分存）
LessonPlan 1──N Export
Hotspot 1──0..1 Case（来源；★raw_text 短摘录）
★CaseKnowledgePoint / CaseTemplate（关联表，替代 JSON）
★KnowledgePatch（知识补丁）
★SysConfig / UserExportPrefs（配置表）
ClassGroup 1──N Feedback（★最小四字段）
★QuestionnaireResponses.student_no（可选学号独立列）
GenerationTask（贯穿所有生成，★类型扩充）
RssSource（阶段 2）
```

### 4.2 数据表详细设计（v0.2 关键变更）

#### courses / chapters / lessons
- 不变；`lessons.objectives` 改为结构化（目标 id 列表或子表），禁止纯自由文本作为唯一目标。

#### ★course_outcomes（课程目标，新增）
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER PK | |
| course_id | FK | |
| code | TEXT | 目标编码（如 O1-1） |
| text | TEXT | 目标表述 |
| literacy_dim | TEXT | 素养维（五维之一） |
| is_core | BOOLEAN | core 不可删，optional 可调 |

#### knowledge_points（知识点，v0.2）
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER PK | |
| lesson_id | FK | |
| title | TEXT | |
| description | TEXT | 可教最小完整度；**空/过短拒生成** |
| content_depth | TEXT | 原 base_depth 改名：popular/applied/technical |
| bloom_range | TEXT(JSON) | 认知层级范围（如 ["理解","评价"]） |
| misconceptions | TEXT(JSON) | 常见误解：[{statement, conflict_strategy}] |

#### ★knowledge_prereq（先修关联，新增）
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER PK | |
| from_kp_id | FK | 前置知识点 |
| to_kp_id | FK | 后置知识点 |

#### sizheng_elements / knowledge_point_sizheng（v0.2）
- sizheng_elements 增加：theme（价值主题）、natural_example、forbidden_example
- knowledge_point_sizheng 增加：role（'content' 可考知识点 / 'infusion' 价值融入）、suggestion

#### major_templates / template_rules（v0.2）
- major_templates：`default_depth` 改名 `default_content_depth`；增加 default_ppt_theme（仅皮肤）
- template_rules（PCK 全字段）：literacy_focus[]、omit_items[]、permitted_tools[]、expected_student_performance、preferred_lesson_type、media_strategy

#### classes（v0.2）
| 字段 | 类型 | 说明 |
|---|---|---|
| profile | TEXT(JSON) | 版本化分布结构：`{version, source, created_at, metrics:{...分布}, spread_notes, grouping_suggestion, teacher_notes, verified_at}`；问卷重分析生成新版本，**不覆盖教师手工层** |
| chaoxing_course_id / chaoxing_class_id | TEXT NULL | 可选，仅命名/交换物用 |
| profile_revision_log | TEXT(JSON) | 学情修订记录 |

#### questionnaires / questionnaire_responses（v0.2）
- questionnaires.questions 每题含：module_id（∈ A–F）、profile_field、blueprint_locked；status 与 token 增加 expires_at、max_submissions
- ★questionnaire_responses.student_no：可空字符串**独立列**（非 questions[] 题目）；分析构造函数禁止读取该列

#### hotspots（v0.2）
- raw_text 短摘录上限（500–800 字）；analysis 增加：sizheng_confidence、suggest_patch、compliance_check

#### cases（v0.2）
- 增加：case_type（例证/决策困境/伦理两难/失败复盘）、dilemma、stakeholders、teaching_note、time_needed、literacy_focus、source_case_id（引用来源）
- knowledge_point_ids / template_ids 改为**关联表** case_knowledge_points / case_templates

#### ★knowledge_patches（知识补丁，新增）
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER PK | |
| knowledge_point_id | FK | |
| patch_type | TEXT | concept_update / risk_alert / example_replace / deprecated |
| summary | TEXT | 补丁摘要 |
| valid_from | DATE | |
| status | TEXT | draft / active / archived |
| citations | TEXT(JSON) | 闭集引用 |
| created_by | FK | |

#### lesson_plans（v0.2 核心）
| 字段 | 类型 | 说明 |
|---|---|---|
| status | TEXT | **七态**：not_started → plan_draft → plan_confirmed → ppt_draft → ppt_confirmed → materials_draft → completed |
| draft_content / confirmed_content | TEXT(JSON) | 草稿与定稿分存 |
| teacher_edits_summary | TEXT(JSON) | 改动痕迹 |
| why_changed | TEXT | 改动原因（学情/时间/准确性/价值） |
| adaptation_log | TEXT(JSON) | 生成决策日志（证据→决策），确认页只读 |
| generation_meta | TEXT(JSON) | 模型/时间/确认人（导出 AI 标识数据源） |

#### course_outlines（v0.2）
- 语义改为"本班课程设计对象"：version、confirmed_at、assessment_plan 结构化（形成性/终结性节点与权重提示）；**允许课前 confirmed**；课时完成后反写周进度

#### feedbacks（v0.2 最小集）
- 四字段：goal_achievement（高/中/低）、difficulty、case_sparked_discussion、next_lesson_suggestion；effect_rating 保留但非唯一信号；预留学习通汇总指标粘贴字段（阶段 1 不自动采集）

#### ★sys_config / user_export_prefs（配置表，新增）
- sys_config：key/value（LESSON_MINUTES、export_columns JSON、file_naming_pattern）；`.env` 为初值，表覆盖之
- user_export_prefs：教师个人导出偏好（栏目顺序/标题）

#### generation_tasks（v0.2）
- type 扩充：lesson_plan / ppt / materials / outline / questionnaire / profile_report / knowledge_extract / hotspot_analyze

### 4.3 种子数据规划（按执行计划调整三范围）

| 种子 | 内容 |
|---|---|
| 第七章 NLP | **完整实例**：课时目标（bloom 标注）、素养要点、omit 清单、误解与冲突策略、先修、主案例（流浪狗舆情：争议结构 + teaching_note + 法律争议视角）、经典案例位 |
| 第 0/1 课 | 第一课教学包（问卷 + 迷思小案例 + 素养解说 + 差异化说明） |
| 法学模板 | template_rules 完整实例（上学期 3 个法学班经验："何处过深、何例有效"） |
| 问卷蓝图 | 必测模块 A–F 题目样例（见《v0.2样例JSON.md》） |
| 经典案例 | 算法歧视、生成内容责任、人脸识别等（预置位） |
| 其他章 | 标题 + 占位 description，**走拒生成**（"全部章可教最小完整度"为阶段 2 录入工作） |
| 演示班级 | 分布画像示例（非单值） |

---

## 5. 核心流程设计

### 5.1 两段式工作流（v0.2 重画）

```
【课程设计段】班级粒度
选班 → 确认模板与 content_depth 意向 → 引用已校准画像（可先手填，问卷后回写）
    → 生成并确认本班课程目标（course_outcomes）与考核方案
    → 生成并确认周进度草稿（course_outlines 可课前 confirmed）
        │
【课时开发段】课时粒度（七态状态机）
        ▼
课时目标确认（从课程目标分解，3–5 条，无 objectives[] 不得确认）
    → 评价任务草案 → 主案例选择（AI 推荐 3 选 1，无主案例不得生成案例型教案）
    → 生成教案（plan_draft）→ 确认（plan_confirmed）
    → 并行生成 PPT 草稿（ppt_draft）与材料草稿（materials_draft，含习题/真实性任务）
    → 分别确认（ppt_confirmed / materials_draft → completed）
        │
全部课时完成后 → 周进度反写微调 → 定稿导出（大纲不得作为首次设计时机）
```

**关键规则**：
- 状态机：not_started → plan_draft → plan_confirmed → ppt_draft → ppt_confirmed → materials_draft → completed
- 每一步确认前可**按失败条目**重新生成（六条标准勾选失败项作为修订指令）
- 修改教案后，PPT/材料提示"基于修改后内容重新生成"
- 生成请求入 `generation_tasks` 异步执行，前端轮询
- **学时校验**：确认前 `sum(timeline.duration) ≤ lessons.hours × LESSON_MINUTES（可配置）`，超载标红；讨论课主问题 2–4 个
- **平行班复制**：从班级 A 复制骨架到 B，默认只重生案例、习题、relevance_to_major

### 5.2 热点采集与审核流程

```
[手动粘贴 链接/文本] 或 [RSS 抓取（阶段 2）]
        ▼
AI 分析（时间窗约束）
  1. 提取事件要素（短摘录上限）
  2. 知识点匹配：**先定目标再找案例，弱匹配不进备课建议**
  3. 检测"是否暴露现有知识点过时" → 建议知识补丁分支
  4. 专业模板匹配 + 思政角度匹配（低置信度不写入教案，不可硬配）
  5. 生成建议讨论问题 + 合规表（导向/敏感个案/刻板印象/适合本班/匿名化）
        ▼
案例卡（status=pending）→ 审核工作台：采纳（转述入案例库）/ 修改 / 驳回
```

**经典案例与热点双轨**：经典案例（算法歧视、生成内容责任、人脸识别等）预置在案例库，不依赖时间窗；热点只做补丁。

### 5.3 思政融合机制（v0.2）

- **预置层**：知识点↔思政元素关联（含 role：content 可考 / infusion 价值融入）+ 价值主题库（natural/forbidden 示例）
- **自动层**：生成时输出 `sizheng_integration` **数组**，每条含：organic_link（自然关联）、student_dilemma（学生必须表态的争议）、position、avoid_preaching；**思政点必须锚定案例争议/学生困境，禁止独立说教**
- **审核层**：确认清单检查"至少一处争议绑定本课目标/案例"；**取消"思政环节是否齐全"作为过关条件**（原栏目降为教师备注）
- **兜底层**：热点三维匹配不可硬配；思政小结页（PPT）改为可选

### 5.4 来源引用机制（闭集）

- `citations[]` 仅允许 source_type ∈ {knowledge_point, case, hotspot, teacher_url, textbook_section} + source_id
- 无法对应的主张：`claim_unverified: true`，确认清单必勾"已核验或已删除"
- **禁止模型自拟文献名与 URL**
- 导出文档引用以文末"参考来源"呈现，未核验项突出显示
- 抽检已确认教案的引用编造率作为验收项；超阈值不得宣称"来源引用"能力

### 5.5 学情画像问卷流程（v0.2）

```
第一课教学包（问卷 15–20 分钟 + 迷思小案例 + 素养解说 + 差异化说明）
    → AI 依蓝图生成问卷草稿（必测模块 A–F 锁定，不可删）
    → 教师编题（显示题—画像字段映射）→ 发布（隐私首屏；学号选填独立列）
    → 收集（token 限期/限次；样本量/完成率展示）
    → AI 出分布报告（深度只给理由；低完成率只出"供参考"）
    → 教师确认 → 写回 profile（新版本，不覆盖教师手工层）
```

**可选学号处理**：
- 独立列 `questionnaire_responses.student_no`（可空），**不作为问卷题目**（避免 AI 改蓝图时动学号题），作答页末展示独立选填框
- 学号**自报、未核验**，不作为成绩/考勤依据；仅教师本人（owner）在班级详情可见
- **学号不进分析/生成 prompt**（构造函数禁止读取该列 + 断言测试）
- 阶段 1 只允许教师查看某生**本次作答原文**；"开学 vs 期中个体对比"推迟阶段 3
- 隐私：保留期、教师删除作答、备份访问控制并入安全基线

### 5.6 确认清单（六条质量标准，v0.2 新增）

模型生成与教师确认共用量规，确认页逐条展示：

1. **目标可观察**：有素养维、有成功标准，3–5 条
2. **针对画像分布**：有核心/支架/拓展
3. **主案例有困境**：讨论含评价/决策层（案例型课必检）
4. **价值引领嵌在争议中**：非独立说教
5. **评估能提供目标证据**：至少一项评估挂 objective_ids
6. **事实性主张有闭集来源** 或已标 claim_unverified

确认前同时展示：adaptation_log（只读）、班内差异提示卡、学时比对、未核验引用列表。

---

## 6. AI 生成引擎设计

### 6.1 接入与封装

- 统一客户端：chat completion + JSON 输出（response_format json_object）
- 配置：DEEPSEEK_API_KEY / BASE_URL / MODEL（默认 deepseek-chat）
- 错误处理：超时重试 1 次；JSON 解析失败重试 1 次；**Schema 校验失败重试或标红**；最终失败记录 generation_tasks.error
- **生成后自检步骤**：目标—活动—评价对齐、与知识库冲突检测、未核验主张列表
- **易错字段 ⚠ 标记**：模型名、日期、法规条款、数据指标自动标记"需人工核验"
- **已知错误清单**：教师纠正的错误入库，后续提示词携带（错误记忆）
- **出域最小化**：教材提取只送切片/圈选；问卷分析送聚合统计+必要文本，禁止整表出域
- 流式输出可选（MVP 非流式 + 任务轮询）

### 6.2 提示词策略（v0.2）

**系统提示词构成**（组装顺序）：
1. 角色设定：资深高校 AI 通识课备课专家
2. **素养地图 + 六条质量标准（硬约束，先于知识库上下文）**
3. 课程知识库上下文（相关目标/知识点，含 misconceptions/先修）
4. 班级画像分布 + 模板规则（含 omit_items/课型偏好）
5. 思政元素库（相关主题 + natural/forbidden 示例）
6. 上下文清单（M6.7）：已确认本班大纲与目标 / 主案例 teaching_note / 未过期知识补丁 / 教师历史改动 / 最小反馈 / 错误清单
7. 输出要求：JSON Schema + 闭集引用约束 + cognitive_level 约束

**硬约束**（先于文采与温度）：
- 禁止把非计算机专业课备成简化专业课
- 目标 3–5 条且可观察；活动/习题必须挂目标 id
- 价值引领嵌在争议中
- 闭集引用；结构校验优先于温度

**上下文传递链**：
- 教案生成：目标 + 画像分布 + 主案例 + 思政 + 补丁 + 反馈 + 错误清单
- PPT 生成：**已确认教案**（A6 产物 Schema 冻结后）
- 材料生成：已确认教案 + 案例库（task_type/rubric/tier 生成）
- 大纲：已确认的本班课程设计对象（反写微调，非首次生成）
- 问卷生成：**仅蓝图 + 专业情境**（不得用"将要实施的深度档位"当输入循环证实）

**温度策略**：教案 0.4 · PPT 0.5 · 案例创意 0.7 · 习题 0.5 · 热点分析 0.3 · 问卷 0.4 · 画像 0.3

### 6.3 产物 JSON Schema v0.2

> 完整字段以《v0.2样例JSON.md》第七章样例为准；此处列结构要点。

**教案（lesson_plan）**：
```json
{
  "lesson_title": "", "lesson_type": "案例讨论",
  "class_profile_summary": "对画像分布的适配说明",
  "objectives": [{"id": "o1", "text": "", "bloom": "评价", "literacy_dim": "", "success_criteria": "", "course_outcome_ids": []}],
  "core_plan": {"core": "", "scaffold": "", "extension": ""},
  "lesson_events": [{"phase": "pre|in|post", "duration": "10min", "teacher_move": "", "student_task": "", "interaction": "", "prompt_questions": []}],
  "hook": "", "relevance_to_major": "本知识点与法学专业的关系（必出）",
  "formative_checks": [""],
  "sizheng_integration": [{"element": "", "role": "infusion", "organic_link": "", "student_dilemma": "", "position": "", "avoid_preaching": true}],
  "case_plan": {"case_id": "", "usage": "", "discussion_ladder": ["事实层", "分析层", "评价层", "创造层"]},
  "timeline_check": {"total_minutes": 90, "lesson_minutes": 90},
  "citations": [{"source_type": "case|knowledge_point|hotspot|teacher_url|textbook_section", "source_id": "", "claim_unverified": false}],
  "difficulty_notes": "",
  "adaptation_log": [{"evidence": "", "decision": ""}]
}
```

**PPT（slides）**：
```json
{
  "theme": "简约学术", "slide_type": "case_discussion",
  "slides": [
    {"slide_type": "cover|agenda|concept|diagram|case|compare|quiz|sizheng|summary|activity",
     "title": "", "bullets": [], "visual": "", "diagram_spec": {"kind": "flow|compare|pros_cons", "nodes": []},
     "speaker_notes": "讲稿只进这里", "highlight": "", "takeaway": ""}
  ]
}
```

**材料（materials）**：
```json
{
  "cases": [{"case_id": "", "summary": "", "discussion_questions": [], "sizheng_angle": "", "citations": []}],
  "exercises": [
    {"task_type": "recall|explain|case_ruling|classroom_speech|authentic_task",
     "question": "", "options": [], "answer": "", "rubric": [{"criterion": "", "level": ""}],
     "tier": "required|optional|extension", "objective_ids": [], "difficulty": "easy|medium|hard",
     "knowledge_point": ""}
  ]
}
```

**课程设计对象（outline）**：course_title / total_hours / assessment_plan（形成性+终结性节点与权重提示）/ weekly_schedule[{week, topic, hours, key_points, assessment}] / version / confirmed_at

**学情问卷（questionnaire）**：title / description / module_ids（A–F 锁定）/ questions[{id, module_id, profile_field, blueprint_locked, type, question, options, required}]

**学情画像报告（profile_report）**：summary / metrics（分布，含样本量/完成率）/ misconceptions_top / teaching_risks / core_extension_suggestion / depth_recommendation（只给理由）

### 6.4 成本与缓存

- 生成结果确认后写入 lesson_plans，**重新生成才重新调用 API**
- 热点分析缓存于 hotspots.analysis；画像分析缓存于 profile 版本
- **成本以教师时间为准**：界面提示重生成消耗、统计每课重生成次数、验收看"打开向导到可上课导出"时间与平行班复制节省时间

---

## 7. 导出设计

### 7.1 Word 文档规范（docx 库）

| 文档 | 结构 |
|---|---|
| 教案 | 标题页（课程/班级/课时/教师/日期 + **AI 标识与确认人** + 相对教材补丁摘要）→ 本课目标与成功标准 → **目标—活动—评价对照表** → 课前任务 → 课中过程（活动时间轴、核心/支架/拓展）→ **价值争议点**（非独立思政空壳；原栏目可作教师备注）→ 课后任务 → 案例与讨论（教学说明要点）→ 板书/资源 → 闭集参考来源 |
| 案例与习题 | **教师版**（答案/评分要点/rubric）/ **学生版**（隐藏答案）；题型含真实性任务 |
| 课程大纲 | 课程信息 → 总学时 → 周进度表（表格）→ 考核方案 |

### 7.2 PPT 生成规范（pptxgenjs）

- 页结构随课型变化：封面 → 目录 → 内容（slide_type 化）→ 案例（争议页）→ 评价 → 尾页；**讨论课必须有争议页与记录页，禁止 30 页要点清单**
- **页级硬约束**：内容页要点 ≤5、单条 ≤20 字；讲稿只进 speaker_notes；一页一信号；图文同页；装饰不挤占内容区；**校验失败重试或标红，不得直接待确认**
- diagram_spec 由导出层渲染为形状（流程/对比/利弊表），**阶段 1 不接外部图库**
- 四套视觉风格（简约学术/图文并茂/数据可视化/案例叙事）**仅皮肤**，不替代版式类型；深度档位映射媒体策略（M4.3）
- 无障碍底线：正文 ≥20pt、高对比、不用唯色彩编码；diagram 的 alt/讲稿描述随 speaker_notes
- 文件命名：`{课程}-{班级}-{课时}.pptx`（pattern 可配置）
- 验收：任课教师"不改结构能否上课"评分；不达标产品文案只能称"幻灯片草稿"

### 7.3 学习通交换物（F10）

- 题库导入文件：Excel（题干/选项/答案/难度/知识点列）+ 一页导入说明（列映射）；学校官方模板为阶段 2
- 每课时活动清单：讨论/作业/测验/资料，与章节—课时目录对齐
- 课件包命名：读 classes.chaoxing_* 字段（禁止硬编码）
- "去学习通五步"勾选记录

### 7.4 导出配置

- LESSON_MINUTES（默认 45）、export_columns（栏目 JSON）、file_naming_pattern 均来自 sys_config（.env 为初值）；教师个人导出偏好存 user_export_prefs

---

## 8. 界面与交互设计

### 8.1 页面清单

| 页面 | 路径 | 说明 |
|---|---|---|
| 登录 | /login | |
| 工作台 | /dashboard | 班级进度 + **质量视图**（完成率/重生成次数/待审/近两周修改率）+ 连续零修改温和提示 |
| 班级详情 | /classes/[id] | 画像分布编辑/校准/修订入口；课时进度（七态徽章）；学号归集（owner） |
| 备课向导 | /prepare/[classId] | **课程设计段首步** + 课时开发段（见 8.2） |
| 教案查看/编辑 | /prepare/.../lesson/[lessonId] | 结构化表单 + **近成品文本双模式** |
| PPT 预览 | 同上 | 左侧缩略图 + 右侧大图 |
| 问卷管理 | /classes/[id]/questionnaires | 蓝图生成（锁定模块）、发布、回收、校准分步 |
| 学生作答页 | /q/[token] | 匿名公开、移动端友好、token 限期/限次、隐私首屏、学号选填框 |
| 问卷统计与画像 | /questionnaires/[id] | 样本量/完成率/分布优先展示，AI 叙述其后；确认写回分离 |
| 案例库 | /cases | 浏览/引用（记来源）/投稿；知识点/模板筛选 |
| 热点工作台 | /hotspots | 阶段 2：粘贴分析、案例卡审核 |
| 知识库管理 | /knowledge | 章节树 + 目标 + 误解/先修 + 提取审核台 |
| 补丁管理 | /patches | 知识补丁列表/草稿/发布 |
| 模板管理 | /templates | PCK 全字段 |
| 导出中心 | /exports | 文件列表 + 下载 + 学习通交换物 |

### 8.2 备课向导（核心页面）

```
┌────────────┬───────────────────────────────┬─────────────┐
│ 课时列表    │  当前步骤主区                   │ 操作区       │
│ (左侧)     │  课程设计段：目标/考核/周进度    │ [生成]      │
│  ● 1-1 已确认│  课时开发段：目标→主案例→教案   │ [按条目重生成]│
│  ● 1-2 生成中│  - 六条标准逐条展示 [编辑]     │ [确认]      │
│  ○ 1-3 未开始│  - 差异提示卡 / 学时比对       │ [导出]      │
│  ○ 1-4 ...  │  - 未核验引用列表             │             │
└────────────┴───────────────────────────────┴─────────────┘
 步骤指示：本班目标与考核 → 课时目标 → 主案例 → 教案 → PPT → 案例与习题
```

- 课时徽章按七态状态机（灰=未开始、蓝=生成中、黄=草稿待确认、绿=已确认）
- 双模式编辑：结构化表单 + 近成品文本；映射失败标红
- 重新生成可勾选失败条目；"复制到班级 B"（平行班）
- 无 objectives[] 时确认按钮不可用（G1 闸门）
- 完成页"去学习通五步"；预览徽章：AI 草稿 / 已人工修改 / 已确认
- 关键页响应式（工作台/待确认/问卷回收/热点待审）；知识库树/PPT 细调桌面优先
- 一页纸操作说明 + 法学示例包

### 8.3 问卷与画像界面

- 编辑页：题—画像字段映射 + 锁定模块标识（A–F 不可删）
- 统计页：先样本量/完成率/分布，再 AI 叙述；确认画像按钮与"写回备课"分离

---

## 9. API 设计

### 9.1 接口总览（v0.2 更新）

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/auth/login · /logout | |
| GET | /api/me | |
| GET/POST/PUT/DELETE | /api/courses · /api/chapters · /api/lessons · /api/knowledge-points | 知识库 CRUD |
| GET/POST/PUT | /api/course-outcomes | 课程目标 CRUD |
| GET/POST | /api/knowledge-points/:id/prereqs · /api/knowledge-points/:id/misconceptions | 先修/误解 |
| GET/POST | /api/sizheng-elements | |
| GET/POST/PUT/DELETE | /api/templates | PCK 全字段 |
| GET/POST/PUT | /api/classes | 画像分布/校准/修订 |
| POST | /api/classes/:id/copy | 平行班复制 |
| GET | /api/lesson-plans?classId= | 七态状态 |
| POST | /api/lesson-plans/generate | `{class_id, lesson_id, step}` step ∈ {curriculum, objectives, case_select, plan, ppt, materials, outline} |
| PUT | /api/lesson-plans/:id/confirm | `{step, content, failed_items[]?}` |
| POST | /api/lesson-plans/:id/regenerate | `{step, failed_items[]}` 按条目再生成 |
| POST | /api/lesson-plans/:id/export | `{type}` 含 learning_toolkit（交换物） |
| GET | /api/exports | |
| GET | /api/tasks/:id | 轮询 |
| POST | /api/feedbacks | 最小四字段 |
| GET/POST/PUT | /api/patches | 知识补丁 CRUD |
| POST | /api/questionnaires/generate | 蓝图内生成 |
| GET/POST/PUT | /api/questionnaires | 问卷 CRUD |
| POST | /api/questionnaires/:id/publish | 返回链接/token（限次/过期） |
| GET | /api/questionnaires/:id/responses | 统计（含分布/样本量） |
| POST | /api/questionnaires/:id/analyze | 画像分析（**不自动覆盖 profile，需确认**） |
| POST | /api/q/:token | 学生匿名作答（限次/过期；学号独立列） |
| GET/POST | /api/hotspots · /api/hotspots/:id/review | 阶段 2 |
| GET/POST/PUT | /api/cases | 案例库（引用记 source_case_id） |
| GET/POST | /api/rss-sources | 阶段 2 |
| GET | /api/config | sys_config（只读） |
| POST | /api/import/knowledge | 文件导入/AI 提取（入审核台） |

---

## 10. 开发计划

### 10.1 阶段划分

| 阶段 | 内容 | 交付 |
|---|---|---|
| 阶段 1 | **法学班闭环**（P0.5–P10）：骨架、目标体系、第七章可教种子、两段式向导、教案/PPT/材料闭环、问卷闭环、学习通交换物、验收 | 第七章一节真实课时可上课 |
| 阶段 2 | 热点采集（粘贴分析+案例卡审核+时间窗）、RSS、知识补丁队列与过时检测、学校母版、个人数据导出、资源收藏夹 | 热点工作台 |
| 阶段 3 | 完整反馈闭环、学期改进报告、教师备课偏好分析、模板扩展（理工/医学等） | 完整平台 |

### 10.2 执行序列

按《v0.2修订执行计划》P0（文档，1.5 周）→ P0.5（骨架，1 周）→ P1–P10（开发约 18 周兼职，144–216 h）。详细任务、DoD、依赖、验收见执行计划第 3/7 章与附录 A 追溯矩阵。

### 10.3 里程碑（v0.2）

- **M1**：P0 + P0.5（设计书 v0.2 + 可登录空应用）
- **M2**：P1–P2（数据模型 + 第七章可教种子，含可教性验收）
- **M3**：P3–P5（管理页 + AI 客户端 + 课程设计段）
- **M4**：P6–P7（教案/PPT/材料闭环 + 导出）
- **M5**：P8–P10（问卷闭环 + 交换物 + 联调验收：闸门全绿 + 抽检报告）
- 试讲（第七章一节真实法学课时）按教学日历单列，不作为 M5 硬门槛

---

## 11. 部署与运维

### 11.1 部署方案

Linux 单机，Node LTS + Next.js standalone + SQLite 文件 + 上传目录；systemd/PM2 托管；Docker 可选；内网即可，无公网要求。**上线前安全基线**：HTTPS（或明确 cookie secure 前提）、管理操作审计、备份访问权限。

### 11.2 配置管理

- 环境变量：DEEPSEEK_API_KEY / DATABASE_URL / SESSION_SECRET / UPLOAD_DIR / LESSON_MINUTES（初值）
- **sys_config 表**覆盖 .env 初值：LESSON_MINUTES、export_columns、file_naming_pattern；教师个人偏好 user_export_prefs
- **灵活性原则**：学时/导出栏目/命名等外部信息不阻塞开工，默认值可运行，确定后填配置不返工（学校母版/官方题库模板为阶段 2，阶段 1 人工套用兜底）
- API Key 仅存服务端

### 11.3 数据安全与备份

- SQLite 单文件 + 上传目录每日备份
- **数据出域最小化**：与 DeepSeek 的数据处理策略明示；教材/热点原文默认不出全文（切片）；**学生作答禁止用于训练**；问卷 token 熵/过期/限次；学号属个人信息：保留期、教师删除作答、备份访问控制
- 密码 bcrypt；会话 cookie httpOnly + secure
- 教师须知：AI 标识与核验责任

---

## 12. 风险与开放问题

### 12.1 风险与对策（v0.2 扩充）

| 风险 | 对策 |
|---|---|
| 目标与评价脱节 | 目标编码 + G1 闸门 + 六条标准第 5 条 |
| 思政标签化/两张皮 | 数组 + 争议绑定 + 取消"栏目齐全"过关 |
| 通识课被备成专业缩写 | 素养地图硬约束 + omit_items + 核心/支架/拓展 |
| 确认按钮替代专业判断 | 六条清单 + adaptation_log + 差异提示卡 |
| 学情标签自我实现 | 分布画像 + "待验证假设" + 校准分步 + 支架语言 |
| 热点肢解课程 | 知识点优先 + 弱匹配不推荐 + 经典/热点双轨 |
| 闭集引用失效（编造率） | 闭集 + claim_unverified + 抽检 + 文案降级 |
| PPT 外在负荷过高 | 页级硬约束 + 认知负荷自检 + 校验失败标红 |
| 学习通搬运抵消生成收益 | 交换物 + 五步 + 平行班复制；API 不做承诺 |
| API 便宜教师贵 | 成本叙述改教师时间 + 重生成提示 |
| 过度自动化（连续零修改） | 质量视图 + 温和提示核验 |
| 附录样例未齐备就冻 Schema（执行层） | P0 手工样例 JSON 对拍物 |
| 教学日历约束试讲 | 试讲与开发联调解耦 |
| 可选学号个保法泄露面 | 独立列/自报未核验/剥离/保留期与删除 |
| 种子输入延迟 | P2 输入截止日，逾期只做第七章最小实例 |
| 模型 JSON 不稳定 | 锁最小 Schema + 失败可视化 + 分步上自检 |

### 12.2 开放问题（v0.2）

**已关闭**：
- 教师协作机制（第 6 点）：公共案例可浏览/可引用（记 source_case_id），写入公共库须审核 → M2.12 定稿
- 种子范围"待定" → 按执行计划调整三（阶段 1 = 第七章 + 第一课 + 蓝图；其余章阶段 2）
- "三项会上确认才能开工"（学时/格式/学习通规范）→ 改为**配置项**（第 11.2 节），不阻塞开工

**新增待确认**（非阻塞，确认后填配置）：
- 学校若有红头教案格式/Logo 母版 → 阶段 2 接入
- 学习通/校级若有官方问卷与题库导入规范 → 阶段 2 接入
- 学时默认 45 分钟，如学校为 50 分钟改配置即可

**明确不承诺**：学习通 API 一键同步与成绩回传、课中动态画像（签到/投票实时回传）、第三方图库自动配图、教师端生成参数高级模式、LTI/SCORM/xAPI 完整互操作。

---

**文档结束。**
v0.2 按《修改说明文档》59 条修改项与《v0.2修订执行计划》P0 要求修订；第七章样例 JSON 与问卷 A–F 题目样例见《v0.2样例JSON.md》。