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

| 项目 | 内容 |
|---|---|
| 版本 | v0.1（讨论稿，待评审） |
| 日期 | 2025 |
| 状态 | 需求已收敛，设计待评审 |
| 作者 | 备课平台讨论组 |

---

## 目录

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 目标与定位

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

**两大能力**：
- **备课生成**：班级画像 × 知识点 × 专业模板 → 教案 / PPT / 案例 / 习题 / 大纲
- **内容更新**：热点案例采集与思政融合，为教材持续打补丁

### 1.3 用户与规模

- 教师用户 ≤ 10 人，使用相同教材与教学大纲
- 公共课程层（教材、大纲、知识点体系、公共案例库）多人共建
- 教师个人层（班级画像、定制案例、备课记录）各自私有
- 首批深度打磨模板：**法学类**（上学期已有 3 个法学班实战经验），架构上可扩展其他大类

### 1.4 术语表

| 术语 | 含义 |
|---|---|
| 班级画像 | 某班的专业、年级、人数、学情判断（数学/编程基础、兴趣偏好等） |
| 专业模板 | 某专业大类的备课规则包：默认深度档位、案例偏好、语言风格、思政侧重 |
| 深度档位 | popular（科普级）/ applied（应用级）/ technical（技术级） |
| 课时备课 | 某一课时针对某班级的完整备课产物（教案+PPT+案例+习题） |
| 案例卡 | 热点事件经 AI 分析后生成的待审卡片：摘要、知识点匹配、思政角度、讨论问题 |
| 思政元素 | 课程思政要点（科技伦理、数据安全、科技自立自强等） |
| 学情问卷 | 开学初向学生发放的学情调查问卷：AI 辅助设计、匿名作答、汇总成学情画像 |
| 来源引用 | AI 生成内容中附带的参考来源，供教师核验 |

---

## 2. 需求规格

### 2.1 功能需求

#### F1 用户系统
- F1.1 教师账号注册/登录（用户名+密码，≤10 用户）
- F1.2 角色：admin（管理知识库/模板）、teacher（备课）
- F1.3 公共层资产共享，个人层数据隔离

#### F2 课程知识库
- F2.1 课程结构管理：章节 → 课时 → 知识点（含排序、学时、教学目标）
- F2.2 思政元素库：预设思政元素及其融入角度
- F2.3 知识点与思政元素预置关联
- F2.4 案例库：案例 CRUD，按知识点/专业模板筛选
- F2.5 种子数据：法学模板内容 + AI 基础通用知识点体系
- F2.6 多种录入方式：手工输入（表单）、文件导入（Word/Markdown 大纲解析）、AI 辅助提取（上传教材文档 → AI 生成知识点体系草稿 → 教师审核入库）、批量导入（模板文件）

#### F3 专业模板
- F3.1 模板 CRUD：默认深度档位、案例偏好、语言风格、思政侧重
- F3.2 模板对知识点的深度/案例覆盖规则（可细化到知识点）
- F3.3 首批模板：法学类

#### F4 班级管理
- F4.1 班级 CRUD：名称、专业、年级、人数
- F4.2 学情画像：数学基础、编程基础、兴趣偏好、备注（教师凭经验填写）
- F4.3 班级套用专业模板
- F4.4 学情问卷：见 F9 问卷系统

#### F5 热点采集与审核（核心特色）
- F5.1 手动粘贴：教师粘贴热点链接/文本 → AI 提炼事件要素（时间、主体、经过、争议点）
- F5.2 时间窗设定：如"仅分析最近 30 天的事件"
- F5.3 三维匹配：事件 → 知识点匹配（属哪一章哪一课时）→ 专业模板匹配（法学→法律争议视角）→ 思政角度匹配
- F5.4 案例卡审核工作台：采纳 / 修改 / 驳回；采纳后进入案例库
- F5.5 RSS 订阅（阶段 2）：订阅源管理、定时抓取

#### F6 分步生成引擎（按课时确认制）
- F6.1 每课时流程：**教案 → PPT → 案例与习题 →（全部课时后）汇总大纲**
- F6.2 每步生成后人工确认，可修改、可重新生成
- F6.3 生成时自动融入：班级画像、专业模板、思政元素、案例库匹配结果
- F6.4 来源引用：生成内容自动附参考来源

#### F7 导出中心
- F7.1 Word：教案、案例与习题、课程大纲与进度表
- F7.2 PPT：直接生成 .pptx 课件文件
- F7.3 下载记录管理

#### F8 课后反馈（阶段 3）
- F8.1 课后记录：某班某课时内容效果、学生反馈
- F8.2 效果评分，沉淀为备课经验，反哺下次生成

#### F9 学情问卷（阶段 1）
- F9.1 AI 问卷设计：依据专业模板 + 课程目标生成问卷草稿，教师编辑题目
- F9.2 问卷发布：生成匿名作答链接/二维码，学生免登录填写（移动端友好），可设截止时间
- F9.3 作答收集：查看回收进度，匿名作答保护隐私
- F9.4 画像分析：AI 汇总作答生成班级学情画像，写入班级画像供备课引用；教师可手动补充

