Add structured AI courseware APIs

ARCHITECTURE.md

@@ -261,7 +261,7 @@ RUN pip install -r requirements.txt
 **托管**: Google Cloud Platform (GCP)
 
 **配置**:
-- Cluster URL: `https://xxx.c0.us-west3.gcp.weaviate.cloud`
+- Cluster URL: `https://riiqvgc7tuum6cgwhik9ra.c0.us-west3.gcp.weaviate.cloud`
 - Authentication: API Key
 - Collection Schema: 自动创建（LlamaIndex 管理）
 

api/routes_courseware_ai.py

@@ -0,0 +1,563 @@
+from __future__ import annotations
+
+"""
+AI Courseware AI 接口 (Plan / Prepare / Reflect / Improve)。
+
+按照《AI Courseware AI 接口文档 v1.0》提供 6 个结构化 JSON API：
+- /ai/courseware/syllabus/generate
+- /ai/courseware/flow/generate
+- /ai/courseware/flow/regenerate-partial
+- /ai/courseware/plan/detail/generate
+- /ai/courseware/reflection/generate
+- /ai/courseware/improvement/generate
+"""
+
+import json
+import time
+from typing import List, Optional, Any
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, Field
+
+from api.config import client, DEFAULT_MODEL
+
+
+router = APIRouter(prefix="/ai/courseware", tags=["ai-courseware"])
+
+PROMPT_VERSION = "v1.0"
+
+
+class Meta(BaseModel):
+    """所有成功响应必须携带的 meta 信息。"""
+
+    model: str
+    model_version: Optional[str] = None
+    prompt_version: str
+    temperature: float
+    tokens_used: int
+    latency_ms: int
+
+
+# ---------------------------------------------------------------------------
+# 通用 OpenAI 调用辅助
+# ---------------------------------------------------------------------------
+
+def _call_openai_json(
+    op_name: str,
+    system_prompt: str,
+    user_prompt: str,
+    temperature: float = 0.4,
+) -> tuple[dict, Meta]:
+    """调用 OpenAI 并期望得到 JSON 对象；若解析失败则抛 422。"""
+    started = time.time()
+    try:
+        resp = client.chat.completions.create(
+            model=DEFAULT_MODEL,
+            messages=[
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": user_prompt},
+            ],
+            temperature=temperature,
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"{op_name} OpenAI error: {e}")
+
+    latency_ms = int((time.time() - started) * 1000)
+    model_name = getattr(resp, "model", DEFAULT_MODEL)
+    usage = getattr(resp, "usage", None)
+    tokens_used = int(getattr(usage, "total_tokens", 0) or 0)
+
+    content = (resp.choices[0].message.content or "").strip()
+    try:
+        data = json.loads(content)
+        if not isinstance(data, dict):
+            raise ValueError("top-level JSON is not an object")
+    except Exception as e:
+        raise HTTPException(
+            status_code=422,
+            detail=f"INVALID_GENERATION for {op_name}: cannot parse JSON ({e}); raw={content[:400]}",
+        )
+
+    meta = Meta(
+        model=model_name,
+        model_version=None,
+        prompt_version=PROMPT_VERSION,
+        temperature=temperature,
+        tokens_used=tokens_used,
+        latency_ms=latency_ms,
+    )
+    return data, meta
+
+
+# ---------------------------------------------------------------------------
+# 2.1 生成大纲草案 (Generate Syllabus Preview)
+# ---------------------------------------------------------------------------
+
+
+class SyllabusContext(BaseModel):
+    courseName: str
+    learningOutcome: str
+    studentLevel: str
+    teachingFocus: str
+    courseLength: int = Field(..., ge=1, le=52)
+
+
+class SyllabusGenerateRequest(BaseModel):
+    requestId: str
+    context: SyllabusContext
+
+
+class WeekSyllabus(BaseModel):
+    weekNumber: int
+    title: str
+    learningObjectives: List[str]
+    topics: List[str]
+
+
+class SyllabusGenerateData(BaseModel):
+    syllabus: List[WeekSyllabus]
+
+
+class SyllabusGenerateResponse(BaseModel):
+    data: SyllabusGenerateData
+    meta: Meta
+
+
+@router.post("/syllabus/generate", response_model=SyllabusGenerateResponse)
+def generate_syllabus(req: SyllabusGenerateRequest):
+    """Phase 1 (Plan)：根据课程元数据生成 Weeks/Modules 大纲草案。"""
+    ctx = req.context
+    sys_prompt = (
+        "You are an instructional designer. "
+        "Given course metadata, generate a weekly syllabus as JSON. "
+        "Output ONLY a JSON object with key 'syllabus', matching the provided schema."
+    )
+    user_prompt = f"""
+Course name: {ctx.courseName}
+Learning outcome: {ctx.learningOutcome}
+Student level: {ctx.studentLevel}
+Teaching focus: {ctx.teachingFocus}
+Total weeks/modules: {ctx.courseLength}
+
+Return JSON:
+{{
+  "syllabus": [
+    {{
+      "weekNumber": 1,
+      "title": "string",
+      "learningObjectives": ["string", "..."],
+      "topics": ["string", "..."]
+    }},
+    ...
+  ]
+}}
+Make sure the array length equals courseLength ({ctx.courseLength}) and weekNumber starts from 1.
+"""
+
+    data_dict, meta = _call_openai_json("syllabus.generate", sys_prompt, user_prompt, temperature=0.4)
+    if "syllabus" not in data_dict:
+        raise HTTPException(status_code=422, detail="INVALID_GENERATION: 'syllabus' missing in JSON.")
+
+    return SyllabusGenerateResponse(data=SyllabusGenerateData(**data_dict), meta=meta)
+
+
+# ---------------------------------------------------------------------------
+# 2.2 生成完整教学流程 (Generate Lesson Flow)
+# ---------------------------------------------------------------------------
+
+
+class ModuleContext(BaseModel):
+    title: str
+    learningObjectives: List[str]
+    topics: List[str]
+    durationMinutes: int = Field(..., ge=10, le=600)
+
+
+class FlowGenerateRequest(BaseModel):
+    requestId: str
+    moduleContext: ModuleContext
+    systemPrompts: Optional[List[str]] = None
+
+
+class LessonStep(BaseModel):
+    type: str
+    title: str
+    estimated_duration: int = Field(..., ge=1)
+    ai_understanding: str
+
+
+class FlowGenerateData(BaseModel):
+    steps: List[LessonStep]
+
+
+class FlowGenerateResponse(BaseModel):
+    data: FlowGenerateData
+    meta: Meta
+
+
+@router.post("/flow/generate", response_model=FlowGenerateResponse)
+def generate_lesson_flow(req: FlowGenerateRequest):
+    """Phase 2 (Prepare)：为单个 Module 生成完整教学步骤列表。"""
+    mc = req.moduleContext
+    extra_system = "\n".join(req.systemPrompts or [])
+    sys_prompt = (
+        "You are an AI courseware copilot. "
+        "Generate a detailed lesson flow for one module as JSON. "
+        "Output ONLY a JSON object with key 'steps', each step matching the schema."
+    )
+    user_prompt = f"""
+Module title: {mc.title}
+Learning objectives: {mc.learningObjectives}
+Topics: {mc.topics}
+Duration (minutes): {mc.durationMinutes}
+
+Additional long-term system prompts (optional, may be empty):
+{extra_system}
+
+Return JSON:
+{{
+  "steps": [
+    {{
+      "type": "Teacher Explanation | Interactive Quiz | Group Discussion | ...",
+      "title": "string",
+      "estimated_duration": 10,
+      "ai_understanding": "short explanation of why this step exists and what it should achieve"
+    }},
+    ...
+  ]
+}}
+The total sum of estimated_duration should be roughly close to durationMinutes ({mc.durationMinutes}).
+"""
+
+    data_dict, meta = _call_openai_json("flow.generate", sys_prompt, user_prompt, temperature=0.5)
+    if "steps" not in data_dict:
+        raise HTTPException(status_code=422, detail="INVALID_GENERATION: 'steps' missing in JSON.")
+
+    return FlowGenerateResponse(data=FlowGenerateData(**data_dict), meta=meta)
+
+
+# ---------------------------------------------------------------------------
+# 2.3 局部重构教学流程 (Regenerate Partial Flow)
+# ---------------------------------------------------------------------------
+
+
+class SimpleStep(BaseModel):
+    id: str
+    title: str
+    duration: int
+
+
+class CurrentFlow(BaseModel):
+    lockedSteps: List[SimpleStep]
+    unlockedSteps: List[SimpleStep]
+
+
+class FlowPartialRequest(BaseModel):
+    requestId: str
+    prompt: str
+    currentFlow: CurrentFlow
+
+
+class CopilotProposedStep(BaseModel):
+    type: str
+    title: str
+    estimated_duration: int
+    ai_understanding: str
+
+
+class FlowPartialData(BaseModel):
+    explanation: str
+    proposedSteps: List[CopilotProposedStep]
+
+
+class FlowPartialResponse(BaseModel):
+    data: FlowPartialData
+    meta: Meta
+
+
+@router.post("/flow/regenerate-partial", response_model=FlowPartialResponse)
+def regenerate_partial_flow(req: FlowPartialRequest):
+    """Phase 2 (Prepare)：在锁定部分步骤后，根据 Prompt 重写剩余步骤。"""
+    locked = [s.model_dump() for s in req.currentFlow.lockedSteps]
+    unlocked = [s.model_dump() for s in req.currentFlow.unlockedSteps]
+    sys_prompt = (
+        "You are an AI copilot for lesson flow editing. "
+        "Given lockedSteps and unlockedSteps plus a user prompt, "
+        "propose replacement steps ONLY for unlockedSteps and explain your reasoning."
+        "Return JSON with 'explanation' and 'proposedSteps'."
+    )
+    user_prompt = f"""
+User prompt:
+{req.prompt}
+
+Current flow:
+lockedSteps: {locked}
+unlockedSteps: {unlocked}
+
+Return JSON:
+{{
+  "explanation": "short natural language explanation for the teacher UI bubble",
+  "proposedSteps": [
+    {{
+      "type": "Teacher Explanation | Interactive Quiz | Group Discussion | ...",
+      "title": "string",
+      "estimated_duration": 10,
+      "ai_understanding": "short explanation of this step"
+    }}
+  ]
+}}
+"""
+
+    data_dict, meta = _call_openai_json(
+        "flow.regenerate-partial", sys_prompt, user_prompt, temperature=0.5
+    )
+    if "explanation" not in data_dict or "proposedSteps" not in data_dict:
+        raise HTTPException(
+            status_code=422,
+            detail="INVALID_GENERATION: 'explanation' or 'proposedSteps' missing in JSON.",
+        )
+
+    return FlowPartialResponse(data=FlowPartialData(**data_dict), meta=meta)
+
+
+# ---------------------------------------------------------------------------
+# 2.4 生成/润色实体教案长文 (Generate/Polish Lesson Plan Detail)
+# ---------------------------------------------------------------------------
+
+
+class PlanDetailRequest(BaseModel):
+    requestId: str
+    finalizedSteps: List[Any]
+
+
+class LessonSection(BaseModel):
+    section_id: str
+    type: str
+    content: str
+
+
+class PlanDetailData(BaseModel):
+    sections: List[LessonSection]
+
+
+class PlanDetailResponse(BaseModel):
+    data: PlanDetailData
+    meta: Meta
+
+
+@router.post("/plan/detail/generate", response_model=PlanDetailResponse)
+def generate_plan_detail(req: PlanDetailRequest):
+    """Phase 2 (Prepare)：根据最终 Steps 生成/润色详细教案（富文本结构）。"""
+    sys_prompt = (
+        "You are an expert lesson-plan writer. "
+        "Given finalized lesson steps, generate detailed lesson plan sections as JSON. "
+        "Each section has section_id, type, content (Markdown allowed)."
+    )
+    user_prompt = f"""
+Finalized steps (JSON array, opaque to you but describes lesson flow):
+{json.dumps(req.finalizedSteps, ensure_ascii=False)}
+
+Return JSON:
+{{
+  "sections": [
+    {{
+      "section_id": "sec_obj_01",
+      "type": "Lesson Objectives",
+      "content": "By the end of this lesson, students will be able to..."
+    }},
+    {{
+      "section_id": "sec_content_01",
+      "type": "Content",
+      "content": "### 1. Topic heading\\nDetailed explanation..."
+    }}
+  ]
+}}
+"""
+
+    data_dict, meta = _call_openai_json("plan.detail.generate", sys_prompt, user_prompt, temperature=0.4)
+    if "sections" not in data_dict:
+        raise HTTPException(status_code=422, detail="INVALID_GENERATION: 'sections' missing in JSON.")
+
+    return PlanDetailResponse(data=PlanDetailData(**data_dict), meta=meta)
+
+
+# ---------------------------------------------------------------------------
+# 2.5 生成反思看板数据 (Generate Reflection Report)
+# ---------------------------------------------------------------------------
+
+
+class TeachAnnotation(BaseModel):
+    category: str
+    selectedText: Optional[str] = None
+    feedback: Optional[str] = None
+
+
+class QuizAggregations(BaseModel):
+    averageScore: Optional[float] = None
+    lowestTopic: Optional[str] = None
+
+
+class ReflectionRequest(BaseModel):
+    requestId: str
+    teachAnnotations: List[TeachAnnotation] = Field(default_factory=list)
+    quizAggregations: Optional[QuizAggregations] = None
+
+
+class ReflectionUnderstanding(BaseModel):
+    status: str
+    summary: str
+    bulletPoints: Optional[List[str]] = None
+
+
+class ReflectionEngagement(BaseModel):
+    status: str
+    summary: Optional[str] = None
+
+
+class ReflectionDifficulty(BaseModel):
+    status: str
+    challengingTopics: Optional[List[dict]] = None
+
+
+class ReflectionMisconception(BaseModel):
+    status: str
+    issues: Optional[List[dict]] = None
+
+
+class NextLessonSuggestion(BaseModel):
+    actionText: str
+    deepLinkType: Optional[str] = None
+
+
+class ReflectionData(BaseModel):
+    understanding: ReflectionUnderstanding
+    engagement: ReflectionEngagement
+    difficulty: ReflectionDifficulty
+    misconceptions: ReflectionMisconception
+    nextLessonSuggestions: List[NextLessonSuggestion]
+
+
+class ReflectionResponse(BaseModel):
+    data: ReflectionData
+    meta: Meta
+
+
+@router.post("/reflection/generate", response_model=ReflectionResponse)
+def generate_reflection(req: ReflectionRequest):
+    """Phase 4 (Reflect)：基于反馈与测验数据生成反思看板。"""
+    annotations = [a.model_dump() for a in req.teachAnnotations]
+    qa = req.quizAggregations.model_dump() if req.quizAggregations else {}
+    sys_prompt = (
+        "You are an AI teaching analytics assistant. "
+        "Given teacher annotations and quiz aggregations, generate a reflection dashboard as JSON "
+        "with understanding, engagement, difficulty, misconceptions, and nextLessonSuggestions."
+    )
+    user_prompt = f"""
+Teach annotations:
+{json.dumps(annotations, ensure_ascii=False)}
+
+Quiz aggregations:
+{json.dumps(qa, ensure_ascii=False)}
+
+Return JSON:
+{{
+  "understanding": {{
+    "status": "Low | Medium | High",
+    "summary": "short text",
+    "bulletPoints": ["optional", "..."]
+  }},
+  "engagement": {{
+    "status": "Low | Medium | High",
+    "summary": "optional"
+  }},
+  "difficulty": {{
+    "status": "Low | Medium | High",
+    "challengingTopics": [{{"topic": "string", "percentStruggle": 45}}]
+  }},
+  "misconceptions": {{
+    "status": "Low | Medium | High",
+    "issues": [{{"title": "string", "description": "string", "evidence": "string"}}]
+  }},
+  "nextLessonSuggestions": [
+    {{
+      "actionText": "string",
+      "deepLinkType": "PREPARE_FLOW_EDIT | REFLECT_DASHBOARD | ..."
+    }}
+  ]
+}}
+"""
+
+    data_dict, meta = _call_openai_json("reflection.generate", sys_prompt, user_prompt, temperature=0.4)
+    required = ["understanding", "engagement", "difficulty", "misconceptions", "nextLessonSuggestions"]
+    if any(k not in data_dict for k in required):
+        raise HTTPException(
+            status_code=422,
+            detail=f"INVALID_GENERATION: missing keys in JSON, required={required}",
+        )
+
+    return ReflectionResponse(data=ReflectionData(**data_dict), meta=meta)
+
+
+# ---------------------------------------------------------------------------
+# 2.6 生成跨期改进提案 (Generate Improvement Proposals)
+# ---------------------------------------------------------------------------
+
+
+class ImprovementRequest(BaseModel):
+    requestId: str
+    reflectionReports: List[Any]
+
+
+class ImprovementProposal(BaseModel):
+    title: str
+    priority: str
+    affectedWeeks: Optional[str] = None
+    evidence: Optional[str] = None
+    rootCause: Optional[str] = None
+    proposedSolution: Optional[str] = None
+    expectedImpact: Optional[str] = None
+
+
+class ImprovementData(BaseModel):
+    proposals: List[ImprovementProposal]
+
+
+class ImprovementResponse(BaseModel):
+    data: ImprovementData
+    meta: Meta
+
+
+@router.post("/improvement/generate", response_model=ImprovementResponse)
+def generate_improvement(req: ImprovementRequest):
+    """Phase 5 (Improve)：基于过往反思报告生成跨期改进提案。"""
+    reports = json.dumps(req.reflectionReports, ensure_ascii=False)
+    sys_prompt = (
+        "You are an AI curriculum improvement assistant. "
+        "Given past reflection reports, generate high-level improvement proposals as JSON."
+    )
+    user_prompt = f"""
+Past reflection reports (opaque JSON array):
+{reports}
+
+Return JSON:
+{{
+  "proposals": [
+    {{
+      "title": "Students struggle with gradient descent optimization",
+      "priority": "High Priority | Medium Priority | Low Priority",
+      "affectedWeeks": "Week 2, 3",
+      "evidence": "45% reported difficulty...",
+      "rootCause": "Introduced too quickly without visual math foundation.",
+      "proposedSolution": "Split gradient descent into two lessons: (1) Intuition (2) Math.",
+      "expectedImpact": "Increase scores by 15-20% and reduce frustration."
+    }}
+  ]
+}}
+"""
+
+    data_dict, meta = _call_openai_json("improvement.generate", sys_prompt, user_prompt, temperature=0.4)
+    if "proposals" not in data_dict:
+        raise HTTPException(status_code=422, detail="INVALID_GENERATION: 'proposals' missing in JSON.")
+
+    return ImprovementResponse(data=ImprovementData(**data_dict), meta=meta)
+

