From 5942ece5bb7da0cba570dfa89724f9b379212ab6 Mon Sep 17 00:00:00 2001
From: zhenzhu143321 <hxcisunli@126.com>
Date: Fri, 20 Mar 2026 08:55:24 +0800
Subject: [PATCH 01/30] =?UTF-8?q?feat:=20add=20QN=20(=E4=B8=83=E7=89=9B?=
 =?UTF-8?q?=E4=BA=91)=20LLM=20provider=20+=20Claude=20deploy=20guide?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 CLAUDE_DEPLOY_GUIDE.md        | 421 ++++++++++++++++++++++++++++++++++
 lib/ai/providers.ts           |  39 +++-
 lib/server/provider-config.ts |   1 +
 lib/types/provider.ts         |   3 +-
 4 files changed, 459 insertions(+), 5 deletions(-)
 create mode 100644 CLAUDE_DEPLOY_GUIDE.md

diff --git a/CLAUDE_DEPLOY_GUIDE.md b/CLAUDE_DEPLOY_GUIDE.md
new file mode 100644
index 000000000..a15710474
--- /dev/null
+++ b/CLAUDE_DEPLOY_GUIDE.md
@@ -0,0 +1,421 @@
+# OpenMAIC 部署与自定义 Provider 操作教程
+
+> 供 Claude 实例参考的操作手册，基于实际部署经验总结。
+
+## 1. 项目概览
+
+- 项目地址：`/home/sunli/MyWork/myproject/OpenMAIC/`
+- GitHub：`https://github.com/THU-MAIC/OpenMAIC`
+- 技术栈：Next.js 16 + React 19 + TypeScript + LangGraph + pnpm
+- 服务端口：8002
+- 访问地址：`http://172.16.29.100:8002`
+
+## 2. 部署步骤
+
+### 环境要求
+- Node.js >= 20（当前 v20.19.6）
+- pnpm >= 10（通过 `sudo corepack enable pnpm` 启用）
+
+### 克隆与安装
+```bash
+# 需要代理访问 GitHub
+export http_proxy="http://127.0.0.1:17891" https_proxy="http://127.0.0.1:17891"
+git clone https://github.com/THU-MAIC/OpenMAIC.git
+cd OpenMAIC
+pnpm install
+```
+
+### 配置
+```bash
+cp .env.example .env.local
+# 编辑 .env.local 填入 LLM provider 配置
+```
+
+### 构建与启动
+```bash
+pnpm build
+# 后台启动，指定端口 8002
+nohup pnpm start -p 8002 > /tmp/openmaic.log 2>&1 &
+```
+
+### 停止服务
+```bash
+pkill -f "next-server"
+```
+
+## 3. 新增自定义 LLM Provider（以七牛云 QN 为例）
+
+OpenMAIC 内置了 10 个 provider（openai, anthropic, google, deepseek, qwen, kimi, minimax, glm, siliconflow, doubao）。如果要接入新的 OpenAI 兼容 API，需要改 4 个文件。
+
+### 3.1 `lib/types/provider.ts` — 添加 Provider ID
+
+在 `BuiltInProviderId` 联合类型中添加新 ID：
+
+```typescript
+export type BuiltInProviderId =
+  | 'openai'
+  | 'anthropic'
+  // ...existing...
+  | 'doubao'
+  | 'qn';       // ← 新增
+```
+
+### 3.2 `lib/ai/providers.ts` — 注册 Provider 配置
+
+在 `PROVIDERS` 对象末尾（`doubao` 之后，`};` 之前）添加：
+
+```typescript
+qn: {
+  id: 'qn',
+  name: 'QN (七牛云)',
+  type: 'openai',                          // OpenAI 兼容接口
+  defaultBaseUrl: 'https://api.qnaigc.com/v1',
+  requiresApiKey: true,
+  icon: '/logos/qwen.svg',                 // 暂用已有图标
+  models: [
+    {
+      id: 'gemini-3.1-pro-preview',
+      name: 'Gemini 3.1 Pro Preview',
+      contextWindow: 1048576,
+      capabilities: { streaming: true, tools: true, vision: false },
+    },
+    {
+      id: 'deepseek-v3.1',
+      name: 'DeepSeek V3.1',
+      contextWindow: 128000,
+      capabilities: { streaming: true, tools: true, vision: false },
+    },
+    // ...更多模型按需添加
+  ],
+},
+```
+
+关键字段说明：
+- `type: 'openai'` — 使用 `@ai-sdk/openai` 的 `createOpenAI` 创建客户端，兼容所有 OpenAI API 格式的服务
+- `type: 'anthropic'` — 使用 `@ai-sdk/anthropic`
+- `type: 'google'` — 使用 `@ai-sdk/google`
+- `models` — 前端模型选择列表，ID 必须与 API 实际支持的模型名一致
+
+### 3.3 `lib/server/provider-config.ts` — 添加环境变量映射
+
+在 `LLM_ENV_MAP` 中添加映射（key 是环境变量前缀，value 是 provider ID）：
+
+```typescript
+const LLM_ENV_MAP: Record<string, string> = {
+  OPENAI: 'openai',
+  // ...existing...
+  DOUBAO: 'doubao',
+  QN: 'qn',        // ← 新增：QN_API_KEY, QN_BASE_URL, QN_MODELS
+};
+```
+
+这样系统会自动读取 `QN_API_KEY`、`QN_BASE_URL`、`QN_MODELS` 环境变量。
+
+### 3.4 `.env.local` — 配置 API 密钥
+
+```env
+QN_API_KEY=sk-your-api-key-here
+QN_BASE_URL=https://api.qnaigc.com/v1
+QN_MODELS=                                 # 留空则显示 providers.ts 中定义的所有模型
+
+# 设置默认模型（格式：providerId:modelId）
+DEFAULT_MODEL=qn:gemini-3.1-pro-preview
+```
+
+## 4. 架构要点（供理解代码用）
+
+### 配置加载流程
+```
+.env.local / server-providers.yml
+    ↓
+lib/server/provider-config.ts    （服务端加载，缓存在内存）
+    ↓
+GET /api/server-providers        （返回 provider ID + metadata，不暴露 API key）
+    ↓
+lib/store/settings.ts            （前端 Zustand store，合并到 providersConfig）
+    ↓
+前端 UI 显示 provider 列表
+```
+
+### 模型调用流程
+```
+前端选择 model → POST /api/chat (body: { model: "qn:gemini-3.1-pro-preview" })
+    ↓
+lib/server/resolve-model.ts      （解析 modelString，获取 apiKey/baseUrl）
+    ↓
+lib/ai/providers.ts getModel()   （根据 provider.type 创建对应 SDK 客户端）
+    ↓
+createOpenAI({ apiKey, baseURL }) → 调用 QN API
+```
+
+### 关键文件索引
+| 文件 | 作用 |
+|------|------|
+| `lib/types/provider.ts` | Provider/Model 类型定义 |
+| `lib/ai/providers.ts` | Provider 注册表 + getModel() |
+| `lib/server/provider-config.ts` | 服务端配置加载（env + yaml） |
+| `lib/server/resolve-model.ts` | API 路由中的模型解析 |
+| `lib/store/settings.ts` | 前端设置 store（Zustand） |
+| `lib/types/settings.ts` | ProviderSettings 类型 |
+| `app/api/server-providers/route.ts` | 暴露 provider 元数据的 API |
+| `app/api/chat/route.ts` | 聊天 API 路由 |
+
+### 自动机制（不需要手动改）
+- `getDefaultProvidersConfig()` — 遍历 `PROVIDERS` 自动生成前端初始配置
+- `ensureBuiltInProviders()` — 每次 rehydrate 自动合并新增的 provider
+- `fetchServerProviders()` — 前端自动标记 `isServerConfigured`，显示"管理员已配置"
+
+## 5. 常用操作
+
+### 查看 QN API 可用模型
+```bash
+export http_proxy="http://127.0.0.1:17891" https_proxy="http://127.0.0.1:17891"
+curl -s https://api.qnaigc.com/v1/models \
+  -H "Authorization: Bearer $QN_API_KEY" | python3 -m json.tool
+```
+
+### 验证 server-providers API
+```bash
+curl -s http://localhost:8002/api/server-providers | python3 -m json.tool
+```
+
+### 健康检查
+```bash
+curl -s http://localhost:8002/api/health
+```
+
+### 重新构建部署
+```bash
+pkill -f "next-server"
+cd /home/sunli/MyWork/myproject/OpenMAIC
+pnpm build
+nohup pnpm start -p 8002 > /tmp/openmaic.log 2>&1 &
+```
+
+## 6. 注意事项
+
+- `OPENAI_MODELS` 等 `*_MODELS` 环境变量如果设了值，前端会用 `filter` 从内置模型列表筛选。如果模型 ID 不在内置列表里，会被过滤掉导致列表为空。所以自定义 provider 的模型必须在 `providers.ts` 的 `models` 数组中注册。
+- `DEFAULT_MODEL` 只影响服务端 API 的 fallback 模型（`resolve-model.ts:30`），不影响前端 UI 默认选择。
+- 前端首次加载时，如果用户没选过模型，会自动选择第一个 `isServerConfigured` 的 provider 的第一个模型。
+- `.env.local` 已在 `.gitignore` 中（`.env*` 规则），不会被提交。
+- 构建需要代理：`export http_proxy="http://127.0.0.1:17891" https_proxy="http://127.0.0.1:17891"`
+
+## 7. 项目目录结构
+
+```
+OpenMAIC/
+├── app/                          # Next.js App Router
+│   ├── api/                      #   服务端 API 路由
+│   │   ├── chat/route.ts         #     多智能体聊天（SSE 流式）
+│   │   ├── generate-classroom/   #     异步课堂生成（提交 + 轮询）
+│   │   ├── generate/             #     场景生成流水线
+│   │   │   ├── scene-outlines-stream/  # 大纲生成
+│   │   │   ├── scene-content/    #     场景内容生成
+│   │   │   ├── scene-actions/    #     场景动作生成
+│   │   │   ├── agent-profiles/   #     智能体角色生成
+│   │   │   ├── tts/              #     语音合成
+│   │   │   └── image/            #     图片生成
+│   │   ├── quiz-grade/           #     测验评分
+│   │   ├── parse-pdf/            #     PDF 解析
+│   │   ├── pbl/                  #     项目制学习
+│   │   ├── web-search/           #     网络搜索
+│   │   ├── transcription/        #     语音识别
+│   │   ├── server-providers/     #     Provider 元数据 API
+│   │   ├── health/               #     健康检查
+│   │   ├── verify-model/         #     模型验证
+│   │   └── classroom/            #     课堂数据 API
+│   ├── classroom/[id]/           #   课堂页面（动态路由）
+│   ├── generation-preview/       #   生成预览页面
+│   ├── layout.tsx                #   根布局
+│   └── page.tsx                  #   首页
+├── components/                   # React 组件
+│   ├── classroom/                #   课堂相关组件（slides, quiz, interactive, pbl）
+│   ├── generation/               #   课堂生成 UI
+│   ├── settings/                 #   设置面板
+│   └── ui/                       #   通用 UI 组件（shadcn/radix）
+├── lib/                          # 核心库
+│   ├── ai/                       #   AI Provider 注册 + 模型创建
+│   │   └── providers.ts          #     ★ PROVIDERS 注册表 + getModel()
+│   ├── server/                   #   服务端工具
+│   │   ├── provider-config.ts    #     ★ 环境变量/YAML 配置加载
+│   │   └── resolve-model.ts      #     ★ 模型解析（DEFAULT_MODEL fallback）
+│   ├── store/                    #   前端状态管理
+│   │   └── settings.ts           #     ★ Zustand store（provider/model 选择）
+│   ├── types/                    #   TypeScript 类型定义
+│   │   ├── provider.ts           #     ★ ProviderId, ModelInfo 等
+│   │   └── settings.ts           #     ProviderSettings 类型
+│   ├── generation/               #   课堂生成逻辑（大纲→场景→内容）
+│   ├── orchestration/            #   多智能体编排（LangGraph）
+│   ├── chat/                     #   聊天逻辑
+│   ├── audio/                    #   TTS/ASR 音频处理
+│   ├── pdf/                      #   PDF 解析（unpdf/MinerU）
+│   ├── media/                    #   图片/视频生成
+│   ├── export/                   #   导出（PPTX/HTML）
+│   ├── playback/                 #   课堂回放控制
+│   ├── i18n/                     #   国际化（中/英）
+│   ├── web-search/               #   网络搜索（Tavily）
+│   └── utils/                    #   通用工具函数
+├── packages/                     # workspace 子包
+│   ├── mathml2omml/              #   MathML → OMML 转换（PPTX 公式）
+│   └── pptxgenjs/                #   PPTX 生成（fork 版）
+├── public/logos/                 # Provider 图标（SVG/PNG）
+├── .env.example                  # 环境变量模板
+├── .env.local                    # 实际配置（gitignored）
+├── next.config.ts                # Next.js 配置
+├── package.json                  # 依赖（pnpm workspace）
+└── CLAUDE_DEPLOY_GUIDE.md        # 本文档
+```
+
+标 ★ 的是修改最频繁的核心文件。
+
+## 8. 课堂生成流程
+
+这是 OpenMAIC 的核心功能，理解它对排查问题至关重要。
+
+### 两阶段流水线
+```
+用户输入主题/上传PDF
+    ↓
+[阶段1] 大纲生成
+    POST /api/generate/scene-outlines-stream
+    → LLM 分析输入，生成结构化大纲（SSE 流式返回）
+    ↓
+[阶段2] 场景生成（并行）
+    对每个大纲条目：
+    ├── POST /api/generate/scene-content    → 生成场景内容（slides/quiz/interactive/pbl）
+    ├── POST /api/generate/scene-actions    → 生成教师动作（激光笔、聚光灯等）
+    ├── POST /api/generate/agent-profiles   → 生成智能体角色
+    └── POST /api/generate/tts              → 生成语音
+    ↓
+课堂就绪，跳转 /classroom/{id}
+```
+
+### 异步生成模式（API 调用）
+```bash
+# 1. 提交生成任务
+curl -X POST http://localhost:8002/api/generate-classroom \
+  -H "Content-Type: application/json" \
+  -d '{"requirement": "教我 Python 基础"}'
+# 返回: { "jobId": "abc123", "pollUrl": "...", "status": "queued" }
+
+# 2. 轮询进度
+curl http://localhost:8002/api/generate-classroom/abc123
+# 返回: { "status": "running", "step": "generating-scenes", "progress": 0.6 }
+
+# 3. 完成后获取课堂 URL
+# 返回: { "status": "succeeded", "result": { "classroomId": "xxx", "url": "/classroom/xxx" } }
+```
+
+## 9. 前端页面路由
+
+| 路由 | 说明 |
+|------|------|
+| `/` | 首页 — 输入主题或上传 PDF 生成课堂 |
+| `/classroom/[id]` | 课堂页面 — 幻灯片、测验、互动、PBL |
+| `/generation-preview` | 生成预览 — 查看大纲和场景生成进度 |
+
+前端状态全部存在浏览器 localStorage（key: `settings-storage`），通过 Zustand persist 中间件管理。清除浏览器缓存会重置所有设置。
+
+## 10. 多智能体系统
+
+### 编排引擎
+- 基于 LangGraph（`lib/orchestration/`）
+- 支持多个 AI 智能体角色（教师、学生、助教等）
+- 聊天通过 SSE 流式传输（`app/api/chat/route.ts`）
+
+### 场景类型
+| 类型 | 说明 | 关键组件 |
+|------|------|----------|
+| slides | 幻灯片演示 | `components/classroom/slides/` |
+| quiz | 交互测验 | `components/classroom/quiz/` |
+| interactive | HTML 交互模拟 | `components/classroom/interactive/` |
+| pbl | 项目制学习 | `components/classroom/pbl/` |
+
+## 11. 当前 .env.local 配置状态
+
+```env
+# 已配置（有效）
+QN_API_KEY=sk-ebad...（七牛云 API）
+QN_BASE_URL=https://api.qnaigc.com/v1
+DEFAULT_MODEL=qn:gemini-3.1-pro-preview
+
+# 未配置（留空）
+OPENAI_API_KEY=        # 如需 OpenAI 原生模型
+ANTHROPIC_API_KEY=     # 如需 Claude 模型
+GOOGLE_API_KEY=        # 如需 Gemini 模型（直连 Google）
+# TTS/ASR/PDF/Image/Video 均未配置
+```
+
+如需添加更多 provider，直接在 `.env.local` 填入对应的 `{PROVIDER}_API_KEY` 即可，无需改代码（前提是该 provider 已在内置列表中）。
+
+## 12. 故障排查
+
+### 服务无法启动
+```bash
+# 查看日志
+tail -50 /tmp/openmaic.log
+
+# 检查端口占用
+ss -tlnp | grep 8002
+
+# 杀掉残留进程
+pkill -f "next-server"
+```
+
+### 模型调用失败
+```bash
+# 1. 确认 provider 配置正确
+curl -s http://localhost:8002/api/server-providers | python3 -m json.tool
+
+# 2. 直接测试 QN API 连通性（需代理）
+export http_proxy="http://127.0.0.1:17891" https_proxy="http://127.0.0.1:17891"
+curl -s https://api.qnaigc.com/v1/chat/completions \
+  -H "Authorization: Bearer sk-ebad216962663702e91a69addd28b51c85c3b6b01a3e6dd623cdf89f319bade5" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"gemini-3.1-pro-preview","messages":[{"role":"user","content":"hi"}],"max_tokens":10}'
+
+# 3. 检查服务端日志中的错误
+grep -i "error\|fail" /tmp/openmaic.log | tail -20
+```
+
+### 前端不显示新 provider
+- 清除浏览器 localStorage（开发者工具 → Application → Storage → Clear site data）
+- 或删除 `settings-storage` key
+- 确认已重新 `pnpm build` 并重启服务
+
+### 课堂生成卡住
+```bash
+# 检查生成任务状态
+curl -s http://localhost:8002/api/generate-classroom/{jobId} | python3 -m json.tool
+```
+生成任务是内存中的，服务重启后任务丢失。
+
+### 构建失败
+```bash
+# TypeScript 类型错误：检查新增的 provider ID 是否在所有相关文件中一致
+# 常见遗漏：lib/types/provider.ts 的 BuiltInProviderId 忘记添加
+
+# 依赖问题：清理重装
+rm -rf node_modules .next
+pnpm install
+pnpm build
+```
+
+## 13. 代理相关
+
+本机通过 Shadowsocks 代理访问外网：
+- HTTP 代理：`http://127.0.0.1:17891`
+- SOCKS5 代理：`socks5://127.0.0.1:17890`
+- 服务：`shadowsocks-client.service`
+
+OpenMAIC 服务端调用 QN API 时，QN API 地址 `api.qnaigc.com` 是国内服务，不需要代理。但如果配置了 OpenAI/Anthropic/Google 等海外 provider，需要在 `.env.local` 中设置：
+```env
+HTTP_PROXY=http://127.0.0.1:17891
+HTTPS_PROXY=http://127.0.0.1:17891
+```
+
+`pnpm install` 和 `pnpm build` 下载依赖时需要代理（npm registry 部分包在海外）。
+
+---
+
+> 最后更新：2026-03-20 | 维护者：Claude Code
diff --git a/lib/ai/providers.ts b/lib/ai/providers.ts
index 05d167ee1..b9fc604b4 100644
--- a/lib/ai/providers.ts
+++ b/lib/ai/providers.ts
@@ -837,11 +837,42 @@ export const PROVIDERS: Record<ProviderId, ProviderConfig> = {
       },
     ],
   },
-};
 
-/**
- * Get provider config (from built-in or unified config in localStorage)
- */
+  qn: {
+    id: 'qn',
+    name: 'QN (七牛云)',
+    type: 'openai',
+    defaultBaseUrl: 'https://api.qnaigc.com/v1',
+    requiresApiKey: true,
+    icon: '/logos/qwen.svg',
+    models: [
+      {
+        id: 'gemini-3.1-pro-preview',
+        name: 'Gemini 3.1 Pro Preview',
+        contextWindow: 1048576,
+        capabilities: { streaming: true, tools: true, vision: false },
+      },
+      {
+        id: 'deepseek-v3.1',
+        name: 'DeepSeek V3.1',
+        contextWindow: 128000,
+        capabilities: { streaming: true, tools: true, vision: false },
+      },
+      {
+        id: 'qwen3-max',
+        name: 'Qwen3 Max',
+        contextWindow: 262144,
+        capabilities: { streaming: true, tools: true, vision: false },
+      },
+      {
+        id: 'kimi-k2',
+        name: 'Kimi K2',
+        contextWindow: 128000,
+        capabilities: { streaming: true, tools: true, vision: false },
+      },
+    ],
+  },
+};
 function getProviderConfig(providerId: ProviderId): ProviderConfig | null {
   // Check built-in providers first
   if (PROVIDERS[providerId]) {
diff --git a/lib/server/provider-config.ts b/lib/server/provider-config.ts
index b1e0dd47b..7508ecc8d 100644
--- a/lib/server/provider-config.ts
+++ b/lib/server/provider-config.ts
@@ -48,6 +48,7 @@ const LLM_ENV_MAP: Record<string, string> = {
   GLM: 'glm',
   SILICONFLOW: 'siliconflow',
   DOUBAO: 'doubao',
+  QN: 'qn',
 };
 
 const TTS_ENV_MAP: Record<string, string> = {
diff --git a/lib/types/provider.ts b/lib/types/provider.ts
index 2014aa801..ac826a56a 100644
--- a/lib/types/provider.ts
+++ b/lib/types/provider.ts
@@ -15,7 +15,8 @@ export type BuiltInProviderId =
   | 'minimax'
   | 'glm'
   | 'siliconflow'
-  | 'doubao';
+  | 'doubao'
+  | 'qn';
 
 /**
  * Provider ID (built-in or custom)

From 5e1558548dd343c32ac497f58691a4c2be156b74 Mon Sep 17 00:00:00 2001
From: zhenzhu143321 <hxcisunli@126.com>
Date: Fri, 20 Mar 2026 19:51:35 +0800
Subject: [PATCH 02/30] fix: TTS voice jumping, API missing images, and
 publish-to-public

1. TTS voice consistency: generateAndStoreTTS now accepts optional
   TTSOverrides to pin voice/provider across a batch run.
   backfillMissingTTS snapshots TTS settings before iterating scenes,
   preventing voice changes from async provider loading.

2. API-generated classrooms now include images: pass
   imageGenerationEnabled: true to generateSceneOutlinesFromRequirements
   so LLM includes mediaGenerations in outlines.

3. Add "Publish as public" button (Globe icon) in Header:
   - POST classroom.json to /api/classroom (now includes outlines)
   - Upload only current classroom's TTS audio from IndexedDB
   - Upload completed media generation results
   - Fixed TTS cross-classroom leak: filter by scene audioIds instead
     of uploading all IndexedDB audio files

4. POST /api/classroom now persists outlines (was previously dropped).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 app/api/classroom/route.ts         |  15 +-
 app/classroom/[id]/page.tsx        | 217 ++++++++++++++++++++++++++++-
 components/header.tsx              | 111 +++++++++++++++
 lib/hooks/use-scene-generator.ts   |  43 +++++-
 lib/i18n/stage.ts                  |   8 ++
 lib/server/classroom-generation.ts |   6 +
 6 files changed, 385 insertions(+), 15 deletions(-)

diff --git a/app/api/classroom/route.ts b/app/api/classroom/route.ts
index 1c83ad2b5..b3a1dc892 100644
--- a/app/api/classroom/route.ts
+++ b/app/api/classroom/route.ts
@@ -4,6 +4,7 @@ import { apiSuccess, apiError, API_ERROR_CODES } from '@/lib/server/api-response
 import {
   buildRequestOrigin,
   isValidClassroomId,
+  listClassrooms,
   persistClassroom,
   readClassroom,
 } from '@/lib/server/classroom-storage';
@@ -11,7 +12,7 @@ import {
 export async function POST(request: NextRequest) {
   try {
     const body = await request.json();
-    const { stage, scenes } = body;
+    const { stage, scenes, outlines } = body;
 
     if (!stage || !scenes) {
       return apiError(
@@ -24,7 +25,10 @@ export async function POST(request: NextRequest) {
     const id = stage.id || randomUUID();
     const baseUrl = buildRequestOrigin(request);
 
-    const persisted = await persistClassroom({ id, stage: { ...stage, id }, scenes }, baseUrl);
+    const persisted = await persistClassroom(
+      { id, stage: { ...stage, id }, scenes, outlines: outlines || [] },
+      baseUrl,
+    );
 
     return apiSuccess({ id: persisted.id, url: persisted.url }, 201);
   } catch (error) {
@@ -42,11 +46,8 @@ export async function GET(request: NextRequest) {
     const id = request.nextUrl.searchParams.get('id');
 
     if (!id) {
-      return apiError(
-        API_ERROR_CODES.MISSING_REQUIRED_FIELD,
-        400,
-        'Missing required parameter: id',
-      );
+      const list = await listClassrooms();
+      return apiSuccess({ classrooms: list });
     }
 
     if (!isValidClassroomId(id)) {
diff --git a/app/classroom/[id]/page.tsx b/app/classroom/[id]/page.tsx
index 523e23211..5c7f00f5f 100644
--- a/app/classroom/[id]/page.tsx
+++ b/app/classroom/[id]/page.tsx
@@ -6,15 +6,211 @@ import { useStageStore } from '@/lib/store';
 import { loadImageMapping } from '@/lib/utils/image-storage';
 import { useEffect, useRef, useState, useCallback } from 'react';
 import { useParams } from 'next/navigation';
-import { useSceneGenerator } from '@/lib/hooks/use-scene-generator';
+import { useSceneGenerator, generateAndStoreTTS, type TTSOverrides } from '@/lib/hooks/use-scene-generator';
 import { useMediaGenerationStore } from '@/lib/store/media-generation';
 import { useWhiteboardHistoryStore } from '@/lib/store/whiteboard-history';
+import { db } from '@/lib/utils/database';
+import { useSettingsStore } from '@/lib/store/settings';
 import { createLogger } from '@/lib/logger';
 import { MediaStageProvider } from '@/lib/contexts/media-stage-context';
 import { generateMediaForOutlines } from '@/lib/media/media-orchestrator';
 
 const log = createLogger('Classroom');
 
+// Module-level promise so backfillMissingTTS can wait for prefill to finish
+let prefillPromise: Promise<void> = Promise.resolve();
+
+/**
+ * Pre-fill local IndexedDB with cached media from the server.
+ * Runs async, does not block page rendering.
+ */
+async function prefillMediaCache(classroomId: string): Promise<void> {
+  const res = await fetch(`/api/classroom/media?id=${encodeURIComponent(classroomId)}&list=true`);
+  if (!res.ok) return;
+  const json = await res.json();
+  if (!json.success || !Array.isArray(json.files) || json.files.length === 0) return;
+
+  const files: string[] = json.files;
+  const mediaStore = useMediaGenerationStore.getState();
+  const prefilledTtsIds = new Set<string>();
+
+  for (const fileName of files) {
+    const dotIdx = fileName.lastIndexOf('.');
+    if (dotIdx <= 0) continue;
+    const fileId = fileName.slice(0, dotIdx);
+    const ext = fileName.slice(dotIdx);
+
+    if (fileName.startsWith('tts_')) {
+      // Check if already in IndexedDB
+      const existing = await db.audioFiles.get(fileId);
+      if (existing) {
+        prefilledTtsIds.add(fileId);
+        continue;
+      }
+
+      const mediaUrl = `/api/classroom/media?id=${encodeURIComponent(classroomId)}&file=${encodeURIComponent(fileId)}`;
+      try {
+        const blobRes = await fetch(mediaUrl);
+        if (!blobRes.ok) continue;
+        const blob = await blobRes.blob();
+        const format = ext.replace('.', '');
+        await db.audioFiles.put({
+          id: fileId,
+          blob,
+          format,
+          createdAt: Date.now(),
+        });
+        prefilledTtsIds.add(fileId);
+        log.info('Prefilled TTS from cache:', fileId);
+      } catch { /* best effort */ }
+    } else if (fileName.startsWith('gen_img_') || fileName.startsWith('gen_vid_')) {
+      const elementId = fileId;
+      const task = mediaStore.getTask(elementId);
+      if (task?.status === 'done') continue;
+
+      const mediaUrl = `/api/classroom/media?id=${encodeURIComponent(classroomId)}&file=${encodeURIComponent(fileId)}`;
+      const type = fileName.startsWith('gen_img_') ? 'image' : 'video';
+      // Directly set task as done with API URL — works even if task wasn't enqueued yet
+      useMediaGenerationStore.setState((s) => ({
+        tasks: {
+          ...s.tasks,
+          [elementId]: {
+            elementId,
+            type: type as 'image' | 'video',
+            status: 'done' as const,
+            prompt: '',
+            params: {},
+            retryCount: 0,
+            stageId: classroomId,
+            objectUrl: mediaUrl,
+          },
+        },
+      }));
+      log.info('Prefilled media from cache:', elementId);
+    }
+  }
+
+  // Patch audioId on speech actions whose TTS was prefilled from server cache
+  if (prefilledTtsIds.size > 0) {
+    const scenes = useStageStore.getState().scenes;
+    let anyUpdated = false;
+    const updatedScenes = scenes.map(scene => {
+      const actions = scene.actions || [];
+      let sceneUpdated = false;
+      const newActions = actions.map(action => {
+        if (action.type !== 'speech' || !('text' in action) || action.audioId) return action;
+        const candidateId = `tts_${action.id}`;
+        if (prefilledTtsIds.has(candidateId)) {
+          sceneUpdated = true;
+          return { ...action, audioId: candidateId };
+        }
+        return action;
+      });
+      if (!sceneUpdated) return scene;
+      anyUpdated = true;
+      return { ...scene, actions: newActions };
+    });
+    if (anyUpdated) {
+      useStageStore.getState().setScenes(updatedScenes);
+      log.info('Patched audioId on scenes from prefilled TTS cache');
+    }
+  }
+}
+
+/**
+ * Backfill TTS for completed scenes whose speech actions lack audio.
+ * API-generated classrooms have speech actions but no TTS — this fills the gap.
+ *
+ * Key fixes over the original:
+ * 1. Deep-copies scenes/actions so Zustand detects the change
+ * 2. Immediately persists to IndexedDB (not relying on 500ms debounce)
+ * 3. Updates server-side classroom.json so audioIds survive across browsers
+ */
+async function backfillMissingTTS(classroomId: string): Promise<void> {
+  const settings = useSettingsStore.getState();
+  if (!settings.ttsEnabled || settings.ttsProviderId === 'browser-native-tts') return;
+
+  // Wait for prefill to finish so we don't regenerate already-cached TTS
+  await prefillPromise;
+
+  const scenes = useStageStore.getState().scenes;
+  if (!scenes || scenes.length === 0) return;
+
+  // Phase 1: collect all speech actions missing TTS
+  const missing: { sceneIdx: number; actionIdx: number; audioId: string; text: string }[] = [];
+  for (let si = 0; si < scenes.length; si++) {
+    const actions = scenes[si].actions || [];
+    for (let ai = 0; ai < actions.length; ai++) {
+      const action = actions[ai];
+      if (action.type !== 'speech' || !('text' in action) || !action.text) continue;
+      const audioId = action.audioId || `tts_${action.id}`;
+      const existing = await db.audioFiles.get(audioId);
+      if (existing) continue;
+      missing.push({ sceneIdx: si, actionIdx: ai, audioId, text: action.text });
+    }
+  }
+
+  if (missing.length === 0) return;
+  log.info(`Backfilling ${missing.length} missing TTS...`);
+
+  // Snapshot TTS settings once so all items use the same voice
+  const ttsProviderConfig = settings.ttsProvidersConfig?.[settings.ttsProviderId];
+  const ttsSnapshot: TTSOverrides = {
+    providerId: settings.ttsProviderId,
+    voice: settings.ttsVoice,
+    speed: settings.ttsSpeed,
+    apiKey: ttsProviderConfig?.apiKey,
+    baseUrl: ttsProviderConfig?.baseUrl,
+  };
+
+  // Phase 2: generate TTS one by one (skip failures)
+  const generated: typeof missing = [];
+  for (const item of missing) {
+    try {
+      await generateAndStoreTTS(item.audioId, item.text, undefined, ttsSnapshot);
+      generated.push(item);
+      log.info('Backfilled TTS:', item.audioId);
+    } catch (err) {
+      log.warn('Backfill TTS failed:', item.audioId, err);
+    }
+  }
+
+  if (generated.length === 0) return;
+
+  // Phase 3: deep-copy scenes and assign audioId (new object refs for Zustand)
+  const updatedScenes = scenes.map((scene, si) => {
+    const updates = generated.filter(g => g.sceneIdx === si);
+    if (updates.length === 0) return scene;
+    return {
+      ...scene,
+      actions: scene.actions?.map((action, ai) => {
+        const upd = updates.find(u => u.actionIdx === ai);
+        return upd ? { ...action, audioId: upd.audioId } : action;
+      }),
+    };
+  });
+
+  // Phase 4: update store + persist immediately
+  useStageStore.getState().setScenes(updatedScenes);
+  await useStageStore.getState().saveToStorage();
+  log.info(`Backfilled ${generated.length} TTS, saved to IndexedDB`);
+
+  // Phase 5: update server-side classroom.json (best effort)
+  try {
+    const state = useStageStore.getState();
+    await fetch('/api/classroom', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        stage: state.stage,
+        scenes: state.scenes,
+        outlines: state.outlines,
+      }),
+    });
+    log.info('Updated server-side classroom.json with audioIds');
+  } catch { /* best effort */ }
+}
+
 export default function ClassroomDetailPage() {
   const params = useParams();
   const classroomId = params?.id as string;
@@ -25,6 +221,7 @@ export default function ClassroomDetailPage() {
   const [error, setError] = useState<string | null>(null);
 
   const generationStartedRef = useRef(false);
+  const backfillStartedRef = useRef(false);
 
   const { generateRemaining, retrySingleOutline, stop } = useSceneGenerator({
     onComplete: () => {
@@ -44,10 +241,11 @@ export default function ClassroomDetailPage() {
           if (res.ok) {
             const json = await res.json();
             if (json.success && json.classroom) {
-              const { stage, scenes } = json.classroom;
+              const { stage, scenes, outlines } = json.classroom;
               useStageStore.getState().setStage(stage);
               useStageStore.setState({
                 scenes,
+                outlines: outlines || [],
                 currentSceneId: scenes[0]?.id ?? null,
               });
               log.info('Loaded from server-side storage:', classroomId);
@@ -60,6 +258,12 @@ export default function ClassroomDetailPage() {
 
       // Restore completed media generation tasks from IndexedDB
       await useMediaGenerationStore.getState().restoreFromDB(classroomId);
+
+      // Pre-fill media cache from server (fire-and-forget, backfill awaits this promise)
+      prefillPromise = prefillMediaCache(classroomId).catch((err) => {
+        log.warn('Media cache prefill failed:', err);
+      });
+
       // Restore generated agents for this stage
       const { loadGeneratedAgentsForStage } = await import('@/lib/orchestration/registry/store');
       const agentIds = await loadGeneratedAgentsForStage(classroomId);
@@ -81,6 +285,7 @@ export default function ClassroomDetailPage() {
     setLoading(true);
     setError(null);
     generationStartedRef.current = false;
+    backfillStartedRef.current = false;
 
     // Clear previous classroom's media tasks to prevent cross-classroom contamination.
     // Placeholder IDs (gen_img_1, gen_vid_1) are NOT globally unique across stages,
@@ -146,6 +351,14 @@ export default function ClassroomDetailPage() {
         log.warn('[Classroom] Media generation resume error:', err);
       });
     }
+
+    // Backfill TTS for completed scenes that lack audio (e.g. API-generated classrooms)
+    if (stage && !backfillStartedRef.current) {
+      backfillStartedRef.current = true;
+      backfillMissingTTS(stage.id).catch((err) => {
+        log.warn('[Classroom] TTS backfill error:', err);
+      });
+    }
   }, [loading, error, generateRemaining]);
 
   return (
diff --git a/components/header.tsx b/components/header.tsx
index 77a63b03a..6fc70428e 100644
--- a/components/header.tsx
+++ b/components/header.tsx
@@ -10,6 +10,7 @@ import {
   Download,
   FileDown,
   Package,
+  Globe,
 } from 'lucide-react';
 import { useI18n } from '@/lib/hooks/use-i18n';
 import { useTheme } from '@/lib/hooks/use-theme';
@@ -21,11 +22,16 @@ import { useSettingsStore } from '@/lib/store/settings';
 import { useStageStore } from '@/lib/store/stage';
 import { useMediaGenerationStore } from '@/lib/store/media-generation';
 import { useExportPPTX } from '@/lib/export/use-export-pptx';
+import { db } from '@/lib/utils/database';
+import { toast } from 'sonner';
+import { createLogger } from '@/lib/logger';
 
 interface HeaderProps {
   readonly currentSceneTitle: string;
 }
 
+const log = createLogger('Header');
+
 export function Header({ currentSceneTitle }: HeaderProps) {
   const { t, locale, setLocale } = useI18n();
   const { theme, setTheme } = useTheme();
@@ -33,6 +39,7 @@ export function Header({ currentSceneTitle }: HeaderProps) {
   const [settingsOpen, setSettingsOpen] = useState(false);
   const [languageOpen, setLanguageOpen] = useState(false);
   const [themeOpen, setThemeOpen] = useState(false);
+  const [publishing, setPublishing] = useState(false);
 
   // Model setup state
   const currentModelId = useSettingsStore((s) => s.modelId);
@@ -53,6 +60,91 @@ export function Header({ currentSceneTitle }: HeaderProps) {
     failedOutlines.length === 0 &&
     Object.values(mediaTasks).every((task) => task.status === 'done' || task.status === 'failed');
 
+  const stage = useStageStore((s) => s.stage);
+  const outlines = useStageStore((s) => s.outlines);
+
+  const publishClassroom = useCallback(async () => {
+    if (publishing || !stage) return;
+    setPublishing(true);
+    try {
+      // 1. Save classroom.json to server
+      const res = await fetch('/api/classroom', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ stage, scenes, outlines }),
+      });
+      if (!res.ok) throw new Error(`Save failed: ${res.status}`);
+
+      // 2. Upload TTS audio files from IndexedDB (only for this classroom's scenes)
+      const ownAudioIds = new Set<string>();
+      for (const scene of scenes) {
+        for (const action of scene.actions || []) {
+          if (action.type === 'speech' && 'audioId' in action && action.audioId) {
+            ownAudioIds.add(action.audioId);
+          }
+        }
+      }
+      for (const audioId of ownAudioIds) {
+        try {
+          const audio = await db.audioFiles.get(audioId);
+          if (!audio) continue;
+          const buf = await audio.blob.arrayBuffer();
+          const base64 = btoa(
+            new Uint8Array(buf).reduce((s, b) => s + String.fromCharCode(b), ''),
+          );
+          await fetch('/api/classroom/media', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+              classroomId: stage.id,
+              fileId: audio.id,
+              ext: audio.format,
+              base64,
+            }),
+          });
+        } catch {
+          log.warn('Failed to upload TTS:', audioId);
+        }
+      }
+
+      // 3. Upload completed media (images/videos) from media generation tasks
+      for (const task of Object.values(mediaTasks)) {
+        if (task.status !== 'done' || !task.objectUrl) continue;
+        // Skip server-cached URLs (already on server)
+        if (task.objectUrl.startsWith('/api/')) continue;
+        try {
+          const blobRes = await fetch(task.objectUrl);
+          if (!blobRes.ok) continue;
+          const blob = await blobRes.blob();
+          const buf = await blob.arrayBuffer();
+          const base64 = btoa(
+            new Uint8Array(buf).reduce((s, b) => s + String.fromCharCode(b), ''),
+          );
+          const ext = task.type === 'image' ? 'png' : 'mp4';
+          await fetch('/api/classroom/media', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+              classroomId: stage.id,
+              fileId: task.elementId,
+              ext,
+              base64,
+            }),
+          });
+        } catch {
+          log.warn('Failed to upload media:', task.elementId);
+        }
+      }
+
+      toast.success(t('share.publishSuccess'));
+    } catch (err) {
+      log.error('Publish failed:', err);
+      toast.error(t('share.publishFailed'));
+    } finally {
+      setPublishing(false);
+    }
+  }, [publishing, stage, scenes, outlines, mediaTasks, t]);
+
   const languageRef = useRef<HTMLDivElement>(null);
   const themeRef = useRef<HTMLDivElement>(null);
 
@@ -237,6 +329,25 @@ export function Header({ currentSceneTitle }: HeaderProps) {
           </div>
         </div>
 
+        {/* Publish Button */}
+        <button
+          onClick={publishClassroom}
+          disabled={!canExport || publishing}
+          title={canExport ? (publishing ? t('share.publishing') : t('share.publish')) : t('share.notReady')}
+          className={cn(
+            'shrink-0 p-2 rounded-full transition-all',
+            canExport && !publishing
+              ? 'text-gray-400 dark:text-gray-500 hover:bg-white dark:hover:bg-gray-700 hover:text-gray-800 dark:hover:text-gray-200 hover:shadow-sm'
+              : 'text-gray-300 dark:text-gray-600 cursor-not-allowed opacity-50',
+          )}
+        >
+          {publishing ? (
+            <Loader2 className="w-4 h-4 animate-spin" />
+          ) : (
+            <Globe className="w-4 h-4" />
+          )}
+        </button>
+
         {/* Export Dropdown */}
         <div className="relative" ref={exportRef}>
           <button
diff --git a/lib/hooks/use-scene-generator.ts b/lib/hooks/use-scene-generator.ts
index 1c7d540fa..b46f2870d 100644
--- a/lib/hooks/use-scene-generator.ts
+++ b/lib/hooks/use-scene-generator.ts
@@ -204,14 +204,39 @@ async function fetchSceneActions(
   return response.json();
 }
 
+/** Upload media to server cache (fire-and-forget) */
+async function uploadMediaToServer(
+  classroomId: string,
+  fileId: string,
+  base64: string,
+  ext: string,
+): Promise<void> {
+  await fetch('/api/classroom/media', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ classroomId, fileId, ext, base64 }),
+  });
+}
+
+/** Snapshot of TTS settings, used to pin voice across a batch run */
+export interface TTSOverrides {
+  providerId: TTSProviderId;
+  voice: string;
+  speed: number;
+  apiKey?: string;
+  baseUrl?: string;
+}
+
 /** Generate TTS for one speech action and store in IndexedDB */
 export async function generateAndStoreTTS(
   audioId: string,
   text: string,
   signal?: AbortSignal,
+  ttsOverrides?: TTSOverrides,
 ): Promise<void> {
   const settings = useSettingsStore.getState();
-  if (settings.ttsProviderId === 'browser-native-tts') return;
+  const providerId = ttsOverrides?.providerId ?? settings.ttsProviderId;
+  if (providerId === 'browser-native-tts') return;
 
   const ttsProviderConfig = settings.ttsProvidersConfig?.[settings.ttsProviderId];
   const response = await fetch('/api/generate/tts', {
@@ -220,11 +245,11 @@ export async function generateAndStoreTTS(
     body: JSON.stringify({
       text,
       audioId,
-      ttsProviderId: settings.ttsProviderId,
-      ttsVoice: settings.ttsVoice,
-      ttsSpeed: settings.ttsSpeed,
-      ttsApiKey: ttsProviderConfig?.apiKey || undefined,
-      ttsBaseUrl: ttsProviderConfig?.baseUrl || undefined,
+      ttsProviderId: providerId,
+      ttsVoice: ttsOverrides?.voice ?? settings.ttsVoice,
+      ttsSpeed: ttsOverrides?.speed ?? settings.ttsSpeed,
+      ttsApiKey: ttsOverrides?.apiKey ?? ttsProviderConfig?.apiKey ?? undefined,
+      ttsBaseUrl: ttsOverrides?.baseUrl ?? ttsProviderConfig?.baseUrl ?? undefined,
     }),
     signal,
   });
@@ -252,6 +277,12 @@ export async function generateAndStoreTTS(
     format: data.format,
     createdAt: Date.now(),
   });
+
+  // Fire-and-forget upload to server media cache
+  const stageId = useStageStore.getState().stage?.id;
+  if (stageId) {
+    uploadMediaToServer(stageId, audioId, data.base64, data.format).catch(() => {});
+  }
 }
 
 /** Generate TTS for all speech actions in a scene. Returns result. */
diff --git a/lib/i18n/stage.ts b/lib/i18n/stage.ts
index 5603cbc1d..5f25003fa 100644
--- a/lib/i18n/stage.ts
+++ b/lib/i18n/stage.ts
@@ -138,6 +138,10 @@ export const stageZhCN = {
   },
   share: {
     notReady: '生成完成后可分享',
+    publish: '发布为公共课',
+    publishing: '正在发布...',
+    publishSuccess: '发布成功',
+    publishFailed: '发布失败',
   },
 } as const;
 
@@ -282,5 +286,9 @@ export const stageEnUS = {
   },
   share: {
     notReady: 'Available after generation completes',
+    publish: 'Publish as public',
+    publishing: 'Publishing...',
+    publishSuccess: 'Published successfully',
+    publishFailed: 'Publish failed',
   },
 } as const;
diff --git a/lib/server/classroom-generation.ts b/lib/server/classroom-generation.ts
index 8214508fc..1dea58fdb 100644
--- a/lib/server/classroom-generation.ts
+++ b/lib/server/classroom-generation.ts
@@ -146,6 +146,11 @@ export async function generateClassroom(
     pdfText,
     undefined,
     aiCall,
+    undefined,
+    {
+      imageGenerationEnabled: true,
+      videoGenerationEnabled: false,
+    },
   );
 
   if (!outlinesResult.success || !outlinesResult.data) {
@@ -239,6 +244,7 @@ export async function generateClassroom(
       id: stageId,
       stage,
       scenes,
+      outlines,
     },
     options.baseUrl,
   );

From 54c5a6787e690890e6e0a359049e48ecff757551 Mon Sep 17 00:00:00 2001
From: zhenzhu143321 <hxcisunli@126.com>
Date: Fri, 20 Mar 2026 19:52:49 +0800
Subject: [PATCH 03/30] feat: server-side classroom storage, media cache API,
 and public listing

- Add /api/classroom/media endpoint for uploading/serving cached TTS
  and generated images/videos (idempotent, 50MB limit)
- Add media-storage module for persistent file storage under
  data/classrooms/{id}/media/
- Enhance classroom-storage with listClassrooms and readClassroom
- Homepage now displays public classrooms from server storage
- Update CLAUDE_DEPLOY_GUIDE with job persistence, media cache docs,
  and troubleshooting sections
- Add generation i18n keys for public classroom listing

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 CLAUDE_DEPLOY_GUIDE.md           |  90 +++++++++++++++++--
 app/api/classroom/media/route.ts | 100 +++++++++++++++++++++
 app/page.tsx                     | 146 ++++++++++++++++++++++++++++++-
 lib/i18n/generation.ts           |   4 +
 lib/media/media-orchestrator.ts  |  27 ++++++
 lib/server/classroom-storage.ts  |  92 +++++++++++++++++--
 lib/server/media-storage.ts      |  83 ++++++++++++++++++
 7 files changed, 529 insertions(+), 13 deletions(-)
 create mode 100644 app/api/classroom/media/route.ts
 create mode 100644 lib/server/media-storage.ts

diff --git a/CLAUDE_DEPLOY_GUIDE.md b/CLAUDE_DEPLOY_GUIDE.md
index a15710474..79ecad9f3 100644
--- a/CLAUDE_DEPLOY_GUIDE.md
+++ b/CLAUDE_DEPLOY_GUIDE.md
@@ -296,16 +296,52 @@ OpenMAIC/
 curl -X POST http://localhost:8002/api/generate-classroom \
   -H "Content-Type: application/json" \
   -d '{"requirement": "教我 Python 基础"}'
-# 返回: { "jobId": "abc123", "pollUrl": "...", "status": "queued" }
+# 返回:
+# {
+#   "success": true,
+#   "jobId": "abc123",
+#   "pollUrl": "/api/generate-classroom/abc123",
+#   "status": "queued"
+# }
 
 # 2. 轮询进度
 curl http://localhost:8002/api/generate-classroom/abc123
-# 返回: { "status": "running", "step": "generating-scenes", "progress": 0.6 }
+# 返回:
+# {
+#   "success": true,
+#   "jobId": "abc123",
+#   "status": "running",
+#   "step": "generating_scenes",
+#   "progress": 60
+# }
 
 # 3. 完成后获取课堂 URL
-# 返回: { "status": "succeeded", "result": { "classroomId": "xxx", "url": "/classroom/xxx" } }
+# 返回:
+# {
+#   "success": true,
+#   "jobId": "abc123",
+#   "status": "succeeded",
+#   "result": { "classroomId": "xxx", "url": "/classroom/xxx" }
+# }
+
+# 4. 失败时
+# 返回:
+# {
+#   "success": false,
+#   "jobId": "abc123",
+#   "status": "failed",
+#   "error": "错误描述"
+# }
 ```
 
+所有 API 响应都包含 `success: true/false` 字段。其他通用字段：
+- `jobId` — 任务唯一标识
+- `status` — 任务状态（`queued` / `running` / `succeeded` / `failed`）
+- `step` — 当前步骤（下划线格式，如 `generating_outlines`、`generating_scenes`、`generating_actions`）
+- `progress` — 整数百分比（0-100）
+- `result` — 成功时包含课堂数据
+- `error` — 失败时包含错误描述
+
 ## 9. 前端页面路由
 
 | 路由 | 说明 |
@@ -388,7 +424,7 @@ grep -i "error\|fail" /tmp/openmaic.log | tail -20
 # 检查生成任务状态
 curl -s http://localhost:8002/api/generate-classroom/{jobId} | python3 -m json.tool
 ```
-生成任务是内存中的，服务重启后任务丢失。
+生成任务持久化到 `data/classroom-jobs/` 目录，服务重启后不会丢失。系统有 30 分钟 stale 检测机制——超过 30 分钟未更新的 `running` 状态任务会被标记为 `failed`。
 
 ### 构建失败
 ```bash
@@ -401,7 +437,51 @@ pnpm install
 pnpm build
 ```
 
-## 13. 代理相关
+## 13. 公共课程与媒体缓存
+
+### 工作原理
+
+公共课程（Public Classroom）支持媒体缓存机制，避免重复生成 TTS 音频和 AI 图片：
+
+1. **首次访问**：第一个用户打开公共课程时，前端检测到缺少媒体缓存，触发 TTS 和图片生成，生成完成后自动上传到服务端
+2. **后续访问**：其他用户打开同一课程时，直接从服务端加载已缓存的媒体文件，无需重新生成
+3. **存储位置**：缓存文件存储在 `data/classrooms/{id}/media/` 目录
+
+### 相关 API
+
+```bash
+# 查询课堂媒体缓存状态
+curl http://localhost:8002/api/classroom/media?classroomId={id}
+
+# 上传媒体缓存（前端自动调用）
+curl -X POST http://localhost:8002/api/classroom/media \
+  -H "Content-Type: application/json" \
+  -d '{"classroomId": "xxx", "files": [...]}'
+```
+
+所有响应包含 `success: true/false` 字段。
+
+## 14. data/ 目录说明
+
+`data/` 目录是服务端持久化存储的根目录，位于项目根目录下：
+
+```
+data/
+├── classrooms/
+│   ├── {id}/
+│   │   ├── classroom.json    ← 课堂数据（场景、大纲、配置等）
+│   │   └── media/            ← 媒体缓存（公共课程）
+│   │       ├── tts_*.mp3     ← TTS 音频文件
+│   │       └── gen_img_*.png ← AI 生成图片
+└── classroom-jobs/
+    └── {jobId}.json          ← 生成任务状态（含 30min stale 检测）
+```
+
+- `classrooms/{id}/classroom.json` — 完整课堂数据，包括所有场景内容、智能体配置等
+- `classrooms/{id}/media/` — 公共课程的媒体缓存，首次访问时生成并上传
+- `classroom-jobs/{jobId}.json` — 异步生成任务的持久化状态，轮询 API 读取此文件
+
+## 15. 代理相关
 
 本机通过 Shadowsocks 代理访问外网：
 - HTTP 代理：`http://127.0.0.1:17891`
diff --git a/app/api/classroom/media/route.ts b/app/api/classroom/media/route.ts
new file mode 100644
index 000000000..ec03fbf02
--- /dev/null
+++ b/app/api/classroom/media/route.ts
@@ -0,0 +1,100 @@
+import { type NextRequest, NextResponse } from 'next/server';
+import { promises as fs } from 'fs';
+import path from 'path';
+import { apiSuccess, apiError, API_ERROR_CODES } from '@/lib/server/api-response';
+import { isValidClassroomId } from '@/lib/server/classroom-storage';
+import { listMedia, saveMedia, getMediaPath, mediaExists } from '@/lib/server/media-storage';
+
+const MIME_MAP: Record<string, string> = {
+  '.mp3': 'audio/mpeg',
+  '.wav': 'audio/wav',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.mp4': 'video/mp4',
+  '.webm': 'video/webm',
+};
+
+const MAX_UPLOAD_SIZE = 50 * 1024 * 1024; // 50MB
+
+export async function GET(request: NextRequest) {
+  const id = request.nextUrl.searchParams.get('id');
+  if (!id || !isValidClassroomId(id)) {
+    return apiError(API_ERROR_CODES.INVALID_REQUEST, 400, 'Invalid or missing classroom id');
+  }
+
+  const listAll = request.nextUrl.searchParams.get('list');
+  if (listAll === 'true') {
+    const files = await listMedia(id);
+    return apiSuccess({ files });
+  }
+
+  const file = request.nextUrl.searchParams.get('file');
+  if (!file) {
+    return apiError(API_ERROR_CODES.MISSING_REQUIRED_FIELD, 400, 'Missing file parameter');
+  }
+
+  // file can be either a bare fileId or fileId.ext
+  const dotIdx = file.lastIndexOf('.');
+  const fileId = dotIdx > 0 ? file.slice(0, dotIdx) : file;
+
+  const filePath = await getMediaPath(id, fileId);
+  if (!filePath) {
+    return apiError(API_ERROR_CODES.INVALID_REQUEST, 404, 'Media file not found');
+  }
+
+  const ext = path.extname(filePath).toLowerCase();
+  const contentType = MIME_MAP[ext] || 'application/octet-stream';
+
+  const stat = await fs.stat(filePath);
+  const fileBuffer = await fs.readFile(filePath);
+
+  return new NextResponse(fileBuffer, {
+    status: 200,
+    headers: {
+      'Content-Type': contentType,
+      'Content-Length': String(stat.size),
+      'Cache-Control': 'public, max-age=31536000, immutable',
+    },
+  });
+}
+
+export async function POST(request: NextRequest) {
+  try {
+    const body = await request.json();
+    const { classroomId, fileId, ext, base64 } = body;
+
+    if (!classroomId || !fileId || !ext || !base64) {
+      return apiError(
+        API_ERROR_CODES.MISSING_REQUIRED_FIELD,
+        400,
+        'Missing required fields: classroomId, fileId, ext, base64',
+      );
+    }
+
+    if (!isValidClassroomId(classroomId)) {
+      return apiError(API_ERROR_CODES.INVALID_REQUEST, 400, 'Invalid classroom id');
+    }
+
+    // Idempotent: if already exists, return 200 directly
+    const existing = await mediaExists(classroomId, fileId);
+    if (existing.exists) {
+      return apiSuccess({ fileName: existing.fullName, cached: true });
+    }
+
+    const buffer = Buffer.from(base64, 'base64');
+    if (buffer.length > MAX_UPLOAD_SIZE) {
+      return apiError(API_ERROR_CODES.INVALID_REQUEST, 400, 'File too large (max 50MB)');
+    }
+
+    const fileName = await saveMedia(classroomId, fileId, buffer, ext);
+    return apiSuccess({ fileName, cached: false }, 201);
+  } catch (error) {
+    return apiError(
+      API_ERROR_CODES.INTERNAL_ERROR,
+      500,
+      'Failed to save media',
+      error instanceof Error ? error.message : String(error),
+    );
+  }
+}
diff --git a/app/page.tsx b/app/page.tsx
index 80dfbd850..c09d95e71 100644
--- a/app/page.tsx
+++ b/app/page.tsx
@@ -9,6 +9,7 @@ import {
   ChevronDown,
   Clock,
   Copy,
+  Globe,
   ImagePlus,
   Pencil,
   Trash2,
@@ -53,6 +54,16 @@ const WEB_SEARCH_STORAGE_KEY = 'webSearchEnabled';
 const LANGUAGE_STORAGE_KEY = 'generationLanguage';
 const RECENT_OPEN_STORAGE_KEY = 'recentClassroomsOpen';
 
+interface PublicClassroomItem {
+  id: string;
+  name: string;
+  description?: string;
+  language?: string;
+  sceneCount: number;
+  createdAt: string;
+  firstSlide?: Slide | null;
+}
+
 interface FormState {
   pdfFile: File | null;
   requirement: string;
@@ -131,6 +142,8 @@ function HomePage() {
   const [error, setError] = useState<string | null>(null);
   const [classrooms, setClassrooms] = useState<StageListItem[]>([]);
   const [thumbnails, setThumbnails] = useState<Record<string, Slide>>({});
+  const [publicClassrooms, setPublicClassrooms] = useState<PublicClassroomItem[]>([]);
+  const [publicThumbnails, setPublicThumbnails] = useState<Record<string, Slide>>({});
   const [pendingDeleteId, setPendingDeleteId] = useState<string | null>(null);
   const toolbarRef = useRef<HTMLDivElement>(null);
   const textareaRef = useRef<HTMLTextAreaElement>(null);
@@ -171,6 +184,21 @@ function HomePage() {
 
     // eslint-disable-next-line react-hooks/set-state-in-effect -- Store hydration on mount
     loadClassrooms();
+
+    // Load public classrooms from server
+    fetch('/api/classroom')
+      .then(res => res.json())
+      .then(data => {
+        if (data.success && data.classrooms) {
+          setPublicClassrooms(data.classrooms);
+          const thumbs: Record<string, Slide> = {};
+          for (const c of data.classrooms) {
+            if (c.firstSlide) thumbs[c.id] = c.firstSlide;
+          }
+          setPublicThumbnails(thumbs);
+        }
+      })
+      .catch(() => {});
   }, []);
 
   const handleDelete = (id: string, e: React.MouseEvent) => {
@@ -489,7 +517,7 @@ function HomePage() {
         transition={{ duration: 0.6, ease: 'easeOut' }}
         className={cn(
           'relative z-20 w-full max-w-[800px] flex flex-col items-center',
-          classrooms.length === 0 ? 'justify-center min-h-[calc(100dvh-8rem)]' : 'mt-[10vh]',
+          classrooms.length === 0 && publicClassrooms.length === 0 ? 'justify-center min-h-[calc(100dvh-8rem)]' : 'mt-[10vh]',
         )}
       >
         {/* ── Logo ── */}
@@ -607,6 +635,43 @@ function HomePage() {
         </AnimatePresence>
       </motion.div>
 
+      {/* ═══ Public classrooms ═══ */}
+      {publicClassrooms.length > 0 && (
+        <motion.div
+          initial={{ opacity: 0 }}
+          animate={{ opacity: 1 }}
+          transition={{ delay: 0.45 }}
+          className="relative z-10 mt-10 w-full max-w-6xl flex flex-col items-center"
+        >
+          <div className="w-full flex items-center gap-4 py-2">
+            <div className="flex-1 h-px bg-border/40" />
+            <span className="shrink-0 flex items-center gap-2 text-[13px] text-muted-foreground/60 select-none">
+              <Globe className="size-3.5" />
+              {t('classroom.publicClassrooms')}
+              <span className="text-[11px] tabular-nums opacity-60">{publicClassrooms.length}</span>
+            </span>
+            <div className="flex-1 h-px bg-border/40" />
+          </div>
+
+          <div className="pt-8 grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-x-5 gap-y-8 w-full">
+            {publicClassrooms.map((pc, i) => (
+              <motion.div
+                key={pc.id}
+                initial={{ opacity: 0, y: 16 }}
+                animate={{ opacity: 1, y: 0 }}
+                transition={{ delay: i * 0.04, duration: 0.35, ease: 'easeOut' }}
+              >
+                <PublicClassroomCard
+                  classroom={pc}
+                  slide={publicThumbnails[pc.id]}
+                  onClick={() => router.push(`/classroom/${pc.id}`)}
+                />
+              </motion.div>
+            ))}
+          </div>
+        </motion.div>
+      )}
+
       {/* ═══ Recent classrooms — collapsible ═══ */}
       {classrooms.length > 0 && (
         <motion.div
@@ -982,6 +1047,85 @@ function GreetingBar() {
   );
 }
 
+// ─── Public Classroom Card — no delete button ───────────────────
+function PublicClassroomCard({
+  classroom,
+  slide,
+  onClick,
+}: {
+  classroom: PublicClassroomItem;
+  slide?: Slide;
+  onClick: () => void;
+}) {
+  const { t } = useI18n();
+  const thumbRef = useRef<HTMLDivElement>(null);
+  const [thumbWidth, setThumbWidth] = useState(0);
+
+  useEffect(() => {
+    const el = thumbRef.current;
+    if (!el) return;
+    const ro = new ResizeObserver(([entry]) => {
+      setThumbWidth(Math.round(entry.contentRect.width));
+    });
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, []);
+
+  const formatCreatedAt = (iso: string) => {
+    const date = new Date(iso);
+    const now = new Date();
+    const diffDays = Math.floor((now.getTime() - date.getTime()) / (1000 * 60 * 60 * 24));
+    if (diffDays === 0) return t('classroom.today');
+    if (diffDays === 1) return t('classroom.yesterday');
+    if (diffDays < 7) return `${diffDays} ${t('classroom.daysAgo')}`;
+    return date.toLocaleDateString();
+  };
+
+  return (
+    <div className="group cursor-pointer" onClick={onClick}>
+      <div
+        ref={thumbRef}
+        className="relative w-full aspect-[16/9] rounded-2xl bg-slate-100 dark:bg-slate-800/80 overflow-hidden transition-transform duration-200 group-hover:scale-[1.02]"
+      >
+        {slide && thumbWidth > 0 ? (
+          <ThumbnailSlide
+            slide={slide}
+            size={thumbWidth}
+            viewportSize={slide.viewportSize ?? 1000}
+            viewportRatio={slide.viewportRatio ?? 0.5625}
+          />
+        ) : !slide ? (
+          <div className="absolute inset-0 flex items-center justify-center">
+            <div className="size-12 rounded-2xl bg-gradient-to-br from-violet-100 to-blue-100 dark:from-violet-900/30 dark:to-blue-900/30 flex items-center justify-center">
+              <span className="text-xl opacity-50">📄</span>
+            </div>
+          </div>
+        ) : null}
+      </div>
+
+      <div className="mt-2.5 px-1 flex items-center gap-2">
+        <span className="shrink-0 inline-flex items-center rounded-full bg-violet-100 dark:bg-violet-900/30 px-2 py-0.5 text-[11px] font-medium text-violet-600 dark:text-violet-400">
+          {classroom.sceneCount} {t('classroom.slides')} · {formatCreatedAt(classroom.createdAt)}
+        </span>
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <p className="font-medium text-[15px] truncate text-foreground/90 min-w-0">
+              {classroom.name}
+            </p>
+          </TooltipTrigger>
+          <TooltipContent
+            side="bottom"
+            sideOffset={4}
+            className="!max-w-[min(90vw,32rem)] break-words whitespace-normal"
+          >
+            {classroom.name}
+          </TooltipContent>
+        </Tooltip>
+      </div>
+    </div>
+  );
+}
+
 // ─── Classroom Card — clean, minimal style ──────────────────────
 function ClassroomCard({
   classroom,
diff --git a/lib/i18n/generation.ts b/lib/i18n/generation.ts
index 1ed17f351..43d60a4b3 100644
--- a/lib/i18n/generation.ts
+++ b/lib/i18n/generation.ts
@@ -8,6 +8,8 @@ export const generationZhCN = {
     nameCopied: '课堂名称已复制',
     deleteConfirmTitle: '删除课堂',
     delete: '删除',
+    publicClassrooms: '公共课程',
+    noPublicClassrooms: '暂无公共课程',
   },
   upload: {
     pdfSizeLimit: '支持最大50MB的PDF文件',
@@ -72,6 +74,8 @@ export const generationEnUS = {
     nameCopied: 'Name copied',
     deleteConfirmTitle: 'Delete',
     delete: 'Delete',
+    publicClassrooms: 'Public Classrooms',
+    noPublicClassrooms: 'No public classrooms yet',
   },
   upload: {
     pdfSizeLimit: 'Supports PDF files up to 50MB',
diff --git a/lib/media/media-orchestrator.ts b/lib/media/media-orchestrator.ts
index 151a3acab..6c30bd28f 100644
--- a/lib/media/media-orchestrator.ts
+++ b/lib/media/media-orchestrator.ts
@@ -152,6 +152,11 @@ async function generateSingleMedia(
     const objectUrl = URL.createObjectURL(blob);
     const posterObjectUrl = posterBlob ? URL.createObjectURL(posterBlob) : undefined;
     useMediaGenerationStore.getState().markDone(req.elementId, objectUrl, posterObjectUrl);
+
+    // Fire-and-forget upload to server media cache
+    uploadBlobToServer(stageId, req.elementId, blob, req.type === 'image' ? 'png' : 'mp4').catch(
+      () => {},
+    );
   } catch (err) {
     if (abortSignal?.aborted) return;
     const message = err instanceof Error ? err.message : String(err);
@@ -284,3 +289,25 @@ async function fetchAsBlob(url: string): Promise<Blob> {
   if (!res.ok) throw new Error(`Failed to fetch blob: ${res.status}`);
   return res.blob();
 }
+
+/** Convert blob to base64 and upload to server media cache */
+async function uploadBlobToServer(
+  classroomId: string,
+  fileId: string,
+  blob: Blob,
+  ext: string,
+): Promise<void> {
+  const buffer = await blob.arrayBuffer();
+  const bytes = new Uint8Array(buffer);
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  const base64 = btoa(binary);
+
+  await fetch('/api/classroom/media', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ classroomId, fileId, ext, base64 }),
+  });
+}
diff --git a/lib/server/classroom-storage.ts b/lib/server/classroom-storage.ts
index 41e3e8c9e..0c8f7bc4b 100644
--- a/lib/server/classroom-storage.ts
+++ b/lib/server/classroom-storage.ts
@@ -1,7 +1,9 @@
 import { promises as fs } from 'fs';
 import path from 'path';
 import type { NextRequest } from 'next/server';
-import type { Scene, Stage } from '@/lib/types/stage';
+import type { Scene, Stage, SlideContent } from '@/lib/types/stage';
+import type { Slide } from '@/lib/types/slides';
+import type { SceneOutline } from '@/lib/types/generation';
 
 export const CLASSROOMS_DIR = path.join(process.cwd(), 'data', 'classrooms');
 export const CLASSROOM_JOBS_DIR = path.join(process.cwd(), 'data', 'classroom-jobs');
@@ -38,6 +40,7 @@ export interface PersistedClassroomData {
   id: string;
   stage: Stage;
   scenes: Scene[];
+  outlines?: SceneOutline[];
   createdAt: string;
 }
 
@@ -46,23 +49,97 @@ export function isValidClassroomId(id: string): boolean {
 }
 
 export async function readClassroom(id: string): Promise<PersistedClassroomData | null> {
-  const filePath = path.join(CLASSROOMS_DIR, `${id}.json`);
+  // New path: data/classrooms/{id}/classroom.json
+  const newPath = path.join(CLASSROOMS_DIR, id, 'classroom.json');
   try {
-    const content = await fs.readFile(filePath, 'utf-8');
+    const content = await fs.readFile(newPath, 'utf-8');
     return JSON.parse(content) as PersistedClassroomData;
   } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
-      return null;
-    }
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+  }
+  // Fallback: old path data/classrooms/{id}.json
+  const oldPath = path.join(CLASSROOMS_DIR, `${id}.json`);
+  try {
+    const content = await fs.readFile(oldPath, 'utf-8');
+    return JSON.parse(content) as PersistedClassroomData;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
     throw error;
   }
 }
 
+export interface ClassroomListItem {
+  id: string;
+  name: string;
+  description?: string;
+  language?: string;
+  sceneCount: number;
+  createdAt: string;
+  firstSlide?: Slide | null;
+}
+
+export async function listClassrooms(): Promise<ClassroomListItem[]> {
+  await ensureClassroomsDir();
+  const entries = await fs.readdir(CLASSROOMS_DIR, { withFileTypes: true });
+  const items: ClassroomListItem[] = [];
+
+  // New format: subdirectories with classroom.json
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      const jsonPath = path.join(CLASSROOMS_DIR, entry.name, 'classroom.json');
+      try {
+        const content = await fs.readFile(jsonPath, 'utf-8');
+        const data = JSON.parse(content) as PersistedClassroomData;
+        const firstSlideScene = data.scenes?.find(s => s.content?.type === 'slide');
+        items.push({
+          id: data.id,
+          name: data.stage?.name || 'Untitled',
+          description: data.stage?.description,
+          language: data.stage?.language,
+          sceneCount: data.scenes?.length || 0,
+          createdAt: data.createdAt,
+          firstSlide: firstSlideScene?.content?.type === 'slide'
+            ? (firstSlideScene.content as SlideContent).canvas
+            : null,
+        });
+      } catch { /* skip if no classroom.json */ }
+    }
+  }
+
+  // Backward compat: also read old flat .json files
+  for (const entry of entries) {
+    if (!entry.isDirectory() && entry.name.endsWith('.json')) {
+      const id = entry.name.replace('.json', '');
+      if (items.some(item => item.id === id)) continue; // already found in new format
+      try {
+        const content = await fs.readFile(path.join(CLASSROOMS_DIR, entry.name), 'utf-8');
+        const data = JSON.parse(content) as PersistedClassroomData;
+        const firstSlideScene = data.scenes?.find(s => s.content?.type === 'slide');
+        items.push({
+          id: data.id,
+          name: data.stage?.name || 'Untitled',
+          description: data.stage?.description,
+          language: data.stage?.language,
+          sceneCount: data.scenes?.length || 0,
+          createdAt: data.createdAt,
+          firstSlide: firstSlideScene?.content?.type === 'slide'
+            ? (firstSlideScene.content as SlideContent).canvas
+            : null,
+        });
+      } catch { /* skip corrupt files */ }
+    }
+  }
+
+  items.sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
+  return items;
+}
+
 export async function persistClassroom(
   data: {
     id: string;
     stage: Stage;
     scenes: Scene[];
+    outlines?: SceneOutline[];
   },
   baseUrl: string,
 ): Promise<PersistedClassroomData & { url: string }> {
@@ -70,11 +147,12 @@ export async function persistClassroom(
     id: data.id,
     stage: data.stage,
     scenes: data.scenes,
+    outlines: data.outlines,
     createdAt: new Date().toISOString(),
   };
 
   await ensureClassroomsDir();
-  const filePath = path.join(CLASSROOMS_DIR, `${data.id}.json`);
+  const filePath = path.join(CLASSROOMS_DIR, data.id, 'classroom.json');
   await writeJsonFileAtomic(filePath, classroomData);
 
   return {
diff --git a/lib/server/media-storage.ts b/lib/server/media-storage.ts
new file mode 100644
index 000000000..8c3f02f23
--- /dev/null
+++ b/lib/server/media-storage.ts
@@ -0,0 +1,83 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import { CLASSROOMS_DIR } from './classroom-storage';
+
+const VALID_FILE_ID = /^[a-zA-Z0-9_-]+$/;
+const KNOWN_EXTENSIONS = ['.mp3', '.wav', '.png', '.mp4', '.jpg', '.webp', '.webm'];
+
+export function getMediaDir(classroomId: string): string {
+  return path.join(CLASSROOMS_DIR, classroomId, 'media');
+}
+
+export async function mediaExists(
+  classroomId: string,
+  fileId: string,
+): Promise<{ exists: boolean; fullName?: string }> {
+  if (!VALID_FILE_ID.test(fileId)) return { exists: false };
+
+  const dir = getMediaDir(classroomId);
+  for (const ext of KNOWN_EXTENSIONS) {
+    const filePath = path.join(dir, `${fileId}${ext}`);
+    try {
+      await fs.access(filePath);
+      return { exists: true, fullName: `${fileId}${ext}` };
+    } catch {
+      // try next extension
+    }
+  }
+  return { exists: false };
+}
+
+export async function saveMedia(
+  classroomId: string,
+  fileId: string,
+  buffer: Buffer,
+  ext: string,
+): Promise<string> {
+  if (!VALID_FILE_ID.test(fileId)) {
+    throw new Error('Invalid fileId: only [a-zA-Z0-9_-] allowed');
+  }
+
+  const normalizedExt = ext.startsWith('.') ? ext : `.${ext}`;
+  const dir = getMediaDir(classroomId);
+  await fs.mkdir(dir, { recursive: true });
+
+  const fileName = `${fileId}${normalizedExt}`;
+  const filePath = path.join(dir, fileName);
+  const tmpPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+
+  await fs.writeFile(tmpPath, buffer);
+  await fs.rename(tmpPath, filePath);
+
+  return fileName;
+}
+
+export async function getMediaPath(
+  classroomId: string,
+  fileId: string,
+): Promise<string | null> {
+  if (!VALID_FILE_ID.test(fileId)) return null;
+
+  const dir = getMediaDir(classroomId);
+  for (const ext of KNOWN_EXTENSIONS) {
+    const filePath = path.join(dir, `${fileId}${ext}`);
+    try {
+      await fs.access(filePath);
+      return filePath;
+    } catch {
+      // try next
+    }
+  }
+  return null;
+}
+
+export async function listMedia(classroomId: string): Promise<string[]> {
+  const dir = getMediaDir(classroomId);
+  try {
+    const files = await fs.readdir(dir);
+    return files.filter((f) => !f.endsWith('.tmp'));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+    throw error;
+  }
+}

From 4cd084f34f7f6c4679f3ba4d3015be4b40671023 Mon Sep 17 00:00:00 2001
From: zhenzhu143321 <hxcisunli@126.com>
Date: Fri, 20 Mar 2026 22:57:58 +0800
Subject: [PATCH 04/30] fix: remove leaked API key from deploy guide and
 untrack file

- Replace hardcoded QN API key with $QN_API_KEY env var reference
- Mask key prefix in .env.local status section (sk-****)
- Correct proxy docs: global HTTP_PROXY only for Tavily/pnpm, LLM proxy is per-provider in YAML
- Update provider count to 11 (qn already built-in), use myProvider as example
- Add note that QN_* vars need manual addition to .env.local
- Fix frontend storage description: settings in localStorage, classroom data in IndexedDB
- Add CLAUDE_DEPLOY_GUIDE.md to .gitignore and untrack it (contains machine-specific config)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .gitignore             |   3 +
 CLAUDE_DEPLOY_GUIDE.md | 501 -----------------------------------------
 2 files changed, 3 insertions(+), 501 deletions(-)
 delete mode 100644 CLAUDE_DEPLOY_GUIDE.md

diff --git a/.gitignore b/.gitignore
index 86c2726c6..491aec2fe 100644
--- a/.gitignore
+++ b/.gitignore
@@ -61,3 +61,6 @@ next-env.d.ts
 
 # docs
 /docs
+
+# local deploy guide (contains machine-specific config)
+CLAUDE_DEPLOY_GUIDE.md
diff --git a/CLAUDE_DEPLOY_GUIDE.md b/CLAUDE_DEPLOY_GUIDE.md
deleted file mode 100644
index 79ecad9f3..000000000
--- a/CLAUDE_DEPLOY_GUIDE.md
+++ /dev/null
@@ -1,501 +0,0 @@
-# OpenMAIC 部署与自定义 Provider 操作教程
-
-> 供 Claude 实例参考的操作手册，基于实际部署经验总结。
-
-## 1. 项目概览
-
-- 项目地址：`/home/sunli/MyWork/myproject/OpenMAIC/`
-- GitHub：`https://github.com/THU-MAIC/OpenMAIC`
-- 技术栈：Next.js 16 + React 19 + TypeScript + LangGraph + pnpm
-- 服务端口：8002
-- 访问地址：`http://172.16.29.100:8002`
-
-## 2. 部署步骤
-
-### 环境要求
-- Node.js >= 20（当前 v20.19.6）
-- pnpm >= 10（通过 `sudo corepack enable pnpm` 启用）
-
-### 克隆与安装
-```bash
-# 需要代理访问 GitHub
-export http_proxy="http://127.0.0.1:17891" https_proxy="http://127.0.0.1:17891"
-git clone https://github.com/THU-MAIC/OpenMAIC.git
-cd OpenMAIC
-pnpm install
-```
-
-### 配置
-```bash
-cp .env.example .env.local
-# 编辑 .env.local 填入 LLM provider 配置
-```
-
-### 构建与启动
-```bash
-pnpm build
-# 后台启动，指定端口 8002
-nohup pnpm start -p 8002 > /tmp/openmaic.log 2>&1 &
-```
-
-### 停止服务
-```bash
-pkill -f "next-server"
-```
-
-## 3. 新增自定义 LLM Provider（以七牛云 QN 为例）
-
-OpenMAIC 内置了 10 个 provider（openai, anthropic, google, deepseek, qwen, kimi, minimax, glm, siliconflow, doubao）。如果要接入新的 OpenAI 兼容 API，需要改 4 个文件。
-
-### 3.1 `lib/types/provider.ts` — 添加 Provider ID
-
-在 `BuiltInProviderId` 联合类型中添加新 ID：
-
-```typescript
-export type BuiltInProviderId =
-  | 'openai'
-  | 'anthropic'
-  // ...existing...
-  | 'doubao'
-  | 'qn';       // ← 新增
-```
-
-### 3.2 `lib/ai/providers.ts` — 注册 Provider 配置
-
-在 `PROVIDERS` 对象末尾（`doubao` 之后，`};` 之前）添加：
-
-```typescript
-qn: {
-  id: 'qn',
-  name: 'QN (七牛云)',
-  type: 'openai',                          // OpenAI 兼容接口
-  defaultBaseUrl: 'https://api.qnaigc.com/v1',
-  requiresApiKey: true,
-  icon: '/logos/qwen.svg',                 // 暂用已有图标
-  models: [
-    {
-      id: 'gemini-3.1-pro-preview',
-      name: 'Gemini 3.1 Pro Preview',
-      contextWindow: 1048576,
-      capabilities: { streaming: true, tools: true, vision: false },
-    },
-    {
-      id: 'deepseek-v3.1',
-      name: 'DeepSeek V3.1',
-      contextWindow: 128000,
-      capabilities: { streaming: true, tools: true, vision: false },
-    },
-    // ...更多模型按需添加
-  ],
-},
-```
-
-关键字段说明：
-- `type: 'openai'` — 使用 `@ai-sdk/openai` 的 `createOpenAI` 创建客户端，兼容所有 OpenAI API 格式的服务
-- `type: 'anthropic'` — 使用 `@ai-sdk/anthropic`
-- `type: 'google'` — 使用 `@ai-sdk/google`
-- `models` — 前端模型选择列表，ID 必须与 API 实际支持的模型名一致
-
-### 3.3 `lib/server/provider-config.ts` — 添加环境变量映射
-
-在 `LLM_ENV_MAP` 中添加映射（key 是环境变量前缀，value 是 provider ID）：
-
-```typescript
-const LLM_ENV_MAP: Record<string, string> = {
-  OPENAI: 'openai',
-  // ...existing...
-  DOUBAO: 'doubao',
-  QN: 'qn',        // ← 新增：QN_API_KEY, QN_BASE_URL, QN_MODELS
-};
-```
-
-这样系统会自动读取 `QN_API_KEY`、`QN_BASE_URL`、`QN_MODELS` 环境变量。
-
-### 3.4 `.env.local` — 配置 API 密钥
-
-```env
-QN_API_KEY=sk-your-api-key-here
-QN_BASE_URL=https://api.qnaigc.com/v1
-QN_MODELS=                                 # 留空则显示 providers.ts 中定义的所有模型
-
-# 设置默认模型（格式：providerId:modelId）
-DEFAULT_MODEL=qn:gemini-3.1-pro-preview
-```
-
-## 4. 架构要点（供理解代码用）
-
-### 配置加载流程
-```
-.env.local / server-providers.yml
-    ↓
-lib/server/provider-config.ts    （服务端加载，缓存在内存）
-    ↓
-GET /api/server-providers        （返回 provider ID + metadata，不暴露 API key）
-    ↓
-lib/store/settings.ts            （前端 Zustand store，合并到 providersConfig）
-    ↓
-前端 UI 显示 provider 列表
-```
-
-### 模型调用流程
-```
-前端选择 model → POST /api/chat (body: { model: "qn:gemini-3.1-pro-preview" })
-    ↓
-lib/server/resolve-model.ts      （解析 modelString，获取 apiKey/baseUrl）
-    ↓
-lib/ai/providers.ts getModel()   （根据 provider.type 创建对应 SDK 客户端）
-    ↓
-createOpenAI({ apiKey, baseURL }) → 调用 QN API
-```
-
-### 关键文件索引
-| 文件 | 作用 |
-|------|------|
-| `lib/types/provider.ts` | Provider/Model 类型定义 |
-| `lib/ai/providers.ts` | Provider 注册表 + getModel() |
-| `lib/server/provider-config.ts` | 服务端配置加载（env + yaml） |
-| `lib/server/resolve-model.ts` | API 路由中的模型解析 |
-| `lib/store/settings.ts` | 前端设置 store（Zustand） |
-| `lib/types/settings.ts` | ProviderSettings 类型 |
-| `app/api/server-providers/route.ts` | 暴露 provider 元数据的 API |
-| `app/api/chat/route.ts` | 聊天 API 路由 |
-
-### 自动机制（不需要手动改）
-- `getDefaultProvidersConfig()` — 遍历 `PROVIDERS` 自动生成前端初始配置
-- `ensureBuiltInProviders()` — 每次 rehydrate 自动合并新增的 provider
-- `fetchServerProviders()` — 前端自动标记 `isServerConfigured`，显示"管理员已配置"
-
-## 5. 常用操作
-
-### 查看 QN API 可用模型
-```bash
-export http_proxy="http://127.0.0.1:17891" https_proxy="http://127.0.0.1:17891"
-curl -s https://api.qnaigc.com/v1/models \
-  -H "Authorization: Bearer $QN_API_KEY" | python3 -m json.tool
-```
-
-### 验证 server-providers API
-```bash
-curl -s http://localhost:8002/api/server-providers | python3 -m json.tool
-```
-
-### 健康检查
-```bash
-curl -s http://localhost:8002/api/health
-```
-
-### 重新构建部署
-```bash
-pkill -f "next-server"
-cd /home/sunli/MyWork/myproject/OpenMAIC
-pnpm build
-nohup pnpm start -p 8002 > /tmp/openmaic.log 2>&1 &
-```
-
-## 6. 注意事项
-
-- `OPENAI_MODELS` 等 `*_MODELS` 环境变量如果设了值，前端会用 `filter` 从内置模型列表筛选。如果模型 ID 不在内置列表里，会被过滤掉导致列表为空。所以自定义 provider 的模型必须在 `providers.ts` 的 `models` 数组中注册。
-- `DEFAULT_MODEL` 只影响服务端 API 的 fallback 模型（`resolve-model.ts:30`），不影响前端 UI 默认选择。
-- 前端首次加载时，如果用户没选过模型，会自动选择第一个 `isServerConfigured` 的 provider 的第一个模型。
-- `.env.local` 已在 `.gitignore` 中（`.env*` 规则），不会被提交。
-- 构建需要代理：`export http_proxy="http://127.0.0.1:17891" https_proxy="http://127.0.0.1:17891"`
-
-## 7. 项目目录结构
-
-```
-OpenMAIC/
-├── app/                          # Next.js App Router
-│   ├── api/                      #   服务端 API 路由
-│   │   ├── chat/route.ts         #     多智能体聊天（SSE 流式）
-│   │   ├── generate-classroom/   #     异步课堂生成（提交 + 轮询）
-│   │   ├── generate/             #     场景生成流水线
-│   │   │   ├── scene-outlines-stream/  # 大纲生成
-│   │   │   ├── scene-content/    #     场景内容生成
-│   │   │   ├── scene-actions/    #     场景动作生成
-│   │   │   ├── agent-profiles/   #     智能体角色生成
-│   │   │   ├── tts/              #     语音合成
-│   │   │   └── image/            #     图片生成
-│   │   ├── quiz-grade/           #     测验评分
-│   │   ├── parse-pdf/            #     PDF 解析
-│   │   ├── pbl/                  #     项目制学习
-│   │   ├── web-search/           #     网络搜索
-│   │   ├── transcription/        #     语音识别
-│   │   ├── server-providers/     #     Provider 元数据 API
-│   │   ├── health/               #     健康检查
-│   │   ├── verify-model/         #     模型验证
-│   │   └── classroom/            #     课堂数据 API
-│   ├── classroom/[id]/           #   课堂页面（动态路由）
-│   ├── generation-preview/       #   生成预览页面
-│   ├── layout.tsx                #   根布局
-│   └── page.tsx                  #   首页
-├── components/                   # React 组件
-│   ├── classroom/                #   课堂相关组件（slides, quiz, interactive, pbl）
-│   ├── generation/               #   课堂生成 UI
-│   ├── settings/                 #   设置面板
-│   └── ui/                       #   通用 UI 组件（shadcn/radix）
-├── lib/                          # 核心库
-│   ├── ai/                       #   AI Provider 注册 + 模型创建
-│   │   └── providers.ts          #     ★ PROVIDERS 注册表 + getModel()
-│   ├── server/                   #   服务端工具
-│   │   ├── provider-config.ts    #     ★ 环境变量/YAML 配置加载
-│   │   └── resolve-model.ts      #     ★ 模型解析（DEFAULT_MODEL fallback）
-│   ├── store/                    #   前端状态管理
-│   │   └── settings.ts           #     ★ Zustand store（provider/model 选择）
-│   ├── types/                    #   TypeScript 类型定义
-│   │   ├── provider.ts           #     ★ ProviderId, ModelInfo 等
-│   │   └── settings.ts           #     ProviderSettings 类型
-│   ├── generation/               #   课堂生成逻辑（大纲→场景→内容）
-│   ├── orchestration/            #   多智能体编排（LangGraph）
-│   ├── chat/                     #   聊天逻辑
-│   ├── audio/                    #   TTS/ASR 音频处理
-│   ├── pdf/                      #   PDF 解析（unpdf/MinerU）
-│   ├── media/                    #   图片/视频生成
-│   ├── export/                   #   导出（PPTX/HTML）
-│   ├── playback/                 #   课堂回放控制
-│   ├── i18n/                     #   国际化（中/英）
-│   ├── web-search/               #   网络搜索（Tavily）
-│   └── utils/                    #   通用工具函数
-├── packages/                     # workspace 子包
-│   ├── mathml2omml/              #   MathML → OMML 转换（PPTX 公式）
-│   └── pptxgenjs/                #   PPTX 生成（fork 版）
-├── public/logos/                 # Provider 图标（SVG/PNG）
-├── .env.example                  # 环境变量模板
-├── .env.local                    # 实际配置（gitignored）
-├── next.config.ts                # Next.js 配置
-├── package.json                  # 依赖（pnpm workspace）
-└── CLAUDE_DEPLOY_GUIDE.md        # 本文档
-```
-
-标 ★ 的是修改最频繁的核心文件。
-
-## 8. 课堂生成流程
-
-这是 OpenMAIC 的核心功能，理解它对排查问题至关重要。
-
-### 两阶段流水线
-```
-用户输入主题/上传PDF
-    ↓
-[阶段1] 大纲生成
-    POST /api/generate/scene-outlines-stream
-    → LLM 分析输入，生成结构化大纲（SSE 流式返回）
-    ↓
-[阶段2] 场景生成（并行）
-    对每个大纲条目：
-    ├── POST /api/generate/scene-content    → 生成场景内容（slides/quiz/interactive/pbl）
-    ├── POST /api/generate/scene-actions    → 生成教师动作（激光笔、聚光灯等）
-    ├── POST /api/generate/agent-profiles   → 生成智能体角色
-    └── POST /api/generate/tts              → 生成语音
-    ↓
-课堂就绪，跳转 /classroom/{id}
-```
-
-### 异步生成模式（API 调用）
-```bash
-# 1. 提交生成任务
-curl -X POST http://localhost:8002/api/generate-classroom \
-  -H "Content-Type: application/json" \
-  -d '{"requirement": "教我 Python 基础"}'
-# 返回:
-# {
-#   "success": true,
-#   "jobId": "abc123",
-#   "pollUrl": "/api/generate-classroom/abc123",
-#   "status": "queued"
-# }
-
-# 2. 轮询进度
-curl http://localhost:8002/api/generate-classroom/abc123
-# 返回:
-# {
-#   "success": true,
-#   "jobId": "abc123",
-#   "status": "running",
-#   "step": "generating_scenes",
-#   "progress": 60
-# }
-
-# 3. 完成后获取课堂 URL
-# 返回:
-# {
-#   "success": true,
-#   "jobId": "abc123",
-#   "status": "succeeded",
-#   "result": { "classroomId": "xxx", "url": "/classroom/xxx" }
-# }
-
-# 4. 失败时
-# 返回:
-# {
-#   "success": false,
-#   "jobId": "abc123",
-#   "status": "failed",
-#   "error": "错误描述"
-# }
-```
-
-所有 API 响应都包含 `success: true/false` 字段。其他通用字段：
-- `jobId` — 任务唯一标识
-- `status` — 任务状态（`queued` / `running` / `succeeded` / `failed`）
-- `step` — 当前步骤（下划线格式，如 `generating_outlines`、`generating_scenes`、`generating_actions`）
-- `progress` — 整数百分比（0-100）
-- `result` — 成功时包含课堂数据
-- `error` — 失败时包含错误描述
-
-## 9. 前端页面路由
-
-| 路由 | 说明 |
-|------|------|
-| `/` | 首页 — 输入主题或上传 PDF 生成课堂 |
-| `/classroom/[id]` | 课堂页面 — 幻灯片、测验、互动、PBL |
-| `/generation-preview` | 生成预览 — 查看大纲和场景生成进度 |
-
-前端状态全部存在浏览器 localStorage（key: `settings-storage`），通过 Zustand persist 中间件管理。清除浏览器缓存会重置所有设置。
-
-## 10. 多智能体系统
-
-### 编排引擎
-- 基于 LangGraph（`lib/orchestration/`）
-- 支持多个 AI 智能体角色（教师、学生、助教等）
-- 聊天通过 SSE 流式传输（`app/api/chat/route.ts`）
-
-### 场景类型
-| 类型 | 说明 | 关键组件 |
-|------|------|----------|
-| slides | 幻灯片演示 | `components/classroom/slides/` |
-| quiz | 交互测验 | `components/classroom/quiz/` |
-| interactive | HTML 交互模拟 | `components/classroom/interactive/` |
-| pbl | 项目制学习 | `components/classroom/pbl/` |
-
-## 11. 当前 .env.local 配置状态
-
-```env
-# 已配置（有效）
-QN_API_KEY=sk-ebad...（七牛云 API）
-QN_BASE_URL=https://api.qnaigc.com/v1
-DEFAULT_MODEL=qn:gemini-3.1-pro-preview
-
-# 未配置（留空）
-OPENAI_API_KEY=        # 如需 OpenAI 原生模型
-ANTHROPIC_API_KEY=     # 如需 Claude 模型
-GOOGLE_API_KEY=        # 如需 Gemini 模型（直连 Google）
-# TTS/ASR/PDF/Image/Video 均未配置
-```
-
-如需添加更多 provider，直接在 `.env.local` 填入对应的 `{PROVIDER}_API_KEY` 即可，无需改代码（前提是该 provider 已在内置列表中）。
-
-## 12. 故障排查
-
-### 服务无法启动
-```bash
-# 查看日志
-tail -50 /tmp/openmaic.log
-
-# 检查端口占用
-ss -tlnp | grep 8002
-
-# 杀掉残留进程
-pkill -f "next-server"
-```
-
-### 模型调用失败
-```bash
-# 1. 确认 provider 配置正确
-curl -s http://localhost:8002/api/server-providers | python3 -m json.tool
-
-# 2. 直接测试 QN API 连通性（需代理）
-export http_proxy="http://127.0.0.1:17891" https_proxy="http://127.0.0.1:17891"
-curl -s https://api.qnaigc.com/v1/chat/completions \
-  -H "Authorization: Bearer sk-ebad216962663702e91a69addd28b51c85c3b6b01a3e6dd623cdf89f319bade5" \
-  -H "Content-Type: application/json" \
-  -d '{"model":"gemini-3.1-pro-preview","messages":[{"role":"user","content":"hi"}],"max_tokens":10}'
-
-# 3. 检查服务端日志中的错误
-grep -i "error\|fail" /tmp/openmaic.log | tail -20
-```
-
-### 前端不显示新 provider
-- 清除浏览器 localStorage（开发者工具 → Application → Storage → Clear site data）
-- 或删除 `settings-storage` key
-- 确认已重新 `pnpm build` 并重启服务
-
-### 课堂生成卡住
-```bash
-# 检查生成任务状态
-curl -s http://localhost:8002/api/generate-classroom/{jobId} | python3 -m json.tool
-```
-生成任务持久化到 `data/classroom-jobs/` 目录，服务重启后不会丢失。系统有 30 分钟 stale 检测机制——超过 30 分钟未更新的 `running` 状态任务会被标记为 `failed`。
-
-### 构建失败
-```bash
-# TypeScript 类型错误：检查新增的 provider ID 是否在所有相关文件中一致
-# 常见遗漏：lib/types/provider.ts 的 BuiltInProviderId 忘记添加
-
-# 依赖问题：清理重装
-rm -rf node_modules .next
-pnpm install
-pnpm build
-```
-
-## 13. 公共课程与媒体缓存
-
-### 工作原理
-
-公共课程（Public Classroom）支持媒体缓存机制，避免重复生成 TTS 音频和 AI 图片：
-
-1. **首次访问**：第一个用户打开公共课程时，前端检测到缺少媒体缓存，触发 TTS 和图片生成，生成完成后自动上传到服务端
-2. **后续访问**：其他用户打开同一课程时，直接从服务端加载已缓存的媒体文件，无需重新生成
-3. **存储位置**：缓存文件存储在 `data/classrooms/{id}/media/` 目录
-
-### 相关 API
-
-```bash
-# 查询课堂媒体缓存状态
-curl http://localhost:8002/api/classroom/media?classroomId={id}
-
-# 上传媒体缓存（前端自动调用）
-curl -X POST http://localhost:8002/api/classroom/media \
-  -H "Content-Type: application/json" \
-  -d '{"classroomId": "xxx", "files": [...]}'
-```
-
-所有响应包含 `success: true/false` 字段。
-
-## 14. data/ 目录说明
-
-`data/` 目录是服务端持久化存储的根目录，位于项目根目录下：
-
-```
-data/
-├── classrooms/
-│   ├── {id}/
-│   │   ├── classroom.json    ← 课堂数据（场景、大纲、配置等）
-│   │   └── media/            ← 媒体缓存（公共课程）
-│   │       ├── tts_*.mp3     ← TTS 音频文件
-│   │       └── gen_img_*.png ← AI 生成图片
-└── classroom-jobs/
-    └── {jobId}.json          ← 生成任务状态（含 30min stale 检测）
-```
-
-- `classrooms/{id}/classroom.json` — 完整课堂数据，包括所有场景内容、智能体配置等
-- `classrooms/{id}/media/` — 公共课程的媒体缓存，首次访问时生成并上传
-- `classroom-jobs/{jobId}.json` — 异步生成任务的持久化状态，轮询 API 读取此文件
-
-## 15. 代理相关
-
-本机通过 Shadowsocks 代理访问外网：
-- HTTP 代理：`http://127.0.0.1:17891`
-- SOCKS5 代理：`socks5://127.0.0.1:17890`
-- 服务：`shadowsocks-client.service`
-
-OpenMAIC 服务端调用 QN API 时，QN API 地址 `api.qnaigc.com` 是国内服务，不需要代理。但如果配置了 OpenAI/Anthropic/Google 等海外 provider，需要在 `.env.local` 中设置：
-```env
-HTTP_PROXY=http://127.0.0.1:17891
-HTTPS_PROXY=http://127.0.0.1:17891
-```
-
-`pnpm install` 和 `pnpm build` 下载依赖时需要代理（npm registry 部分包在海外）。
-
----
-
-> 最后更新：2026-03-20 | 维护者：Claude Code

From 39de4f913b716e4a41cb1ffe7a0a5fd83d173e46 Mon Sep 17 00:00:00 2001
From: zhenzhu143321 <hxcisunli@126.com>
Date: Wed, 25 Mar 2026 14:28:03 +0800
Subject: [PATCH 05/30] Fix standalone 8002 startup and classroom storage

---
 RUNBOOK-8002.md                 | 73 +++++++++++++++++++++++++++++++++
 lib/server/classroom-storage.ts | 20 ++++++++-
 scripts/start-8002.sh           | 18 ++++++++
 3 files changed, 109 insertions(+), 2 deletions(-)
 create mode 100644 RUNBOOK-8002.md
 create mode 100755 scripts/start-8002.sh

diff --git a/RUNBOOK-8002.md b/RUNBOOK-8002.md
new file mode 100644
index 000000000..3a2a31f16
--- /dev/null
+++ b/RUNBOOK-8002.md
@@ -0,0 +1,73 @@
+# OpenMAIC 8002 Runbook
+
+## Correct startup mode
+
+This project is built with Next.js `output: 'standalone'`.
+
+Do not use `pnpm start` for the production-style 8002 service. It prints a warning and may not behave as expected with the standalone output.
+
+Use the standalone server entry instead:
+
+```bash
+cd /home/sunli/MyWork/myproject/OpenMAIC
+PORT=8002 HOSTNAME=0.0.0.0 OPENMAIC_PROJECT_ROOT=/home/sunli/MyWork/myproject/OpenMAIC node .next/standalone/server.js
+```
+
+Or use the helper script:
+
+```bash
+cd /home/sunli/MyWork/myproject/OpenMAIC
+./scripts/start-8002.sh
+```
+
+## Detached startup with tmux
+
+```bash
+cd /home/sunli/MyWork/myproject/OpenMAIC
+tmux new-session -d -s openmaic-svc-8002 './scripts/start-8002.sh >>/tmp/openmaic-8002.log 2>&1'
+```
+
+## Verify service
+
+```bash
+ss -ltnp 'sport = :8002'
+curl http://127.0.0.1:8002/api/health
+curl http://127.0.0.1:8002/api/classroom
+```
+
+## Stop service
+
+```bash
+tmux kill-session -t openmaic-svc-8002
+```
+
+## Rebuild when needed
+
+If server code changed, rebuild before restarting:
+
+```bash
+cd /home/sunli/MyWork/myproject/OpenMAIC
+pnpm build
+tmux kill-session -t openmaic-svc-8002 || true
+tmux new-session -d -s openmaic-svc-8002 './scripts/start-8002.sh >>/tmp/openmaic-8002.log 2>&1'
+```
+
+## Why the public-course count dropped from 4 to 3
+
+`node .next/standalone/server.js` changes the working directory to `.next/standalone`.
+
+Also note that many Linux hosts already define a shell `HOSTNAME` value such as `k8s-node3-gpu`. If you pass that through unchanged, Next.js may bind to `127.0.1.1` instead of `0.0.0.0`. The helper script forces `HOSTNAME=0.0.0.0` unless `OPENMAIC_HOSTNAME` is set explicitly.
+
+Before the fix in `lib/server/classroom-storage.ts`, server-side classroom storage used `process.cwd()`, so the live service read:
+
+```text
+.next/standalone/data/classrooms
+```
+
+instead of:
+
+```text
+data/classrooms
+```
+
+That standalone snapshot only had 3 classroom JSON files, so `/api/classroom` returned 3 public courses.
diff --git a/lib/server/classroom-storage.ts b/lib/server/classroom-storage.ts
index 0c8f7bc4b..f92f1c4a3 100644
--- a/lib/server/classroom-storage.ts
+++ b/lib/server/classroom-storage.ts
@@ -5,8 +5,24 @@ import type { Scene, Stage, SlideContent } from '@/lib/types/stage';
 import type { Slide } from '@/lib/types/slides';
 import type { SceneOutline } from '@/lib/types/generation';
 
-export const CLASSROOMS_DIR = path.join(process.cwd(), 'data', 'classrooms');
-export const CLASSROOM_JOBS_DIR = path.join(process.cwd(), 'data', 'classroom-jobs');
+function resolveProjectRoot(): string {
+  const explicitRoot = process.env.OPENMAIC_PROJECT_ROOT;
+  if (explicitRoot) {
+    return path.resolve(explicitRoot);
+  }
+
+  const cwd = process.cwd();
+  const standaloneSuffix = `${path.sep}.next${path.sep}standalone`;
+  if (cwd.endsWith(standaloneSuffix)) {
+    return path.resolve(cwd, '..', '..');
+  }
+
+  return cwd;
+}
+
+export const PROJECT_ROOT = resolveProjectRoot();
+export const CLASSROOMS_DIR = path.join(PROJECT_ROOT, 'data', 'classrooms');
+export const CLASSROOM_JOBS_DIR = path.join(PROJECT_ROOT, 'data', 'classroom-jobs');
 
 async function ensureDir(dir: string) {
   await fs.mkdir(dir, { recursive: true });
diff --git a/scripts/start-8002.sh b/scripts/start-8002.sh
new file mode 100755
index 000000000..764077fea
--- /dev/null
+++ b/scripts/start-8002.sh
@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+cd "$ROOT_DIR"
+
+export OPENMAIC_PROJECT_ROOT="$ROOT_DIR"
+export PORT="${PORT:-8002}"
+export HOSTNAME="${OPENMAIC_HOSTNAME:-0.0.0.0}"
+
+if [[ ! -f .next/standalone/server.js ]]; then
+  echo "Missing standalone build: $ROOT_DIR/.next/standalone/server.js" >&2
+  echo "Run 'pnpm build' first." >&2
+  exit 1
+fi
+
+exec node .next/standalone/server.js

From ed42b548bd475719add8fe251a1b38235d22f891 Mon Sep 17 00:00:00 2001
From: zhenzhu143321 <hxcisunli@126.com>
Date: Wed, 25 Mar 2026 14:43:02 +0800
Subject: [PATCH 06/30] Add OpenMAIC agent startup notes

---
 AGENTS.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..4c4c92289
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,46 @@
+# OpenMAIC Agent Notes
+
+## 8002 Service Startup
+
+- Project root: `/home/sunli/MyWork/myproject/OpenMAIC`
+- The production-style `8002` service uses the Next.js standalone build.
+- Do not use `pnpm start` for the `8002` service.
+
+Use this preferred detached startup command:
+
+```bash
+cd /home/sunli/MyWork/myproject/OpenMAIC
+tmux new-session -d -s openmaic-svc-8002 './scripts/start-8002.sh >>/tmp/openmaic-8002.log 2>&1'
+```
+
+## Verify
+
+```bash
+ss -ltnp 'sport = :8002'
+curl http://127.0.0.1:8002/api/health
+curl http://127.0.0.1:8002/api/classroom
+```
+
+## Stop
+
+```bash
+tmux kill-session -t openmaic-svc-8002
+```
+
+## Rebuild Before Restart
+
+If server-side code changed, rebuild before restarting:
+
+```bash
+cd /home/sunli/MyWork/myproject/OpenMAIC
+pnpm build
+tmux kill-session -t openmaic-svc-8002 || true
+tmux new-session -d -s openmaic-svc-8002 './scripts/start-8002.sh >>/tmp/openmaic-8002.log 2>&1'
+```
+
+## Important Pitfalls
+
+- `node .next/standalone/server.js` changes `process.cwd()` to `.next/standalone`.
+- Server-side storage must resolve back to the repo root, not the standalone snapshot directory.
+- On this host, shell `HOSTNAME` may point to a machine hostname such as `k8s-node3-gpu`; if passed through unchanged, Next.js may bind to `127.0.1.1` instead of `0.0.0.0`.
+- `./scripts/start-8002.sh` is the safe entry because it sets `OPENMAIC_PROJECT_ROOT`, `PORT`, and a safe `HOSTNAME`.

From 5f8370dfeeae3aed996c2136fb41d210f190db38 Mon Sep 17 00:00:00 2001
From: zhenzhu143321 <hxcisunli@126.com>
Date: Fri, 27 Mar 2026 12:41:47 +0800
Subject: [PATCH 07/30] feat: add course management system with optimizations

- Add Course and CourseListItem types with Omit utility
- Implement server-side storage with atomic writes
- Create API routes for CRUD and classroom relationships
- Add Zustand store with optimistic updates
- Build course list, detail pages and form components
- Add i18n support (zh-CN/en-US)
- Integrate with home page tabs

Optimizations:
- Parallel file I/O in listCourses using Promise.all
- Parallel API loading on homepage
- Create generic resource-lock utility
- Fix concurrent modification race conditions
- Use nanoid for ID generation
- Add error handling and validation

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .claude/plans/course-management.md | 246 +++++++++++++++++++++++++++++
 CLAUDE.md                          | 112 +++++++++++++
 app/api/course/classrooms/route.ts |  41 +++++
 app/api/course/route.ts            |  50 ++++++
 app/course/[id]/page.tsx           |  66 ++++++++
 app/course/page.tsx                |  69 ++++++++
 app/page.tsx                       |  81 +++++++---
 components/course/course-form.tsx  |  90 +++++++++++
 lib/i18n/course.ts                 |  41 +++++
 lib/i18n/index.ts                  |   3 +
 lib/server/course-lock.ts          |   3 +
 lib/server/course-storage.ts       | 100 ++++++++++++
 lib/server/resource-lock.ts        |  22 +++
 lib/store/course.ts                | 113 +++++++++++++
 lib/types/course.ts                |  15 ++
 15 files changed, 1034 insertions(+), 18 deletions(-)
 create mode 100644 .claude/plans/course-management.md
 create mode 100644 CLAUDE.md
 create mode 100644 app/api/course/classrooms/route.ts
 create mode 100644 app/api/course/route.ts
 create mode 100644 app/course/[id]/page.tsx
 create mode 100644 app/course/page.tsx
 create mode 100644 components/course/course-form.tsx
 create mode 100644 lib/i18n/course.ts
 create mode 100644 lib/server/course-lock.ts
 create mode 100644 lib/server/course-storage.ts
 create mode 100644 lib/server/resource-lock.ts
 create mode 100644 lib/store/course.ts
 create mode 100644 lib/types/course.ts

diff --git a/.claude/plans/course-management.md b/.claude/plans/course-management.md
new file mode 100644
index 000000000..8ad5c2669
--- /dev/null
+++ b/.claude/plans/course-management.md
@@ -0,0 +1,246 @@
+# Course Management Feature - Implementation Plan
+
+## 需求概述
+
+为 OpenMAIC 添加「课程」管理功能，使教师能够创建课程并将多个课堂组织到课程中。
+
+### 核心需求
+1. Course 元数据：学院、专业、课程名称、课程简介、教师姓名
+2. 前端 UI：创建/编辑/删除课程
+3. 生成流程：选择目标课程 → 生成课堂 → 发布到课程
+4. 课程浏览：按课程查看有序的课堂列表
+5. 向后兼容：现有独立课堂继续工作
+
+## 设计原则
+
+### 数据结构 - 索引关系而非嵌套
+- Course 只存储 `classroomIds[]`，不嵌入完整 classroom 数据
+- Classroom 仍然独立存储在 `data/classrooms/{id}/`
+- 关系是 Course → Classroom (1:N)，通过 ID 引用
+
+### 零破坏性
+- 不修改现有 `Stage` 类型
+- 不修改现有 `POST /api/classroom` 逻辑
+- 现有 classroom 自动成为「独立课堂」
+- 所有现有 URL 和 API 保持不变
+
+## 实现步骤
+
+### Phase 1: 数据模型与服务端存储
+
+#### 1.1 新增类型定义
+**文件**: `lib/types/course.ts` (新建)
+
+```typescript
+export interface Course {
+  id: string;
+  name: string;              // 课程名称
+  college: string;           // 学院
+  major: string;             // 专业
+  description: string;       // 课程简介
+  teacherName: string;       // 教师姓名
+  classroomIds: string[];    // 有序的课堂ID列表
+  createdAt: string;         // ISO 8601
+  updatedAt: string;
+}
+
+export interface CourseListItem {
+  id: string;
+  name: string;
+  college: string;
+  major: string;
+  description: string;
+  teacherName: string;
+  classroomCount: number;
+  createdAt: string;
+}
+```
+
+#### 1.2 服务端存储模块
+**文件**: `lib/server/course-storage.ts` (新建)
+
+实现函数：
+- `persistCourse(course: Course): Promise<void>` - 原子写入
+- `readCourse(id: string): Promise<Course | null>`
+- `listCourses(): Promise<CourseListItem[]>` - 按 createdAt 降序
+- `deleteCourse(id: string): Promise<void>`
+- `addClassroomToCourse(courseId: string, classroomId: string): Promise<void>`
+- `removeClassroomFromCourse(courseId: string, classroomId: string): Promise<void>`
+- `reorderClassrooms(courseId: string, newOrder: string[]): Promise<void>`
+
+存储路径：`data/courses/{courseId}.json`
+
+#### 1.3 API 路由设计
+**文件**: `app/api/course/route.ts` (新建)
+
+```typescript
+GET /api/course          → listCourses()
+GET /api/course?id=xxx   → readCourse(id)
+POST /api/course         → persistCourse(body)
+DELETE /api/course?id=xxx → deleteCourse(id)
+```
+
+**文件**: `app/api/course/classrooms/route.ts` (新建)
+
+```typescript
+POST /api/course/classrooms    → addClassroomToCourse(courseId, classroomId)
+DELETE /api/course/classrooms  → removeClassroomFromCourse(courseId, classroomId)
+PUT /api/course/classrooms     → reorderClassrooms(courseId, newOrder)
+```
+
+### Phase 2: 前端状态管理
+
+#### 2.1 Course Store
+**文件**: `lib/store/course.ts` (新建)
+
+状态：
+- `courses: CourseListItem[]` - 课程列表
+- `currentCourse: Course | null` - 当前编辑的课程
+- `isLoading: boolean`
+
+Actions：
+- `fetchCourses()` - 从服务器加载课程列表
+- `fetchCourse(id)` - 加载单个课程详情
+- `createCourse(data)` - 创建新课程
+- `updateCourse(id, data)` - 更新课程
+- `deleteCourse(id)` - 删除课程
+- `addClassroom(courseId, classroomId)` - 添加课堂到课程
+- `removeClassroom(courseId, classroomId)` - 从课程移除课堂
+- `reorderClassrooms(courseId, newOrder)` - 重排课堂顺序
+
+### Phase 3: UI 组件与页面
+
+#### 3.1 课程列表页
+**文件**: `app/course/page.tsx` (新建)
+
+功能：
+- 显示所有课程的卡片列表
+- 每个卡片显示：课程名、学院、专业、课堂数量
+- 操作按钮：新建课程、编辑、删除
+- 点击卡片进入课程详情页
+
+#### 3.2 课程详情页
+**文件**: `app/course/[id]/page.tsx` (新建)
+
+功能：
+- 显示课程元数据（可编辑）
+- 显示课程内的课堂列表（可拖拽排序）
+- 每个课堂显示缩略图、标题、创建时间
+- 操作：添加现有课堂、生成新课堂、移除课堂、预览课堂
+- 点击课堂进入播放页面
+
+#### 3.3 课程表单组件
+**文件**: `components/course/course-form.tsx` (新建)
+
+表单字段：
+- 课程名称 (name)
+- 学院 (college)
+- 专业 (major)
+- 课程简介 (description)
+- 教师姓名 (teacherName)
+
+用于创建和编辑课程。
+
+### Phase 4: 生成流程集成
+
+#### 4.1 修改生成器传递 courseId
+**文件**: `lib/hooks/use-scene-generator.ts`
+
+在 `generateRemaining()` 中添加可选的 `courseId` 参数，传递给后端 API。
+
+#### 4.2 修改发布流程
+**文件**: `components/header.tsx`
+
+`publishClassroom()` 函数：
+- 如果当前在课程上下文中，调用 `POST /api/course/classrooms` 将课堂关联到课程
+- 保持现有独立发布流程不变
+
+#### 4.3 生成页面课程选择
+**文件**: `app/page.tsx` 或生成表单组件
+
+在生成表单中添加：
+- 可选的"目标课程"下拉选择
+- 如果选择了课程，生成后自动关联到该课程
+- 如果未选择，生成独立课堂
+
+### Phase 5: 首页修改
+
+**文件**: `app/page.tsx`
+
+添加 Tab 切换：
+- Tab 1: 我的课程 (显示课程列表)
+- Tab 2: 独立课堂 (显示未关联到任何课程的课堂)
+
+逻辑：
+- 课程 Tab：调用 `GET /api/course` 获取课程列表
+- 独立课堂 Tab：调用 `GET /api/classroom`，过滤出不在任何课程中的课堂
+
+### Phase 6: 国际化
+
+**文件**: `locales/zh-CN.json` 和 `locales/en-US.json`
+
+添加翻译键：
+- `course.name` - 课程名称 / Course Name
+- `course.college` - 学院 / College
+- `course.major` - 专业 / Major
+- `course.description` - 课程简介 / Description
+- `course.teacherName` - 教师姓名 / Teacher Name
+- `course.create` - 创建课程 / Create Course
+- `course.edit` - 编辑课程 / Edit Course
+- `course.delete` - 删除课程 / Delete Course
+- `course.classroomCount` - 课堂数量 / Classroom Count
+- `course.myCourses` - 我的课程 / My Courses
+- `course.standaloneClassrooms` - 独立课堂 / Standalone Classrooms
+
+## 验证计划
+
+### 端到端测试流程
+
+1. **创建课程**
+   - 访问 `/course`
+   - 点击"创建课程"
+   - 填写表单：学院、专业、课程名称、简介、教师姓名
+   - 提交，验证课程出现在列表中
+
+2. **生成课堂到课程**
+   - 在首页生成表单中选择目标课程
+   - 填写课堂主题，点击生成
+   - 等待生成完成
+   - 验证课堂出现在课程详情页的课堂列表中
+
+3. **课程详情管理**
+   - 访问 `/course/[id]`
+   - 验证课程元数据显示正确
+   - 拖拽课堂重新排序
+   - 点击课堂进入播放页面
+   - 移除一个课堂，验证它变成独立课堂
+
+4. **向后兼容性**
+   - 访问首页"独立课堂" Tab
+   - 验证现有课堂仍然可见
+   - 点击播放，验证功能正常
+   - 验证所有现有 API 端点仍然工作
+
+5. **数据持久化**
+   - 重启服务器
+   - 验证课程和课堂关系保持不变
+   - 检查 `data/courses/` 目录下的 JSON 文件格式正确
+
+## 关键文件清单
+
+### 新建文件 (8个)
+1. `lib/types/course.ts` - 类型定义
+2. `lib/server/course-storage.ts` - 服务端存储
+3. `lib/store/course.ts` - 前端状态管理
+4. `app/api/course/route.ts` - 课程 CRUD API
+5. `app/api/course/classrooms/route.ts` - 课程-课堂关系 API
+6. `app/course/page.tsx` - 课程列表页
+7. `app/course/[id]/page.tsx` - 课程详情页
+8. `components/course/course-form.tsx` - 课程表单组件
+
+### 修改文件 (4个)
+1. `lib/hooks/use-scene-generator.ts` - 添加 courseId 参数
+2. `components/header.tsx` - 发布时关联课程
+3. `app/page.tsx` - 添加 Tab 切换
+4. `locales/*.json` - 国际化字符串
+
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 000000000..46ab405a0
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,112 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+pnpm dev          # Development server on :3000
+pnpm build        # Production build (standalone output)
+pnpm start        # Start production server (use scripts/start-8002.sh for port 8002)
+pnpm lint         # ESLint
+pnpm check        # Prettier check
+pnpm format       # Prettier format
+```
+
+**Note:** `pnpm install` and `pnpm build` require the proxy (`export http_proxy="http://127.0.0.1:17891" https_proxy="http://127.0.0.1:17891"`) for downloading packages from overseas registries.
+
+### Production Service (Port 8002)
+
+The deployed instance runs via standalone build on port 8002. Preferred startup:
+
+```bash
+tmux new-session -d -s openmaic-svc-8002 './scripts/start-8002.sh >>/tmp/openmaic-8002.log 2>&1'
+```
+
+After any server-side code change: `pnpm build` → kill session → re-launch.
+
+Verify: `curl http://127.0.0.1:8002/api/health`
+
+## Architecture Overview
+
+Next.js 16 App Router + React 19 + TypeScript. State management via Zustand. Multi-agent orchestration via LangGraph.
+
+### Key Data Flows
+
+**Provider Configuration:**
+```
+.env.local / server-providers.yml
+  → lib/server/provider-config.ts  (server-side, never exposes keys)
+  → GET /api/server-providers       (metadata only)
+  → lib/store/settings.ts           (Zustand, merged into providersConfig)
+```
+
+**Model Resolution (per API call):**
+```
+POST /api/chat { model: "qn:gemini-3.1-pro-preview" }
+  → lib/server/resolve-model.ts    (parse modelString, fetch apiKey/baseUrl)
+  → lib/ai/providers.ts getModel() (create @ai-sdk/* client by provider.type)
+```
+
+**Classroom Generation (two-stage pipeline):**
+```
+Stage 1: POST /api/generate/scene-outlines-stream  (SSE, LLM builds outline)
+Stage 2: parallel per outline item:
+  POST /api/generate/scene-content   → slides/quiz/interactive/pbl content
+  POST /api/generate/scene-actions   → teacher actions (laser, spotlight, speech)
+  POST /api/generate/agent-profiles  → agent personas
+  POST /api/generate/tts             → audio synthesis
+Stage 2.5 (client-side): generateMediaForOutlines() → image/video generation
+```
+
+Async API mode: `POST /api/generate-classroom` submits a job; poll `GET /api/generate-classroom/{jobId}` until `status: succeeded`.
+
+### Core Modules
+
+| Module | Purpose |
+|--------|---------|
+| `lib/ai/providers.ts` | PROVIDERS registry + `getModel()`. Supports openai/anthropic/google types plus any OpenAI-compatible endpoint |
+| `lib/server/provider-config.ts` | Loads config from `server-providers.yml` + env vars; `LLM_ENV_MAP` maps env prefixes to provider IDs |
+| `lib/server/resolve-model.ts` | Parses `"providerId:modelId"` strings; handles `DEFAULT_MODEL` fallback |
+| `lib/generation/` | Two-stage pipeline: outline → scenes. `pipeline-runner.ts` orchestrates; `scene-generator.ts` generates per-scene content |
+| `lib/orchestration/director-graph.ts` | LangGraph state machine for multi-agent classroom discussion |
+| `lib/playback/` | State machine: idle → playing → live; drives scene transitions and agent turns |
+| `lib/action/` | Executes 28+ action types (speech, whiteboard draw/write/shape, spotlight, laser, etc.) |
+| `lib/server/classroom-storage.ts` | `persistClassroom`, `readClassroom`, `listClassrooms` — reads both new (`{id}/classroom.json`) and old (`{id}.json`) formats |
+| `lib/server/media-storage.ts` | `saveMedia`, `getMediaPath`, `mediaExists` — atomic writes to `data/classrooms/{id}/media/` |
+
+### Frontend Storage
+
+- **Settings**: `localStorage` key `settings-storage` (Zustand persist)
+- **Classroom data** (scenes, audio, media, chat): IndexedDB, database name `MAIC-Database`
+- **Server-persisted classrooms**: `data/classrooms/{id}/` on the server
+
+### Scene Types
+
+| Type | Components |
+|------|-----------|
+| `slides` | `components/slide-renderer/` — canvas-based editor with ProseMirror text editing |
+| `quiz` | `components/scene-renderers/` — single/multiple choice + short answer |
+| `interactive` | `components/scene-renderers/` — sandboxed HTML simulations |
+| `pbl` | Project-Based Learning with role selection and milestones |
+
+### Adding a New LLM Provider
+
+Requires changes to 4 files — see `CLAUDE_DEPLOY_GUIDE.md` §3 for the complete walkthrough:
+
+1. `lib/types/provider.ts` — add to `BuiltInProviderId`
+2. `lib/ai/providers.ts` — add entry to `PROVIDERS` object
+3. `lib/server/provider-config.ts` — add prefix to `LLM_ENV_MAP`
+4. `.env.local` — set `{PREFIX}_API_KEY` and `{PREFIX}_BASE_URL`
+
+Models must be registered in `providers.ts` before referencing them via `*_MODELS` env var — otherwise the filter removes them.
+
+### Workspace Packages
+
+`packages/pptxgenjs` and `packages/mathml2omml` are local workspace packages rebuilt during `pnpm install` via `postinstall`. They are transpiled into the Next.js build via `transpilePackages` in `next.config.ts`.
+
+### Proxy Notes
+
+- LLM provider proxy is **per-provider** in `server-providers.yml` (`proxy: "http://127.0.0.1:17891"`) — only Google provider currently consumes this field.
+- Web search (Tavily) proxy uses `HTTP_PROXY`/`HTTPS_PROXY` in `.env.local`.
+- OpenAI/Anthropic-type providers do **not** support proxy forwarding in the current code.
diff --git a/app/api/course/classrooms/route.ts b/app/api/course/classrooms/route.ts
new file mode 100644
index 000000000..3621e0b4d
--- /dev/null
+++ b/app/api/course/classrooms/route.ts
@@ -0,0 +1,41 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { addClassroomToCourse, removeClassroomFromCourse, reorderClassrooms } from '@/lib/server/course-storage';
+
+export async function POST(req: NextRequest) {
+  try {
+    const { courseId, classroomId } = await req.json();
+    if (!courseId || !classroomId) {
+      return NextResponse.json({ error: 'Missing required fields' }, { status: 400 });
+    }
+    await addClassroomToCourse(courseId, classroomId);
+    return NextResponse.json({ success: true });
+  } catch (error) {
+    return NextResponse.json({ error: String(error) }, { status: 500 });
+  }
+}
+
+export async function DELETE(req: NextRequest) {
+  try {
+    const { courseId, classroomId } = await req.json();
+    if (!courseId || !classroomId) {
+      return NextResponse.json({ error: 'Missing required fields' }, { status: 400 });
+    }
+    await removeClassroomFromCourse(courseId, classroomId);
+    return NextResponse.json({ success: true });
+  } catch (error) {
+    return NextResponse.json({ error: String(error) }, { status: 500 });
+  }
+}
+
+export async function PUT(req: NextRequest) {
+  try {
+    const { courseId, newOrder } = await req.json();
+    if (!courseId || !newOrder) {
+      return NextResponse.json({ error: 'Missing required fields' }, { status: 400 });
+    }
+    await reorderClassrooms(courseId, newOrder);
+    return NextResponse.json({ success: true });
+  } catch (error) {
+    return NextResponse.json({ error: String(error) }, { status: 500 });
+  }
+}
diff --git a/app/api/course/route.ts b/app/api/course/route.ts
new file mode 100644
index 000000000..f5aeef46c
--- /dev/null
+++ b/app/api/course/route.ts
@@ -0,0 +1,50 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { listCourses, readCourse, persistCourse, deleteCourse } from '@/lib/server/course-storage';
+import type { Course } from '@/lib/types/course';
+
+export async function GET(req: NextRequest) {
+  try {
+    const { searchParams } = new URL(req.url);
+    const id = searchParams.get('id');
+
+    if (id) {
+      const course = await readCourse(id);
+      if (!course) {
+        return NextResponse.json({ error: 'Course not found' }, { status: 404 });
+      }
+      return NextResponse.json(course);
+    }
+
+    const courses = await listCourses();
+    return NextResponse.json(courses);
+  } catch (error) {
+    return NextResponse.json({ error: String(error) }, { status: 500 });
+  }
+}
+
+export async function POST(req: NextRequest) {
+  try {
+    const body = await req.json() as Course;
+    if (!body.id || !body.name) {
+      return NextResponse.json({ error: 'Missing required fields' }, { status: 400 });
+    }
+    await persistCourse(body);
+    return NextResponse.json({ success: true });
+  } catch (error) {
+    return NextResponse.json({ error: String(error) }, { status: 500 });
+  }
+}
+
+export async function DELETE(req: NextRequest) {
+  try {
+    const { searchParams } = new URL(req.url);
+    const id = searchParams.get('id');
+    if (!id) {
+      return NextResponse.json({ error: 'Missing id' }, { status: 400 });
+    }
+    await deleteCourse(id);
+    return NextResponse.json({ success: true });
+  } catch (error) {
+    return NextResponse.json({ error: String(error) }, { status: 500 });
+  }
+}
diff --git a/app/course/[id]/page.tsx b/app/course/[id]/page.tsx
new file mode 100644
index 000000000..74ccaf07b
--- /dev/null
+++ b/app/course/[id]/page.tsx
@@ -0,0 +1,66 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { useRouter } from 'next/navigation';
+import { useI18n } from '@/lib/hooks/use-i18n';
+import { useCourseStore } from '@/lib/store/course';
+import { CourseForm } from '@/components/course/course-form';
+
+export default function CourseDetailPage({ params }: { params: { id: string } }) {
+  const { t } = useI18n();
+  const router = useRouter();
+  const { currentCourse, fetchCourse, updateCourse, removeClassroom } = useCourseStore();
+  const [editing, setEditing] = useState(false);
+
+  useEffect(() => {
+    fetchCourse(params.id);
+  }, [params.id, fetchCourse]);
+
+  if (!currentCourse) return <div className="p-8">{t('common.loading')}</div>;
+
+  const handleUpdate = async (data: Parameters<typeof updateCourse>[1]) => {
+    await updateCourse(params.id, data);
+    setEditing(false);
+  };
+
+  if (editing) {
+    return (
+      <div className="p-8 max-w-2xl mx-auto">
+        <h1 className="text-2xl mb-4">{t('course.edit')}</h1>
+        <CourseForm initialData={currentCourse} onSubmit={handleUpdate} onCancel={() => setEditing(false)} />
+      </div>
+    );
+  }
+
+  return (
+    <div className="p-8">
+      <div className="flex justify-between items-center mb-6">
+        <h1 className="text-2xl">{currentCourse.name}</h1>
+        <button onClick={() => setEditing(true)} className="px-4 py-2 border rounded">
+          {t('course.edit')}
+        </button>
+      </div>
+      <div className="mb-6 space-y-2">
+        <p><strong>{t('course.college')}:</strong> {currentCourse.college}</p>
+        <p><strong>{t('course.major')}:</strong> {currentCourse.major}</p>
+        <p><strong>{t('course.teacherName')}:</strong> {currentCourse.teacherName}</p>
+        <p><strong>{t('course.description')}:</strong> {currentCourse.description}</p>
+      </div>
+      <h2 className="text-xl mb-4">{t('course.classroomCount')}: {currentCourse.classroomIds.length}</h2>
+      {currentCourse.classroomIds.length === 0 ? (
+        <p className="text-gray-500">{t('course.noClassrooms')}</p>
+      ) : (
+        <div className="space-y-2">
+          {currentCourse.classroomIds.map((id) => (
+            <div key={id} className="border rounded p-4 flex justify-between items-center">
+              <span className="cursor-pointer" onClick={() => router.push(`/stage/${id}`)}>{id}</span>
+              <button onClick={() => removeClassroom(params.id, id)} className="text-red-500 text-sm">
+                {t('course.removeClassroom')}
+              </button>
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/app/course/page.tsx b/app/course/page.tsx
new file mode 100644
index 000000000..46f7bc08f
--- /dev/null
+++ b/app/course/page.tsx
@@ -0,0 +1,69 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { useRouter } from 'next/navigation';
+import { useI18n } from '@/lib/hooks/use-i18n';
+import { useCourseStore } from '@/lib/store/course';
+import { CourseForm } from '@/components/course/course-form';
+
+export default function CoursePage() {
+  const { t } = useI18n();
+  const router = useRouter();
+  const { courses, fetchCourses, createCourse, deleteCourse } = useCourseStore();
+  const [showForm, setShowForm] = useState(false);
+
+  useEffect(() => {
+    fetchCourses();
+  }, [fetchCourses]);
+
+  const handleCreate = async (data: Parameters<typeof createCourse>[0]) => {
+    await createCourse(data);
+    setShowForm(false);
+  };
+
+  const handleDelete = async (id: string) => {
+    if (confirm(t('course.confirmDelete'))) {
+      await deleteCourse(id);
+    }
+  };
+
+  if (showForm) {
+    return (
+      <div className="p-8 max-w-2xl mx-auto">
+        <h1 className="text-2xl mb-4">{t('course.create')}</h1>
+        <CourseForm onSubmit={handleCreate} onCancel={() => setShowForm(false)} />
+      </div>
+    );
+  }
+
+  return (
+    <div className="p-8">
+      <div className="flex justify-between items-center mb-6">
+        <h1 className="text-2xl">{t('course.myCourses')}</h1>
+        <button onClick={() => setShowForm(true)} className="px-4 py-2 bg-blue-500 text-white rounded">
+          {t('course.create')}
+        </button>
+      </div>
+      {courses.length === 0 ? (
+        <p className="text-gray-500">{t('course.noCourses')}</p>
+      ) : (
+        <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+          {courses.map((course) => (
+            <div key={course.id} className="border rounded p-4 hover:shadow-lg transition-shadow cursor-pointer">
+              <div onClick={() => router.push(`/course/${course.id}`)}>
+                <h2 className="text-xl mb-2">{course.name}</h2>
+                <p className="text-sm text-gray-600">{course.college} - {course.major}</p>
+                <p className="text-sm text-gray-500 mt-2">{course.description}</p>
+                <p className="text-sm mt-2">{t('course.teacherName')}: {course.teacherName}</p>
+                <p className="text-sm text-gray-500">{t('course.classroomCount')}: {course.classroomCount}</p>
+              </div>
+              <button onClick={() => handleDelete(course.id)} className="mt-2 text-red-500 text-sm">
+                {t('course.delete')}
+              </button>
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/app/page.tsx b/app/page.tsx
index c09d95e71..691a03cd2 100644
--- a/app/page.tsx
+++ b/app/page.tsx
@@ -47,6 +47,7 @@ import { toast } from 'sonner';
 import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip';
 import { useDraftCache } from '@/lib/hooks/use-draft-cache';
 import { SpeechButton } from '@/components/audio/speech-button';
+import { useCourseStore } from '@/lib/store/course';
 
 const log = createLogger('Home');
 
@@ -147,6 +148,8 @@ function HomePage() {
   const [pendingDeleteId, setPendingDeleteId] = useState<string | null>(null);
   const toolbarRef = useRef<HTMLDivElement>(null);
   const textareaRef = useRef<HTMLTextAreaElement>(null);
+  const [activeTab, setActiveTab] = useState<'courses' | 'standalone'>('courses');
+  const { courses, fetchCourses } = useCourseStore();
 
   // Close dropdowns when clicking outside
   useEffect(() => {
@@ -183,22 +186,20 @@ function HomePage() {
     useMediaGenerationStore.setState({ tasks: {} });
 
     // eslint-disable-next-line react-hooks/set-state-in-effect -- Store hydration on mount
-    loadClassrooms();
-
-    // Load public classrooms from server
-    fetch('/api/classroom')
-      .then(res => res.json())
-      .then(data => {
-        if (data.success && data.classrooms) {
-          setPublicClassrooms(data.classrooms);
-          const thumbs: Record<string, Slide> = {};
-          for (const c of data.classrooms) {
-            if (c.firstSlide) thumbs[c.id] = c.firstSlide;
-          }
-          setPublicThumbnails(thumbs);
+    Promise.all([
+      loadClassrooms(),
+      fetchCourses(),
+      fetch('/api/classroom').then(res => res.json())
+    ]).then(([, , publicData]) => {
+      if (publicData.success && publicData.classrooms) {
+        setPublicClassrooms(publicData.classrooms);
+        const thumbs: Record<string, Slide> = {};
+        for (const c of publicData.classrooms) {
+          if (c.firstSlide) thumbs[c.id] = c.firstSlide;
         }
-      })
-      .catch(() => {});
+        setPublicThumbnails(thumbs);
+      }
+    }).catch(() => {});
   }, []);
 
   const handleDelete = (id: string, e: React.MouseEvent) => {
@@ -673,15 +674,57 @@ function HomePage() {
       )}
 
       {/* ═══ Recent classrooms — collapsible ═══ */}
-      {classrooms.length > 0 && (
+      {(classrooms.length > 0 || courses.length > 0) && (
         <motion.div
           initial={{ opacity: 0 }}
           animate={{ opacity: 1 }}
           transition={{ delay: 0.5 }}
           className="relative z-10 mt-10 w-full max-w-6xl flex flex-col items-center"
         >
-          {/* Trigger — divider-line with centered text */}
-          <button
+          {/* Tab buttons */}
+          <div className="flex gap-4 mb-4">
+            <button
+              onClick={() => setActiveTab('courses')}
+              className={cn(
+                'px-4 py-2 rounded transition-colors',
+                activeTab === 'courses' ? 'bg-blue-500 text-white' : 'bg-gray-200'
+              )}
+            >
+              {t('course.myCourses')} ({courses.length})
+            </button>
+            <button
+              onClick={() => setActiveTab('standalone')}
+              className={cn(
+                'px-4 py-2 rounded transition-colors',
+                activeTab === 'standalone' ? 'bg-blue-500 text-white' : 'bg-gray-200'
+              )}
+            >
+              {t('course.standaloneClassrooms')} ({classrooms.length})
+            </button>
+          </div>
+
+          {/* Courses tab */}
+          {activeTab === 'courses' && courses.length > 0 && (
+            <div className="w-full grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-4">
+              {courses.map((course) => (
+                <div
+                  key={course.id}
+                  onClick={() => router.push(`/course/${course.id}`)}
+                  className="border rounded p-4 cursor-pointer hover:shadow-lg transition-shadow"
+                >
+                  <h3 className="font-semibold">{course.name}</h3>
+                  <p className="text-sm text-gray-600">{course.college}</p>
+                  <p className="text-xs text-gray-500 mt-2">{course.classroomCount} {t('course.classroomCount')}</p>
+                </div>
+              ))}
+            </div>
+          )}
+
+          {/* Standalone classrooms tab */}
+          {activeTab === 'standalone' && (
+            <>
+              {/* Trigger — divider-line with centered text */}
+              <button
             onClick={() => {
               const next = !recentOpen;
               setRecentOpen(next);
@@ -746,6 +789,8 @@ function HomePage() {
               </motion.div>
             )}
           </AnimatePresence>
+            </>
+          )}
         </motion.div>
       )}
 
diff --git a/components/course/course-form.tsx b/components/course/course-form.tsx
new file mode 100644
index 000000000..f325288cf
--- /dev/null
+++ b/components/course/course-form.tsx
@@ -0,0 +1,90 @@
+'use client';
+
+import { useState } from 'react';
+import { useI18n } from '@/lib/hooks/use-i18n';
+import type { Course } from '@/lib/types/course';
+
+interface CourseFormProps {
+  initialData?: Partial<Course>;
+  onSubmit: (data: Omit<Course, 'id' | 'createdAt' | 'updatedAt' | 'classroomIds'>) => void;
+  onCancel: () => void;
+}
+
+export function CourseForm({ initialData, onSubmit, onCancel }: CourseFormProps) {
+  const { t } = useI18n();
+  const [formData, setFormData] = useState({
+    name: initialData?.name || '',
+    college: initialData?.college || '',
+    major: initialData?.major || '',
+    description: initialData?.description || '',
+    teacherName: initialData?.teacherName || '',
+  });
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    onSubmit({ ...formData, classroomIds: [] });
+  };
+
+  return (
+    <form onSubmit={handleSubmit} className="space-y-4">
+      <div>
+        <label className="block text-sm mb-1">{t('course.name')}</label>
+        <input
+          type="text"
+          value={formData.name}
+          onChange={(e) => setFormData({ ...formData, name: e.target.value })}
+          className="w-full px-3 py-2 border rounded"
+          required
+        />
+      </div>
+      <div>
+        <label className="block text-sm mb-1">{t('course.college')}</label>
+        <input
+          type="text"
+          value={formData.college}
+          onChange={(e) => setFormData({ ...formData, college: e.target.value })}
+          className="w-full px-3 py-2 border rounded"
+          required
+        />
+      </div>
+      <div>
+        <label className="block text-sm mb-1">{t('course.major')}</label>
+        <input
+          type="text"
+          value={formData.major}
+          onChange={(e) => setFormData({ ...formData, major: e.target.value })}
+          className="w-full px-3 py-2 border rounded"
+          required
+        />
+      </div>
+      <div>
+        <label className="block text-sm mb-1">{t('course.description')}</label>
+        <textarea
+          value={formData.description}
+          onChange={(e) => setFormData({ ...formData, description: e.target.value })}
+          className="w-full px-3 py-2 border rounded"
+          rows={3}
+          required
+        />
+      </div>
+      <div>
+        <label className="block text-sm mb-1">{t('course.teacherName')}</label>
+        <input
+          type="text"
+          value={formData.teacherName}
+          onChange={(e) => setFormData({ ...formData, teacherName: e.target.value })}
+          className="w-full px-3 py-2 border rounded"
+          required
+        />
+      </div>
+      <div className="flex gap-2">
+        <button type="submit" className="px-4 py-2 bg-blue-500 text-white rounded">
+          {t('common.confirm')}
+        </button>
+        <button type="button" onClick={onCancel} className="px-4 py-2 border rounded">
+          {t('common.cancel')}
+        </button>
+      </div>
+    </form>
+  );
+}
diff --git a/lib/i18n/course.ts b/lib/i18n/course.ts
new file mode 100644
index 000000000..fe181456a
--- /dev/null
+++ b/lib/i18n/course.ts
@@ -0,0 +1,41 @@
+export const courseZhCN = {
+  course: {
+    name: '课程名称',
+    college: '学院',
+    major: '专业',
+    description: '课程简介',
+    teacherName: '教师姓名',
+    create: '创建课程',
+    edit: '编辑课程',
+    delete: '删除课程',
+    classroomCount: '课堂数量',
+    myCourses: '我的课程',
+    standaloneClassrooms: '独立课堂',
+    addClassroom: '添加课堂',
+    removeClassroom: '移除课堂',
+    noCourses: '暂无课程',
+    noClassrooms: '暂无课堂',
+    confirmDelete: '确定删除此课程吗？',
+  },
+};
+
+export const courseEnUS = {
+  course: {
+    name: 'Course Name',
+    college: 'College',
+    major: 'Major',
+    description: 'Description',
+    teacherName: 'Teacher Name',
+    create: 'Create Course',
+    edit: 'Edit Course',
+    delete: 'Delete Course',
+    classroomCount: 'Classroom Count',
+    myCourses: 'My Courses',
+    standaloneClassrooms: 'Standalone Classrooms',
+    addClassroom: 'Add Classroom',
+    removeClassroom: 'Remove Classroom',
+    noCourses: 'No courses yet',
+    noClassrooms: 'No classrooms yet',
+    confirmDelete: 'Are you sure you want to delete this course?',
+  },
+};
diff --git a/lib/i18n/index.ts b/lib/i18n/index.ts
index 5fd70da52..b74f67589 100644
--- a/lib/i18n/index.ts
+++ b/lib/i18n/index.ts
@@ -5,6 +5,7 @@ import { stageZhCN, stageEnUS } from './stage';
 import { chatZhCN, chatEnUS } from './chat';
 import { generationZhCN, generationEnUS } from './generation';
 import { settingsZhCN, settingsEnUS } from './settings';
+import { courseZhCN, courseEnUS } from './course';
 
 export const translations = {
   'zh-CN': {
@@ -13,6 +14,7 @@ export const translations = {
     ...chatZhCN,
     ...generationZhCN,
     ...settingsZhCN,
+    ...courseZhCN,
   },
   'en-US': {
     ...commonEnUS,
@@ -20,6 +22,7 @@ export const translations = {
     ...chatEnUS,
     ...generationEnUS,
     ...settingsEnUS,
+    ...courseEnUS,
   },
 } as const;
 
diff --git a/lib/server/course-lock.ts b/lib/server/course-lock.ts
new file mode 100644
index 000000000..79b1c45c2
--- /dev/null
+++ b/lib/server/course-lock.ts
@@ -0,0 +1,3 @@
+import { createResourceLock } from './resource-lock';
+
+export const withCourseLock = createResourceLock<string>();
diff --git a/lib/server/course-storage.ts b/lib/server/course-storage.ts
new file mode 100644
index 000000000..d460690fd
--- /dev/null
+++ b/lib/server/course-storage.ts
@@ -0,0 +1,100 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import type { Course, CourseListItem } from '@/lib/types/course';
+import { PROJECT_ROOT, writeJsonFileAtomic } from './classroom-storage';
+import { withCourseLock } from './course-lock';
+
+const COURSES_DIR = path.join(PROJECT_ROOT, 'data', 'courses');
+
+async function ensureCoursesDir() {
+  await fs.mkdir(COURSES_DIR, { recursive: true });
+}
+
+export async function persistCourse(course: Course): Promise<void> {
+  await ensureCoursesDir();
+  const filePath = path.join(COURSES_DIR, `${course.id}.json`);
+  await writeJsonFileAtomic(filePath, course);
+}
+
+export async function readCourse(id: string): Promise<Course | null> {
+  const filePath = path.join(COURSES_DIR, `${id}.json`);
+  try {
+    const content = await fs.readFile(filePath, 'utf-8');
+    return JSON.parse(content) as Course;
+  } catch {
+    return null;
+  }
+}
+
+export async function listCourses(): Promise<CourseListItem[]> {
+  await ensureCoursesDir();
+  try {
+    const files = await fs.readdir(COURSES_DIR);
+    const jsonFiles = files.filter(f => f.endsWith('.json'));
+
+    const courses = await Promise.all(
+      jsonFiles.map(async (file) => {
+        try {
+          const content = await fs.readFile(path.join(COURSES_DIR, file), 'utf-8');
+          const course = JSON.parse(content) as Course;
+          return {
+            id: course.id,
+            name: course.name,
+            college: course.college,
+            major: course.major,
+            description: course.description,
+            teacherName: course.teacherName,
+            classroomCount: course.classroomIds.length,
+            createdAt: course.createdAt,
+          };
+        } catch {
+          return null;
+        }
+      })
+    );
+
+    return courses
+      .filter((c): c is CourseListItem => c !== null)
+      .sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
+  } catch {
+    return [];
+  }
+}
+
+export async function deleteCourse(id: string): Promise<void> {
+  const filePath = path.join(COURSES_DIR, `${id}.json`);
+  await fs.unlink(filePath);
+}
+
+export async function addClassroomToCourse(courseId: string, classroomId: string): Promise<void> {
+  await withCourseLock(courseId, async () => {
+    const course = await readCourse(courseId);
+    if (!course) throw new Error('Course not found');
+    if (!course.classroomIds.includes(classroomId)) {
+      course.classroomIds.push(classroomId);
+      course.updatedAt = new Date().toISOString();
+      await persistCourse(course);
+    }
+  });
+}
+
+export async function removeClassroomFromCourse(courseId: string, classroomId: string): Promise<void> {
+  await withCourseLock(courseId, async () => {
+    const course = await readCourse(courseId);
+    if (!course) throw new Error('Course not found');
+    course.classroomIds = course.classroomIds.filter(id => id !== classroomId);
+    course.updatedAt = new Date().toISOString();
+    await persistCourse(course);
+  });
+}
+
+export async function reorderClassrooms(courseId: string, newOrder: string[]): Promise<void> {
+  await withCourseLock(courseId, async () => {
+    const course = await readCourse(courseId);
+    if (!course) throw new Error('Course not found');
+    course.classroomIds = newOrder;
+    course.updatedAt = new Date().toISOString();
+    await persistCourse(course);
+  });
+}
+
diff --git a/lib/server/resource-lock.ts b/lib/server/resource-lock.ts
new file mode 100644
index 000000000..6ce076155
--- /dev/null
+++ b/lib/server/resource-lock.ts
@@ -0,0 +1,22 @@
+export function createResourceLock<T extends string = string>() {
+  const locks = new Map<T, Promise<void>>();
+
+  return async function withLock<R>(
+    resourceId: T,
+    fn: () => Promise<R>
+  ): Promise<R> {
+    const prev = locks.get(resourceId) ?? Promise.resolve();
+    let resolve: () => void;
+    const next = new Promise<void>((r) => {
+      resolve = r;
+    });
+    locks.set(resourceId, next);
+    try {
+      await prev;
+      return await fn();
+    } finally {
+      resolve!();
+      if (locks.get(resourceId) === next) locks.delete(resourceId);
+    }
+  };
+}
diff --git a/lib/store/course.ts b/lib/store/course.ts
new file mode 100644
index 000000000..56928a66a
--- /dev/null
+++ b/lib/store/course.ts
@@ -0,0 +1,113 @@
+import { create } from 'zustand';
+import type { Course, CourseListItem } from '@/lib/types/course';
+import { nanoid } from 'nanoid';
+
+interface CourseState {
+  courses: CourseListItem[];
+  currentCourse: Course | null;
+  isLoading: boolean;
+  fetchCourses: () => Promise<void>;
+  fetchCourse: (id: string) => Promise<void>;
+  createCourse: (data: Omit<Course, 'id' | 'createdAt' | 'updatedAt'>) => Promise<string>;
+  updateCourse: (id: string, data: Partial<Course>) => Promise<void>;
+  deleteCourse: (id: string) => Promise<void>;
+  addClassroom: (courseId: string, classroomId: string) => Promise<void>;
+  removeClassroom: (courseId: string, classroomId: string) => Promise<void>;
+  reorderClassrooms: (courseId: string, newOrder: string[]) => Promise<void>;
+}
+
+export const useCourseStore = create<CourseState>((set, get) => ({
+  courses: [],
+  currentCourse: null,
+  isLoading: false,
+
+  fetchCourses: async () => {
+    set({ isLoading: true });
+    try {
+      const res = await fetch('/api/course');
+      if (!res.ok) throw new Error('Failed to fetch courses');
+      const courses = await res.json();
+      set({ courses, isLoading: false });
+    } catch (error) {
+      console.error('fetchCourses failed:', error);
+      set({ isLoading: false });
+    }
+  },
+
+  fetchCourse: async (id: string) => {
+    set({ isLoading: true });
+    try {
+      const res = await fetch(`/api/course?id=${id}`);
+      if (!res.ok) throw new Error('Failed to fetch course');
+      const course = await res.json();
+      set({ currentCourse: course, isLoading: false });
+    } catch (error) {
+      console.error('fetchCourse failed:', error);
+      set({ isLoading: false });
+    }
+  },
+
+  createCourse: async (data) => {
+    const id = `course_${nanoid(10)}`;
+    const course: Course = {
+      ...data,
+      id,
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    };
+    await fetch('/api/course', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(course),
+    });
+    await get().fetchCourses();
+    return id;
+  },
+
+  updateCourse: async (id, data) => {
+    const course = get().currentCourse;
+    if (!course) return;
+    const updated = { ...course, ...data, updatedAt: new Date().toISOString() };
+    set({ currentCourse: updated });
+    set((state) => ({
+      courses: state.courses.map((c) => (c.id === id ? { ...c, ...data } : c)),
+    }));
+    await fetch('/api/course', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(updated),
+    });
+  },
+
+  deleteCourse: async (id) => {
+    await fetch(`/api/course?id=${id}`, { method: 'DELETE' });
+    await get().fetchCourses();
+  },
+
+  addClassroom: async (courseId, classroomId) => {
+    await fetch('/api/course/classrooms', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ courseId, classroomId }),
+    });
+    await get().fetchCourse(courseId);
+  },
+
+  removeClassroom: async (courseId, classroomId) => {
+    await fetch('/api/course/classrooms', {
+      method: 'DELETE',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ courseId, classroomId }),
+    });
+    await get().fetchCourse(courseId);
+  },
+
+  reorderClassrooms: async (courseId, newOrder) => {
+    await fetch('/api/course/classrooms', {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ courseId, newOrder }),
+    });
+    await get().fetchCourse(courseId);
+  },
+}));
diff --git a/lib/types/course.ts b/lib/types/course.ts
new file mode 100644
index 000000000..2e95b6e89
--- /dev/null
+++ b/lib/types/course.ts
@@ -0,0 +1,15 @@
+export interface Course {
+  id: string;
+  name: string;
+  college: string;
+  major: string;
+  description: string;
+  teacherName: string;
+  classroomIds: string[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+export type CourseListItem = Omit<Course, 'classroomIds' | 'updatedAt'> & {
+  classroomCount: number;
+};

From e0dd570c4bc86b90ef8f0cce70f8f8dbb3561eaa Mon Sep 17 00:00:00 2001
From: zhenzhu143321 <hxcisunli@126.com>
Date: Fri, 27 Mar 2026 13:06:21 +0800
Subject: [PATCH 08/30] fix: resolve type mismatches, routing, and default tab
 issues

- Fix CourseForm type signature to exclude classroomIds
- Add classroomIds in createCourse implementation
- Fix classroom route from /stage to /classroom
- Change default tab to standalone for backward compatibility

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 app/course/[id]/page.tsx          | 2 +-
 app/page.tsx                      | 2 +-
 components/course/course-form.tsx | 2 +-
 lib/store/course.ts               | 3 ++-
 4 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/app/course/[id]/page.tsx b/app/course/[id]/page.tsx
index 74ccaf07b..e890031a6 100644
--- a/app/course/[id]/page.tsx
+++ b/app/course/[id]/page.tsx
@@ -53,7 +53,7 @@ export default function CourseDetailPage({ params }: { params: { id: string } })
         <div className="space-y-2">
           {currentCourse.classroomIds.map((id) => (
             <div key={id} className="border rounded p-4 flex justify-between items-center">
-              <span className="cursor-pointer" onClick={() => router.push(`/stage/${id}`)}>{id}</span>
+              <span className="cursor-pointer" onClick={() => router.push(`/classroom/${id}`)}>{id}</span>
               <button onClick={() => removeClassroom(params.id, id)} className="text-red-500 text-sm">
                 {t('course.removeClassroom')}
               </button>
diff --git a/app/page.tsx b/app/page.tsx
index 691a03cd2..a42ab0ae5 100644
--- a/app/page.tsx
+++ b/app/page.tsx
@@ -148,7 +148,7 @@ function HomePage() {
   const [pendingDeleteId, setPendingDeleteId] = useState<string | null>(null);
   const toolbarRef = useRef<HTMLDivElement>(null);
   const textareaRef = useRef<HTMLTextAreaElement>(null);
-  const [activeTab, setActiveTab] = useState<'courses' | 'standalone'>('courses');
+  const [activeTab, setActiveTab] = useState<'courses' | 'standalone'>('standalone');
   const { courses, fetchCourses } = useCourseStore();
 
   // Close dropdowns when clicking outside
diff --git a/components/course/course-form.tsx b/components/course/course-form.tsx
index f325288cf..2fbf602d4 100644
--- a/components/course/course-form.tsx
+++ b/components/course/course-form.tsx
@@ -22,7 +22,7 @@ export function CourseForm({ initialData, onSubmit, onCancel }: CourseFormProps)
 
   const handleSubmit = (e: React.FormEvent) => {
     e.preventDefault();
-    onSubmit({ ...formData, classroomIds: [] });
+    onSubmit(formData);
   };
 
   return (
diff --git a/lib/store/course.ts b/lib/store/course.ts
index 56928a66a..b08fb66b0 100644
--- a/lib/store/course.ts
+++ b/lib/store/course.ts
@@ -8,7 +8,7 @@ interface CourseState {
   isLoading: boolean;
   fetchCourses: () => Promise<void>;
   fetchCourse: (id: string) => Promise<void>;
-  createCourse: (data: Omit<Course, 'id' | 'createdAt' | 'updatedAt'>) => Promise<string>;
+  createCourse: (data: Omit<Course, 'id' | 'createdAt' | 'updatedAt' | 'classroomIds'>) => Promise<string>;
   updateCourse: (id: string, data: Partial<Course>) => Promise<void>;
   deleteCourse: (id: string) => Promise<void>;
   addClassroom: (courseId: string, classroomId: string) => Promise<void>;
@@ -51,6 +51,7 @@ export const useCourseStore = create<CourseState>((set, get) => ({
     const id = `course_${nanoid(10)}`;
     const course: Course = {
       ...data,
+      classroomIds: [],
       id,
       createdAt: new Date().toISOString(),
       updatedAt: new Date().toISOString(),

From f6e684fbb89dafeda9d25a147b718fba3333b653 Mon Sep 17 00:00:00 2001
From: zhenzhu143321 <hxcisunli@126.com>
Date: Fri, 27 Mar 2026 20:50:07 +0800
Subject: [PATCH 09/30] feat: upgrade course model to Chapter hierarchy with
 full classroom binding flow
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Course → Chapter[] → Classroom (replacing flat classroomIds[])
- Read-time migration writes back immediately to stabilize chapter IDs
- CourseFormData decoupled from Course type; publishStatus runtime-derived
- New API: /api/course/chapters (POST/PUT/DELETE); remove old /classrooms route
- ChapterList + ChapterForm + ClassroomPickerDialog UI components
- sessionStorage courseChapterContext with stageId binding; auto-clears on cancel/stale
- Header auto-binds chapter after publish; validates stageId before writing
- Batch /api/classroom fetch replaces N+1 per-chapter requests
- COURSE_CHAPTER_CONTEXT_KEY + CourseChapterContext + ClassroomMeta extracted to lib/types/course.ts
- Fix standalone build: copy static assets in start-8002.sh
- Fix gen_img_* 404: dynamic route app/[mediaId]/route.ts serves media files

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 app/[mediaId]/route.ts                        |  46 +++++
 app/api/course/chapters/route.ts              |  56 +++++
 app/api/course/classrooms/route.ts            |  41 ----
 app/course/[id]/page.tsx                      | 174 +++++++++++++---
 app/course/page.tsx                           |   2 +-
 app/generation-preview/page.tsx               |  14 ++
 app/page.tsx                                  |  60 ++++--
 components/course/chapter-form.tsx            |  57 +++++
 components/course/chapter-list.tsx            | 194 ++++++++++++++++++
 components/course/classroom-picker-dialog.tsx |  88 ++++++++
 components/course/course-form.tsx             |   6 +-
 components/header.tsx                         |  23 +++
 lib/i18n/course.ts                            |  42 +++-
 lib/server/course-storage.ts                  |  90 ++++++--
 lib/store/course.ts                           |  42 ++--
 lib/types/course.ts                           |  36 +++-
 scripts/start-8002.sh                         |   4 +
 17 files changed, 845 insertions(+), 130 deletions(-)
 create mode 100644 app/[mediaId]/route.ts
 create mode 100644 app/api/course/chapters/route.ts
 delete mode 100644 app/api/course/classrooms/route.ts
 create mode 100644 components/course/chapter-form.tsx
 create mode 100644 components/course/chapter-list.tsx
 create mode 100644 components/course/classroom-picker-dialog.tsx

diff --git a/app/[mediaId]/route.ts b/app/[mediaId]/route.ts
new file mode 100644
index 000000000..d04604253
--- /dev/null
+++ b/app/[mediaId]/route.ts
@@ -0,0 +1,46 @@
+import { type NextRequest, NextResponse } from 'next/server';
+import { getMediaPath } from '@/lib/server/media-storage';
+import { promises as fs } from 'fs';
+import path from 'path';
+
+const MIME_MAP: Record<string, string> = {
+  '.mp3': 'audio/mpeg',
+  '.wav': 'audio/wav',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.mp4': 'video/mp4',
+  '.webm': 'video/webm',
+};
+
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ mediaId: string }> }
+) {
+  const { mediaId } = await params;
+
+  if (!mediaId.startsWith('gen_img_') && !mediaId.startsWith('tts_')) {
+    return NextResponse.json({ error: 'Not found' }, { status: 404 });
+  }
+
+  const classroomId = request.nextUrl.searchParams.get('classroomId');
+  if (!classroomId) {
+    return NextResponse.json({ error: 'Missing classroomId' }, { status: 400 });
+  }
+
+  const filePath = await getMediaPath(classroomId, mediaId);
+  if (!filePath) {
+    return NextResponse.json({ error: 'Media not found' }, { status: 404 });
+  }
+
+  const ext = path.extname(filePath).toLowerCase();
+  const contentType = MIME_MAP[ext] || 'application/octet-stream';
+  const buffer = await fs.readFile(filePath);
+
+  return new NextResponse(buffer, {
+    headers: {
+      'Content-Type': contentType,
+      'Cache-Control': 'public, max-age=31536000, immutable',
+    },
+  });
+}
diff --git a/app/api/course/chapters/route.ts b/app/api/course/chapters/route.ts
new file mode 100644
index 000000000..0b64cc104
--- /dev/null
+++ b/app/api/course/chapters/route.ts
@@ -0,0 +1,56 @@
+import { type NextRequest, NextResponse } from 'next/server';
+import { addChapter, updateChapter, removeChapter, reorderChapters } from '@/lib/server/course-storage';
+
+export async function POST(req: NextRequest) {
+  try {
+    const { courseId, title, description } = await req.json();
+    if (!courseId || !title) {
+      return NextResponse.json({ error: 'Missing required fields' }, { status: 400 });
+    }
+    const chapter = await addChapter(courseId, { title, description });
+    return NextResponse.json({ success: true, chapter });
+  } catch (error) {
+    return NextResponse.json({ error: String(error) }, { status: 500 });
+  }
+}
+
+export async function PUT(req: NextRequest) {
+  try {
+    const body = await req.json();
+    const { courseId } = body;
+    if (!courseId) {
+      return NextResponse.json({ error: 'Missing courseId' }, { status: 400 });
+    }
+    // Reorder: { courseId, chapterIds: string[] }
+    if (Array.isArray(body.chapterIds)) {
+      await reorderChapters(courseId, body.chapterIds);
+      return NextResponse.json({ success: true });
+    }
+    // Update single chapter: { courseId, chapterId, ...updates }
+    const { chapterId, title, description, classroomId } = body;
+    if (!chapterId) {
+      return NextResponse.json({ error: 'Missing chapterId' }, { status: 400 });
+    }
+    const updates: Parameters<typeof updateChapter>[2] = {};
+    if (title !== undefined) updates.title = title;
+    if (description !== undefined) updates.description = description;
+    if (classroomId !== undefined) updates.classroomId = classroomId;
+    await updateChapter(courseId, chapterId, updates);
+    return NextResponse.json({ success: true });
+  } catch (error) {
+    return NextResponse.json({ error: String(error) }, { status: 500 });
+  }
+}
+
+export async function DELETE(req: NextRequest) {
+  try {
+    const { courseId, chapterId } = await req.json();
+    if (!courseId || !chapterId) {
+      return NextResponse.json({ error: 'Missing required fields' }, { status: 400 });
+    }
+    await removeChapter(courseId, chapterId);
+    return NextResponse.json({ success: true });
+  } catch (error) {
+    return NextResponse.json({ error: String(error) }, { status: 500 });
+  }
+}
diff --git a/app/api/course/classrooms/route.ts b/app/api/course/classrooms/route.ts
deleted file mode 100644
index 3621e0b4d..000000000
--- a/app/api/course/classrooms/route.ts
+++ /dev/null
@@ -1,41 +0,0 @@
-import { NextRequest, NextResponse } from 'next/server';
-import { addClassroomToCourse, removeClassroomFromCourse, reorderClassrooms } from '@/lib/server/course-storage';
-
-export async function POST(req: NextRequest) {
-  try {
-    const { courseId, classroomId } = await req.json();
-    if (!courseId || !classroomId) {
-      return NextResponse.json({ error: 'Missing required fields' }, { status: 400 });
-    }
-    await addClassroomToCourse(courseId, classroomId);
-    return NextResponse.json({ success: true });
-  } catch (error) {
-    return NextResponse.json({ error: String(error) }, { status: 500 });
-  }
-}
-
-export async function DELETE(req: NextRequest) {
-  try {
-    const { courseId, classroomId } = await req.json();
-    if (!courseId || !classroomId) {
-      return NextResponse.json({ error: 'Missing required fields' }, { status: 400 });
-    }
-    await removeClassroomFromCourse(courseId, classroomId);
-    return NextResponse.json({ success: true });
-  } catch (error) {
-    return NextResponse.json({ error: String(error) }, { status: 500 });
-  }
-}
-
-export async function PUT(req: NextRequest) {
-  try {
-    const { courseId, newOrder } = await req.json();
-    if (!courseId || !newOrder) {
-      return NextResponse.json({ error: 'Missing required fields' }, { status: 400 });
-    }
-    await reorderClassrooms(courseId, newOrder);
-    return NextResponse.json({ success: true });
-  } catch (error) {
-    return NextResponse.json({ error: String(error) }, { status: 500 });
-  }
-}
diff --git a/app/course/[id]/page.tsx b/app/course/[id]/page.tsx
index e890031a6..7c729a464 100644
--- a/app/course/[id]/page.tsx
+++ b/app/course/[id]/page.tsx
@@ -1,28 +1,118 @@
 'use client';
 
-import { useEffect, useState } from 'react';
+import { useEffect, useState, useCallback, useMemo } from 'react';
 import { useRouter } from 'next/navigation';
 import { useI18n } from '@/lib/hooks/use-i18n';
 import { useCourseStore } from '@/lib/store/course';
 import { CourseForm } from '@/components/course/course-form';
+import { ChapterList } from '@/components/course/chapter-list';
+import { ClassroomPickerDialog } from '@/components/course/classroom-picker-dialog';
+import type { ClassroomMeta, CourseChapterContext, CourseFormData } from '@/lib/types/course';
+import { COURSE_CHAPTER_CONTEXT_KEY } from '@/lib/types/course';
 
-export default function CourseDetailPage({ params }: { params: { id: string } }) {
+export default function CourseDetailPage({ params }: { params: Promise<{ id: string }> }) {
   const { t } = useI18n();
   const router = useRouter();
-  const { currentCourse, fetchCourse, updateCourse, removeClassroom } = useCourseStore();
+  const { currentCourse, fetchCourse, updateCourse, addChapter, updateChapter, removeChapter, reorderChapters } =
+    useCourseStore();
   const [editing, setEditing] = useState(false);
+  const [courseId, setCourseId] = useState<string | null>(null);
+  const [classroomMeta, setClassroomMeta] = useState<Record<string, ClassroomMeta>>({});
+  const [bindingChapterId, setBindingChapterId] = useState<string | null>(null);
 
   useEffect(() => {
-    fetchCourse(params.id);
-  }, [params.id, fetchCourse]);
+    params.then(({ id }) => {
+      setCourseId(id);
+      fetchCourse(id);
+    });
+  }, [params, fetchCourse]);
 
-  if (!currentCourse) return <div className="p-8">{t('common.loading')}</div>;
+  // Stable dep: comma-joined sorted classroomIds — only refetch when bound classrooms change
+  const boundClassroomIdsKey = currentCourse?.chapters
+    .map((c) => c.classroomId)
+    .filter((id): id is string => !!id)
+    .sort()
+    .join(',') ?? '';
 
-  const handleUpdate = async (data: Parameters<typeof updateCourse>[1]) => {
-    await updateCourse(params.id, data);
+  const loadClassroomMeta = useCallback(async (classroomIds: string[]) => {
+    try {
+      // Single batch fetch instead of N per-classroom requests
+      const res = await fetch('/api/classroom');
+      if (!res.ok) return;
+      const { classrooms } = await res.json() as { classrooms: Array<{ id: string; name?: string; scenes?: unknown[] }> };
+      const idSet = new Set(classroomIds);
+      setClassroomMeta(
+        Object.fromEntries(
+          classrooms
+            .filter((c) => idSet.has(c.id))
+            .map((c): [string, ClassroomMeta] => [
+              c.id,
+              { name: c.name || c.id, sceneCount: (c.scenes?.length ?? 0), published: true },
+            ]),
+        ),
+      );
+    } catch {
+      // non-fatal, metadata stays empty
+    }
+  }, []);
+
+  useEffect(() => {
+    const ids = boundClassroomIdsKey ? boundClassroomIdsKey.split(',') : [];
+    if (ids.length > 0) loadClassroomMeta(ids);
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [boundClassroomIdsKey, loadClassroomMeta]);
+
+  // Stable set for dialog — only recomputes when bound IDs change
+  const usedClassroomIds = useMemo(
+    () => new Set(currentCourse?.chapters.map((c) => c.classroomId).filter((id): id is string => !!id) ?? []),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [boundClassroomIdsKey],
+  );
+
+  if (!courseId || !currentCourse) return <div className="p-8">{t('common.loading')}</div>;
+
+  const handleUpdate = async (data: CourseFormData) => {
+    await updateCourse(courseId, data);
     setEditing(false);
   };
 
+  const handleMove = async (chapterId: string, direction: 'up' | 'down') => {
+    const chapters = currentCourse.chapters;
+    const idx = chapters.findIndex((c) => c.id === chapterId);
+    if (idx === -1) return;
+    const newIdx = direction === 'up' ? idx - 1 : idx + 1;
+    if (newIdx < 0 || newIdx >= chapters.length) return;
+    const ids = chapters.map((c) => c.id);
+    [ids[idx], ids[newIdx]] = [ids[newIdx], ids[idx]];
+    await reorderChapters(courseId, ids);
+  };
+
+  const handleUnbind = async (chapterId: string) => {
+    await updateChapter(courseId, chapterId, { classroomId: undefined });
+  };
+
+  const handleBind = (chapterId: string) => {
+    setBindingChapterId(chapterId);
+  };
+
+  const handlePickerSelect = async (classroomId: string) => {
+    if (!bindingChapterId) return;
+    await updateChapter(courseId, bindingChapterId, { classroomId });
+    setBindingChapterId(null);
+  };
+
+  const handleCreateAndBind = (chapterId: string) => {
+    sessionStorage.setItem(
+      COURSE_CHAPTER_CONTEXT_KEY,
+      JSON.stringify({ courseId, chapterId, stageId: null } satisfies CourseChapterContext),
+    );
+    router.push('/');
+  };
+
+  const handleOpenClassroom = (classroomId: string) => {
+    router.push(`/classroom/${classroomId}`);
+  };
+
   if (editing) {
     return (
       <div className="p-8 max-w-2xl mx-auto">
@@ -33,33 +123,59 @@ export default function CourseDetailPage({ params }: { params: { id: string } })
   }
 
   return (
-    <div className="p-8">
+    <div className="p-8 max-w-4xl mx-auto">
       <div className="flex justify-between items-center mb-6">
-        <h1 className="text-2xl">{currentCourse.name}</h1>
+        <div>
+          <button onClick={() => router.push('/course')} className="text-sm text-gray-500 hover:text-gray-700 mb-2 block">
+            ← {t('course.myCourses')}
+          </button>
+          <h1 className="text-2xl">{currentCourse.name}</h1>
+        </div>
         <button onClick={() => setEditing(true)} className="px-4 py-2 border rounded">
           {t('course.edit')}
         </button>
       </div>
-      <div className="mb-6 space-y-2">
-        <p><strong>{t('course.college')}:</strong> {currentCourse.college}</p>
-        <p><strong>{t('course.major')}:</strong> {currentCourse.major}</p>
-        <p><strong>{t('course.teacherName')}:</strong> {currentCourse.teacherName}</p>
-        <p><strong>{t('course.description')}:</strong> {currentCourse.description}</p>
+
+      <div className="mb-8 space-y-1.5 text-sm">
+        <p>
+          <span className="text-gray-500">{t('course.college')}:</span> {currentCourse.college}
+        </p>
+        <p>
+          <span className="text-gray-500">{t('course.major')}:</span> {currentCourse.major}
+        </p>
+        <p>
+          <span className="text-gray-500">{t('course.teacherName')}:</span> {currentCourse.teacherName}
+        </p>
+        <p>
+          <span className="text-gray-500">{t('course.description')}:</span> {currentCourse.description}
+        </p>
       </div>
-      <h2 className="text-xl mb-4">{t('course.classroomCount')}: {currentCourse.classroomIds.length}</h2>
-      {currentCourse.classroomIds.length === 0 ? (
-        <p className="text-gray-500">{t('course.noClassrooms')}</p>
-      ) : (
-        <div className="space-y-2">
-          {currentCourse.classroomIds.map((id) => (
-            <div key={id} className="border rounded p-4 flex justify-between items-center">
-              <span className="cursor-pointer" onClick={() => router.push(`/classroom/${id}`)}>{id}</span>
-              <button onClick={() => removeClassroom(params.id, id)} className="text-red-500 text-sm">
-                {t('course.removeClassroom')}
-              </button>
-            </div>
-          ))}
-        </div>
+
+      <div>
+        <h2 className="text-lg font-medium mb-3">
+          {t('course.chapter')} ({currentCourse.chapters.length})
+        </h2>
+        <ChapterList
+          courseId={courseId}
+          chapters={currentCourse.chapters}
+          classroomMeta={classroomMeta}
+          onAdd={(title, description) => addChapter(courseId, title, description)}
+          onEdit={(chapterId, title, description) => updateChapter(courseId, chapterId, { title, description })}
+          onRemove={(chapterId) => removeChapter(courseId, chapterId)}
+          onMove={handleMove}
+          onBind={handleBind}
+          onUnbind={handleUnbind}
+          onCreateAndBind={handleCreateAndBind}
+          onOpenClassroom={handleOpenClassroom}
+        />
+      </div>
+
+      {bindingChapterId && (
+        <ClassroomPickerDialog
+          usedClassroomIds={usedClassroomIds}
+          onSelect={handlePickerSelect}
+          onClose={() => setBindingChapterId(null)}
+        />
       )}
     </div>
   );
diff --git a/app/course/page.tsx b/app/course/page.tsx
index 46f7bc08f..6c2267e6f 100644
--- a/app/course/page.tsx
+++ b/app/course/page.tsx
@@ -55,7 +55,7 @@ export default function CoursePage() {
                 <p className="text-sm text-gray-600">{course.college} - {course.major}</p>
                 <p className="text-sm text-gray-500 mt-2">{course.description}</p>
                 <p className="text-sm mt-2">{t('course.teacherName')}: {course.teacherName}</p>
-                <p className="text-sm text-gray-500">{t('course.classroomCount')}: {course.classroomCount}</p>
+                <p className="text-sm text-gray-500">{t('course.chapterCount')}: {course.chapterCount}</p>
               </div>
               <button onClick={() => handleDelete(course.id)} className="mt-2 text-red-500 text-sm">
                 {t('course.delete')}
diff --git a/app/generation-preview/page.tsx b/app/generation-preview/page.tsx
index 213a51409..6d0b01788 100644
--- a/app/generation-preview/page.tsx
+++ b/app/generation-preview/page.tsx
@@ -23,6 +23,7 @@ import { db } from '@/lib/utils/database';
 import { MAX_PDF_CONTENT_CHARS, MAX_VISION_IMAGES } from '@/lib/constants/generation';
 import { nanoid } from 'nanoid';
 import type { Stage } from '@/lib/types/stage';
+import { COURSE_CHAPTER_CONTEXT_KEY, type CourseChapterContext } from '@/lib/types/course';
 import type { SceneOutline, PdfImage, ImageMapping } from '@/lib/types/generation';
 import { AgentRevealModal } from '@/components/agent/agent-reveal-modal';
 import { createLogger } from '@/lib/logger';
@@ -373,6 +374,18 @@ function GenerationPreviewContent() {
         updatedAt: Date.now(),
       };
 
+      // Write stageId into courseChapterContext so publish can do the binding
+      try {
+        const ctxStr = sessionStorage.getItem(COURSE_CHAPTER_CONTEXT_KEY);
+        if (ctxStr) {
+          const ctx = JSON.parse(ctxStr) as CourseChapterContext;
+          ctx.stageId = stageId;
+          sessionStorage.setItem(COURSE_CHAPTER_CONTEXT_KEY, JSON.stringify(ctx));
+        }
+      } catch {
+        // non-fatal
+      }
+
       if (settings.agentMode === 'auto') {
         const agentStepIdx = activeSteps.findIndex((s) => s.id === 'agent-generation');
         if (agentStepIdx >= 0) setCurrentStepIndex(agentStepIdx);
@@ -745,6 +758,7 @@ function GenerationPreviewContent() {
   const goBackToHome = () => {
     abortControllerRef.current?.abort();
     sessionStorage.removeItem('generationSession');
+    sessionStorage.removeItem(COURSE_CHAPTER_CONTEXT_KEY);
     router.push('/');
   };
 
diff --git a/app/page.tsx b/app/page.tsx
index a42ab0ae5..b4dd15a95 100644
--- a/app/page.tsx
+++ b/app/page.tsx
@@ -32,6 +32,7 @@ import { useTheme } from '@/lib/hooks/use-theme';
 import { nanoid } from 'nanoid';
 import { storePdfBlob } from '@/lib/utils/image-storage';
 import type { UserRequirements } from '@/lib/types/generation';
+import { COURSE_CHAPTER_CONTEXT_KEY, type CourseChapterContext } from '@/lib/types/course';
 import { useSettingsStore } from '@/lib/store/settings';
 import { useUserProfileStore, AVATAR_OPTIONS } from '@/lib/store/user-profile';
 import {
@@ -195,7 +196,15 @@ function HomePage() {
         setPublicClassrooms(publicData.classrooms);
         const thumbs: Record<string, Slide> = {};
         for (const c of publicData.classrooms) {
-          if (c.firstSlide) thumbs[c.id] = c.firstSlide;
+          if (c.firstSlide) {
+            const slide = structuredClone(c.firstSlide);
+            for (const el of slide.elements as Array<{ type: string; src?: string }>) {
+              if (el.type === 'image' && el.src && /^gen_(img|vid)_[\w-]+$/i.test(el.src)) {
+                el.src = `/api/classroom/media?id=${encodeURIComponent(c.id)}&file=${encodeURIComponent(el.src)}`;
+              }
+            }
+            thumbs[c.id] = slide;
+          }
         }
         setPublicThumbnails(thumbs);
       }
@@ -322,6 +331,19 @@ function HomePage() {
         currentStep: 'generating' as const,
       };
       sessionStorage.setItem('generationSession', JSON.stringify(sessionState));
+      // If there is a stale context (stageId already set from a prior generation),
+      // remove it so this new generation starts fresh without an accidental chapter binding.
+      try {
+        const ctxStr = sessionStorage.getItem(COURSE_CHAPTER_CONTEXT_KEY);
+        if (ctxStr) {
+          const ctx = JSON.parse(ctxStr) as CourseChapterContext;
+          if (ctx.stageId !== null) {
+            sessionStorage.removeItem(COURSE_CHAPTER_CONTEXT_KEY);
+          }
+        }
+      } catch {
+        sessionStorage.removeItem(COURSE_CHAPTER_CONTEXT_KEY);
+      }
 
       router.push('/generation-preview');
     } catch (err) {
@@ -704,19 +726,33 @@ function HomePage() {
           </div>
 
           {/* Courses tab */}
-          {activeTab === 'courses' && courses.length > 0 && (
-            <div className="w-full grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-4">
-              {courses.map((course) => (
-                <div
-                  key={course.id}
-                  onClick={() => router.push(`/course/${course.id}`)}
-                  className="border rounded p-4 cursor-pointer hover:shadow-lg transition-shadow"
+          {activeTab === 'courses' && (
+            <div className="w-full">
+              <div className="flex justify-end mb-3">
+                <button
+                  onClick={() => router.push('/course')}
+                  className="px-3 py-1.5 bg-blue-500 text-white text-sm rounded hover:bg-blue-600 transition-colors"
                 >
-                  <h3 className="font-semibold">{course.name}</h3>
-                  <p className="text-sm text-gray-600">{course.college}</p>
-                  <p className="text-xs text-gray-500 mt-2">{course.classroomCount} {t('course.classroomCount')}</p>
+                  {t('course.manage')}
+                </button>
+              </div>
+              {courses.length === 0 ? (
+                <p className="text-center text-gray-500 py-8">{t('course.noCourses')}</p>
+              ) : (
+                <div className="grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-4">
+                  {courses.map((course) => (
+                    <div
+                      key={course.id}
+                      onClick={() => router.push(`/course/${course.id}`)}
+                      className="border rounded p-4 cursor-pointer hover:shadow-lg transition-shadow"
+                    >
+                      <h3 className="font-semibold">{course.name}</h3>
+                      <p className="text-sm text-gray-600">{course.college}</p>
+                      <p className="text-xs text-gray-500 mt-2">{course.chapterCount} {t('course.chapterCount')}</p>
+                    </div>
+                  ))}
                 </div>
-              ))}
+              )}
             </div>
           )}
 
diff --git a/components/course/chapter-form.tsx b/components/course/chapter-form.tsx
new file mode 100644
index 000000000..b2f23edf4
--- /dev/null
+++ b/components/course/chapter-form.tsx
@@ -0,0 +1,57 @@
+'use client';
+
+import { useState } from 'react';
+import { useI18n } from '@/lib/hooks/use-i18n';
+
+interface ChapterFormProps {
+  initialTitle?: string;
+  initialDescription?: string;
+  onSubmit: (title: string, description?: string) => void;
+  onCancel: () => void;
+}
+
+export function ChapterForm({ initialTitle = '', initialDescription = '', onSubmit, onCancel }: ChapterFormProps) {
+  const { t } = useI18n();
+  const [title, setTitle] = useState(initialTitle);
+  const [description, setDescription] = useState(initialDescription);
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!title.trim()) return;
+    onSubmit(title.trim(), description.trim() || undefined);
+  };
+
+  return (
+    <form onSubmit={handleSubmit} className="space-y-3">
+      <div>
+        <label className="block text-sm font-medium mb-1">{t('course.chapterTitle')}</label>
+        <input
+          type="text"
+          value={title}
+          onChange={(e) => setTitle(e.target.value)}
+          className="w-full px-3 py-2 border rounded text-sm"
+          autoFocus
+          required
+        />
+      </div>
+      <div>
+        <label className="block text-sm font-medium mb-1">{t('course.chapterDescription')}</label>
+        <input
+          type="text"
+          value={description}
+          onChange={(e) => setDescription(e.target.value)}
+          className="w-full px-3 py-2 border rounded text-sm"
+          placeholder="（可选）"
+        />
+      </div>
+      <div className="flex gap-2">
+        <button type="submit" className="px-3 py-1.5 bg-blue-500 text-white text-sm rounded hover:bg-blue-600">
+          {t('common.confirm')}
+        </button>
+        <button type="button" onClick={onCancel} className="px-3 py-1.5 border text-sm rounded hover:bg-gray-50">
+          {t('common.cancel')}
+        </button>
+      </div>
+    </form>
+  );
+}
diff --git a/components/course/chapter-list.tsx b/components/course/chapter-list.tsx
new file mode 100644
index 000000000..c686719ae
--- /dev/null
+++ b/components/course/chapter-list.tsx
@@ -0,0 +1,194 @@
+'use client';
+
+import { useState } from 'react';
+import { useI18n } from '@/lib/hooks/use-i18n';
+import type { ClassroomMeta, CourseChapter } from '@/lib/types/course';
+import { ChapterForm } from './chapter-form';
+
+interface ChapterListProps {
+  courseId: string;
+  chapters: CourseChapter[];
+  classroomMeta: Record<string, ClassroomMeta>;
+  onAdd: (title: string, description?: string) => Promise<void>;
+  onEdit: (chapterId: string, title: string, description?: string) => Promise<void>;
+  onRemove: (chapterId: string) => Promise<void>;
+  onMove: (chapterId: string, direction: 'up' | 'down') => Promise<void>;
+  onBind: (chapterId: string) => void;
+  onUnbind: (chapterId: string) => Promise<void>;
+  onCreateAndBind: (chapterId: string) => void;
+  onOpenClassroom: (classroomId: string) => void;
+}
+
+export function ChapterList({
+  courseId: _courseId,
+  chapters,
+  classroomMeta,
+  onAdd,
+  onEdit,
+  onRemove,
+  onMove,
+  onBind,
+  onUnbind,
+  onCreateAndBind,
+  onOpenClassroom,
+}: ChapterListProps) {
+  const { t } = useI18n();
+  const [showAddForm, setShowAddForm] = useState(false);
+  const [editingId, setEditingId] = useState<string | null>(null);
+
+  const handleAdd = async (title: string, description?: string) => {
+    await onAdd(title, description);
+    setShowAddForm(false);
+  };
+
+  const handleEdit = async (chapterId: string, title: string, description?: string) => {
+    await onEdit(chapterId, title, description);
+    setEditingId(null);
+  };
+
+  const handleRemove = async (chapterId: string) => {
+    if (!confirm(t('course.confirmRemoveChapter'))) return;
+    await onRemove(chapterId);
+  };
+
+  if (chapters.length === 0 && !showAddForm) {
+    return (
+      <div className="text-center py-12 text-gray-500">
+        <p className="mb-4">{t('course.noChapters')}</p>
+        <button
+          onClick={() => setShowAddForm(true)}
+          className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600 text-sm"
+        >
+          {t('course.addChapter')}
+        </button>
+      </div>
+    );
+  }
+
+  return (
+    <div className="space-y-3">
+      {chapters.map((chapter, idx) => {
+        const meta = chapter.classroomId ? classroomMeta[chapter.classroomId] : undefined;
+        const isEditing = editingId === chapter.id;
+
+        return (
+          <div key={chapter.id} className="border rounded-lg p-4">
+            {isEditing ? (
+              <ChapterForm
+                initialTitle={chapter.title}
+                initialDescription={chapter.description}
+                onSubmit={(title, description) => handleEdit(chapter.id, title, description)}
+                onCancel={() => setEditingId(null)}
+              />
+            ) : (
+              <div className="flex items-start gap-3">
+                {/* Order number */}
+                <span className="flex-shrink-0 w-7 h-7 rounded-full bg-gray-100 flex items-center justify-center text-sm font-medium text-gray-600">
+                  {idx + 1}
+                </span>
+
+                {/* Content */}
+                <div className="flex-1 min-w-0">
+                  <div className="flex items-center gap-2 flex-wrap">
+                    <span className="font-medium">{chapter.title}</span>
+                    {chapter.classroomId && (
+                      <span
+                        className={`text-xs px-1.5 py-0.5 rounded-full ${
+                          meta?.published
+                            ? 'bg-green-100 text-green-700'
+                            : 'bg-gray-100 text-gray-500'
+                        }`}
+                      >
+                        {meta?.published ? t('course.published') : t('course.unpublished')}
+                      </span>
+                    )}
+                  </div>
+                  {chapter.description && (
+                    <p className="text-sm text-gray-500 mt-0.5">{chapter.description}</p>
+                  )}
+                  {chapter.classroomId && meta && (
+                    <button
+                      onClick={() => onOpenClassroom(chapter.classroomId!)}
+                      className="text-sm text-blue-600 hover:underline mt-1"
+                    >
+                      {meta.name} · {meta.sceneCount} 个场景
+                    </button>
+                  )}
+                </div>
+
+                {/* Actions */}
+                <div className="flex items-center gap-1 flex-shrink-0">
+                  <button
+                    onClick={() => onMove(chapter.id, 'up')}
+                    disabled={idx === 0}
+                    className="p-1 text-gray-400 hover:text-gray-600 disabled:opacity-30 disabled:cursor-not-allowed text-xs"
+                    title={t('course.moveUp')}
+                  >
+                    ↑
+                  </button>
+                  <button
+                    onClick={() => onMove(chapter.id, 'down')}
+                    disabled={idx === chapters.length - 1}
+                    className="p-1 text-gray-400 hover:text-gray-600 disabled:opacity-30 disabled:cursor-not-allowed text-xs"
+                    title={t('course.moveDown')}
+                  >
+                    ↓
+                  </button>
+                  <button
+                    onClick={() => setEditingId(chapter.id)}
+                    className="px-2 py-1 text-xs border rounded hover:bg-gray-50"
+                  >
+                    {t('course.editChapter')}
+                  </button>
+                  {chapter.classroomId ? (
+                    <button
+                      onClick={() => onUnbind(chapter.id)}
+                      className="px-2 py-1 text-xs border rounded hover:bg-gray-50"
+                    >
+                      {t('course.unbindClassroom')}
+                    </button>
+                  ) : (
+                    <>
+                      <button
+                        onClick={() => onBind(chapter.id)}
+                        className="px-2 py-1 text-xs border rounded hover:bg-gray-50"
+                      >
+                        {t('course.bindClassroom')}
+                      </button>
+                      <button
+                        onClick={() => onCreateAndBind(chapter.id)}
+                        className="px-2 py-1 text-xs bg-blue-500 text-white rounded hover:bg-blue-600"
+                      >
+                        {t('course.createAndBindClassroom')}
+                      </button>
+                    </>
+                  )}
+                  <button
+                    onClick={() => handleRemove(chapter.id)}
+                    className="px-2 py-1 text-xs text-red-500 border border-red-200 rounded hover:bg-red-50"
+                  >
+                    {t('course.removeChapter')}
+                  </button>
+                </div>
+              </div>
+            )}
+          </div>
+        );
+      })}
+
+      {/* Add form */}
+      {showAddForm ? (
+        <div className="border rounded-lg p-4">
+          <ChapterForm onSubmit={handleAdd} onCancel={() => setShowAddForm(false)} />
+        </div>
+      ) : (
+        <button
+          onClick={() => setShowAddForm(true)}
+          className="w-full py-2 border border-dashed rounded-lg text-sm text-gray-500 hover:border-blue-400 hover:text-blue-500 transition-colors"
+        >
+          + {t('course.addChapter')}
+        </button>
+      )}
+    </div>
+  );
+}
diff --git a/components/course/classroom-picker-dialog.tsx b/components/course/classroom-picker-dialog.tsx
new file mode 100644
index 000000000..be14f03b0
--- /dev/null
+++ b/components/course/classroom-picker-dialog.tsx
@@ -0,0 +1,88 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+interface PublishedClassroom {
+  id: string;
+  name: string;
+  sceneCount: number;
+}
+
+interface ClassroomPickerDialogProps {
+  /** Chapter IDs already bound in the course — exclude from picker */
+  usedClassroomIds: Set<string>;
+  onSelect: (classroomId: string) => Promise<void>;
+  onClose: () => void;
+}
+
+export function ClassroomPickerDialog({ usedClassroomIds, onSelect, onClose }: ClassroomPickerDialogProps) {
+  const [classrooms, setClassrooms] = useState<PublishedClassroom[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [submitting, setSubmitting] = useState(false);
+
+  useEffect(() => {
+    fetch('/api/classroom')
+      .then((r) => r.json())
+      .then((list: Array<{ id: string; name?: string; scenes?: unknown[] }>) => {
+        const items: PublishedClassroom[] = list
+          .filter((c) => !usedClassroomIds.has(c.id))
+          .map((c) => ({
+            id: c.id,
+            name: c.name || c.id,
+            sceneCount: c.scenes?.length ?? 0,
+          }));
+        setClassrooms(items);
+      })
+      .catch(console.error)
+      .finally(() => setLoading(false));
+  }, [usedClassroomIds]);
+
+  const handleSelect = async (id: string) => {
+    setSubmitting(true);
+    try {
+      await onSelect(id);
+      onClose();
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  return (
+    <div className="fixed inset-0 bg-black/40 flex items-center justify-center z-50" onClick={onClose}>
+      <div
+        className="bg-white rounded-lg shadow-xl w-full max-w-md max-h-[70vh] flex flex-col"
+        onClick={(e) => e.stopPropagation()}
+      >
+        <div className="flex items-center justify-between px-5 py-4 border-b">
+          <h2 className="text-base font-semibold">选择已发布课堂</h2>
+          <button onClick={onClose} className="text-gray-400 hover:text-gray-600 text-lg leading-none">
+            ×
+          </button>
+        </div>
+
+        <div className="overflow-y-auto flex-1 px-3 py-2">
+          {loading ? (
+            <p className="text-center text-gray-500 py-8 text-sm">加载中…</p>
+          ) : classrooms.length === 0 ? (
+            <p className="text-center text-gray-500 py-8 text-sm">暂无可绑定的已发布课堂</p>
+          ) : (
+            <ul className="space-y-1.5">
+              {classrooms.map((c) => (
+                <li key={c.id}>
+                  <button
+                    disabled={submitting}
+                    onClick={() => handleSelect(c.id)}
+                    className="w-full text-left px-4 py-3 rounded-lg border hover:border-blue-400 hover:bg-blue-50 transition-colors disabled:opacity-50"
+                  >
+                    <div className="font-medium text-sm">{c.name}</div>
+                    <div className="text-xs text-gray-500 mt-0.5">{c.sceneCount} 个场景</div>
+                  </button>
+                </li>
+              ))}
+            </ul>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/components/course/course-form.tsx b/components/course/course-form.tsx
index 2fbf602d4..19db330d6 100644
--- a/components/course/course-form.tsx
+++ b/components/course/course-form.tsx
@@ -2,11 +2,11 @@
 
 import { useState } from 'react';
 import { useI18n } from '@/lib/hooks/use-i18n';
-import type { Course } from '@/lib/types/course';
+import type { CourseFormData } from '@/lib/types/course';
 
 interface CourseFormProps {
-  initialData?: Partial<Course>;
-  onSubmit: (data: Omit<Course, 'id' | 'createdAt' | 'updatedAt' | 'classroomIds'>) => void;
+  initialData?: Partial<CourseFormData>;
+  onSubmit: (data: CourseFormData) => void;
   onCancel: () => void;
 }
 
diff --git a/components/header.tsx b/components/header.tsx
index 6fc70428e..f93e54469 100644
--- a/components/header.tsx
+++ b/components/header.tsx
@@ -25,6 +25,7 @@ import { useExportPPTX } from '@/lib/export/use-export-pptx';
 import { db } from '@/lib/utils/database';
 import { toast } from 'sonner';
 import { createLogger } from '@/lib/logger';
+import { COURSE_CHAPTER_CONTEXT_KEY, type CourseChapterContext } from '@/lib/types/course';
 
 interface HeaderProps {
   readonly currentSceneTitle: string;
@@ -137,6 +138,28 @@ export function Header({ currentSceneTitle }: HeaderProps) {
       }
 
       toast.success(t('share.publishSuccess'));
+
+      // Auto-bind to course chapter if this classroom was created from a chapter context
+      try {
+        const ctxStr = sessionStorage.getItem(COURSE_CHAPTER_CONTEXT_KEY);
+        if (ctxStr && stage) {
+          const ctx = JSON.parse(ctxStr) as CourseChapterContext;
+          if (ctx.stageId === stage.id) {
+            await fetch('/api/course/chapters', {
+              method: 'PUT',
+              headers: { 'Content-Type': 'application/json' },
+              body: JSON.stringify({
+                courseId: ctx.courseId,
+                chapterId: ctx.chapterId,
+                classroomId: stage.id,
+              }),
+            });
+            sessionStorage.removeItem(COURSE_CHAPTER_CONTEXT_KEY);
+          }
+        }
+      } catch (err) {
+        log.warn('Auto-bind to chapter failed (non-fatal):', err);
+      }
     } catch (err) {
       log.error('Publish failed:', err);
       toast.error(t('share.publishFailed'));
diff --git a/lib/i18n/course.ts b/lib/i18n/course.ts
index fe181456a..433b20627 100644
--- a/lib/i18n/course.ts
+++ b/lib/i18n/course.ts
@@ -8,14 +8,29 @@ export const courseZhCN = {
     create: '创建课程',
     edit: '编辑课程',
     delete: '删除课程',
-    classroomCount: '课堂数量',
+    manage: '管理课程',
     myCourses: '我的课程',
     standaloneClassrooms: '独立课堂',
-    addClassroom: '添加课堂',
-    removeClassroom: '移除课堂',
     noCourses: '暂无课程',
     noClassrooms: '暂无课堂',
     confirmDelete: '确定删除此课程吗？',
+    // chapter
+    chapter: '章节',
+    chapterTitle: '章节标题',
+    chapterDescription: '章节简介',
+    addChapter: '添加章节',
+    editChapter: '编辑章节',
+    removeChapter: '删除章节',
+    confirmRemoveChapter: '确定删除此章节吗？',
+    chapterCount: '章节数量',
+    noChapters: '暂无章节，点击下方按钮添加第一个章节',
+    bindClassroom: '绑定课堂',
+    unbindClassroom: '解绑课堂',
+    createAndBindClassroom: '新建课堂并绑定',
+    published: '已发布',
+    unpublished: '未发布',
+    moveUp: '上移',
+    moveDown: '下移',
   },
 };
 
@@ -29,13 +44,28 @@ export const courseEnUS = {
     create: 'Create Course',
     edit: 'Edit Course',
     delete: 'Delete Course',
-    classroomCount: 'Classroom Count',
+    manage: 'Manage Courses',
     myCourses: 'My Courses',
     standaloneClassrooms: 'Standalone Classrooms',
-    addClassroom: 'Add Classroom',
-    removeClassroom: 'Remove Classroom',
     noCourses: 'No courses yet',
     noClassrooms: 'No classrooms yet',
     confirmDelete: 'Are you sure you want to delete this course?',
+    // chapter
+    chapter: 'Chapter',
+    chapterTitle: 'Chapter Title',
+    chapterDescription: 'Chapter Description',
+    addChapter: 'Add Chapter',
+    editChapter: 'Edit Chapter',
+    removeChapter: 'Delete Chapter',
+    confirmRemoveChapter: 'Are you sure you want to delete this chapter?',
+    chapterCount: 'Chapter Count',
+    noChapters: 'No chapters yet. Click the button below to add the first one.',
+    bindClassroom: 'Bind Classroom',
+    unbindClassroom: 'Unbind',
+    createAndBindClassroom: 'Create & Bind Classroom',
+    published: 'Published',
+    unpublished: 'Unpublished',
+    moveUp: 'Move Up',
+    moveDown: 'Move Down',
   },
 };
diff --git a/lib/server/course-storage.ts b/lib/server/course-storage.ts
index d460690fd..fb82fb5c5 100644
--- a/lib/server/course-storage.ts
+++ b/lib/server/course-storage.ts
@@ -1,6 +1,7 @@
 import { promises as fs } from 'fs';
 import path from 'path';
-import type { Course, CourseListItem } from '@/lib/types/course';
+import { nanoid } from 'nanoid';
+import type { Course, CourseChapter, CourseListItem } from '@/lib/types/course';
 import { PROJECT_ROOT, writeJsonFileAtomic } from './classroom-storage';
 import { withCourseLock } from './course-lock';
 
@@ -10,6 +11,26 @@ async function ensureCoursesDir() {
   await fs.mkdir(COURSES_DIR, { recursive: true });
 }
 
+// Migrate old-format course (classroomIds[]) to new format (chapters[]).
+// Writes back immediately to stabilize chapter IDs.
+async function migrateCourseIfNeeded(
+  filePath: string,
+  raw: Record<string, unknown>,
+): Promise<Course> {
+  if (Array.isArray((raw as unknown as Course).chapters)) return raw as unknown as Course;
+  const ids = (raw.classroomIds as string[] | undefined) ?? [];
+  const chapters: CourseChapter[] = ids.map((cid, i) => ({
+    id: nanoid(10),
+    title: `第 ${i + 1} 章`,
+    order: i,
+    classroomId: cid,
+  }));
+  const { classroomIds: _removed, ...rest } = raw;
+  const migrated = { ...(rest as Omit<Course, 'chapters'>), chapters } as Course;
+  await writeJsonFileAtomic(filePath, migrated);
+  return migrated;
+}
+
 export async function persistCourse(course: Course): Promise<void> {
   await ensureCoursesDir();
   const filePath = path.join(COURSES_DIR, `${course.id}.json`);
@@ -20,7 +41,8 @@ export async function readCourse(id: string): Promise<Course | null> {
   const filePath = path.join(COURSES_DIR, `${id}.json`);
   try {
     const content = await fs.readFile(filePath, 'utf-8');
-    return JSON.parse(content) as Course;
+    const raw = JSON.parse(content) as Record<string, unknown>;
+    return await migrateCourseIfNeeded(filePath, raw);
   } catch {
     return null;
   }
@@ -30,13 +52,15 @@ export async function listCourses(): Promise<CourseListItem[]> {
   await ensureCoursesDir();
   try {
     const files = await fs.readdir(COURSES_DIR);
-    const jsonFiles = files.filter(f => f.endsWith('.json'));
+    const jsonFiles = files.filter((f) => f.endsWith('.json'));
 
     const courses = await Promise.all(
       jsonFiles.map(async (file) => {
+        const filePath = path.join(COURSES_DIR, file);
         try {
-          const content = await fs.readFile(path.join(COURSES_DIR, file), 'utf-8');
-          const course = JSON.parse(content) as Course;
+          const content = await fs.readFile(filePath, 'utf-8');
+          const raw = JSON.parse(content) as Record<string, unknown>;
+          const course = await migrateCourseIfNeeded(filePath, raw);
           return {
             id: course.id,
             name: course.name,
@@ -44,13 +68,13 @@ export async function listCourses(): Promise<CourseListItem[]> {
             major: course.major,
             description: course.description,
             teacherName: course.teacherName,
-            classroomCount: course.classroomIds.length,
+            chapterCount: course.chapters.length,
             createdAt: course.createdAt,
-          };
+          } satisfies CourseListItem;
         } catch {
           return null;
         }
-      })
+      }),
     );
 
     return courses
@@ -66,35 +90,63 @@ export async function deleteCourse(id: string): Promise<void> {
   await fs.unlink(filePath);
 }
 
-export async function addClassroomToCourse(courseId: string, classroomId: string): Promise<void> {
-  await withCourseLock(courseId, async () => {
+export async function addChapter(
+  courseId: string,
+  data: { title: string; description?: string },
+): Promise<CourseChapter> {
+  return withCourseLock(courseId, async () => {
     const course = await readCourse(courseId);
     if (!course) throw new Error('Course not found');
-    if (!course.classroomIds.includes(classroomId)) {
-      course.classroomIds.push(classroomId);
-      course.updatedAt = new Date().toISOString();
-      await persistCourse(course);
-    }
+    const chapter: CourseChapter = {
+      id: nanoid(10),
+      title: data.title,
+      description: data.description,
+      order: course.chapters.length,
+    };
+    course.chapters.push(chapter);
+    course.updatedAt = new Date().toISOString();
+    await persistCourse(course);
+    return chapter;
   });
 }
 
-export async function removeClassroomFromCourse(courseId: string, classroomId: string): Promise<void> {
+export async function updateChapter(
+  courseId: string,
+  chapterId: string,
+  updates: Partial<Pick<CourseChapter, 'title' | 'description' | 'classroomId'>>,
+): Promise<void> {
   await withCourseLock(courseId, async () => {
     const course = await readCourse(courseId);
     if (!course) throw new Error('Course not found');
-    course.classroomIds = course.classroomIds.filter(id => id !== classroomId);
+    const chapter = course.chapters.find((c) => c.id === chapterId);
+    if (!chapter) throw new Error('Chapter not found');
+    Object.assign(chapter, updates);
     course.updatedAt = new Date().toISOString();
     await persistCourse(course);
   });
 }
 
-export async function reorderClassrooms(courseId: string, newOrder: string[]): Promise<void> {
+export async function removeChapter(courseId: string, chapterId: string): Promise<void> {
   await withCourseLock(courseId, async () => {
     const course = await readCourse(courseId);
     if (!course) throw new Error('Course not found');
-    course.classroomIds = newOrder;
+    course.chapters = course.chapters
+      .filter((c) => c.id !== chapterId)
+      .map((c, i) => ({ ...c, order: i }));
     course.updatedAt = new Date().toISOString();
     await persistCourse(course);
   });
 }
 
+export async function reorderChapters(courseId: string, chapterIds: string[]): Promise<void> {
+  await withCourseLock(courseId, async () => {
+    const course = await readCourse(courseId);
+    if (!course) throw new Error('Course not found');
+    const chapterMap = new Map(course.chapters.map((c) => [c.id, c]));
+    course.chapters = chapterIds
+      .filter((id) => chapterMap.has(id))
+      .map((id, i) => ({ ...chapterMap.get(id)!, order: i }));
+    course.updatedAt = new Date().toISOString();
+    await persistCourse(course);
+  });
+}
diff --git a/lib/store/course.ts b/lib/store/course.ts
index b08fb66b0..e0eaf86de 100644
--- a/lib/store/course.ts
+++ b/lib/store/course.ts
@@ -1,5 +1,5 @@
 import { create } from 'zustand';
-import type { Course, CourseListItem } from '@/lib/types/course';
+import type { Course, CourseChapter, CourseFormData, CourseListItem } from '@/lib/types/course';
 import { nanoid } from 'nanoid';
 
 interface CourseState {
@@ -8,12 +8,13 @@ interface CourseState {
   isLoading: boolean;
   fetchCourses: () => Promise<void>;
   fetchCourse: (id: string) => Promise<void>;
-  createCourse: (data: Omit<Course, 'id' | 'createdAt' | 'updatedAt' | 'classroomIds'>) => Promise<string>;
-  updateCourse: (id: string, data: Partial<Course>) => Promise<void>;
+  createCourse: (data: CourseFormData) => Promise<string>;
+  updateCourse: (id: string, data: Partial<CourseFormData>) => Promise<void>;
   deleteCourse: (id: string) => Promise<void>;
-  addClassroom: (courseId: string, classroomId: string) => Promise<void>;
-  removeClassroom: (courseId: string, classroomId: string) => Promise<void>;
-  reorderClassrooms: (courseId: string, newOrder: string[]) => Promise<void>;
+  addChapter: (courseId: string, title: string, description?: string) => Promise<void>;
+  updateChapter: (courseId: string, chapterId: string, updates: Partial<CourseChapter>) => Promise<void>;
+  removeChapter: (courseId: string, chapterId: string) => Promise<void>;
+  reorderChapters: (courseId: string, chapterIds: string[]) => Promise<void>;
 }
 
 export const useCourseStore = create<CourseState>((set, get) => ({
@@ -51,7 +52,7 @@ export const useCourseStore = create<CourseState>((set, get) => ({
     const id = `course_${nanoid(10)}`;
     const course: Course = {
       ...data,
-      classroomIds: [],
+      chapters: [],
       id,
       createdAt: new Date().toISOString(),
       updatedAt: new Date().toISOString(),
@@ -85,29 +86,38 @@ export const useCourseStore = create<CourseState>((set, get) => ({
     await get().fetchCourses();
   },
 
-  addClassroom: async (courseId, classroomId) => {
-    await fetch('/api/course/classrooms', {
+  addChapter: async (courseId, title, description) => {
+    await fetch('/api/course/chapters', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ courseId, classroomId }),
+      body: JSON.stringify({ courseId, title, description }),
     });
     await get().fetchCourse(courseId);
   },
 
-  removeClassroom: async (courseId, classroomId) => {
-    await fetch('/api/course/classrooms', {
+  updateChapter: async (courseId, chapterId, updates) => {
+    await fetch('/api/course/chapters', {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ courseId, chapterId, ...updates }),
+    });
+    await get().fetchCourse(courseId);
+  },
+
+  removeChapter: async (courseId, chapterId) => {
+    await fetch('/api/course/chapters', {
       method: 'DELETE',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ courseId, classroomId }),
+      body: JSON.stringify({ courseId, chapterId }),
     });
     await get().fetchCourse(courseId);
   },
 
-  reorderClassrooms: async (courseId, newOrder) => {
-    await fetch('/api/course/classrooms', {
+  reorderChapters: async (courseId, chapterIds) => {
+    await fetch('/api/course/chapters', {
       method: 'PUT',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ courseId, newOrder }),
+      body: JSON.stringify({ courseId, chapterIds }),
     });
     await get().fetchCourse(courseId);
   },
diff --git a/lib/types/course.ts b/lib/types/course.ts
index 2e95b6e89..f88958dfa 100644
--- a/lib/types/course.ts
+++ b/lib/types/course.ts
@@ -1,3 +1,33 @@
+export const COURSE_CHAPTER_CONTEXT_KEY = 'courseChapterContext';
+
+export interface CourseChapterContext {
+  courseId: string;
+  chapterId: string;
+  stageId: string | null;
+}
+
+export interface ClassroomMeta {
+  name: string;
+  sceneCount: number;
+  published: boolean;
+}
+
+export interface CourseChapter {
+  id: string;
+  title: string;
+  description?: string;
+  order: number;
+  classroomId?: string; // only published classrooms (server-persisted)
+}
+
+export interface CourseFormData {
+  name: string;
+  college: string;
+  major: string;
+  description: string;
+  teacherName: string;
+}
+
 export interface Course {
   id: string;
   name: string;
@@ -5,11 +35,11 @@ export interface Course {
   major: string;
   description: string;
   teacherName: string;
-  classroomIds: string[];
+  chapters: CourseChapter[];
   createdAt: string;
   updatedAt: string;
 }
 
-export type CourseListItem = Omit<Course, 'classroomIds' | 'updatedAt'> & {
-  classroomCount: number;
+export type CourseListItem = Omit<Course, 'chapters' | 'updatedAt'> & {
+  chapterCount: number;
 };
diff --git a/scripts/start-8002.sh b/scripts/start-8002.sh
index 764077fea..da165ed54 100755
--- a/scripts/start-8002.sh
+++ b/scripts/start-8002.sh
@@ -15,4 +15,8 @@ if [[ ! -f .next/standalone/server.js ]]; then
   exit 1
 fi
 
+# Copy static assets (required for standalone mode)
+cp -r .next/static .next/standalone/.next/static 2>/dev/null || true
+cp -r public .next/standalone/public 2>/dev/null || true
+
 exec node .next/standalone/server.js

From a6d31fc2c420682b819ece73a4d3bafb723ace0c Mon Sep 17 00:00:00 2001
From: zhenzhu143321 <hxcisunli@126.com>
Date: Fri, 27 Mar 2026 22:30:26 +0800
Subject: [PATCH 10/30] fix: resolve 4 runtime bugs in course chapter system
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Bug 1: ClassroomPickerDialog crash — destructure {classrooms} from apiSuccess
  response instead of treating it as raw array; read sceneCount not scenes.length

Bug 2: courseChapterContext leak — add createdAt timestamp to CourseChapterContext;
  handleGenerate clears context if stageId already set OR older than 5 minutes,
  preventing stale context from binding a new classroom to a forgotten chapter

Bug 3: unbind/clear-description silently failed — JSON.stringify drops undefined keys;
  introduce ChapterUpdates type (classroomId/description allow null); updateChapter
  storage fn now deletes the field when null is received; API route uses 'in body'
  check to detect explicit null vs absent field; handleUnbind passes null not undefined

Bug 4: scene count always 0 — ClassroomListItem has sceneCount:number not scenes[];
  fix both loadClassroomMeta in course detail page and ClassroomPickerDialog

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 app/api/course/chapters/route.ts              | 10 ++++++----
 app/course/[id]/page.tsx                      |  8 ++++----
 app/page.tsx                                  |  9 ++++-----
 components/course/classroom-picker-dialog.tsx |  6 +++---
 lib/server/course-storage.ts                  | 20 ++++++++++++++++---
 lib/store/course.ts                           |  4 ++--
 lib/types/course.ts                           |  8 ++++++++
 7 files changed, 44 insertions(+), 21 deletions(-)

diff --git a/app/api/course/chapters/route.ts b/app/api/course/chapters/route.ts
index 0b64cc104..7bb44d6ae 100644
--- a/app/api/course/chapters/route.ts
+++ b/app/api/course/chapters/route.ts
@@ -1,5 +1,6 @@
 import { type NextRequest, NextResponse } from 'next/server';
 import { addChapter, updateChapter, removeChapter, reorderChapters } from '@/lib/server/course-storage';
+import type { ChapterUpdates } from '@/lib/types/course';
 
 export async function POST(req: NextRequest) {
   try {
@@ -31,10 +32,11 @@ export async function PUT(req: NextRequest) {
     if (!chapterId) {
       return NextResponse.json({ error: 'Missing chapterId' }, { status: 400 });
     }
-    const updates: Parameters<typeof updateChapter>[2] = {};
-    if (title !== undefined) updates.title = title;
-    if (description !== undefined) updates.description = description;
-    if (classroomId !== undefined) updates.classroomId = classroomId;
+    // Build updates; include a key whenever it is explicitly present in body (even if null)
+    const updates: ChapterUpdates = {};
+    if ('title' in body && title !== undefined) updates.title = title;
+    if ('description' in body) updates.description = description ?? null;
+    if ('classroomId' in body) updates.classroomId = classroomId ?? null;
     await updateChapter(courseId, chapterId, updates);
     return NextResponse.json({ success: true });
   } catch (error) {
diff --git a/app/course/[id]/page.tsx b/app/course/[id]/page.tsx
index 7c729a464..cb700ec39 100644
--- a/app/course/[id]/page.tsx
+++ b/app/course/[id]/page.tsx
@@ -39,7 +39,7 @@ export default function CourseDetailPage({ params }: { params: Promise<{ id: str
       // Single batch fetch instead of N per-classroom requests
       const res = await fetch('/api/classroom');
       if (!res.ok) return;
-      const { classrooms } = await res.json() as { classrooms: Array<{ id: string; name?: string; scenes?: unknown[] }> };
+      const { classrooms } = await res.json() as { classrooms: Array<{ id: string; name?: string; sceneCount: number }> };
       const idSet = new Set(classroomIds);
       setClassroomMeta(
         Object.fromEntries(
@@ -47,7 +47,7 @@ export default function CourseDetailPage({ params }: { params: Promise<{ id: str
             .filter((c) => idSet.has(c.id))
             .map((c): [string, ClassroomMeta] => [
               c.id,
-              { name: c.name || c.id, sceneCount: (c.scenes?.length ?? 0), published: true },
+              { name: c.name || c.id, sceneCount: c.sceneCount ?? 0, published: true },
             ]),
         ),
       );
@@ -88,7 +88,7 @@ export default function CourseDetailPage({ params }: { params: Promise<{ id: str
   };
 
   const handleUnbind = async (chapterId: string) => {
-    await updateChapter(courseId, chapterId, { classroomId: undefined });
+    await updateChapter(courseId, chapterId, { classroomId: null });
   };
 
   const handleBind = (chapterId: string) => {
@@ -104,7 +104,7 @@ export default function CourseDetailPage({ params }: { params: Promise<{ id: str
   const handleCreateAndBind = (chapterId: string) => {
     sessionStorage.setItem(
       COURSE_CHAPTER_CONTEXT_KEY,
-      JSON.stringify({ courseId, chapterId, stageId: null } satisfies CourseChapterContext),
+      JSON.stringify({ courseId, chapterId, stageId: null, createdAt: Date.now() } satisfies CourseChapterContext),
     );
     router.push('/');
   };
diff --git a/app/page.tsx b/app/page.tsx
index b4dd15a95..6d1167740 100644
--- a/app/page.tsx
+++ b/app/page.tsx
@@ -331,15 +331,14 @@ function HomePage() {
         currentStep: 'generating' as const,
       };
       sessionStorage.setItem('generationSession', JSON.stringify(sessionState));
-      // If there is a stale context (stageId already set from a prior generation),
-      // remove it so this new generation starts fresh without an accidental chapter binding.
+      // Clear stale chapter binding context: if stageId is set (prior generation ran) OR
+      // if it's older than 5 minutes (user abandoned the "create & bind" flow without generating).
       try {
         const ctxStr = sessionStorage.getItem(COURSE_CHAPTER_CONTEXT_KEY);
         if (ctxStr) {
           const ctx = JSON.parse(ctxStr) as CourseChapterContext;
-          if (ctx.stageId !== null) {
-            sessionStorage.removeItem(COURSE_CHAPTER_CONTEXT_KEY);
-          }
+          const stale = ctx.stageId !== null || Date.now() - (ctx.createdAt ?? 0) > 5 * 60 * 1000;
+          if (stale) sessionStorage.removeItem(COURSE_CHAPTER_CONTEXT_KEY);
         }
       } catch {
         sessionStorage.removeItem(COURSE_CHAPTER_CONTEXT_KEY);
diff --git a/components/course/classroom-picker-dialog.tsx b/components/course/classroom-picker-dialog.tsx
index be14f03b0..613ba2e3f 100644
--- a/components/course/classroom-picker-dialog.tsx
+++ b/components/course/classroom-picker-dialog.tsx
@@ -23,13 +23,13 @@ export function ClassroomPickerDialog({ usedClassroomIds, onSelect, onClose }: C
   useEffect(() => {
     fetch('/api/classroom')
       .then((r) => r.json())
-      .then((list: Array<{ id: string; name?: string; scenes?: unknown[] }>) => {
-        const items: PublishedClassroom[] = list
+      .then(({ classrooms }: { classrooms: Array<{ id: string; name?: string; sceneCount: number }> }) => {
+        const items: PublishedClassroom[] = classrooms
           .filter((c) => !usedClassroomIds.has(c.id))
           .map((c) => ({
             id: c.id,
             name: c.name || c.id,
-            sceneCount: c.scenes?.length ?? 0,
+            sceneCount: c.sceneCount ?? 0,
           }));
         setClassrooms(items);
       })
diff --git a/lib/server/course-storage.ts b/lib/server/course-storage.ts
index fb82fb5c5..f8271eac9 100644
--- a/lib/server/course-storage.ts
+++ b/lib/server/course-storage.ts
@@ -1,7 +1,7 @@
 import { promises as fs } from 'fs';
 import path from 'path';
 import { nanoid } from 'nanoid';
-import type { Course, CourseChapter, CourseListItem } from '@/lib/types/course';
+import type { Course, CourseChapter, ChapterUpdates, CourseListItem } from '@/lib/types/course';
 import { PROJECT_ROOT, writeJsonFileAtomic } from './classroom-storage';
 import { withCourseLock } from './course-lock';
 
@@ -113,14 +113,28 @@ export async function addChapter(
 export async function updateChapter(
   courseId: string,
   chapterId: string,
-  updates: Partial<Pick<CourseChapter, 'title' | 'description' | 'classroomId'>>,
+  updates: ChapterUpdates,
 ): Promise<void> {
   await withCourseLock(courseId, async () => {
     const course = await readCourse(courseId);
     if (!course) throw new Error('Course not found');
     const chapter = course.chapters.find((c) => c.id === chapterId);
     if (!chapter) throw new Error('Chapter not found');
-    Object.assign(chapter, updates);
+    if (updates.title !== undefined) chapter.title = updates.title;
+    if ('description' in updates) {
+      if (updates.description === null || updates.description === undefined) {
+        delete chapter.description;
+      } else {
+        chapter.description = updates.description;
+      }
+    }
+    if ('classroomId' in updates) {
+      if (updates.classroomId === null || updates.classroomId === undefined) {
+        delete chapter.classroomId;
+      } else {
+        chapter.classroomId = updates.classroomId;
+      }
+    }
     course.updatedAt = new Date().toISOString();
     await persistCourse(course);
   });
diff --git a/lib/store/course.ts b/lib/store/course.ts
index e0eaf86de..b310f79e7 100644
--- a/lib/store/course.ts
+++ b/lib/store/course.ts
@@ -1,5 +1,5 @@
 import { create } from 'zustand';
-import type { Course, CourseChapter, CourseFormData, CourseListItem } from '@/lib/types/course';
+import type { Course, CourseChapter, ChapterUpdates, CourseFormData, CourseListItem } from '@/lib/types/course';
 import { nanoid } from 'nanoid';
 
 interface CourseState {
@@ -12,7 +12,7 @@ interface CourseState {
   updateCourse: (id: string, data: Partial<CourseFormData>) => Promise<void>;
   deleteCourse: (id: string) => Promise<void>;
   addChapter: (courseId: string, title: string, description?: string) => Promise<void>;
-  updateChapter: (courseId: string, chapterId: string, updates: Partial<CourseChapter>) => Promise<void>;
+  updateChapter: (courseId: string, chapterId: string, updates: ChapterUpdates) => Promise<void>;
   removeChapter: (courseId: string, chapterId: string) => Promise<void>;
   reorderChapters: (courseId: string, chapterIds: string[]) => Promise<void>;
 }
diff --git a/lib/types/course.ts b/lib/types/course.ts
index f88958dfa..4c80f207b 100644
--- a/lib/types/course.ts
+++ b/lib/types/course.ts
@@ -4,6 +4,7 @@ export interface CourseChapterContext {
   courseId: string;
   chapterId: string;
   stageId: string | null;
+  createdAt: number;
 }
 
 export interface ClassroomMeta {
@@ -12,6 +13,13 @@ export interface ClassroomMeta {
   published: boolean;
 }
 
+/** Updates accepted by the updateChapter API. null means "clear the field". */
+export interface ChapterUpdates {
+  title?: string;
+  description?: string | null;
+  classroomId?: string | null;
+}
+
 export interface CourseChapter {
   id: string;
   title: string;

From 284b5fd65ffd72d5c875c2902050fe7539de9b5b Mon Sep 17 00:00:00 2001
From: zhenzhu143321 <hxcisunli@126.com>
Date: Sat, 28 Mar 2026 06:28:40 +0800
Subject: [PATCH 11/30] fix: prevent chapter data loss on reorder; fix
 description clear via UI
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Bug 1: reorderChapters now validates that incoming chapterIds exactly matches
  the current chapter set — partial list previously silently deleted unlisted chapters

Bug 2: ChapterForm passes null (not undefined) for empty description so
  JSON.stringify preserves the field; updateChapter already handles null as an
  explicit clear; addChapter normalises null description to omit on creation

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 components/course/chapter-form.tsx |  4 ++--
 components/course/chapter-list.tsx |  8 ++++----
 lib/server/course-storage.ts       | 16 +++++++++++-----
 lib/store/course.ts                |  2 +-
 4 files changed, 18 insertions(+), 12 deletions(-)

diff --git a/components/course/chapter-form.tsx b/components/course/chapter-form.tsx
index b2f23edf4..046b2d657 100644
--- a/components/course/chapter-form.tsx
+++ b/components/course/chapter-form.tsx
@@ -6,7 +6,7 @@ import { useI18n } from '@/lib/hooks/use-i18n';
 interface ChapterFormProps {
   initialTitle?: string;
   initialDescription?: string;
-  onSubmit: (title: string, description?: string) => void;
+  onSubmit: (title: string, description: string | null) => void;
   onCancel: () => void;
 }
 
@@ -18,7 +18,7 @@ export function ChapterForm({ initialTitle = '', initialDescription = '', onSubm
   const handleSubmit = (e: React.FormEvent) => {
     e.preventDefault();
     if (!title.trim()) return;
-    onSubmit(title.trim(), description.trim() || undefined);
+    onSubmit(title.trim(), description.trim() || null);
   };
 
   return (
diff --git a/components/course/chapter-list.tsx b/components/course/chapter-list.tsx
index c686719ae..cd7c1227b 100644
--- a/components/course/chapter-list.tsx
+++ b/components/course/chapter-list.tsx
@@ -9,8 +9,8 @@ interface ChapterListProps {
   courseId: string;
   chapters: CourseChapter[];
   classroomMeta: Record<string, ClassroomMeta>;
-  onAdd: (title: string, description?: string) => Promise<void>;
-  onEdit: (chapterId: string, title: string, description?: string) => Promise<void>;
+  onAdd: (title: string, description: string | null) => Promise<void>;
+  onEdit: (chapterId: string, title: string, description: string | null) => Promise<void>;
   onRemove: (chapterId: string) => Promise<void>;
   onMove: (chapterId: string, direction: 'up' | 'down') => Promise<void>;
   onBind: (chapterId: string) => void;
@@ -36,12 +36,12 @@ export function ChapterList({
   const [showAddForm, setShowAddForm] = useState(false);
   const [editingId, setEditingId] = useState<string | null>(null);
 
-  const handleAdd = async (title: string, description?: string) => {
+  const handleAdd = async (title: string, description: string | null) => {
     await onAdd(title, description);
     setShowAddForm(false);
   };
 
-  const handleEdit = async (chapterId: string, title: string, description?: string) => {
+  const handleEdit = async (chapterId: string, title: string, description: string | null) => {
     await onEdit(chapterId, title, description);
     setEditingId(null);
   };
diff --git a/lib/server/course-storage.ts b/lib/server/course-storage.ts
index f8271eac9..82d0d39da 100644
--- a/lib/server/course-storage.ts
+++ b/lib/server/course-storage.ts
@@ -92,7 +92,7 @@ export async function deleteCourse(id: string): Promise<void> {
 
 export async function addChapter(
   courseId: string,
-  data: { title: string; description?: string },
+  data: { title: string; description?: string | null },
 ): Promise<CourseChapter> {
   return withCourseLock(courseId, async () => {
     const course = await readCourse(courseId);
@@ -100,7 +100,7 @@ export async function addChapter(
     const chapter: CourseChapter = {
       id: nanoid(10),
       title: data.title,
-      description: data.description,
+      ...(data.description ? { description: data.description } : {}),
       order: course.chapters.length,
     };
     course.chapters.push(chapter);
@@ -157,9 +157,15 @@ export async function reorderChapters(courseId: string, chapterIds: string[]): P
     const course = await readCourse(courseId);
     if (!course) throw new Error('Course not found');
     const chapterMap = new Map(course.chapters.map((c) => [c.id, c]));
-    course.chapters = chapterIds
-      .filter((id) => chapterMap.has(id))
-      .map((id, i) => ({ ...chapterMap.get(id)!, order: i }));
+    // Reject if the incoming set doesn't match the current chapter set exactly —
+    // a partial list would silently delete missing chapters.
+    if (
+      chapterIds.length !== chapterMap.size ||
+      chapterIds.some((id) => !chapterMap.has(id))
+    ) {
+      throw new Error('chapterIds must contain exactly the current chapter set');
+    }
+    course.chapters = chapterIds.map((id, i) => ({ ...chapterMap.get(id)!, order: i }));
     course.updatedAt = new Date().toISOString();
     await persistCourse(course);
   });
diff --git a/lib/store/course.ts b/lib/store/course.ts
index b310f79e7..6b94a56e2 100644
--- a/lib/store/course.ts
+++ b/lib/store/course.ts
@@ -11,7 +11,7 @@ interface CourseState {
   createCourse: (data: CourseFormData) => Promise<string>;
   updateCourse: (id: string, data: Partial<CourseFormData>) => Promise<void>;
   deleteCourse: (id: string) => Promise<void>;
-  addChapter: (courseId: string, title: string, description?: string) => Promise<void>;
+  addChapter: (courseId: string, title: string, description: string | null) => Promise<void>;
   updateChapter: (courseId: string, chapterId: string, updates: ChapterUpdates) => Promise<void>;
   removeChapter: (courseId: string, chapterId: string) => Promise<void>;
   reorderChapters: (courseId: string, chapterIds: string[]) => Promise<void>;

From df1dcaad61dd1d7acf6321f6bf9709e12a693837 Mon Sep 17 00:00:00 2001
From: zhenzhu143321 <hxcisunli@126.com>
Date: Sat, 28 Mar 2026 08:50:58 +0800
Subject: [PATCH 12/30] fix: improve course accessibility interactions

---
 app/course/page.tsx                |  9 +++++--
 components/course/chapter-form.tsx | 18 ++++++++++---
 components/course/course-form.tsx  | 42 +++++++++++++++++++++++++-----
 3 files changed, 58 insertions(+), 11 deletions(-)

diff --git a/app/course/page.tsx b/app/course/page.tsx
index 6c2267e6f..aaa4be66e 100644
--- a/app/course/page.tsx
+++ b/app/course/page.tsx
@@ -50,13 +50,18 @@ export default function CoursePage() {
         <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
           {courses.map((course) => (
             <div key={course.id} className="border rounded p-4 hover:shadow-lg transition-shadow cursor-pointer">
-              <div onClick={() => router.push(`/course/${course.id}`)}>
+              <button
+                type="button"
+                onClick={() => router.push(`/course/${course.id}`)}
+                className="w-full text-left rounded focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-blue-500"
+                aria-label={`${t('course.myCourses')}: ${course.name}`}
+              >
                 <h2 className="text-xl mb-2">{course.name}</h2>
                 <p className="text-sm text-gray-600">{course.college} - {course.major}</p>
                 <p className="text-sm text-gray-500 mt-2">{course.description}</p>
                 <p className="text-sm mt-2">{t('course.teacherName')}: {course.teacherName}</p>
                 <p className="text-sm text-gray-500">{t('course.chapterCount')}: {course.chapterCount}</p>
-              </div>
+              </button>
               <button onClick={() => handleDelete(course.id)} className="mt-2 text-red-500 text-sm">
                 {t('course.delete')}
               </button>
diff --git a/components/course/chapter-form.tsx b/components/course/chapter-form.tsx
index 046b2d657..bc9b1e6c3 100644
--- a/components/course/chapter-form.tsx
+++ b/components/course/chapter-form.tsx
@@ -1,6 +1,6 @@
 'use client';
 
-import { useState } from 'react';
+import { useId, useState } from 'react';
 import { useI18n } from '@/lib/hooks/use-i18n';
 
 interface ChapterFormProps {
@@ -12,6 +12,8 @@ interface ChapterFormProps {
 
 export function ChapterForm({ initialTitle = '', initialDescription = '', onSubmit, onCancel }: ChapterFormProps) {
   const { t } = useI18n();
+  const titleId = useId();
+  const descriptionId = useId();
   const [title, setTitle] = useState(initialTitle);
   const [description, setDescription] = useState(initialDescription);
 
@@ -24,9 +26,14 @@ export function ChapterForm({ initialTitle = '', initialDescription = '', onSubm
   return (
     <form onSubmit={handleSubmit} className="space-y-3">
       <div>
-        <label className="block text-sm font-medium mb-1">{t('course.chapterTitle')}</label>
+        <label htmlFor={titleId} className="block text-sm font-medium mb-1">
+          {t('course.chapterTitle')}
+        </label>
         <input
+          id={titleId}
+          name="title"
           type="text"
+          autoComplete="off"
           value={title}
           onChange={(e) => setTitle(e.target.value)}
           className="w-full px-3 py-2 border rounded text-sm"
@@ -35,9 +42,14 @@ export function ChapterForm({ initialTitle = '', initialDescription = '', onSubm
         />
       </div>
       <div>
-        <label className="block text-sm font-medium mb-1">{t('course.chapterDescription')}</label>
+        <label htmlFor={descriptionId} className="block text-sm font-medium mb-1">
+          {t('course.chapterDescription')}
+        </label>
         <input
+          id={descriptionId}
+          name="description"
           type="text"
+          autoComplete="off"
           value={description}
           onChange={(e) => setDescription(e.target.value)}
           className="w-full px-3 py-2 border rounded text-sm"
diff --git a/components/course/course-form.tsx b/components/course/course-form.tsx
index 19db330d6..8ec2fb023 100644
--- a/components/course/course-form.tsx
+++ b/components/course/course-form.tsx
@@ -1,6 +1,6 @@
 'use client';
 
-import { useState } from 'react';
+import { useId, useState } from 'react';
 import { useI18n } from '@/lib/hooks/use-i18n';
 import type { CourseFormData } from '@/lib/types/course';
 
@@ -12,6 +12,11 @@ interface CourseFormProps {
 
 export function CourseForm({ initialData, onSubmit, onCancel }: CourseFormProps) {
   const { t } = useI18n();
+  const nameId = useId();
+  const collegeId = useId();
+  const majorId = useId();
+  const descriptionId = useId();
+  const teacherNameId = useId();
   const [formData, setFormData] = useState({
     name: initialData?.name || '',
     college: initialData?.college || '',
@@ -28,9 +33,14 @@ export function CourseForm({ initialData, onSubmit, onCancel }: CourseFormProps)
   return (
     <form onSubmit={handleSubmit} className="space-y-4">
       <div>
-        <label className="block text-sm mb-1">{t('course.name')}</label>
+        <label htmlFor={nameId} className="block text-sm mb-1">
+          {t('course.name')}
+        </label>
         <input
+          id={nameId}
+          name="name"
           type="text"
+          autoComplete="off"
           value={formData.name}
           onChange={(e) => setFormData({ ...formData, name: e.target.value })}
           className="w-full px-3 py-2 border rounded"
@@ -38,9 +48,14 @@ export function CourseForm({ initialData, onSubmit, onCancel }: CourseFormProps)
         />
       </div>
       <div>
-        <label className="block text-sm mb-1">{t('course.college')}</label>
+        <label htmlFor={collegeId} className="block text-sm mb-1">
+          {t('course.college')}
+        </label>
         <input
+          id={collegeId}
+          name="college"
           type="text"
+          autoComplete="organization"
           value={formData.college}
           onChange={(e) => setFormData({ ...formData, college: e.target.value })}
           className="w-full px-3 py-2 border rounded"
@@ -48,9 +63,14 @@ export function CourseForm({ initialData, onSubmit, onCancel }: CourseFormProps)
         />
       </div>
       <div>
-        <label className="block text-sm mb-1">{t('course.major')}</label>
+        <label htmlFor={majorId} className="block text-sm mb-1">
+          {t('course.major')}
+        </label>
         <input
+          id={majorId}
+          name="major"
           type="text"
+          autoComplete="off"
           value={formData.major}
           onChange={(e) => setFormData({ ...formData, major: e.target.value })}
           className="w-full px-3 py-2 border rounded"
@@ -58,8 +78,13 @@ export function CourseForm({ initialData, onSubmit, onCancel }: CourseFormProps)
         />
       </div>
       <div>
-        <label className="block text-sm mb-1">{t('course.description')}</label>
+        <label htmlFor={descriptionId} className="block text-sm mb-1">
+          {t('course.description')}
+        </label>
         <textarea
+          id={descriptionId}
+          name="description"
+          autoComplete="off"
           value={formData.description}
           onChange={(e) => setFormData({ ...formData, description: e.target.value })}
           className="w-full px-3 py-2 border rounded"
@@ -68,9 +93,14 @@ export function CourseForm({ initialData, onSubmit, onCancel }: CourseFormProps)
         />
       </div>
       <div>
-        <label className="block text-sm mb-1">{t('course.teacherName')}</label>
+        <label htmlFor={teacherNameId} className="block text-sm mb-1">
+          {t('course.teacherName')}
+        </label>
         <input
+          id={teacherNameId}
+          name="teacherName"
           type="text"
+          autoComplete="name"
           value={formData.teacherName}
           onChange={(e) => setFormData({ ...formData, teacherName: e.target.value })}
           className="w-full px-3 py-2 border rounded"

From 9542143047c5e209487cdabebbb7cf533cfda99d Mon Sep 17 00:00:00 2001
From: zhenzhu143321 <hxcisunli@126.com>
Date: Sun, 29 Mar 2026 10:00:18 +0800
Subject: [PATCH 13/30] feat: async classroom generation API +
 classroom-storage/provider improvements

- Add async job-based classroom generation endpoint (POST /api/generate-classroom,
  GET /api/generate-classroom/[jobId]) backed by in-memory job queue
- Expand classroom-generation.ts with scene outline and content generation helpers
- classroom-storage: support new directory layout {id}/classroom.json alongside
  legacy flat {id}.json; add listClassrooms with sceneCount
- provider-config: cache server providers in module scope; fix runtime-env import
- resolve-model: surface clearer error when provider is not configured

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 app/api/generate-classroom/route.ts |  90 ++++++++
 lib/server/classroom-generation.ts  | 339 +++++++++++++++++++++++++++-
 lib/server/classroom-storage.ts     |  21 +-
 lib/server/provider-config.ts       |   4 +-
 lib/server/resolve-model.ts         |   2 +
 5 files changed, 446 insertions(+), 10 deletions(-)

diff --git a/app/api/generate-classroom/route.ts b/app/api/generate-classroom/route.ts
index b35448e7b..9a46288da 100644
--- a/app/api/generate-classroom/route.ts
+++ b/app/api/generate-classroom/route.ts
@@ -8,6 +8,12 @@ import { buildRequestOrigin } from '@/lib/server/classroom-storage';
 
 export const maxDuration = 30;
 
+function parseOptionalNumber(value: string | null): number | undefined {
+  if (value === null || value.trim() === '') return undefined;
+  const parsed = Number.parseFloat(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
 export async function POST(req: NextRequest) {
   try {
     const rawBody = (await req.json()) as Partial<GenerateClassroomInput>;
@@ -15,6 +21,90 @@ export async function POST(req: NextRequest) {
       requirement: rawBody.requirement || '',
       ...(rawBody.pdfContent ? { pdfContent: rawBody.pdfContent } : {}),
       ...(rawBody.language ? { language: rawBody.language } : {}),
+      ...(rawBody.stageName || req.headers.get('x-stage-name')
+        ? { stageName: rawBody.stageName || req.headers.get('x-stage-name') || undefined }
+        : {}),
+      ...(rawBody.modelString || req.headers.get('x-model')
+        ? { modelString: rawBody.modelString || req.headers.get('x-model') || undefined }
+        : {}),
+      ...(rawBody.apiKey || req.headers.get('x-api-key')
+        ? { apiKey: rawBody.apiKey || req.headers.get('x-api-key') || undefined }
+        : {}),
+      ...(rawBody.baseUrl || req.headers.get('x-base-url')
+        ? { baseUrl: rawBody.baseUrl || req.headers.get('x-base-url') || undefined }
+        : {}),
+      ...(rawBody.providerType || req.headers.get('x-provider-type')
+        ? { providerType: rawBody.providerType || req.headers.get('x-provider-type') || undefined }
+        : {}),
+      ...(rawBody.requiresApiKey !== undefined ||
+      req.headers.get('x-requires-api-key') !== null
+        ? {
+            requiresApiKey:
+              rawBody.requiresApiKey ??
+              (req.headers.get('x-requires-api-key') === 'true' ? true : false),
+          }
+        : {}),
+      ...(rawBody.imageGenerationEnabled !== undefined ||
+      req.headers.get('x-image-generation-enabled') !== null
+        ? {
+            imageGenerationEnabled:
+              rawBody.imageGenerationEnabled ??
+              (req.headers.get('x-image-generation-enabled') === 'true' ? true : false),
+          }
+        : {}),
+      ...(rawBody.imageProviderId || req.headers.get('x-image-provider')
+        ? {
+            imageProviderId:
+              (rawBody.imageProviderId ||
+                req.headers.get('x-image-provider') ||
+                undefined) as GenerateClassroomInput['imageProviderId'],
+          }
+        : {}),
+      ...(rawBody.imageModel || req.headers.get('x-image-model')
+        ? { imageModel: rawBody.imageModel || req.headers.get('x-image-model') || undefined }
+        : {}),
+      ...(rawBody.imageApiKey || req.headers.get('x-image-api-key')
+        ? {
+            imageApiKey:
+              rawBody.imageApiKey || req.headers.get('x-image-api-key') || undefined,
+          }
+        : {}),
+      ...(rawBody.imageBaseUrl || req.headers.get('x-image-base-url')
+        ? {
+            imageBaseUrl:
+              rawBody.imageBaseUrl || req.headers.get('x-image-base-url') || undefined,
+          }
+        : {}),
+      ...(rawBody.ttsEnabled !== undefined || req.headers.get('x-tts-enabled') !== null
+        ? {
+            ttsEnabled:
+              rawBody.ttsEnabled ??
+              (req.headers.get('x-tts-enabled') === 'true' ? true : false),
+          }
+        : {}),
+      ...(rawBody.ttsProviderId || req.headers.get('x-tts-provider')
+        ? {
+            ttsProviderId: (rawBody.ttsProviderId ||
+              req.headers.get('x-tts-provider') ||
+              undefined) as GenerateClassroomInput['ttsProviderId'],
+          }
+        : {}),
+      ...(rawBody.ttsVoice || req.headers.get('x-tts-voice')
+        ? { ttsVoice: rawBody.ttsVoice || req.headers.get('x-tts-voice') || undefined }
+        : {}),
+      ...(rawBody.ttsSpeed !== undefined || req.headers.get('x-tts-speed') !== null
+        ? {
+            ttsSpeed: rawBody.ttsSpeed ?? parseOptionalNumber(req.headers.get('x-tts-speed')),
+          }
+        : {}),
+      ...(rawBody.ttsApiKey || req.headers.get('x-tts-api-key')
+        ? { ttsApiKey: rawBody.ttsApiKey || req.headers.get('x-tts-api-key') || undefined }
+        : {}),
+      ...(rawBody.ttsBaseUrl || req.headers.get('x-tts-base-url')
+        ? {
+            ttsBaseUrl: rawBody.ttsBaseUrl || req.headers.get('x-tts-base-url') || undefined,
+          }
+        : {}),
     };
     const { requirement } = body;
 
diff --git a/lib/server/classroom-generation.ts b/lib/server/classroom-generation.ts
index 1dea58fdb..da549793e 100644
--- a/lib/server/classroom-generation.ts
+++ b/lib/server/classroom-generation.ts
@@ -1,5 +1,8 @@
 import { nanoid } from 'nanoid';
 import { callLLM } from '@/lib/ai/llm';
+import { DEFAULT_TTS_VOICES } from '@/lib/audio/constants';
+import { generateTTS } from '@/lib/audio/tts-providers';
+import type { TTSProviderId } from '@/lib/audio/types';
 import { createStageAPI } from '@/lib/api/stage-api';
 import type { StageStore } from '@/lib/api/stage-api-types';
 import {
@@ -13,11 +16,22 @@ import {
 } from '@/lib/generation/scene-generator';
 import type { AICallFn } from '@/lib/generation/pipeline-types';
 import { createLogger } from '@/lib/logger';
+import { generateImage } from '@/lib/media/image-providers';
+import type { ImageProviderId, MediaGenerationRequest } from '@/lib/media/types';
 import { parseModelString } from '@/lib/ai/providers';
-import { resolveApiKey } from '@/lib/server/provider-config';
+import {
+  resolveApiKey,
+  resolveImageApiKey,
+  resolveImageBaseUrl,
+  resolveTTSApiKey,
+  resolveTTSBaseUrl,
+} from '@/lib/server/provider-config';
 import { resolveModel } from '@/lib/server/resolve-model';
 import { persistClassroom } from '@/lib/server/classroom-storage';
-import type { UserRequirements } from '@/lib/types/generation';
+import { saveMedia, mediaExists } from '@/lib/server/media-storage';
+import { validateUrlForSSRF } from '@/lib/server/ssrf-guard';
+import type { SpeechAction } from '@/lib/types/action';
+import type { SceneOutline, UserRequirements } from '@/lib/types/generation';
 import type { Scene, Stage } from '@/lib/types/stage';
 
 const log = createLogger('Classroom');
@@ -26,12 +40,30 @@ export interface GenerateClassroomInput {
   requirement: string;
   pdfContent?: { text: string; images: string[] };
   language?: string;
+  stageName?: string;
+  modelString?: string;
+  apiKey?: string;
+  baseUrl?: string;
+  providerType?: string;
+  requiresApiKey?: boolean;
+  imageGenerationEnabled?: boolean;
+  imageProviderId?: ImageProviderId;
+  imageModel?: string;
+  imageApiKey?: string;
+  imageBaseUrl?: string;
+  ttsEnabled?: boolean;
+  ttsProviderId?: TTSProviderId;
+  ttsVoice?: string;
+  ttsSpeed?: number;
+  ttsApiKey?: string;
+  ttsBaseUrl?: string;
 }
 
 export type ClassroomGenerationStep =
   | 'initializing'
   | 'generating_outlines'
   | 'generating_scenes'
+  | 'generating_media'
   | 'persisting'
   | 'completed';
 
@@ -83,6 +115,284 @@ function normalizeLanguage(language?: string): 'zh-CN' | 'en-US' {
   return language === 'en-US' ? 'en-US' : 'zh-CN';
 }
 
+interface ResolvedImageGenerationConfig {
+  providerId: ImageProviderId;
+  apiKey: string;
+  baseUrl?: string;
+  model?: string;
+}
+
+interface ResolvedTTSGenerationConfig {
+  providerId: Exclude<TTSProviderId, 'browser-native-tts'>;
+  apiKey: string;
+  baseUrl?: string;
+  voice: string;
+  speed: number;
+}
+
+function assertSafeClientBaseUrl(baseUrl?: string): void {
+  if (!baseUrl || process.env.NODE_ENV !== 'production') return;
+  const ssrfError = validateUrlForSSRF(baseUrl);
+  if (ssrfError) {
+    throw new Error(ssrfError);
+  }
+}
+
+function extractStageNameFromRequirement(requirement: string): string | undefined {
+  const patterns = [
+    /【(?:章节|课堂|课程)标题】\s*([^\n]+)/u,
+    /(?:章节|课堂|课程)标题[:：]\s*([^\n]+)/u,
+  ];
+
+  for (const pattern of patterns) {
+    const match = requirement.match(pattern);
+    const value = match?.[1]?.trim();
+    if (value) return value;
+  }
+  return undefined;
+}
+
+function resolveStageName(
+  input: GenerateClassroomInput,
+  requirement: string,
+  outlines: SceneOutline[],
+): string {
+  return (
+    input.stageName?.trim() ||
+    extractStageNameFromRequirement(requirement) ||
+    outlines[0]?.title ||
+    requirement.slice(0, 50)
+  );
+}
+
+function resolveImageGenerationConfig(
+  input: GenerateClassroomInput,
+): ResolvedImageGenerationConfig | null {
+  if (input.imageGenerationEnabled === false) return null;
+
+  const providerId = input.imageProviderId || 'seedream';
+  assertSafeClientBaseUrl(input.imageBaseUrl);
+
+  const clientApiKey = input.imageApiKey?.trim() || undefined;
+  const apiKey = input.imageBaseUrl
+    ? clientApiKey || ''
+    : resolveImageApiKey(providerId, clientApiKey);
+
+  if (!apiKey) {
+    const explicitlyConfigured = !!(
+      input.imageProviderId ||
+      input.imageApiKey ||
+      input.imageBaseUrl ||
+      input.imageModel
+    );
+    if (explicitlyConfigured) {
+      throw new Error(`No API key configured for image provider: ${providerId}`);
+    }
+    return null;
+  }
+
+  return {
+    providerId,
+    apiKey,
+    baseUrl: input.imageBaseUrl
+      ? input.imageBaseUrl
+      : resolveImageBaseUrl(providerId, input.imageBaseUrl),
+    model: input.imageModel,
+  };
+}
+
+function resolveTTSGenerationConfig(
+  input: GenerateClassroomInput,
+): ResolvedTTSGenerationConfig | null {
+  if (input.ttsEnabled === false) return null;
+
+  const providerId = (input.ttsProviderId || 'qwen-tts') as TTSProviderId;
+  if (providerId === 'browser-native-tts') return null;
+
+  assertSafeClientBaseUrl(input.ttsBaseUrl);
+
+  const clientApiKey = input.ttsApiKey?.trim() || undefined;
+  const apiKey = input.ttsBaseUrl ? clientApiKey || '' : resolveTTSApiKey(providerId, clientApiKey);
+
+  if (!apiKey) {
+    const explicitlyConfigured = !!(
+      input.ttsProviderId ||
+      input.ttsApiKey ||
+      input.ttsBaseUrl ||
+      input.ttsVoice ||
+      input.ttsSpeed !== undefined
+    );
+    if (explicitlyConfigured) {
+      throw new Error(`No API key configured for TTS provider: ${providerId}`);
+    }
+    return null;
+  }
+
+  return {
+    providerId,
+    apiKey,
+    baseUrl: input.ttsBaseUrl ? input.ttsBaseUrl : resolveTTSBaseUrl(providerId, input.ttsBaseUrl),
+    voice: input.ttsVoice?.trim() || DEFAULT_TTS_VOICES[providerId],
+    speed: input.ttsSpeed ?? 1.0,
+  };
+}
+
+function collectImageRequests(outlines: SceneOutline[]): MediaGenerationRequest[] {
+  const requests: MediaGenerationRequest[] = [];
+  const seen = new Set<string>();
+
+  for (const outline of outlines) {
+    for (const request of outline.mediaGenerations || []) {
+      if (request.type !== 'image' || seen.has(request.elementId)) continue;
+      seen.add(request.elementId);
+      requests.push(request);
+    }
+  }
+
+  return requests;
+}
+
+function isSpeechAction(
+  action: NonNullable<Scene['actions']>[number] | undefined,
+): action is SpeechAction {
+  return !!action && action.type === 'speech' && typeof action.text === 'string' && action.text.trim().length > 0;
+}
+
+function inferImageExtension(contentType?: string | null, url?: string): string {
+  const normalized = (contentType || '').toLowerCase();
+  if (normalized.includes('png')) return 'png';
+  if (normalized.includes('jpeg') || normalized.includes('jpg')) return 'jpg';
+  if (normalized.includes('webp')) return 'webp';
+
+  if (url) {
+    const cleanUrl = url.split('?')[0] || url;
+    const match = cleanUrl.match(/\.([a-zA-Z0-9]+)$/);
+    if (match?.[1]) {
+      const ext = match[1].toLowerCase();
+      if (['png', 'jpg', 'jpeg', 'webp'].includes(ext)) {
+        return ext === 'jpeg' ? 'jpg' : ext;
+      }
+    }
+  }
+
+  return 'png';
+}
+
+async function resolveGeneratedImageBuffer(
+  result: Awaited<ReturnType<typeof generateImage>>,
+): Promise<{ buffer: Buffer; ext: string }> {
+  if (result.base64) {
+    return { buffer: Buffer.from(result.base64, 'base64'), ext: 'png' };
+  }
+
+  if (!result.url) {
+    throw new Error('Image generation returned no image payload');
+  }
+
+  const response = await fetch(result.url);
+  if (!response.ok) {
+    throw new Error(`Failed to download generated image (${response.status})`);
+  }
+
+  const buffer = Buffer.from(await response.arrayBuffer());
+  return {
+    buffer,
+    ext: inferImageExtension(response.headers.get('content-type'), result.url),
+  };
+}
+
+async function generateClassroomMedia(
+  stageId: string,
+  outlines: SceneOutline[],
+  scenes: Scene[],
+  mediaConfig: {
+    image: ResolvedImageGenerationConfig | null;
+    tts: ResolvedTTSGenerationConfig | null;
+  },
+  onProgress?: (progress: ClassroomGenerationProgress) => Promise<void> | void,
+): Promise<void> {
+  const imageConfig = mediaConfig.image;
+  const ttsConfig = mediaConfig.tts;
+
+  const imageRequests = imageConfig ? collectImageRequests(outlines) : [];
+  const speechActions = ttsConfig
+    ? scenes.flatMap((scene) =>
+        (scene.actions || [])
+          .filter(isSpeechAction)
+          .map((action) => ({ sceneTitle: scene.title, action })),
+      )
+    : [];
+
+  const totalItems = imageRequests.length + speechActions.length;
+  if (totalItems === 0) return;
+
+  let completedItems = 0;
+  const reportProgress = async (message: string) => {
+    const progress = totalItems > 0 ? 91 + Math.floor((completedItems / totalItems) * 3) : 94;
+    await onProgress?.({
+      step: 'generating_media',
+      progress: Math.min(progress, 94),
+      message,
+      scenesGenerated: scenes.length,
+      totalScenes: outlines.length,
+    });
+  };
+
+  await reportProgress('Generating classroom media');
+
+  if (imageConfig) {
+    for (const request of imageRequests) {
+      try {
+        const existing = await mediaExists(stageId, request.elementId);
+        if (!existing.exists) {
+          const imageResult = await generateImage(imageConfig, {
+            prompt: request.prompt,
+            aspectRatio: request.aspectRatio,
+            style: request.style,
+          });
+          const { buffer, ext } = await resolveGeneratedImageBuffer(imageResult);
+          await saveMedia(stageId, request.elementId, buffer, ext);
+          log.info(`Generated image media: ${request.elementId}`);
+        }
+      } catch (error) {
+        log.warn(`Failed to generate image media "${request.elementId}":`, error);
+      } finally {
+        completedItems += 1;
+        await reportProgress(`Generated media ${completedItems}/${totalItems}`);
+      }
+    }
+  }
+
+  if (ttsConfig) {
+    for (const { sceneTitle, action } of speechActions) {
+      const audioId = action.audioId || `tts_${action.id}`;
+      try {
+        const existing = await mediaExists(stageId, audioId);
+        if (!existing.exists) {
+          const audioResult = await generateTTS(
+            {
+              providerId: ttsConfig.providerId,
+              apiKey: ttsConfig.apiKey,
+              baseUrl: ttsConfig.baseUrl,
+              voice: ttsConfig.voice,
+              speed: ttsConfig.speed,
+            },
+            action.text,
+          );
+          await saveMedia(stageId, audioId, Buffer.from(audioResult.audio), audioResult.format);
+          log.info(`Generated TTS media: ${audioId} (${sceneTitle})`);
+        }
+        action.audioId = audioId;
+      } catch (error) {
+        log.warn(`Failed to generate TTS media "${audioId}" (${sceneTitle}):`, error);
+      } finally {
+        completedItems += 1;
+        await reportProgress(`Generated media ${completedItems}/${totalItems}`);
+      }
+    }
+  }
+}
+
 export async function generateClassroom(
   input: GenerateClassroomInput,
   options: {
@@ -99,16 +409,25 @@ export async function generateClassroom(
     scenesGenerated: 0,
   });
 
-  const { model: languageModel, modelInfo, modelString } = resolveModel({});
+  const { model: languageModel, modelInfo, modelString } = resolveModel({
+    modelString: input.modelString,
+    apiKey: input.apiKey,
+    baseUrl: input.baseUrl,
+    providerType: input.providerType,
+    requiresApiKey: input.requiresApiKey,
+  });
   log.info(`Using server-configured model: ${modelString}`);
 
   // Fail fast if the resolved provider has no API key configured
   const { providerId } = parseModelString(modelString);
-  const apiKey = resolveApiKey(providerId);
+  const apiKey = input.baseUrl
+    ? input.apiKey?.trim() || ''
+    : resolveApiKey(providerId, input.apiKey?.trim() || '');
   if (!apiKey) {
     throw new Error(
       `No API key configured for provider "${providerId}". ` +
-        `Set the appropriate key in .env.local or server-providers.yml (e.g. ${providerId.toUpperCase()}_API_KEY).`,
+        `Pass it in the request or set the appropriate key in .env.local / server-providers.yml ` +
+        `(e.g. ${providerId.toUpperCase()}_API_KEY).`,
     );
   }
 
@@ -128,6 +447,10 @@ export async function generateClassroom(
   };
 
   const lang = normalizeLanguage(input.language);
+  const mediaConfig = {
+    image: resolveImageGenerationConfig(input),
+    tts: resolveTTSGenerationConfig(input),
+  };
   const requirements: UserRequirements = {
     requirement,
     language: lang,
@@ -148,7 +471,7 @@ export async function generateClassroom(
     aiCall,
     undefined,
     {
-      imageGenerationEnabled: true,
+      imageGenerationEnabled: !!mediaConfig.image,
       videoGenerationEnabled: false,
     },
   );
@@ -172,7 +495,7 @@ export async function generateClassroom(
   const stageId = nanoid(10);
   const stage: Stage = {
     id: stageId,
-    name: outlines[0]?.title || requirement.slice(0, 50),
+    name: resolveStageName(input, requirement, outlines),
     description: undefined,
     language: lang,
     style: 'interactive',
@@ -231,6 +554,8 @@ export async function generateClassroom(
     throw new Error('No scenes were generated');
   }
 
+  await generateClassroomMedia(stageId, outlines, scenes, mediaConfig, options.onProgress);
+
   await options.onProgress?.({
     step: 'persisting',
     progress: 95,
diff --git a/lib/server/classroom-storage.ts b/lib/server/classroom-storage.ts
index f92f1c4a3..385887d53 100644
--- a/lib/server/classroom-storage.ts
+++ b/lib/server/classroom-storage.ts
@@ -94,6 +94,23 @@ export interface ClassroomListItem {
   firstSlide?: Slide | null;
 }
 
+function getDisplayClassroomName(data: PersistedClassroomData): string {
+  const rawName = data.stage?.name?.trim() || '';
+  const fallbackTitle =
+    data.scenes?.find((scene) => scene.title?.trim())?.title?.trim() || data.id || 'Untitled';
+
+  if (!rawName) return fallbackTitle;
+
+  const firstLine = rawName.split(/\r?\n/, 1)[0]?.trim() || '';
+  const looksLikeReferenceBlob =
+    rawName.startsWith('参考资料{') ||
+    /\n#{1,6}\s/.test(rawName) ||
+    /\n[-*]\s/.test(rawName);
+
+  if (looksLikeReferenceBlob) return fallbackTitle;
+  return firstLine || fallbackTitle;
+}
+
 export async function listClassrooms(): Promise<ClassroomListItem[]> {
   await ensureClassroomsDir();
   const entries = await fs.readdir(CLASSROOMS_DIR, { withFileTypes: true });
@@ -109,7 +126,7 @@ export async function listClassrooms(): Promise<ClassroomListItem[]> {
         const firstSlideScene = data.scenes?.find(s => s.content?.type === 'slide');
         items.push({
           id: data.id,
-          name: data.stage?.name || 'Untitled',
+          name: getDisplayClassroomName(data),
           description: data.stage?.description,
           language: data.stage?.language,
           sceneCount: data.scenes?.length || 0,
@@ -133,7 +150,7 @@ export async function listClassrooms(): Promise<ClassroomListItem[]> {
         const firstSlideScene = data.scenes?.find(s => s.content?.type === 'slide');
         items.push({
           id: data.id,
-          name: data.stage?.name || 'Untitled',
+          name: getDisplayClassroomName(data),
           description: data.stage?.description,
           language: data.stage?.language,
           sceneCount: data.scenes?.length || 0,
diff --git a/lib/server/provider-config.ts b/lib/server/provider-config.ts
index 7508ecc8d..16440ef6d 100644
--- a/lib/server/provider-config.ts
+++ b/lib/server/provider-config.ts
@@ -9,6 +9,7 @@ import fs from 'fs';
 import path from 'path';
 import yaml from 'js-yaml';
 import { createLogger } from '@/lib/logger';
+import { ensureRuntimeEnvLoaded, resolveProjectRoot } from '@/lib/server/runtime-env';
 
 const log = createLogger('ServerProviderConfig');
 
@@ -101,7 +102,7 @@ type YamlData = Partial<{
 
 function loadYamlFile(filename: string): YamlData {
   try {
-    const filePath = path.join(process.cwd(), filename);
+    const filePath = path.join(resolveProjectRoot(), filename);
     if (!fs.existsSync(filePath)) return {};
     const raw = fs.readFileSync(filePath, 'utf-8');
     const parsed = yaml.load(raw) as Record<string, unknown> | null;
@@ -210,6 +211,7 @@ function getConfig(): ServerConfig {
   const cached = _configs.get('');
   if (cached) return cached;
 
+  ensureRuntimeEnvLoaded();
   const yamlData = loadYamlFile(DEFAULT_FILENAME);
   const config = buildConfig(yamlData);
   logConfig(config, DEFAULT_FILENAME);
diff --git a/lib/server/resolve-model.ts b/lib/server/resolve-model.ts
index 71b95005d..22e57c6f2 100644
--- a/lib/server/resolve-model.ts
+++ b/lib/server/resolve-model.ts
@@ -8,6 +8,7 @@
 import type { NextRequest } from 'next/server';
 import { getModel, parseModelString, type ModelWithInfo } from '@/lib/ai/providers';
 import { resolveApiKey, resolveBaseUrl, resolveProxy } from '@/lib/server/provider-config';
+import { ensureRuntimeEnvLoaded } from '@/lib/server/runtime-env';
 import { validateUrlForSSRF } from '@/lib/server/ssrf-guard';
 
 export interface ResolvedModel extends ModelWithInfo {
@@ -27,6 +28,7 @@ export function resolveModel(params: {
   providerType?: string;
   requiresApiKey?: boolean;
 }): ResolvedModel {
+  ensureRuntimeEnvLoaded();
   const modelString = params.modelString || process.env.DEFAULT_MODEL || 'gpt-4o-mini';
   const { providerId, modelId } = parseModelString(modelString);
 

From 1cc1eede92765df37f7c1e297ebc39fe215eac1d Mon Sep 17 00:00:00 2001
From: zhenzhu143321 <hxcisunli@126.com>
Date: Sun, 29 Mar 2026 10:00:26 +0800
Subject: [PATCH 14/30] fix: classroom page server-first load; fix text element
 overflow in playback

- classroom/[id]: always fetch latest data from server (cache: no-store) on mount,
  then write-through to IndexedDB; fall back to IndexedDB only if server fetch fails.
  Prevents stale IndexedDB data from shadowing server-side edits to published classrooms.
- BaseTextElement: fix h-full + overflow-hidden so text boxes respect their designed
  height in read-only playback; clear paragraph margins and use --paragraphSpace CSS
  var for consistent line spacing.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 app/classroom/[id]/page.tsx                   | 51 +++++++++++--------
 .../element/TextElement/BaseTextElement.tsx   |  6 +--
 2 files changed, 33 insertions(+), 24 deletions(-)

diff --git a/app/classroom/[id]/page.tsx b/app/classroom/[id]/page.tsx
index 5c7f00f5f..4b120e9d0 100644
--- a/app/classroom/[id]/page.tsx
+++ b/app/classroom/[id]/page.tsx
@@ -231,28 +231,37 @@ export default function ClassroomDetailPage() {
 
   const loadClassroom = useCallback(async () => {
     try {
-      await loadFromStorage(classroomId);
-
-      // If IndexedDB had no data, try server-side storage (API-generated classrooms)
-      if (!useStageStore.getState().stage) {
-        log.info('No IndexedDB data, trying server-side storage for:', classroomId);
-        try {
-          const res = await fetch(`/api/classroom?id=${encodeURIComponent(classroomId)}`);
-          if (res.ok) {
-            const json = await res.json();
-            if (json.success && json.classroom) {
-              const { stage, scenes, outlines } = json.classroom;
-              useStageStore.getState().setStage(stage);
-              useStageStore.setState({
-                scenes,
-                outlines: outlines || [],
-                currentSceneId: scenes[0]?.id ?? null,
-              });
-              log.info('Loaded from server-side storage:', classroomId);
-            }
+      let loadedFromServer = false;
+
+      // Published classrooms should prefer the latest server copy.
+      // IndexedDB stays as an offline/cache fallback instead of being authoritative.
+      try {
+        const res = await fetch(`/api/classroom?id=${encodeURIComponent(classroomId)}`, {
+          cache: 'no-store',
+        });
+        if (res.ok) {
+          const json = await res.json();
+          if (json.success && json.classroom) {
+            const { stage, scenes, outlines } = json.classroom;
+            useStageStore.getState().setStage(stage);
+            useStageStore.setState({
+              scenes,
+              outlines: outlines || [],
+              currentSceneId: scenes[0]?.id ?? null,
+            });
+            await useStageStore.getState().saveToStorage();
+            loadedFromServer = true;
+            log.info('Loaded latest classroom from server-side storage:', classroomId);
           }
-        } catch (fetchErr) {
-          log.warn('Server-side storage fetch failed:', fetchErr);
+        }
+      } catch (fetchErr) {
+        log.warn('Server-side storage fetch failed, falling back to IndexedDB:', fetchErr);
+      }
+
+      if (!loadedFromServer) {
+        await loadFromStorage(classroomId);
+        if (useStageStore.getState().stage) {
+          log.info('Loaded classroom from IndexedDB fallback:', classroomId);
         }
       }
 
diff --git a/components/slide-renderer/components/element/TextElement/BaseTextElement.tsx b/components/slide-renderer/components/element/TextElement/BaseTextElement.tsx
index 84ba299a8..babeb2203 100644
--- a/components/slide-renderer/components/element/TextElement/BaseTextElement.tsx
+++ b/components/slide-renderer/components/element/TextElement/BaseTextElement.tsx
@@ -31,10 +31,10 @@ export function BaseTextElement({ elementInfo, target }: BaseTextElementProps) {
         style={{ transform: `rotate(${elementInfo.rotate}deg)` }}
       >
         <div
-          className="element-content relative p-[10px] leading-[1.5] break-words"
+          className="element-content relative h-full overflow-hidden p-[10px] leading-[1.5] break-words"
           style={{
             width: elementInfo.vertical ? 'auto' : `${elementInfo.width}px`,
-            height: elementInfo.vertical ? `${elementInfo.height}px` : 'auto',
+            height: `${elementInfo.height}px`,
             backgroundColor: elementInfo.fill,
             opacity: elementInfo.opacity,
             textShadow: shadowStyle,
@@ -53,7 +53,7 @@ export function BaseTextElement({ elementInfo, target }: BaseTextElementProps) {
             outline={elementInfo.outline}
           />
           <div
-            className={`text ProseMirror-static relative ${target === 'thumbnail' ? 'pointer-events-none' : ''}`}
+            className={`text ProseMirror-static relative overflow-hidden [&_p]:m-0 [&_p]:mb-[var(--paragraphSpace)] [&_p:last-child]:mb-0 ${target === 'thumbnail' ? 'pointer-events-none' : ''}`}
             dangerouslySetInnerHTML={{ __html: elementInfo.content }}
           />
         </div>

From 770527a038d74ee81ba307ffd99dbfdcc3888a57 Mon Sep 17 00:00:00 2001
From: zhenzhu143321 <hxcisunli@126.com>
Date: Sun, 29 Mar 2026 11:07:13 +0800
Subject: [PATCH 15/30] feat: redesign course management UI with shadcn/ui and
 glassmorphism style
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace ad-hoc HTML+hardcoded-Tailwind course pages with the project's
established design system:

- All 4 course components now use shadcn/ui primitives (Button, Card,
  Input, Textarea, Label, Badge, Dialog, AlertDialog, DropdownMenu,
  ScrollArea) instead of raw HTML elements
- Course list and detail pages adopt the glassmorphism layout (gradient
  bg, backdrop-blur cards, decorative blur blobs) consistent with the
  home page
- window.confirm() replaced by AlertDialog throughout
- Hand-rolled classroom picker modal replaced by shadcn Dialog with
  ScrollArea, skeleton loading states, and motion stagger animations
- Chapter action buttons collapsed into DropdownMenu (3 visible → 1);
  reorder arrows kept visible as high-frequency controls
- AnimatePresence + layout animations for chapter add/remove/reorder
- Empty states with BookOpen icon and clear CTAs
- Create/edit course forms moved into Dialog overlays (no more full-page
  replacement)
- 15 new i18n keys added to lib/i18n/course.ts; hardcoded Chinese
  strings in classroom-picker-dialog eliminated
- Lucide icons replace text-character arrows (↑↓) and × buttons
- All hardcoded colors (bg-blue-500, text-gray-500, text-red-500)
  replaced with semantic tokens (bg-primary, text-muted-foreground,
  text-destructive)
- Purple primary theme consistent with rest of application

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 app/course/[id]/page.tsx                      | 192 +++++++---
 app/course/page.tsx                           | 186 ++++++---
 components/course/chapter-form.tsx            |  33 +-
 components/course/chapter-list.tsx            | 355 +++++++++++-------
 components/course/classroom-picker-dialog.tsx |  83 ++--
 components/course/course-form.tsx             |  59 ++-
 lib/i18n/course.ts                            |  26 ++
 7 files changed, 622 insertions(+), 312 deletions(-)

diff --git a/app/course/[id]/page.tsx b/app/course/[id]/page.tsx
index cb700ec39..fe4039b36 100644
--- a/app/course/[id]/page.tsx
+++ b/app/course/[id]/page.tsx
@@ -2,6 +2,7 @@
 
 import { useEffect, useState, useCallback, useMemo } from 'react';
 import { useRouter } from 'next/navigation';
+import { motion } from 'motion/react';
 import { useI18n } from '@/lib/hooks/use-i18n';
 import { useCourseStore } from '@/lib/store/course';
 import { CourseForm } from '@/components/course/course-form';
@@ -9,6 +10,12 @@ import { ChapterList } from '@/components/course/chapter-list';
 import { ClassroomPickerDialog } from '@/components/course/classroom-picker-dialog';
 import type { ClassroomMeta, CourseChapterContext, CourseFormData } from '@/lib/types/course';
 import { COURSE_CHAPTER_CONTEXT_KEY } from '@/lib/types/course';
+import { Card, CardHeader, CardTitle, CardContent, CardAction } from '@/components/ui/card';
+import { Button } from '@/components/ui/button';
+import { Badge } from '@/components/ui/badge';
+import { Separator } from '@/components/ui/separator';
+import { Dialog, DialogContent, DialogHeader, DialogTitle } from '@/components/ui/dialog';
+import { ArrowLeft, Pencil, BookOpen, Building2, GraduationCap, User } from 'lucide-react';
 
 export default function CourseDetailPage({ params }: { params: Promise<{ id: string }> }) {
   const { t } = useI18n();
@@ -36,7 +43,6 @@ export default function CourseDetailPage({ params }: { params: Promise<{ id: str
 
   const loadClassroomMeta = useCallback(async (classroomIds: string[]) => {
     try {
-      // Single batch fetch instead of N per-classroom requests
       const res = await fetch('/api/classroom');
       if (!res.ok) return;
       const { classrooms } = await res.json() as { classrooms: Array<{ id: string; name?: string; sceneCount: number }> };
@@ -52,7 +58,7 @@ export default function CourseDetailPage({ params }: { params: Promise<{ id: str
         ),
       );
     } catch {
-      // non-fatal, metadata stays empty
+      // non-fatal
     }
   }, []);
 
@@ -62,14 +68,24 @@ export default function CourseDetailPage({ params }: { params: Promise<{ id: str
   // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [boundClassroomIdsKey, loadClassroomMeta]);
 
-  // Stable set for dialog — only recomputes when bound IDs change
   const usedClassroomIds = useMemo(
     () => new Set(currentCourse?.chapters.map((c) => c.classroomId).filter((id): id is string => !!id) ?? []),
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [boundClassroomIdsKey],
   );
 
-  if (!courseId || !currentCourse) return <div className="p-8">{t('common.loading')}</div>;
+  if (!courseId || !currentCourse) {
+    return (
+      <div className="min-h-[100dvh] bg-gradient-to-b from-slate-50 to-slate-100 dark:from-slate-950 dark:to-slate-900 p-4 md:p-8">
+        <div className="max-w-3xl mx-auto space-y-4 pt-8">
+          <div className="h-8 w-32 rounded-lg bg-muted animate-pulse" />
+          <div className="h-10 w-64 rounded-lg bg-muted animate-pulse" />
+          <div className="h-40 rounded-xl bg-muted animate-pulse" />
+          <div className="h-64 rounded-xl bg-muted animate-pulse" />
+        </div>
+      </div>
+    );
+  }
 
   const handleUpdate = async (data: CourseFormData) => {
     await updateCourse(courseId, data);
@@ -113,63 +129,129 @@ export default function CourseDetailPage({ params }: { params: Promise<{ id: str
     router.push(`/classroom/${classroomId}`);
   };
 
-  if (editing) {
-    return (
-      <div className="p-8 max-w-2xl mx-auto">
-        <h1 className="text-2xl mb-4">{t('course.edit')}</h1>
-        <CourseForm initialData={currentCourse} onSubmit={handleUpdate} onCancel={() => setEditing(false)} />
-      </div>
-    );
-  }
-
   return (
-    <div className="p-8 max-w-4xl mx-auto">
-      <div className="flex justify-between items-center mb-6">
-        <div>
-          <button onClick={() => router.push('/course')} className="text-sm text-gray-500 hover:text-gray-700 mb-2 block">
-            ← {t('course.myCourses')}
-          </button>
-          <h1 className="text-2xl">{currentCourse.name}</h1>
-        </div>
-        <button onClick={() => setEditing(true)} className="px-4 py-2 border rounded">
-          {t('course.edit')}
-        </button>
+    <div className="relative min-h-[100dvh] bg-gradient-to-b from-slate-50 to-slate-100 dark:from-slate-950 dark:to-slate-900 p-4 md:p-8">
+      {/* Decorative blobs */}
+      <div className="absolute inset-0 overflow-hidden pointer-events-none">
+        <div className="absolute top-0 left-1/4 w-80 h-80 bg-purple-500/8 rounded-full blur-3xl" />
+        <div className="absolute bottom-1/3 right-1/4 w-80 h-80 bg-violet-500/8 rounded-full blur-3xl" />
       </div>
 
-      <div className="mb-8 space-y-1.5 text-sm">
-        <p>
-          <span className="text-gray-500">{t('course.college')}:</span> {currentCourse.college}
-        </p>
-        <p>
-          <span className="text-gray-500">{t('course.major')}:</span> {currentCourse.major}
-        </p>
-        <p>
-          <span className="text-gray-500">{t('course.teacherName')}:</span> {currentCourse.teacherName}
-        </p>
-        <p>
-          <span className="text-gray-500">{t('course.description')}:</span> {currentCourse.description}
-        </p>
-      </div>
+      <div className="relative max-w-3xl mx-auto">
+        {/* Back nav */}
+        <motion.div
+          initial={{ opacity: 0, x: -8 }}
+          animate={{ opacity: 1, x: 0 }}
+          transition={{ duration: 0.3 }}
+          className="mb-6"
+        >
+          <Button variant="ghost" size="sm" onClick={() => router.push('/course')}>
+            <ArrowLeft />
+            {t('course.backToCourses')}
+          </Button>
+        </motion.div>
 
-      <div>
-        <h2 className="text-lg font-medium mb-3">
-          {t('course.chapter')} ({currentCourse.chapters.length})
-        </h2>
-        <ChapterList
-          courseId={courseId}
-          chapters={currentCourse.chapters}
-          classroomMeta={classroomMeta}
-          onAdd={(title, description) => addChapter(courseId, title, description)}
-          onEdit={(chapterId, title, description) => updateChapter(courseId, chapterId, { title, description })}
-          onRemove={(chapterId) => removeChapter(courseId, chapterId)}
-          onMove={handleMove}
-          onBind={handleBind}
-          onUnbind={handleUnbind}
-          onCreateAndBind={handleCreateAndBind}
-          onOpenClassroom={handleOpenClassroom}
-        />
+        {/* Course info card */}
+        <motion.div
+          initial={{ opacity: 0, y: 16 }}
+          animate={{ opacity: 1, y: 0 }}
+          transition={{ duration: 0.4 }}
+          className="mb-6"
+        >
+          <Card className="bg-white/60 dark:bg-slate-900/60 backdrop-blur-sm border-border/40">
+            <CardHeader>
+              <CardTitle className="text-xl">{currentCourse.name}</CardTitle>
+              <CardAction>
+                <Button variant="outline" size="sm" onClick={() => setEditing(true)}>
+                  <Pencil />
+                  {t('course.edit')}
+                </Button>
+              </CardAction>
+            </CardHeader>
+            <CardContent>
+              <div className="grid grid-cols-1 sm:grid-cols-2 gap-4 text-sm">
+                <div className="flex items-start gap-2">
+                  <Building2 className="size-4 text-muted-foreground mt-0.5 flex-shrink-0" />
+                  <div>
+                    <p className="text-xs font-medium text-muted-foreground uppercase tracking-wider mb-0.5">
+                      {t('course.college')}
+                    </p>
+                    <p className="text-foreground">{currentCourse.college}</p>
+                  </div>
+                </div>
+                <div className="flex items-start gap-2">
+                  <GraduationCap className="size-4 text-muted-foreground mt-0.5 flex-shrink-0" />
+                  <div>
+                    <p className="text-xs font-medium text-muted-foreground uppercase tracking-wider mb-0.5">
+                      {t('course.major')}
+                    </p>
+                    <p className="text-foreground">{currentCourse.major}</p>
+                  </div>
+                </div>
+                <div className="flex items-start gap-2">
+                  <User className="size-4 text-muted-foreground mt-0.5 flex-shrink-0" />
+                  <div>
+                    <p className="text-xs font-medium text-muted-foreground uppercase tracking-wider mb-0.5">
+                      {t('course.teacherName')}
+                    </p>
+                    <p className="text-foreground">{currentCourse.teacherName}</p>
+                  </div>
+                </div>
+                {currentCourse.description && (
+                  <div className="sm:col-span-2">
+                    <p className="text-xs font-medium text-muted-foreground uppercase tracking-wider mb-0.5">
+                      {t('course.description')}
+                    </p>
+                    <p className="text-muted-foreground">{currentCourse.description}</p>
+                  </div>
+                )}
+              </div>
+            </CardContent>
+          </Card>
+        </motion.div>
+
+        {/* Chapters section */}
+        <motion.div
+          initial={{ opacity: 0, y: 16 }}
+          animate={{ opacity: 1, y: 0 }}
+          transition={{ delay: 0.12, duration: 0.4 }}
+        >
+          <Separator className="mb-6" />
+          <div className="flex items-center gap-2 mb-4">
+            <BookOpen className="size-4 text-muted-foreground" />
+            <h2 className="text-base font-medium text-foreground">{t('course.chapters')}</h2>
+            <Badge variant="secondary" className="ml-1">
+              {currentCourse.chapters.length}
+            </Badge>
+          </div>
+
+          <ChapterList
+            courseId={courseId}
+            chapters={currentCourse.chapters}
+            classroomMeta={classroomMeta}
+            onAdd={(title, description) => addChapter(courseId, title, description)}
+            onEdit={(chapterId, title, description) => updateChapter(courseId, chapterId, { title, description })}
+            onRemove={(chapterId) => removeChapter(courseId, chapterId)}
+            onMove={handleMove}
+            onBind={handleBind}
+            onUnbind={handleUnbind}
+            onCreateAndBind={handleCreateAndBind}
+            onOpenClassroom={handleOpenClassroom}
+          />
+        </motion.div>
       </div>
 
+      {/* Edit course dialog */}
+      <Dialog open={editing} onOpenChange={(open) => { if (!open) setEditing(false); }}>
+        <DialogContent className="max-w-lg">
+          <DialogHeader>
+            <DialogTitle>{t('course.edit')}</DialogTitle>
+          </DialogHeader>
+          <CourseForm initialData={currentCourse} onSubmit={handleUpdate} onCancel={() => setEditing(false)} />
+        </DialogContent>
+      </Dialog>
+
+      {/* Classroom picker dialog */}
       {bindingChapterId && (
         <ClassroomPickerDialog
           usedClassroomIds={usedClassroomIds}
diff --git a/app/course/page.tsx b/app/course/page.tsx
index aaa4be66e..51d52f872 100644
--- a/app/course/page.tsx
+++ b/app/course/page.tsx
@@ -2,15 +2,32 @@
 
 import { useEffect, useState } from 'react';
 import { useRouter } from 'next/navigation';
+import { motion } from 'motion/react';
 import { useI18n } from '@/lib/hooks/use-i18n';
 import { useCourseStore } from '@/lib/store/course';
 import { CourseForm } from '@/components/course/course-form';
+import { Card, CardHeader, CardTitle, CardContent, CardFooter } from '@/components/ui/card';
+import { Button } from '@/components/ui/button';
+import { Badge } from '@/components/ui/badge';
+import { Dialog, DialogContent, DialogHeader, DialogTitle } from '@/components/ui/dialog';
+import {
+  AlertDialog,
+  AlertDialogContent,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogAction,
+  AlertDialogCancel,
+} from '@/components/ui/alert-dialog';
+import { Plus, BookOpen, User, Trash2 } from 'lucide-react';
 
 export default function CoursePage() {
   const { t } = useI18n();
   const router = useRouter();
   const { courses, fetchCourses, createCourse, deleteCourse } = useCourseStore();
   const [showForm, setShowForm] = useState(false);
+  const [deletingId, setDeletingId] = useState<string | null>(null);
 
   useEffect(() => {
     fetchCourses();
@@ -21,54 +38,137 @@ export default function CoursePage() {
     setShowForm(false);
   };
 
-  const handleDelete = async (id: string) => {
-    if (confirm(t('course.confirmDelete'))) {
-      await deleteCourse(id);
-    }
+  const handleConfirmDelete = async () => {
+    if (!deletingId) return;
+    await deleteCourse(deletingId);
+    setDeletingId(null);
   };
 
-  if (showForm) {
-    return (
-      <div className="p-8 max-w-2xl mx-auto">
-        <h1 className="text-2xl mb-4">{t('course.create')}</h1>
-        <CourseForm onSubmit={handleCreate} onCancel={() => setShowForm(false)} />
-      </div>
-    );
-  }
-
   return (
-    <div className="p-8">
-      <div className="flex justify-between items-center mb-6">
-        <h1 className="text-2xl">{t('course.myCourses')}</h1>
-        <button onClick={() => setShowForm(true)} className="px-4 py-2 bg-blue-500 text-white rounded">
-          {t('course.create')}
-        </button>
+    <div className="relative min-h-[100dvh] bg-gradient-to-b from-slate-50 to-slate-100 dark:from-slate-950 dark:to-slate-900 p-4 md:p-8">
+      {/* Decorative blobs */}
+      <div className="absolute inset-0 overflow-hidden pointer-events-none">
+        <div className="absolute top-0 left-1/4 w-96 h-96 bg-purple-500/8 rounded-full blur-3xl" />
+        <div className="absolute bottom-0 right-1/3 w-96 h-96 bg-violet-500/8 rounded-full blur-3xl" />
       </div>
-      {courses.length === 0 ? (
-        <p className="text-gray-500">{t('course.noCourses')}</p>
-      ) : (
-        <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
-          {courses.map((course) => (
-            <div key={course.id} className="border rounded p-4 hover:shadow-lg transition-shadow cursor-pointer">
-              <button
-                type="button"
-                onClick={() => router.push(`/course/${course.id}`)}
-                className="w-full text-left rounded focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-blue-500"
-                aria-label={`${t('course.myCourses')}: ${course.name}`}
-              >
-                <h2 className="text-xl mb-2">{course.name}</h2>
-                <p className="text-sm text-gray-600">{course.college} - {course.major}</p>
-                <p className="text-sm text-gray-500 mt-2">{course.description}</p>
-                <p className="text-sm mt-2">{t('course.teacherName')}: {course.teacherName}</p>
-                <p className="text-sm text-gray-500">{t('course.chapterCount')}: {course.chapterCount}</p>
-              </button>
-              <button onClick={() => handleDelete(course.id)} className="mt-2 text-red-500 text-sm">
-                {t('course.delete')}
-              </button>
+
+      <div className="relative max-w-5xl mx-auto">
+        {/* Page header */}
+        <motion.div
+          initial={{ opacity: 0, y: 20 }}
+          animate={{ opacity: 1, y: 0 }}
+          transition={{ duration: 0.45 }}
+          className="flex justify-between items-center mb-8"
+        >
+          <h1 className="text-2xl font-bold text-foreground">{t('course.myCourses')}</h1>
+          <Button onClick={() => setShowForm(true)}>
+            <Plus />
+            {t('course.create')}
+          </Button>
+        </motion.div>
+
+        {/* Empty state */}
+        {courses.length === 0 ? (
+          <motion.div
+            initial={{ opacity: 0, y: 16 }}
+            animate={{ opacity: 1, y: 0 }}
+            transition={{ delay: 0.1, duration: 0.4 }}
+            className="text-center py-20"
+          >
+            <div className="inline-flex items-center justify-center w-20 h-20 rounded-full bg-muted mb-5">
+              <BookOpen className="size-9 text-muted-foreground" />
             </div>
-          ))}
-        </div>
-      )}
+            <p className="text-lg font-medium text-foreground mb-2">{t('course.emptyStateTitle')}</p>
+            <p className="text-muted-foreground text-sm mb-6">{t('course.emptyStateDesc')}</p>
+            <Button onClick={() => setShowForm(true)}>
+              <Plus />
+              {t('course.create')}
+            </Button>
+          </motion.div>
+        ) : (
+          <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+            {courses.map((course, i) => (
+              <motion.div
+                key={course.id}
+                initial={{ opacity: 0, y: 16 }}
+                animate={{ opacity: 1, y: 0 }}
+                transition={{ delay: i * 0.05, duration: 0.35, ease: 'easeOut' }}
+              >
+                <Card
+                  className="bg-white/60 dark:bg-slate-900/60 backdrop-blur-sm border-border/40 hover:shadow-lg hover:shadow-violet-500/[0.06] hover:-translate-y-0.5 transition-all duration-200 cursor-pointer group"
+                  onClick={() => router.push(`/course/${course.id}`)}
+                >
+                  <CardHeader>
+                    <CardTitle className="text-base leading-snug line-clamp-2">
+                      {course.name}
+                    </CardTitle>
+                  </CardHeader>
+                  <CardContent className="space-y-3">
+                    <div className="flex flex-wrap gap-1.5">
+                      <Badge variant="secondary" className="text-xs font-normal">
+                        {course.college}
+                      </Badge>
+                      <Badge variant="secondary" className="text-xs font-normal">
+                        {course.major}
+                      </Badge>
+                    </div>
+                    {course.description && (
+                      <p className="text-sm text-muted-foreground line-clamp-2">{course.description}</p>
+                    )}
+                    <div className="flex items-center gap-1.5 text-xs text-muted-foreground">
+                      <User className="size-3.5" />
+                      <span>{course.teacherName}</span>
+                    </div>
+                    <div className="flex items-center gap-1.5 text-xs text-muted-foreground">
+                      <BookOpen className="size-3.5" />
+                      <span>{course.chapterCount} {t('course.chapter')}</span>
+                    </div>
+                  </CardContent>
+                  <CardFooter className="border-t border-border/30 pt-3">
+                    <Button
+                      variant="ghost"
+                      size="icon-sm"
+                      className="ml-auto text-muted-foreground hover:text-destructive opacity-0 group-hover:opacity-100 transition-opacity"
+                      onClick={(e) => {
+                        e.stopPropagation();
+                        setDeletingId(course.id);
+                      }}
+                    >
+                      <Trash2 />
+                    </Button>
+                  </CardFooter>
+                </Card>
+              </motion.div>
+            ))}
+          </div>
+        )}
+      </div>
+
+      {/* Create course dialog */}
+      <Dialog open={showForm} onOpenChange={(open) => { if (!open) setShowForm(false); }}>
+        <DialogContent className="max-w-lg">
+          <DialogHeader>
+            <DialogTitle>{t('course.create')}</DialogTitle>
+          </DialogHeader>
+          <CourseForm onSubmit={handleCreate} onCancel={() => setShowForm(false)} />
+        </DialogContent>
+      </Dialog>
+
+      {/* Delete confirmation */}
+      <AlertDialog open={!!deletingId} onOpenChange={(open) => { if (!open) setDeletingId(null); }}>
+        <AlertDialogContent size="sm">
+          <AlertDialogHeader>
+            <AlertDialogTitle>{t('course.confirmDeleteTitle')}</AlertDialogTitle>
+            <AlertDialogDescription>{t('course.confirmDelete')}</AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel>{t('course.cancel')}</AlertDialogCancel>
+            <AlertDialogAction variant="destructive" onClick={handleConfirmDelete}>
+              {t('course.delete')}
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
     </div>
   );
 }
diff --git a/components/course/chapter-form.tsx b/components/course/chapter-form.tsx
index bc9b1e6c3..ba48b63f1 100644
--- a/components/course/chapter-form.tsx
+++ b/components/course/chapter-form.tsx
@@ -2,6 +2,9 @@
 
 import { useId, useState } from 'react';
 import { useI18n } from '@/lib/hooks/use-i18n';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import { Button } from '@/components/ui/button';
 
 interface ChapterFormProps {
   initialTitle?: string;
@@ -25,44 +28,34 @@ export function ChapterForm({ initialTitle = '', initialDescription = '', onSubm
 
   return (
     <form onSubmit={handleSubmit} className="space-y-3">
-      <div>
-        <label htmlFor={titleId} className="block text-sm font-medium mb-1">
-          {t('course.chapterTitle')}
-        </label>
-        <input
+      <div className="space-y-1.5">
+        <Label htmlFor={titleId}>{t('course.chapterTitle')}</Label>
+        <Input
           id={titleId}
           name="title"
           type="text"
           autoComplete="off"
           value={title}
           onChange={(e) => setTitle(e.target.value)}
-          className="w-full px-3 py-2 border rounded text-sm"
           autoFocus
           required
         />
       </div>
-      <div>
-        <label htmlFor={descriptionId} className="block text-sm font-medium mb-1">
-          {t('course.chapterDescription')}
-        </label>
-        <input
+      <div className="space-y-1.5">
+        <Label htmlFor={descriptionId}>{t('course.chapterDescription')}</Label>
+        <Input
           id={descriptionId}
           name="description"
           type="text"
           autoComplete="off"
           value={description}
           onChange={(e) => setDescription(e.target.value)}
-          className="w-full px-3 py-2 border rounded text-sm"
-          placeholder="（可选）"
+          placeholder={t('course.chapterDescriptionOptional')}
         />
       </div>
-      <div className="flex gap-2">
-        <button type="submit" className="px-3 py-1.5 bg-blue-500 text-white text-sm rounded hover:bg-blue-600">
-          {t('common.confirm')}
-        </button>
-        <button type="button" onClick={onCancel} className="px-3 py-1.5 border text-sm rounded hover:bg-gray-50">
-          {t('common.cancel')}
-        </button>
+      <div className="flex gap-2 pt-1">
+        <Button type="submit" size="sm">{t('common.confirm')}</Button>
+        <Button type="button" variant="outline" size="sm" onClick={onCancel}>{t('common.cancel')}</Button>
       </div>
     </form>
   );
diff --git a/components/course/chapter-list.tsx b/components/course/chapter-list.tsx
index cd7c1227b..dc66ef251 100644
--- a/components/course/chapter-list.tsx
+++ b/components/course/chapter-list.tsx
@@ -1,9 +1,44 @@
 'use client';
 
 import { useState } from 'react';
+import { motion, AnimatePresence } from 'motion/react';
 import { useI18n } from '@/lib/hooks/use-i18n';
 import type { ClassroomMeta, CourseChapter } from '@/lib/types/course';
 import { ChapterForm } from './chapter-form';
+import { Card, CardContent } from '@/components/ui/card';
+import { Button } from '@/components/ui/button';
+import { Badge } from '@/components/ui/badge';
+import {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+} from '@/components/ui/dropdown-menu';
+import {
+  AlertDialog,
+  AlertDialogContent,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogAction,
+  AlertDialogCancel,
+} from '@/components/ui/alert-dialog';
+import {
+  ChevronUp,
+  ChevronDown,
+  Pencil,
+  Link,
+  Unlink,
+  Trash2,
+  Plus,
+  ExternalLink,
+  MoreHorizontal,
+  Sparkles,
+  BookOpen,
+} from 'lucide-react';
+import { cn } from '@/lib/utils';
 
 interface ChapterListProps {
   courseId: string;
@@ -35,6 +70,7 @@ export function ChapterList({
   const { t } = useI18n();
   const [showAddForm, setShowAddForm] = useState(false);
   const [editingId, setEditingId] = useState<string | null>(null);
+  const [removingChapterId, setRemovingChapterId] = useState<string | null>(null);
 
   const handleAdd = async (title: string, description: string | null) => {
     await onAdd(title, description);
@@ -46,149 +82,214 @@ export function ChapterList({
     setEditingId(null);
   };
 
-  const handleRemove = async (chapterId: string) => {
-    if (!confirm(t('course.confirmRemoveChapter'))) return;
-    await onRemove(chapterId);
+  const handleConfirmRemove = async () => {
+    if (!removingChapterId) return;
+    await onRemove(removingChapterId);
+    setRemovingChapterId(null);
   };
 
   if (chapters.length === 0 && !showAddForm) {
     return (
-      <div className="text-center py-12 text-gray-500">
-        <p className="mb-4">{t('course.noChapters')}</p>
-        <button
-          onClick={() => setShowAddForm(true)}
-          className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600 text-sm"
-        >
+      <div className="text-center py-16">
+        <div className="inline-flex items-center justify-center w-16 h-16 rounded-full bg-muted mb-4">
+          <BookOpen className="size-7 text-muted-foreground" />
+        </div>
+        <p className="text-muted-foreground text-sm mb-5">{t('course.noChapters')}</p>
+        <Button onClick={() => setShowAddForm(true)}>
+          <Plus />
           {t('course.addChapter')}
-        </button>
+        </Button>
       </div>
     );
   }
 
   return (
-    <div className="space-y-3">
-      {chapters.map((chapter, idx) => {
-        const meta = chapter.classroomId ? classroomMeta[chapter.classroomId] : undefined;
-        const isEditing = editingId === chapter.id;
-
-        return (
-          <div key={chapter.id} className="border rounded-lg p-4">
-            {isEditing ? (
-              <ChapterForm
-                initialTitle={chapter.title}
-                initialDescription={chapter.description}
-                onSubmit={(title, description) => handleEdit(chapter.id, title, description)}
-                onCancel={() => setEditingId(null)}
-              />
-            ) : (
-              <div className="flex items-start gap-3">
-                {/* Order number */}
-                <span className="flex-shrink-0 w-7 h-7 rounded-full bg-gray-100 flex items-center justify-center text-sm font-medium text-gray-600">
-                  {idx + 1}
-                </span>
+    <div className="space-y-2.5">
+      <AnimatePresence mode="popLayout">
+        {chapters.map((chapter, idx) => {
+          const meta = chapter.classroomId ? classroomMeta[chapter.classroomId] : undefined;
+          const isEditing = editingId === chapter.id;
 
-                {/* Content */}
-                <div className="flex-1 min-w-0">
-                  <div className="flex items-center gap-2 flex-wrap">
-                    <span className="font-medium">{chapter.title}</span>
-                    {chapter.classroomId && (
-                      <span
-                        className={`text-xs px-1.5 py-0.5 rounded-full ${
-                          meta?.published
-                            ? 'bg-green-100 text-green-700'
-                            : 'bg-gray-100 text-gray-500'
-                        }`}
-                      >
-                        {meta?.published ? t('course.published') : t('course.unpublished')}
+          return (
+            <motion.div
+              key={chapter.id}
+              layout
+              initial={{ opacity: 0, y: 10 }}
+              animate={{ opacity: 1, y: 0 }}
+              exit={{ opacity: 0, x: -20 }}
+              transition={{ duration: 0.22, ease: 'easeOut' }}
+            >
+              <Card className="bg-white/60 dark:bg-slate-900/60 backdrop-blur-sm border-border/40 hover:shadow-md hover:shadow-violet-500/[0.04] transition-all duration-200">
+                <CardContent className="py-4">
+                  {isEditing ? (
+                    <ChapterForm
+                      initialTitle={chapter.title}
+                      initialDescription={chapter.description}
+                      onSubmit={(title, description) => handleEdit(chapter.id, title, description)}
+                      onCancel={() => setEditingId(null)}
+                    />
+                  ) : (
+                    <div className="flex items-start gap-3">
+                      {/* Order number */}
+                      <span className="flex-shrink-0 w-7 h-7 rounded-full bg-primary/10 flex items-center justify-center text-sm font-medium text-primary">
+                        {idx + 1}
                       </span>
-                    )}
-                  </div>
-                  {chapter.description && (
-                    <p className="text-sm text-gray-500 mt-0.5">{chapter.description}</p>
-                  )}
-                  {chapter.classroomId && meta && (
-                    <button
-                      onClick={() => onOpenClassroom(chapter.classroomId!)}
-                      className="text-sm text-blue-600 hover:underline mt-1"
-                    >
-                      {meta.name} · {meta.sceneCount} 个场景
-                    </button>
-                  )}
-                </div>
 
-                {/* Actions */}
-                <div className="flex items-center gap-1 flex-shrink-0">
-                  <button
-                    onClick={() => onMove(chapter.id, 'up')}
-                    disabled={idx === 0}
-                    className="p-1 text-gray-400 hover:text-gray-600 disabled:opacity-30 disabled:cursor-not-allowed text-xs"
-                    title={t('course.moveUp')}
-                  >
-                    ↑
-                  </button>
-                  <button
-                    onClick={() => onMove(chapter.id, 'down')}
-                    disabled={idx === chapters.length - 1}
-                    className="p-1 text-gray-400 hover:text-gray-600 disabled:opacity-30 disabled:cursor-not-allowed text-xs"
-                    title={t('course.moveDown')}
-                  >
-                    ↓
-                  </button>
-                  <button
-                    onClick={() => setEditingId(chapter.id)}
-                    className="px-2 py-1 text-xs border rounded hover:bg-gray-50"
-                  >
-                    {t('course.editChapter')}
-                  </button>
-                  {chapter.classroomId ? (
-                    <button
-                      onClick={() => onUnbind(chapter.id)}
-                      className="px-2 py-1 text-xs border rounded hover:bg-gray-50"
-                    >
-                      {t('course.unbindClassroom')}
-                    </button>
-                  ) : (
-                    <>
-                      <button
-                        onClick={() => onBind(chapter.id)}
-                        className="px-2 py-1 text-xs border rounded hover:bg-gray-50"
-                      >
-                        {t('course.bindClassroom')}
-                      </button>
-                      <button
-                        onClick={() => onCreateAndBind(chapter.id)}
-                        className="px-2 py-1 text-xs bg-blue-500 text-white rounded hover:bg-blue-600"
-                      >
-                        {t('course.createAndBindClassroom')}
-                      </button>
-                    </>
+                      {/* Content */}
+                      <div className="flex-1 min-w-0">
+                        <div className="flex items-center gap-2 flex-wrap">
+                          <span className="font-medium text-foreground">{chapter.title}</span>
+                          {chapter.classroomId && (
+                            <Badge
+                              variant="secondary"
+                              className={cn(
+                                meta?.published
+                                  ? 'bg-emerald-500/10 text-emerald-600 dark:text-emerald-400 border border-emerald-500/20'
+                                  : '',
+                              )}
+                            >
+                              {meta?.published ? t('course.published') : t('course.unpublished')}
+                            </Badge>
+                          )}
+                        </div>
+                        {chapter.description && (
+                          <p className="text-sm text-muted-foreground mt-0.5">{chapter.description}</p>
+                        )}
+                        {chapter.classroomId && meta && (
+                          <Button
+                            variant="link"
+                            size="sm"
+                            className="h-auto p-0 mt-1 text-xs"
+                            onClick={() => onOpenClassroom(chapter.classroomId!)}
+                          >
+                            <ExternalLink className="size-3" />
+                            {meta.name} · {meta.sceneCount} {t('course.scenes')}
+                          </Button>
+                        )}
+                      </div>
+
+                      {/* Actions */}
+                      <div className="flex items-center gap-0.5 flex-shrink-0">
+                        <Button
+                          variant="ghost"
+                          size="icon-xs"
+                          disabled={idx === 0}
+                          onClick={() => onMove(chapter.id, 'up')}
+                          title={t('course.moveUp')}
+                        >
+                          <ChevronUp />
+                        </Button>
+                        <Button
+                          variant="ghost"
+                          size="icon-xs"
+                          disabled={idx === chapters.length - 1}
+                          onClick={() => onMove(chapter.id, 'down')}
+                          title={t('course.moveDown')}
+                        >
+                          <ChevronDown />
+                        </Button>
+
+                        <DropdownMenu>
+                          <DropdownMenuTrigger asChild>
+                            <Button variant="ghost" size="icon-xs">
+                              <MoreHorizontal />
+                            </Button>
+                          </DropdownMenuTrigger>
+                          <DropdownMenuContent align="end">
+                            <DropdownMenuItem onClick={() => setEditingId(chapter.id)}>
+                              <Pencil />
+                              {t('course.editChapter')}
+                            </DropdownMenuItem>
+                            {chapter.classroomId ? (
+                              <>
+                                <DropdownMenuItem onClick={() => onOpenClassroom(chapter.classroomId!)}>
+                                  <ExternalLink />
+                                  {t('course.openClassroom')}
+                                </DropdownMenuItem>
+                                <DropdownMenuItem onClick={() => onUnbind(chapter.id)}>
+                                  <Unlink />
+                                  {t('course.unbindClassroom')}
+                                </DropdownMenuItem>
+                              </>
+                            ) : (
+                              <>
+                                <DropdownMenuItem onClick={() => onBind(chapter.id)}>
+                                  <Link />
+                                  {t('course.bindClassroom')}
+                                </DropdownMenuItem>
+                                <DropdownMenuItem onClick={() => onCreateAndBind(chapter.id)}>
+                                  <Sparkles />
+                                  {t('course.createAndBindClassroom')}
+                                </DropdownMenuItem>
+                              </>
+                            )}
+                            <DropdownMenuSeparator />
+                            <DropdownMenuItem
+                              variant="destructive"
+                              onClick={() => setRemovingChapterId(chapter.id)}
+                            >
+                              <Trash2 />
+                              {t('course.removeChapter')}
+                            </DropdownMenuItem>
+                          </DropdownMenuContent>
+                        </DropdownMenu>
+                      </div>
+                    </div>
                   )}
-                  <button
-                    onClick={() => handleRemove(chapter.id)}
-                    className="px-2 py-1 text-xs text-red-500 border border-red-200 rounded hover:bg-red-50"
-                  >
-                    {t('course.removeChapter')}
-                  </button>
-                </div>
-              </div>
-            )}
-          </div>
-        );
-      })}
+                </CardContent>
+              </Card>
+            </motion.div>
+          );
+        })}
+      </AnimatePresence>
 
       {/* Add form */}
-      {showAddForm ? (
-        <div className="border rounded-lg p-4">
-          <ChapterForm onSubmit={handleAdd} onCancel={() => setShowAddForm(false)} />
-        </div>
-      ) : (
-        <button
-          onClick={() => setShowAddForm(true)}
-          className="w-full py-2 border border-dashed rounded-lg text-sm text-gray-500 hover:border-blue-400 hover:text-blue-500 transition-colors"
-        >
-          + {t('course.addChapter')}
-        </button>
-      )}
+      <AnimatePresence mode="wait">
+        {showAddForm ? (
+          <motion.div
+            key="add-form"
+            initial={{ opacity: 0, y: 8 }}
+            animate={{ opacity: 1, y: 0 }}
+            exit={{ opacity: 0, y: -4 }}
+            transition={{ duration: 0.2 }}
+          >
+            <Card className="bg-white/60 dark:bg-slate-900/60 backdrop-blur-sm border-border/40">
+              <CardContent className="py-4">
+                <ChapterForm onSubmit={handleAdd} onCancel={() => setShowAddForm(false)} />
+              </CardContent>
+            </Card>
+          </motion.div>
+        ) : (
+          <motion.button
+            key="add-btn"
+            initial={{ opacity: 0 }}
+            animate={{ opacity: 1 }}
+            exit={{ opacity: 0 }}
+            transition={{ duration: 0.15 }}
+            onClick={() => setShowAddForm(true)}
+            className="w-full py-3.5 border-2 border-dashed border-border/50 rounded-xl text-sm text-muted-foreground hover:border-primary/40 hover:text-primary hover:bg-primary/5 transition-all duration-200 flex items-center justify-center gap-2"
+          >
+            <Plus className="size-4" />
+            {t('course.addChapter')}
+          </motion.button>
+        )}
+      </AnimatePresence>
+
+      {/* Delete confirmation */}
+      <AlertDialog open={!!removingChapterId} onOpenChange={(open) => { if (!open) setRemovingChapterId(null); }}>
+        <AlertDialogContent size="sm">
+          <AlertDialogHeader>
+            <AlertDialogTitle>{t('course.confirmDeleteChapterTitle')}</AlertDialogTitle>
+            <AlertDialogDescription>{t('course.confirmRemoveChapter')}</AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel>{t('course.cancel')}</AlertDialogCancel>
+            <AlertDialogAction variant="destructive" onClick={handleConfirmRemove}>
+              {t('course.removeChapter')}
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
     </div>
   );
 }
diff --git a/components/course/classroom-picker-dialog.tsx b/components/course/classroom-picker-dialog.tsx
index 613ba2e3f..328837036 100644
--- a/components/course/classroom-picker-dialog.tsx
+++ b/components/course/classroom-picker-dialog.tsx
@@ -1,6 +1,17 @@
 'use client';
 
 import { useEffect, useState } from 'react';
+import { motion } from 'motion/react';
+import {
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  DialogDescription,
+} from '@/components/ui/dialog';
+import { ScrollArea } from '@/components/ui/scroll-area';
+import { useI18n } from '@/lib/hooks/use-i18n';
+import { cn } from '@/lib/utils';
 
 interface PublishedClassroom {
   id: string;
@@ -16,6 +27,7 @@ interface ClassroomPickerDialogProps {
 }
 
 export function ClassroomPickerDialog({ usedClassroomIds, onSelect, onClose }: ClassroomPickerDialogProps) {
+  const { t } = useI18n();
   const [classrooms, setClassrooms] = useState<PublishedClassroom[]>([]);
   const [loading, setLoading] = useState(true);
   const [submitting, setSubmitting] = useState(false);
@@ -48,41 +60,52 @@ export function ClassroomPickerDialog({ usedClassroomIds, onSelect, onClose }: C
   };
 
   return (
-    <div className="fixed inset-0 bg-black/40 flex items-center justify-center z-50" onClick={onClose}>
-      <div
-        className="bg-white rounded-lg shadow-xl w-full max-w-md max-h-[70vh] flex flex-col"
-        onClick={(e) => e.stopPropagation()}
-      >
-        <div className="flex items-center justify-between px-5 py-4 border-b">
-          <h2 className="text-base font-semibold">选择已发布课堂</h2>
-          <button onClick={onClose} className="text-gray-400 hover:text-gray-600 text-lg leading-none">
-            ×
-          </button>
-        </div>
+    <Dialog open onOpenChange={(open) => { if (!open) onClose(); }}>
+      <DialogContent className="max-w-md">
+        <DialogHeader>
+          <DialogTitle>{t('course.selectClassroom')}</DialogTitle>
+          <DialogDescription className="sr-only">
+            {t('course.noAvailableClassrooms')}
+          </DialogDescription>
+        </DialogHeader>
 
-        <div className="overflow-y-auto flex-1 px-3 py-2">
+        <ScrollArea className="max-h-[60vh] -mx-1 px-1">
           {loading ? (
-            <p className="text-center text-gray-500 py-8 text-sm">加载中…</p>
+            <div className="space-y-2 py-1">
+              {[0, 1, 2].map((i) => (
+                <div key={i} className="h-16 rounded-lg bg-muted animate-pulse" />
+              ))}
+            </div>
           ) : classrooms.length === 0 ? (
-            <p className="text-center text-gray-500 py-8 text-sm">暂无可绑定的已发布课堂</p>
+            <p className="text-center text-muted-foreground py-8 text-sm">
+              {t('course.noAvailableClassrooms')}
+            </p>
           ) : (
-            <ul className="space-y-1.5">
-              {classrooms.map((c) => (
-                <li key={c.id}>
-                  <button
-                    disabled={submitting}
-                    onClick={() => handleSelect(c.id)}
-                    className="w-full text-left px-4 py-3 rounded-lg border hover:border-blue-400 hover:bg-blue-50 transition-colors disabled:opacity-50"
-                  >
-                    <div className="font-medium text-sm">{c.name}</div>
-                    <div className="text-xs text-gray-500 mt-0.5">{c.sceneCount} 个场景</div>
-                  </button>
-                </li>
+            <div className="space-y-1.5 py-1">
+              {classrooms.map((c, i) => (
+                <motion.button
+                  key={c.id}
+                  initial={{ opacity: 0, y: 6 }}
+                  animate={{ opacity: 1, y: 0 }}
+                  transition={{ delay: i * 0.04, duration: 0.2 }}
+                  disabled={submitting}
+                  onClick={() => handleSelect(c.id)}
+                  className={cn(
+                    'w-full text-left px-4 py-3 rounded-lg border border-border/40',
+                    'hover:border-primary/40 hover:bg-primary/5 transition-all duration-150',
+                    'disabled:opacity-50 disabled:cursor-not-allowed',
+                  )}
+                >
+                  <div className="font-medium text-sm text-foreground">{c.name}</div>
+                  <div className="text-xs text-muted-foreground mt-0.5">
+                    {c.sceneCount} {t('course.scenes')}
+                  </div>
+                </motion.button>
               ))}
-            </ul>
+            </div>
           )}
-        </div>
-      </div>
-    </div>
+        </ScrollArea>
+      </DialogContent>
+    </Dialog>
   );
 }
diff --git a/components/course/course-form.tsx b/components/course/course-form.tsx
index 8ec2fb023..0c454d2e9 100644
--- a/components/course/course-form.tsx
+++ b/components/course/course-form.tsx
@@ -3,6 +3,10 @@
 import { useId, useState } from 'react';
 import { useI18n } from '@/lib/hooks/use-i18n';
 import type { CourseFormData } from '@/lib/types/course';
+import { Input } from '@/components/ui/input';
+import { Textarea } from '@/components/ui/textarea';
+import { Label } from '@/components/ui/label';
+import { Button } from '@/components/ui/button';
 
 interface CourseFormProps {
   initialData?: Partial<CourseFormData>;
@@ -32,88 +36,69 @@ export function CourseForm({ initialData, onSubmit, onCancel }: CourseFormProps)
 
   return (
     <form onSubmit={handleSubmit} className="space-y-4">
-      <div>
-        <label htmlFor={nameId} className="block text-sm mb-1">
-          {t('course.name')}
-        </label>
-        <input
+      <div className="space-y-1.5">
+        <Label htmlFor={nameId}>{t('course.name')}</Label>
+        <Input
           id={nameId}
           name="name"
           type="text"
           autoComplete="off"
           value={formData.name}
           onChange={(e) => setFormData({ ...formData, name: e.target.value })}
-          className="w-full px-3 py-2 border rounded"
           required
         />
       </div>
-      <div>
-        <label htmlFor={collegeId} className="block text-sm mb-1">
-          {t('course.college')}
-        </label>
-        <input
+      <div className="space-y-1.5">
+        <Label htmlFor={collegeId}>{t('course.college')}</Label>
+        <Input
           id={collegeId}
           name="college"
           type="text"
           autoComplete="organization"
           value={formData.college}
           onChange={(e) => setFormData({ ...formData, college: e.target.value })}
-          className="w-full px-3 py-2 border rounded"
           required
         />
       </div>
-      <div>
-        <label htmlFor={majorId} className="block text-sm mb-1">
-          {t('course.major')}
-        </label>
-        <input
+      <div className="space-y-1.5">
+        <Label htmlFor={majorId}>{t('course.major')}</Label>
+        <Input
           id={majorId}
           name="major"
           type="text"
           autoComplete="off"
           value={formData.major}
           onChange={(e) => setFormData({ ...formData, major: e.target.value })}
-          className="w-full px-3 py-2 border rounded"
           required
         />
       </div>
-      <div>
-        <label htmlFor={descriptionId} className="block text-sm mb-1">
-          {t('course.description')}
-        </label>
-        <textarea
+      <div className="space-y-1.5">
+        <Label htmlFor={descriptionId}>{t('course.description')}</Label>
+        <Textarea
           id={descriptionId}
           name="description"
           autoComplete="off"
           value={formData.description}
           onChange={(e) => setFormData({ ...formData, description: e.target.value })}
-          className="w-full px-3 py-2 border rounded"
           rows={3}
           required
         />
       </div>
-      <div>
-        <label htmlFor={teacherNameId} className="block text-sm mb-1">
-          {t('course.teacherName')}
-        </label>
-        <input
+      <div className="space-y-1.5">
+        <Label htmlFor={teacherNameId}>{t('course.teacherName')}</Label>
+        <Input
           id={teacherNameId}
           name="teacherName"
           type="text"
           autoComplete="name"
           value={formData.teacherName}
           onChange={(e) => setFormData({ ...formData, teacherName: e.target.value })}
-          className="w-full px-3 py-2 border rounded"
           required
         />
       </div>
-      <div className="flex gap-2">
-        <button type="submit" className="px-4 py-2 bg-blue-500 text-white rounded">
-          {t('common.confirm')}
-        </button>
-        <button type="button" onClick={onCancel} className="px-4 py-2 border rounded">
-          {t('common.cancel')}
-        </button>
+      <div className="flex gap-2 pt-2">
+        <Button type="submit">{t('common.confirm')}</Button>
+        <Button type="button" variant="outline" onClick={onCancel}>{t('common.cancel')}</Button>
       </div>
     </form>
   );
diff --git a/lib/i18n/course.ts b/lib/i18n/course.ts
index 433b20627..ec5d4b18f 100644
--- a/lib/i18n/course.ts
+++ b/lib/i18n/course.ts
@@ -31,6 +31,19 @@ export const courseZhCN = {
     unpublished: '未发布',
     moveUp: '上移',
     moveDown: '下移',
+    selectClassroom: '选择已发布课堂',
+    noAvailableClassrooms: '暂无可绑定的已发布课堂',
+    scenes: '个场景',
+    chapterDescriptionOptional: '（可选）',
+    backToCourses: '返回我的课程',
+    courseInfo: '课程信息',
+    chapters: '章节列表',
+    emptyStateTitle: '还没有课程',
+    emptyStateDesc: '创建你的第一个课程开始吧',
+    confirmDeleteTitle: '删除课程',
+    confirmDeleteChapterTitle: '删除章节',
+    openClassroom: '查看课堂',
+    cancel: '取消',
   },
 };
 
@@ -67,5 +80,18 @@ export const courseEnUS = {
     unpublished: 'Unpublished',
     moveUp: 'Move Up',
     moveDown: 'Move Down',
+    selectClassroom: 'Select Published Classroom',
+    noAvailableClassrooms: 'No available classrooms to bind',
+    scenes: 'scenes',
+    chapterDescriptionOptional: '(optional)',
+    backToCourses: 'Back to My Courses',
+    courseInfo: 'Course Info',
+    chapters: 'Chapters',
+    emptyStateTitle: 'No courses yet',
+    emptyStateDesc: 'Create your first course to get started',
+    confirmDeleteTitle: 'Delete Course',
+    confirmDeleteChapterTitle: 'Delete Chapter',
+    openClassroom: 'View Classroom',
+    cancel: 'Cancel',
   },
 };

From 001ed98ebaa2dbffa62559bfc610661fe1922599 Mon Sep 17 00:00:00 2001
From: zhenzhu143321 <hxcisunli@126.com>
Date: Sun, 29 Mar 2026 15:44:23 +0800
Subject: [PATCH 16/30] feat: upgrade course cards to gradient-cover design
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace simple color-bar cards with rich gradient-cover cards — 135deg gradient
header with decorative white circles, chapter count badge, teacher name, and
hover-reveal delete; matches project's glassmorphism aesthetic throughout both
the dedicated course list page and the home page 'My Courses' tab.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 app/course/page.tsx | 172 ++++++++++++++++++++++++++++++--------------
 app/page.tsx        |  88 +++++++++++++++++------
 2 files changed, 184 insertions(+), 76 deletions(-)

diff --git a/app/course/page.tsx b/app/course/page.tsx
index 51d52f872..b38b21c9b 100644
--- a/app/course/page.tsx
+++ b/app/course/page.tsx
@@ -5,10 +5,9 @@ import { useRouter } from 'next/navigation';
 import { motion } from 'motion/react';
 import { useI18n } from '@/lib/hooks/use-i18n';
 import { useCourseStore } from '@/lib/store/course';
+import type { CourseListItem } from '@/lib/types/course';
 import { CourseForm } from '@/components/course/course-form';
-import { Card, CardHeader, CardTitle, CardContent, CardFooter } from '@/components/ui/card';
 import { Button } from '@/components/ui/button';
-import { Badge } from '@/components/ui/badge';
 import { Dialog, DialogContent, DialogHeader, DialogTitle } from '@/components/ui/dialog';
 import {
   AlertDialog,
@@ -20,7 +19,115 @@ import {
   AlertDialogAction,
   AlertDialogCancel,
 } from '@/components/ui/alert-dialog';
-import { Plus, BookOpen, User, Trash2 } from 'lucide-react';
+import { Plus, BookOpen, Trash2, GraduationCap, User } from 'lucide-react';
+import { cn } from '@/lib/utils';
+
+const COVERS = [
+  { from: '#7c3aed', to: '#a78bfa' },
+  { from: '#0ea5e9', to: '#38bdf8' },
+  { from: '#059669', to: '#34d399' },
+  { from: '#e11d48', to: '#fb7185' },
+  { from: '#d97706', to: '#fbbf24' },
+  { from: '#0d9488', to: '#2dd4bf' },
+  { from: '#c026d3', to: '#e879f9' },
+  { from: '#ea580c', to: '#fb923c' },
+];
+
+function coverFor(id: string) {
+  const hash = id.split('').reduce((acc, c) => acc + c.charCodeAt(0), 0);
+  return COVERS[hash % COVERS.length];
+}
+
+interface CourseCardProps {
+  course: CourseListItem;
+  index: number;
+  onOpen: () => void;
+  onDelete: () => void;
+  chapterLabel: string;
+}
+
+function CourseCard({ course, index, onOpen, onDelete, chapterLabel }: CourseCardProps) {
+  const cover = coverFor(course.id);
+
+  return (
+    <motion.div
+      initial={{ opacity: 0, y: 22 }}
+      animate={{ opacity: 1, y: 0 }}
+      transition={{ delay: index * 0.055, duration: 0.38, ease: [0.25, 0.46, 0.45, 0.94] }}
+    >
+      <div
+        role="button"
+        tabIndex={0}
+        onClick={onOpen}
+        onKeyDown={(e) => e.key === 'Enter' && onOpen()}
+        className={cn(
+          'group rounded-2xl overflow-hidden cursor-pointer flex flex-col',
+          'border border-white/10 shadow-md hover:shadow-2xl',
+          'hover:-translate-y-1.5 transition-all duration-300',
+          'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2',
+        )}
+        style={{ minHeight: '220px' }}
+      >
+        {/* Cover area */}
+        <div
+          className="relative flex-shrink-0 h-[110px] overflow-hidden flex flex-col justify-between p-4"
+          style={{ background: `linear-gradient(135deg, ${cover.from}, ${cover.to})` }}
+        >
+          {/* Geometric decorations */}
+          <div
+            className="absolute -top-6 -right-6 w-28 h-28 rounded-full opacity-20"
+            style={{ background: 'rgba(255,255,255,0.4)' }}
+          />
+          <div
+            className="absolute bottom-0 right-8 w-16 h-16 rounded-full opacity-15"
+            style={{ background: 'rgba(255,255,255,0.5)' }}
+          />
+          <div
+            className="absolute -bottom-8 -left-4 w-32 h-32 rounded-full opacity-10"
+            style={{ background: 'rgba(255,255,255,0.6)' }}
+          />
+          {/* Top row: chapter badge + delete */}
+          <div className="relative z-10 flex items-center justify-between">
+            <span className="inline-flex items-center gap-1 text-[10px] font-semibold bg-white/20 backdrop-blur-sm text-white px-2 py-0.5 rounded-full border border-white/30">
+              <BookOpen className="size-2.5" />
+              {course.chapterCount} {chapterLabel}
+            </span>
+            <button
+              className="opacity-0 group-hover:opacity-100 transition-opacity duration-200 bg-white/15 hover:bg-white/30 backdrop-blur-sm text-white p-1 rounded-lg"
+              onClick={(e) => { e.stopPropagation(); onDelete(); }}
+              aria-label="删除课程"
+            >
+              <Trash2 className="size-3" />
+            </button>
+          </div>
+          {/* Bottom: teacher name */}
+          <div className="relative z-10 flex items-center gap-1">
+            <User className="size-2.5 text-white/70 flex-shrink-0" />
+            <span className="text-[11px] text-white/80 font-medium truncate">{course.teacherName}</span>
+          </div>
+        </div>
+
+        {/* Info area */}
+        <div className="flex-1 flex flex-col bg-white dark:bg-slate-900 px-4 pt-3.5 pb-4 min-h-0">
+          <h2 className="text-[14px] font-semibold text-foreground leading-snug line-clamp-2 mb-auto tracking-tight">
+            {course.name}
+          </h2>
+          {course.description && (
+            <p className="text-[11px] text-muted-foreground line-clamp-1 mt-1.5">
+              {course.description}
+            </p>
+          )}
+          <div className="mt-2.5 pt-2.5 border-t border-slate-100 dark:border-slate-800 flex items-center gap-1.5 min-w-0">
+            <GraduationCap className="size-3 flex-shrink-0" style={{ color: cover.from }} />
+            <span className="text-[11px] text-muted-foreground truncate">
+              {course.college} · {course.major}
+            </span>
+          </div>
+        </div>
+      </div>
+    </motion.div>
+  );
+}
 
 export default function CoursePage() {
   const { t } = useI18n();
@@ -86,59 +193,16 @@ export default function CoursePage() {
             </Button>
           </motion.div>
         ) : (
-          <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+          <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-5">
             {courses.map((course, i) => (
-              <motion.div
+              <CourseCard
                 key={course.id}
-                initial={{ opacity: 0, y: 16 }}
-                animate={{ opacity: 1, y: 0 }}
-                transition={{ delay: i * 0.05, duration: 0.35, ease: 'easeOut' }}
-              >
-                <Card
-                  className="bg-white/60 dark:bg-slate-900/60 backdrop-blur-sm border-border/40 hover:shadow-lg hover:shadow-violet-500/[0.06] hover:-translate-y-0.5 transition-all duration-200 cursor-pointer group"
-                  onClick={() => router.push(`/course/${course.id}`)}
-                >
-                  <CardHeader>
-                    <CardTitle className="text-base leading-snug line-clamp-2">
-                      {course.name}
-                    </CardTitle>
-                  </CardHeader>
-                  <CardContent className="space-y-3">
-                    <div className="flex flex-wrap gap-1.5">
-                      <Badge variant="secondary" className="text-xs font-normal">
-                        {course.college}
-                      </Badge>
-                      <Badge variant="secondary" className="text-xs font-normal">
-                        {course.major}
-                      </Badge>
-                    </div>
-                    {course.description && (
-                      <p className="text-sm text-muted-foreground line-clamp-2">{course.description}</p>
-                    )}
-                    <div className="flex items-center gap-1.5 text-xs text-muted-foreground">
-                      <User className="size-3.5" />
-                      <span>{course.teacherName}</span>
-                    </div>
-                    <div className="flex items-center gap-1.5 text-xs text-muted-foreground">
-                      <BookOpen className="size-3.5" />
-                      <span>{course.chapterCount} {t('course.chapter')}</span>
-                    </div>
-                  </CardContent>
-                  <CardFooter className="border-t border-border/30 pt-3">
-                    <Button
-                      variant="ghost"
-                      size="icon-sm"
-                      className="ml-auto text-muted-foreground hover:text-destructive opacity-0 group-hover:opacity-100 transition-opacity"
-                      onClick={(e) => {
-                        e.stopPropagation();
-                        setDeletingId(course.id);
-                      }}
-                    >
-                      <Trash2 />
-                    </Button>
-                  </CardFooter>
-                </Card>
-              </motion.div>
+                course={course}
+                index={i}
+                onOpen={() => router.push(`/course/${course.id}`)}
+                onDelete={() => setDeletingId(course.id)}
+                chapterLabel={t('course.chapter')}
+              />
             ))}
           </div>
         )}
diff --git a/app/page.tsx b/app/page.tsx
index 6d1167740..f2284e505 100644
--- a/app/page.tsx
+++ b/app/page.tsx
@@ -19,6 +19,8 @@ import {
   Monitor,
   BotOff,
   ChevronUp,
+  BookOpen,
+  GraduationCap,
 } from 'lucide-react';
 import { useI18n } from '@/lib/hooks/use-i18n';
 import { createLogger } from '@/lib/logger';
@@ -703,12 +705,14 @@ function HomePage() {
           className="relative z-10 mt-10 w-full max-w-6xl flex flex-col items-center"
         >
           {/* Tab buttons */}
-          <div className="flex gap-4 mb-4">
+          <div className="flex gap-2 mb-4 p-1 rounded-full bg-muted/60 backdrop-blur-sm">
             <button
               onClick={() => setActiveTab('courses')}
               className={cn(
-                'px-4 py-2 rounded transition-colors',
-                activeTab === 'courses' ? 'bg-blue-500 text-white' : 'bg-gray-200'
+                'px-4 py-1.5 rounded-full text-sm font-medium transition-all duration-200',
+                activeTab === 'courses'
+                  ? 'bg-primary text-primary-foreground shadow-sm'
+                  : 'text-muted-foreground hover:text-foreground',
               )}
             >
               {t('course.myCourses')} ({courses.length})
@@ -716,8 +720,10 @@ function HomePage() {
             <button
               onClick={() => setActiveTab('standalone')}
               className={cn(
-                'px-4 py-2 rounded transition-colors',
-                activeTab === 'standalone' ? 'bg-blue-500 text-white' : 'bg-gray-200'
+                'px-4 py-1.5 rounded-full text-sm font-medium transition-all duration-200',
+                activeTab === 'standalone'
+                  ? 'bg-primary text-primary-foreground shadow-sm'
+                  : 'text-muted-foreground hover:text-foreground',
               )}
             >
               {t('course.standaloneClassrooms')} ({classrooms.length})
@@ -728,28 +734,66 @@ function HomePage() {
           {activeTab === 'courses' && (
             <div className="w-full">
               <div className="flex justify-end mb-3">
-                <button
-                  onClick={() => router.push('/course')}
-                  className="px-3 py-1.5 bg-blue-500 text-white text-sm rounded hover:bg-blue-600 transition-colors"
-                >
+                <Button variant="outline" size="sm" onClick={() => router.push('/course')}>
                   {t('course.manage')}
-                </button>
+                </Button>
               </div>
               {courses.length === 0 ? (
-                <p className="text-center text-gray-500 py-8">{t('course.noCourses')}</p>
+                <p className="text-center text-muted-foreground py-8 text-sm">{t('course.noCourses')}</p>
               ) : (
                 <div className="grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-4">
-                  {courses.map((course) => (
-                    <div
-                      key={course.id}
-                      onClick={() => router.push(`/course/${course.id}`)}
-                      className="border rounded p-4 cursor-pointer hover:shadow-lg transition-shadow"
-                    >
-                      <h3 className="font-semibold">{course.name}</h3>
-                      <p className="text-sm text-gray-600">{course.college}</p>
-                      <p className="text-xs text-gray-500 mt-2">{course.chapterCount} {t('course.chapterCount')}</p>
-                    </div>
-                  ))}
+                  {courses.map((course) => {
+                    // Deterministic accent per course id
+                    const COVERS = [
+                      { from: '#7c3aed', to: '#a78bfa', dot: 'rgba(255,255,255,0.15)' },
+                      { from: '#0ea5e9', to: '#38bdf8', dot: 'rgba(255,255,255,0.15)' },
+                      { from: '#059669', to: '#34d399', dot: 'rgba(255,255,255,0.15)' },
+                      { from: '#e11d48', to: '#fb7185', dot: 'rgba(255,255,255,0.15)' },
+                      { from: '#d97706', to: '#fbbf24', dot: 'rgba(255,255,255,0.15)' },
+                      { from: '#0d9488', to: '#2dd4bf', dot: 'rgba(255,255,255,0.15)' },
+                      { from: '#c026d3', to: '#e879f9', dot: 'rgba(255,255,255,0.15)' },
+                      { from: '#ea580c', to: '#fb923c', dot: 'rgba(255,255,255,0.15)' },
+                    ];
+                    const hash = course.id.split('').reduce((a, c) => a + c.charCodeAt(0), 0);
+                    const cover = COVERS[hash % COVERS.length];
+                    return (
+                      <div
+                        key={course.id}
+                        onClick={() => router.push(`/course/${course.id}`)}
+                        className="group rounded-2xl overflow-hidden cursor-pointer border border-white/10 shadow-md hover:shadow-xl hover:-translate-y-1 transition-all duration-250 flex flex-col"
+                        style={{ minHeight: '200px' }}
+                      >
+                        {/* Cover area */}
+                        <div
+                          className="relative flex-shrink-0 h-[88px] flex items-end px-4 pb-3 overflow-hidden"
+                          style={{ background: `linear-gradient(135deg, ${cover.from}, ${cover.to})` }}
+                        >
+                          {/* Decorative circles */}
+                          <div className="absolute -top-4 -right-4 w-20 h-20 rounded-full" style={{ background: cover.dot }} />
+                          <div className="absolute top-2 right-10 w-10 h-10 rounded-full" style={{ background: cover.dot }} />
+                          <div className="absolute -bottom-6 -left-4 w-24 h-24 rounded-full" style={{ background: cover.dot }} />
+                          {/* Chapter badge */}
+                          <span className="relative z-10 inline-flex items-center gap-1 text-[10px] font-semibold bg-white/20 backdrop-blur-sm text-white px-2 py-0.5 rounded-full border border-white/30">
+                            <BookOpen className="size-2.5" />
+                            {course.chapterCount} {t('course.chapter')}
+                          </span>
+                        </div>
+
+                        {/* Info area */}
+                        <div className="flex-1 flex flex-col bg-white dark:bg-slate-900 px-4 pt-3 pb-3.5 min-h-0">
+                          <h3 className="text-[13px] font-semibold text-foreground leading-snug line-clamp-2 mb-auto">
+                            {course.name}
+                          </h3>
+                          <div className="mt-2.5 flex items-center gap-1.5 min-w-0">
+                            <GraduationCap className="size-3 flex-shrink-0" style={{ color: cover.from }} />
+                            <span className="text-[11px] text-muted-foreground truncate">
+                              {course.college} · {course.major}
+                            </span>
+                          </div>
+                        </div>
+                      </div>
+                    );
+                  })}
                 </div>
               )}
             </div>

From 83e3e23b8994cddbb418bb1f1e1c639c69bb6bc1 Mon Sep 17 00:00:00 2001
From: zhenzhu143321 <hxcisunli@126.com>
Date: Sun, 29 Mar 2026 16:09:10 +0800
Subject: [PATCH 17/30] =?UTF-8?q?fix:=20unify=20course=20card=20layout=20?=
 =?UTF-8?q?=E2=80=94=20name=20in=20cover,=203-line=20description?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Move course name into the gradient cover area (88px), expand the white
info section to show 3 lines of description, and align home page cards
with the dedicated course list page for visual consistency.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 app/course/page.tsx | 50 ++++++++++++++++++++++-----------------------
 app/page.tsx        | 29 ++++++++++++++++----------
 2 files changed, 43 insertions(+), 36 deletions(-)

diff --git a/app/course/page.tsx b/app/course/page.tsx
index b38b21c9b..d86f574fd 100644
--- a/app/course/page.tsx
+++ b/app/course/page.tsx
@@ -68,22 +68,18 @@ function CourseCard({ course, index, onOpen, onDelete, chapterLabel }: CourseCar
         )}
         style={{ minHeight: '220px' }}
       >
-        {/* Cover area */}
+        {/* Cover area — compact, holds course name */}
         <div
-          className="relative flex-shrink-0 h-[110px] overflow-hidden flex flex-col justify-between p-4"
+          className="relative flex-shrink-0 h-[88px] overflow-hidden flex flex-col justify-between px-4 pt-3 pb-3"
           style={{ background: `linear-gradient(135deg, ${cover.from}, ${cover.to})` }}
         >
           {/* Geometric decorations */}
           <div
-            className="absolute -top-6 -right-6 w-28 h-28 rounded-full opacity-20"
+            className="absolute -top-5 -right-5 w-24 h-24 rounded-full opacity-20"
             style={{ background: 'rgba(255,255,255,0.4)' }}
           />
           <div
-            className="absolute bottom-0 right-8 w-16 h-16 rounded-full opacity-15"
-            style={{ background: 'rgba(255,255,255,0.5)' }}
-          />
-          <div
-            className="absolute -bottom-8 -left-4 w-32 h-32 rounded-full opacity-10"
+            className="absolute -bottom-6 -left-3 w-28 h-28 rounded-full opacity-10"
             style={{ background: 'rgba(255,255,255,0.6)' }}
           />
           {/* Top row: chapter badge + delete */}
@@ -100,28 +96,32 @@ function CourseCard({ course, index, onOpen, onDelete, chapterLabel }: CourseCar
               <Trash2 className="size-3" />
             </button>
           </div>
-          {/* Bottom: teacher name */}
-          <div className="relative z-10 flex items-center gap-1">
-            <User className="size-2.5 text-white/70 flex-shrink-0" />
-            <span className="text-[11px] text-white/80 font-medium truncate">{course.teacherName}</span>
-          </div>
-        </div>
-
-        {/* Info area */}
-        <div className="flex-1 flex flex-col bg-white dark:bg-slate-900 px-4 pt-3.5 pb-4 min-h-0">
-          <h2 className="text-[14px] font-semibold text-foreground leading-snug line-clamp-2 mb-auto tracking-tight">
+          {/* Course name on gradient */}
+          <h2 className="relative z-10 text-[13px] font-bold text-white leading-snug line-clamp-1 tracking-tight drop-shadow-sm">
             {course.name}
           </h2>
-          {course.description && (
-            <p className="text-[11px] text-muted-foreground line-clamp-1 mt-1.5">
+        </div>
+
+        {/* Info area — taller now, 3 lines of description */}
+        <div className="flex-1 flex flex-col bg-white dark:bg-slate-900 px-4 pt-3 pb-4 min-h-0">
+          {course.description ? (
+            <p className="text-[11px] text-muted-foreground line-clamp-3 mb-auto leading-relaxed">
               {course.description}
             </p>
+          ) : (
+            <div className="mb-auto" />
           )}
-          <div className="mt-2.5 pt-2.5 border-t border-slate-100 dark:border-slate-800 flex items-center gap-1.5 min-w-0">
-            <GraduationCap className="size-3 flex-shrink-0" style={{ color: cover.from }} />
-            <span className="text-[11px] text-muted-foreground truncate">
-              {course.college} · {course.major}
-            </span>
+          <div className="mt-2.5 pt-2.5 border-t border-slate-100 dark:border-slate-800 flex items-center justify-between gap-2 min-w-0">
+            <div className="flex items-center gap-1.5 min-w-0">
+              <GraduationCap className="size-3 flex-shrink-0" style={{ color: cover.from }} />
+              <span className="text-[11px] text-muted-foreground truncate">
+                {course.college} · {course.major}
+              </span>
+            </div>
+            <div className="flex items-center gap-1 flex-shrink-0">
+              <User className="size-2.5 text-muted-foreground/60" />
+              <span className="text-[11px] text-muted-foreground/70 truncate max-w-[72px]">{course.teacherName}</span>
+            </div>
           </div>
         </div>
       </div>
diff --git a/app/page.tsx b/app/page.tsx
index f2284e505..0373ef8f3 100644
--- a/app/page.tsx
+++ b/app/page.tsx
@@ -763,28 +763,35 @@ function HomePage() {
                         className="group rounded-2xl overflow-hidden cursor-pointer border border-white/10 shadow-md hover:shadow-xl hover:-translate-y-1 transition-all duration-250 flex flex-col"
                         style={{ minHeight: '200px' }}
                       >
-                        {/* Cover area */}
+                        {/* Cover area — compact with course name */}
                         <div
-                          className="relative flex-shrink-0 h-[88px] flex items-end px-4 pb-3 overflow-hidden"
+                          className="relative flex-shrink-0 h-[88px] flex flex-col justify-between px-3 pt-2.5 pb-2.5 overflow-hidden"
                           style={{ background: `linear-gradient(135deg, ${cover.from}, ${cover.to})` }}
                         >
                           {/* Decorative circles */}
                           <div className="absolute -top-4 -right-4 w-20 h-20 rounded-full" style={{ background: cover.dot }} />
-                          <div className="absolute top-2 right-10 w-10 h-10 rounded-full" style={{ background: cover.dot }} />
-                          <div className="absolute -bottom-6 -left-4 w-24 h-24 rounded-full" style={{ background: cover.dot }} />
+                          <div className="absolute -bottom-5 -left-3 w-24 h-24 rounded-full" style={{ background: cover.dot }} />
                           {/* Chapter badge */}
-                          <span className="relative z-10 inline-flex items-center gap-1 text-[10px] font-semibold bg-white/20 backdrop-blur-sm text-white px-2 py-0.5 rounded-full border border-white/30">
+                          <span className="relative z-10 inline-flex items-center gap-1 text-[10px] font-semibold bg-white/20 backdrop-blur-sm text-white px-2 py-0.5 rounded-full border border-white/30 self-start">
                             <BookOpen className="size-2.5" />
                             {course.chapterCount} {t('course.chapter')}
                           </span>
-                        </div>
-
-                        {/* Info area */}
-                        <div className="flex-1 flex flex-col bg-white dark:bg-slate-900 px-4 pt-3 pb-3.5 min-h-0">
-                          <h3 className="text-[13px] font-semibold text-foreground leading-snug line-clamp-2 mb-auto">
+                          {/* Course name on gradient */}
+                          <h3 className="relative z-10 text-[12px] font-bold text-white leading-snug line-clamp-1 tracking-tight drop-shadow-sm">
                             {course.name}
                           </h3>
-                          <div className="mt-2.5 flex items-center gap-1.5 min-w-0">
+                        </div>
+
+                        {/* Info area — taller, shows description */}
+                        <div className="flex-1 flex flex-col bg-white dark:bg-slate-900 px-3 pt-2.5 pb-3 min-h-0">
+                          {course.description ? (
+                            <p className="text-[11px] text-muted-foreground line-clamp-3 mb-auto leading-relaxed">
+                              {course.description}
+                            </p>
+                          ) : (
+                            <div className="mb-auto" />
+                          )}
+                          <div className="mt-2 flex items-center gap-1.5 min-w-0">
                             <GraduationCap className="size-3 flex-shrink-0" style={{ color: cover.from }} />
                             <span className="text-[11px] text-muted-foreground truncate">
                               {course.college} · {course.major}

From 444ba78c866e0f14c045fc3b4e688bbab619e005 Mon Sep 17 00:00:00 2001
From: zhenzhu143321 <hxcisunli@126.com>
Date: Sun, 29 Mar 2026 17:33:52 +0800
Subject: [PATCH 18/30] fix: rename homepage tabs to reflect actual data
 sources
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Rename misleading labels per information architecture review:
- 我的课程 → 课程管理 (Course Library): no user isolation exists
- 独立课堂 → 本地课堂 (Local Classrooms): browser IndexedDB, not server data
- 公共课程 → 已发布课堂 (Published Classrooms): shows classrooms, not courses
- 返回我的课程 → 返回课程管理

Also add a hint under the Local Classrooms tab explaining browser-local storage.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 app/page.tsx           |  4 ++++
 lib/i18n/course.ts     | 14 ++++++++------
 lib/i18n/generation.ts |  8 ++++----
 3 files changed, 16 insertions(+), 10 deletions(-)

diff --git a/app/page.tsx b/app/page.tsx
index 0373ef8f3..34858ff63 100644
--- a/app/page.tsx
+++ b/app/page.tsx
@@ -809,6 +809,10 @@ function HomePage() {
           {/* Standalone classrooms tab */}
           {activeTab === 'standalone' && (
             <>
+              {/* Browser-local hint */}
+              <p className="w-full text-center text-[11px] text-muted-foreground/50 mb-3">
+                {t('course.localClassroomHint')}
+              </p>
               {/* Trigger — divider-line with centered text */}
               <button
             onClick={() => {
diff --git a/lib/i18n/course.ts b/lib/i18n/course.ts
index ec5d4b18f..f3ad665da 100644
--- a/lib/i18n/course.ts
+++ b/lib/i18n/course.ts
@@ -9,8 +9,8 @@ export const courseZhCN = {
     edit: '编辑课程',
     delete: '删除课程',
     manage: '管理课程',
-    myCourses: '我的课程',
-    standaloneClassrooms: '独立课堂',
+    myCourses: '课程管理',
+    standaloneClassrooms: '本地课堂',
     noCourses: '暂无课程',
     noClassrooms: '暂无课堂',
     confirmDelete: '确定删除此课程吗？',
@@ -35,7 +35,7 @@ export const courseZhCN = {
     noAvailableClassrooms: '暂无可绑定的已发布课堂',
     scenes: '个场景',
     chapterDescriptionOptional: '（可选）',
-    backToCourses: '返回我的课程',
+    backToCourses: '返回课程管理',
     courseInfo: '课程信息',
     chapters: '章节列表',
     emptyStateTitle: '还没有课程',
@@ -44,6 +44,7 @@ export const courseZhCN = {
     confirmDeleteChapterTitle: '删除章节',
     openClassroom: '查看课堂',
     cancel: '取消',
+    localClassroomHint: '仅保存在当前浏览器，不同浏览器数量可能不同',
   },
 };
 
@@ -58,8 +59,8 @@ export const courseEnUS = {
     edit: 'Edit Course',
     delete: 'Delete Course',
     manage: 'Manage Courses',
-    myCourses: 'My Courses',
-    standaloneClassrooms: 'Standalone Classrooms',
+    myCourses: 'Course Library',
+    standaloneClassrooms: 'Local Classrooms',
     noCourses: 'No courses yet',
     noClassrooms: 'No classrooms yet',
     confirmDelete: 'Are you sure you want to delete this course?',
@@ -84,7 +85,7 @@ export const courseEnUS = {
     noAvailableClassrooms: 'No available classrooms to bind',
     scenes: 'scenes',
     chapterDescriptionOptional: '(optional)',
-    backToCourses: 'Back to My Courses',
+    backToCourses: 'Back to Course Library',
     courseInfo: 'Course Info',
     chapters: 'Chapters',
     emptyStateTitle: 'No courses yet',
@@ -93,5 +94,6 @@ export const courseEnUS = {
     confirmDeleteChapterTitle: 'Delete Chapter',
     openClassroom: 'View Classroom',
     cancel: 'Cancel',
+    localClassroomHint: 'Saved in this browser only; counts may differ across browsers',
   },
 };
diff --git a/lib/i18n/generation.ts b/lib/i18n/generation.ts
index 43d60a4b3..5ff3e4b13 100644
--- a/lib/i18n/generation.ts
+++ b/lib/i18n/generation.ts
@@ -8,8 +8,8 @@ export const generationZhCN = {
     nameCopied: '课堂名称已复制',
     deleteConfirmTitle: '删除课堂',
     delete: '删除',
-    publicClassrooms: '公共课程',
-    noPublicClassrooms: '暂无公共课程',
+    publicClassrooms: '已发布课堂',
+    noPublicClassrooms: '暂无已发布课堂',
   },
   upload: {
     pdfSizeLimit: '支持最大50MB的PDF文件',
@@ -74,8 +74,8 @@ export const generationEnUS = {
     nameCopied: 'Name copied',
     deleteConfirmTitle: 'Delete',
     delete: 'Delete',
-    publicClassrooms: 'Public Classrooms',
-    noPublicClassrooms: 'No public classrooms yet',
+    publicClassrooms: 'Published Classrooms',
+    noPublicClassrooms: 'No published classrooms yet',
   },
   upload: {
     pdfSizeLimit: 'Supports PDF files up to 50MB',

From 794ec2e5635afac5d1f62250326bbe9e55e9b47c Mon Sep 17 00:00:00 2001
From: zhenzhu143321 <hxcisunli@126.com>
Date: Sun, 29 Mar 2026 19:37:34 +0800
Subject: [PATCH 19/30] fix: improve homepage tab UX and date display
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add 'twoDaysAgo' i18n key (前天 / Two days ago) to formatDate so
  2-day-old classrooms show '前天' instead of '2 天前'
- Rename '最近学习' → '本地课堂记录' for terminology consistency within
  the Local Classrooms tab
- Auto-switch default tab to 'courses' when courses exist but no local
  classrooms are present

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 app/page.tsx           | 10 ++++++++++
 lib/i18n/generation.ts |  6 ++++--
 2 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/app/page.tsx b/app/page.tsx
index 34858ff63..b1ccfae80 100644
--- a/app/page.tsx
+++ b/app/page.tsx
@@ -154,6 +154,14 @@ function HomePage() {
   const [activeTab, setActiveTab] = useState<'courses' | 'standalone'>('standalone');
   const { courses, fetchCourses } = useCourseStore();
 
+  // Default to 'courses' tab when courses exist but no local classrooms
+  useEffect(() => {
+    if (courses.length > 0 && classrooms.length === 0) {
+      setActiveTab('courses');
+    }
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [courses.length, classrooms.length]);
+
   // Close dropdowns when clicking outside
   useEffect(() => {
     if (!languageOpen && !themeOpen) return;
@@ -361,6 +369,7 @@ function HomePage() {
 
     if (diffDays === 0) return t('classroom.today');
     if (diffDays === 1) return t('classroom.yesterday');
+    if (diffDays === 2) return t('classroom.twoDaysAgo');
     if (diffDays < 7) return `${diffDays} ${t('classroom.daysAgo')}`;
     return date.toLocaleDateString();
   };
@@ -1212,6 +1221,7 @@ function PublicClassroomCard({
     const diffDays = Math.floor((now.getTime() - date.getTime()) / (1000 * 60 * 60 * 24));
     if (diffDays === 0) return t('classroom.today');
     if (diffDays === 1) return t('classroom.yesterday');
+    if (diffDays === 2) return t('classroom.twoDaysAgo');
     if (diffDays < 7) return `${diffDays} ${t('classroom.daysAgo')}`;
     return date.toLocaleDateString();
   };
diff --git a/lib/i18n/generation.ts b/lib/i18n/generation.ts
index 5ff3e4b13..5a64c17cc 100644
--- a/lib/i18n/generation.ts
+++ b/lib/i18n/generation.ts
@@ -1,8 +1,9 @@
 export const generationZhCN = {
   classroom: {
-    recentClassrooms: '最近学习',
+    recentClassrooms: '本地课堂记录',
     today: '今天',
     yesterday: '昨天',
+    twoDaysAgo: '前天',
     daysAgo: '天前',
     slides: '页',
     nameCopied: '课堂名称已复制',
@@ -66,9 +67,10 @@ export const generationZhCN = {
 
 export const generationEnUS = {
   classroom: {
-    recentClassrooms: 'Recent',
+    recentClassrooms: 'Local Classrooms',
     today: 'Today',
     yesterday: 'Yesterday',
+    twoDaysAgo: 'Two days ago',
     daysAgo: 'days ago',
     slides: 'slides',
     nameCopied: 'Name copied',

From b8fe62020d5d438ea9f5812778d82238052be172 Mon Sep 17 00:00:00 2001
From: zhenzhu143321 <hxcisunli@126.com>
Date: Sun, 29 Mar 2026 20:36:59 +0800
Subject: [PATCH 20/30] feat: course-level publish/unpublish with homepage
 public courses section

- Add status/publishedAt fields to Course and CourseListItem types
- Backfill status='draft' for old courses without the field
- Support GET /api/course?status=published filter
- Add publishCourse/unpublishCourse actions to Zustand store
- Course detail page: publish button with canPublish guard, tooltip on
  disabled state, AlertDialog confirmation, X/N bound progress badge
- Homepage: fetch and render published courses section above classrooms

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 app/api/course/route.ts      |  4 +-
 app/course/[id]/page.tsx     | 99 +++++++++++++++++++++++++++++++++---
 app/page.tsx                 | 89 ++++++++++++++++++++++++++++++--
 lib/i18n/course.ts           | 20 ++++++++
 lib/server/course-storage.ts | 34 ++++++++-----
 lib/store/course.ts          | 35 +++++++++++++
 lib/types/course.ts          |  2 +
 7 files changed, 261 insertions(+), 22 deletions(-)

diff --git a/app/api/course/route.ts b/app/api/course/route.ts
index f5aeef46c..9cde8429d 100644
--- a/app/api/course/route.ts
+++ b/app/api/course/route.ts
@@ -16,7 +16,9 @@ export async function GET(req: NextRequest) {
     }
 
     const courses = await listCourses();
-    return NextResponse.json(courses);
+    const statusFilter = searchParams.get('status');
+    const filtered = statusFilter ? courses.filter((c) => c.status === statusFilter) : courses;
+    return NextResponse.json(filtered);
   } catch (error) {
     return NextResponse.json({ error: String(error) }, { status: 500 });
   }
diff --git a/app/course/[id]/page.tsx b/app/course/[id]/page.tsx
index fe4039b36..5db9a0acf 100644
--- a/app/course/[id]/page.tsx
+++ b/app/course/[id]/page.tsx
@@ -15,17 +15,31 @@ import { Button } from '@/components/ui/button';
 import { Badge } from '@/components/ui/badge';
 import { Separator } from '@/components/ui/separator';
 import { Dialog, DialogContent, DialogHeader, DialogTitle } from '@/components/ui/dialog';
-import { ArrowLeft, Pencil, BookOpen, Building2, GraduationCap, User } from 'lucide-react';
+import {
+  AlertDialog,
+  AlertDialogContent,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogAction,
+  AlertDialogCancel,
+} from '@/components/ui/alert-dialog';
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip';
+import { ArrowLeft, Pencil, BookOpen, Building2, GraduationCap, User, Globe, GlobeLock } from 'lucide-react';
+
+type PublishDialogMode = 'publish' | 'unpublish' | null;
 
 export default function CourseDetailPage({ params }: { params: Promise<{ id: string }> }) {
   const { t } = useI18n();
   const router = useRouter();
-  const { currentCourse, fetchCourse, updateCourse, addChapter, updateChapter, removeChapter, reorderChapters } =
+  const { currentCourse, fetchCourse, updateCourse, addChapter, updateChapter, removeChapter, reorderChapters, publishCourse, unpublishCourse } =
     useCourseStore();
   const [editing, setEditing] = useState(false);
   const [courseId, setCourseId] = useState<string | null>(null);
   const [classroomMeta, setClassroomMeta] = useState<Record<string, ClassroomMeta>>({});
   const [bindingChapterId, setBindingChapterId] = useState<string | null>(null);
+  const [publishDialog, setPublishDialog] = useState<PublishDialogMode>(null);
 
   useEffect(() => {
     params.then(({ id }) => {
@@ -87,6 +101,13 @@ export default function CourseDetailPage({ params }: { params: Promise<{ id: str
     );
   }
 
+  const canPublish =
+    currentCourse.chapters.length > 0 &&
+    currentCourse.chapters.every((ch) => !!ch.classroomId);
+  const boundCount = currentCourse.chapters.filter((ch) => !!ch.classroomId).length;
+  const totalCount = currentCourse.chapters.length;
+  const isPublished = currentCourse.status === 'published';
+
   const handleUpdate = async (data: CourseFormData) => {
     await updateCourse(courseId, data);
     setEditing(false);
@@ -107,6 +128,13 @@ export default function CourseDetailPage({ params }: { params: Promise<{ id: str
     await updateChapter(courseId, chapterId, { classroomId: null });
   };
 
+  const handlePublishConfirm = async () => {
+    if (!courseId) return;
+    if (publishDialog === 'publish') await publishCourse(courseId);
+    else if (publishDialog === 'unpublish') await unpublishCourse(courseId);
+    setPublishDialog(null);
+  };
+
   const handleBind = (chapterId: string) => {
     setBindingChapterId(chapterId);
   };
@@ -162,10 +190,41 @@ export default function CourseDetailPage({ params }: { params: Promise<{ id: str
             <CardHeader>
               <CardTitle className="text-xl">{currentCourse.name}</CardTitle>
               <CardAction>
-                <Button variant="outline" size="sm" onClick={() => setEditing(true)}>
-                  <Pencil />
-                  {t('course.edit')}
-                </Button>
+                <div className="flex items-center gap-2">
+                  {isPublished ? (
+                    <>
+                      <Badge variant="secondary" className="gap-1 text-emerald-600 dark:text-emerald-400 border-emerald-200 dark:border-emerald-800 bg-emerald-50 dark:bg-emerald-950/40">
+                        <Globe className="size-3" />
+                        {t('course.publishedStatus')}
+                      </Badge>
+                      <Button variant="ghost" size="sm" className="text-muted-foreground hover:text-destructive" onClick={() => setPublishDialog('unpublish')}>
+                        <GlobeLock className="size-4" />
+                        {t('course.unpublish')}
+                      </Button>
+                    </>
+                  ) : canPublish ? (
+                    <Button variant="default" size="sm" onClick={() => setPublishDialog('publish')}>
+                      <Globe className="size-4" />
+                      {t('course.publish')}
+                    </Button>
+                  ) : (
+                    <Tooltip>
+                      <TooltipTrigger asChild>
+                        <span tabIndex={0}>
+                          <Button variant="outline" size="sm" disabled>
+                            <Globe className="size-4" />
+                            {t('course.publish')}
+                          </Button>
+                        </span>
+                      </TooltipTrigger>
+                      <TooltipContent>{t('course.cannotPublish')}</TooltipContent>
+                    </Tooltip>
+                  )}
+                  <Button variant="outline" size="sm" onClick={() => setEditing(true)}>
+                    <Pencil />
+                    {t('course.edit')}
+                  </Button>
+                </div>
               </CardAction>
             </CardHeader>
             <CardContent>
@@ -223,6 +282,14 @@ export default function CourseDetailPage({ params }: { params: Promise<{ id: str
             <Badge variant="secondary" className="ml-1">
               {currentCourse.chapters.length}
             </Badge>
+            {totalCount > 0 && (
+              <Badge
+                variant="outline"
+                className={`ml-auto text-xs ${boundCount === totalCount ? 'text-emerald-600 dark:text-emerald-400 border-emerald-200 dark:border-emerald-800' : 'text-muted-foreground'}`}
+              >
+                {boundCount}/{totalCount} {t('course.chaptersReady')}
+              </Badge>
+            )}
           </div>
 
           <ChapterList
@@ -259,6 +326,26 @@ export default function CourseDetailPage({ params }: { params: Promise<{ id: str
           onClose={() => setBindingChapterId(null)}
         />
       )}
+
+      {/* Publish / Unpublish confirmation dialog */}
+      <AlertDialog open={publishDialog !== null} onOpenChange={(open) => { if (!open) setPublishDialog(null); }}>
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogTitle>
+              {publishDialog === 'publish' ? t('course.publish') : t('course.unpublish')}
+            </AlertDialogTitle>
+            <AlertDialogDescription>
+              {publishDialog === 'publish' ? t('course.confirmPublish') : t('course.confirmUnpublish')}
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel>{t('course.cancel')}</AlertDialogCancel>
+            <AlertDialogAction onClick={handlePublishConfirm}>
+              {publishDialog === 'publish' ? t('course.publish') : t('course.unpublish')}
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
     </div>
   );
 }
diff --git a/app/page.tsx b/app/page.tsx
index b1ccfae80..435dc1218 100644
--- a/app/page.tsx
+++ b/app/page.tsx
@@ -34,7 +34,7 @@ import { useTheme } from '@/lib/hooks/use-theme';
 import { nanoid } from 'nanoid';
 import { storePdfBlob } from '@/lib/utils/image-storage';
 import type { UserRequirements } from '@/lib/types/generation';
-import { COURSE_CHAPTER_CONTEXT_KEY, type CourseChapterContext } from '@/lib/types/course';
+import { COURSE_CHAPTER_CONTEXT_KEY, type CourseChapterContext, type CourseListItem } from '@/lib/types/course';
 import { useSettingsStore } from '@/lib/store/settings';
 import { useUserProfileStore, AVATAR_OPTIONS } from '@/lib/store/user-profile';
 import {
@@ -148,6 +148,7 @@ function HomePage() {
   const [thumbnails, setThumbnails] = useState<Record<string, Slide>>({});
   const [publicClassrooms, setPublicClassrooms] = useState<PublicClassroomItem[]>([]);
   const [publicThumbnails, setPublicThumbnails] = useState<Record<string, Slide>>({});
+  const [publishedCourses, setPublishedCourses] = useState<CourseListItem[]>([]);
   const [pendingDeleteId, setPendingDeleteId] = useState<string | null>(null);
   const toolbarRef = useRef<HTMLDivElement>(null);
   const textareaRef = useRef<HTMLTextAreaElement>(null);
@@ -200,8 +201,9 @@ function HomePage() {
     Promise.all([
       loadClassrooms(),
       fetchCourses(),
-      fetch('/api/classroom').then(res => res.json())
-    ]).then(([, , publicData]) => {
+      fetch('/api/classroom').then(res => res.json()),
+      fetch('/api/course?status=published').then(res => res.json()),
+    ]).then(([, , publicData, publishedCourseData]) => {
       if (publicData.success && publicData.classrooms) {
         setPublicClassrooms(publicData.classrooms);
         const thumbs: Record<string, Slide> = {};
@@ -218,6 +220,9 @@ function HomePage() {
         }
         setPublicThumbnails(thumbs);
       }
+      if (Array.isArray(publishedCourseData)) {
+        setPublishedCourses(publishedCourseData);
+      }
     }).catch(() => {});
   }, []);
 
@@ -668,6 +673,84 @@ function HomePage() {
         </AnimatePresence>
       </motion.div>
 
+      {/* ═══ Published courses ═══ */}
+      {publishedCourses.length > 0 && (
+        <motion.div
+          initial={{ opacity: 0 }}
+          animate={{ opacity: 1 }}
+          transition={{ delay: 0.42 }}
+          className="relative z-10 mt-10 w-full max-w-6xl flex flex-col items-center"
+        >
+          <div className="w-full flex items-center gap-4 py-2">
+            <div className="flex-1 h-px bg-border/40" />
+            <span className="shrink-0 flex items-center gap-2 text-[13px] text-muted-foreground/60 select-none">
+              <Globe className="size-3.5" />
+              {t('course.publishedCourses')}
+              <span className="text-[11px] tabular-nums opacity-60">{publishedCourses.length}</span>
+            </span>
+            <div className="flex-1 h-px bg-border/40" />
+          </div>
+
+          <div className="pt-4 grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-4 w-full">
+            {publishedCourses.map((course, i) => {
+              const COVERS = [
+                { from: '#7c3aed', to: '#a78bfa', dot: 'rgba(255,255,255,0.15)' },
+                { from: '#0ea5e9', to: '#38bdf8', dot: 'rgba(255,255,255,0.15)' },
+                { from: '#059669', to: '#34d399', dot: 'rgba(255,255,255,0.15)' },
+                { from: '#e11d48', to: '#fb7185', dot: 'rgba(255,255,255,0.15)' },
+                { from: '#d97706', to: '#fbbf24', dot: 'rgba(255,255,255,0.15)' },
+                { from: '#0d9488', to: '#2dd4bf', dot: 'rgba(255,255,255,0.15)' },
+                { from: '#c026d3', to: '#e879f9', dot: 'rgba(255,255,255,0.15)' },
+                { from: '#ea580c', to: '#fb923c', dot: 'rgba(255,255,255,0.15)' },
+              ];
+              const hash = course.id.split('').reduce((a, c) => a + c.charCodeAt(0), 0);
+              const cover = COVERS[hash % COVERS.length];
+              return (
+                <motion.div
+                  key={course.id}
+                  initial={{ opacity: 0, y: 16 }}
+                  animate={{ opacity: 1, y: 0 }}
+                  transition={{ delay: i * 0.04, duration: 0.35, ease: 'easeOut' }}
+                  onClick={() => router.push(`/course/${course.id}`)}
+                  className="group rounded-2xl overflow-hidden cursor-pointer border border-white/10 shadow-md hover:shadow-xl hover:-translate-y-1 transition-all duration-250 flex flex-col"
+                  style={{ minHeight: '200px' }}
+                >
+                  <div
+                    className="relative flex-shrink-0 h-[88px] flex flex-col justify-between px-3 pt-2.5 pb-2.5 overflow-hidden"
+                    style={{ background: `linear-gradient(135deg, ${cover.from}, ${cover.to})` }}
+                  >
+                    <div className="absolute -top-4 -right-4 w-20 h-20 rounded-full" style={{ background: cover.dot }} />
+                    <div className="absolute -bottom-5 -left-3 w-24 h-24 rounded-full" style={{ background: cover.dot }} />
+                    <span className="relative z-10 inline-flex items-center gap-1 text-[10px] font-semibold bg-white/20 backdrop-blur-sm text-white px-2 py-0.5 rounded-full border border-white/30 self-start">
+                      <BookOpen className="size-2.5" />
+                      {course.chapterCount} {t('course.chapter')}
+                    </span>
+                    <h3 className="relative z-10 text-[12px] font-bold text-white leading-snug line-clamp-1 tracking-tight drop-shadow-sm">
+                      {course.name}
+                    </h3>
+                  </div>
+                  <div className="flex-1 flex flex-col bg-white dark:bg-slate-900 px-3 pt-2.5 pb-3 min-h-0">
+                    {course.description ? (
+                      <p className="text-[11px] text-muted-foreground line-clamp-3 mb-auto leading-relaxed">
+                        {course.description}
+                      </p>
+                    ) : (
+                      <div className="mb-auto" />
+                    )}
+                    <div className="mt-2 flex items-center gap-1.5 min-w-0">
+                      <GraduationCap className="size-3 flex-shrink-0" style={{ color: cover.from }} />
+                      <span className="text-[11px] text-muted-foreground truncate">
+                        {course.college} · {course.major}
+                      </span>
+                    </div>
+                  </div>
+                </motion.div>
+              );
+            })}
+          </div>
+        </motion.div>
+      )}
+
       {/* ═══ Public classrooms ═══ */}
       {publicClassrooms.length > 0 && (
         <motion.div
diff --git a/lib/i18n/course.ts b/lib/i18n/course.ts
index f3ad665da..d0db7f37f 100644
--- a/lib/i18n/course.ts
+++ b/lib/i18n/course.ts
@@ -45,6 +45,16 @@ export const courseZhCN = {
     openClassroom: '查看课堂',
     cancel: '取消',
     localClassroomHint: '仅保存在当前浏览器，不同浏览器数量可能不同',
+    publish: '发布课程',
+    unpublish: '取消发布',
+    publishedStatus: '已发布',
+    draftStatus: '草稿',
+    confirmPublish: '发布后将出现在首页公共课程区，确定发布吗？',
+    confirmUnpublish: '取消发布后将从首页移除，确定取消吗？',
+    cannotPublish: '所有章节都需绑定课堂后才能发布',
+    publishedCourses: '公共课程',
+    noPublishedCourses: '暂无公共课程',
+    chaptersReady: '已绑定',
   },
 };
 
@@ -95,5 +105,15 @@ export const courseEnUS = {
     openClassroom: 'View Classroom',
     cancel: 'Cancel',
     localClassroomHint: 'Saved in this browser only; counts may differ across browsers',
+    publish: 'Publish Course',
+    unpublish: 'Unpublish',
+    publishedStatus: 'Published',
+    draftStatus: 'Draft',
+    confirmPublish: 'This course will appear in the public area on the homepage. Publish?',
+    confirmUnpublish: 'This will remove the course from the public area. Unpublish?',
+    cannotPublish: 'All chapters must have a bound classroom before publishing',
+    publishedCourses: 'Public Courses',
+    noPublishedCourses: 'No public courses yet',
+    chaptersReady: 'bound',
   },
 };
diff --git a/lib/server/course-storage.ts b/lib/server/course-storage.ts
index 82d0d39da..d34510370 100644
--- a/lib/server/course-storage.ts
+++ b/lib/server/course-storage.ts
@@ -17,18 +17,26 @@ async function migrateCourseIfNeeded(
   filePath: string,
   raw: Record<string, unknown>,
 ): Promise<Course> {
-  if (Array.isArray((raw as unknown as Course).chapters)) return raw as unknown as Course;
-  const ids = (raw.classroomIds as string[] | undefined) ?? [];
-  const chapters: CourseChapter[] = ids.map((cid, i) => ({
-    id: nanoid(10),
-    title: `第 ${i + 1} 章`,
-    order: i,
-    classroomId: cid,
-  }));
-  const { classroomIds: _removed, ...rest } = raw;
-  const migrated = { ...(rest as Omit<Course, 'chapters'>), chapters } as Course;
-  await writeJsonFileAtomic(filePath, migrated);
-  return migrated;
+  let course: Course;
+  if (Array.isArray((raw as unknown as Course).chapters)) {
+    course = raw as unknown as Course;
+  } else {
+    const ids = (raw.classroomIds as string[] | undefined) ?? [];
+    const chapters: CourseChapter[] = ids.map((cid, i) => ({
+      id: nanoid(10),
+      title: `第 ${i + 1} 章`,
+      order: i,
+      classroomId: cid,
+    }));
+    const { classroomIds: _removed, ...rest } = raw;
+    course = { ...(rest as Omit<Course, 'chapters'>), chapters } as Course;
+  }
+  // Backfill missing status field for old courses
+  if (!course.status) {
+    course.status = 'draft';
+    await writeJsonFileAtomic(filePath, course);
+  }
+  return course;
 }
 
 export async function persistCourse(course: Course): Promise<void> {
@@ -69,6 +77,8 @@ export async function listCourses(): Promise<CourseListItem[]> {
             description: course.description,
             teacherName: course.teacherName,
             chapterCount: course.chapters.length,
+            status: course.status,
+            ...(course.publishedAt ? { publishedAt: course.publishedAt } : {}),
             createdAt: course.createdAt,
           } satisfies CourseListItem;
         } catch {
diff --git a/lib/store/course.ts b/lib/store/course.ts
index 6b94a56e2..05aef0a03 100644
--- a/lib/store/course.ts
+++ b/lib/store/course.ts
@@ -11,6 +11,8 @@ interface CourseState {
   createCourse: (data: CourseFormData) => Promise<string>;
   updateCourse: (id: string, data: Partial<CourseFormData>) => Promise<void>;
   deleteCourse: (id: string) => Promise<void>;
+  publishCourse: (id: string) => Promise<void>;
+  unpublishCourse: (id: string) => Promise<void>;
   addChapter: (courseId: string, title: string, description: string | null) => Promise<void>;
   updateChapter: (courseId: string, chapterId: string, updates: ChapterUpdates) => Promise<void>;
   removeChapter: (courseId: string, chapterId: string) => Promise<void>;
@@ -54,6 +56,7 @@ export const useCourseStore = create<CourseState>((set, get) => ({
       ...data,
       chapters: [],
       id,
+      status: 'draft',
       createdAt: new Date().toISOString(),
       updatedAt: new Date().toISOString(),
     };
@@ -86,6 +89,38 @@ export const useCourseStore = create<CourseState>((set, get) => ({
     await get().fetchCourses();
   },
 
+  publishCourse: async (id) => {
+    const course = get().currentCourse;
+    if (!course || course.id !== id) return;
+    const updated: Course = {
+      ...course,
+      status: 'published',
+      publishedAt: course.publishedAt ?? new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    };
+    await fetch('/api/course', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(updated),
+    });
+    set({ currentCourse: updated });
+    await get().fetchCourses();
+  },
+
+  unpublishCourse: async (id) => {
+    const course = get().currentCourse;
+    if (!course || course.id !== id) return;
+    const { publishedAt: _removed, ...rest } = course;
+    const updated: Course = { ...rest, status: 'draft', updatedAt: new Date().toISOString() };
+    await fetch('/api/course', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(updated),
+    });
+    set({ currentCourse: updated });
+    await get().fetchCourses();
+  },
+
   addChapter: async (courseId, title, description) => {
     await fetch('/api/course/chapters', {
       method: 'POST',
diff --git a/lib/types/course.ts b/lib/types/course.ts
index 4c80f207b..175fa21e4 100644
--- a/lib/types/course.ts
+++ b/lib/types/course.ts
@@ -44,6 +44,8 @@ export interface Course {
   description: string;
   teacherName: string;
   chapters: CourseChapter[];
+  status: 'draft' | 'published';
+  publishedAt?: string;
   createdAt: string;
   updatedAt: string;
 }

From 6048541657b3a02c6cbcfd1400e5d96a03e0c9e3 Mon Sep 17 00:00:00 2001
From: zhenzhu143321 <hxcisunli@126.com>
Date: Sun, 29 Mar 2026 21:16:54 +0800
Subject: [PATCH 21/30] =?UTF-8?q?feat:=20course=20publish=20hardening=20?=
 =?UTF-8?q?=E2=80=94=20server=20validation,=20toast=20feedback,=20classroo?=
 =?UTF-8?q?m=20section=20collapse?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- POST /api/course now validates all chapters have classroomId when status=published
- publishCourse/unpublishCourse check res.ok and throw on failure
- Course detail page shows success/failure toast on publish/unpublish
- Homepage: classrooms section is collapsible, defaults collapsed when published courses exist

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 app/api/course/route.ts  | 11 ++++++++-
 app/course/[id]/page.tsx | 14 +++++++++--
 app/page.tsx             | 51 +++++++++++++++++++++++++++-------------
 lib/i18n/course.ts       |  8 +++++++
 lib/store/course.ts      |  6 +++--
 5 files changed, 69 insertions(+), 21 deletions(-)

diff --git a/app/api/course/route.ts b/app/api/course/route.ts
index 9cde8429d..a66aa2aa7 100644
--- a/app/api/course/route.ts
+++ b/app/api/course/route.ts
@@ -1,6 +1,6 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { listCourses, readCourse, persistCourse, deleteCourse } from '@/lib/server/course-storage';
-import type { Course } from '@/lib/types/course';
+import type { Course, CourseChapter } from '@/lib/types/course';
 
 export async function GET(req: NextRequest) {
   try {
@@ -30,6 +30,15 @@ export async function POST(req: NextRequest) {
     if (!body.id || !body.name) {
       return NextResponse.json({ error: 'Missing required fields' }, { status: 400 });
     }
+    if (body.status === 'published') {
+      if (!body.chapters || body.chapters.length === 0) {
+        return NextResponse.json({ error: 'Course must have at least one chapter to publish' }, { status: 400 });
+      }
+      const unbound = body.chapters.filter((ch: CourseChapter) => !ch.classroomId);
+      if (unbound.length > 0) {
+        return NextResponse.json({ error: 'All chapters must have a bound classroom to publish' }, { status: 400 });
+      }
+    }
     await persistCourse(body);
     return NextResponse.json({ success: true });
   } catch (error) {
diff --git a/app/course/[id]/page.tsx b/app/course/[id]/page.tsx
index 5db9a0acf..2f1ae3257 100644
--- a/app/course/[id]/page.tsx
+++ b/app/course/[id]/page.tsx
@@ -27,6 +27,7 @@ import {
 } from '@/components/ui/alert-dialog';
 import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip';
 import { ArrowLeft, Pencil, BookOpen, Building2, GraduationCap, User, Globe, GlobeLock } from 'lucide-react';
+import { toast } from 'sonner';
 
 type PublishDialogMode = 'publish' | 'unpublish' | null;
 
@@ -130,8 +131,17 @@ export default function CourseDetailPage({ params }: { params: Promise<{ id: str
 
   const handlePublishConfirm = async () => {
     if (!courseId) return;
-    if (publishDialog === 'publish') await publishCourse(courseId);
-    else if (publishDialog === 'unpublish') await unpublishCourse(courseId);
+    try {
+      if (publishDialog === 'publish') {
+        await publishCourse(courseId);
+        toast.success(t('course.publishSuccess'));
+      } else if (publishDialog === 'unpublish') {
+        await unpublishCourse(courseId);
+        toast.success(t('course.unpublishSuccess'));
+      }
+    } catch {
+      toast.error(publishDialog === 'publish' ? t('course.publishFailed') : t('course.unpublishFailed'));
+    }
     setPublishDialog(null);
   };
 
diff --git a/app/page.tsx b/app/page.tsx
index 435dc1218..c3912cf04 100644
--- a/app/page.tsx
+++ b/app/page.tsx
@@ -149,6 +149,7 @@ function HomePage() {
   const [publicClassrooms, setPublicClassrooms] = useState<PublicClassroomItem[]>([]);
   const [publicThumbnails, setPublicThumbnails] = useState<Record<string, Slide>>({});
   const [publishedCourses, setPublishedCourses] = useState<CourseListItem[]>([]);
+  const [classroomsExpanded, setClassroomsExpanded] = useState(false);
   const [pendingDeleteId, setPendingDeleteId] = useState<string | null>(null);
   const toolbarRef = useRef<HTMLDivElement>(null);
   const textareaRef = useRef<HTMLTextAreaElement>(null);
@@ -222,6 +223,7 @@ function HomePage() {
       }
       if (Array.isArray(publishedCourseData)) {
         setPublishedCourses(publishedCourseData);
+        if (publishedCourseData.length === 0) setClassroomsExpanded(true);
       }
     }).catch(() => {});
   }, []);
@@ -759,32 +761,49 @@ function HomePage() {
           transition={{ delay: 0.45 }}
           className="relative z-10 mt-10 w-full max-w-6xl flex flex-col items-center"
         >
-          <div className="w-full flex items-center gap-4 py-2">
+          <button
+            onClick={() => setClassroomsExpanded((v) => !v)}
+            className="w-full flex items-center gap-4 py-2 cursor-pointer group"
+          >
             <div className="flex-1 h-px bg-border/40" />
-            <span className="shrink-0 flex items-center gap-2 text-[13px] text-muted-foreground/60 select-none">
+            <span className="shrink-0 flex items-center gap-2 text-[13px] text-muted-foreground/60 select-none group-hover:text-muted-foreground/80 transition-colors">
               <Globe className="size-3.5" />
               {t('classroom.publicClassrooms')}
               <span className="text-[11px] tabular-nums opacity-60">{publicClassrooms.length}</span>
+              {classroomsExpanded ? <ChevronUp className="size-3" /> : <ChevronDown className="size-3" />}
             </span>
             <div className="flex-1 h-px bg-border/40" />
-          </div>
+          </button>
 
-          <div className="pt-8 grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-x-5 gap-y-8 w-full">
-            {publicClassrooms.map((pc, i) => (
+          <AnimatePresence>
+            {classroomsExpanded && (
               <motion.div
-                key={pc.id}
-                initial={{ opacity: 0, y: 16 }}
-                animate={{ opacity: 1, y: 0 }}
-                transition={{ delay: i * 0.04, duration: 0.35, ease: 'easeOut' }}
+                key="classrooms-grid"
+                initial={{ opacity: 0, height: 0 }}
+                animate={{ opacity: 1, height: 'auto' }}
+                exit={{ opacity: 0, height: 0 }}
+                transition={{ duration: 0.25, ease: 'easeOut' }}
+                className="w-full overflow-hidden"
               >
-                <PublicClassroomCard
-                  classroom={pc}
-                  slide={publicThumbnails[pc.id]}
-                  onClick={() => router.push(`/classroom/${pc.id}`)}
-                />
+                <div className="pt-8 grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-x-5 gap-y-8 w-full">
+                  {publicClassrooms.map((pc, i) => (
+                    <motion.div
+                      key={pc.id}
+                      initial={{ opacity: 0, y: 16 }}
+                      animate={{ opacity: 1, y: 0 }}
+                      transition={{ delay: i * 0.04, duration: 0.35, ease: 'easeOut' }}
+                    >
+                      <PublicClassroomCard
+                        classroom={pc}
+                        slide={publicThumbnails[pc.id]}
+                        onClick={() => router.push(`/classroom/${pc.id}`)}
+                      />
+                    </motion.div>
+                  ))}
+                </div>
               </motion.div>
-            ))}
-          </div>
+            )}
+          </AnimatePresence>
         </motion.div>
       )}
 
diff --git a/lib/i18n/course.ts b/lib/i18n/course.ts
index d0db7f37f..fff124b89 100644
--- a/lib/i18n/course.ts
+++ b/lib/i18n/course.ts
@@ -55,6 +55,10 @@ export const courseZhCN = {
     publishedCourses: '公共课程',
     noPublishedCourses: '暂无公共课程',
     chaptersReady: '已绑定',
+    publishSuccess: '课程已发布',
+    publishFailed: '发布失败',
+    unpublishSuccess: '已取消发布',
+    unpublishFailed: '取消发布失败',
   },
 };
 
@@ -115,5 +119,9 @@ export const courseEnUS = {
     publishedCourses: 'Public Courses',
     noPublishedCourses: 'No public courses yet',
     chaptersReady: 'bound',
+    publishSuccess: 'Course published',
+    publishFailed: 'Failed to publish',
+    unpublishSuccess: 'Course unpublished',
+    unpublishFailed: 'Failed to unpublish',
   },
 };
diff --git a/lib/store/course.ts b/lib/store/course.ts
index 05aef0a03..64d4992e0 100644
--- a/lib/store/course.ts
+++ b/lib/store/course.ts
@@ -98,11 +98,12 @@ export const useCourseStore = create<CourseState>((set, get) => ({
       publishedAt: course.publishedAt ?? new Date().toISOString(),
       updatedAt: new Date().toISOString(),
     };
-    await fetch('/api/course', {
+    const res = await fetch('/api/course', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify(updated),
     });
+    if (!res.ok) throw new Error('Publish failed');
     set({ currentCourse: updated });
     await get().fetchCourses();
   },
@@ -112,11 +113,12 @@ export const useCourseStore = create<CourseState>((set, get) => ({
     if (!course || course.id !== id) return;
     const { publishedAt: _removed, ...rest } = course;
     const updated: Course = { ...rest, status: 'draft', updatedAt: new Date().toISOString() };
-    await fetch('/api/course', {
+    const res = await fetch('/api/course', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify(updated),
     });
+    if (!res.ok) throw new Error('Unpublish failed');
     set({ currentCourse: updated });
     await get().fetchCourses();
   },

From 97091d12fa358fab16d7b726e845b91559c1f2be Mon Sep 17 00:00:00 2001
From: zhenzhu143321 <hxcisunli@126.com>
Date: Mon, 30 Mar 2026 06:16:09 +0800
Subject: [PATCH 22/30] refactor: deduplicate COVERS/course-card logic, fix
 classroomsExpanded default

- Extract COURSE_COVERS constant and getCourseGradient() helper to module level
  (was copy-pasted in 2 map callbacks with ~50 lines each)
- Extract saveCourse() helper in store; publishCourse/unpublishCourse now share it
- Remove redundant CourseChapter type annotation in API route (inferred from Course)
- Fix classroomsExpanded: default true, collapse only after published courses load

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 app/api/course/route.ts |  4 ++--
 app/page.tsx            | 52 ++++++++++++++++-------------------------
 lib/store/course.ts     | 23 +++++++++---------
 3 files changed, 33 insertions(+), 46 deletions(-)

diff --git a/app/api/course/route.ts b/app/api/course/route.ts
index a66aa2aa7..4ec5ec9b6 100644
--- a/app/api/course/route.ts
+++ b/app/api/course/route.ts
@@ -1,6 +1,6 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { listCourses, readCourse, persistCourse, deleteCourse } from '@/lib/server/course-storage';
-import type { Course, CourseChapter } from '@/lib/types/course';
+import type { Course } from '@/lib/types/course';
 
 export async function GET(req: NextRequest) {
   try {
@@ -34,7 +34,7 @@ export async function POST(req: NextRequest) {
       if (!body.chapters || body.chapters.length === 0) {
         return NextResponse.json({ error: 'Course must have at least one chapter to publish' }, { status: 400 });
       }
-      const unbound = body.chapters.filter((ch: CourseChapter) => !ch.classroomId);
+      const unbound = body.chapters.filter((ch) => !ch.classroomId);
       if (unbound.length > 0) {
         return NextResponse.json({ error: 'All chapters must have a bound classroom to publish' }, { status: 400 });
       }
diff --git a/app/page.tsx b/app/page.tsx
index c3912cf04..418062a10 100644
--- a/app/page.tsx
+++ b/app/page.tsx
@@ -82,6 +82,22 @@ const initialFormState: FormState = {
   webSearch: false,
 };
 
+const COURSE_COVERS = [
+  { from: '#7c3aed', to: '#a78bfa', dot: 'rgba(255,255,255,0.15)' },
+  { from: '#0ea5e9', to: '#38bdf8', dot: 'rgba(255,255,255,0.15)' },
+  { from: '#059669', to: '#34d399', dot: 'rgba(255,255,255,0.15)' },
+  { from: '#e11d48', to: '#fb7185', dot: 'rgba(255,255,255,0.15)' },
+  { from: '#d97706', to: '#fbbf24', dot: 'rgba(255,255,255,0.15)' },
+  { from: '#0d9488', to: '#2dd4bf', dot: 'rgba(255,255,255,0.15)' },
+  { from: '#c026d3', to: '#e879f9', dot: 'rgba(255,255,255,0.15)' },
+  { from: '#ea580c', to: '#fb923c', dot: 'rgba(255,255,255,0.15)' },
+] as const;
+
+function getCourseGradient(courseId: string) {
+  const hash = courseId.split('').reduce((a, c) => a + c.charCodeAt(0), 0);
+  return COURSE_COVERS[hash % COURSE_COVERS.length];
+}
+
 function HomePage() {
   const { t, locale, setLocale } = useI18n();
   const { theme, setTheme } = useTheme();
@@ -149,7 +165,7 @@ function HomePage() {
   const [publicClassrooms, setPublicClassrooms] = useState<PublicClassroomItem[]>([]);
   const [publicThumbnails, setPublicThumbnails] = useState<Record<string, Slide>>({});
   const [publishedCourses, setPublishedCourses] = useState<CourseListItem[]>([]);
-  const [classroomsExpanded, setClassroomsExpanded] = useState(false);
+  const [classroomsExpanded, setClassroomsExpanded] = useState(true);
   const [pendingDeleteId, setPendingDeleteId] = useState<string | null>(null);
   const toolbarRef = useRef<HTMLDivElement>(null);
   const textareaRef = useRef<HTMLTextAreaElement>(null);
@@ -223,7 +239,7 @@ function HomePage() {
       }
       if (Array.isArray(publishedCourseData)) {
         setPublishedCourses(publishedCourseData);
-        if (publishedCourseData.length === 0) setClassroomsExpanded(true);
+        if (publishedCourseData.length > 0) setClassroomsExpanded(false);
       }
     }).catch(() => {});
   }, []);
@@ -695,18 +711,7 @@ function HomePage() {
 
           <div className="pt-4 grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-4 w-full">
             {publishedCourses.map((course, i) => {
-              const COVERS = [
-                { from: '#7c3aed', to: '#a78bfa', dot: 'rgba(255,255,255,0.15)' },
-                { from: '#0ea5e9', to: '#38bdf8', dot: 'rgba(255,255,255,0.15)' },
-                { from: '#059669', to: '#34d399', dot: 'rgba(255,255,255,0.15)' },
-                { from: '#e11d48', to: '#fb7185', dot: 'rgba(255,255,255,0.15)' },
-                { from: '#d97706', to: '#fbbf24', dot: 'rgba(255,255,255,0.15)' },
-                { from: '#0d9488', to: '#2dd4bf', dot: 'rgba(255,255,255,0.15)' },
-                { from: '#c026d3', to: '#e879f9', dot: 'rgba(255,255,255,0.15)' },
-                { from: '#ea580c', to: '#fb923c', dot: 'rgba(255,255,255,0.15)' },
-              ];
-              const hash = course.id.split('').reduce((a, c) => a + c.charCodeAt(0), 0);
-              const cover = COVERS[hash % COVERS.length];
+              const cover = getCourseGradient(course.id);
               return (
                 <motion.div
                   key={course.id}
@@ -854,19 +859,7 @@ function HomePage() {
               ) : (
                 <div className="grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-4">
                   {courses.map((course) => {
-                    // Deterministic accent per course id
-                    const COVERS = [
-                      { from: '#7c3aed', to: '#a78bfa', dot: 'rgba(255,255,255,0.15)' },
-                      { from: '#0ea5e9', to: '#38bdf8', dot: 'rgba(255,255,255,0.15)' },
-                      { from: '#059669', to: '#34d399', dot: 'rgba(255,255,255,0.15)' },
-                      { from: '#e11d48', to: '#fb7185', dot: 'rgba(255,255,255,0.15)' },
-                      { from: '#d97706', to: '#fbbf24', dot: 'rgba(255,255,255,0.15)' },
-                      { from: '#0d9488', to: '#2dd4bf', dot: 'rgba(255,255,255,0.15)' },
-                      { from: '#c026d3', to: '#e879f9', dot: 'rgba(255,255,255,0.15)' },
-                      { from: '#ea580c', to: '#fb923c', dot: 'rgba(255,255,255,0.15)' },
-                    ];
-                    const hash = course.id.split('').reduce((a, c) => a + c.charCodeAt(0), 0);
-                    const cover = COVERS[hash % COVERS.length];
+                    const cover = getCourseGradient(course.id);
                     return (
                       <div
                         key={course.id}
@@ -874,26 +867,21 @@ function HomePage() {
                         className="group rounded-2xl overflow-hidden cursor-pointer border border-white/10 shadow-md hover:shadow-xl hover:-translate-y-1 transition-all duration-250 flex flex-col"
                         style={{ minHeight: '200px' }}
                       >
-                        {/* Cover area — compact with course name */}
                         <div
                           className="relative flex-shrink-0 h-[88px] flex flex-col justify-between px-3 pt-2.5 pb-2.5 overflow-hidden"
                           style={{ background: `linear-gradient(135deg, ${cover.from}, ${cover.to})` }}
                         >
-                          {/* Decorative circles */}
                           <div className="absolute -top-4 -right-4 w-20 h-20 rounded-full" style={{ background: cover.dot }} />
                           <div className="absolute -bottom-5 -left-3 w-24 h-24 rounded-full" style={{ background: cover.dot }} />
-                          {/* Chapter badge */}
                           <span className="relative z-10 inline-flex items-center gap-1 text-[10px] font-semibold bg-white/20 backdrop-blur-sm text-white px-2 py-0.5 rounded-full border border-white/30 self-start">
                             <BookOpen className="size-2.5" />
                             {course.chapterCount} {t('course.chapter')}
                           </span>
-                          {/* Course name on gradient */}
                           <h3 className="relative z-10 text-[12px] font-bold text-white leading-snug line-clamp-1 tracking-tight drop-shadow-sm">
                             {course.name}
                           </h3>
                         </div>
 
-                        {/* Info area — taller, shows description */}
                         <div className="flex-1 flex flex-col bg-white dark:bg-slate-900 px-3 pt-2.5 pb-3 min-h-0">
                           {course.description ? (
                             <p className="text-[11px] text-muted-foreground line-clamp-3 mb-auto leading-relaxed">
diff --git a/lib/store/course.ts b/lib/store/course.ts
index 64d4992e0..df75eb9f2 100644
--- a/lib/store/course.ts
+++ b/lib/store/course.ts
@@ -19,6 +19,15 @@ interface CourseState {
   reorderChapters: (courseId: string, chapterIds: string[]) => Promise<void>;
 }
 
+async function saveCourse(course: Course): Promise<void> {
+  const res = await fetch('/api/course', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(course),
+  });
+  if (!res.ok) throw new Error('Failed to save course');
+}
+
 export const useCourseStore = create<CourseState>((set, get) => ({
   courses: [],
   currentCourse: null,
@@ -98,12 +107,7 @@ export const useCourseStore = create<CourseState>((set, get) => ({
       publishedAt: course.publishedAt ?? new Date().toISOString(),
       updatedAt: new Date().toISOString(),
     };
-    const res = await fetch('/api/course', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(updated),
-    });
-    if (!res.ok) throw new Error('Publish failed');
+    await saveCourse(updated);
     set({ currentCourse: updated });
     await get().fetchCourses();
   },
@@ -113,12 +117,7 @@ export const useCourseStore = create<CourseState>((set, get) => ({
     if (!course || course.id !== id) return;
     const { publishedAt: _removed, ...rest } = course;
     const updated: Course = { ...rest, status: 'draft', updatedAt: new Date().toISOString() };
-    const res = await fetch('/api/course', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(updated),
-    });
-    if (!res.ok) throw new Error('Unpublish failed');
+    await saveCourse(updated);
     set({ currentCourse: updated });
     await get().fetchCourses();
   },

From 3a618fb070b3c7716dacd1c1618a4bd010236821 Mon Sep 17 00:00:00 2001
From: zhenzhu143321 <hxcisunli@126.com>
Date: Tue, 31 Mar 2026 17:51:46 +0800
Subject: [PATCH 23/30] fix: resolve media/TTS race conditions on published
 classroom playback

Browsing a published classroom triggered unnecessary POST /api/generate/image
requests because generateMediaForOutlines ran before prefillMediaCache finished
populating the Zustand store. Similarly, clicking Play before prefill completed
caused TTS to fall back to a ~100s reading timer instead of actual audio.

- Extract shared prefill promise into lib/media/prefill-state.ts (getter/setter)
- Chain generateMediaForOutlines after getPrefillPromise() in page.tsx
- Await getPrefillPromise() in stage.tsx handlePlayPause before engine.start()
- Remove unused classroomId param from backfillMissingTTS

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 app/classroom/[id]/page.tsx | 20 ++++++++++----------
 components/stage.tsx        |  3 +++
 lib/media/prefill-state.ts  | 13 +++++++++++++
 3 files changed, 26 insertions(+), 10 deletions(-)
 create mode 100644 lib/media/prefill-state.ts

diff --git a/app/classroom/[id]/page.tsx b/app/classroom/[id]/page.tsx
index 4b120e9d0..def07632a 100644
--- a/app/classroom/[id]/page.tsx
+++ b/app/classroom/[id]/page.tsx
@@ -14,12 +14,10 @@ import { useSettingsStore } from '@/lib/store/settings';
 import { createLogger } from '@/lib/logger';
 import { MediaStageProvider } from '@/lib/contexts/media-stage-context';
 import { generateMediaForOutlines } from '@/lib/media/media-orchestrator';
+import { setPrefillPromise, getPrefillPromise } from '@/lib/media/prefill-state';
 
 const log = createLogger('Classroom');
 
-// Module-level promise so backfillMissingTTS can wait for prefill to finish
-let prefillPromise: Promise<void> = Promise.resolve();
-
 /**
  * Pre-fill local IndexedDB with cached media from the server.
  * Runs async, does not block page rendering.
@@ -126,12 +124,12 @@ async function prefillMediaCache(classroomId: string): Promise<void> {
  * 2. Immediately persists to IndexedDB (not relying on 500ms debounce)
  * 3. Updates server-side classroom.json so audioIds survive across browsers
  */
-async function backfillMissingTTS(classroomId: string): Promise<void> {
+async function backfillMissingTTS(): Promise<void> {
   const settings = useSettingsStore.getState();
   if (!settings.ttsEnabled || settings.ttsProviderId === 'browser-native-tts') return;
 
   // Wait for prefill to finish so we don't regenerate already-cached TTS
-  await prefillPromise;
+  await getPrefillPromise();
 
   const scenes = useStageStore.getState().scenes;
   if (!scenes || scenes.length === 0) return;
@@ -269,9 +267,9 @@ export default function ClassroomDetailPage() {
       await useMediaGenerationStore.getState().restoreFromDB(classroomId);
 
       // Pre-fill media cache from server (fire-and-forget, backfill awaits this promise)
-      prefillPromise = prefillMediaCache(classroomId).catch((err) => {
+      setPrefillPromise(prefillMediaCache(classroomId).catch((err) => {
         log.warn('Media cache prefill failed:', err);
-      });
+      }));
 
       // Restore generated agents for this stage
       const { loadGeneratedAgentsForStage } = await import('@/lib/orchestration/registry/store');
@@ -356,15 +354,17 @@ export default function ClassroomDetailPage() {
       // Resume media generation for any tasks not yet in IndexedDB.
       // generateMediaForOutlines skips already-completed tasks automatically.
       generationStartedRef.current = true;
-      generateMediaForOutlines(outlines, stage.id).catch((err) => {
-        log.warn('[Classroom] Media generation resume error:', err);
+      getPrefillPromise().then(() => {
+        generateMediaForOutlines(outlines, stage.id).catch((err) => {
+          log.warn('[Classroom] Media generation resume error:', err);
+        });
       });
     }
 
     // Backfill TTS for completed scenes that lack audio (e.g. API-generated classrooms)
     if (stage && !backfillStartedRef.current) {
       backfillStartedRef.current = true;
-      backfillMissingTTS(stage.id).catch((err) => {
+      backfillMissingTTS().catch((err) => {
         log.warn('[Classroom] TTS backfill error:', err);
       });
     }
diff --git a/components/stage.tsx b/components/stage.tsx
index d9025ec04..c193e3f3e 100644
--- a/components/stage.tsx
+++ b/components/stage.tsx
@@ -29,6 +29,7 @@ import {
 } from '@/components/ui/alert-dialog';
 import { AlertTriangle } from 'lucide-react';
 import { VisuallyHidden } from 'radix-ui';
+import { getPrefillPromise } from '@/lib/media/prefill-state';
 
 /**
  * Stage Component
@@ -585,6 +586,8 @@ export function Stage({
         const sessionId = await chatAreaRef.current.startLecture(currentScene.id);
         lectureSessionIdRef.current = sessionId;
       }
+      // Wait for media prefill to finish so TTS audio is in IndexedDB before playback starts
+      await getPrefillPromise();
       if (wasCompleted) {
         // Restart from beginning (user clicked restart after completion)
         lectureActionCounterRef.current = 0;
diff --git a/lib/media/prefill-state.ts b/lib/media/prefill-state.ts
new file mode 100644
index 000000000..3c330b59c
--- /dev/null
+++ b/lib/media/prefill-state.ts
@@ -0,0 +1,13 @@
+/**
+ * Shared prefill promise — set by classroom page when prefillMediaCache starts,
+ * awaited by playback engine before starting so TTS audio is in IndexedDB first.
+ */
+let _prefillPromise: Promise<void> = Promise.resolve();
+
+export function setPrefillPromise(p: Promise<void>): void {
+  _prefillPromise = p;
+}
+
+export function getPrefillPromise(): Promise<void> {
+  return _prefillPromise;
+}

From 087ee7e21fd17c71d7ac7855cbdefe8c8b43628b Mon Sep 17 00:00:00 2001
From: zhenzhu143321 <hxcisunli@126.com>
Date: Tue, 31 Mar 2026 17:52:56 +0800
Subject: [PATCH 24/30] =?UTF-8?q?refactor:=20course=20publish=20model=20?=
 =?UTF-8?q?=E2=80=94=20partial=20binding,=20homepage=20cleanup,=20badge=20?=
 =?UTF-8?q?semantics?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Remove "Public Classrooms" section from homepage (-169 lines); only published
  courses appear publicly
- Change publish rule: at least 1 chapter bound (was: all chapters bound),
  both server and client validation updated
- Rename ClassroomMeta.published → .ready to clarify semantics (classroom
  exists on server ≠ "published")
- Update chapter badges: "已就绪/Ready" and "待绑定/Pending" replace
  "已发布/未发布" wording
- Update i18n strings (zh-CN + en-US) for new publish flow and binding dialog

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 app/api/course/route.ts            |   6 +-
 app/course/[id]/page.tsx           |   4 +-
 app/page.tsx                       | 169 +----------------------------
 components/course/chapter-list.tsx |  23 ++--
 lib/i18n/course.ts                 |  22 ++--
 lib/types/course.ts                |   2 +-
 6 files changed, 30 insertions(+), 196 deletions(-)

diff --git a/app/api/course/route.ts b/app/api/course/route.ts
index 4ec5ec9b6..dde2cca5e 100644
--- a/app/api/course/route.ts
+++ b/app/api/course/route.ts
@@ -34,9 +34,9 @@ export async function POST(req: NextRequest) {
       if (!body.chapters || body.chapters.length === 0) {
         return NextResponse.json({ error: 'Course must have at least one chapter to publish' }, { status: 400 });
       }
-      const unbound = body.chapters.filter((ch) => !ch.classroomId);
-      if (unbound.length > 0) {
-        return NextResponse.json({ error: 'All chapters must have a bound classroom to publish' }, { status: 400 });
+      const bound = body.chapters.filter((ch) => ch.classroomId);
+      if (bound.length === 0) {
+        return NextResponse.json({ error: 'At least one chapter must have a bound classroom to publish' }, { status: 400 });
       }
     }
     await persistCourse(body);
diff --git a/app/course/[id]/page.tsx b/app/course/[id]/page.tsx
index 2f1ae3257..6041ebc77 100644
--- a/app/course/[id]/page.tsx
+++ b/app/course/[id]/page.tsx
@@ -68,7 +68,7 @@ export default function CourseDetailPage({ params }: { params: Promise<{ id: str
             .filter((c) => idSet.has(c.id))
             .map((c): [string, ClassroomMeta] => [
               c.id,
-              { name: c.name || c.id, sceneCount: c.sceneCount ?? 0, published: true },
+              { name: c.name || c.id, sceneCount: c.sceneCount ?? 0, ready: true },
             ]),
         ),
       );
@@ -104,7 +104,7 @@ export default function CourseDetailPage({ params }: { params: Promise<{ id: str
 
   const canPublish =
     currentCourse.chapters.length > 0 &&
-    currentCourse.chapters.every((ch) => !!ch.classroomId);
+    currentCourse.chapters.some((ch) => !!ch.classroomId);
   const boundCount = currentCourse.chapters.filter((ch) => !!ch.classroomId).length;
   const totalCount = currentCourse.chapters.length;
   const isPublished = currentCourse.status === 'published';
diff --git a/app/page.tsx b/app/page.tsx
index 418062a10..d552029ec 100644
--- a/app/page.tsx
+++ b/app/page.tsx
@@ -58,16 +58,6 @@ const WEB_SEARCH_STORAGE_KEY = 'webSearchEnabled';
 const LANGUAGE_STORAGE_KEY = 'generationLanguage';
 const RECENT_OPEN_STORAGE_KEY = 'recentClassroomsOpen';
 
-interface PublicClassroomItem {
-  id: string;
-  name: string;
-  description?: string;
-  language?: string;
-  sceneCount: number;
-  createdAt: string;
-  firstSlide?: Slide | null;
-}
-
 interface FormState {
   pdfFile: File | null;
   requirement: string;
@@ -162,10 +152,7 @@ function HomePage() {
   const [error, setError] = useState<string | null>(null);
   const [classrooms, setClassrooms] = useState<StageListItem[]>([]);
   const [thumbnails, setThumbnails] = useState<Record<string, Slide>>({});
-  const [publicClassrooms, setPublicClassrooms] = useState<PublicClassroomItem[]>([]);
-  const [publicThumbnails, setPublicThumbnails] = useState<Record<string, Slide>>({});
   const [publishedCourses, setPublishedCourses] = useState<CourseListItem[]>([]);
-  const [classroomsExpanded, setClassroomsExpanded] = useState(true);
   const [pendingDeleteId, setPendingDeleteId] = useState<string | null>(null);
   const toolbarRef = useRef<HTMLDivElement>(null);
   const textareaRef = useRef<HTMLTextAreaElement>(null);
@@ -218,28 +205,10 @@ function HomePage() {
     Promise.all([
       loadClassrooms(),
       fetchCourses(),
-      fetch('/api/classroom').then(res => res.json()),
       fetch('/api/course?status=published').then(res => res.json()),
-    ]).then(([, , publicData, publishedCourseData]) => {
-      if (publicData.success && publicData.classrooms) {
-        setPublicClassrooms(publicData.classrooms);
-        const thumbs: Record<string, Slide> = {};
-        for (const c of publicData.classrooms) {
-          if (c.firstSlide) {
-            const slide = structuredClone(c.firstSlide);
-            for (const el of slide.elements as Array<{ type: string; src?: string }>) {
-              if (el.type === 'image' && el.src && /^gen_(img|vid)_[\w-]+$/i.test(el.src)) {
-                el.src = `/api/classroom/media?id=${encodeURIComponent(c.id)}&file=${encodeURIComponent(el.src)}`;
-              }
-            }
-            thumbs[c.id] = slide;
-          }
-        }
-        setPublicThumbnails(thumbs);
-      }
+    ]).then(([, , publishedCourseData]) => {
       if (Array.isArray(publishedCourseData)) {
         setPublishedCourses(publishedCourseData);
-        if (publishedCourseData.length > 0) setClassroomsExpanded(false);
       }
     }).catch(() => {});
   }, []);
@@ -573,7 +542,7 @@ function HomePage() {
         transition={{ duration: 0.6, ease: 'easeOut' }}
         className={cn(
           'relative z-20 w-full max-w-[800px] flex flex-col items-center',
-          classrooms.length === 0 && publicClassrooms.length === 0 ? 'justify-center min-h-[calc(100dvh-8rem)]' : 'mt-[10vh]',
+          classrooms.length === 0 ? 'justify-center min-h-[calc(100dvh-8rem)]' : 'mt-[10vh]',
         )}
       >
         {/* ── Logo ── */}
@@ -758,60 +727,6 @@ function HomePage() {
         </motion.div>
       )}
 
-      {/* ═══ Public classrooms ═══ */}
-      {publicClassrooms.length > 0 && (
-        <motion.div
-          initial={{ opacity: 0 }}
-          animate={{ opacity: 1 }}
-          transition={{ delay: 0.45 }}
-          className="relative z-10 mt-10 w-full max-w-6xl flex flex-col items-center"
-        >
-          <button
-            onClick={() => setClassroomsExpanded((v) => !v)}
-            className="w-full flex items-center gap-4 py-2 cursor-pointer group"
-          >
-            <div className="flex-1 h-px bg-border/40" />
-            <span className="shrink-0 flex items-center gap-2 text-[13px] text-muted-foreground/60 select-none group-hover:text-muted-foreground/80 transition-colors">
-              <Globe className="size-3.5" />
-              {t('classroom.publicClassrooms')}
-              <span className="text-[11px] tabular-nums opacity-60">{publicClassrooms.length}</span>
-              {classroomsExpanded ? <ChevronUp className="size-3" /> : <ChevronDown className="size-3" />}
-            </span>
-            <div className="flex-1 h-px bg-border/40" />
-          </button>
-
-          <AnimatePresence>
-            {classroomsExpanded && (
-              <motion.div
-                key="classrooms-grid"
-                initial={{ opacity: 0, height: 0 }}
-                animate={{ opacity: 1, height: 'auto' }}
-                exit={{ opacity: 0, height: 0 }}
-                transition={{ duration: 0.25, ease: 'easeOut' }}
-                className="w-full overflow-hidden"
-              >
-                <div className="pt-8 grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-x-5 gap-y-8 w-full">
-                  {publicClassrooms.map((pc, i) => (
-                    <motion.div
-                      key={pc.id}
-                      initial={{ opacity: 0, y: 16 }}
-                      animate={{ opacity: 1, y: 0 }}
-                      transition={{ delay: i * 0.04, duration: 0.35, ease: 'easeOut' }}
-                    >
-                      <PublicClassroomCard
-                        classroom={pc}
-                        slide={publicThumbnails[pc.id]}
-                        onClick={() => router.push(`/classroom/${pc.id}`)}
-                      />
-                    </motion.div>
-                  ))}
-                </div>
-              </motion.div>
-            )}
-          </AnimatePresence>
-        </motion.div>
-      )}
-
       {/* ═══ Recent classrooms — collapsible ═══ */}
       {(classrooms.length > 0 || courses.length > 0) && (
         <motion.div
@@ -1281,86 +1196,6 @@ function GreetingBar() {
   );
 }
 
-// ─── Public Classroom Card — no delete button ───────────────────
-function PublicClassroomCard({
-  classroom,
-  slide,
-  onClick,
-}: {
-  classroom: PublicClassroomItem;
-  slide?: Slide;
-  onClick: () => void;
-}) {
-  const { t } = useI18n();
-  const thumbRef = useRef<HTMLDivElement>(null);
-  const [thumbWidth, setThumbWidth] = useState(0);
-
-  useEffect(() => {
-    const el = thumbRef.current;
-    if (!el) return;
-    const ro = new ResizeObserver(([entry]) => {
-      setThumbWidth(Math.round(entry.contentRect.width));
-    });
-    ro.observe(el);
-    return () => ro.disconnect();
-  }, []);
-
-  const formatCreatedAt = (iso: string) => {
-    const date = new Date(iso);
-    const now = new Date();
-    const diffDays = Math.floor((now.getTime() - date.getTime()) / (1000 * 60 * 60 * 24));
-    if (diffDays === 0) return t('classroom.today');
-    if (diffDays === 1) return t('classroom.yesterday');
-    if (diffDays === 2) return t('classroom.twoDaysAgo');
-    if (diffDays < 7) return `${diffDays} ${t('classroom.daysAgo')}`;
-    return date.toLocaleDateString();
-  };
-
-  return (
-    <div className="group cursor-pointer" onClick={onClick}>
-      <div
-        ref={thumbRef}
-        className="relative w-full aspect-[16/9] rounded-2xl bg-slate-100 dark:bg-slate-800/80 overflow-hidden transition-transform duration-200 group-hover:scale-[1.02]"
-      >
-        {slide && thumbWidth > 0 ? (
-          <ThumbnailSlide
-            slide={slide}
-            size={thumbWidth}
-            viewportSize={slide.viewportSize ?? 1000}
-            viewportRatio={slide.viewportRatio ?? 0.5625}
-          />
-        ) : !slide ? (
-          <div className="absolute inset-0 flex items-center justify-center">
-            <div className="size-12 rounded-2xl bg-gradient-to-br from-violet-100 to-blue-100 dark:from-violet-900/30 dark:to-blue-900/30 flex items-center justify-center">
-              <span className="text-xl opacity-50">📄</span>
-            </div>
-          </div>
-        ) : null}
-      </div>
-
-      <div className="mt-2.5 px-1 flex items-center gap-2">
-        <span className="shrink-0 inline-flex items-center rounded-full bg-violet-100 dark:bg-violet-900/30 px-2 py-0.5 text-[11px] font-medium text-violet-600 dark:text-violet-400">
-          {classroom.sceneCount} {t('classroom.slides')} · {formatCreatedAt(classroom.createdAt)}
-        </span>
-        <Tooltip>
-          <TooltipTrigger asChild>
-            <p className="font-medium text-[15px] truncate text-foreground/90 min-w-0">
-              {classroom.name}
-            </p>
-          </TooltipTrigger>
-          <TooltipContent
-            side="bottom"
-            sideOffset={4}
-            className="!max-w-[min(90vw,32rem)] break-words whitespace-normal"
-          >
-            {classroom.name}
-          </TooltipContent>
-        </Tooltip>
-      </div>
-    </div>
-  );
-}
-
 // ─── Classroom Card — clean, minimal style ──────────────────────
 function ClassroomCard({
   classroom,
diff --git a/components/course/chapter-list.tsx b/components/course/chapter-list.tsx
index dc66ef251..c1e518b77 100644
--- a/components/course/chapter-list.tsx
+++ b/components/course/chapter-list.tsx
@@ -108,6 +108,7 @@ export function ChapterList({
       <AnimatePresence mode="popLayout">
         {chapters.map((chapter, idx) => {
           const meta = chapter.classroomId ? classroomMeta[chapter.classroomId] : undefined;
+          const isReady = !!chapter.classroomId && (meta?.ready ?? true);
           const isEditing = editingId === chapter.id;
 
           return (
@@ -139,18 +140,16 @@ export function ChapterList({
                       <div className="flex-1 min-w-0">
                         <div className="flex items-center gap-2 flex-wrap">
                           <span className="font-medium text-foreground">{chapter.title}</span>
-                          {chapter.classroomId && (
-                            <Badge
-                              variant="secondary"
-                              className={cn(
-                                meta?.published
-                                  ? 'bg-emerald-500/10 text-emerald-600 dark:text-emerald-400 border border-emerald-500/20'
-                                  : '',
-                              )}
-                            >
-                              {meta?.published ? t('course.published') : t('course.unpublished')}
-                            </Badge>
-                          )}
+                          <Badge
+                            variant="secondary"
+                            className={cn(
+                              isReady
+                                ? 'bg-emerald-500/10 text-emerald-600 dark:text-emerald-400 border border-emerald-500/20'
+                                : 'text-muted-foreground',
+                            )}
+                          >
+                            {isReady ? t('course.published') : t('course.unpublished')}
+                          </Badge>
                         </div>
                         {chapter.description && (
                           <p className="text-sm text-muted-foreground mt-0.5">{chapter.description}</p>
diff --git a/lib/i18n/course.ts b/lib/i18n/course.ts
index fff124b89..48d701942 100644
--- a/lib/i18n/course.ts
+++ b/lib/i18n/course.ts
@@ -27,12 +27,12 @@ export const courseZhCN = {
     bindClassroom: '绑定课堂',
     unbindClassroom: '解绑课堂',
     createAndBindClassroom: '新建课堂并绑定',
-    published: '已发布',
-    unpublished: '未发布',
+    published: '已就绪',
+    unpublished: '待绑定',
     moveUp: '上移',
     moveDown: '下移',
-    selectClassroom: '选择已发布课堂',
-    noAvailableClassrooms: '暂无可绑定的已发布课堂',
+    selectClassroom: '选择课堂',
+    noAvailableClassrooms: '暂无可绑定的课堂',
     scenes: '个场景',
     chapterDescriptionOptional: '（可选）',
     backToCourses: '返回课程管理',
@@ -49,9 +49,9 @@ export const courseZhCN = {
     unpublish: '取消发布',
     publishedStatus: '已发布',
     draftStatus: '草稿',
-    confirmPublish: '发布后将出现在首页公共课程区，确定发布吗？',
+    confirmPublish: '发布后将出现在首页公共课程区，未绑定的章节将显示为"待更新"。确定发布吗？',
     confirmUnpublish: '取消发布后将从首页移除，确定取消吗？',
-    cannotPublish: '所有章节都需绑定课堂后才能发布',
+    cannotPublish: '至少需要一个章节绑定课堂才能发布',
     publishedCourses: '公共课程',
     noPublishedCourses: '暂无公共课程',
     chaptersReady: '已绑定',
@@ -91,11 +91,11 @@ export const courseEnUS = {
     bindClassroom: 'Bind Classroom',
     unbindClassroom: 'Unbind',
     createAndBindClassroom: 'Create & Bind Classroom',
-    published: 'Published',
-    unpublished: 'Unpublished',
+    published: 'Ready',
+    unpublished: 'Pending',
     moveUp: 'Move Up',
     moveDown: 'Move Down',
-    selectClassroom: 'Select Published Classroom',
+    selectClassroom: 'Select Classroom',
     noAvailableClassrooms: 'No available classrooms to bind',
     scenes: 'scenes',
     chapterDescriptionOptional: '(optional)',
@@ -113,9 +113,9 @@ export const courseEnUS = {
     unpublish: 'Unpublish',
     publishedStatus: 'Published',
     draftStatus: 'Draft',
-    confirmPublish: 'This course will appear in the public area on the homepage. Publish?',
+    confirmPublish: 'This course will appear in the public area. Chapters without a bound classroom will show as "Coming Soon". Publish?',
     confirmUnpublish: 'This will remove the course from the public area. Unpublish?',
-    cannotPublish: 'All chapters must have a bound classroom before publishing',
+    cannotPublish: 'At least one chapter must have a bound classroom before publishing',
     publishedCourses: 'Public Courses',
     noPublishedCourses: 'No public courses yet',
     chaptersReady: 'bound',
diff --git a/lib/types/course.ts b/lib/types/course.ts
index 175fa21e4..7098ff826 100644
--- a/lib/types/course.ts
+++ b/lib/types/course.ts
@@ -10,7 +10,7 @@ export interface CourseChapterContext {
 export interface ClassroomMeta {
   name: string;
   sceneCount: number;
-  published: boolean;
+  ready: boolean;
 }
 
 /** Updates accepted by the updateChapter API. null means "clear the field". */

From b068ce49085d6d96c5bf50f105fde5dbd90e8284 Mon Sep 17 00:00:00 2001
From: zhenzhu143321 <hxcisunli@126.com>
Date: Tue, 31 Mar 2026 21:49:44 +0800
Subject: [PATCH 25/30] =?UTF-8?q?feat:=20course=20public=20view=20mode=20?=
 =?UTF-8?q?=E2=80=94=20read-only=20UI=20via=20=3Fmode=3Dview?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Published courses on the homepage now link to /course/{id}?mode=view,
which hides all editor controls (edit, publish/unpublish, reorder,
bind/unbind classrooms, delete chapters, add chapters). Public viewers
see course info, chapter list with Ready/Coming Soon badges, and can
open bound classrooms for playback.

- Add useSearchParams + Suspense wrapper to course detail page
- isViewMode=true: back button → home, CardAction shows published badge
  only, ChapterList is read-only, editor dialogs not rendered
- isViewMode=false: full editor UI unchanged
- Guard loadClassroomMeta effect and usedClassroomIds memo to skip in
  view mode (avoids unnecessary API call + Set allocation)
- Unify published badge rendering — single conditional branch
- ChapterList: readOnly prop makes all editor callbacks optional with
  non-null assertions; handleAdd/Edit/Remove guarded behind prop check
- Add i18n: backToHome, comingSoon, noChaptersPublic (zh-CN + en-US)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 app/course/[id]/page.tsx           | 184 ++++++++++++++++-------------
 app/page.tsx                       |   2 +-
 components/course/chapter-list.tsx |  56 +++++----
 lib/i18n/course.ts                 |   6 +
 4 files changed, 143 insertions(+), 105 deletions(-)

diff --git a/app/course/[id]/page.tsx b/app/course/[id]/page.tsx
index 6041ebc77..124254ced 100644
--- a/app/course/[id]/page.tsx
+++ b/app/course/[id]/page.tsx
@@ -1,7 +1,7 @@
 'use client';
 
-import { useEffect, useState, useCallback, useMemo } from 'react';
-import { useRouter } from 'next/navigation';
+import { useEffect, useState, useCallback, useMemo, Suspense } from 'react';
+import { useRouter, useSearchParams } from 'next/navigation';
 import { motion } from 'motion/react';
 import { useI18n } from '@/lib/hooks/use-i18n';
 import { useCourseStore } from '@/lib/store/course';
@@ -31,9 +31,11 @@ import { toast } from 'sonner';
 
 type PublishDialogMode = 'publish' | 'unpublish' | null;
 
-export default function CourseDetailPage({ params }: { params: Promise<{ id: string }> }) {
+function CourseDetailContent({ params }: { params: Promise<{ id: string }> }) {
   const { t } = useI18n();
   const router = useRouter();
+  const searchParams = useSearchParams();
+  const isViewMode = searchParams.get('mode') === 'view';
   const { currentCourse, fetchCourse, updateCourse, addChapter, updateChapter, removeChapter, reorderChapters, publishCourse, unpublishCourse } =
     useCourseStore();
   const [editing, setEditing] = useState(false);
@@ -78,15 +80,16 @@ export default function CourseDetailPage({ params }: { params: Promise<{ id: str
   }, []);
 
   useEffect(() => {
+    if (isViewMode) return;
     const ids = boundClassroomIdsKey ? boundClassroomIdsKey.split(',') : [];
     if (ids.length > 0) loadClassroomMeta(ids);
   // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [boundClassroomIdsKey, loadClassroomMeta]);
+  }, [isViewMode, boundClassroomIdsKey, loadClassroomMeta]);
 
   const usedClassroomIds = useMemo(
-    () => new Set(currentCourse?.chapters.map((c) => c.classroomId).filter((id): id is string => !!id) ?? []),
+    () => isViewMode ? new Set<string>() : new Set(currentCourse?.chapters.map((c) => c.classroomId).filter((id): id is string => !!id) ?? []),
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    [boundClassroomIdsKey],
+    [isViewMode, boundClassroomIdsKey],
   );
 
   if (!courseId || !currentCourse) {
@@ -183,9 +186,9 @@ export default function CourseDetailPage({ params }: { params: Promise<{ id: str
           transition={{ duration: 0.3 }}
           className="mb-6"
         >
-          <Button variant="ghost" size="sm" onClick={() => router.push('/course')}>
+          <Button variant="ghost" size="sm" onClick={() => router.push(isViewMode ? '/' : '/course')}>
             <ArrowLeft />
-            {t('course.backToCourses')}
+            {isViewMode ? t('course.backToHome') : t('course.backToCourses')}
           </Button>
         </motion.div>
 
@@ -201,39 +204,43 @@ export default function CourseDetailPage({ params }: { params: Promise<{ id: str
               <CardTitle className="text-xl">{currentCourse.name}</CardTitle>
               <CardAction>
                 <div className="flex items-center gap-2">
-                  {isPublished ? (
+                  {(isViewMode || isPublished) && (
+                    <Badge variant="secondary" className="gap-1 text-emerald-600 dark:text-emerald-400 border-emerald-200 dark:border-emerald-800 bg-emerald-50 dark:bg-emerald-950/40">
+                      <Globe className="size-3" />
+                      {t('course.publishedStatus')}
+                    </Badge>
+                  )}
+                  {!isViewMode && (
                     <>
-                      <Badge variant="secondary" className="gap-1 text-emerald-600 dark:text-emerald-400 border-emerald-200 dark:border-emerald-800 bg-emerald-50 dark:bg-emerald-950/40">
-                        <Globe className="size-3" />
-                        {t('course.publishedStatus')}
-                      </Badge>
-                      <Button variant="ghost" size="sm" className="text-muted-foreground hover:text-destructive" onClick={() => setPublishDialog('unpublish')}>
-                        <GlobeLock className="size-4" />
-                        {t('course.unpublish')}
+                      {isPublished ? (
+                        <Button variant="ghost" size="sm" className="text-muted-foreground hover:text-destructive" onClick={() => setPublishDialog('unpublish')}>
+                          <GlobeLock className="size-4" />
+                          {t('course.unpublish')}
+                        </Button>
+                      ) : canPublish ? (
+                        <Button variant="default" size="sm" onClick={() => setPublishDialog('publish')}>
+                          <Globe className="size-4" />
+                          {t('course.publish')}
+                        </Button>
+                      ) : (
+                        <Tooltip>
+                          <TooltipTrigger asChild>
+                            <span tabIndex={0}>
+                              <Button variant="outline" size="sm" disabled>
+                                <Globe className="size-4" />
+                                {t('course.publish')}
+                              </Button>
+                            </span>
+                          </TooltipTrigger>
+                          <TooltipContent>{t('course.cannotPublish')}</TooltipContent>
+                        </Tooltip>
+                      )}
+                      <Button variant="outline" size="sm" onClick={() => setEditing(true)}>
+                        <Pencil />
+                        {t('course.edit')}
                       </Button>
                     </>
-                  ) : canPublish ? (
-                    <Button variant="default" size="sm" onClick={() => setPublishDialog('publish')}>
-                      <Globe className="size-4" />
-                      {t('course.publish')}
-                    </Button>
-                  ) : (
-                    <Tooltip>
-                      <TooltipTrigger asChild>
-                        <span tabIndex={0}>
-                          <Button variant="outline" size="sm" disabled>
-                            <Globe className="size-4" />
-                            {t('course.publish')}
-                          </Button>
-                        </span>
-                      </TooltipTrigger>
-                      <TooltipContent>{t('course.cannotPublish')}</TooltipContent>
-                    </Tooltip>
                   )}
-                  <Button variant="outline" size="sm" onClick={() => setEditing(true)}>
-                    <Pencil />
-                    {t('course.edit')}
-                  </Button>
                 </div>
               </CardAction>
             </CardHeader>
@@ -292,7 +299,7 @@ export default function CourseDetailPage({ params }: { params: Promise<{ id: str
             <Badge variant="secondary" className="ml-1">
               {currentCourse.chapters.length}
             </Badge>
-            {totalCount > 0 && (
+            {!isViewMode && totalCount > 0 && (
               <Badge
                 variant="outline"
                 className={`ml-auto text-xs ${boundCount === totalCount ? 'text-emerald-600 dark:text-emerald-400 border-emerald-200 dark:border-emerald-800' : 'text-muted-foreground'}`}
@@ -306,56 +313,71 @@ export default function CourseDetailPage({ params }: { params: Promise<{ id: str
             courseId={courseId}
             chapters={currentCourse.chapters}
             classroomMeta={classroomMeta}
-            onAdd={(title, description) => addChapter(courseId, title, description)}
-            onEdit={(chapterId, title, description) => updateChapter(courseId, chapterId, { title, description })}
-            onRemove={(chapterId) => removeChapter(courseId, chapterId)}
-            onMove={handleMove}
-            onBind={handleBind}
-            onUnbind={handleUnbind}
-            onCreateAndBind={handleCreateAndBind}
+            readOnly={isViewMode}
             onOpenClassroom={handleOpenClassroom}
+            {...(!isViewMode && {
+              onAdd: (title, description) => addChapter(courseId, title, description),
+              onEdit: (chapterId, title, description) => updateChapter(courseId, chapterId, { title, description }),
+              onRemove: (chapterId) => removeChapter(courseId, chapterId),
+              onMove: handleMove,
+              onBind: handleBind,
+              onUnbind: handleUnbind,
+              onCreateAndBind: handleCreateAndBind,
+            })}
           />
         </motion.div>
       </div>
 
-      {/* Edit course dialog */}
-      <Dialog open={editing} onOpenChange={(open) => { if (!open) setEditing(false); }}>
-        <DialogContent className="max-w-lg">
-          <DialogHeader>
-            <DialogTitle>{t('course.edit')}</DialogTitle>
-          </DialogHeader>
-          <CourseForm initialData={currentCourse} onSubmit={handleUpdate} onCancel={() => setEditing(false)} />
-        </DialogContent>
-      </Dialog>
+      {!isViewMode && (
+        <>
+          {/* Edit course dialog */}
+          <Dialog open={editing} onOpenChange={(open) => { if (!open) setEditing(false); }}>
+            <DialogContent className="max-w-lg">
+              <DialogHeader>
+                <DialogTitle>{t('course.edit')}</DialogTitle>
+              </DialogHeader>
+              <CourseForm initialData={currentCourse} onSubmit={handleUpdate} onCancel={() => setEditing(false)} />
+            </DialogContent>
+          </Dialog>
 
-      {/* Classroom picker dialog */}
-      {bindingChapterId && (
-        <ClassroomPickerDialog
-          usedClassroomIds={usedClassroomIds}
-          onSelect={handlePickerSelect}
-          onClose={() => setBindingChapterId(null)}
-        />
-      )}
+          {/* Classroom picker dialog */}
+          {bindingChapterId && (
+            <ClassroomPickerDialog
+              usedClassroomIds={usedClassroomIds}
+              onSelect={handlePickerSelect}
+              onClose={() => setBindingChapterId(null)}
+            />
+          )}
 
-      {/* Publish / Unpublish confirmation dialog */}
-      <AlertDialog open={publishDialog !== null} onOpenChange={(open) => { if (!open) setPublishDialog(null); }}>
-        <AlertDialogContent>
-          <AlertDialogHeader>
-            <AlertDialogTitle>
-              {publishDialog === 'publish' ? t('course.publish') : t('course.unpublish')}
-            </AlertDialogTitle>
-            <AlertDialogDescription>
-              {publishDialog === 'publish' ? t('course.confirmPublish') : t('course.confirmUnpublish')}
-            </AlertDialogDescription>
-          </AlertDialogHeader>
-          <AlertDialogFooter>
-            <AlertDialogCancel>{t('course.cancel')}</AlertDialogCancel>
-            <AlertDialogAction onClick={handlePublishConfirm}>
-              {publishDialog === 'publish' ? t('course.publish') : t('course.unpublish')}
-            </AlertDialogAction>
-          </AlertDialogFooter>
-        </AlertDialogContent>
-      </AlertDialog>
+          {/* Publish / Unpublish confirmation dialog */}
+          <AlertDialog open={publishDialog !== null} onOpenChange={(open) => { if (!open) setPublishDialog(null); }}>
+            <AlertDialogContent>
+              <AlertDialogHeader>
+                <AlertDialogTitle>
+                  {publishDialog === 'publish' ? t('course.publish') : t('course.unpublish')}
+                </AlertDialogTitle>
+                <AlertDialogDescription>
+                  {publishDialog === 'publish' ? t('course.confirmPublish') : t('course.confirmUnpublish')}
+                </AlertDialogDescription>
+              </AlertDialogHeader>
+              <AlertDialogFooter>
+                <AlertDialogCancel>{t('course.cancel')}</AlertDialogCancel>
+                <AlertDialogAction onClick={handlePublishConfirm}>
+                  {publishDialog === 'publish' ? t('course.publish') : t('course.unpublish')}
+                </AlertDialogAction>
+              </AlertDialogFooter>
+            </AlertDialogContent>
+          </AlertDialog>
+        </>
+      )}
     </div>
   );
 }
+
+export default function CourseDetailPage({ params }: { params: Promise<{ id: string }> }) {
+  return (
+    <Suspense>
+      <CourseDetailContent params={params} />
+    </Suspense>
+  );
+}
diff --git a/app/page.tsx b/app/page.tsx
index d552029ec..68eb9eab9 100644
--- a/app/page.tsx
+++ b/app/page.tsx
@@ -687,7 +687,7 @@ function HomePage() {
                   initial={{ opacity: 0, y: 16 }}
                   animate={{ opacity: 1, y: 0 }}
                   transition={{ delay: i * 0.04, duration: 0.35, ease: 'easeOut' }}
-                  onClick={() => router.push(`/course/${course.id}`)}
+                  onClick={() => router.push(`/course/${course.id}?mode=view`)}
                   className="group rounded-2xl overflow-hidden cursor-pointer border border-white/10 shadow-md hover:shadow-xl hover:-translate-y-1 transition-all duration-250 flex flex-col"
                   style={{ minHeight: '200px' }}
                 >
diff --git a/components/course/chapter-list.tsx b/components/course/chapter-list.tsx
index c1e518b77..dae683a01 100644
--- a/components/course/chapter-list.tsx
+++ b/components/course/chapter-list.tsx
@@ -44,13 +44,14 @@ interface ChapterListProps {
   courseId: string;
   chapters: CourseChapter[];
   classroomMeta: Record<string, ClassroomMeta>;
-  onAdd: (title: string, description: string | null) => Promise<void>;
-  onEdit: (chapterId: string, title: string, description: string | null) => Promise<void>;
-  onRemove: (chapterId: string) => Promise<void>;
-  onMove: (chapterId: string, direction: 'up' | 'down') => Promise<void>;
-  onBind: (chapterId: string) => void;
-  onUnbind: (chapterId: string) => Promise<void>;
-  onCreateAndBind: (chapterId: string) => void;
+  readOnly?: boolean;
+  onAdd?: (title: string, description: string | null) => Promise<void>;
+  onEdit?: (chapterId: string, title: string, description: string | null) => Promise<void>;
+  onRemove?: (chapterId: string) => Promise<void>;
+  onMove?: (chapterId: string, direction: 'up' | 'down') => Promise<void>;
+  onBind?: (chapterId: string) => void;
+  onUnbind?: (chapterId: string) => Promise<void>;
+  onCreateAndBind?: (chapterId: string) => void;
   onOpenClassroom: (classroomId: string) => void;
 }
 
@@ -58,6 +59,7 @@ export function ChapterList({
   courseId: _courseId,
   chapters,
   classroomMeta,
+  readOnly = false,
   onAdd,
   onEdit,
   onRemove,
@@ -73,18 +75,18 @@ export function ChapterList({
   const [removingChapterId, setRemovingChapterId] = useState<string | null>(null);
 
   const handleAdd = async (title: string, description: string | null) => {
-    await onAdd(title, description);
+    await onAdd!(title, description);
     setShowAddForm(false);
   };
 
   const handleEdit = async (chapterId: string, title: string, description: string | null) => {
-    await onEdit(chapterId, title, description);
+    await onEdit!(chapterId, title, description);
     setEditingId(null);
   };
 
   const handleConfirmRemove = async () => {
     if (!removingChapterId) return;
-    await onRemove(removingChapterId);
+    await onRemove!(removingChapterId);
     setRemovingChapterId(null);
   };
 
@@ -94,11 +96,15 @@ export function ChapterList({
         <div className="inline-flex items-center justify-center w-16 h-16 rounded-full bg-muted mb-4">
           <BookOpen className="size-7 text-muted-foreground" />
         </div>
-        <p className="text-muted-foreground text-sm mb-5">{t('course.noChapters')}</p>
-        <Button onClick={() => setShowAddForm(true)}>
-          <Plus />
-          {t('course.addChapter')}
-        </Button>
+        <p className="text-muted-foreground text-sm mb-5">
+          {readOnly ? t('course.noChaptersPublic') : t('course.noChapters')}
+        </p>
+        {!readOnly && (
+          <Button onClick={() => setShowAddForm(true)}>
+            <Plus />
+            {t('course.addChapter')}
+          </Button>
+        )}
       </div>
     );
   }
@@ -148,7 +154,7 @@ export function ChapterList({
                                 : 'text-muted-foreground',
                             )}
                           >
-                            {isReady ? t('course.published') : t('course.unpublished')}
+                            {isReady ? t('course.published') : readOnly ? t('course.comingSoon') : t('course.unpublished')}
                           </Badge>
                         </div>
                         {chapter.description && (
@@ -167,13 +173,14 @@ export function ChapterList({
                         )}
                       </div>
 
-                      {/* Actions */}
+                      {/* Actions — editor only */}
+                      {!readOnly && (
                       <div className="flex items-center gap-0.5 flex-shrink-0">
                         <Button
                           variant="ghost"
                           size="icon-xs"
                           disabled={idx === 0}
-                          onClick={() => onMove(chapter.id, 'up')}
+                          onClick={() => onMove!(chapter.id, 'up')}
                           title={t('course.moveUp')}
                         >
                           <ChevronUp />
@@ -182,7 +189,7 @@ export function ChapterList({
                           variant="ghost"
                           size="icon-xs"
                           disabled={idx === chapters.length - 1}
-                          onClick={() => onMove(chapter.id, 'down')}
+                          onClick={() => onMove!(chapter.id, 'down')}
                           title={t('course.moveDown')}
                         >
                           <ChevronDown />
@@ -205,18 +212,18 @@ export function ChapterList({
                                   <ExternalLink />
                                   {t('course.openClassroom')}
                                 </DropdownMenuItem>
-                                <DropdownMenuItem onClick={() => onUnbind(chapter.id)}>
+                                <DropdownMenuItem onClick={() => onUnbind!(chapter.id)}>
                                   <Unlink />
                                   {t('course.unbindClassroom')}
                                 </DropdownMenuItem>
                               </>
                             ) : (
                               <>
-                                <DropdownMenuItem onClick={() => onBind(chapter.id)}>
+                                <DropdownMenuItem onClick={() => onBind!(chapter.id)}>
                                   <Link />
                                   {t('course.bindClassroom')}
                                 </DropdownMenuItem>
-                                <DropdownMenuItem onClick={() => onCreateAndBind(chapter.id)}>
+                                <DropdownMenuItem onClick={() => onCreateAndBind!(chapter.id)}>
                                   <Sparkles />
                                   {t('course.createAndBindClassroom')}
                                 </DropdownMenuItem>
@@ -233,6 +240,7 @@ export function ChapterList({
                           </DropdownMenuContent>
                         </DropdownMenu>
                       </div>
+                      )}
                     </div>
                   )}
                 </CardContent>
@@ -242,7 +250,8 @@ export function ChapterList({
         })}
       </AnimatePresence>
 
-      {/* Add form */}
+      {/* Add form — editor only */}
+      {!readOnly && (
       <AnimatePresence mode="wait">
         {showAddForm ? (
           <motion.div
@@ -273,6 +282,7 @@ export function ChapterList({
           </motion.button>
         )}
       </AnimatePresence>
+      )}
 
       {/* Delete confirmation */}
       <AlertDialog open={!!removingChapterId} onOpenChange={(open) => { if (!open) setRemovingChapterId(null); }}>
diff --git a/lib/i18n/course.ts b/lib/i18n/course.ts
index 48d701942..8b43c398c 100644
--- a/lib/i18n/course.ts
+++ b/lib/i18n/course.ts
@@ -36,6 +36,9 @@ export const courseZhCN = {
     scenes: '个场景',
     chapterDescriptionOptional: '（可选）',
     backToCourses: '返回课程管理',
+    backToHome: '返回首页',
+    comingSoon: '待更新',
+    noChaptersPublic: '暂无章节内容',
     courseInfo: '课程信息',
     chapters: '章节列表',
     emptyStateTitle: '还没有课程',
@@ -100,6 +103,9 @@ export const courseEnUS = {
     scenes: 'scenes',
     chapterDescriptionOptional: '(optional)',
     backToCourses: 'Back to Course Library',
+    backToHome: 'Back to Home',
+    comingSoon: 'Coming Soon',
+    noChaptersPublic: 'No chapters available yet',
     courseInfo: 'Course Info',
     chapters: 'Chapters',
     emptyStateTitle: 'No courses yet',

From 81ab4efde5cd0380229007c61c71887d003f6ee5 Mon Sep 17 00:00:00 2001
From: zhenzhu143321 <hxcisunli@126.com>
Date: Tue, 31 Mar 2026 21:57:54 +0800
Subject: [PATCH 26/30] fix: validate bound classroomIds exist on server before
 publishing course

Previously the publish endpoint only checked that at least one chapter
had a classroomId, but did not verify the classroom JSON existed on disk.
A course with a dangling classroomId could be published and appear on the
homepage, causing 404/white-screen when opening the chapter.

- Add classroomExists() to lib/server/classroom-storage.ts (fs.access,
  checks both new {id}/classroom.json and legacy {id}.json paths)
- In POST /api/course, after the bound-count check, verify all bound
  classroomIds resolve to real files; reject with 400 listing missing IDs

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 app/api/course/route.ts         | 7 +++++++
 lib/server/classroom-storage.ts | 8 ++++++++
 2 files changed, 15 insertions(+)

diff --git a/app/api/course/route.ts b/app/api/course/route.ts
index dde2cca5e..598a5a3c0 100644
--- a/app/api/course/route.ts
+++ b/app/api/course/route.ts
@@ -1,5 +1,6 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { listCourses, readCourse, persistCourse, deleteCourse } from '@/lib/server/course-storage';
+import { classroomExists } from '@/lib/server/classroom-storage';
 import type { Course } from '@/lib/types/course';
 
 export async function GET(req: NextRequest) {
@@ -38,6 +39,12 @@ export async function POST(req: NextRequest) {
       if (bound.length === 0) {
         return NextResponse.json({ error: 'At least one chapter must have a bound classroom to publish' }, { status: 400 });
       }
+      const missing = (await Promise.all(bound.map(async (ch) => ({ ch, exists: await classroomExists(ch.classroomId!) }))))
+        .filter(({ exists }) => !exists)
+        .map(({ ch }) => ch.classroomId);
+      if (missing.length > 0) {
+        return NextResponse.json({ error: `Bound classrooms not found on server: ${missing.join(', ')}` }, { status: 400 });
+      }
     }
     await persistCourse(body);
     return NextResponse.json({ success: true });
diff --git a/lib/server/classroom-storage.ts b/lib/server/classroom-storage.ts
index 385887d53..827822334 100644
--- a/lib/server/classroom-storage.ts
+++ b/lib/server/classroom-storage.ts
@@ -64,6 +64,14 @@ export function isValidClassroomId(id: string): boolean {
   return /^[a-zA-Z0-9_-]+$/.test(id);
 }
 
+export async function classroomExists(id: string): Promise<boolean> {
+  const newPath = path.join(CLASSROOMS_DIR, id, 'classroom.json');
+  try { await fs.access(newPath); return true; } catch {}
+  const oldPath = path.join(CLASSROOMS_DIR, `${id}.json`);
+  try { await fs.access(oldPath); return true; } catch {}
+  return false;
+}
+
 export async function readClassroom(id: string): Promise<PersistedClassroomData | null> {
   // New path: data/classrooms/{id}/classroom.json
   const newPath = path.join(CLASSROOMS_DIR, id, 'classroom.json');

From 53ae95929d8b1dc3cb6e159a1acc79aa498c6575 Mon Sep 17 00:00:00 2001
From: zhenzhu143321 <hxcisunli@126.com>
Date: Thu, 2 Apr 2026 15:05:42 +0800
Subject: [PATCH 27/30] feat: add QNAIGC (Qiniu Cloud) TTS and image generation
 providers

- Add qnaigc-tts provider with 38 voices (traditional, special, bilingual)
- Add qnaigc-image provider using hidden gemini-3.1-flash-image-preview model
- Fix TTS request body to match upstream nested structure (audio/request)
- Add voice selector and speed control to TTS settings panel
- Fix QN LLM provider icon from qwen.svg to qiniu.svg
- Add qiniu.svg logo asset
- Add course list "Back to Home" button
- Fix interactive scene width (no longer forced 16:9)
- Fix course view mode classroom metadata loading

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 app/course/[id]/page.tsx                   |   3 +-
 app/course/page.tsx                        |  10 +-
 components/canvas/canvas-area.tsx          |   3 +-
 components/settings/audio-settings.tsx     |   1 +
 components/settings/index.tsx              |   3 +
 components/settings/tts-settings.tsx       |  58 +++++++++++-
 lib/ai/providers.ts                        |   2 +-
 lib/audio/constants.ts                     |  53 +++++++++++
 lib/audio/tts-providers.ts                 |  45 +++++++++
 lib/audio/types.ts                         |   1 +
 lib/i18n/settings.ts                       |   4 +
 lib/media/adapters/qnaigc-image-adapter.ts | 105 +++++++++++++++++++++
 lib/media/image-providers.ts               |  15 +++
 lib/media/types.ts                         |   2 +-
 lib/server/provider-config.ts              |   2 +
 public/logos/qiniu.svg                     |  23 +++++
 16 files changed, 322 insertions(+), 8 deletions(-)
 create mode 100644 lib/media/adapters/qnaigc-image-adapter.ts
 create mode 100644 public/logos/qiniu.svg

diff --git a/app/course/[id]/page.tsx b/app/course/[id]/page.tsx
index 124254ced..445614b9e 100644
--- a/app/course/[id]/page.tsx
+++ b/app/course/[id]/page.tsx
@@ -80,11 +80,10 @@ function CourseDetailContent({ params }: { params: Promise<{ id: string }> }) {
   }, []);
 
   useEffect(() => {
-    if (isViewMode) return;
     const ids = boundClassroomIdsKey ? boundClassroomIdsKey.split(',') : [];
     if (ids.length > 0) loadClassroomMeta(ids);
   // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [isViewMode, boundClassroomIdsKey, loadClassroomMeta]);
+  }, [boundClassroomIdsKey, loadClassroomMeta]);
 
   const usedClassroomIds = useMemo(
     () => isViewMode ? new Set<string>() : new Set(currentCourse?.chapters.map((c) => c.classroomId).filter((id): id is string => !!id) ?? []),
diff --git a/app/course/page.tsx b/app/course/page.tsx
index d86f574fd..23b3306e5 100644
--- a/app/course/page.tsx
+++ b/app/course/page.tsx
@@ -19,7 +19,7 @@ import {
   AlertDialogAction,
   AlertDialogCancel,
 } from '@/components/ui/alert-dialog';
-import { Plus, BookOpen, Trash2, GraduationCap, User } from 'lucide-react';
+import { ArrowLeft, Plus, BookOpen, Trash2, GraduationCap, User } from 'lucide-react';
 import { cn } from '@/lib/utils';
 
 const COVERS = [
@@ -167,7 +167,13 @@ export default function CoursePage() {
           transition={{ duration: 0.45 }}
           className="flex justify-between items-center mb-8"
         >
-          <h1 className="text-2xl font-bold text-foreground">{t('course.myCourses')}</h1>
+          <div className="flex items-center gap-3">
+            <Button variant="ghost" size="sm" onClick={() => router.push('/')}>
+              <ArrowLeft />
+              {t('course.backToHome')}
+            </Button>
+            <h1 className="text-2xl font-bold text-foreground">{t('course.myCourses')}</h1>
+          </div>
           <Button onClick={() => setShowForm(true)}>
             <Plus />
             {t('course.create')}
diff --git a/components/canvas/canvas-area.tsx b/components/canvas/canvas-area.tsx
index 8dade97e7..a0c220078 100644
--- a/components/canvas/canvas-area.tsx
+++ b/components/canvas/canvas-area.tsx
@@ -90,7 +90,8 @@ export function CanvasArea({
       >
         <div
           className={cn(
-            'aspect-[16/9] h-full max-h-full max-w-full bg-white dark:bg-gray-800 shadow-2xl rounded-lg overflow-hidden relative transition-all duration-700',
+            'h-full max-h-full max-w-full bg-white dark:bg-gray-800 shadow-2xl rounded-lg overflow-hidden relative transition-all duration-700',
+            currentScene?.type === 'interactive' ? 'w-full' : 'aspect-[16/9]',
             showControls && !isLiveSession && currentScene?.type === 'slide' && 'cursor-pointer',
             currentScene?.type === 'interactive'
               ? 'shadow-blue-200/50 dark:shadow-blue-900/50 ring-1 ring-blue-900/5 dark:ring-blue-500/10'
diff --git a/components/settings/audio-settings.tsx b/components/settings/audio-settings.tsx
index 92c2670de..15ea10186 100644
--- a/components/settings/audio-settings.tsx
+++ b/components/settings/audio-settings.tsx
@@ -43,6 +43,7 @@ function getTTSProviderName(providerId: TTSProviderId, t: (key: string) => strin
     'azure-tts': t('settings.providerAzureTTS'),
     'glm-tts': t('settings.providerGLMTTS'),
     'qwen-tts': t('settings.providerQwenTTS'),
+    'qnaigc-tts': t('settings.providerQnaigcTTS'),
     'browser-native-tts': t('settings.providerBrowserNativeTTS'),
   };
   return names[providerId];
diff --git a/components/settings/index.tsx b/components/settings/index.tsx
index a5927224b..e3e4bec24 100644
--- a/components/settings/index.tsx
+++ b/components/settings/index.tsx
@@ -121,6 +121,7 @@ function getTTSProviderName(providerId: TTSProviderId, t: (key: string) => strin
     'azure-tts': t('settings.providerAzureTTS'),
     'glm-tts': t('settings.providerGLMTTS'),
     'qwen-tts': t('settings.providerQwenTTS'),
+    'qnaigc-tts': t('settings.providerQnaigcTTS'),
     'browser-native-tts': t('settings.providerBrowserNativeTTS'),
   };
   return names[providerId];
@@ -140,12 +141,14 @@ const IMAGE_PROVIDER_NAMES: Record<ImageProviderId, string> = {
   seedream: 'providerSeedream',
   'qwen-image': 'providerQwenImage',
   'nano-banana': 'providerNanoBanana',
+  'qnaigc-image': 'providerQnaigcImage',
 };
 
 const IMAGE_PROVIDER_ICONS: Record<ImageProviderId, string> = {
   seedream: '/logos/doubao.svg',
   'qwen-image': '/logos/bailian.svg',
   'nano-banana': '/logos/gemini.svg',
+  'qnaigc-image': '/logos/qiniu.svg',
 };
 
 const VIDEO_PROVIDER_NAMES: Record<VideoProviderId, string> = {
diff --git a/components/settings/tts-settings.tsx b/components/settings/tts-settings.tsx
index 5315345e1..820c0a1fb 100644
--- a/components/settings/tts-settings.tsx
+++ b/components/settings/tts-settings.tsx
@@ -4,9 +4,17 @@ import { useState, useEffect } from 'react';
 import { Label } from '@/components/ui/label';
 import { Input } from '@/components/ui/input';
 import { Button } from '@/components/ui/button';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+import { Slider } from '@/components/ui/slider';
 import { useI18n } from '@/lib/hooks/use-i18n';
 import { useSettingsStore } from '@/lib/store/settings';
-import { TTS_PROVIDERS, DEFAULT_TTS_VOICES } from '@/lib/audio/constants';
+import { TTS_PROVIDERS, DEFAULT_TTS_VOICES, getTTSVoices } from '@/lib/audio/constants';
 import type { TTSProviderId } from '@/lib/audio/types';
 import { Volume2, Loader2, CheckCircle2, XCircle, Eye, EyeOff } from 'lucide-react';
 import { cn } from '@/lib/utils';
@@ -26,6 +34,8 @@ export function TTSSettings({ selectedProviderId }: TTSSettingsProps) {
   const ttsSpeed = useSettingsStore((state) => state.ttsSpeed);
   const ttsProvidersConfig = useSettingsStore((state) => state.ttsProvidersConfig);
   const setTTSProviderConfig = useSettingsStore((state) => state.setTTSProviderConfig);
+  const setTTSVoice = useSettingsStore((state) => state.setTTSVoice);
+  const setTTSSpeed = useSettingsStore((state) => state.setTTSSpeed);
   const activeProviderId = useSettingsStore((state) => state.ttsProviderId);
 
   // When testing a non-active provider, use that provider's default voice
@@ -164,6 +174,9 @@ export function TTSSettings({ selectedProviderId }: TTSSettingsProps) {
               case 'qwen-tts':
                 endpointPath = '/services/aigc/multimodal-generation/generation';
                 break;
+              case 'qnaigc-tts':
+                endpointPath = '/voice/tts';
+                break;
             }
             if (!endpointPath) return null;
             return (
@@ -175,6 +188,49 @@ export function TTSSettings({ selectedProviderId }: TTSSettingsProps) {
         </>
       )}
 
+      {/* Voice & Speed — only when this is the active TTS provider */}
+      {selectedProviderId === activeProviderId && selectedProviderId !== 'browser-native-tts' && (
+        <div
+          className="grid gap-4"
+          style={{ gridTemplateColumns: ttsProvider.speedRange ? '1fr 200px' : '1fr' }}
+        >
+          <div className="space-y-2">
+            <Label className="text-sm">{t('settings.ttsVoice')}</Label>
+            <Select value={ttsVoice} onValueChange={setTTSVoice}>
+              <SelectTrigger className="w-full">
+                <SelectValue />
+              </SelectTrigger>
+              <SelectContent>
+                {getTTSVoices(selectedProviderId).map((voice) => (
+                  <SelectItem key={voice.id} value={voice.id}>
+                    {voice.name}
+                    {voice.description && ` - ${t(`settings.${voice.description}`)}`}
+                  </SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+          </div>
+          {ttsProvider.speedRange && (
+            <div className="space-y-2">
+              <Label className="text-sm">{t('settings.ttsSpeed')}</Label>
+              <div className="flex items-center gap-3">
+                <Slider
+                  value={[ttsSpeed]}
+                  onValueChange={(value) => setTTSSpeed(value[0])}
+                  min={ttsProvider.speedRange.min}
+                  max={ttsProvider.speedRange.max}
+                  step={0.1}
+                  className="flex-1"
+                />
+                <span className="text-xs text-muted-foreground min-w-[3rem] text-right">
+                  {ttsSpeed.toFixed(1)}x
+                </span>
+              </div>
+            </div>
+          )}
+        </div>
+      )}
+
       {/* Test TTS */}
       <div className="space-y-2">
         <Label className="text-sm">{t('settings.testTTS')}</Label>
diff --git a/lib/ai/providers.ts b/lib/ai/providers.ts
index b9fc604b4..188250be8 100644
--- a/lib/ai/providers.ts
+++ b/lib/ai/providers.ts
@@ -844,7 +844,7 @@ export const PROVIDERS: Record<ProviderId, ProviderConfig> = {
     type: 'openai',
     defaultBaseUrl: 'https://api.qnaigc.com/v1',
     requiresApiKey: true,
-    icon: '/logos/qwen.svg',
+    icon: '/logos/qiniu.svg',
     models: [
       {
         id: 'gemini-3.1-pro-preview',
diff --git a/lib/audio/constants.ts b/lib/audio/constants.ts
index 55a5cbb36..f560361e9 100644
--- a/lib/audio/constants.ts
+++ b/lib/audio/constants.ts
@@ -606,6 +606,58 @@ export const TTS_PROVIDERS: Record<TTSProviderId, TTSProviderConfig> = {
     supportedFormats: ['mp3', 'wav', 'pcm'],
   },
 
+  'qnaigc-tts': {
+    id: 'qnaigc-tts',
+    name: 'QNAIGC TTS (七牛云)',
+    requiresApiKey: true,
+    defaultBaseUrl: 'https://api.qnaigc.com/v1',
+    icon: '/logos/qiniu.svg',
+    voices: [
+      // 传统音色 (Traditional)
+      { id: 'qiniu_zh_female_xyqxxj', name: '校园清新学姐', language: 'zh', gender: 'female' },
+      { id: 'qiniu_zh_male_ybxknjs', name: '渊博学科男教师', language: 'zh', gender: 'male' },
+      { id: 'qiniu_zh_male_ljfdxz', name: '邻家辅导学长', language: 'zh', gender: 'male' },
+      { id: 'qiniu_zh_female_ljfdxx', name: '邻家辅导学姐', language: 'zh', gender: 'female' },
+      { id: 'qiniu_zh_male_whxkxg', name: '温和学科小哥', language: 'zh', gender: 'male' },
+      { id: 'qiniu_zh_female_wwxkjx', name: '温婉学科讲师', language: 'zh', gender: 'female' },
+      { id: 'qiniu_zh_male_tyygjs', name: '通用阳光讲师', language: 'zh', gender: 'male' },
+      { id: 'qiniu_zh_female_zxjxnjs', name: '知性教学女教师', language: 'zh', gender: 'female' },
+      { id: 'qiniu_zh_male_hlsnkk', name: '火力少年凯凯', language: 'zh', gender: 'male' },
+      { id: 'qiniu_zh_male_wncwxz', name: '温暖沉稳学长', language: 'zh', gender: 'male' },
+      { id: 'qiniu_zh_female_tmjxxy', name: '甜美教学小源', language: 'zh', gender: 'female' },
+      { id: 'qiniu_zh_female_glktss', name: '干练课堂思思', language: 'zh', gender: 'female' },
+      { id: 'qiniu_zh_male_szxyxd', name: '率真校园向导', language: 'zh', gender: 'male' },
+      { id: 'qiniu_zh_female_kljxdd', name: '开朗教学督导', language: 'zh', gender: 'female' },
+      // 特殊音色 (Special)
+      { id: 'qiniu_zh_female_wwkjby', name: '温婉课件配音', language: 'zh', gender: 'female' },
+      { id: 'qiniu_zh_male_hllzmz', name: '活力率真萌仔', language: 'zh', gender: 'male' },
+      { id: 'qiniu_zh_male_mzjsxg', name: '名著角色猴哥', language: 'zh', gender: 'male' },
+      { id: 'qiniu_zh_male_tcsnsf', name: '天才少年示范', language: 'zh', gender: 'male' },
+      { id: 'qiniu_zh_female_yyqmpq', name: '英语启蒙佩奇', language: 'zh', gender: 'female' },
+      { id: 'qiniu_zh_female_sqjyay', name: '社区教育阿姨', language: 'zh', gender: 'female' },
+      { id: 'qiniu_zh_female_segsby', name: '少儿故事配音', language: 'zh', gender: 'female' },
+      { id: 'qiniu_zh_female_qwzscb', name: '趣味知识传播', language: 'zh', gender: 'female' },
+      { id: 'qiniu_zh_female_dmytwz', name: '动漫樱桃丸子', language: 'zh', gender: 'female' },
+      { id: 'qiniu_zh_male_cxkjns', name: '磁性课件男声', language: 'zh', gender: 'male' },
+      { id: 'qiniu_zh_male_etgsxe', name: '儿童故事熊二', language: 'zh', gender: 'male' },
+      { id: 'qiniu_zh_male_gzjjxb', name: '古装剧教学版', language: 'zh', gender: 'male' },
+      { id: 'qiniu_zh_male_qslymb', name: '轻松懒音绵宝', language: 'zh', gender: 'male' },
+      { id: 'qiniu_zh_female_cxjxgw', name: '慈祥教学顾问', language: 'zh', gender: 'female' },
+      // 双语音色 (Bilingual)
+      { id: 'qiniu_multi_male_rxsyn2', name: '日西双语男2', language: 'multi', gender: 'male' },
+      { id: 'qiniu_multi_female_rxsyn2', name: '日西双语女2', language: 'multi', gender: 'female' },
+      { id: 'qiniu_multi_female_rxsyn1', name: '日西双语女1', language: 'multi', gender: 'female' },
+      { id: 'qiniu_multi_male_rxsyn1', name: '日西双语男1', language: 'multi', gender: 'male' },
+      { id: 'qiniu_en_female_azyy', name: '澳洲英语女', language: 'en-AU', gender: 'female' },
+      { id: 'qiniu_en_female_msyyn', name: '美式英语女', language: 'en-US', gender: 'female' },
+      { id: 'qiniu_en_female_ysyyn', name: '英式英语女', language: 'en-GB', gender: 'female' },
+      { id: 'qiniu_en_male_ysyyn', name: '英式英语男', language: 'en-GB', gender: 'male' },
+      { id: 'qiniu_en_male_msyyn', name: '美式英语男', language: 'en-US', gender: 'male' },
+      { id: 'qiniu_en_male_azyyn', name: '澳洲英语男', language: 'en-AU', gender: 'male' },
+    ],
+    supportedFormats: ['mp3'],
+  },
+
   'browser-native-tts': {
     id: 'browser-native-tts',
     name: '浏览器原生 (Web Speech API)',
@@ -833,6 +885,7 @@ export const DEFAULT_TTS_VOICES: Record<TTSProviderId, string> = {
   'azure-tts': 'zh-CN-XiaoxiaoNeural',
   'glm-tts': 'tongtong',
   'qwen-tts': 'Cherry',
+  'qnaigc-tts': 'qiniu_zh_male_ybxknjs',
   'browser-native-tts': 'default',
 };
 
diff --git a/lib/audio/tts-providers.ts b/lib/audio/tts-providers.ts
index bf1f2c128..90ccddc04 100644
--- a/lib/audio/tts-providers.ts
+++ b/lib/audio/tts-providers.ts
@@ -130,6 +130,9 @@ export async function generateTTS(
     case 'qwen-tts':
       return await generateQwenTTS(config, text);
 
+    case 'qnaigc-tts':
+      return await generateQnaigcTTS(config, text);
+
     case 'browser-native-tts':
       throw new Error(
         'Browser Native TTS must be handled client-side using Web Speech API. This provider cannot be used on the server.',
@@ -316,6 +319,48 @@ async function generateQwenTTS(config: TTSModelConfig, text: string): Promise<TT
   };
 }
 
+/**
+ * QNAIGC TTS implementation (Qiniu Cloud)
+ */
+async function generateQnaigcTTS(
+  config: TTSModelConfig,
+  text: string,
+): Promise<TTSGenerationResult> {
+  const baseUrl = config.baseUrl || TTS_PROVIDERS['qnaigc-tts'].defaultBaseUrl;
+
+  const response = await fetch(`${baseUrl}/voice/tts`, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${config.apiKey}`,
+      'Content-Type': 'application/json; charset=utf-8',
+    },
+    body: JSON.stringify({
+      audio: {
+        voice_type: config.voice,
+        encoding: 'mp3',
+        speed_ratio: config.speed || 1.0,
+      },
+      request: {
+        text,
+      },
+    }),
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text().catch(() => response.statusText);
+    throw new Error(`QNAIGC TTS API error: ${errorText}`);
+  }
+
+  const data = await response.json();
+
+  if (!data.data) {
+    throw new Error(`QNAIGC TTS error: No audio data in response. Response: ${JSON.stringify(data)}`);
+  }
+
+  const audio = new Uint8Array(Buffer.from(data.data as string, 'base64'));
+  return { audio, format: 'mp3' };
+}
+
 /**
  * Get current TTS configuration from settings store
  * Note: This function should only be called in browser context
diff --git a/lib/audio/types.ts b/lib/audio/types.ts
index 43c37087f..30305d44b 100644
--- a/lib/audio/types.ts
+++ b/lib/audio/types.ts
@@ -82,6 +82,7 @@ export type TTSProviderId =
   | 'azure-tts'
   | 'glm-tts'
   | 'qwen-tts'
+  | 'qnaigc-tts'
   | 'browser-native-tts';
 // Add new TTS providers below (uncomment and modify):
 // | 'elevenlabs-tts'
diff --git a/lib/i18n/settings.ts b/lib/i18n/settings.ts
index 1e6918263..78ecf3dd3 100644
--- a/lib/i18n/settings.ts
+++ b/lib/i18n/settings.ts
@@ -221,6 +221,7 @@ export const settingsZhCN = {
     providerAzureTTS: 'Azure TTS',
     providerGLMTTS: 'GLM TTS',
     providerQwenTTS: 'Qwen TTS（阿里云百炼）',
+    providerQnaigcTTS: 'QNAIGC TTS（七牛云）',
     providerBrowserNativeTTS: '浏览器原生 TTS',
     providerOpenAIWhisper: 'OpenAI ASR (gpt-4o-mini-transcribe)',
     providerBrowserNative: '浏览器原生 ASR',
@@ -480,6 +481,7 @@ export const settingsZhCN = {
     providerSeedream: 'Seedream（字节豆包）',
     providerQwenImage: 'Qwen Image（阿里通义）',
     providerNanoBanana: 'Nano Banana（Gemini）',
+    providerQnaigcImage: 'QNAIGC 图像（七牛云 Gemini）',
     testImageGeneration: '测试图像生成',
     testImageConnectivity: '测试连接',
     imageConnectivitySuccess: '图像服务连接成功',
@@ -806,6 +808,7 @@ export const settingsEnUS = {
     providerAzureTTS: 'Azure TTS',
     providerGLMTTS: 'GLM TTS',
     providerQwenTTS: 'Qwen TTS (Alibaba Cloud Bailian)',
+    providerQnaigcTTS: 'QNAIGC TTS (Qiniu Cloud)',
     providerBrowserNativeTTS: 'Browser Native TTS',
     providerOpenAIWhisper: 'OpenAI ASR (gpt-4o-mini-transcribe)',
     providerBrowserNative: 'Browser Native ASR',
@@ -1068,6 +1071,7 @@ export const settingsEnUS = {
     providerSeedream: 'Seedream (ByteDance)',
     providerQwenImage: 'Qwen Image (Alibaba)',
     providerNanoBanana: 'Nano Banana (Gemini)',
+    providerQnaigcImage: 'QNAIGC Image (Qiniu Gemini)',
     testImageGeneration: 'Test Image Generation',
     testImageConnectivity: 'Test Connection',
     imageConnectivitySuccess: 'Image service connected successfully',
diff --git a/lib/media/adapters/qnaigc-image-adapter.ts b/lib/media/adapters/qnaigc-image-adapter.ts
new file mode 100644
index 000000000..3b8273c77
--- /dev/null
+++ b/lib/media/adapters/qnaigc-image-adapter.ts
@@ -0,0 +1,105 @@
+/**
+ * QNAIGC Image Generation Adapter (Qiniu Cloud)
+ *
+ * Uses QNAIGC's OpenAI-compatible image generation endpoint.
+ * Model: gemini-3.1-flash-image-preview (hidden model, not in /v1/models)
+ *
+ * Endpoint: POST https://api.qnaigc.com/v1/images/generations
+ * Auth: Authorization: Bearer <apiKey>
+ * Response: { data: [{ b64_json: "..." }], output_format: "png" }
+ */
+
+import type {
+  ImageGenerationConfig,
+  ImageGenerationOptions,
+  ImageGenerationResult,
+} from '../types';
+
+const DEFAULT_MODEL = 'gemini-3.1-flash-image-preview';
+const DEFAULT_BASE_URL = 'https://api.qnaigc.com/v1';
+
+// Default output dimensions per aspect ratio (observed from live API)
+const ASPECT_RATIO_DIMENSIONS: Record<string, { width: number; height: number }> = {
+  '16:9': { width: 1376, height: 768 },
+  '9:16': { width: 768, height: 1376 },
+  '4:3': { width: 1024, height: 768 },
+  '1:1': { width: 1024, height: 1024 },
+};
+
+export async function testQnaigcImageConnectivity(
+  config: ImageGenerationConfig,
+): Promise<{ success: boolean; message: string }> {
+  const baseUrl = config.baseUrl || DEFAULT_BASE_URL;
+
+  try {
+    const response = await fetch(`${baseUrl}/images/generations`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${config.apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        model: config.model || DEFAULT_MODEL,
+        prompt: '',
+        image_config: { aspect_ratio: '1:1' },
+      }),
+    });
+
+    if (response.status === 401 || response.status === 403) {
+      return {
+        success: false,
+        message: `Invalid API key or unauthorized (${response.status}). Check your QNAIGC API Key.`,
+      };
+    }
+
+    // 400 or 200 both mean the key was accepted (400 might be prompt rejection, which is fine)
+    return { success: true, message: `Connected to QNAIGC Image (${config.model || DEFAULT_MODEL})` };
+  } catch (err) {
+    return {
+      success: false,
+      message: `Network error: unable to reach ${baseUrl}. ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
+export async function generateWithQnaigcImage(
+  config: ImageGenerationConfig,
+  options: ImageGenerationOptions,
+): Promise<ImageGenerationResult> {
+  const baseUrl = config.baseUrl || DEFAULT_BASE_URL;
+  const model = config.model || DEFAULT_MODEL;
+  const aspectRatio = options.aspectRatio ?? '16:9';
+
+  const response = await fetch(`${baseUrl}/images/generations`, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${config.apiKey}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      model,
+      prompt: options.prompt,
+      image_config: { aspect_ratio: aspectRatio },
+    }),
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`QNAIGC image generation failed (${response.status}): ${text}`);
+  }
+
+  const data = await response.json();
+  const b64 = data?.data?.[0]?.b64_json as string | undefined;
+
+  if (!b64) {
+    throw new Error(`QNAIGC image: no b64_json in response. Got: ${JSON.stringify(data)}`);
+  }
+
+  const dims = ASPECT_RATIO_DIMENSIONS[aspectRatio] ?? { width: 1024, height: 576 };
+
+  return {
+    base64: b64,
+    width: options.width || dims.width,
+    height: options.height || dims.height,
+  };
+}
diff --git a/lib/media/image-providers.ts b/lib/media/image-providers.ts
index e5130ae9a..30c49ec70 100644
--- a/lib/media/image-providers.ts
+++ b/lib/media/image-providers.ts
@@ -12,6 +12,7 @@ import type {
 import { generateWithSeedream, testSeedreamConnectivity } from './adapters/seedream-adapter';
 import { generateWithQwenImage, testQwenImageConnectivity } from './adapters/qwen-image-adapter';
 import { generateWithNanoBanana, testNanoBananaConnectivity } from './adapters/nano-banana-adapter';
+import { generateWithQnaigcImage, testQnaigcImageConnectivity } from './adapters/qnaigc-image-adapter';
 
 export const IMAGE_PROVIDERS: Record<ImageProviderId, ImageProviderConfig> = {
   seedream: {
@@ -66,6 +67,16 @@ export const IMAGE_PROVIDERS: Record<ImageProviderId, ImageProviderConfig> = {
     ],
     supportedAspectRatios: ['16:9', '4:3', '1:1'],
   },
+  'qnaigc-image': {
+    id: 'qnaigc-image',
+    name: 'QNAIGC 图像 (七牛云 Gemini)',
+    requiresApiKey: true,
+    defaultBaseUrl: 'https://api.qnaigc.com/v1',
+    models: [
+      { id: 'gemini-3.1-flash-image-preview', name: 'Gemini 3.1 Flash Image' },
+    ],
+    supportedAspectRatios: ['16:9', '4:3', '1:1', '9:16'],
+  },
 };
 
 export async function testImageConnectivity(
@@ -78,6 +89,8 @@ export async function testImageConnectivity(
       return testQwenImageConnectivity(config);
     case 'nano-banana':
       return testNanoBananaConnectivity(config);
+    case 'qnaigc-image':
+      return testQnaigcImageConnectivity(config);
     default:
       return {
         success: false,
@@ -97,6 +110,8 @@ export async function generateImage(
       return generateWithQwenImage(config, options);
     case 'nano-banana':
       return generateWithNanoBanana(config, options);
+    case 'qnaigc-image':
+      return generateWithQnaigcImage(config, options);
     default:
       throw new Error(`Unsupported image provider: ${config.providerId}`);
   }
diff --git a/lib/media/types.ts b/lib/media/types.ts
index 9e0a1d08c..6a461ea90 100644
--- a/lib/media/types.ts
+++ b/lib/media/types.ts
@@ -69,7 +69,7 @@
  * Add new image providers here as union members.
  * Keep in sync with IMAGE_PROVIDERS registry in constants.ts
  */
-export type ImageProviderId = 'seedream' | 'qwen-image' | 'nano-banana';
+export type ImageProviderId = 'seedream' | 'qwen-image' | 'nano-banana' | 'qnaigc-image';
 // Add new image providers below (uncomment and modify):
 // | 'dall-e'
 // | 'midjourney'
diff --git a/lib/server/provider-config.ts b/lib/server/provider-config.ts
index 16440ef6d..f6204b574 100644
--- a/lib/server/provider-config.ts
+++ b/lib/server/provider-config.ts
@@ -57,6 +57,7 @@ const TTS_ENV_MAP: Record<string, string> = {
   TTS_AZURE: 'azure-tts',
   TTS_GLM: 'glm-tts',
   TTS_QWEN: 'qwen-tts',
+  TTS_QNAIGC: 'qnaigc-tts',
 };
 
 const ASR_ENV_MAP: Record<string, string> = {
@@ -73,6 +74,7 @@ const IMAGE_ENV_MAP: Record<string, string> = {
   IMAGE_SEEDREAM: 'seedream',
   IMAGE_QWEN_IMAGE: 'qwen-image',
   IMAGE_NANO_BANANA: 'nano-banana',
+  IMAGE_QNAIGC: 'qnaigc-image',
 };
 
 const VIDEO_ENV_MAP: Record<string, string> = {
diff --git a/public/logos/qiniu.svg b/public/logos/qiniu.svg
new file mode 100644
index 000000000..2923f452d
--- /dev/null
+++ b/public/logos/qiniu.svg
@@ -0,0 +1,23 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" role="img" aria-label="Qiniu Cloud">
+  <defs>
+    <linearGradient id="cloudGradient" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#28b1f7"/>
+      <stop offset="100%" stop-color="#28b1f7"/>
+    </linearGradient>
+    <mask id="qCutout">
+      <rect width="256" height="256" fill="white"/>
+      <circle cx="126" cy="128" r="27" fill="black"/>
+      <circle cx="126" cy="128" r="16" fill="white"/>
+      <rect x="138" y="139" width="20" height="8" rx="4" transform="rotate(38 148 143)" fill="black"/>
+    </mask>
+    <filter id="softShadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="6" stdDeviation="8" flood-color="#0b6fb0" flood-opacity="0.12"/>
+    </filter>
+  </defs>
+  <g filter="url(#softShadow)">
+    <path mask="url(#qCutout)" fill="url(#cloudGradient)" d="M73 187c-23.2 0-42-18.4-42-41.2 0-19.9 14.3-36.7 33.7-40.3C70.4 78 94 58 122.6 58c24.1 0 45.1 14.1 55.1 34.5 2.4-.5 4.9-.7 7.5-.7 22 0 39.8 17.4 39.8 38.8S207.2 169 185.2 169H82.4c-2.2 0-4.2-.2-6.3-.5-1.4 5.8-1.9 12.2-3.1 18.5Z"/>
+    <path fill="#28b1f7" opacity="0.28" d="M86 104c9-16 24.9-26 42.9-26 16.7 0 31.2 7.9 40.1 20.7-9.7-7-21.8-11.1-34.8-11.1-21.7 0-40.9 11.6-51.9 28.8-3.2 5-7.1 12.9-7.7 13.4 1.1-7.8 6.6-18.2 11.4-25.8Z"/>
+  </g>
+  <circle cx="185" cy="82" r="20" fill="#ff9933"/>
+  <circle cx="189" cy="78" r="6" fill="#fff" opacity="0.58"/>
+</svg>

From d091c1e8225471f6feefcec5fb2314cd4869201e Mon Sep 17 00:00:00 2001
From: zhenzhu143321 <hxcisunli@126.com>
Date: Thu, 2 Apr 2026 21:56:29 +0800
Subject: [PATCH 28/30] =?UTF-8?q?fix:=20add=20speedRange=20to=20qnaigc-tts?=
 =?UTF-8?q?=20provider=20(0.5=E2=80=932.0)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Backend already passes speed_ratio to upstream; this exposes the
speed slider in the TTS settings UI.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 lib/audio/constants.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/lib/audio/constants.ts b/lib/audio/constants.ts
index f560361e9..0c44fb407 100644
--- a/lib/audio/constants.ts
+++ b/lib/audio/constants.ts
@@ -655,6 +655,7 @@ export const TTS_PROVIDERS: Record<TTSProviderId, TTSProviderConfig> = {
       { id: 'qiniu_en_male_msyyn', name: '美式英语男', language: 'en-US', gender: 'male' },
       { id: 'qiniu_en_male_azyyn', name: '澳洲英语男', language: 'en-AU', gender: 'male' },
     ],
+    speedRange: { min: 0.5, max: 2.0, default: 1.0 },
     supportedFormats: ['mp3'],
   },
 

From 89b6d8972b620ac2c37e99c04a1febb12daf20c3 Mon Sep 17 00:00:00 2001
From: zhenzhu143321 <hxcisunli@126.com>
Date: Thu, 2 Apr 2026 22:19:12 +0800
Subject: [PATCH 29/30] chore: remove stale eslint-disable in
 course/[id]/page.tsx

The disable was left over after removing isViewMode from the useEffect
dependency array. The deps list is now complete so the directive serves
no purpose.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 app/course/[id]/page.tsx | 1 -
 1 file changed, 1 deletion(-)

diff --git a/app/course/[id]/page.tsx b/app/course/[id]/page.tsx
index 445614b9e..7c06b17cb 100644
--- a/app/course/[id]/page.tsx
+++ b/app/course/[id]/page.tsx
@@ -82,7 +82,6 @@ function CourseDetailContent({ params }: { params: Promise<{ id: string }> }) {
   useEffect(() => {
     const ids = boundClassroomIdsKey ? boundClassroomIdsKey.split(',') : [];
     if (ids.length > 0) loadClassroomMeta(ids);
-  // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [boundClassroomIdsKey, loadClassroomMeta]);
 
   const usedClassroomIds = useMemo(

From 521da59d926357f920581bc90b376e47401e7321 Mon Sep 17 00:00:00 2001
From: zhenzhu143321 <hxcisunli@126.com>
Date: Fri, 3 Apr 2026 15:21:00 +0800
Subject: [PATCH 30/30] =?UTF-8?q?fix:=20review=20fixes=20=E2=80=94=20path?=
 =?UTF-8?q?=20traversal,=20isReady=20default,=20stale=20eslint-disables?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- classroomExists: add isValidClassroomId guard to prevent path traversal
  via user-controlled classroomId strings in course publish validation
- chapter-list: fix isReady default ?? true → ?? false; metadata loading
  state should treat missing/unloaded meta as not-ready, not ready
- app/page.tsx: remove 4 stale eslint-disable/enable directives left over
  from the homepage public-courses refactor; add justified exhaustive-deps
  disable on mount-only useEffect

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 app/page.tsx                       | 5 +----
 components/course/chapter-list.tsx | 2 +-
 lib/server/classroom-storage.ts    | 1 +
 3 files changed, 3 insertions(+), 5 deletions(-)

diff --git a/app/page.tsx b/app/page.tsx
index 68eb9eab9..2a224933c 100644
--- a/app/page.tsx
+++ b/app/page.tsx
@@ -108,7 +108,6 @@ function HomePage() {
   const [recentOpen, setRecentOpen] = useState(true);
 
   // Hydrate client-only state after mount (avoids SSR mismatch)
-  /* eslint-disable react-hooks/set-state-in-effect -- Hydration from localStorage must happen in effect */
   useEffect(() => {
     setStoreHydrated(true);
     try {
@@ -135,7 +134,6 @@ function HomePage() {
       /* localStorage unavailable */
     }
   }, []);
-  /* eslint-enable react-hooks/set-state-in-effect */
 
   // Restore requirement draft from cache (derived state pattern — no effect needed)
   const [prevCachedRequirement, setPrevCachedRequirement] = useState(cachedRequirement);
@@ -164,7 +162,6 @@ function HomePage() {
     if (courses.length > 0 && classrooms.length === 0) {
       setActiveTab('courses');
     }
-  // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [courses.length, classrooms.length]);
 
   // Close dropdowns when clicking outside
@@ -201,7 +198,6 @@ function HomePage() {
     useMediaGenerationStore.getState().revokeObjectUrls();
     useMediaGenerationStore.setState({ tasks: {} });
 
-    // eslint-disable-next-line react-hooks/set-state-in-effect -- Store hydration on mount
     Promise.all([
       loadClassrooms(),
       fetchCourses(),
@@ -211,6 +207,7 @@ function HomePage() {
         setPublishedCourses(publishedCourseData);
       }
     }).catch(() => {});
+  // eslint-disable-next-line react-hooks/exhaustive-deps -- mount-only: intentionally run once
   }, []);
 
   const handleDelete = (id: string, e: React.MouseEvent) => {
diff --git a/components/course/chapter-list.tsx b/components/course/chapter-list.tsx
index dae683a01..330cd2a34 100644
--- a/components/course/chapter-list.tsx
+++ b/components/course/chapter-list.tsx
@@ -114,7 +114,7 @@ export function ChapterList({
       <AnimatePresence mode="popLayout">
         {chapters.map((chapter, idx) => {
           const meta = chapter.classroomId ? classroomMeta[chapter.classroomId] : undefined;
-          const isReady = !!chapter.classroomId && (meta?.ready ?? true);
+          const isReady = !!chapter.classroomId && (meta?.ready ?? false);
           const isEditing = editingId === chapter.id;
 
           return (
diff --git a/lib/server/classroom-storage.ts b/lib/server/classroom-storage.ts
index 827822334..b69b23d1a 100644
--- a/lib/server/classroom-storage.ts
+++ b/lib/server/classroom-storage.ts
@@ -65,6 +65,7 @@ export function isValidClassroomId(id: string): boolean {
 }
 
 export async function classroomExists(id: string): Promise<boolean> {
+  if (!isValidClassroomId(id)) return false;
   const newPath = path.join(CLASSROOMS_DIR, id, 'classroom.json');
   try { await fs.access(newPath); return true; } catch {}
   const oldPath = path.join(CLASSROOMS_DIR, `${id}.json`);