### 2.2 非功能需求

| 类别 | 要求 |
|---|---|
| 性能 | ≤10 用户，常规操作 < 1s；AI 生成单步 < 60s（异步任务+进度提示） |
| 安全 | 密码哈希存储；教师数据按用户隔离；API Key 仅存服务端 |
| 合规 | 热点案例**转述提炼**而非原文转载；不抓取热搜榜（不稳定且有风险）；思政内容遵循主流导向 |
| 成本 | 生成结果持久化（确认后不重复调用）；DeepSeek 按量计费，预估月成本极低 |
| 可维护 | 知识点体系与模板分离，新增专业大类不改代码 |

---

## 3. 系统架构

### 3.1 技术选型

| 层 | 选型 | 理由 |
|---|---|---|
| 前端+后端 | Next.js 14（App Router）+ TypeScript | 前后端一体，单项目部署，开发效率高 |
| 数据库 | SQLite（better-sqlite3 或 Prisma） | ≤10 用户足够，零运维，单文件备份 |
| AI | DeepSeek API（JSON 结构化输出） | 中文强、成本低、输出稳定 |
| PPT 生成 | pptxgenjs | Node 原生生成 .pptx |
| Word 生成 | docx | Node 原生生成 .docx |
| RSS（阶段 2） | rss-parser | 轻量解析 |
| 样式 | Tailwind CSS + shadcn/ui | 快速搭建管理界面 |
| 部署 | 单机 Node 部署（Docker 可选） | 用户规模小，简单优先 |

### 3.2 总体架构

```
┌─────────────────────────────────────────────┐
│                Web 前端（Next.js）            │
│  工作台/备课向导/热点工作台/知识库/模板/导出    │
└──────────────────┬──────────────────────────┘
                   │ REST API
┌──────────────────▼──────────────────────────┐
│               Next.js API 路由               │
│  ┌───────────┐ ┌───────────┐ ┌────────────┐ │
│  │ 认证/权限  │ │ 业务模块   │ │ 生成任务队列 │ │
│  └───────────┘ └─────┬─────┘ └────────────┘ │
└──────────────────────┼──────────────────────┘
        ┌───────────────┼───────────────┐
┌───────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
│   SQLite     │ │  DeepSeek   │ │  文件存储    │
│  (业务数据)   │ │   API       │ │ (Word/PPT)  │
└──────────────┘ └─────────────┘ └─────────────┘
```

### 3.3 项目目录结构（规划）

```
ai-lesson-prep/
├── docs/                  # 设计文档
├── prisma/                # 数据模型与迁移
├── src/
│   ├── app/               # Next.js App Router
│   │   ├── (auth)/login/  # 登录页
│   │   ├── dashboard/     # 工作台首页
│   │   ├── classes/       # 班级管理
│   │   ├── prepare/       # 备课向导（核心）
│   │   ├── questionnaires/ # 问卷管理
│   │   ├── q/             # 学生作答页（公开）
│   │   ├── hotspots/      # 热点工作台
│   │   ├── cases/         # 案例库
│   │   ├── knowledge/     # 知识库管理
│   │   ├── templates/     # 模板管理
│   │   ├── exports/       # 导出中心
│   │   └── api/           # 后端 API 路由
│   ├── lib/
│   │   ├── ai/            # DeepSeek 客户端封装
│   │   │   ├── client.ts
│   │   │   ├── prompts/   # 提示词模板
│   │   │   └── schemas/   # 产物 JSON Schema
│   │   ├── exporters/     # pptxgenjs / docx 导出
│   │   ├── hotspot/       # 热点分析
│   │   └── db.ts
│   └── components/
├── seed/                  # 种子数据（法学模板、知识点体系、思政库）
└── public/
```

---

## 4. 数据模型设计

### 4.1 实体关系总览

```
User 1──N ClassGroup N──1 MajorTemplate
Course 1──N Chapter 1──N Lesson 1──N KnowledgePoint
KnowledgePoint N──N SizhengElement（关联表含融入建议）
MajorTemplate 1──N TemplateRule（知识点级覆盖规则）
ClassGroup 1──N LessonPlan N──1 Lesson
LessonPlan 1──N Export
Hotspot 1──0..1 Case（来源）
Hotspot N──1 User（审核人）
Case N──N KnowledgePoint（JSON 存 id 列表，MVP 简化）
ClassGroup 1──N Feedback
RssSource（阶段 2）
GenerationTask（异步任务表，贯穿所有生成）
```

### 4.2 数据表详细设计

#### users（用户）
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER PK | |
| username | TEXT UNIQUE | 登录名 |
| password_hash | TEXT | bcrypt 哈希 |
| display_name | TEXT | 显示名 |
| role | TEXT | 'admin' / 'teacher' |
| created_at | DATETIME | |