api/server.py

@@ -36,6 +36,7 @@ from api.routes_directory import router as directory_router
 from api.routes_teacher import router as teacher_router
 # ✅ Courseware：课程愿景、活动设计、课堂助教、QA 优化、教案与 PPT
 from api.routes_courseware import router as courseware_router
+from api.routes_courseware_ai import router as courseware_ai_router
 
 # ✅ LangSmith (optional)
 try:
@@ -99,6 +100,7 @@ app.add_middleware(
 app.include_router(directory_router)
 app.include_router(teacher_router)
 app.include_router(courseware_router)
+app.include_router(courseware_ai_router)
 
 # ----------------------------
 # Static hosting (Vite build)

docs/AI_COURSEWARE_API_USAGE.md

@@ -0,0 +1,249 @@
+## AI Courseware 结构化 API 使用说明（前后端协作）
+
+本说明基于《AI Courseware AI 接口文档 v1.0》，结合当前 Clare Courseware 实现，帮助前端与其他后端服务正确调用 AI 课程设计相关接口。
+
+---
+
+### 1. 服务 Base URL 与部署
+
+- 所有接口均由 Clare 后端 (`api/server.py`) 暴露。
+- 部署在本地开发环境时：
+  - Base URL 通常为 `http://localhost:8000`
+- 部署在 Hugging Face Space 或其他环境时：
+  - 前端通过 Vite 环境变量 `VITE_API_BASE` 配置 Base URL
+  - 例如：`VITE_API_BASE=https://your-space.hf.space`
+
+> 下文统一用 `{{BASE}}` 表示后端根地址（如 `http://localhost:8000`）。
+
+---
+
+### 2. 路由概览
+
+#### 2.1 现有 Clare Teacher/Courseware 接口（非结构化文本）
+
+这些接口主要给当前 Clare 前端使用，返回 Markdown/文本：
+
+- `POST {{BASE}}/api/courseware/vision`
+- `POST {{BASE}}/api/courseware/activities`
+- `POST {{BASE}}/api/courseware/copilot`
+- `POST {{BASE}}/api/courseware/qa-optimize`
+- `POST {{BASE}}/api/courseware/content`
+
+对应的前端封装函数在 `web/src/lib/api.ts` 中：
+
+- `apiCoursewareVision`
+- `apiCoursewareActivities`
+- `apiCoursewareCopilot`
+- `apiCoursewareQAOptimize`
+- `apiCoursewareContent`
+
+#### 2.2 新增 AI Courseware 结构化接口（建议给 LMS/独立前端用）
+
+新路由前缀：`/ai/courseware`，在 `api/routes_courseware_ai.py` 中实现，返回结构化 JSON (`data + meta`)：
+
+1. **生成大纲草案**  
+   - `POST {{BASE}}/ai/courseware/syllabus/generate`
+2. **生成单个模块的教学流程**  
+   - `POST {{BASE}}/ai/courseware/flow/generate`
+3. **局部重构教学流程（Copilot）**  
+   - `POST {{BASE}}/ai/courseware/flow/regenerate-partial`
+4. **生成/润色教案长文**  
+   - `POST {{BASE}}/ai/courseware/plan/detail/generate`
+5. **生成反思看板数据**  
+   - `POST {{BASE}}/ai/courseware/reflection/generate`
+6. **生成跨期改进提案**  
+   - `POST {{BASE}}/ai/courseware/improvement/generate`
+
+所有成功响应都遵循统一包装：
+
+```json
+{
+  "data": { ... },   // 每个接口自己的数据结构
+  "meta": {
+    "model": "gpt-4o",
+    "model_version": null,
+    "prompt_version": "v1.0",
+    "temperature": 0.4,
+    "tokens_used": 1234,
+    "latency_ms": 5678
+  }
+}
+```
+
+`meta` 由后端统一生成，包含模型、Prompt 版本、token 消耗和延迟，便于监控。
+
+---
+
+### 3. 前端 TypeScript 封装（`web/src/lib/api.ts`）
+
+前端已经在 `web/src/lib/api.ts` 中提供了 6 个结构化接口的封装函数，可直接在 React 组件中调用。
+
+#### 3.1 生成大纲草案 `apiAiSyllabusGenerate`
+
+```ts
+import {
+  apiAiSyllabusGenerate,
+  type AiSyllabusGenerateReq,
+  type AiSyllabusGenerateResp,
+} from "@/lib/api";
+
+const req: AiSyllabusGenerateReq = {
+  requestId: "req_cw_101",
+  context: {
+    courseName: "IST 345 Building Generative AI Application",
+    learningOutcome: "Understand LLMs and build a RAG application",
+    studentLevel: "BEGINNER",
+    teachingFocus: "PRACTICE_ORIENTED",
+    courseLength: 4,
+  },
+};
+
+const resp: AiSyllabusGenerateResp = await apiAiSyllabusGenerate(req);
+// resp.data.syllabus -> Week 级别数组
+// resp.meta -> 模型与性能信息
+```
+
+#### 3.2 生成单个模块的教学流程 `apiAiFlowGenerate`
+
+```ts
+import {
+  apiAiFlowGenerate,
+  type AiFlowGenerateReq,
+  type AiFlowGenerateResp,
+} from "@/lib/api";
+
+const req: AiFlowGenerateReq = {
+  requestId: "req_cw_102",
+  moduleContext: {
+    title: "Introduction to Generative AI",
+    learningObjectives: ["Understand basic LLM concepts"],
+    topics: ["History of AI", "Transformer Architecture"],
+    durationMinutes: 90,
+  },
+  systemPrompts: ["(可选) 来自 Improve 阶段的长期提示"],
+};
+
+const resp: AiFlowGenerateResp = await apiAiFlowGenerate(req);
+// resp.data.steps -> 每个 step 含 type/title/estimated_duration/ai_understanding
+```
+
+#### 3.3 局部重构教学流程 `apiAiFlowRegeneratePartial`
+
+```ts
+import {
+  apiAiFlowRegeneratePartial,
+  type AiFlowPartialReq,
+  type AiFlowPartialResp,
+} from "@/lib/api";
+
+const req: AiFlowPartialReq = {
+  requestId: "req_cw_103",
+  prompt: "Split the 30-min explanation into two shorter parts with a quiz in between.",
+  currentFlow: {
+    lockedSteps: [{ id: "step_1", title: "Welcome", duration: 15 }],
+    unlockedSteps: [{ id: "step_2", title: "Heavy Explanation", duration: 30 }],
+  },
+};
+
+const resp: AiFlowPartialResp = await apiAiFlowRegeneratePartial(req);
+// resp.data.explanation -> Copilot 气泡文案
+// resp.data.proposedSteps -> 用于替换 unlockedSteps 的新步骤
+```
+
+#### 3.4 教案长文 `apiAiPlanDetailGenerate`
+
+```ts
+import {
+  apiAiPlanDetailGenerate,
+  type AiPlanDetailReq,
+  type AiPlanDetailResp,
+} from "@/lib/api";
+
+const req: AiPlanDetailReq = {
+  requestId: "req_cw_104",
+  finalizedSteps: stepsArray, // 来自 Flow 阶段确定的完整 steps
+};
+
+const resp: AiPlanDetailResp = await apiAiPlanDetailGenerate(req);
+// resp.data.sections -> 多个 section（Lesson Objectives / Content 等），content 支持 Markdown
+```
+
+#### 3.5 反思看板 `apiAiReflectionGenerate`
+
+```ts
+import {
+  apiAiReflectionGenerate,
+  type AiReflectionReq,
+  type AiReflectionResp,
+} from "@/lib/api";
+
+const req: AiReflectionReq = {
+  requestId: "req_cw_105",
+  teachAnnotations: [
+    {
+      category: "NEEDS_MORE_TIME",
+      selectedText: "Gradient Descent",
+      feedback: "Students were confused by the math",
+    },
+  ],
+  quizAggregations: {
+    averageScore: 72,
+    lowestTopic: "Matrix Operations",
+  },
+};
+
+const resp: AiReflectionResp = await apiAiReflectionGenerate(req);
+// resp.data.understanding / engagement / difficulty / misconceptions / nextLessonSuggestions
+```
+
+#### 3.6 改进提案 `apiAiImprovementGenerate`
+
+```ts
+import {
+  apiAiImprovementGenerate,
+  type AiImprovementReq,
+  type AiImprovementResp,
+} from "@/lib/api";
+
+const req: AiImprovementReq = {
+  requestId: "req_cw_106",
+  reflectionReports: previousReflectionReports, // 来自 2.5 的历史数据数组
+};
+
+const resp: AiImprovementResp = await apiAiImprovementGenerate(req);
+// resp.data.proposals -> 每条包含 title/priority/affectedWeeks/evidence/rootCause/proposedSolution/expectedImpact
+```
+
+---
+
+### 4. 后端如何配置 OpenAI 模型（固定为 gpt‑4o）
+
+后端 `api/config.py` 使用环境变量 `CLARE_DEFAULT_MODEL` 控制默认模型：
+
+```python
+DEFAULT_MODEL = (os.getenv("CLARE_DEFAULT_MODEL") or "gpt-4.1-mini").strip()
+```
+
+在 Hugging Face Space（或其他部署环境）中：
+
+- 打开 **Settings → Variables and secrets**
+- 设置：
+
+```text
+CLARE_DEFAULT_MODEL = gpt-4o
+```
+
+这样，上述所有 `/ai/courseware/...` 接口默认都会使用 `gpt-4o`，同时 `meta.model` 字段会反映真实模型名称，便于前端或监控系统做统计。
+
+---
+
+### 5. 错误处理约定
+
+- 若 OpenAI 调用失败：后端返回 `500`，`detail` 内含错误信息。
+- 若 LLM 返回的内容不是合法 JSON 或缺少关键字段：
+  - 返回 `422 INVALID_GENERATION`，`detail` 会说明缺失的字段或解析失败原因。
+- 前端封装函数（`apiAi*` 系列）若收到非 2xx，会抛出 `Error`，错误信息来源：
+  - `data.error` / `data.detail` / `data.message` / 自定义 fallback。
+
+前端在捕获异常时可以统一提示“AI 生成失败，请稍后重试”，并记录 `requestId` 以便后端排查。 
+

docs/TEACHER_AGENT.md

@@ -25,7 +25,7 @@
 
 与 ClareVoice 相同：在环境变量或 `.env` 中配置：
 
-- `WEAVIATE_URL`：Weaviate Cloud 集群地址（如 `https://xxx.c0.us-west3.gcp.weaviate.cloud`）
+- `WEAVIATE_URL`：Weaviate Cloud 集群地址（如 `https://riiqvgc7tuum6cgwhik9ra.c0.us-west3.gcp.weaviate.cloud`）
 - `WEAVIATE_API_KEY`：API Key
 - `WEAVIATE_COLLECTION`：可选，默认 `GenAICourses`
 

web/src/lib/api.ts

@@ -580,3 +580,300 @@ export async function apiCoursewareContent(payload: {
   if (!res.ok) throw new Error(errMsg(data, "Content generation failed"));
   return data as { content: string; weaviate_used: boolean };
 }
+
+// -------------------- AI Courseware structured APIs (Plan / Prepare / Reflect / Improve) --------------------
+
+export type AiMeta = {
+  model: string;
+  model_version?: string | null;
+  prompt_version: string;
+  temperature: number;
+  tokens_used: number;
+  latency_ms: number;
+};
+
+// 2.1 Generate Syllabus Preview
+export type AiSyllabusContext = {
+  courseName: string;
+  learningOutcome: string;
+  studentLevel: string;
+  teachingFocus: string;
+  courseLength: number;
+};
+
+export type AiSyllabusGenerateReq = {
+  requestId: string;
+  context: AiSyllabusContext;
+};
+
+export type AiWeekSyllabus = {
+  weekNumber: number;
+  title: string;
+  learningObjectives: string[];
+  topics: string[];
+};
+
+export type AiSyllabusGenerateResp = {
+  data: { syllabus: AiWeekSyllabus[] };
+  meta: AiMeta;
+};
+
+export async function apiAiSyllabusGenerate(
+  payload: AiSyllabusGenerateReq
+): Promise<AiSyllabusGenerateResp> {
+  const base = getBaseUrl();
+  const res = await fetchWithTimeout(
+    `${base}/ai/courseware/syllabus/generate`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    },
+    TEACHER_TIMEOUT_MS
+  );
+  const data = await parseJsonSafe(res);
+  if (!res.ok) throw new Error(errMsg(data, "AI syllabus generate failed"));
+  return data as AiSyllabusGenerateResp;
+}
+
+// 2.2 Generate Lesson Flow
+export type AiModuleContext = {
+  title: string;
+  learningObjectives: string[];
+  topics: string[];
+  durationMinutes: number;
+};
+
+export type AiFlowGenerateReq = {
+  requestId: string;
+  moduleContext: AiModuleContext;
+  systemPrompts?: string[] | null;
+};
+
+export type AiLessonStep = {
+  type: string;
+  title: string;
+  estimated_duration: number;
+  ai_understanding: string;
+};
+
+export type AiFlowGenerateResp = {
+  data: { steps: AiLessonStep[] };
+  meta: AiMeta;
+};
+
+export async function apiAiFlowGenerate(
+  payload: AiFlowGenerateReq
+): Promise<AiFlowGenerateResp> {
+  const base = getBaseUrl();
+  const res = await fetchWithTimeout(
+    `${base}/ai/courseware/flow/generate`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    },
+    TEACHER_TIMEOUT_MS
+  );
+  const data = await parseJsonSafe(res);
+  if (!res.ok) throw new Error(errMsg(data, "AI flow generate failed"));
+  return data as AiFlowGenerateResp;
+}
+
+// 2.3 Regenerate Partial Flow
+export type AiSimpleStep = {
+  id: string;
+  title: string;
+  duration: number;
+};
+
+export type AiCurrentFlow = {
+  lockedSteps: AiSimpleStep[];
+  unlockedSteps: AiSimpleStep[];
+};
+
+export type AiFlowPartialReq = {
+  requestId: string;
+  prompt: string;
+  currentFlow: AiCurrentFlow;
+};
+
+export type AiCopilotProposedStep = {
+  type: string;
+  title: string;
+  estimated_duration: number;
+  ai_understanding: string;
+};
+
+export type AiFlowPartialResp = {
+  data: {
+    explanation: string;
+    proposedSteps: AiCopilotProposedStep[];
+  };
+  meta: AiMeta;
+};
+
+export async function apiAiFlowRegeneratePartial(
+  payload: AiFlowPartialReq
+): Promise<AiFlowPartialResp> {
+  const base = getBaseUrl();
+  const res = await fetchWithTimeout(
+    `${base}/ai/courseware/flow/regenerate-partial`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    },
+    TEACHER_TIMEOUT_MS
+  );
+  const data = await parseJsonSafe(res);
+  if (!res.ok) throw new Error(errMsg(data, "AI flow partial regenerate failed"));
+  return data as AiFlowPartialResp;
+}
+
+// 2.4 Generate/Polish Lesson Plan Detail
+export type AiPlanDetailReq = {
+  requestId: string;
+  finalizedSteps: any[];
+};
+
+export type AiLessonSection = {
+  section_id: string;
+  type: string;
+  content: string;
+};
+
+export type AiPlanDetailResp = {
+  data: { sections: AiLessonSection[] };
+  meta: AiMeta;
+};
+
+export async function apiAiPlanDetailGenerate(
+  payload: AiPlanDetailReq
+): Promise<AiPlanDetailResp> {
+  const base = getBaseUrl();
+  const res = await fetchWithTimeout(
+    `${base}/ai/courseware/plan/detail/generate`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    },
+    TEACHER_TIMEOUT_MS
+  );
+  const data = await parseJsonSafe(res);
+  if (!res.ok) throw new Error(errMsg(data, "AI plan detail generate failed"));
+  return data as AiPlanDetailResp;
+}
+
+// 2.5 Generate Reflection Report
+export type AiTeachAnnotation = {
+  category: string;
+  selectedText?: string | null;
+  feedback?: string | null;
+};
+
+export type AiQuizAggregations = {
+  averageScore?: number | null;
+  lowestTopic?: string | null;
+};
+
+export type AiReflectionReq = {
+  requestId: string;
+  teachAnnotations: AiTeachAnnotation[];
+  quizAggregations?: AiQuizAggregations | null;
+};
+
+export type AiReflectionUnderstanding = {
+  status: string;
+  summary: string;
+  bulletPoints?: string[] | null;
+};
+
+export type AiReflectionEngagement = {
+  status: string;
+  summary?: string | null;
+};
+
+export type AiReflectionDifficulty = {
+  status: string;
+  challengingTopics?: any[] | null;
+};
+
+export type AiReflectionMisconception = {
+  status: string;
+  issues?: any[] | null;
+};
+
+export type AiNextLessonSuggestion = {
+  actionText: string;
+  deepLinkType?: string | null;
+};
+
+export type AiReflectionResp = {
+  data: {
+    understanding: AiReflectionUnderstanding;
+    engagement: AiReflectionEngagement;
+    difficulty: AiReflectionDifficulty;
+    misconceptions: AiReflectionMisconception;
+    nextLessonSuggestions: AiNextLessonSuggestion[];
+  };
+  meta: AiMeta;
+};
+
+export async function apiAiReflectionGenerate(
+  payload: AiReflectionReq
+): Promise<AiReflectionResp> {
+  const base = getBaseUrl();
+  const res = await fetchWithTimeout(
+    `${base}/ai/courseware/reflection/generate`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    },
+    TEACHER_TIMEOUT_MS
+  );
+  const data = await parseJsonSafe(res);
+  if (!res.ok) throw new Error(errMsg(data, "AI reflection generate failed"));
+  return data as AiReflectionResp;
+}
+
+// 2.6 Generate Improvement Proposals
+export type AiImprovementReq = {
+  requestId: string;
+  reflectionReports: any[];
+};
+
+export type AiImprovementProposal = {
+  title: string;
+  priority: string;
+  affectedWeeks?: string | null;
+  evidence?: string | null;
+  rootCause?: string | null;
+  proposedSolution?: string | null;
+  expectedImpact?: string | null;
+};
+
+export type AiImprovementResp = {
+  data: { proposals: AiImprovementProposal[] };
+  meta: AiMeta;
+};
+
+export async function apiAiImprovementGenerate(
+  payload: AiImprovementReq
+): Promise<AiImprovementResp> {
+  const base = getBaseUrl();
+  const res = await fetchWithTimeout(
+    `${base}/ai/courseware/improvement/generate`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    },
+    TEACHER_TIMEOUT_MS
+  );
+  const data = await parseJsonSafe(res);
+  if (!res.ok) throw new Error(errMsg(data, "AI improvement generate failed"));
+  return data as AiImprovementResp;
+}