@shundoo-ai/dsh-cosmic 1.0.21 → 1.0.22

package/skills/cosmic-build/skills/cosmic-meta-api/contracts/schema/report-write.schema.json

@@ -8,6 +8,14 @@
       "pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
       "minLength": 1
     },
+    "columnRemoval": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["fieldKey"],
+      "properties": {
+        "fieldKey": {"$ref": "#/$defs/identifier", "description": "Exact leaf column key; groups are not supported. Backend ReportColumns.remove patch required."}
+      }
+    },
     "sort": {
       "type": "object",
       "additionalProperties": false,
@@ -30,7 +38,7 @@
         },
         "fieldType": {
           "enum": ["text", "integer", "bigint", "decimal", "date", "datetime", "boolean", "picture", "combofield", "formula"],
-          "description": "Only these types have proven write/read-back symmetry in report metadata. Money, quantity and base-data presentation is not expressible here: declare the storage-shaped type (decimal for money/quantity, text or bigint for a base-data reference) and declare the real presentation in this column's `presentation` object, which is compiled into the plugin contract."
+          "description": "仅这些列类型具有已验证写入/回读对称性。decimal 表示标量存储，不能证明单位/币别动态精度；amount/qty/price 的 presentation 当前写前拒绝，需求须保留至平台引用链路验证。基础资料呈现使用 text 或 bigint，并编译为插件要求，不代表运行验收。"
         },
         "caption": {"type": "string", "minLength": 1},
         "width": {"type": "string", "minLength": 1},
@@ -44,7 +52,8 @@
       "type": "object",
       "additionalProperties": false,
       "required": ["kind"],
-      "description": "Runtime presentation that report metadata cannot carry. It is never sent to the platform: the report pipeline compiles it into {appRoot}/_runtime/<formNumber>.report-plugin-contract.json, and prepare_plugin_handoff forwards it as handoff.reportContract so the data-fetch plugin binds it in getColumns(). Each kind compiles to one ReportColumnFactory call with a documented signature (contract field `java`) plus any setters to apply afterwards (`javaFollowUp`), so no ReportColumn.TYPE_* constant has to be guessed.",
+      "description": "运行呈现不直接写入平台，支持的类型编译为插件契约。amount/qty/price 的动态精度暂被 REPORT_PRECISION_REFERENCE_UNVERIFIED 写前阻断；隐藏 bigint、相同名称及 getColumns() 工厂签名不证明 DynamicObject 引用。原始或历史需求编译保留 precisionSource，但必须先验证平台引用字段、旧字段迁移和格式化前批量物化；不能固定精度降级。",
+      "not": {"required": ["kind"], "properties": {"kind": {"enum": ["amount", "qty", "price"]}}},
       "properties": {
         "kind": {
           "enum": ["amount", "qty", "price", "basedata", "decimal"],
@@ -52,11 +61,11 @@
         },
         "currencyField": {
           "$ref": "#/$defs/identifier",
-          "description": "Required for amount and price. Names another report column's fieldKey: the column that carries the currency record's id, normally declared as fieldType bigint with hide true. It is not a loose DataSet column name. The platform builds the runtime entity from the column list (ReportPropUtil.createReportType) and packages row data under fieldKey, so a binding to a name that is not a declared column resolves to nothing on the client. The bound column must keep fieldKey == dateIndex, which makes the same artifact correct whether the platform reads this as a fieldKey or as a DataSet column name."
+          "description": "amount/price 的币别引用字段要求，仅保留历史需求形状，当前写入拒绝。fieldKey == dateIndex 只证明名称一致，隐藏 bigint 仍是 Long，不能作为 DynamicObject 精度引用。平台引用字段及批量物化验证后才能开放。"
         },
         "measureUnitField": {
           "$ref": "#/$defs/identifier",
-          "description": "Required for qty. Names another report column's fieldKey: the column that carries the measure-unit record's id, normally declared as fieldType bigint with hide true. Same rules as currencyField."
+          "description": "qty 的单位引用字段要求；与 currencyField 同样被写前阻断。Long 主键不是 DynamicObject 引用，不能靠 hide 或工厂转换证明运行正确。"
         },
         "entityId": {"type": "string", "minLength": 1, "description": "Required for basedata, e.g. bd_supplier."},
         "displayProp": {"type": "string", "minLength": 1, "description": "Required for basedata, e.g. name."},
@@ -86,6 +95,28 @@
       "items": {"$ref": "#/$defs/columnOrGroup"},
       "examples": [[{"kind": "column", "fieldKey": "contract_no", "dateIndex": "contract_no", "fieldType": "text", "caption": "合同号"}]]
     },