#### courses（课程，预留多课程扩展）
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER PK | |
| name | TEXT | 课程名，如"人工智能基础" |
| code | TEXT | 课程代码 |
| description | TEXT | |

> 注：当前版本仅《人工智能基础》单课程；保留 course 关联字段，后续扩展其他课程成本极低。

#### chapters（章节）
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER PK | |
| course_id | FK → courses | |
| sort_order | INTEGER | 排序 |
| title | TEXT | 如"自然语言处理与应用"（第七章） |
| description | TEXT | |

#### lessons（课时）
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER PK | |
| chapter_id | FK → chapters | |
| sort_order | INTEGER | |
| title | TEXT | 课时主题 |
| hours | REAL | 学时（如 2） |
| objectives | TEXT | 教学目标 |
| description | TEXT | |

#### knowledge_points（知识点）
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER PK | |
| lesson_id | FK → lessons | |
| sort_order | INTEGER | |
| title | TEXT | 如"舆情分析与立场检测" |
| description | TEXT | |
| base_depth | TEXT | 基准深度：popular / applied / technical |

#### sizheng_elements（思政元素库）
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER PK | |
| name | TEXT | 如"科技伦理" |
| description | TEXT | |
| keywords | TEXT | 检索关键词 |
| examples | TEXT | 融入角度示例 |

#### knowledge_point_sizheng（知识点-思政关联）
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER PK | |
| knowledge_point_id | FK | |
| sizheng_element_id | FK | |
| suggestion | TEXT | 该知识点如何融入该思政点 |

#### major_templates（专业模板）
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER PK | |
| name | TEXT | 如"法学类" |
| code | TEXT UNIQUE | 如 'law' |
| description | TEXT | |
| default_depth | TEXT | 默认深度档位 |
| case_preferences | TEXT(JSON) | 案例偏好说明（法学：法律争议、司法 AI、AI 生成内容责任等） |
| style_guidelines | TEXT | 语言风格、行文要求 |
| sizheng_focus | TEXT | 思政侧重（法学：法治精神、公平正义、数据合规） |
| default_ppt_theme | TEXT | 默认 PPT 视觉风格（四选一，可被班级/课时覆盖） |

#### template_rules（模板-知识点规则，可选细化）
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER PK | |
| template_id | FK | |
| knowledge_point_id | FK | |
| depth_level | TEXT | 覆盖基准深度 |
| case_theme | TEXT | 该知识点对该专业的案例主题偏好 |

#### classes（班级）
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER PK | |
| name | TEXT | 如"2024 级法学 1 班" |
| major | TEXT | 专业 |
| grade | TEXT | 年级 |
| student_count | INTEGER | 人数 |
| template_id | FK → major_templates | 套用模板 |
| owner_id | FK → users | 创建教师 |
| profile | TEXT(JSON) | 学情画像：`{math_basis, programming_basis, interests, notes}`，可由问卷分析自动生成或教师手填 |
| created_at | DATETIME | |

#### questionnaires（学情问卷）
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER PK | |
| class_id | FK → classes | 所属班级 |
| title | TEXT | 问卷标题 |
| description | TEXT | 说明文案（展示给学生） |
| questions | TEXT(JSON) | 题目列表：`[{id, type:"single|multi|scale|text", question, options[], required}]` |
| status | TEXT | 'draft' / 'published' / 'closed' |
| token | TEXT UNIQUE | 作答链接 token（匿名作答） |
| deadline | DATETIME | 截止时间 |
| created_by | FK | |
| created_at | DATETIME | |

#### questionnaire_responses（作答记录）
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER PK | |
| questionnaire_id | FK | |
| answers | TEXT(JSON) | `{question_id: answer}` |
| submitted_at | DATETIME | |

#### hotspots（热点）
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER PK | |
| source_type | TEXT | 'manual'（手动粘贴）/ 'rss' |
| source_url | TEXT | 来源链接 |
| raw_text | TEXT | 原文/粘贴文本 |
| title | TEXT | 事件标题 |
| event_date | DATE | 事件发生日期（AI 提取） |
| summary | TEXT | 事件摘要 |
| status | TEXT | 'pending' / 'adopted' / 'rejected' |
| analysis | TEXT(JSON) | 案例卡：`{event_elements, matched_knowledge_points[], matched_templates[], sizheng_angles[], discussion_questions[], freshness}` |
| created_by | FK → users | |
| reviewed_at | DATETIME | |
| created_at | DATETIME | |

#### cases（案例库）
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER PK | |
| title | TEXT | |
| source_type | TEXT | 'hotspot' / 'manual' |
| hotspot_id | FK NULL | 来源热点 |
| content | TEXT | 案例正文（转述提炼版） |
| discussion_questions | TEXT(JSON) | 讨论问题列表 |
| sizheng_angle | TEXT | 思政切入点 |
| citations | TEXT(JSON) | 引用来源列表 |
| knowledge_point_ids | TEXT(JSON) | 关联知识点 id 列表 |
| template_ids | TEXT(JSON) | 适配的专业模板 id 列表 |
| status | TEXT | 'draft' / 'active' / 'archived' |
| created_by | FK | |
| created_at | DATETIME | |

