Enforce proposed_draft keys for syllabus partial

api/routes_courseware_ai.py

@@ -210,7 +210,9 @@ class SyllabusLockedSections(BaseModel):
 
 
 class SyllabusUnlockedSections(BaseModel):
-    syllabus: List[Dict[str, Any]] = Field(default_factory=list)
+    """允许前端提交多个待重构顶层区块（动态键）。"""
+
+    model_config = {"extra": "allow"}
 
 
 class CurrentSyllabus(BaseModel):
@@ -226,7 +228,9 @@ class SyllabusPartialRequest(BaseModel):
 
 
 class SyllabusPartialDraft(BaseModel):
-    syllabus: List[WeekSyllabus]
+    """proposed_draft 顶层键必须与 unlocked_sections 完全一致。"""
+
+    model_config = {"extra": "allow"}
 
 
 class SyllabusPartialData(BaseModel):
@@ -241,17 +245,19 @@ class SyllabusPartialResponse(BaseModel):
 
 @router.post("/syllabus/regenerate-partial", response_model=SyllabusPartialResponse)
 def regenerate_partial_syllabus(req: SyllabusPartialRequest):
-    """Phase 1 (Plan)：在锁定部分大纲后，根据 Prompt 重写未锁定部分（主要是 syllabus 数组）。"""
+    """Phase 1 (Plan)：在锁定部分大纲后，根据 Prompt 重写未锁定部分（支持多个顶层区块）。"""
     locked_sections = req.current_syllabus.locked_sections.model_dump()
     unlocked_sections = req.current_syllabus.unlocked_sections.model_dump()
     ctx = req.context
 
+    expected_keys = set(unlocked_sections.keys())
     sys_prompt = (
         "You are an AI copilot for course syllabus editing. "
         "Given lockedSections (must NOT be changed), unlockedSections, a user prompt, "
         "and the overall course context, propose a revised draft ONLY for unlockedSections. "
         "Output ONLY JSON with keys 'explanation' and 'proposed_draft'. "
-        "proposed_draft MUST have the same top-level keys as unlockedSections (e.g., 'syllabus')."
+        "proposed_draft MUST have exactly the same top-level key set as unlockedSections "
+        "(same names, same level, snake_case). Do not add extra keys and do not omit any key."
     )
     user_prompt = f"""
 User prompt:
@@ -274,14 +280,12 @@ Return JSON:
 {{
   "explanation": "short natural language explanation for why you changed the unlocked sections",
   "proposed_draft": {{
-    "syllabus": [
-      {{
-        "week_number": 1,
-        "title": "string",
-        "learning_objectives": ["string", "..."],
-        "topics": ["string", "..."]
-      }}
-    ]
+    "syllabus": [{{"week_number": 1, "title": "string", "learning_objectives": ["..."], "topics": ["..."]}}],
+    "assessment": "string",
+    "course_overview": "string",
+    "teaching_approach": "string",
+    "workload_expectation": "string",
+    "academic_integrity_policy": "string"
   }}
 }}
 """
@@ -294,11 +298,27 @@ Return JSON:
             status_code=422,
             detail="INVALID_GENERATION: 'explanation' or 'proposed_draft' missing in JSON.",
         )
+    if not isinstance(data_dict["proposed_draft"], dict):
+        raise HTTPException(
+            status_code=422,
+            detail="INVALID_GENERATION: 'proposed_draft' must be a JSON object.",
+        )
+
+    actual_keys = set(data_dict["proposed_draft"].keys())
+    if actual_keys != expected_keys:
+        raise HTTPException(
+            status_code=422,
+            detail=(
+                "INVALID_GENERATION: 'proposed_draft' top-level keys must exactly match "
+                f"'current_syllabus.unlocked_sections'. expected={sorted(expected_keys)}, "
+                f"actual={sorted(actual_keys)}"
+            ),
+        )
 
     return SyllabusPartialResponse(
         data=SyllabusPartialData(
             explanation=data_dict["explanation"],
-            proposed_draft=SyllabusPartialDraft(**data_dict["proposed_draft"]),
+            proposed_draft=SyllabusPartialDraft.model_validate(data_dict["proposed_draft"]),
         ),
         meta=meta,
     )

docs/AI_COURSEWARE_API_USAGE.md

@@ -135,6 +135,8 @@ const req: AiSyllabusPartialReq = {
           topics: ["History of AI"],
         },
       ],
+      assessment: "Weekly assignments + project",
+      course_overview: "Intro to GenAI course overview",
     },
   },
   context: {
@@ -148,7 +150,9 @@ const req: AiSyllabusPartialReq = {
 
 const resp: AiSyllabusPartialResp = await apiAiSyllabusRegeneratePartial(req);
 // resp.data.explanation -> Copilot 气泡说明文案
-// resp.data.proposed_draft.syllabus -> 用于替换未锁定 syllabus 的新大纲
+// 强约束：resp.data.proposed_draft 的顶层键集合必须与 req.current_syllabus.unlocked_sections 完全一致
+// 例如 unlocked_sections 传了 syllabus/assessment/course_overview，
+// proposed_draft 也必须同时返回这 3 个键（已改写键返回新值，未改写键返回原值，且不能多键/少键）
 ```
 
 #### 3.3 生成单个模块的教学流程 `apiAiFlowGenerate`（snake_case）

web/src/lib/api.ts

@@ -655,7 +655,13 @@ export type AiSyllabusLockedSections = {
 };
 
 export type AiSyllabusUnlockedSections = {
-  syllabus: Partial<AiWeekSyllabus>[];
+  syllabus?: Partial<AiWeekSyllabus>[];
+  assessment?: string | null;
+  course_overview?: string | null;
+  teaching_approach?: string | null;
+  workload_expectation?: string | null;
+  academic_integrity_policy?: string | null;
+  [key: string]: any;
 };
 
 export type AiCurrentSyllabus = {
@@ -673,9 +679,8 @@ export type AiSyllabusPartialReq = {
 export type AiSyllabusPartialResp = {
   data: {
     explanation: string;
-    proposed_draft: {
-      syllabus: AiWeekSyllabus[];
-    };
+    // Must have exactly the same top-level keys as current_syllabus.unlocked_sections.
+    proposed_draft: Record<string, any>;
   };
   meta: AiMeta;
 };