+    "filterFieldType": {
+      "enum": ["TextField", "IntegerField", "BigIntField", "DecimalField", "DateField", "DateTimeField", "DateRangeField", "TimeField", "TimeRangeField", "CheckBoxField", "ComboField", "MulComboField", "CheckBoxGroupField", "BasedataField", "MulBasedataField", "OrgField", "UserField", "CurrencyField", "UnitField", "MaterielField", "CustomerField", "SupplierField", "AssistantField", "ItemClassTypeField", "ItemClassField"],
+      "description": "The filter's native editor, built by the platform's typed report filter API (a platform patch). The CLI also accepts the platform's lower-case aliases (basedata, mulbasedata, combo, date, org, ...) and normalizes them to these class names. With compare=between, DateField / DateTimeField become DateRangeField and TimeField becomes TimeRangeField; a range editor needs compare=between. A platform without the patch ignores fieldType and renders its legacy control (TextField, or DateRangeField for between); the write reports such a filter as degraded instead of failing, and the read-back confirms which editor rendered."
+    },
+    "filterComboItem": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["value", "caption"],
+      "properties": {
+        "value": {"type": ["string", "number"], "description": "The stored value query() compares against, kept exactly: 0 and leading zeros are values."},
+        "caption": {"type": "string", "minLength": 1}
+      }
+    },
+    "filterItemClassType": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["basedataNumber"],
+      "properties": {
+        "basedataNumber": {"type": "string", "minLength": 1},
+        "caption": {"type": "string", "minLength": 1}
+      }
+    },
     "filter": {
       "type": "object",
       "additionalProperties": false,
@@ -93,27 +124,47 @@
       "properties": {
         "fieldPath": {
           "$ref": "#/$defs/identifier",
-          "description": "Filter key, not a dotted entity path. setReportFilters creates the control under this key and the plugin reads its value through ReportQueryParam.getFilter().getFilterItem(<key>). It must not repeat any reportColumns fieldKey, group keys included: control and column would share one element key, the write and every API read-back would still succeed, and only the designer would reject the duplicated identifier. Filtering on a displayed column means a distinct key such as flt_<column>, which the plugin applies to that column."
+          "description": "Filter key, not a dotted entity path. setReportFilters creates the control under this key and the plugin reads its value through ReportQueryParam.getFilter() under this key. It must not repeat any reportColumns fieldKey, group keys included: control and column would share one element key, the write and every API read-back would still succeed, and only the designer would reject the duplicated identifier. Filtering on a displayed column means a distinct key such as flt_<column>, which the plugin applies to that column."
         },
         "displayName": {"type": "string", "minLength": 1},
         "compare": {
           "enum": ["=", "in", "between"],
-          "description": "Query comparison (=, in, between), not an arbitrary control-type selector. The platform source may create DateRangeField for between and TextField otherwise; verify actual deployment output. This input cannot request DateField, MulBaseDataField or ComboListField."
+          "description": "业务查询比较（=、in、between），必须在所属 query() 显式落实。新 API 可从 ReportFilterFieldConfig 投影实际比较配置，但不代表 setReportFilters 自动绑定业务查询；回读保留 compareConfig 来源，不猜 compareTypeId。编辑器由 fieldType 决定。"
         },
-        "source": {"type": "object", "additionalProperties": false, "required": ["formNumber", "fieldKey"], "properties": {"formNumber": {"$ref": "#/$defs/identifier"}, "fieldKey": {"$ref": "#/$defs/identifier"}}, "description": "Verified source form and field. Uses the ReportFilters.typed platform extension; copies its native editor type, reference, enum and numeric/date options. between on a date creates DateRangeField. Legacy platforms fail closed; no TextField fallback."},
-        "defaultValue": {},
+        "fieldType": {"$ref": "#/$defs/filterFieldType"},
+        "basedataNumber": {"type": "string", "minLength": 1, "description": "Required for BasedataField and MulBasedataField: the base data form number, e.g. bd_supplier. Only the number is accepted; the platform resolves and validates it."},
+        "comboItems": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/filterComboItem"}, "description": "Required for ComboField, MulComboField and CheckBoxGroupField: the options, with unique values."},
+        "itemClassTypes": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/filterItemClassType"}, "description": "Required for ItemClassTypeField: the base data types the user chooses between."},
+        "typeFieldKey": {"$ref": "#/$defs/identifier", "description": "Required for ItemClassField: the fieldPath of the ItemClassTypeField filter in the same request that selects its base data type."},
+        "asstTypeId": {"type": "string", "pattern": "^\\d+$", "description": "Required for AssistantField: the numeric id of the assistant data group."},
+        "orgFuncs": {"type": "string", "minLength": 1, "description": "Optional for OrgField: the organization function code the picker is scoped to; the platform refuses a code it does not list."},
+        "showStyle": {"type": "integer", "minimum": 0, "maximum": 3, "description": "Optional for CheckBoxField: the platform's checkbox display style."},
+        "startDateFieldKey": {"$ref": "#/$defs/identifier", "description": "Optional for DateRangeField / TimeRangeField: the runtime key of the range's start item. Default <fieldPath>_startdate, or <fieldPath>_starttime for a time range. A platform without the patch always uses the default."},
+        "endDateFieldKey": {"$ref": "#/$defs/identifier", "description": "Optional for DateRangeField / TimeRangeField: the runtime key of the range's end item. Default <fieldPath>_enddate, or <fieldPath>_endtime for a time range."},
+        "defaultValue": {"description": "Not accepted on an F7 editor (the platform refuses it). CheckBoxField takes true, false, 1 or 0. Compiled into the plugin contract as a requirement either way."},
         "mustInput": {
           "type": "boolean",
-          "description": "Accepted but not persisted by the tested deployment. Declaring it is not a no-op: the read-back reports it as an explicit mismatch and it is compiled into the plugin contract as a requirement query() must enforce from getFilter()."
+          "description": "类型化过滤 API 设置实体字段必录；新投影从实际字段 Boolean 回读，旧平台可由新鲜 DYM 补证据。null/unknown 不是 false；保存标志不能替代 verifyQuery/query 在取数前的共用校验。不能与 visible:false 合用。"
         },
-        "visible": {"type": "boolean", "description": "Accepted but not persisted by the tested deployment; same handling as mustInput."}
-      }
+        "visible": {"type": "boolean", "description": "visible:false 声明初始隐藏。新投影使用 visibleEffective 的实际 Boolean，控件阶段字符串不是 Boolean，null/unknown 不算已验证；旧平台保留 DYM 回读。"}
+      },
+      "allOf": [
+        {"if": {"required": ["fieldType"], "properties": {"fieldType": {"enum": ["BasedataField", "MulBasedataField"]}}}, "then": {"required": ["basedataNumber"]}},
+        {"if": {"required": ["fieldType"], "properties": {"fieldType": {"enum": ["ComboField", "MulComboField", "CheckBoxGroupField"]}}}, "then": {"required": ["comboItems"]}},
+        {"if": {"required": ["fieldType"], "properties": {"fieldType": {"const": "ItemClassTypeField"}}}, "then": {"required": ["itemClassTypes"]}},
+        {"if": {"required": ["fieldType"], "properties": {"fieldType": {"const": "ItemClassField"}}}, "then": {"required": ["typeFieldKey"]}},
+        {"if": {"required": ["fieldType"], "properties": {"fieldType": {"const": "AssistantField"}}}, "then": {"required": ["asstTypeId"]}}
+      ]
     },
     "filters": {
       "type": "array",
       "minItems": 1,
       "items": {"$ref": "#/$defs/filter"},
-      "examples": [[{"fieldPath": "sign_date", "displayName": "签约日期", "compare": "between", "mustInput": false, "visible": true}]]
+      "examples": [[
+        {"fieldPath": "flt_sign_date", "displayName": "签约日期", "compare": "between", "fieldType": "DateRangeField", "mustInput": true},
+        {"fieldPath": "flt_supplier", "displayName": "供应商", "compare": "in", "fieldType": "MulBasedataField", "basedataNumber": "bd_supplier"},
+        {"fieldPath": "flt_status", "displayName": "状态", "compare": "=", "fieldType": "ComboField", "comboItems": [{"value": "A", "caption": "暂存"}, {"value": "C", "caption": "已审核"}]}
+      ]]
     },
     "sorts": {
       "type": "array",
@@ -159,7 +210,7 @@
     },
     "reportPropertyTarget": {
       "enum": ["list", "filterPanel", "moreFilterPanel", "form", "tree", "column"],
-      "description": "Which host control the property map is applied to. list -> ReportListAp (reportlistap); filterPanel -> ReportFilterAp (reportfilterap); moreFilterPanel -> ReportMoreFilterPanelAp (reportmorefilterpanelap); form -> ReportFormAp, whose element key IS the form number; tree -> ReportTreeAp (reporttreeap); column -> one EntryFieldAp or EntryFieldGroupAp named by --element. Only 'column' takes an --element; every other target resolves its host from the form number."
+      "description": "Which host control the property map is applied to. list -> ReportListAp (reportlistap); filterPanel -> ReportFilterAp (reportfilterap); moreFilterPanel -> ReportMoreFilterPanelAp (reportmorefilterpanelap); form -> ReportFormAp, whose element key IS the form number; tree -> the report's one ReportTreeAp, found by element type because a user adds it in the designer under any key; column -> one EntryFieldAp or EntryFieldGroupAp named by --element. 'column' needs an --element and 'tree' takes one only to pick among several trees; every other target resolves its host from the form number."
     },
     "reportListProperties": {
       "type": "object",
@@ -200,7 +251,7 @@
           "type": "array",
           "minItems": 1,
           "items": {"$ref": "#/$defs/identifier"},
-          "description": "A list of filter keys, which the CLI serialises to the JSON array string the runtime parses. setReportFilters writes the same property as a comma-joined string the runtime cannot read, so this is also the repair for a report the platform wrote; the command contract carries the measurement."
+          "description": "A list of filter keys, which the CLI serialises to the JSON array string the runtime parses. On a platform without the typed report filter patch, setReportFilters writes the same property as a comma-joined string the runtime cannot read, so this is also the repair for a report that platform wrote; the command contract carries the measurement."
         }
       },
       "examples": [{"UserConfiguration": true, "ShowFilterFields": ["flt_biztime", "flt_supplier"]}]