#### lesson_plans（课时备课，核心表）
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER PK | |
| class_id | FK → classes | |
| lesson_id | FK → lessons | |
| status | TEXT | 状态机见 5.1：not_started → plan_generated → plan_confirmed → ppt_generated → materials_generated → completed |
| plan_content | TEXT(JSON) | 已确认教案 |
| ppt_content | TEXT(JSON) | 已确认幻灯片数据 |
| materials_content | TEXT(JSON) | 已确认案例+习题 |
| citations | TEXT(JSON) | 汇总来源引用 |
| created_by | FK | |
| updated_at | DATETIME | |
| UNIQUE(class_id, lesson_id) | | |

#### exports（导出记录）
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER PK | |
| lesson_plan_id | FK NULL | |
| export_type | TEXT | 'lesson_plan_docx' / 'ppt_pptx' / 'materials_docx' / 'outline_docx' |
| file_name | TEXT | |
| file_path | TEXT | |
| created_by | FK | |
| created_at | DATETIME | |

#### course_outlines（课程大纲汇总）
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER PK | |
| class_id | FK | |
| content | TEXT(JSON) | 每周进度：`{weekly_schedule:[{week,topic,hours,key_points,assessment}], assessment_plan}` |
| status | TEXT | 'draft' / 'confirmed' |
| created_at | DATETIME | |

#### feedbacks（课后反馈，阶段 3）
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER PK | |
| class_id | FK | |
| lesson_id | FK | |
| content | TEXT | 课后记录 |
| effect_rating | INTEGER | 1-5 |
| created_by | FK | |
| created_at | DATETIME | |

#### generation_tasks（生成任务）
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER PK | |
| type | TEXT | 'lesson_plan' / 'ppt' / 'materials' / 'outline' / 'hotspot_analyze' |
| params | TEXT(JSON) | 请求参数 |
| status | TEXT | 'pending' / 'running' / 'done' / 'failed' |
| result | TEXT(JSON) | 结果（确认后写入对应表） |
| error | TEXT | 失败原因 |
| created_at / finished_at | DATETIME | |

#### rss_sources（RSS 订阅源，阶段 2）
| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER PK | |
| name | TEXT | 订阅源名称 |
| url | TEXT | RSS 地址 |
| enabled | BOOLEAN | |
| last_fetched_at | DATETIME | |

### 4.3 种子数据规划

| 种子 | 内容 |
|---|---|
| 课程 | 《人工智能基础》单课程 |
| 章节/课时/知识点 | 按教材目录预置（AI 概述、机器学习、深度学习、CV、NLP、大模型、AI 伦理等），**第七章 NLP 优先完整录入**（有实战案例） |
| 思政元素库 | 科技伦理、数据隐私与安全、科技自立自强、法治精神、社会责任、理性用网/信息素养、创新精神等 |
| 法学模板 | default_depth=applied、案例偏好（司法 AI、AI 生成内容责任、舆情与言论、数据合规）、思政侧重（法治精神、公平正义） |
| 案例库 | 流浪狗舆情反转案例（NLP+法学）等 3-5 个初始案例 |
| 演示班级 | "2024 级法学 1 班"示例 + 学情画像示例 |
| 示例问卷 | 法学班学情问卷模板（AI 生成后教师可修改） |

---

## 5. 核心流程设计

### 5.1 分步生成工作流（按课时确认制）

```
用户选择班级 → 系统列出该班课程全部课时（带状态）
                    │
     ┌──────────────▼──────────────┐
     │ 当前课时状态机               │
     │ not_started                 │
     │   → [生成教案]               │
     │ plan_generated              │
     │   → [确认/修改] 或 [重新生成] │
     │ plan_confirmed              │
     │   → [生成 PPT]               │
     │ ppt_generated               │
     │   → [确认/修改] 或 [重新生成]  │
     │ materials_generated(案例习题) │
     │   → [确认/修改]              │
     │ completed                   │
     └─────────────────────────────┘
                    │
   全部课时 completed → [生成课程大纲与进度表] → [导出]
```

**关键规则**：
- 每一步"确认"前可无限次"重新生成"（重新生成消耗 API，需提示）
- 修改教案后，PPT/材料需提示"基于修改后内容重新生成"
- 生成请求进入 `generation_tasks` 异步执行，前端轮询进度

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

```
[手动粘贴 链接/文本] 或 [RSS 抓取]
        │
        ▼
AI 分析（受时间窗约束，如"最近 30 天"）
  1. 提取事件要素：时间/主体/经过/争议点
  2. 知识点匹配：属于哪个章节课时（如 NLP→舆情分析）
  3. 专业模板匹配：法学→法律争议视角
  4. 思政角度匹配：信息素养/法治精神等
  5. 生成建议讨论问题
        │
        ▼
案例卡（status=pending）进入审核工作台
   [采纳] → 转述提炼 → 写入案例库（status=active）
   [修改] → 教师编辑后采纳
   [驳回] → status=rejected（可备注原因）
```

