feat：架构重构

app/schemas/actions/add.py

@@ -10,16 +10,18 @@ from app.schemas.screen import ScreenNode
 
 
 class AddAction(ActionModel):
+    """按物料新增组件"""
+
     type: Literal["add"] = "add"
+    component_key: NonBlankString = Field(
+        description="物料目录编号，即 list_components 返回的 key"
+    )
     node: ScreenNode = Field(
-        description="待新增的完整组件，包含新 ID、类型、布局和配置"
-    )
-    plan_id: NonBlankString | None = Field(
-        default=None, description="对应的规划组件编号，独立模拟时可省略"
-    )
-    component_key: NonBlankString | None = Field(
-        default=None, description="使用的物料目录编号，规划生成时必填"
+        description="新组件。id、type、layout 必填，其余只写需要覆盖物料默认配置的字段；"
+        "后端按物料默认配置补全：对象逐层覆盖，数组整体替换，null 明确覆盖。"
+        "id 不能与现有组件重复，同一批里先 delete 的 ID 可以再用；type 必须与物料一致"
     )
     sample_data: bool = Field(
-        default=False, description="物料含示例数据，不代表已获取真实业务数据"
+        default=False,
+        description="由后端按物料设置，不用填写；true 表示组件使用物料示例数据，不是真实业务数据",
     )