@@ -229,7 +280,7 @@
       "description": "ReportTreeAp scalars, so they apply only to a report that actually has a left tree; the CLI refuses the write before sending when the element resolves none of them. BaseEntityId is refused here because it has its own candidate-backed route (setComplexProperty --complexType baseEntityId, values from listBaseEntityTypes).",
       "properties": {
         "LeafNodeQuery": {"type": "boolean"},
-        "ReportPlugin": {"type": "string", "minLength": 1, "description": "The left tree's own data plugin class name. Writing it records the name; it does not create the class."}
+        "ReportPlugin": {"type": "string", "minLength": 1, "description": "The left tree's own data plugin class name: an AbstractReportTreeDataPlugin returning List<TreeNode>, registered here and never as a reportPlugins entry (that slot is the report list's data-fetch plugin). Writing it records the name; it does not create the class, which Java delivery provides as type reporttreelist."}
       }
     },
     "reportColumnLeafProperties": {
@@ -317,7 +368,7 @@
       "type": "object",
       "additionalProperties": false,
       "minProperties": 1,
-      "description": "The report Artifact's `reportProperties` section: the same properties the modifier writes one host at a time, declared up front so one `run` creates a report that is already configured. It is applied LAST in the pipeline, after the filters, which is what leaves ShowFilterFields in the JSON-array form the runtime parses rather than the comma-joined form the filter write produces. Each column key is resolved against the artifact's own reportColumns to decide whether it is an EntryFieldAp or an EntryFieldGroupAp, because the two accept different property sets and the platform silently ignores a key sent to the wrong one.",
+      "description": "The report Artifact's `reportProperties` section: the same properties the modifier writes one host at a time, declared up front so one `run` creates a report that is already configured. It is applied LAST in the pipeline, after the filters, which is what leaves ShowFilterFields in the JSON-array form the runtime parses rather than the comma-joined form the filter write produces on a platform without the typed report filter patch, and lets a declared FilterMustInput or defaultHiddenFields outlast a patched filter write, which resets both. Each column key is resolved against the artifact's own reportColumns to decide whether it is an EntryFieldAp or an EntryFieldGroupAp, because the two accept different property sets and the platform silently ignores a key sent to the wrong one.",
       "properties": {
         "list": {"$ref": "#/$defs/reportListProperties"},
         "filterPanel": {"$ref": "#/$defs/reportFilterPanelProperties"},
@@ -325,7 +376,7 @@
         "form": {"$ref": "#/$defs/reportFormProperties"},
         "tree": {
           "$ref": "#/$defs/reportTreeProperties",
-          "description": "Only a report whose template carries a ReportTreeAp has these. On any other report the write is refused before it is sent, so declaring them on a plain bos_rpttpl report fails the run."
+          "description": "Only a report that carries a ReportTreeAp has these, and no public report template presets one: bos_grouprpttpl is the grouped report (group panel + group list), not a left tree. A left tree exists only after a user adds the report tree control to the report in the designer. On any other report the write is refused before it is sent, so declaring them in a creation Artifact fails the run after createPage; the validator refuses it as R-property-tree."
         },
         "columns": {
           "type": "object",
@@ -381,6 +432,11 @@
     {"command": "setReportColumns", "input": [{"kind": "column", "fieldKey": "sup", "dateIndex": "sup", "fieldType": "decimal", "caption": "Supplier", "presentation": {"kind": "basedata", "entityId": "bd_supplier", "displayProp": "name"}}], "error": "presentation.kind='basedata' needs fieldType in ['bigint', 'text']"},
     {"command": "addReportColumns", "input": [{"kind": "column", "fieldKey": "creator_email", "dateIndex": "creator_email", "fieldType": "text"}], "error": "caption is required; addReportColumns shares the columns contract with setReportColumns and only differs in write semantics"},
     {"command": "setReportFilters", "input": [{"fieldPath": "biz_date", "displayName": "Business Date", "compare": "between", "enableFuzzy": true}], "error": "filters[0] contains unsupported properties ['enableFuzzy']"},
+    {"command": "setReportFilters", "input": [{"fieldPath": "flt_supplier", "displayName": "Supplier", "compare": "in", "fieldType": "MulBasedataField"}], "error": "filters[0].basedataNumber is required for fieldType MulBasedataField"},
+    {"command": "setReportFilters", "input": [{"fieldPath": "flt_supplier", "displayName": "Supplier", "compare": "between", "fieldType": "BasedataField", "basedataNumber": "bd_supplier"}], "error": "filters[0]: compare=between needs a range editor (DateRangeField or TimeRangeField), and BasedataField holds one value; declare a from/to pair of filters instead"},
+    {"command": "setReportFilters", "input": [{"fieldPath": "flt_status", "displayName": "Status", "compare": "=", "comboItems": [{"value": "A", "caption": "Draft"}]}], "error": "filters[0].comboItems needs fieldType: it configures a typed filter editor"},
+    {"command": "setReportFilters", "input": [{"fieldPath": "flt_org", "displayName": "Org", "compare": "=", "fieldType": "OrgField", "basedataNumber": "bos_org"}], "error": "filters[0].basedataNumber does not apply to fieldType OrgField; it configures ['BasedataField', 'MulBasedataField']"},
+    {"command": "setReportFilters", "input": [{"fieldPath": "flt_supplier", "displayName": "Supplier", "compare": "=", "source": {"formNumber": "pm_purorderbill", "fieldKey": "supplier"}}], "error": "filters[0].source is retired: declare fieldType and its parameters instead (an F7 filter is fieldType plus basedataNumber); read the source field's type and reference from that form's getFormSchema"},
     {"command": "setReportSorts", "input": [{"fieldKey": "amount", "direction": "descending"}], "error": "direction must be asc or desc"},
     {"command": "registerReportPlugin", "input": {"className": "kd.example.report.P", "generateCode": true}, "error": "plugin contains unsupported properties ['generateCode']"},
     {"command": "setReportProperties", "input": {"target": "list", "input": {"ShowSeq": 1}}, "error": "input.ShowSeq must be a JSON boolean, got int"},
@@ -395,7 +451,8 @@
     {"command": "setReportProperties", "input": {"target": "column", "element": "amt_group", "input": {"Summary": 1}}, "error": "Summary is not a writable property of target column (EntryFieldGroupAp); it accepts ['Freeze', 'GroupCollapsible', 'GroupDefaultCollapse', 'Hidden', 'Hide', 'Merge', 'TextAlign']"},
     {"command": "setReportProperties", "input": {"target": "column", "element": "total_amount", "input": {"Merge": true}}, "error": "Merge is not a writable property of target column (EntryFieldAp)"},
     {"command": "setReportProperties", "input": {"target": "list", "element": "reportlistap", "input": {"ShowSeq": false}}, "error": "target 'list' writes reportlistap and takes no --element"},
-    {"command": "setReportProperties", "input": {"target": "tree", "input": {"LeafNodeQuery": false}}, "error": "REPORT_PROPERTY_ELEMENT_MISMATCH: 'reporttreeap' resolves none of ['LeafNodeQuery'], so writing them would report success and change nothing — this report has no left tree"},
+    {"command": "setReportProperties", "input": {"target": "tree", "input": {"LeafNodeQuery": false}}, "error": "REPORT_PROPERTY_ELEMENT_MISMATCH: 'kdtest_cost_analysis_rpt' has no ReportTreeAp control, so there is nothing to write to — no public report template presets one; a user adds it in the designer first"},
+    {"command": "setReportProperties", "input": {"target": "tree", "input": {"LeafNodeQuery": false}}, "error": "'kdtest_cost_analysis_rpt' has several ReportTreeAp controls ['tree_a', 'tree_b']; name one with --element"},
     {"command": "setReportRowBackColor", "input": {"rules": []}, "error": "rules must be a non-empty JSON array of rule objects"},
     {"command": "setReportFilterFieldConfig", "input": {"fields": [{"fieldName": "amount"}]}, "error": "fields[0].key is required"},
     {"command": "setReportDefaultHiddenFields", "input": {"fields": [{"fieldKey": "flt_a", "userHide": false}]}, "error": "every entry has userHide false, and the platform stores only userHide true, so this write would change nothing"}

package/skills/cosmic-build/skills/cosmic-meta-api/modules/pdm/scripts/pdm_auto.py

@@ -1239,6 +1239,8 @@ def _run_patch_remove_index(patch_args):
         "operation": "remove-index",
         "table": target_table.get("tableName", table_name),
         "removedIndex": removed.get("indexName", index_name),
+        "note": ("Only takes effect for indexes not yet on the platform: save merges indexes "
+                 "additively and never drops an existing one, so --apply rejects removing it"),
     }
     print(json.dumps(result, ensure_ascii=False, indent=2))
     sys.exit(0)
@@ -1248,6 +1250,26 @@ def _run_patch_remove_index(patch_args):
 # apply mode
 # ---------------------------------------------------------------------------
 
+def find_dropped_indexes(confirmed_tables, current_tables):
+    """Return [(tableName, indexName)] present on the platform but missing from confirmed_tables.
+
+    The platform save merges indexes additively (an index absent from the request is kept),
+    so such a removal would be reported as done while the index stays in place.
+    """
+    confirmed_map = {(t.get("tableName") or "").strip().upper(): t for t in confirmed_tables}
+    dropped = []
+    for cur in current_tables or []:
+        conf = confirmed_map.get((cur.get("tableName") or "").strip().upper())
+        if conf is None:
+            continue
+        kept = {_idx_key(i) for i in (conf.get("indexes") or [])}
+        for idx in cur.get("indexes") or []:
+            key = _idx_key(idx)
+            if key and key not in kept:
+                dropped.append((cur.get("tableName", ""), idx.get("indexName", "")))
+    return dropped
+
+
 def run_apply(args):
     """Execution mode: read confirmed tableAps, execute save -> submit -> write files."""
     lf = sys.stderr  # Progress output to stderr
@@ -1316,6 +1338,23 @@ def run_apply(args):
     model_id = args.model_id
     _log(f"   -> Model: mdlCode={mdl_code}, modelId={model_id}", file=lf)
 
+    # -- Guard: save cannot drop existing indexes --
+    table_names = [t.get("tableName", "") for t in confirmed_tables if t.get("tableName")]
+    if table_names:
+        try:
+            current_tables = client.get_current_table_aps(model_id, table_names).get("tableAps", [])
+        except Exception as e:
+            _log(f"⚠️ Failed to fetch existing table structure, index removal check skipped: {e}", file=lf)
+            current_tables = []
+        dropped = find_dropped_indexes(confirmed_tables, current_tables)
+        if dropped:
+            _log("❌ TableAps removes indexes that already exist on the platform: "
+                 + ", ".join(f"{t}.{i}" for t, i in dropped), file=lf)
+            _log("   Platform save merges indexes additively and keeps them, so the removal would "
+                 "silently not happen. Restore these indexes in the file and drop them in the "
+                 "designer data model instead.", file=lf)
+            sys.exit(1)
+
     # -- Step 6: Save to D table --
     _log(f"\n[Save] Saving to D table...", file=lf)
     try:

package/skills/cosmic-build/skills/cosmic-meta-api/modules/pdm/scripts/pdm_client.py

@@ -43,7 +43,7 @@ if str(_PROJECT_ROOT_SCRIPTS_DIR) not in sys.path:
     sys.path.insert(0, str(_PROJECT_ROOT_SCRIPTS_DIR))
 
 import cosmic_api  # noqa: E402 — 复用 do_auth / load_config / _post / _get
-from kd_auth import get_token as _kd_get_token  # noqa: E402
+from kd_auth import get_token as _kd_get_token, make_auth_headers  # noqa: E402
 from kd_env_loader import get_kd_config_path, load_effective_skill_config  # noqa: E402
 from _http_client import DEFAULT_USER_AGENT, get_ssl_context  # noqa: E402
 
@@ -144,6 +144,9 @@ def resolve_credentials(cfg_raw: dict, env: str) -> dict:
     if env == "server":
         s = cfg_raw.get("server", {})
         creds = {
+            # 整节透传：kd_auth 依据 normalAccessToken 路由认证模式，并读取 loginUser /
+            # userType / acgwIdentity；任一字段丢失都会静默改变认证模式、getToken 用户名或网关头
+            **s,
             # cosmic_api.do_auth() 所需字段
             "base_url":     (s.get("baseUrl", "") or "").strip().rstrip("/"),
             "login_user":   (s.get("user", "") or "").strip(),
@@ -151,7 +154,8 @@ def resolve_credentials(cfg_raw: dict, env: str) -> dict:
             "app_secret":   (s.get("appSecret", "") or "").strip(),
             "account_id":   (s.get("accountId", "") or "").strip(),
             "tenant_id":    (s.get("tenantId", "") or "").strip(),
-            "user_type":    "Mobile",
+            "user_type":    (s.get("userType", "") or "Mobile").strip(),
+            "normalAccessToken": s.get("normalAccessToken") is True,
             "language":     "zh_CN",
             # 硬编码 API 基路径
             "api_base_path": "/kapi/v2/devportal/ai-meta",
@@ -165,13 +169,15 @@ def resolve_credentials(cfg_raw: dict, env: str) -> dict:
     elif env == "datamodel":
         p = cfg_raw.get("pdm", {})
         creds = {
+            **p,  # 与 server 分支相同的整节透传
             "base_url":     (p.get("baseUrl", "") or "").strip().rstrip("/"),
             "login_user":   (p.get("user", "") or "").strip(),
             "app_id":       (p.get("appId", "") or "").strip(),
             "app_secret":   (p.get("appSecret", "") or "").strip(),
             "account_id":   (p.get("accountId", "") or "").strip(),
             "tenant_id":    (p.get("tenantId", "") or "").strip(),
-            "user_type":    "Mobile",
+            "user_type":    (p.get("userType", "") or "Mobile").strip(),
+            "normalAccessToken": p.get("normalAccessToken") is True,
             "language":     "zh_CN",
             "api_base_path": "/kapi/v2/devportal/ai-meta",
             # PDM 专用
@@ -185,6 +191,73 @@ def resolve_credentials(cfg_raw: dict, env: str) -> dict:
         raise ValueError(f"未知 env 类型: {env!r}，应为 'server' 或 'datamodel'")
 
 
+def _same_index(a, b):
+    """索引定义相同：unique / cluster 标志与有序列列表一致（不区分大小写）。"""
+    return (bool(a.get("unique")) == bool(b.get("unique"))
+            and bool(a.get("cluster")) == bool(b.get("cluster"))
+            and [str(c).upper() for c in a.get("columns") or []]
+            == [str(c).upper() for c in b.get("columns") or []])
+
+
+def columnless_index_tables(table_aps: list) -> list:
+    """返回带索引但未带 columns 的表名列表，这些索引 save 无法解析。"""
+    return [t.get("tableName", "") for t in table_aps
+            if t.get("indexes") and not t.get("columns")]
+
+
+def align_index_columns(table_aps: list, current_tables=None) -> list:
+    """使索引 / 主键列能被 save 解析，在未打补丁的平台上同样成立。
+
+    save 接口按 columnName 精确（区分大小写）对照请求中的 columns 解析这些列，解析不到的列
+    被静默丢弃，随后用缩短后的列表覆盖已有索引。convert 输出 "FLocaleID"，而 M 表索引读回为
+    "FLOCALEID"，于是 (FID, FLOCALEID) 索引在 submit 后退化为 (FID)。
+
+    - 可解析的列一律改写为请求 columns 中 columnName 的精确拼写。
+    - 未带 columns 的表会保留已有列，因此与 current_tables 相比未变化的索引从请求中省略：
+      save 会原样保留请求中未出现的已有索引。
+    - 否则抛 ValueError，而不是交给接口静默丢弃该列。带 columns 时 save 还会删除请求中
+      未出现的已有列，索引同样无法原样保留。
+
+    返回被省略的索引 [(tableName, indexName)]。
+    """
+    current_idx = {}
+    for cur in current_tables or []:
+        tn = (cur.get("tableName") or "").upper()
+        for idx in cur.get("indexes") or []:
+            current_idx[(tn, (idx.get("indexName") or "").upper())] = idx
+    omitted = []
+    for table in table_aps:
+        table_name = table.get("tableName") or ""
+        actual_names = {}
+        for col in table.get("columns") or []:
+            name = col.get("columnName")
+            if name:
+                actual_names.setdefault(name.upper(), name)
+        pk = table.get("primaryKey")
+        if isinstance(pk, dict) and pk.get("columns"):
+            pk["columns"] = [actual_names.get(str(n).upper(), n) for n in pk["columns"]]
+        if not table.get("indexes"):
+            continue
+        kept = []
+        for idx in table["indexes"]:
+            cols = idx.get("columns") or []
+            aligned = [actual_names.get(str(n).upper()) for n in cols]
+            if None not in aligned:
+                idx["columns"] = aligned
+                kept.append(idx)
+                continue
+            cur = current_idx.get((table_name.upper(), (idx.get("indexName") or "").upper()))
+            if not table.get("columns") and cur is not None and _same_index(idx, cur):
+                omitted.append((table_name, idx.get("indexName", "")))
+                continue
+            missing = ", ".join(str(n) for n, a in zip(cols, aligned) if a is None)
+            raise ValueError(
+                f"索引 {idx.get('indexName')} 引用的列 {missing} 不在表 "
+                f"{table_name} 的 columns 中，save 会静默丢弃该列")
+        table["indexes"] = kept
+    return omitted
+
+
 # ---------------------------------------------------------------------------
 # PDMClient
 # ---------------------------------------------------------------------------
@@ -233,7 +306,7 @@ class PDMClient:
     # ------------------------------------------------------------------
 
     def login(self, env="server", force=False):
-        """使用 cosmic_api.do_auth() 进行两步 OAuth2 认证
+        """经 kd_auth.get_token 认证（自动路由 normal 两步 / enhanced getToken）
 
         Args:
             env: "server" 或 "datamodel"
@@ -245,9 +318,7 @@ class PDMClient:
         if env == "server":
             if not self._server_cfg:
                 raise ValueError("server 凭据未配置，请检查 ~/.kd/config.json 默认环境")
-            # cosmic_api.do_auth 使用 token cache，PDM 双环境不能共用缓存
-            # 因此这里直接走 force=True 避免环境混淆
-            token = self._do_two_step_auth(self._server_cfg)
+            token = self._get_oauth_token(self._server_cfg)
             self._server_token = token
             print(f"  [AUTH] server 环境认证成功: {token[:40]}...")
             return token
@@ -293,7 +364,10 @@ class PDMClient:
         return self._server_token if env == "server" else self._pdm_token
 
     def _auth_headers(self, env):
-        return {"access_token": self._get_token(env), "api": "true"}
+        # legacy_api：access_token + 无下划线的 accesstoken（经 nginx 不被丢弃）+ api:true，
+        # 环境位于网关后时另带 x-acgw-identity
+        cfg = self._server_cfg if env == "server" else self._pdm_cfg
+        return make_auth_headers(cfg, self._get_token(env), style="legacy_api")
 
     def _api_call(self, env, method, path, data=None, retry_on_401=True):
         """通用 API 调用，自动处理 token 过期重试
@@ -432,8 +506,21 @@ class PDMClient:
             {"modelId": ..., "validations": [...], "message": ...}
         """
         path = "/kapi/v2/devportal/ai-meta/pdm/save"
-        if isinstance(table_aps_json, (list, dict)):
-            table_aps_json = json.dumps(table_aps_json, ensure_ascii=False)
+        table_aps = (json.loads(table_aps_json) if isinstance(table_aps_json, str)
+                     else table_aps_json)
+        if isinstance(table_aps, list):
+            current = None
+            unresolved = columnless_index_tables(table_aps)
+            if unresolved:
+                try:
+                    current = self.get_current_table_aps(model_id, unresolved).get("tableAps", [])
+                except Exception as e:
+                    print(f"  [WARN] 获取 {', '.join(unresolved)} 的现有索引失败: {e}",
+                          file=sys.stderr)
+            for tn, iname in align_index_columns(table_aps, current):
+                print(f"  [SAVE] 索引 {tn}.{iname} 未变化且所属表未带 columns，"
+                      f"已从请求中省略，由平台原样保留", file=sys.stderr)
+        table_aps_json = json.dumps(table_aps, ensure_ascii=False)
         body = {
             "modelId": model_id,
             "tableApsJson": table_aps_json,

package/skills/cosmic-build/skills/cosmic-meta-api/modules/verify/SKILL.md

@@ -90,8 +90,8 @@
 | 状态 | 含义 | AI Agent 行动 |
 |------|------|--------------|
 | **PASS** | 断言通过，实际数据与预期一致 | 无需处理，继续后续流程 |
-| **FAIL** | 断言失败，实际数据与预期不一致 | 分析失败原因，尝试用正确的 API 重新执行操作 |
-| **WARN** | 命中已知缺陷库，API 本身的限制导致操作不生效 | 按建议使用替代 API（详见下方已知缺陷） |
+| **FAIL** | 断言失败，实际数据与预期不一致 | 先核对当前状态，仅修复已确认差异，不重放整个写入 |
+| **WARN** | 命中候选平台限制，是否生效仍需独立回读 | 确认差异后仅对未完成项选替代 API；状态未知不写入 |
 | **ERROR** | API 回读调用失败（网络/鉴权问题等），不代表写入操作失败 | 重试验证，或检查网络/鉴权状态 |
 | **SKIP** | 无法通过现有 API 验证的项 | 需人工在苍穹设计器中确认 |
 
@@ -117,23 +117,21 @@
 
 ### FAIL — 断言失败
 
-1. 解析失败断言的 `message` 和 `actual` / `expected` 差异
-2. 判断失败原因：
-   - **字段/实体不存在**：检查 buildMeta / modifyMeta 的 artifact / ops 是否正确，必要时重新执行
-   - **属性值不一致**：检查 setProperties / modifyMeta 的参数，使用正确参数重新调用
-   - **删除未生效**：确认 remove op 的 target 是否正确
-3. 用正确的 API 参数重新执行操作，再次调用验证确认修复
+1. 解析 `message` 和 `actual` / `expected` 差异；先独立回读当前状态及已有成功回执。
+2. 只修复已确认的差异：字段/实体缺失先确认目标与创建状态；属性不符核对 schema 和参数；删除未生效核对 target。
+3. 对尚未完成的差异选择正确 API，再次回读；不得重放整个 artifact / ops 数组，不得用 remove+add 替代属性修复。
+4. 回读失败、部分成功或写后状态未知时停止后续写入，遵循 `reconcile_before_retry`；只重试读取，不重试写入。
 
 ### WARN — 已知缺陷
 
-已知缺陷库中收录了苍穹 API 的已知限制。WARN 表示操作因平台限制未生效，AI Agent 应按建议使用替代方案：
+已知缺陷库记录候选平台限制。WARN 不能证明本次写入未发生；需核对实际部署、目标类型和独立回读，再决定是否使用替代方案：
 
 | 缺陷场景 | 现象 | 替代方案 |
 |----------|------|---------|
 | modifyMeta 设置 MulBasedataField.tableName | modifyMeta 无法生效 | 改用 `setProperties` API 设置 tableName |
-| modifyMeta modify mustInput | mustInput 可能被静默忽略 | 改用 `setProperties` API，或在 add 之后追加 modify op |
+| modifyMeta modify mustInput | mustInput 可能被静默忽略 | 独立验证创建后，改用带回读的 `setProperties`；不要混合结构和属性事务 |
 
-> 遇到 WARN 时，AI Agent 应自动切换到建议的替代 API 重新执行，然后再次验证。
+> WARN 是需要核对的候选限制，不是写入未发生的证明。先独立回读已完成和未完成项，再仅对已确认差异调用建议 API；状态未知时禁止重放写入或删除重建。
 
 ### ERROR — 回读失败
 
@@ -142,7 +140,7 @@
 3. 重试验证命令（最多 2 次）
 4. 仍然失败则提示用户检查环境
 
-> **注意**：ERROR 仅代表回读调用失败，不代表前序写入操作失败。
+> **注意**：ERROR 仅表示回读失败，前序写入状态仍未知；只重试验证读取，禁止重放写入。仍无法确认时停止依赖写入并交代未完成验证。
 
 ---
 

package/skills/cosmic-build/skills/cosmic-meta-api/scripts/_core/cmd_apps.py

@@ -222,7 +222,8 @@ def do_add_menu(cfg, token, biz_app_id, name, parent_menu_id=None,
         "linkUrl": link_url,
         "openType": open_type,
         "visible": visible,
-        "description": description,
+        # 旧平台缺省不初始化 LocaleString，菜单列表读取描述时可能空指针。
+        "description": name if description is None else description,
         "caption": caption,
         "parameter": parameter,
         "parameterType": parameter_type,
@@ -261,6 +262,7 @@ def do_add_menu(cfg, token, biz_app_id, name, parent_menu_id=None,
     else:
         expected = {
             "name": name,
+            "description": payload["description"],
             "menuType": platform_menu_type,
             "openType": open_type,
         }