**RSS（阶段 2）**：定时任务（如每日一次）抓取订阅源 → 新增条目自动走分析流程 → 产生 pending 案例卡。

### 5.3 思政融合机制

- **预置层**：知识点↔思政元素关联表，含具体融入建议
- **自动层**：生成教案/案例时，AI 依据关联表 + 模板思政侧重自动融入，输出 `sizheng_integration`（元素、融入方式、出现位置）
- **审核层**：教师在确认步骤可修改思政内容
- **兜底层**：教案模板固定"课程思政"环节，防止遗漏

### 5.4 来源引用机制

- 生成产物每个事实性内容附 `citations: [{source, url, used_for}]`
- 案例卡分析中附原始链接
- 导出文档中引用以脚注/文末"参考来源"呈现
- 教师确认时可增删引用

### 5.5 学情画像问卷流程

```
开学第一课（教材未到位）→ 教师为班级创建问卷
    → AI 依据「专业模板 + 课程目标」生成问卷草稿
    → 教师编辑题目 → 发布（匿名链接/二维码，学生手机作答）
    → 收集作答（设定截止时间，查看回收进度）
    → AI 汇总分析 → 生成班级学情画像报告
    → 写入 classes.profile → 备课生成时自动引用
```

- 画像内容：专业背景、数学/编程基础分布、兴趣话题、AI 认知水平、期望学习内容
- 匿名作答，不采集可识别身份字段（可选学号），保护学生隐私
- 教师可在画像基础上手动补充（如对个别学生的观察）

---

## 6. AI 生成引擎设计

### 6.1 DeepSeek 接入与封装

- 统一客户端 `lib/ai/client.ts`：封装 chat completion，强制 JSON 输出（`response_format: {type: "json_object"}`）
- 配置：`DEEPSEEK_API_KEY`、`DEEPSEEK_BASE_URL`、`DEEPSEEK_MODEL`（默认 deepseek-chat）
- 错误处理：超时重试 1 次；JSON 解析失败重试 1 次并附带错误提示；最终失败记录到 `generation_tasks.error`
- 流式输出可选（MVP 用非流式+任务轮询，实现简单）

### 6.2 提示词策略

**系统提示词构成**（组装顺序）：
1. 角色设定：资深高校 AI 课程备课专家
2. 课程知识库上下文：相关章节/课时/知识点描述
3. 班级画像：模板规则 + 学情画像 JSON
4. 思政元素库：该知识点关联的思政元素及建议
5. 案例库匹配结果：相关案例（若有）
6. 输出要求：JSON Schema 描述 + 引用要求 + 深度档位约束

**上下文传递链**：
- 教案生成：知识库 + 画像 + 思政 + 案例
- PPT 生成：**已确认教案** + 画像（保证内容一致性）
- 案例与习题生成：已确认教案 + 案例库
- 大纲汇总：全部已确认课时教案

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

### 6.3 产物 JSON Schema

**教案（lesson_plan）**：
```json
{
  "lesson_title": "课时标题",
  "class_profile_summary": "对班级画像的适配说明",
  "teaching_objectives": ["目标1", "目标2"],
  "key_points": [
    {"title": "知识点名", "content": "讲解要点", "depth": "popular|applied|technical"}
  ],
  "teaching_method": ["讲授", "案例分析"],
  "sizheng_integration": {
    "element": "思政元素名",
    "approach": "融入方式",
    "position": "导入|案例|总结"
  },
  "case_plan": {
    "case_title": "案例名",
    "usage": "导入|讲解|讨论",
    "discussion_questions": ["问题1"]
  },
  "timeline": [
    {"duration": "10min", "segment": "环节名", "content": "环节内容"}
  ],
  "difficulty_notes": "难度适配说明",
  "citations": [{"source": "来源名", "url": "链接", "used_for": "用于哪部分"}]
}
```

**PPT（slides）**：
```json
{
  "theme": "简约学术",
  "slides": [
    {
      "title": "页标题",
      "bullets": ["要点1", "要点2"],
      "visual": "配图/图表建议",
      "speaker_notes": "讲稿备注",
      "sizheng_tag": "可选：思政提示"
    }
  ]
}
```

**案例与习题（materials）**：
```json
{
  "cases": [
    {
      "title": "案例名",
      "summary": "转述提炼的案例正文",
      "discussion_questions": ["问题1"],
      "sizheng_angle": "思政切入点",
      "citations": [{"source": "", "url": ""}]
    }
  ],
  "exercises": [
    {
      "type": "choice|short_answer|discussion",
      "question": "题目",
      "options": ["A", "B", "C"],        // 仅 choice
      "answer": "参考答案",
      "difficulty": "easy|medium|hard",
      "knowledge_point": "对应知识点"
    }
  ]
}
```

