Switch AI courseware APIs to snake_case schema

api/routes_courseware_ai.py

@@ -14,7 +14,7 @@ AI Courseware AI 接口 (Plan / Prepare / Reflect / Improve)。
 
 import json
 import time
-from typing import List, Optional, Any
+from typing import List, Optional, Any, Dict
 
 from fastapi import APIRouter, HTTPException
 from pydantic import BaseModel, Field
@@ -112,31 +112,32 @@ def _call_openai_json(
 
 
 class SyllabusContext(BaseModel):
-    courseName: str
-    learningOutcome: str
-    studentLevel: str
-    teachingFocus: str
-    courseLength: int = Field(..., ge=1, le=52)
+    course_name: str
+    learning_outcome: str
+    student_level: str
+    teaching_focus: str
+    course_length: int = Field(..., ge=1, le=52)
 
 
 class SyllabusGenerateRequest(BaseModel):
-    requestId: str
+    request_id: str
     context: SyllabusContext
+    system_prompts: Optional[List[str]] = None
 
 
 class WeekSyllabus(BaseModel):
-    weekNumber: int
+    week_number: int
     title: str
-    learningObjectives: List[str]
+    learning_objectives: List[str]
     topics: List[str]
 
 
 class SyllabusGenerateData(BaseModel):
-    courseOverview: str | None = None
+    course_overview: str | None = None
     assessment: str | None = None
-    teachingApproach: str | None = None
-    workloadExpectation: str | None = None
-    academicIntegrityPolicy: str | None = None
+    teaching_approach: str | None = None
+    workload_expectation: str | None = None
+    academic_integrity_policy: str | None = None
     syllabus: List[WeekSyllabus]
 
 
@@ -149,37 +150,42 @@ class SyllabusGenerateResponse(BaseModel):
 def generate_syllabus(req: SyllabusGenerateRequest):
     """Phase 1 (Plan)：根据课程元数据生成 Weeks/Modules 大纲草案。"""
     ctx = req.context
+    extra_system = "\n".join(req.system_prompts or [])
     sys_prompt = (
         "You are an instructional designer. "
         "Given course metadata, generate a weekly syllabus and key syllabus header fields as JSON. "
-        "Output ONLY a JSON object with keys 'courseOverview', 'assessment', 'teachingApproach', "
-        "'workloadExpectation', 'academicIntegrityPolicy', and 'syllabus', matching the provided schema."
+        "Output ONLY a JSON object using snake_case keys: "
+        "'course_overview', 'assessment', 'teaching_approach', "
+        "'workload_expectation', 'academic_integrity_policy', and 'syllabus'."
     )
     user_prompt = f"""
-Course name: {ctx.courseName}
-Learning outcome: {ctx.learningOutcome}
-Student level: {ctx.studentLevel}
-Teaching focus: {ctx.teachingFocus}
-Total weeks/modules: {ctx.courseLength}
+Course name: {ctx.course_name}
+Learning outcome: {ctx.learning_outcome}
+Student level: {ctx.student_level}
+Teaching focus: {ctx.teaching_focus}
+Total weeks/modules: {ctx.course_length}
+
+Additional long-term system prompts (optional, may be empty):
+{extra_system}
 
 Return JSON:
 {{
-  "courseOverview": "One short paragraph course overview",
+  "course_overview": "One short paragraph course overview",
   "assessment": "Assessment breakdown text...",
-  "teachingApproach": "How the course will be taught...",
-  "workloadExpectation": "Expected weekly workload...",
-  "academicIntegrityPolicy": "Short academic integrity policy...",
+  "teaching_approach": "How the course will be taught...",
+  "workload_expectation": "Expected weekly workload...",
+  "academic_integrity_policy": "Short academic integrity policy...",
   "syllabus": [
     {{
-      "weekNumber": 1,
+      "week_number": 1,
       "title": "string",
-      "learningObjectives": ["string", "..."],
+      "learning_objectives": ["string", "..."],
       "topics": ["string", "..."]
     }},
     ...
   ]
 }}
-Make sure the array length equals courseLength ({ctx.courseLength}) and weekNumber starts from 1.
+Make sure the array length equals course_length ({ctx.course_length}) and week_number starts from 1.
 """
 
     data_dict, meta = _call_openai_json("syllabus.generate", sys_prompt, user_prompt, temperature=0.4)
@@ -195,27 +201,27 @@ Make sure the array length equals courseLength ({ctx.courseLength}) and weekNumb
 
 
 class SyllabusLockedSections(BaseModel):
-    courseOverview: Optional[str] = None
+    course_overview: Optional[str] = None
     assessment: Optional[str] = None
-    teachingApproach: Optional[str] = None
-    workloadExpectation: Optional[str] = None
-    academicIntegrityPolicy: Optional[str] = None
+    teaching_approach: Optional[str] = None
+    workload_expectation: Optional[str] = None
+    academic_integrity_policy: Optional[str] = None
+    syllabus: Optional[List[Dict[str, Any]]] = None
 
 
 class SyllabusUnlockedSections(BaseModel):
-    # 目前仅支持对 syllabus 数组进行重写；保留为任意对象数组以兼容前端裁剪字段
-    syllabus: List[dict] = Field(default_factory=list)
+    syllabus: List[Dict[str, Any]] = Field(default_factory=list)
 
 
 class CurrentSyllabus(BaseModel):
-    lockedSections: SyllabusLockedSections
-    unlockedSections: SyllabusUnlockedSections
+    locked_sections: SyllabusLockedSections
+    unlocked_sections: SyllabusUnlockedSections
 
 
 class SyllabusPartialRequest(BaseModel):
-    requestId: str
+    request_id: str
     prompt: str
-    currentSyllabus: CurrentSyllabus
+    current_syllabus: CurrentSyllabus
     context: SyllabusContext
 
 
@@ -236,8 +242,8 @@ class SyllabusPartialResponse(BaseModel):
 @router.post("/syllabus/regenerate-partial", response_model=SyllabusPartialResponse)
 def regenerate_partial_syllabus(req: SyllabusPartialRequest):
     """Phase 1 (Plan)：在锁定部分大纲后，根据 Prompt 重写未锁定部分（主要是 syllabus 数组）。"""
-    locked_sections = req.currentSyllabus.lockedSections.model_dump()
-    unlocked_sections = req.currentSyllabus.unlockedSections.model_dump()
+    locked_sections = req.current_syllabus.locked_sections.model_dump()
+    unlocked_sections = req.current_syllabus.unlocked_sections.model_dump()
     ctx = req.context
 
     sys_prompt = (
@@ -252,11 +258,11 @@ User prompt:
 {req.prompt}
 
 Course context:
-- courseName: {ctx.courseName}
-- learningOutcome: {ctx.learningOutcome}
-- studentLevel: {ctx.studentLevel}
-- teachingFocus: {ctx.teachingFocus}
-- courseLength: {ctx.courseLength}
+- course_name: {ctx.course_name}
+- learning_outcome: {ctx.learning_outcome}
+- student_level: {ctx.student_level}
+- teaching_focus: {ctx.teaching_focus}
+- course_length: {ctx.course_length}
 
 Locked sections (MUST remain unchanged, only for your reference):
 {json.dumps(locked_sections, ensure_ascii=False)}
@@ -270,9 +276,9 @@ Return JSON:
   "proposed_draft": {{
     "syllabus": [
       {{
-        "weekNumber": 1,
+        "week_number": 1,
         "title": "string",
-        "learningObjectives": ["string", "..."],
+        "learning_objectives": ["string", "..."],
         "topics": ["string", "..."]
       }}
     ]
@@ -305,26 +311,26 @@ Return JSON:
 
 class ModuleContext(BaseModel):
     title: str
-    learningObjectives: List[str]
+    learning_objectives: List[str]
     topics: List[str]
-    durationMinutes: int = Field(..., ge=10, le=600)
+    duration_minutes: int = Field(..., ge=10, le=600)
 
 
 class FlowGenerateRequest(BaseModel):
-    requestId: str
-    moduleContext: ModuleContext
-    systemPrompts: Optional[List[str]] = None
+    request_id: str
+    module_context: ModuleContext
+    system_prompts: Optional[List[str]] = None
 
 
 class LessonStep(BaseModel):
     type: str
     title: str
-    estimatedDuration: int = Field(..., ge=1)
-    aiUnderstanding: str
-    teacherActivity: Optional[str] = None
-    studentActivity: Optional[str] = None
-    guidingQuestions: Optional[str] = None
-    requiredMaterials: Optional[str] = None
+    estimated_duration: int = Field(..., ge=1)
+    ai_understanding: str
+    teacher_activity: Optional[str] = None
+    student_activity: Optional[str] = None
+    guiding_questions: Optional[str] = None
+    required_materials: Optional[str] = None
 
 
 class FlowGenerateData(BaseModel):
@@ -339,8 +345,8 @@ class FlowGenerateResponse(BaseModel):
 @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 [])
+    mc = req.module_context
+    extra_system = "\n".join(req.system_prompts or [])
     sys_prompt = (
         "You are an AI courseware copilot. "
         "Generate a detailed lesson flow for one module as JSON. "
@@ -348,9 +354,9 @@ def generate_lesson_flow(req: FlowGenerateRequest):
     )
     user_prompt = f"""
 Module title: {mc.title}
-Learning objectives: {mc.learningObjectives}
+Learning objectives: {mc.learning_objectives}
 Topics: {mc.topics}
-Duration (minutes): {mc.durationMinutes}
+Duration (minutes): {mc.duration_minutes}
 
 Additional long-term system prompts (optional, may be empty):
 {extra_system}
@@ -361,17 +367,17 @@ Return JSON:
     {{
       "type": "Teacher Explanation | Interactive Quiz | Group Discussion | ...",
       "title": "string",
-      "estimatedDuration": 10,
-      "aiUnderstanding": "short explanation of why this step exists and what it should achieve",
-      "teacherActivity": "what the teacher should concretely do/say in this step",
-      "studentActivity": "what students are expected to do",
-      "guidingQuestions": "- question 1\\n- question 2",
-      "requiredMaterials": "Projector, handouts, whiteboard, ..."
+      "estimated_duration": 10,
+      "ai_understanding": "short explanation of why this step exists and what it should achieve",
+      "teacher_activity": "what the teacher should concretely do/say in this step",
+      "student_activity": "what students are expected to do",
+      "guiding_questions": "- question 1\\n- question 2",
+      "required_materials": "Projector, handouts, whiteboard, ..."
     }},
     ...
   ]
 }}
-The total sum of estimatedDuration should be roughly close to durationMinutes ({mc.durationMinutes}).
+The total sum of estimated_duration should be roughly close to duration_minutes ({mc.duration_minutes}).
 """
 
     data_dict, meta = _call_openai_json("flow.generate", sys_prompt, user_prompt, temperature=0.5)
@@ -393,30 +399,30 @@ class SimpleStep(BaseModel):
 
 
 class CurrentFlow(BaseModel):
-    lockedSteps: List[SimpleStep]
-    unlockedSteps: List[SimpleStep]
+    locked_steps: List[SimpleStep]
+    unlocked_steps: List[SimpleStep]
 
 
 class FlowPartialRequest(BaseModel):
-    requestId: str
+    request_id: str
     prompt: str
-    currentFlow: CurrentFlow
+    current_flow: CurrentFlow
 
 
 class CopilotProposedStep(BaseModel):
     type: str
     title: str
-    estimatedDuration: int
-    aiUnderstanding: str
-    teacherActivity: Optional[str] = None
-    studentActivity: Optional[str] = None
-    guidingQuestions: Optional[str] = None
-    requiredMaterials: Optional[str] = None
+    estimated_duration: int
+    ai_understanding: str
+    teacher_activity: Optional[str] = None
+    student_activity: Optional[str] = None
+    guiding_questions: Optional[str] = None
+    required_materials: Optional[str] = None
 
 
 class FlowPartialData(BaseModel):
     explanation: str
-    proposedSteps: List[CopilotProposedStep]
+    proposed_steps: List[CopilotProposedStep]
 
 
 class FlowPartialResponse(BaseModel):
@@ -427,8 +433,8 @@ class FlowPartialResponse(BaseModel):
 @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]
+    locked = [s.model_dump() for s in req.current_flow.locked_steps]
+    unlocked = [s.model_dump() for s in req.current_flow.unlocked_steps]
     sys_prompt = (
         "You are an AI copilot for lesson flow editing. "
         "Given lockedSteps and unlockedSteps plus a user prompt, "
@@ -446,16 +452,16 @@ unlockedSteps: {unlocked}
 Return JSON:
 {{
   "explanation": "short natural language explanation for the teacher UI bubble",
-  "proposedSteps": [
+  "proposed_steps": [
     {{
       "type": "Teacher Explanation | Interactive Quiz | Group Discussion | ...",
       "title": "string",
-      "estimatedDuration": 10,
-      "aiUnderstanding": "short explanation of this step",
-      "teacherActivity": "what the teacher should concretely do/say in this step",
-      "studentActivity": "what students are expected to do",
-      "guidingQuestions": "- question 1\\n- question 2",
-      "requiredMaterials": "Projector, handouts, whiteboard, ..."
+      "estimated_duration": 10,
+      "ai_understanding": "short explanation of this step",
+      "teacher_activity": "what the teacher should concretely do/say in this step",
+      "student_activity": "what students are expected to do",
+      "guiding_questions": "- question 1\\n- question 2",
+      "required_materials": "Projector, handouts, whiteboard, ..."
     }}
   ]
 }}
@@ -464,10 +470,10 @@ Return JSON:
     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:
+    if "explanation" not in data_dict or "proposed_steps" not in data_dict:
         raise HTTPException(
             status_code=422,
-            detail="INVALID_GENERATION: 'explanation' or 'proposedSteps' missing in JSON.",
+            detail="INVALID_GENERATION: 'explanation' or 'proposed_steps' missing in JSON.",
         )
 
     return FlowPartialResponse(data=FlowPartialData(**data_dict), meta=meta)
@@ -479,17 +485,19 @@ Return JSON:
 
 
 class PlanDetailRequest(BaseModel):
-    requestId: str
-    finalizedSteps: List[Any]
+    request_id: str
+    finalized_steps: List[Any]
 
 
 class LessonSection(BaseModel):
     section_id: str
     type: str
+    title: str
     content: str
 
 
 class PlanDetailData(BaseModel):
+    course_name: Optional[str] = None
     sections: List[LessonSection]
 
 
@@ -508,19 +516,22 @@ def generate_plan_detail(req: PlanDetailRequest):
     )
     user_prompt = f"""
 Finalized steps (JSON array, opaque to you but describes lesson flow):
-{json.dumps(req.finalizedSteps, ensure_ascii=False)}
+{json.dumps(req.finalized_steps, ensure_ascii=False)}
 
 Return JSON:
 {{
+  "course_name": "string",
   "sections": [
     {{
-      "section_id": "sec_obj_01",
-      "type": "Lesson Objectives",
+      "section_id": "learning_objectives",
+      "type": "Learning Objectives",
+      "title": "Learning Objectives",
       "content": "By the end of this lesson, students will be able to..."
     }},
     {{
-      "section_id": "sec_content_01",
-      "type": "Content",
+      "section_id": "lesson_activities",
+      "type": "Lesson Activities",
+      "title": "Lesson Activities",
       "content": "### 1. Topic heading\\nDetailed explanation..."
     }}
   ]
@@ -556,54 +567,65 @@ class TeachAnnotation(BaseModel):
 
     dimension: str  # e.g. "TIME" | "DIFFICULTY" | "ENGAGEMENT"
     level: str      # e.g. "LIMITED" | "ADEQUATE" | "STRONG"
-    selectedText: Optional[str] = None
+    selected_text: Optional[str] = None
     feedback: Optional[str] = None
 
 
 class QuizAggregations(BaseModel):
-    averageScore: Optional[float] = None
-    lowestTopic: Optional[str] = None
+    average_score: Optional[float] = None
+    lowest_topic: Optional[str] = None
 
 
 class ReflectionRequest(BaseModel):
-    requestId: str
-    lessonSteps: List[LessonStepForReflection] = Field(default_factory=list)
-    teachAnnotations: List[TeachAnnotation] = Field(default_factory=list)
-    quizAggregations: Optional[QuizAggregations] = None
+    request_id: str
+    lesson_steps: List[LessonStepForReflection] = Field(default_factory=list)
+    teach_annotations: List[TeachAnnotation] = Field(default_factory=list)
+    quiz_aggregations: Optional[QuizAggregations] = None
 
 
-class ReflectionUnderstanding(BaseModel):
-    status: str
-    summary: str
-    bulletPoints: Optional[List[str]] = None
+class ReflectionDetails(BaseModel):
+    description: Optional[str] = None
+    bullet_points: Optional[List[str]] = None
+    challenging_topics: Optional[List[str]] = None
+    issues: Optional[List[str]] = None
 
 
-class ReflectionEngagement(BaseModel):
+class ReflectionField(BaseModel):
     status: str
-    summary: Optional[str] = None
+    summary: str
+    details: ReflectionDetails
 
 
-class ReflectionDifficulty(BaseModel):
-    status: str
-    challengingTopics: Optional[List[dict]] = None
+class UpperSectionFields(BaseModel):
+    understanding: ReflectionField
+    engagement: ReflectionField
+    difficulty: ReflectionField
+    misconceptions: ReflectionField
 
 
-class ReflectionMisconception(BaseModel):
-    status: str
-    issues: Optional[List[dict]] = None
+class UpperSection(BaseModel):
+    description: Optional[str] = None
+    required: bool = True
+    fields: UpperSectionFields
 
 
 class NextLessonSuggestion(BaseModel):
-    actionText: str
-    deepLinkType: Optional[str] = None
+    text: str
+    deep_link_type: Optional[str] = None
+
+
+class LowerSection(BaseModel):
+    summary: str
+    description: Optional[str] = None
+    overall_summary: Optional[str] = None
+    strengths: List[str]
+    next_lesson_suggestions: List[NextLessonSuggestion]
 
 
 class ReflectionData(BaseModel):
-    understanding: ReflectionUnderstanding
-    engagement: ReflectionEngagement
-    difficulty: ReflectionDifficulty
-    misconceptions: ReflectionMisconception
-    nextLessonSuggestions: List[NextLessonSuggestion]
+    overall_status: str
+    upper_section: UpperSection
+    lower_section: LowerSection
 
 
 class ReflectionResponse(BaseModel):
@@ -614,13 +636,15 @@ class ReflectionResponse(BaseModel):
 @router.post("/reflection/generate", response_model=ReflectionResponse)
 def generate_reflection(req: ReflectionRequest):
     """Phase 4 (Reflect)：基于反馈与测验数据生成反思看板。"""
-    lesson_steps = [s.model_dump() for s in req.lessonSteps]
-    annotations = [a.model_dump() for a in req.teachAnnotations]
-    qa = req.quizAggregations.model_dump() if req.quizAggregations else {}
+    lesson_steps = [s.model_dump() for s in req.lesson_steps]
+    annotations = [a.model_dump() for a in req.teach_annotations]
+    qa = req.quiz_aggregations.model_dump() if req.quiz_aggregations else {}
     sys_prompt = (
         "You are an AI teaching analytics assistant. "
-        "Given lesson steps, teacher annotations, and quiz aggregations, generate a reflection dashboard as JSON "
-        "with understanding, engagement, difficulty, misconceptions, and nextLessonSuggestions."
+        "Given lesson steps, teacher annotations, and quiz aggregations, generate a reflection dashboard as JSON. "
+        "Use snake_case keys and match this structure: overall_status, upper_section(fields: understanding/engagement/"
+        "difficulty/misconceptions), and lower_section(summary/strengths/next_lesson_suggestions). "
+        "Output ONLY the JSON object that matches the schema."
     )
     user_prompt = f"""
 Lesson steps:
@@ -634,34 +658,59 @@ Quiz aggregations:
 
 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 | ..."
+  "overall_status": "Overall: Progressing",
+  "upper_section": {{
+    "description": "One short sentence describing the upper section purpose",
+    "required": true,
+    "fields": {{
+      "understanding": {{
+        "status": "Low | Medium | High",
+        "summary": "Comprehension of core concepts",
+        "details": {{
+          "description": "A short paragraph",
+          "bullet_points": ["..."]
+        }}
+      }},
+      "engagement": {{
+        "status": "Low | Medium | High",
+        "summary": "Student participation and motivation",
+        "details": {{
+          "description": "A short paragraph",
+          "bullet_points": ["..."]
+        }}
+      }},
+      "difficulty": {{
+        "status": "Low | Medium | High",
+        "summary": "Challenging topics and areas",
+        "details": {{
+          "description": "A short paragraph",
+          "challenging_topics": ["Topic A (45% struggle)", "Topic B (38% struggle)"]
+        }}
+      }},
+      "misconceptions": {{
+        "status": "Low | Medium | High",
+        "summary": "Common misunderstandings identified",
+        "details": {{
+          "description": "A short paragraph",
+          "issues": ["Misconception A — evidence ...", "Misconception B — evidence ..."]
+        }}
+      }}
     }}
-  ]
+  }},
+  "lower_section": {{
+    "summary": "Lesson 1 Summary",
+    "description": "AI-generated overall assessment and recommendations",
+    "overall_summary": "One paragraph overall summary",
+    "strengths": ["..."],
+    "next_lesson_suggestions": [
+      {{ "text": "Add visual demos ...", "deep_link_type": "PREPARE_FLOW_EDIT" }}
+    ]
+  }}
 }}
 """
 
     data_dict, meta = _call_openai_json("reflection.generate", sys_prompt, user_prompt, temperature=0.4)
-    required = ["understanding", "engagement", "difficulty", "misconceptions", "nextLessonSuggestions"]
+    required = ["overall_status", "upper_section", "lower_section"]
     if any(k not in data_dict for k in required):
         raise HTTPException(
             status_code=422,
@@ -677,18 +726,18 @@ Return JSON:
 
 
 class ImprovementRequest(BaseModel):
-    requestId: str
-    reflectionReports: List[Any]
+    request_id: str
+    reflection_reports: List[Any]
 
 
 class ImprovementProposal(BaseModel):
     title: str
     priority: str
-    affectedWeeks: Optional[str] = None
+    affected_weeks: Optional[str] = None
     evidence: Optional[str] = None
-    rootCause: Optional[str] = None
-    proposedSolution: Optional[str] = None
-    expectedImpact: Optional[str] = None
+    root_cause: Optional[str] = None
+    proposed_solution: Optional[str] = None
+    expected_impact: Optional[str] = None
 
 
 class ImprovementData(BaseModel):
@@ -703,7 +752,7 @@ class ImprovementResponse(BaseModel):
 @router.post("/improvement/generate", response_model=ImprovementResponse)
 def generate_improvement(req: ImprovementRequest):
     """Phase 5 (Improve)：基于过往反思报告生成跨期改进提案。"""
-    reports = json.dumps(req.reflectionReports, ensure_ascii=False)
+    reports = json.dumps(req.reflection_reports, ensure_ascii=False)
     sys_prompt = (
         "You are an AI curriculum improvement assistant. "
         "Given past reflection reports, generate high-level improvement proposals as JSON."
@@ -718,11 +767,11 @@ Return JSON:
     {{
       "title": "Students struggle with gradient descent optimization",
       "priority": "High Priority | Medium Priority | Low Priority",
-      "affectedWeeks": "Week 2, 3",
+      "affected_weeks": "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."
+      "root_cause": "Introduced too quickly without visual math foundation.",
+      "proposed_solution": "Split gradient descent into two lessons: (1) Intuition (2) Math.",
+      "expected_impact": "Increase scores by 15-20% and reduce frustration."
     }}
   ]
 }}

docs/AI_COURSEWARE_API_USAGE.md

@@ -80,7 +80,7 @@
 
 前端已经在 `web/src/lib/api.ts` 中提供了 6 个结构化接口的封装函数，可直接在 React 组件中调用。
 
-#### 3.1 生成大纲草案 `apiAiSyllabusGenerate`
+#### 3.1 生成大纲草案 `apiAiSyllabusGenerate`（snake_case）
 
 ```ts
 import {
@@ -90,27 +90,27 @@ import {
 } from "@/lib/api";
 
 const req: AiSyllabusGenerateReq = {
-  requestId: "req_cw_101",
+  request_id: "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,
+    course_name: "IST 345 Building Generative AI Application",
+    learning_outcome: "Understand LLMs and build a RAG application",
+    student_level: "BEGINNER",
+    teaching_focus: "PRACTICE_ORIENTED",
+    course_length: 4,
   },
 };
 
 const resp: AiSyllabusGenerateResp = await apiAiSyllabusGenerate(req);
-// resp.data.courseOverview -> 课程整体简介（段落）
+// resp.data.course_overview -> 课程整体简介（段落）
 // resp.data.assessment -> 考核方式与比例说明
-// resp.data.teachingApproach -> 教学方式描述
-// resp.data.workloadExpectation -> 学生每周学习负担预期
-// resp.data.academicIntegrityPolicy -> 学术诚信说明（可直接挪用到 Syllabus）
+// resp.data.teaching_approach -> 教学方式描述
+// resp.data.workload_expectation -> 学生每周学习负担预期
+// resp.data.academic_integrity_policy -> 学术诚信说明（可直接挪用到 Syllabus）
 // resp.data.syllabus -> Week 级别数组
 // resp.meta -> 模型与性能信息
 ```
 
-#### 3.2 局部重构大纲草案 `apiAiSyllabusRegeneratePartial`
+#### 3.2 局部重构大纲草案 `apiAiSyllabusRegeneratePartial`（snake_case）
 
 ```ts
 import {
@@ -120,17 +120,17 @@ import {
 } from "@/lib/api";
 
 const req: AiSyllabusPartialReq = {
-  requestId: "req_cw_101b",
+  request_id: "req_cw_101b",
   prompt: "Increase the difficulty and add more details on Transformer.",
-  currentSyllabus: {
-    lockedSections: {
-      courseOverview: "This course provides...",
+  current_syllabus: {
+    locked_sections: {
+      course_overview: "This course provides...",
       assessment: "Weekly Programming Assignments...",
     },
-    unlockedSections: {
+    unlocked_sections: {
       syllabus: [
         {
-          weekNumber: 1,
+          week_number: 1,
           title: "Introduction to Generative AI",
           topics: ["History of AI"],
         },
@@ -138,11 +138,11 @@ const req: AiSyllabusPartialReq = {
     },
   },
   context: {
-    courseName: "IST 345 Building Generative AI Application",
-    learningOutcome: "Understand LLMs and build a RAG application",
-    studentLevel: "BEGINNER",
-    teachingFocus: "PRACTICE_ORIENTED",
-    courseLength: 4,
+    course_name: "IST 345 Building Generative AI Application",
+    learning_outcome: "Understand LLMs and build a RAG application",
+    student_level: "BEGINNER",
+    teaching_focus: "PRACTICE_ORIENTED",
+    course_length: 4,
   },
 };
 
@@ -151,7 +151,7 @@ const resp: AiSyllabusPartialResp = await apiAiSyllabusRegeneratePartial(req);
 // resp.data.proposed_draft.syllabus -> 用于替换未锁定 syllabus 的新大纲
 ```
 
-#### 3.3 生成单个模块的教学流程 `apiAiFlowGenerate`
+#### 3.3 生成单个模块的教学流程 `apiAiFlowGenerate`（snake_case）
 
 ```ts
 import {
@@ -161,26 +161,26 @@ import {
 } from "@/lib/api";
 
 const req: AiFlowGenerateReq = {
-  requestId: "req_cw_102",
-  moduleContext: {
+  request_id: "req_cw_102",
+  module_context: {
     title: "Introduction to Generative AI",
-    learningObjectives: ["Understand basic LLM concepts"],
+    learning_objectives: ["Understand basic LLM concepts"],
     topics: ["History of AI", "Transformer Architecture"],
-    durationMinutes: 90,
+    duration_minutes: 90,
   },
-  systemPrompts: ["(可选) 来自 Improve 阶段的长期提示"],
+  system_prompts: ["(可选) 来自 Improve 阶段的长期提示"],
 };
 
 const resp: AiFlowGenerateResp = await apiAiFlowGenerate(req);
-// resp.data.steps[i].estimatedDuration -> 单步预计时长（分钟）
-// resp.data.steps[i].aiUnderstanding -> AI 对该步骤教学意图的摘要
-// resp.data.steps[i].teacherActivity -> 教师在该步骤的具体行为/讲解要点
-// resp.data.steps[i].studentActivity -> 学生在该步骤预期进行的活动
-// resp.data.steps[i].guidingQuestions -> 建议的引导提问（Markdown 文本）
-// resp.data.steps[i].requiredMaterials -> 所需材料/设备清单
+// resp.data.steps[i].estimated_duration -> 单步预计时长（分钟）
+// resp.data.steps[i].ai_understanding -> AI 对该步骤教学意图的摘要
+// resp.data.steps[i].teacher_activity -> 教师在该步骤的具体行为/讲解要点
+// resp.data.steps[i].student_activity -> 学生在该步骤预期进行的活动
+// resp.data.steps[i].guiding_questions -> 建议的引导提问（Markdown 文本）
+// resp.data.steps[i].required_materials -> 所���材料/设备清单
 ```
 
-#### 3.4 局部重构教学流程 `apiAiFlowRegeneratePartial`
+#### 3.4 局部重构教学流程 `apiAiFlowRegeneratePartial`（snake_case）
 
 ```ts
 import {
@@ -190,20 +190,20 @@ import {
 } from "@/lib/api";
 
 const req: AiFlowPartialReq = {
-  requestId: "req_cw_103",
+  request_id: "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 }],
+  current_flow: {
+    locked_steps: [{ id: "step_1", title: "Welcome", duration: 15 }],
+    unlocked_steps: [{ id: "step_2", title: "Heavy Explanation", duration: 30 }],
   },
 };
 
 const resp: AiFlowPartialResp = await apiAiFlowRegeneratePartial(req);
 // resp.data.explanation -> Copilot 气泡文案
-// resp.data.proposedSteps -> 用于替换 unlockedSteps 的新步骤
+// resp.data.proposed_steps -> 用于替换 unlocked_steps 的新步骤
 ```
 
-#### 3.5 教案长文 `apiAiPlanDetailGenerate`
+#### 3.5 教案长文 `apiAiPlanDetailGenerate`（snake_case）
 
 ```ts
 import {
@@ -213,15 +213,16 @@ import {
 } from "@/lib/api";
 
 const req: AiPlanDetailReq = {
-  requestId: "req_cw_104",
-  finalizedSteps: stepsArray, // 来自 Flow 阶段确定的完整 steps
+  request_id: "req_cw_104",
+  finalized_steps: stepsArray, // 来自 Flow 阶段确定的完整 steps
 };
 
 const resp: AiPlanDetailResp = await apiAiPlanDetailGenerate(req);
-// resp.data.sections -> 多个 section（Lesson Objectives / Content 等），content 支持 Markdown
+// resp.data.course_name -> 课程名（可选）
+// resp.data.sections -> 多个 section（含 section_id/type/title/content），content 支持 Markdown
 ```
 
-#### 3.6 反思看板 `apiAiReflectionGenerate`
+#### 3.6 反思看板 `apiAiReflectionGenerate`（snake_case + 新结构）
 
 ```ts
 import {
@@ -231,25 +232,31 @@ import {
 } from "@/lib/api";
 
 const req: AiReflectionReq = {
-  requestId: "req_cw_105",
-  teachAnnotations: [
+  request_id: "req_cw_105",
+  lesson_steps: [
+    { step_number: 1, title: "Intro", type: "LECTURE", duration: 15 },
+  ],
+  teach_annotations: [
     {
-      category: "NEEDS_MORE_TIME",
-      selectedText: "Gradient Descent",
+      dimension: "TIME",
+      level: "LIMITED",
+      selected_text: "Gradient Descent",
       feedback: "Students were confused by the math",
     },
   ],
-  quizAggregations: {
-    averageScore: 72,
-    lowestTopic: "Matrix Operations",
+  quiz_aggregations: {
+    average_score: 72,
+    lowest_topic: "Matrix Operations",
   },
 };
 
 const resp: AiReflectionResp = await apiAiReflectionGenerate(req);
-// resp.data.understanding / engagement / difficulty / misconceptions / nextLessonSuggestions
+// resp.data.overall_status
+// resp.data.upper_section.fields.understanding / engagement / difficulty / misconceptions
+// resp.data.lower_section.strengths / next_lesson_suggestions
 ```
 
-#### 3.7 改进提案 `apiAiImprovementGenerate`
+#### 3.7 改进提案 `apiAiImprovementGenerate`（snake_case）
 
 ```ts
 import {
@@ -259,8 +266,8 @@ import {
 } from "@/lib/api";
 
 const req: AiImprovementReq = {
-  requestId: "req_cw_106",
-  reflectionReports: previousReflectionReports, // 来自 2.5 的历史数据数组
+  request_id: "req_cw_106",
+  reflection_reports: previousReflectionReports, // 来自 2.6 的历史数据数组
 };
 
 const resp: AiImprovementResp = await apiAiImprovementGenerate(req);

web/src/lib/api.ts

@@ -594,33 +594,33 @@ export type AiMeta = {
 
 // 2.1 Generate Syllabus Preview
 export type AiSyllabusContext = {
-  courseName: string;
-  learningOutcome: string;
-  studentLevel: string;
-  teachingFocus: string;
-  courseLength: number;
+  course_name: string;
+  learning_outcome: string;
+  student_level: string;
+  teaching_focus: string;
+  course_length: number;
 };
 
 export type AiSyllabusGenerateReq = {
-  requestId: string;
+  request_id: string;
   context: AiSyllabusContext;
-  systemPrompts?: string[] | null;
+  system_prompts?: string[] | null;
 };
 
 export type AiWeekSyllabus = {
-  weekNumber: number;
+  week_number: number;
   title: string;
-  learningObjectives: string[];
+  learning_objectives: string[];
   topics: string[];
 };
 
 export type AiSyllabusGenerateResp = {
   data: {
-    courseOverview?: string | null;
+    course_overview?: string | null;
     assessment?: string | null;
-    teachingApproach?: string | null;
-    workloadExpectation?: string | null;
-    academicIntegrityPolicy?: string | null;
+    teaching_approach?: string | null;
+    workload_expectation?: string | null;
+    academic_integrity_policy?: string | null;
     syllabus: AiWeekSyllabus[];
   };
   meta: AiMeta;
@@ -646,11 +646,12 @@ export async function apiAiSyllabusGenerate(
 
 // 2.2 Regenerate Partial Syllabus
 export type AiSyllabusLockedSections = {
-  courseOverview?: string | null;
+  course_overview?: string | null;
   assessment?: string | null;
-  teachingApproach?: string | null;
-  workloadExpectation?: string | null;
-  academicIntegrityPolicy?: string | null;
+  teaching_approach?: string | null;
+  workload_expectation?: string | null;
+  academic_integrity_policy?: string | null;
+  syllabus?: Partial<AiWeekSyllabus>[] | null;
 };
 
 export type AiSyllabusUnlockedSections = {
@@ -658,14 +659,14 @@ export type AiSyllabusUnlockedSections = {
 };
 
 export type AiCurrentSyllabus = {
-  lockedSections: AiSyllabusLockedSections;
-  unlockedSections: AiSyllabusUnlockedSections;
+  locked_sections: AiSyllabusLockedSections;
+  unlocked_sections: AiSyllabusUnlockedSections;
 };
 
 export type AiSyllabusPartialReq = {
-  requestId: string;
+  request_id: string;
   prompt: string;
-  currentSyllabus: AiCurrentSyllabus;
+  current_syllabus: AiCurrentSyllabus;
   context: AiSyllabusContext;
 };
 
@@ -700,26 +701,26 @@ export async function apiAiSyllabusRegeneratePartial(
 // 2.3 Generate Lesson Flow
 export type AiModuleContext = {
   title: string;
-  learningObjectives: string[];
+  learning_objectives: string[];
   topics: string[];
-  durationMinutes: number;
+  duration_minutes: number;
 };
 
 export type AiFlowGenerateReq = {
-  requestId: string;
-  moduleContext: AiModuleContext;
-  systemPrompts?: string[] | null;
+  request_id: string;
+  module_context: AiModuleContext;
+  system_prompts?: string[] | null;
 };
 
 export type AiLessonStep = {
   type: string;
   title: string;
-  estimatedDuration: number;
-  aiUnderstanding: string;
-  teacherActivity?: string | null;
-  studentActivity?: string | null;
-  guidingQuestions?: string | null;
-  requiredMaterials?: string | null;
+  estimated_duration: number;
+  ai_understanding: string;
+  teacher_activity?: string | null;
+  student_activity?: string | null;
+  guiding_questions?: string | null;
+  required_materials?: string | null;
 };
 
 export type AiFlowGenerateResp = {
@@ -753,31 +754,31 @@ export type AiSimpleStep = {
 };
 
 export type AiCurrentFlow = {
-  lockedSteps: AiSimpleStep[];
-  unlockedSteps: AiSimpleStep[];
+  locked_steps: AiSimpleStep[];
+  unlocked_steps: AiSimpleStep[];
 };
 
 export type AiFlowPartialReq = {
-  requestId: string;
+  request_id: string;
   prompt: string;
-  currentFlow: AiCurrentFlow;
+  current_flow: AiCurrentFlow;
 };
 
 export type AiCopilotProposedStep = {
   type: string;
   title: string;
-  estimatedDuration: number;
-  aiUnderstanding: string;
-  teacherActivity?: string | null;
-  studentActivity?: string | null;
-  guidingQuestions?: string | null;
-  requiredMaterials?: string | null;
+  estimated_duration: number;
+  ai_understanding: string;
+  teacher_activity?: string | null;
+  student_activity?: string | null;
+  guiding_questions?: string | null;
+  required_materials?: string | null;
 };
 
 export type AiFlowPartialResp = {
   data: {
     explanation: string;
-    proposedSteps: AiCopilotProposedStep[];
+    proposed_steps: AiCopilotProposedStep[];
   };
   meta: AiMeta;
 };
@@ -802,18 +803,19 @@ export async function apiAiFlowRegeneratePartial(
 
 // 2.4 Generate/Polish Lesson Plan Detail
 export type AiPlanDetailReq = {
-  requestId: string;
-  finalizedSteps: any[];
+  request_id: string;
+  finalized_steps: any[];
 };
 
 export type AiLessonSection = {
   section_id: string;
   type: string;
+  title: string;
   content: string;
 };
 
 export type AiPlanDetailResp = {
-  data: { sections: AiLessonSection[] };
+  data: { course_name?: string | null; sections: AiLessonSection[] };
   meta: AiMeta;
 };
 
@@ -839,18 +841,18 @@ export async function apiAiPlanDetailGenerate(
 export type AiTeachAnnotation = {
   dimension: string;
   level: string;
-  selectedText?: string | null;
+  selected_text?: string | null;
   feedback?: string | null;
 };
 
 export type AiQuizAggregations = {
-  averageScore?: number | null;
-  lowestTopic?: string | null;
+  average_score?: number | null;
+  lowest_topic?: string | null;
 };
 
 export type AiReflectionReq = {
-  requestId: string;
-  lessonSteps?: {
+  request_id: string;
+  lesson_steps?: {
     step_number: number;
     title: string;
     type: string;
@@ -859,43 +861,52 @@ export type AiReflectionReq = {
     student_activity?: string | null;
     guiding_questions?: string | null;
   }[];
-  teachAnnotations: AiTeachAnnotation[];
-  quizAggregations?: AiQuizAggregations | null;
+  teach_annotations: AiTeachAnnotation[];
+  quiz_aggregations?: AiQuizAggregations | null;
 };
 
-export type AiReflectionUnderstanding = {
-  status: string;
-  summary: string;
-  bulletPoints?: string[] | null;
+export type AiReflectionDetails = {
+  description?: string | null;
+  bullet_points?: string[] | null;
+  challenging_topics?: string[] | null;
+  issues?: string[] | null;
 };
 
-export type AiReflectionEngagement = {
+export type AiReflectionField = {
   status: string;
-  summary?: string | null;
+  summary: string;
+  details: AiReflectionDetails;
 };
 
-export type AiReflectionDifficulty = {
-  status: string;
-  challengingTopics?: any[] | null;
+export type AiUpperSection = {
+  description?: string | null;
+  required: boolean;
+  fields: {
+    understanding: AiReflectionField;
+    engagement: AiReflectionField;
+    difficulty: AiReflectionField;
+    misconceptions: AiReflectionField;
+  };
 };
 
-export type AiReflectionMisconception = {
-  status: string;
-  issues?: any[] | null;
+export type AiNextLessonSuggestion = {
+  text: string;
+  deep_link_type?: string | null;
 };
 
-export type AiNextLessonSuggestion = {
-  actionText: string;
-  deepLinkType?: string | null;
+export type AiLowerSection = {
+  summary: string;
+  description?: string | null;
+  overall_summary?: string | null;
+  strengths: string[];
+  next_lesson_suggestions: AiNextLessonSuggestion[];
 };
 
 export type AiReflectionResp = {
   data: {
-    understanding: AiReflectionUnderstanding;
-    engagement: AiReflectionEngagement;
-    difficulty: AiReflectionDifficulty;
-    misconceptions: AiReflectionMisconception;
-    nextLessonSuggestions: AiNextLessonSuggestion[];
+    overall_status: string;
+    upper_section: AiUpperSection;
+    lower_section: AiLowerSection;
   };
   meta: AiMeta;
 };
@@ -920,18 +931,18 @@ export async function apiAiReflectionGenerate(
 
 // 2.6 Generate Improvement Proposals
 export type AiImprovementReq = {
-  requestId: string;
-  reflectionReports: any[];
+  request_id: string;
+  reflection_reports: any[];
 };
 
 export type AiImprovementProposal = {
   title: string;
   priority: string;
-  affectedWeeks?: string | null;
+  affected_weeks?: string | null;
   evidence?: string | null;
-  rootCause?: string | null;
-  proposedSolution?: string | null;
-  expectedImpact?: string | null;
+  root_cause?: string | null;
+  proposed_solution?: string | null;
+  expected_impact?: string | null;
 };
 
 export type AiImprovementResp = {