**课程大纲（outline）**：
```json
{
  "course_title": "人工智能基础",
  "total_hours": 32,
  "weekly_schedule": [
    {"week": 1, "topic": "主题", "hours": 2, "key_points": ["..."], "assessment": "考核方式"}
  ],
  "assessment_plan": "总评构成"
}
```

**学情问卷（questionnaire）**：
```json
{
  "title": "《人工智能基础》学情调查（法学班）",
  "description": "同学你好，本问卷用于了解大家的学习背景，请如实填写……",
  "questions": [
    {"id": "q1", "type": "single", "question": "你的数学基础如何？", "options": ["较弱", "一般", "较好", "很好"], "required": true},
    {"id": "q2", "type": "multi", "question": "你对以下哪些 AI 话题感兴趣？", "options": ["AI 与法律", "大模型应用", "AI 伦理", "AI 绘画"], "required": true},
    {"id": "q3", "type": "scale", "question": "你之前接触过编程吗？（1-5 分）", "required": false},
    {"id": "q4", "type": "text", "question": "你最希望这门课讲什么？", "required": false}
  ]
}
```

**学情画像报告（profile_report）**：
```json
{
  "summary": "班级整体情况概述",
  "math_basis": "数学基础评估",
  "programming_basis": "编程基础评估",
  "interest_topics": ["关注话题"],
  "depth_recommendation": "推荐深度档位",
  "teaching_notes": ["备课建议"]
}
```

### 6.4 成本与缓存

- 生成结果在确认后写入 `lesson_plans`，**重新生成才重新调用 API**
- 热点分析结果缓存于 `hotspots.analysis`
- 预估：每周 3 个班 × 每班 16 课时 × 3 次生成 × 约 2k tokens ≈ 极低月成本（个位数元级）

---

## 7. 导出设计

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

| 文档 | 结构 |
|---|---|
| 教案 | 标题页（课程/班级/课时/教师/日期）→ 教学目标 → 重点难点 → 教学过程（含时间轴）→ 课程思政 → 案例与讨论 → 板书/资源 → 参考来源 |
| 案例与习题 | 案例正文 + 讨论问题 + 思政角度；习题（选择题/简答/讨论）+ 参考答案 |
| 课程大纲 | 课程信息 → 总学时 → 周进度表（表格）→ 考核方案 |

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

- 页结构：封面页（课程/课时/班级）→ 目录页 → 内容页（标题+要点+配图建议区）→ 案例页 → 思政小结页 → 习题页 → 尾页
- 版式：16:9；**四套视觉风格**（可全局/按课时选择，写入 `slides.theme`）：
  1. **简约学术**（默认）：白底深蓝标题，克制配色，适合理论讲解
  2. **图文并茂**：大图 + 要点排版，视觉冲击强，适合概念引入
  3. **数据可视化**：图表驱动，适合机器学习/统计类内容
  4. **案例叙事**：故事线排版，适合案例分析与讨论
- 讲稿：每页 `speaker_notes` 写入备注区，便于教师讲授
- 文件命名：`{课程}-{班级}-{课时}.pptx`

---

## 8. 界面与交互设计

### 8.1 页面清单

| 页面 | 路径 | 说明 |
|---|---|---|
| 登录 | /login | |
| 工作台 | /dashboard | 我的班级卡片（进度条）、待审热点数、最近生成 |
| 班级详情 | /classes/[id] | 画像编辑、课时进度列表（状态徽章） |
| 备课向导 | /prepare/[classId] | **核心页面**，见 8.2 |
| 教案查看/编辑 | /prepare/[classId]/lesson/[lessonId] | 结构化表单 |
| PPT 预览 | 同上 | 左侧缩略图 + 右侧大图 |
| 热点工作台 | /hotspots | 粘贴分析区、待审/已采纳/已驳回列表 |
| 案例卡详情 | /hotspots/[id] | 采纳/修改/驳回 |
| 案例库 | /cases | 列表 + 知识点/模板筛选 |
| 问卷管理 | /classes/[id]/questionnaires | 问卷列表、AI 生成、编辑题目、发布（链接/二维码） |
| 问卷统计与画像 | /questionnaires/[id] | 回收进度、作答统计、AI 学情画像报告 |
| 学生作答页 | /q/[token] | 匿名公开作答页，移动端友好 |
| 知识库管理 | /knowledge | 章节树 + 思政元素管理 |
| 模板管理 | /templates | 模板 CRUD |
| 导出中心 | /exports | 文件列表 + 下载 |

### 8.2 备课向导（核心页面）交互设计

```
┌────────────┬───────────────────────────────┬─────────────┐
│ 课时列表    │  当前步骤主区                   │ 操作区       │
│ (左侧)     │  教案预览（表单化，可编辑）       │ [生成]      │
│  ● 1-1 已确认│  - 教学目标 [编辑]            │ [重新生成]   │
│  ● 1-2 生成中│  - 教学过程 [编辑]            │ [确认]      │
│  ○ 1-3 未开始│  - 课程思政 [编辑]            │ [导出]      │
│  ○ 1-4 ...  │  - 参考来源 [编辑]            │             │
└────────────┴───────────────────────────────┴─────────────┘
 步骤指示：教案 → PPT → 案例与习题 → 汇总大纲
```

- 左侧课时按章节分组，状态用颜色徽章：灰=未开始、蓝=生成中（转圈）、黄=待确认、绿=已完成
- 生成中显示进度（轮询 `generation_tasks`），完成后主区刷新为预览
- "确认"前弹出检查清单：思政环节是否齐全、引用是否可核验、深度是否符合画像

---

## 9. API 设计

### 9.1 接口总览（REST）

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/auth/login | 登录，返回 token |
| POST | /api/auth/logout | 登出 |
| GET | /api/me | 当前用户 |
| GET | /api/courses | 课程列表 |
| GET | /api/chapters?courseId= | 章节列表 |
| GET | /api/lessons?chapterId= | 课时列表 |
| GET | /api/knowledge-points?lessonId= | 知识点列表 |
| GET/POST | /api/sizheng-elements | 思政元素 |
| GET/POST/PUT/DELETE | /api/templates | 专业模板 CRUD |
| GET/POST/PUT | /api/classes | 班级 CRUD（GET 支持 ?owner=me） |
| GET | /api/lesson-plans?classId= | 某班全部课时备课状态 |
| POST | /api/lesson-plans/generate | `{class_id, lesson_id, step}` 发起生成（教案/PPT/材料/大纲） |
| PUT | /api/lesson-plans/:id/confirm | `{step, content}` 确认（可含教师修改） |
| POST | /api/lesson-plans/:id/export | `{type}` 导出 Word/PPT，返回文件 |
| GET | /api/exports | 导出记录 |
| POST | /api/hotspots/analyze | `{text 或 url, window_days}` 粘贴分析 |
| GET | /api/hotspots?status= | 热点列表 |
| POST | /api/hotspots/:id/review | `{action: adopt/reject, edits?}` 审核 |
| GET/POST/PUT | /api/cases | 案例库 CRUD |
| GET | /api/tasks/:id | 生成任务状态轮询 |
| POST | /api/questionnaires/generate | `{class_id}` AI 生成问卷草稿 |
| GET/POST/PUT | /api/questionnaires | 问卷 CRUD |
| POST | /api/questionnaires/:id/publish | 发布，返回作答链接 |
| GET | /api/questionnaires/:id/responses | 作答统计 |
| POST | /api/questionnaires/:id/analyze | AI 汇总 → 学情画像 → classes.profile |
| POST | /api/q/:token | 学生匿名提交作答 |
| POST | /api/feedbacks | 课后反馈（阶段 3） |
| GET/POST | /api/rss-sources | RSS 订阅源（阶段 2） |

---

## 10. 开发计划

### 10.1 阶段划分

| 阶段 | 内容 | 交付 |
|---|---|---|
| 阶段 1（MVP） | 骨架、认证、数据模型、知识库（多方式录入）、模板、班级、学情问卷、分步生成、导出、来源引用 | 可用的备课核心链路 |
| 阶段 2 | 热点采集（粘贴分析+案例卡审核+时间窗）、RSS | 热点工作台 |
| 阶段 3 | 课后反馈闭环、活页教材更新、模板扩展（理工/医学等） | 完整平台 |

### 10.2 详细任务清单（阶段 1）

| # | 任务 | 说明 |
|---|---|---|
| 1.1 | 项目初始化 | Next.js + TS + Tailwind + Prisma(SQLite) 脚手架 |
| 1.2 | 用户认证 | 登录/登出、bcrypt、会话 |
| 1.3 | 数据模型落地 | 全部表 + 迁移 |
| 1.4 | 种子数据 | 课程/章节/课时/知识点（第七章 NLP 优先）、思政库、法学模板、示例班级 |
| 1.5 | 知识库管理页 | 章节→课时→知识点树 CRUD、思政元素管理 |
| 1.6 | 模板管理页 | 模板 CRUD + 模板-知识点规则 |
| 1.7 | 班级管理页 | 班级 CRUD + 学情画像表单 + 套模板 |
| 1.8 | DeepSeek 客户端 | JSON 输出、重试、错误处理 |
| 1.9 | 生成任务模块 | 任务表、异步执行、轮询接口 |
| 1.10 | 教案生成 | 提示词组装 + Schema 校验 + 写入 |
| 1.11 | 教案编辑确认 | 表单化渲染 + 确认/重新生成 |
| 1.12 | PPT 生成 | 基于教案生成幻灯片数据 → pptxgenjs 导出 |
| 1.13 | 案例与习题生成 | 基于教案+案例库生成 → 确认 |
| 1.14 | 大纲汇总生成 | 全部课时完成后汇总 |
| 1.15 | Word 导出 | 教案/材料/大纲 docx |
| 1.16 | 来源引用渲染 | 产物中引用展示与导出 |
| 1.17 | 备课向导页面 | 核心交互（8.2） |
| 1.18 | 工作台首页 | 班级进度、待办入口 |
| 1.19 | 端到端联调 | 法学班完整流程跑通 |
| 1.20 | 问卷数据模型 | questionnaires + questionnaire_responses 表 |
| 1.21 | AI 问卷生成 | 依据模板+课程目标生成问卷草稿（Schema+提示词） |
| 1.22 | 问卷管理与发布 | 编辑题目、发布链接/二维码、截止管理、回收进度 |
| 1.23 | 学生作答页 | /q/[token] 匿名移动端页面 |
| 1.24 | 画像分析 | AI 汇总作答 → 学情画像 → classes.profile |
| 1.25 | 知识库多方式录入 | 手工表单、Word/Markdown 大纲导入解析、AI 辅助提取（教材文档→草稿→审核入库）、批量模板导入 |

### 10.3 里程碑

- **M1**（任务 1.1–1.4）：骨架+认证+数据模型+种子
- **M2**（1.5–1.7、1.20–1.21、1.25）：知识库（含多方式录入）/模板/班级 + 问卷模型与 AI 生成
- **M3**（1.8–1.11、1.22–1.24）：教案生成与确认链路 + 问卷发布/作答/画像分析
- **M4**（1.12–1.16）：PPT/Word 导出、引用
- **M5**（1.17–1.19）：完整备课向导 + 联调验收
- **M6**（阶段 2）：热点工作台
- **M7**（阶段 3）：反馈闭环 + 扩展

---

## 11. 部署与运维

### 11.1 部署方案

- **MVP**：Linux 单机部署，Node LTS 运行 Next.js standalone 构建 + SQLite 文件 + 上传目录（Word/PPT），systemd 服务托管（或 PM2）
- **可选**：Docker Compose 单容器打包，便于迁移
- 部署位置：Linux 服务器/主机（内网即可，无公网要求）

### 11.2 配置管理

- 环境变量：`DEEPSEEK_API_KEY`、`DATABASE_URL`、`SESSION_SECRET`、`UPLOAD_DIR`
- 配置文件 `config.toml`/`.env`，**API Key 仅存服务端**，不进入前端

### 11.3 数据备份与安全

- SQLite 单文件 + 上传目录，每日 cron 备份到本地/网盘
- 密码 bcrypt；会话 cookie httpOnly + secure
- 热点案例只存转述提炼文本与来源链接，不整篇转载

---

## 12. 风险与开放问题

### 12.1 风险与对策

| 风险 | 对策 |
|---|---|
| LLM 生成内容幻觉/不准确 | 来源引用 + 人工审核 + 确认检查清单 |
| JSON 输出不稳定 | 严格 Schema 描述 + 解析重试 + 校验兜底 + 失败可视化 |
| 热点时效性（模型训练截止日之后的事件） | 事件日期由 AI 提取 + 时间窗约束 + 来源链接留痕 |
| 案例内容版权/合规 | 只转述提炼不转载原文，来源链接标注 |
| API 成本失控 | 结果持久化，确认前不重复调用，成本极低 |
| 教师接受度（AI 产出需打磨） | 分步确认制，每步可改，AI 定位为"草稿机" |

### 12.2 开放问题（待评审确认）

1. ~~学情画像来源~~：**已定**——问卷为主（开学第一课、教材未到位时发放）+ 教师经验补充；问卷 AI 生成、教师审核、匿名作答。
2. ~~PPT 视觉风格~~：**已定 4 套**——简约学术 / 图文并茂 / 数据可视化 / 案例叙事，可全局或按课时选择。
3. ~~知识库录入方式~~：**已定多方式**——手工输入、文件导入（Word/Markdown 大纲解析）、AI 辅助提取（教材文档 → 草稿 → 审核入库）、批量模板导入。
4. ~~部署环境~~：**已定 Linux**（systemd/PM2 托管，Docker 可选）。
5. ~~多课程扩展~~：**已定单课程**——当前版本仅《人工智能基础》，数据模型保留 course 字段预留扩展。
6. **教师协作细节**：公共案例库是否允许他人直接采纳进入自己班级备课（共享机制）？建议：可浏览可引用，采纳进备课算个人使用。

---

## 附：评审后待办

- [x] 确认学情画像来源：问卷为主（开学第一课发放）+ 教师经验补充
- [x] 确认运行环境：Linux（systemd/PM2 托管，Docker 可选）
- [x] PPT 视觉风格：4 套（简约学术/图文并茂/数据可视化/案例叙事）
- [x] 知识库录入：多方式（手工/文件导入/AI 辅助提取/批量）
- [x] 课程范围：仅《人工智能基础》单课程（模型预留扩展）
- [ ] 确认剩余开放问题（教师协作机制）
- [ ] 确定种子数据录入方式与范围
- [ ] 确认 Node 版本与部署路径
- [ ] 提供 DeepSeek API Key（或先做成可配置）
- [ ] 批准后启动阶段 1 开发（任务 1.1 起）