@qingflow-tech/qingflow-cli 1.1.43-beta.3 → 1.1.43-beta.5

package/src/qingflow_mcp/builder_facade/app_form.py

@@ -8,18 +8,20 @@ import re
 from typing import Any, Iterable
 from urllib.parse import unquote_plus
 
-from ..app_form_compat import normalize_app_form_declaration, validate_app_form_create_icon
+from ..app_form_compat import normalize_app_form_declaration
 from ..errors import QingflowApiError, is_auth_like_error
 from ..json_types import JSONObject
 from ..solution.compiler.form_compiler import build_options, build_question, default_member_auth
-from ..solution.compiler.icon_utils import encode_workspace_icon
+from ..solution.compiler.icon_utils import encode_workspace_icon_with_defaults
 from ..solution.spec_models import FieldType
 from ..tools.app_tools import AppTools
 from ..tools.package_tools import PackageTools
 from .app_form_schema import AppFormContractError, AppFormSchemaContext, AppFormSchemaRegistry
 from .service import (
+    _coerce_any_int,
     _compile_code_block_binding_fields,
     _compile_q_linker_binding_fields,
+    _encrypt_question_id,
     _field_to_question,
     _looks_like_backend_encoded_formula,
     _normalize_formula_defaults_for_save,
@@ -288,11 +290,39 @@ def _canonical_scope_relation(relation: Any) -> JSONObject | None:
         "displayedFieldType": displayed.get("queType"),
         "matchRuleType": relation.get("matchRuleType"),
         "matchRules": relation.get("matchRules"),
-        "matchRuleFormula": relation.get("matchRuleFormula"),
     }
+    formula = str(relation.get("matchRuleFormula") or "").strip()
+    if formula:
+        result["matchRuleFormula"] = formula
     return _without_none(result)
 
 
+def _canonical_attachment_default_values(value: Any) -> JSONObject | None:
+    if not isinstance(value, dict):
+        return None
+    values = []
+    for item in value.get("values") or []:
+        if not isinstance(item, dict):
+            continue
+        url = str(item.get("value") or "").strip()
+        if not url:
+            data_value = str(item.get("dataValue") or "").strip()
+            url = data_value if "://" in data_value else ""
+        if not url:
+            continue
+        file_name = str(item.get("otherInfo") or item.get("valueStr") or "").strip()
+        values.append(
+            _without_none(
+                {
+                    "value": url,
+                    "otherInfo": file_name or None,
+                    "pluginValue": item.get("pluginValue"),
+                }
+            )
+        )
+    return {"values": values} if values else None
+
+
 def _selector(que_id: Any, name: Any) -> JSONObject:
     result: JSONObject = {}
     normalized_id = _positive_int(que_id)
@@ -361,6 +391,135 @@ def _canonical_equal(left: JSONObject, right: JSONObject) -> bool:
     return _semantic(left) == _semantic(right)
 
 
+def _iter_backend_questions(value: Any) -> Iterable[JSONObject]:
+    if isinstance(value, list):
+        for item in value:
+            yield from _iter_backend_questions(item)
+    elif isinstance(value, dict):
+        if "queType" in value:
+            yield value
+        yield from _iter_backend_questions(value.get("innerQuestions"))
+        yield from _iter_backend_questions(value.get("subQuestions"))
+
+
+def _normalize_published_scope_omissions(form: JSONObject) -> JSONObject:
+    """Allow published GET responses that omit custom member/department scopes."""
+    result = deepcopy(form)
+    for question in _iter_backend_questions(result.get("formQues")):
+        if (
+            _positive_int(question.get("memberSelectScopeType")) == 2
+            and not isinstance(question.get("memberSelectScope"), dict)
+        ):
+            question["memberSelectScopeType"] = 1
+            question["memberSelectScope"] = {}
+        if (
+            _positive_int(question.get("deptSelectScopeType")) == 2
+            and not isinstance(question.get("deptSelectScope"), dict)
+        ):
+            question["deptSelectScopeType"] = 1
+            question["deptSelectScope"] = {}
+    return result
+
+
+def _without_selectable_scopes(resource: JSONObject) -> JSONObject:
+    """Remove only selectable scope values from a published-state comparison."""
+    result = deepcopy(resource)
+    fields = _iter_fields(result.get("spec", {}).get("body") or [])
+    for field in _iter_field_tree(fields):
+        config = field.get("config") if isinstance(field.get("config"), dict) else None
+        if config is None:
+            continue
+        config.pop("memberScope", None)
+        config.pop("departmentScope", None)
+    return result
+
+
+def _published_field_map(resource: JSONObject) -> dict[tuple[str, Any], JSONObject]:
+    fields = _iter_field_tree(_iter_fields(resource.get("spec", {}).get("body") or []))
+    result: dict[tuple[str, Any], JSONObject] = {}
+    for field in fields:
+        que_id = _positive_int(field.get("queId"))
+        key = ("id", que_id) if que_id is not None else ("name", (_field_type(field), field.get("name")))
+        result[key] = field
+    return result
+
+
+def _matching_published_field(field: JSONObject, published_fields: dict[tuple[str, Any], JSONObject]) -> JSONObject | None:
+    que_id = _positive_int(field.get("queId"))
+    if que_id is not None and ("id", que_id) in published_fields:
+        return published_fields[("id", que_id)]
+    return published_fields.get(("name", (_field_type(field), field.get("name"))))
+
+
+def _normalize_published_get_equivalents(draft: JSONObject, published: JSONObject) -> tuple[JSONObject, JSONObject]:
+    """Normalize values that the published GET endpoint omits or materializes."""
+    draft_result = _without_selectable_scopes(draft)
+    published_result = _without_selectable_scopes(published)
+    published_fields = _published_field_map(published_result)
+    for draft_field in _published_field_map(draft_result).values():
+        published_field = _matching_published_field(draft_field, published_fields)
+        if published_field is None:
+            continue
+        field_type = _field_type(draft_field)
+        draft_config = draft_field.get("config") if isinstance(draft_field.get("config"), dict) else {}
+        published_config = published_field.get("config") if isinstance(published_field.get("config"), dict) else {}
+
+        if field_type == "member":
+            draft_default = draft_config.get("defaultMembers")
+            published_default = published_config.get("defaultMembers")
+            if isinstance(draft_default, dict) and isinstance(published_default, dict):
+                # Published GET resolves department defaults into runtime members.
+                for key in ("departments", "includeSubDeparts"):
+                    if key in draft_default:
+                        published_default[key] = deepcopy(draft_default[key])
+
+        if field_type == "data_relation":
+            draft_filters = draft_config.get("filters") if isinstance(draft_config.get("filters"), dict) else {}
+            published_filters = published_config.get("filters") if isinstance(published_config.get("filters"), dict) else {}
+            draft_groups = draft_filters.get("groups") if isinstance(draft_filters.get("groups"), list) else []
+            published_groups = published_filters.get("groups") if isinstance(published_filters.get("groups"), list) else []
+            for draft_group, published_group in zip(draft_groups, published_groups):
+                if not isinstance(draft_group, list) or not isinstance(published_group, list):
+                    continue
+                for draft_rule, published_rule in zip(draft_group, published_group):
+                    if not isinstance(draft_rule, dict) or not isinstance(published_rule, dict):
+                        continue
+                    draft_source = draft_rule.get("sourceField") if isinstance(draft_rule.get("sourceField"), dict) else {}
+                    published_source = published_rule.get("sourceField") if isinstance(published_rule.get("sourceField"), dict) else {}
+                    same_source = _positive_int(draft_source.get("queId")) == _positive_int(published_source.get("queId"))
+                    if same_source and draft_source.get("name") and not published_source.get("name"):
+                        published_source["name"] = draft_source["name"]
+                    draft_operand = draft_rule.get("operand") if isinstance(draft_rule.get("operand"), dict) else {}
+                    published_operand = published_rule.get("operand") if isinstance(published_rule.get("operand"), dict) else {}
+                    if (
+                        same_source
+                        and draft_rule.get("operator") == published_rule.get("operator")
+                        and draft_operand.get("kind") == published_operand.get("kind") == "literal"
+                        and draft_operand.get("values")
+                        and published_operand.get("values") == []
+                    ):
+                        published_operand["values"] = deepcopy(draft_operand["values"])
+            # The backend intentionally emits sortConfig only for beingDraft=true.
+            if "sort" in draft_config and "sort" not in published_config:
+                published_config["sort"] = deepcopy(draft_config["sort"])
+
+        if field_type == "subtable":
+            if draft_config.get("tableRowsLimit") in {None, 200} and published_config.get("tableRowsLimit") in {None, 200}:
+                draft_config.pop("tableRowsLimit", None)
+                published_config.pop("tableRowsLimit", None)
+
+        if field_type in {"number", "amount"}:
+            if draft_config.get("currencyStatus") in {None, False} and published_config.get("currencyStatus") in {None, False}:
+                draft_config.pop("currencyStatus", None)
+                published_config.pop("currencyStatus", None)
+    return draft_result, published_result
+
+
+def _published_equal(draft: JSONObject, published: JSONObject) -> bool:
+    comparable_draft, comparable_published = _normalize_published_get_equivalents(draft, published)
+    return _canonical_equal(comparable_draft, comparable_published)
+
+
 def _layout_semantic(body: list[Any]) -> list[JSONObject]:
     def row_layout(row: Any) -> JSONObject:
         fields = row.get("fields") if isinstance(row, dict) else []
@@ -368,7 +527,7 @@ def _layout_semantic(body: list[Any]) -> list[JSONObject]:
             "fields": [
                 {
                     "name": field.get("name"),
-                    "type": field.get("type"),
+                    "questionType": _field_type(field),
                     "width": field.get("width"),
                 }
                 for field in fields or []
@@ -407,6 +566,16 @@ def _field_semantic(value: JSONObject) -> Any:
     return _semantic({key: item for key, item in value.items() if key != "width"})
 
 
+def _field_type(field: JSONObject) -> str:
+    """Read the AppForm field type while accepting pre-rename declarations."""
+    return str(field.get("questionType") or field.get("type") or "")
+
+
+def _field_required(field: JSONObject) -> bool:
+    """Read the AppForm required flag while accepting pre-rename declarations."""
+    return bool(field.get("beingRequired") if "beingRequired" in field else field.get("required"))
+
+
 def _validate_payload_limits(value: Any) -> None:
     stack = [(value, 1)]
     while stack:
@@ -437,6 +606,9 @@ class AppFormNormalizer:
         relations = [item for item in form.get("questionRelations") or [] if isinstance(item, dict)]
         select_scope_relations = [item for item in form.get("selectScopeRelations") or [] if isinstance(item, dict)]
         field_names = self._field_index(form)
+        definitions = context.complete_schema.get("$defs") if isinstance(context.complete_schema.get("$defs"), dict) else {}
+        relation_properties = definitions.get("RelationConfig", {}).get("properties", {}) if isinstance(definitions.get("RelationConfig"), dict) else {}
+        supports_reference_default_formula = "defaultValueFormula" in relation_properties
         title_id = _positive_int(form.get("dataTitleQueId"))
         cover_id = _positive_int(form.get("dataCoverQueId"))
         body: list[JSONObject] = []
@@ -449,7 +621,7 @@ class AppFormNormalizer:
                 if section_id is None:
                     raise AppFormFailure("UNSUPPORTED_LAYOUT", "existing section has no stable ID", "NORMALIZE")
                 rows = [
-                    {"fields": [self._field(question, relations, select_scope_relations, title_id, cover_id, field_names) for question in inner if isinstance(question, dict)]}
+                    {"fields": [self._field(question, relations, select_scope_relations, field_names, supports_reference_default_formula) for question in inner if isinstance(question, dict)]}
                     for inner in section.get("innerQuestions") or []
                     if isinstance(inner, list) and inner
                 ]
@@ -457,15 +629,15 @@ class AppFormNormalizer:
                     raise AppFormFailure("UNSUPPORTED_LAYOUT", "existing section is empty", "NORMALIZE")
                 body.append({"kind": "section", "sectionId": str(section_id), "title": str(section.get("queTitle") or ""), "rows": rows})
             else:
-                body.append({"kind": "row", "fields": [self._field(question, relations, select_scope_relations, title_id, cover_id, field_names) for question in row if isinstance(question, dict)]})
+                body.append({"kind": "row", "fields": [self._field(question, relations, select_scope_relations, field_names, supports_reference_default_formula) for question in row if isinstance(question, dict)]})
         resource = {
             "apiVersion": context.api_version,
             "appKey": app_key,
             "spec": {
                 "appName": str(form.get("formTitle") or ""),
-                "description": form.get("formDesc") or None,
-                "theme": form.get("formTheme"),
-                "style": self._style(form.get("formStyle")),
+                "appDescription": form.get("formDesc") or None,
+                "dataTitleField": _selector(title_id, field_names.get(title_id or 0)) if title_id is not None else None,
+                "dataCoverField": _selector(cover_id, field_names.get(cover_id or 0)) if cover_id is not None else None,
                 "attachments": self._attachments(form.get("formAttach")),
                 "serialNumber": self._serial_number(form.get("serialNumType"), form.get("serialNumConfig")),
                 "body": body,
@@ -478,9 +650,8 @@ class AppFormNormalizer:
         question: JSONObject,
         relations: list[JSONObject],
         select_scope_relations: list[JSONObject],
-        title_id: int | None,
-        cover_id: int | None,
         field_names: dict[int, str],
+        supports_reference_default_formula: bool,
     ) -> JSONObject:
         que_id = _positive_int(question.get("queId"))
         if que_id is None:
@@ -506,9 +677,9 @@ class AppFormNormalizer:
             )
         field: JSONObject = {
             "name": str(question.get("queTitle") or ""),
-            "type": field_type,
-            "required": bool(question.get("required")),
-            "description": question.get("queHint") or None,
+            "questionType": field_type,
+            "beingRequired": bool(question.get("required")),
+            "questionDescription": question.get("queHint") or None,
         }
         default_type = _positive_int(question.get("queDefaultType"))
         if default_type is not None and (
@@ -526,16 +697,12 @@ class AppFormNormalizer:
             )
         if "queDefaultValue" in question and raw_default_value is not None and not isinstance(raw_default_value, (dict, list)):
             default_value = question.get("queDefaultValue")
-            field["defaultValue"] = _decode_formula_default(default_value) if default_type == 3 else deepcopy(default_value)
+            field["defaultValue"] = _decode_formula_default(default_value)
         if que_id is not None:
             field["queId"] = que_id
         width = _positive_int(question.get("queWidth"))
         if width is not None:
             field["width"] = width
-        if title_id is not None and que_id == title_id:
-            field["dataTitle"] = True
-        if cover_id is not None and que_id == cover_id:
-            field["dataCover"] = True
         if field_type in {"text", "long_text", "link", "phone", "email"}:
             config = _without_none({
                 "minWordCount": _canonical_unlimited(question.get("minWordCount")),
@@ -643,7 +810,7 @@ class AppFormNormalizer:
                 "maxFileLimit": question.get("maxFileLimit"),
                 "canScan": question.get("canScan"),
                 "scanType": question.get("scanType"),
-                "defaultValues": question.get("queDefaultValues") if isinstance(question.get("queDefaultValues"), dict) and (question.get("queDefaultValues", {}).get("values") or question.get("queDefaultValues", {}).get("tableValues")) else None,
+                "defaultValues": _canonical_attachment_default_values(question.get("queDefaultValues")),
             })
         elif field_type == "address":
             field["config"] = _without_none({
@@ -659,30 +826,31 @@ class AppFormNormalizer:
             display_id = _positive_int(reference.get("referQueId"))
             display = next((item for item in refer_questions if _positive_int(item.get("queId")) == display_id), None)
             visible = [item for item in refer_questions if _positive_int(item.get("queAuth")) != 2]
-            field["config"] = _without_none(
-                {
-                    "targetAppKey": reference.get("referAppKey"),
-                    "relationMode": "multiple" if _positive_int(reference.get("optionalDataNum")) not in {None, 1} else "single",
-                    "displayField": _require_selector(
-                        display_id,
-                        (display or {}).get("queTitle"),
-                        message="relation display field cannot be normalized",
+            relation_config: JSONObject = {
+                "targetAppKey": reference.get("referAppKey"),
+                "relationMode": "multiple" if _positive_int(reference.get("optionalDataNum")) not in {None, 1} else "single",
+                "displayField": _require_selector(
+                    display_id,
+                    (display or {}).get("queTitle"),
+                    message="relation display field cannot be normalized",
+                    details={"queId": que_id},
+                ),
+                "visibleFields": [
+                    _require_selector(
+                        item.get("queId"),
+                        item.get("queTitle"),
+                        message="relation visible field cannot be normalized",
                         details={"queId": que_id},
-                    ),
-                    "visibleFields": [
-                        _require_selector(
-                            item.get("queId"),
-                            item.get("queTitle"),
-                            message="relation visible field cannot be normalized",
-                            details={"queId": que_id},
-                        )
-                        for item in visible
-                    ],
-                    "beingDefaultFormulaAutoFillEnabled": reference.get("beingDefaultFormulaAutoFillEnabled"),
-                    "defaultValueMatchRules": reference.get("defaultValueMatchRules"),
-                    "defaultValues": question.get("queDefaultValues") if isinstance(question.get("queDefaultValues"), dict) else None,
-                }
-            )
+                    )
+                    for item in visible
+                ],
+                "beingDefaultFormulaAutoFillEnabled": reference.get("beingDefaultFormulaAutoFillEnabled"),
+                "defaultValueMatchRules": reference.get("defaultValueMatchRules"),
+                "defaultValues": question.get("queDefaultValues") if isinstance(question.get("queDefaultValues"), dict) else None,
+            }
+            if supports_reference_default_formula:
+                relation_config["defaultValueFormula"] = reference.get("defaultValueFormula")
+            field["config"] = _without_none(relation_config)
         elif field_type == "q_linker":
             field["config"] = {"qLinkerBinding": self._q_linker_binding(question, relations, field_names)}
         elif field_type == "code_block":
@@ -691,14 +859,12 @@ class AppFormNormalizer:
             field["config"] = self._data_relation_config(question, relations)
         elif field_type == "subtable":
             field["subfields"] = [
-                self._field(item, relations, select_scope_relations, None, None, field_names)
+                self._field(item, relations, select_scope_relations, field_names, supports_reference_default_formula)
                 for item in question.get("subQuestions") or []
                 if isinstance(item, dict)
             ]
             for subfield in field["subfields"]:
                 subfield.pop("width", None)
-                subfield.pop("dataTitle", None)
-                subfield.pop("dataCover", None)
             field["config"] = _without_none({
                 "tableRowsLimit": question.get("tableRowsLimit"),
                 "tableNoRepeatStatus": question.get("tableNoRepeatStatus"),
@@ -708,12 +874,6 @@ class AppFormNormalizer:
             })
         return field
 
-    @staticmethod
-    def _style(value: Any) -> JSONObject | None:
-        if not isinstance(value, dict) or not any(value.get(key) is not None for key in ("bgImage", "bgColor", "opacity", "headerImage", "headerColor", "fontColor")):
-            return None
-        return {key: value.get(key) for key in ("bgImage", "bgColor", "opacity", "headerImage", "headerColor", "fontColor") if key in value}
-
     @staticmethod
     def _attachments(value: Any) -> list[JSONObject]:
         result = [
@@ -812,7 +972,14 @@ class AppFormNormalizer:
                 if not isinstance(item, dict):
                     continue
                 if _positive_int(item.get("type")) == 2:
-                    inputs.append({"field": _selector(item.get("value"), None), "key": str(item.get("key") or ""), "source": source})
+                    input_que_id = _positive_int(item.get("value"))
+                    inputs.append(
+                        {
+                            "field": _selector(input_que_id, field_names.get(input_que_id or -1)),
+                            "key": str(item.get("key") or ""),
+                            "source": source,
+                        }
+                    )
                 else:
                     static[key].append({"key": str(item.get("key") or ""), "value": item.get("value")})
         request_values = {
@@ -828,9 +995,19 @@ class AppFormNormalizer:
             def replace_reference(match: re.Match[str]) -> str:
                 name = match.group("name").strip()
                 if name:
+                    token = match.group("token").strip()
+                    matching_ids = [
+                        que_id
+                        for que_id, field_name in field_names.items()
+                        if field_name == name and _encrypt_question_id(que_id) == token
+                    ]
                     json_path_inputs.setdefault(
                         name,
-                        {"field": {"name": name}, "key": name, "source": "json_path"},
+                        {
+                            "field": _selector(matching_ids[0] if len(matching_ids) == 1 else None, name),
+                            "key": name,
+                            "source": "json_path",
+                        },
                     )
                 return "{{" + name + "}}"
 
@@ -973,7 +1150,7 @@ class AppFormNormalizer:
             if not bool(sort.get("status")):
                 result["sort"] = {"enabled": False}
             elif _positive_int(sort.get("queId")):
-                result["sort"] = {"enabled": True, "by": {"kind": "field", "field": _selector(sort.get("queId"), sort.get("queTitle"))}, "direction": "asc" if sort.get("ascend") else "desc"}
+                result["sort"] = {"enabled": True, "by": {"kind": "field", "field": _selector(sort.get("queId"), None)}, "direction": "asc" if sort.get("ascend") else "desc"}
             elif str(sort.get("qlinkerAlias") or "").strip():
                 producer = _require_selector(
                     alias.get("queId"),
@@ -994,12 +1171,12 @@ class AppFormNormalizer:
             else:
                 raise AppFormFailure("UNSUPPORTED_FIELD_CONFIG", "data_relation sort cannot be normalized", "NORMALIZE", details={"queId": que_id})
         button = question.get("customButtonConfig") if isinstance(question.get("customButtonConfig"), dict) else None
-        if button is not None:
+        if button is not None and bool(button.get("status")):
             detail = button.get("customButtonDetailInfo") if isinstance(button.get("customButtonDetailInfo"), dict) else {}
             button_id = _positive_int(detail.get("buttonId")) or _positive_int(button.get("buttonId"))
-            if bool(button.get("status")) and button_id is None:
+            if button_id is None:
                 raise AppFormFailure("UNSUPPORTED_FIELD_CONFIG", "enabled data_relation custom button has no buttonId", "NORMALIZE", details={"queId": que_id})
-            result["customButton"] = {"enabled": bool(button.get("status")), **({"buttonId": button_id} if bool(button.get("status")) and button_id else {})}
+            result["customButton"] = {"enabled": True, "buttonId": button_id}
         return result
 
     @staticmethod
@@ -1013,7 +1190,16 @@ class AppFormNormalizer:
         }
         match_type = _positive_int(value.get("matchType")) or 1
         if match_type == 1:
-            condition["operand"] = {"kind": "literal", "values": deepcopy(value.get("judgeValues") or [])}
+            details = value.get("judgeValueDetails")
+            if isinstance(details, list):
+                literal_values = [
+                    str(item.get("value") if item.get("value") is not None else item.get("id"))
+                    for item in details
+                    if isinstance(item, dict) and (item.get("value") is not None or item.get("id") is not None)
+                ]
+            else:
+                literal_values = deepcopy(value.get("judgeValues") or [])
+            condition["operand"] = {"kind": "literal", "values": literal_values}
         elif match_type == 2:
             detail = value.get("judgeQueDetail") if isinstance(value.get("judgeQueDetail"), dict) else {}
             condition["operand"] = {
@@ -1103,6 +1289,62 @@ class AppFormCompiler:
                     details={"field": name},
                 )
             field["queId"] = que_id
+            field_type = _field_type(field)
+            alias_binding = {
+                "code_block": ("codeBlockBinding", "codeBlockConfig", "resultAliasPath"),
+                "q_linker": ("qLinkerBinding", "remoteLookupConfig", "resultFormatPath"),
+            }.get(field_type)
+            if alias_binding is not None:
+                binding_key, backend_config_key, backend_aliases_key = alias_binding
+                config = field.get("config") if isinstance(field.get("config"), dict) else {}
+                binding = config.get(binding_key) if isinstance(config.get(binding_key), dict) else {}
+                outputs = binding.get("outputs") if isinstance(binding.get("outputs"), list) else []
+                backend_config = question.get(backend_config_key) if isinstance(question.get(backend_config_key), dict) else {}
+                backend_aliases = [
+                    item
+                    for item in backend_config.get(backend_aliases_key) or []
+                    if isinstance(item, dict)
+                ]
+                for output_index, output in enumerate(outputs):
+                    if not isinstance(output, dict):
+                        continue
+                    alias_name = str(output.get("alias") or "").strip()
+                    alias_path = str(output.get("path") or "").strip()
+                    matches = [
+                        item
+                        for item in backend_aliases
+                        if str(item.get("aliasName") or "").strip() == alias_name
+                        and str(item.get("aliasPath") or "").strip() == alias_path
+                    ]
+                    if len(matches) != 1:
+                        raise AppFormFailure(
+                            "RELATION_REBIND_FAILED",
+                            "identity write did not return a unique output alias identity",
+                            "IDENTITY_REBOUND",
+                            details={
+                                "field": name,
+                                "fieldType": field_type,
+                                "outputIndex": output_index,
+                                "alias": alias_name,
+                                "path": alias_path,
+                                "matches": len(matches),
+                            },
+                        )
+                    alias_id = _positive_int(matches[0].get("aliasId"))
+                    if alias_id is None:
+                        raise AppFormFailure(
+                            "RELATION_REBIND_FAILED",
+                            "identity write returned an output alias without aliasId",
+                            "IDENTITY_REBOUND",
+                            details={
+                                "field": name,
+                                "fieldType": field_type,
+                                "outputIndex": output_index,
+                                "alias": alias_name,
+                                "path": alias_path,
+                            },
+                        )
+                    output["aliasId"] = alias_id
             subquestions = [item for item in question.get("subQuestions") or [] if isinstance(item, dict)]
             for subfield in field.get("subfields") or []:
                 if not isinstance(subfield, dict):
@@ -1169,17 +1411,18 @@ class AppFormCompiler:
     ) -> JSONObject:
         resource = self.bind_backend_identities(form=form, resource=declaration)
         spec = resource["spec"]
+        field_names = AppFormNormalizer._field_index(form)
+        title_id = _positive_int(form.get("dataTitleQueId"))
+        cover_id = _positive_int(form.get("dataCoverQueId"))
         spec.setdefault("appName", str(form.get("formTitle") or ""))
-        spec.setdefault("description", form.get("formDesc") or None)
-        spec.setdefault("theme", form.get("formTheme"))
-        spec.setdefault("style", AppFormNormalizer._style(form.get("formStyle")))
+        spec.setdefault("appDescription", form.get("formDesc") or None)
+        spec.setdefault("dataTitleField", _selector(title_id, field_names.get(title_id or 0)) if title_id is not None else None)
+        spec.setdefault("dataCoverField", _selector(cover_id, field_names.get(cover_id or 0)) if cover_id is not None else None)
         spec.setdefault("attachments", AppFormNormalizer._attachments(form.get("formAttach")))
         spec.setdefault(
             "serialNumber",
             AppFormNormalizer._serial_number(form.get("serialNumType"), form.get("serialNumConfig")),
         )
-        spec.pop("icon", None)
-        spec.pop("color", None)
         resource["apiVersion"] = context.api_version
         resource["appKey"] = app_key
         resource.pop("packageId", None)
@@ -1189,23 +1432,28 @@ class AppFormCompiler:
         current_spec = current["spec"]
         declared_spec = declaration["spec"]
         target_spec = deepcopy(current_spec)
-        for key in ("appName", "description", "theme", "attachments", "serialNumber"):
+        for key in ("appName", "appDescription", "dataTitleField", "dataCoverField", "attachments", "serialNumber"):
             if key in declared_spec:
                 target_spec[key] = deepcopy(declared_spec[key])
-        if "style" in declared_spec:
-            if declared_spec["style"] is None:
-                target_spec["style"] = None
-            else:
-                merged = deepcopy(current_spec.get("style") or {})
-                merged.update(deepcopy(declared_spec["style"]))
-                target_spec["style"] = merged or None
         target_spec["body"] = self._target_body(current_spec.get("body") or [], declared_spec.get("body") or [])
-        self._validate_target(target_spec["body"])
+        target_fields = list(_iter_fields(target_spec["body"]))
+        for key in ("dataTitleField", "dataCoverField"):
+            if key in declared_spec or not isinstance(target_spec.get(key), dict):
+                continue
+            selector_id = _positive_int(target_spec[key].get("queId"))
+            selected = [field for field in target_fields if selector_id is not None and _positive_int(field.get("queId")) == selector_id]
+            if len(selected) == 1:
+                target_spec[key] = _selector(selected[0].get("queId"), selected[0].get("name"))
+        data_title, data_cover = self._validate_target(target_spec)
+        target_spec["dataTitleField"] = _selector(data_title.get("queId"), data_title.get("name")) if data_title is not None else None
+        target_spec["dataCoverField"] = _selector(data_cover.get("queId"), data_cover.get("name")) if data_cover is not None else None
         return {"apiVersion": context.api_version, "appKey": app_key, "spec": target_spec}
 
     def preflight(self, *, profile: str, app_key: str, declaration: JSONObject, current_form: JSONObject | None) -> None:
-        body = declaration.get("spec", {}).get("body") or []
-        self._validate_target(body)
+        declaration = self._resolve_declared_field_names(declaration, current_form)
+        spec = declaration.get("spec", {})
+        body = spec.get("body") or []
+        self._validate_target(spec, allow_missing_data_title=current_form is not None)
         fields = list(_iter_fields(body))
         templates = self._question_templates(current_form or {})
         internal_fields = [self._internal_field(field, templates=templates) for field in fields]
@@ -1215,16 +1463,17 @@ class AppFormCompiler:
             internal_fields, relations = _compile_code_block_binding_fields(fields=internal_fields, current_schema=current_form or {})
             relation_context = deepcopy(current_form or {})
             relation_context["questionRelations"] = relations
-            internal_fields, _ = _compile_q_linker_binding_fields(fields=internal_fields, current_schema=relation_context)
+            internal_fields, relations = _compile_q_linker_binding_fields(fields=internal_fields, current_schema=relation_context)
+            self._validate_unique_relation_targets(relations, internal_fields)
         except (KeyError, ValueError) as error:
             raise AppFormFailure("UNSUPPORTED_FIELD_CONFIG", str(error), "CONTRACT_PRECHECK") from error
         self._assign_subfield_temp_ids(internal_fields)
         for field in fields:
             config = field.get("config") if isinstance(field.get("config"), dict) else {}
-            if field.get("type") == "relation":
+            if _field_type(field) == "relation":
                 template = templates.get(_positive_int(field.get("queId")) or -1, {}).get("referenceConfig")
                 self._reference_config(profile, config, template if isinstance(template, dict) else None)
-            elif field.get("type") == "q_linker":
+            elif _field_type(field) == "q_linker":
                 for index, item in enumerate((config.get("qLinkerBinding") or {}).get("inputs") or []):
                     if not isinstance(item, dict) or item.get("source") != "json_path":
                         continue
@@ -1236,11 +1485,51 @@ class AppFormCompiler:
                             "CONTRACT_PRECHECK",
                             details={"key": item.get("key"), "field": selected.get("name")},
                         )
-            elif field.get("type") == "data_relation" and "customButton" in config:
+            elif _field_type(field) == "data_relation" and "customButton" in config:
                 template = templates.get(_positive_int(field.get("queId")) or -1)
                 self._data_relation_custom_button(config.get("customButton") or {}, template)
         self._data_relation_relations(profile, app_key, fields, internal_fields)
 
+    @staticmethod
+    def _resolve_declared_field_names(
+        declaration: JSONObject,
+        current_form: JSONObject | None,
+    ) -> JSONObject:
+        """Fill names for ID-only updates before compilation consumes field names."""
+        result = deepcopy(declaration)
+        current_names = AppFormNormalizer._field_index(current_form or {})
+
+        def visit(field: Any, path: str) -> None:
+            if not isinstance(field, dict):
+                return
+            if not str(field.get("name") or "").strip():
+                que_id = _positive_int(field.get("queId"))
+                name = current_names.get(que_id or 0)
+                if name:
+                    field["name"] = name
+                else:
+                    raise AppFormFailure(
+                        "INVALID_SPEC",
+                        "field name is required unless queId identifies an existing field",
+                        "CONTRACT_PRECHECK",
+                        details={"path": path, "queId": field.get("queId")},
+                    )
+            for index, child in enumerate(field.get("subfields") or []):
+                visit(child, f"{path}/subfields/{index}")
+
+        spec = result.get("spec") if isinstance(result.get("spec"), dict) else {}
+        body = spec.get("body") or []
+        for block_index, block in enumerate(body):
+            if not isinstance(block, dict):
+                continue
+            rows = [block] if block.get("kind") == "row" else block.get("rows") or []
+            for row_index, row in enumerate(rows):
+                if not isinstance(row, dict):
+                    continue
+                for field_index, field in enumerate(row.get("fields") or []):
+                    visit(field, f"/spec/body/{block_index}/rows/{row_index}/fields/{field_index}")
+        return result
+
     @staticmethod
     def _assign_layout_temp_ids(body: list[Any], internal_fields: list[JSONObject]) -> None:
         """Assign one temporary-ID sequence to fields and new section wrappers."""
@@ -1319,7 +1608,42 @@ class AppFormCompiler:
             for question in row if isinstance(row, list) else []:
                 visit(question)
 
-    def _target_body(self, current_body: list[Any], declared_body: list[Any]) -> list[JSONObject]:
+    @staticmethod
+    def _validate_unique_relation_targets(relations: list[JSONObject], fields: list[JSONObject]) -> None:
+        field_names: dict[int, str] = {}
+        for field in fields:
+            field_ref = _positive_int(field.get("que_id"))
+            if field_ref is None:
+                field_ref = _coerce_any_int(field.get("que_temp_id"))
+            if field_ref is not None:
+                field_names[field_ref] = str(field.get("name") or field_ref)
+        by_target: dict[int, JSONObject] = {}
+        for relation in relations:
+            target_ref = _coerce_any_int(relation.get("queId"))
+            if target_ref is None:
+                continue
+            previous = by_target.get(target_ref)
+            if previous is None:
+                by_target[target_ref] = relation
+                continue
+            target_name = field_names.get(target_ref, str(target_ref))
+            producers = []
+            for item in (previous, relation):
+                alias_config = item.get("aliasConfig") if isinstance(item.get("aliasConfig"), dict) else {}
+                producer = str(alias_config.get("queTitle") or "").strip()
+                producers.append(producer or f"relationType={item.get('relationType')}")
+            raise ValueError(
+                f"field '{target_name}' is targeted by multiple default-value relations "
+                f"({producers[0]}, {producers[1]}); each field can receive output from only one relation"
+            )
+
+    def _target_body(
+        self,
+        current_body: list[Any],
+        declared_body: list[Any],
+        *,
+        subfields: bool = False,
+    ) -> list[JSONObject]:
         current_fields = list(_iter_fields(current_body))
         by_id = {_positive_int(field.get("queId")): field for field in current_fields if _positive_int(field.get("queId"))}
         sections_by_id = {
@@ -1337,8 +1661,8 @@ class AppFormCompiler:
             target = _deep_overlay(current or {}, declared)
             if "config" in declared:
                 target["config"] = deepcopy(declared["config"])
-            target.setdefault("required", False)
-            target.setdefault("description", None)
+            target.setdefault("beingRequired", False)
+            target.setdefault("questionDescription", None)
             if target.get("defaultValue") is not None:
                 target.setdefault("defaultType", 1)
             if "defaultValue" in declared and declared.get("defaultValue") is None:
@@ -1349,8 +1673,8 @@ class AppFormCompiler:
                 target["queId"] = current.get("queId")
             else:
                 target.pop("queId", None)
-            if target.get("type") in CHOICE_TYPES and "config" not in declared and current is None:
-                target["config"] = {"options": ["是", "否"] if target.get("type") == "single_choice" else []}
+            if _field_type(target) in CHOICE_TYPES and "config" not in declared and current is None:
+                target["config"] = {"options": ["是", "否"] if _field_type(target) == "single_choice" else []}
             return target
 
         def target_field(declared: JSONObject, *, nested: bool) -> JSONObject:
@@ -1363,7 +1687,7 @@ class AppFormCompiler:
                 comparable.pop("queId", None)
                 candidates = []
                 for candidate in current_fields:
-                    if id(candidate) in claimed_fields or candidate.get("type") != declared.get("type"):
+                    if id(candidate) in claimed_fields or _field_type(candidate) != _field_type(declared):
                         continue
                     merged = merge_field(candidate, comparable)
                     if _field_semantic(merged) == _field_semantic(candidate):
@@ -1376,16 +1700,17 @@ class AppFormCompiler:
                         details={"name": declared.get("name"), "queIds": [item.get("queId") for item in candidates]},
                     )
                 current = candidates[0] if candidates else None
-            if current is not None and current.get("type") != declared.get("type"):
-                raise AppFormFailure("FIELD_TYPE_IMMUTABLE", "field type cannot be changed in place", "CONTRACT_PRECHECK", details={"queId": current.get("queId"), "currentType": current.get("type"), "targetType": declared.get("type")})
+            if current is not None and _field_type(current) != _field_type(declared):
+                raise AppFormFailure("FIELD_TYPE_IMMUTABLE", "field type cannot be changed in place", "CONTRACT_PRECHECK", details={"queId": current.get("queId"), "currentType": _field_type(current), "targetType": _field_type(declared)})
             if current is not None:
                 claimed_fields.add(id(current))
             target = merge_field(current, declared)
-            if target.get("type") == "subtable":
+            if _field_type(target) == "subtable":
                 current_subfields = current.get("subfields") if isinstance((current or {}).get("subfields"), list) else []
                 target["subfields"] = self._target_body(
                     [{"kind": "row", "fields": current_subfields}],
                     [{"kind": "row", "fields": target.get("subfields") or []}],
+                    subfields=True,
                 )[0]["fields"]
                 for item in target["subfields"]:
                     item.pop("width", None)
@@ -1397,13 +1722,15 @@ class AppFormCompiler:
         for block in declared_body:
             target_block = deepcopy(block)
             if block.get("kind") == "row":
-                target_block["fields"] = [target_field(field, nested=False) for field in block.get("fields") or []]
-                self._fill_widths(target_block["fields"])
+                target_block["fields"] = [target_field(field, nested=subfields) for field in block.get("fields") or []]
+                if not subfields:
+                    self._fill_widths(target_block["fields"])
             else:
                 target_block["rows"] = []
                 for row in block.get("rows") or []:
-                    fields = [target_field(field, nested=False) for field in row.get("fields") or []]
-                    self._fill_widths(fields)
+                    fields = [target_field(field, nested=subfields) for field in row.get("fields") or []]
+                    if not subfields:
+                        self._fill_widths(fields)
                     target_block["rows"].append({"fields": fields})
                 section_id = str(block.get("sectionId") or "")
                 current_section = sections_by_id.get(section_id) if section_id else None
@@ -1443,40 +1770,75 @@ class AppFormCompiler:
         if any(present) and not all(present):
             raise AppFormFailure("INVALID_ROW_WIDTH", "all fields in a row must provide width together", "CONTRACT_PRECHECK")
         if all(present):
+            if any(_positive_int(field.get("width")) not in {25, 50, 75, 100} for field in fields):
+                raise AppFormFailure("INVALID_ROW_WIDTH", "field widths must be one of 25, 50, 75, or 100", "CONTRACT_PRECHECK")
             if sum(int(field["width"]) for field in fields) != 100:
                 raise AppFormFailure("INVALID_ROW_WIDTH", "field widths in a row must total 100", "CONTRACT_PRECHECK")
             return
-        width, remainder = divmod(100, len(fields))
-        for index, field in enumerate(fields):
-            field["width"] = width + (1 if index < remainder else 0)
+        widths = {
+            1: [100],
+            2: [50, 50],
+            3: [50, 25, 25],
+            4: [25, 25, 25, 25],
+        }[len(fields)]
+        for field, width in zip(fields, widths, strict=True):
+            field["width"] = width
 
     @staticmethod
-    def _validate_target(body: list[JSONObject]) -> None:
+    def _validate_target(
+        spec: JSONObject,
+        *,
+        allow_missing_data_title: bool = False,
+    ) -> tuple[JSONObject | None, JSONObject | None]:
+        body = spec.get("body") or []
         fields = list(_iter_fields(body))
         names: set[str] = set()
-        title_count = 0
-        cover_count = 0
         for field in fields:
             name = str(field.get("name") or "")
             if name in names:
                 raise AppFormFailure("DUPLICATE_FIELD_NAME", f"duplicate top-level field name: {name}", "CONTRACT_PRECHECK")
             names.add(name)
-            title_count += int(bool(field.get("dataTitle")))
-            cover_count += int(bool(field.get("dataCover")))
-            if field.get("dataCover") and field.get("type") != "attachment":
-                raise AppFormFailure("INVALID_DATA_COVER_FIELD", "dataCover must be an attachment field", "CONTRACT_PRECHECK")
-            if field.get("type") == "subtable":
+            if _field_type(field) == "subtable":
                 sub_names: set[str] = set()
                 for subfield in field.get("subfields") or []:
-                    if subfield.get("type") not in SUBFIELD_TYPES:
+                    if _field_type(subfield) not in SUBFIELD_TYPES:
                         raise AppFormFailure("INVALID_SPEC", "unsupported subtable field type", "CONTRACT_PRECHECK", details={"allowedTypes": sorted(SUBFIELD_TYPES)})
                     if subfield.get("name") in sub_names:
                         raise AppFormFailure("DUPLICATE_FIELD_NAME", f"duplicate subtable field name: {subfield.get('name')}", "CONTRACT_PRECHECK")
                     sub_names.add(str(subfield.get("name") or ""))
-        if fields and title_count != 1:
-            raise AppFormFailure("INVALID_DATA_TITLE_FIELD", "non-empty body must contain exactly one dataTitle field", "CONTRACT_PRECHECK")
-        if cover_count > 1:
-            raise AppFormFailure("INVALID_DATA_COVER_FIELD", "body can contain at most one dataCover field", "CONTRACT_PRECHECK")
+        title_selector = spec.get("dataTitleField")
+        data_title: JSONObject | None = None
+        if fields:
+            if title_selector is None and allow_missing_data_title and "dataTitleField" not in spec:
+                pass
+            elif not isinstance(title_selector, dict):
+                raise AppFormFailure(
+                    "INVALID_DATA_TITLE_FIELD",
+                    "non-empty body requires a dataTitleField selector",
+                    "CONTRACT_PRECHECK",
+                )
+            else:
+                data_title = _resolve_canonical_selector(title_selector, fields, "dataTitleField")
+        elif title_selector is not None:
+            raise AppFormFailure(
+                "INVALID_DATA_TITLE_FIELD",
+                "dataTitleField must be null when body is empty",
+                "CONTRACT_PRECHECK",
+            )
+
+        cover_selector = spec.get("dataCoverField")
+        data_cover: JSONObject | None = None
+        if cover_selector is not None:
+            if not isinstance(cover_selector, dict):
+                raise AppFormFailure("INVALID_DATA_COVER_FIELD", "dataCoverField must be a field selector or null", "CONTRACT_PRECHECK")
+            data_cover = _resolve_canonical_selector(cover_selector, fields, "dataCoverField")
+            if _field_type(data_cover) != "attachment":
+                raise AppFormFailure(
+                    "INVALID_DATA_COVER_FIELD",
+                    "dataCoverField must select a top-level attachment field",
+                    "CONTRACT_PRECHECK",
+                )
+        return data_title, data_cover
 
     def payload(
         self,
@@ -1497,6 +1859,7 @@ class AppFormCompiler:
             relation_context = deepcopy(current_form)
             relation_context["questionRelations"] = relations
             internal_fields, relations = _compile_q_linker_binding_fields(fields=internal_fields, current_schema=relation_context)
+            self._validate_unique_relation_targets(relations, internal_fields)
         except (KeyError, ValueError) as error:
             raise AppFormFailure("UNSUPPORTED_FIELD_CONFIG", str(error), "COMPILE") from error
         self._assign_subfield_temp_ids(internal_fields)
@@ -1553,8 +1916,9 @@ class AppFormCompiler:
                 rows.append([section])
         payload["formQues"] = rows
         self._validate_unique_temp_ids(rows)
-        data_title = next((field for field in target_fields if field.get("dataTitle")), None)
-        data_cover = next((field for field in target_fields if field.get("dataCover")), None)
+        data_title = _resolve_canonical_selector(target["spec"]["dataTitleField"], target_fields, "dataTitleField") if target_fields else None
+        data_cover_selector = target["spec"].get("dataCoverField")
+        data_cover = _resolve_canonical_selector(data_cover_selector, target_fields, "dataCoverField") if isinstance(data_cover_selector, dict) else None
         payload["dataTitleQueId"] = self._field_runtime_id(data_title, internal_fields)
         payload["dataCoverQueId"] = self._field_runtime_id(data_cover, internal_fields) if data_cover else None
         payload["questionRelations"].extend(data_relations)
@@ -1569,8 +1933,8 @@ class AppFormCompiler:
             config = field.get("config") if isinstance(field.get("config"), dict) else {}
             binding = config.get("qLinkerBinding") or config.get("codeBlockBinding")
             if _positive_int(field.get("queId")) is None and (
-                field.get("type") in {"q_linker", "data_relation"}
-                or field.get("type") == "code_block" and bool((binding or {}).get("outputs"))
+                _field_type(field) in {"q_linker", "data_relation"}
+                or _field_type(field) == "code_block" and bool((binding or {}).get("outputs"))
             ):
                 return True
             if isinstance(binding, dict):
@@ -1578,7 +1942,7 @@ class AppFormCompiler:
                 selectors += [item.get("targetField") for item in binding.get("outputs") or [] if isinstance(item, dict)]
                 if any(isinstance(selector, dict) and not _positive_int(selector.get("queId")) and selector.get("name") in missing_names for selector in selectors):
                     return True
-            if field.get("type") == "data_relation" and json.dumps(config, ensure_ascii=False, sort_keys=True):
+            if _field_type(field) == "data_relation" and json.dumps(config, ensure_ascii=False, sort_keys=True):
                 for selector in _walk_selectors(config):
                     if not _positive_int(selector.get("queId")) and selector.get("name") in missing_names:
                         return True
@@ -1593,8 +1957,8 @@ class AppFormCompiler:
             config = field.get("config") if isinstance(field.get("config"), dict) else {}
             binding = config.get("qLinkerBinding") or config.get("codeBlockBinding")
             if _positive_int(field.get("queId")) is None and (
-                field.get("type") in {"q_linker", "data_relation"}
-                or field.get("type") == "code_block" and bool((binding or {}).get("outputs"))
+                _field_type(field) in {"q_linker", "data_relation"}
+                or _field_type(field) == "code_block" and bool((binding or {}).get("outputs"))
             ):
                 pending.append(
                     {
@@ -1612,7 +1976,7 @@ class AppFormCompiler:
                     selector = item.get("targetField") if isinstance(item, dict) else None
                     if isinstance(selector, dict) and not _positive_int(selector.get("queId")) and selector.get("name") in missing_names:
                         pending.append({"field": field.get("name"), "path": f"outputs/{index}", "selector": deepcopy(selector)})
-            if field.get("type") == "data_relation":
+            if _field_type(field) == "data_relation":
                 for selector in _walk_selectors(config):
                     if not _positive_int(selector.get("queId")) and selector.get("name") in missing_names:
                         pending.append({"field": field.get("name"), "path": "config", "selector": deepcopy(selector)})
@@ -1706,14 +2070,14 @@ class AppFormCompiler:
                     temp_id -= 1
 
     def _internal_field(self, field: JSONObject, *, templates: dict[int, JSONObject]) -> JSONObject:
-        canonical_type = str(field.get("type"))
+        canonical_type = _field_type(field)
         internal_type = "boolean" if canonical_type == "single_choice" else canonical_type
         config = field.get("config") if isinstance(field.get("config"), dict) else {}
         result: JSONObject = {
             "name": field["name"],
             "type": internal_type,
-            "required": bool(field.get("required")),
-            "description": field.get("description"),
+            "required": _field_required(field),
+            "description": field.get("questionDescription"),
             "que_id": _positive_int(field.get("queId")),
             "options": deepcopy(config.get("options") or []),
             "subfields": [self._internal_field(item, templates=templates) for item in field.get("subfields") or []],
@@ -1775,7 +2139,7 @@ class AppFormCompiler:
         return result
 
     def _question(self, profile: str, app_key: str, field: JSONObject, internal: JSONObject, temp_id: int, relations: list[JSONObject]) -> JSONObject:
-        field_type = str(field["type"])
+        field_type = _field_type(field)
         que_type = CANONICAL_TO_QUE_TYPE[field_type]
         build_type = "boolean" if field_type == "single_choice" else "text" if field_type in {"link", "data_relation"} else field_type
         built_internal = deepcopy(internal)
@@ -1786,7 +2150,7 @@ class AppFormCompiler:
             generated = _field_to_question(built_internal, temp_id=temp_id)
         except (KeyError, ValueError):
             generated, _ = build_question(
-                {"label": field["name"], "type": FieldType.text, "required": bool(field.get("required")), "description": field.get("description"), "config": {}},
+                {"label": field["name"], "type": FieldType.text, "required": _field_required(field), "description": field.get("questionDescription"), "config": {}},
                 temp_id,
             )
         template = internal.get("_question_template") if isinstance(internal.get("_question_template"), dict) else None
@@ -1805,8 +2169,8 @@ class AppFormCompiler:
                 "queType": que_type,
                 "queTitle": field["name"],
                 "queWidth": int(field.get("width") or 100),
-                "required": bool(field.get("required")),
-                "queHint": field.get("description") or "",
+                "required": _field_required(field),
+                "queHint": field.get("questionDescription") or "",
             }
         )
         config = field.get("config") if isinstance(field.get("config"), dict) else {}
@@ -1973,6 +2337,7 @@ class AppFormCompiler:
                 ],
                 "referAuthQues": [{"queId": item["queId"], "queAuth": 1} for item in visible],
                 "beingDefaultFormulaAutoFillEnabled": config.get("beingDefaultFormulaAutoFillEnabled"),
+                "defaultValueFormula": config.get("defaultValueFormula"),
                 "defaultValueMatchRules": deepcopy(config.get("defaultValueMatchRules")),
             }
         )
@@ -2045,7 +2410,7 @@ class AppFormCompiler:
         available_internal_fields = list(_iter_field_tree(internal_fields))
         result = []
         for field, internal in _iter_field_pairs(fields, internal_fields):
-            if field.get("type") != "data_relation":
+            if _field_type(field) != "data_relation":
                 continue
             config = field.get("config") or {}
             source = config.get("source") or {}
@@ -2196,7 +2561,17 @@ class AppFormCompiler:
             "judgeType": JUDGE_TYPE_TO_BACKEND[operator],
         }
         if operand.get("kind") == "literal":
-            payload.update({"matchType": 1, "judgeValues": deepcopy(operand.get("values") or [])})
+            judge_values, judge_value_details = cls._data_relation_literal_values(
+                source,
+                deepcopy(operand.get("values") or []),
+            )
+            payload.update(
+                {
+                    "matchType": 1,
+                    "judgeValues": judge_values,
+                    "judgeValueDetails": judge_value_details,
+                }
+            )
         elif operand.get("kind") == "current_field":
             target = _resolve_internal_selector(operand.get("field") or {}, current_fields, "operand.field")
             target_id = target.get("que_id") or target.get("que_temp_id")
@@ -2213,6 +2588,53 @@ class AppFormCompiler:
             )
         return payload
 
+    @staticmethod
+    def _data_relation_literal_values(source: JSONObject, values: list[Any]) -> tuple[list[str], list[JSONObject]]:
+        field_type = _canonical_backend_field_type(source)
+        options = [item for item in source.get("options") or [] if isinstance(item, dict)]
+        option_by_name = {
+            str(item.get("optValue")): item
+            for item in options
+            if item.get("optValue") is not None
+        }
+        option_by_id = {
+            str(item.get("optId")): item
+            for item in options
+            if _positive_int(item.get("optId")) is not None
+        }
+        judge_values: list[str] = []
+        details: list[JSONObject] = []
+        for value in values:
+            if isinstance(value, bool):
+                text = "true" if value else "false"
+            elif isinstance(value, (str, int, float)):
+                text = str(value)
+            else:
+                raise AppFormFailure(
+                    "UNSUPPORTED_FIELD_CONFIG",
+                    "literal data_relation values must be strings",
+                    "CONTRACT_PRECHECK",
+                    details={"field": AppFormCompiler._data_relation_field_name(source), "value": value},
+                )
+            if field_type in CHOICE_TYPES and options:
+                option = option_by_name.get(text) or option_by_id.get(text)
+                if option is None:
+                    raise AppFormFailure(
+                        "UNSUPPORTED_FIELD_CONFIG",
+                        f"literal value {text!r} is not an option of data_relation source field "
+                        f"{AppFormCompiler._data_relation_field_name(source)!r}",
+                        "CONTRACT_PRECHECK",
+                        details={"value": text, "allowedValues": sorted(option_by_name)},
+                    )
+                option_id = _positive_int(option.get("optId"))
+                option_name = str(option.get("optValue") or text)
+                judge_values.append(str(option_id) if option_id is not None else option_name)
+                details.append(_without_none({"id": option_id, "value": option_name}))
+                continue
+            judge_values.append(text)
+            details.append({"value": text})
+        return judge_values, details
+
     @staticmethod
     def _resolve_data_relation_source_field(
         selector: JSONObject,
@@ -2238,7 +2660,7 @@ class AppFormCompiler:
         backend_type = _positive_int(field.get("queType"))
         if backend_type is not None:
             return backend_type
-        return CANONICAL_TO_QUE_TYPE.get(str(field.get("_app_form_type") or field.get("type") or ""), 2)
+        return CANONICAL_TO_QUE_TYPE.get(str(field.get("_app_form_type") or _field_type(field)), 2)
 
     @staticmethod
     def _data_relation_alias_metadata(
@@ -2270,7 +2692,7 @@ class AppFormCompiler:
         output = matches[0]
         selector = output.get("target_field") or output.get("targetField") or {}
         target = _resolve_internal_selector(selector, internal_fields, "source.alias.targetField")
-        origin_type = CANONICAL_TO_QUE_TYPE.get(str(target.get("_app_form_type") or target.get("type") or ""))
+        origin_type = CANONICAL_TO_QUE_TYPE.get(str(target.get("_app_form_type") or _field_type(target)))
         if origin_type is None:
             raise AppFormFailure(
                 "UNSUPPORTED_FIELD_CONFIG",
@@ -2324,9 +2746,7 @@ class AppFormCompiler:
 
     def _apply_form_settings(self, payload: JSONObject, *, current_form: JSONObject, target_spec: JSONObject, internal_fields: list[JSONObject]) -> None:
         payload["formTitle"] = target_spec["appName"]
-        payload["formDesc"] = target_spec.get("description") or ""
-        payload["formTheme"] = target_spec.get("theme")
-        payload["formStyle"] = deepcopy(target_spec.get("style"))
+        payload["formDesc"] = target_spec.get("appDescription") or ""
         current_attachments = {
             (str(item.get("fileName") or item.get("name") or ""), str(item.get("fileUrl") or item.get("url") or "")): item
             for item in current_form.get("formAttach") or []
@@ -2414,9 +2834,22 @@ class AppFormReconciler:
         self.normalizer = AppFormNormalizer()
         self.compiler = AppFormCompiler(apps)
 
-    def schema(self, *, schema_version: str | None, field_type: str | None) -> JSONObject:
+    def schema(
+        self,
+        *,
+        schema_version: str | None,
+        field_type: str | None,
+        schema_kind: str | None = None,
+    ) -> JSONObject:
         try:
-            return {"status": "success", **self.registry.schema(schema_version=schema_version, field_type=field_type)}
+            return {
+                "status": "success",
+                **self.registry.schema(
+                    schema_version=schema_version,
+                    field_type=field_type,
+                    schema_kind=schema_kind,
+                ),
+            }
         except AppFormContractError as error:
             return self._failure(error.error_code, error.message, "SCHEMA", details=error.details)
 
@@ -2438,6 +2871,8 @@ class AppFormReconciler:
             context = self.registry.resolve_schema_version(schema_version)
             normalizer, _compiler = self._runtime_for(context)
             form = self._read_form(profile, app_key, being_draft=being_draft)
+            if not being_draft:
+                form = _normalize_published_scope_omissions(form)
             resource = normalizer.from_backend(context=context, app_key=app_key, form=form)
             context.validate(resource)
             return {"status": "success", "schemaVersion": context.schema_version, "source": "draft" if being_draft else "published", "resource": resource}
@@ -2474,8 +2909,6 @@ class AppFormReconciler:
                     "create mode requires packageId and spec.appName",
                     details={"mode": "create"},
                 )
-            if not is_update:
-                validate_app_form_create_icon(declaration)
             apply_dto = context.parse_apply(declaration)
             context.assert_apply_dto(apply_dto)
             declaration = apply_dto.resource
@@ -2517,7 +2950,7 @@ class AppFormReconciler:
                     raise
                 app_key = self._create(profile, declaration)
                 created = True
-                diagnostics["operation"] = "CREATED"
+                diagnostics["operation"] = "CREATE_IN_PROGRESS"
             try:
                 package_attached = self._package_contains(profile, package_id, app_key) if package_id is not None else None
             except (QingflowApiError, RuntimeError) as error:
@@ -2548,9 +2981,13 @@ class AppFormReconciler:
             publish_needed = created
             if not form_changed and not created:
                 try:
-                    published_form = self._read_form(profile, app_key, being_draft=False)
-                    published = normalizer.from_backend(context=context, app_key=app_key, form=published_form)
-                    publish_needed = not _canonical_equal(current, published)
+                    published = self._published_resource(
+                        profile=profile,
+                        app_key=app_key,
+                        context=context,
+                        normalizer=normalizer,
+                    )
+                    publish_needed = not _published_equal(current, published)
                 except (QingflowApiError, RuntimeError, AppFormFailure) as error:
                     raise AppFormFailure("PUBLISHED_FORM_READ_FAILED", str(error), "PRECHECK_PUBLISHED_READ") from error
             diagnostics["diff"] = self._diff(current, target)
@@ -2624,6 +3061,7 @@ class AppFormReconciler:
                         self._raise_write_failure(error, diagnostics, first_write=False)
                     diagnostics["writeCount"] += 1
                     diagnostics["formPhase"] = "RELATION_REBIND"
+                    diagnostics["pendingBindings"] = []
 
             if wrote_form:
                 draft_form = self._read_form(profile, app_key, being_draft=True)
@@ -2655,9 +3093,13 @@ class AppFormReconciler:
             publish_needed = created or wrote_form
             if not publish_needed:
                 try:
-                    published_form = self._read_form(profile, app_key, being_draft=False)
-                    published = normalizer.from_backend(context=context, app_key=app_key, form=published_form)
-                    diagnostics["published"] = _canonical_equal(draft, published)
+                    published = self._published_resource(
+                        profile=profile,
+                        app_key=app_key,
+                        context=context,
+                        normalizer=normalizer,
+                    )
+                    diagnostics["published"] = _published_equal(draft, published)
                     publish_needed = not diagnostics["published"]
                 except (QingflowApiError, RuntimeError, AppFormFailure) as error:
                     self._finish_edit(profile, app_key, edit_version_no, diagnostics)
@@ -2685,10 +3127,86 @@ class AppFormReconciler:
             diagnostics["operation"] = "CREATED" if created else "APPLIED" if wrote_form or publish_needed or diagnostics["packageAttachCount"] else "UNCHANGED"
             return self._success(context, draft, diagnostics, warnings)
         except AppFormContractError as error:
-            return self._failure(error.error_code, error.message, "VALIDATE", details={**error.details, **({"path": error.path} if error.path else {})}, diagnostics=diagnostics, app_key=app_key, warnings=warnings)
+            if created and app_key:
+                return self._rollback_created_after_failure(
+                    profile=profile,
+                    app_key=app_key,
+                    error_code=error.error_code,
+                    message=error.message,
+                    phase="VALIDATE",
+                    details={**error.details, **({"path": error.path} if error.path else {})},
+                    diagnostics=diagnostics,
+                    warnings=warnings,
+                )
+            diagnostics["operation"] = {
+                "create": "CREATE_FAILED",
+                "update": "UPDATE_FAILED",
+            }.get(str(diagnostics.get("applyMode") or ""), "VALIDATION_FAILED")
+            validation_diagnostics = {
+                key: diagnostics[key]
+                for key in ("operation", "applyMode")
+                if diagnostics.get(key) is not None
+            }
+            return self._failure(
+                error.error_code,
+                error.message,
+                "VALIDATE",
+                details={**error.details, **({"path": error.path} if error.path else {})},
+                diagnostics=validation_diagnostics,
+                app_key=app_key,
+                warnings=warnings,
+            )
         except AppFormFailure as error:
+            preserve_created_app = error.error_code == "APPLY_READBACK_MISMATCH"
+            if (
+                created
+                and app_key
+                and not preserve_created_app
+                and error.status != "unknown"
+                and diagnostics.get("writeMayHaveSucceeded") is not True
+            ):
+                return self._rollback_created_after_failure(
+                    profile=profile,
+                    app_key=app_key,
+                    error_code=error.error_code,
+                    message=error.message,
+                    phase=error.phase,
+                    details=error.details,
+                    diagnostics=diagnostics,
+                    warnings=warnings,
+                )
+            if created:
+                diagnostics["operation"] = "CREATE_INCOMPLETE"
+            else:
+                diagnostics["operation"] = {
+                    "create": "CREATE_FAILED",
+                    "update": "UPDATE_FAILED",
+                }.get(str(diagnostics.get("applyMode") or ""), "VALIDATION_FAILED")
             status = "partial_success" if created and error.status == "failed" else error.status
-            return self._failure(error.error_code, error.message, error.phase, status=status, details=error.details, diagnostics=diagnostics, app_key=app_key, warnings=warnings)
+            result = self._failure(error.error_code, error.message, error.phase, status=status, details=error.details, diagnostics=diagnostics, app_key=app_key, warnings=warnings)
+            if error.error_code == "APPLY_READBACK_MISMATCH" and app_key:
+                result["requiresFurtherRepair"] = True
+                result["mustReadCurrentStateBeforeRepair"] = True
+                result["nextApplyMode"] = "update"
+                result["suggested_next_call"] = {
+                    "tool_name": "app_form_get",
+                    "arguments": {
+                        "profile": profile,
+                        "app_key": app_key,
+                        "being_draft": True,
+                    },
+                }
+                if created:
+                    result["message"] = (
+                        "the application was created and its form was saved, but backend readback still differs from the apply target; "
+                        "the application was preserved and was not published"
+                    )
+                    result["createdAppPreserved"] = True
+                result["recoveryHint"] = (
+                    "first read the current draft using the returned appKey; compare it with remainingDiff, then merge the intended changes into that current state, "
+                    "keep the appKey in the declaration, validate, and apply again in update mode"
+                )
+            return result
         except (QingflowApiError, RuntimeError) as error:
             uncertain = self._is_uncertain_api_error(error)
             code = (
@@ -2700,6 +3218,24 @@ class AppFormReconciler:
                 if uncertain
                 else "APP_FORM_APPLY_FAILED"
             )
+            if created and app_key and not uncertain:
+                return self._rollback_created_after_failure(
+                    profile=profile,
+                    app_key=app_key,
+                    error_code=code,
+                    message=str(self._error_details(error).get("message") or error),
+                    phase="APPLY",
+                    details=self._error_details(error),
+                    diagnostics=diagnostics,
+                    warnings=warnings,
+                )
+            if created:
+                diagnostics["operation"] = "CREATE_INCOMPLETE"
+            else:
+                diagnostics["operation"] = {
+                    "create": "CREATE_FAILED",
+                    "update": "UPDATE_FAILED",
+                }.get(str(diagnostics.get("applyMode") or ""), "VALIDATION_FAILED")
             mutation_started = bool(
                 created
                 or diagnostics["writeAttempts"]
@@ -2709,6 +3245,60 @@ class AppFormReconciler:
             status = "unknown" if uncertain else "partial_success" if mutation_started else "failed"
             return self._api_failure(code, error, "CREATE" if not app_key else "APPLY", status=status, diagnostics=diagnostics, app_key=app_key, warnings=warnings)
 
+    def _rollback_created_after_failure(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        error_code: str,
+        message: str,
+        phase: str,
+        details: JSONObject | None,
+        diagnostics: JSONObject,
+        warnings: list[JSONObject],
+    ) -> JSONObject:
+        diagnostics["createRollbackAttempted"] = True
+        failure_details = deepcopy(details or {})
+        transport_error = failure_details.pop("transportError", None)
+        if isinstance(transport_error, dict):
+            failure_details["failureCause"] = deepcopy(transport_error)
+        try:
+            self.apps.app_delete(profile=profile, app_key=app_key)
+        except (QingflowApiError, RuntimeError) as rollback_error:
+            rollback_details = self._error_details(rollback_error)
+            uncertain = self._is_uncertain_api_error(rollback_error)
+            diagnostics["createRollbackSucceeded"] = None if uncertain else False
+            diagnostics["operation"] = "CREATE_ROLLBACK_UNKNOWN" if uncertain else "CREATE_ROLLBACK_FAILED"
+            failure_details["rollbackError"] = rollback_details
+            return self._failure(
+                error_code,
+                (
+                    "AppForm creation failed, and cleanup of the newly created application "
+                    f"{'could not be confirmed' if uncertain else 'also failed'}: {message}"
+                ),
+                phase,
+                status="unknown" if uncertain else "partial_success",
+                details=failure_details,
+                diagnostics=diagnostics,
+                app_key=app_key,
+                warnings=warnings,
+            )
+        diagnostics["createRollbackSucceeded"] = True
+        diagnostics["operation"] = "CREATE_ROLLED_BACK"
+        result = self._failure(
+            error_code,
+            f"AppForm creation failed and the newly created application was deleted: {message}",
+            phase,
+            status="failed",
+            details=failure_details,
+            diagnostics=diagnostics,
+            app_key=app_key,
+            warnings=warnings,
+        )
+        result["recoverable"] = True
+        result["recoveryHint"] = "fix the original failure cause, then submit the create declaration again"
+        return result
+
     def delete(self, *, profile: str, app_key: str) -> JSONObject:
         try:
             result = self.apps.app_delete(profile=profile, app_key=app_key)
@@ -2720,11 +3310,9 @@ class AppFormReconciler:
         spec = declaration["spec"]
         app_name = str(spec["appName"])
         package_id = int(declaration["packageId"])
-        icon = str(spec["icon"])
-        color = str(spec["color"])
         payload = {
             "appName": app_name,
-            "appIcon": encode_workspace_icon(icon=icon, color=color, title=app_name),
+            "appIcon": encode_workspace_icon_with_defaults(icon=None, color=None, title=app_name),
             "auth": default_member_auth(),
             "tagIds": [package_id],
         }
@@ -2912,14 +3500,30 @@ class AppFormReconciler:
         diagnostics: JSONObject,
     ) -> bool | None:
         try:
-            published_form = self._read_form(profile, app_key, being_draft=False)
             normalizer, _compiler = self._runtime_for(context)
-            published = normalizer.from_backend(context=context, app_key=app_key, form=published_form)
-            diagnostics["published"] = _canonical_equal(draft, published)
+            published = self._published_resource(
+                profile=profile,
+                app_key=app_key,
+                context=context,
+                normalizer=normalizer,
+            )
+            diagnostics["published"] = _published_equal(draft, published)
         except (QingflowApiError, RuntimeError, AppFormFailure):
             diagnostics["published"] = None
         return diagnostics["published"]
 
+    def _published_resource(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        context: AppFormSchemaContext,
+        normalizer: AppFormNormalizer,
+    ) -> JSONObject:
+        published_form = self._read_form(profile, app_key, being_draft=False)
+        comparable_form = _normalize_published_scope_omissions(published_form)
+        return normalizer.from_backend(context=context, app_key=app_key, form=comparable_form)
+
     def _finish_edit(self, profile: str, app_key: str, edit_version_no: int, diagnostics: JSONObject) -> None:
         try:
             self.apps.app_edit_finished(profile=profile, app_key=app_key, payload={"editVersionNo": edit_version_no})
@@ -2963,9 +3567,13 @@ class AppFormReconciler:
                 details={**diagnostics, "transportError": details},
             ) from error
         diagnostics["writeMayHaveSucceeded"] = self._is_uncertain_api_error(error)
+        backend_message = str(details.get("message") or "").strip()
+        message = "form write failed or could not be confirmed"
+        if backend_message:
+            message = f"{message}: {backend_message}"
         raise AppFormFailure(
             "APPLY_RESULT_UNKNOWN" if diagnostics["writeMayHaveSucceeded"] else "RELATION_REBIND_FAILED" if not first_write else "APP_FORM_WRITE_FAILED",
-            "form write failed or could not be confirmed",
+            message,
             diagnostics["formPhase"],
             status="unknown" if diagnostics["writeMayHaveSucceeded"] else "partial_success" if not first_write else "failed",
             details={**diagnostics, "transportError": details},
@@ -3351,6 +3959,25 @@ def _resolve_backend_selector(selector: JSONObject, candidates: list[JSONObject]
     return matches[0]
 
 
+def _resolve_canonical_selector(selector: JSONObject, candidates: list[JSONObject], location: str) -> JSONObject:
+    que_id = _positive_int(selector.get("queId"))
+    name = str(selector.get("name") or "")
+    matches = [
+        item
+        for item in candidates
+        if (que_id is None or _positive_int(item.get("queId")) == que_id)
+        and (not name or str(item.get("name") or "") == name)
+    ]
+    if len(matches) != 1:
+        raise AppFormFailure(
+            "INVALID_FIELD_SELECTOR",
+            f"{location} must resolve to exactly one top-level field",
+            "CONTRACT_PRECHECK",
+            details={"selector": selector, "matches": len(matches)},
+        )
+    return matches[0]
+
+
 def _resolve_internal_selector(selector: JSONObject, fields: list[JSONObject], location: str) -> JSONObject:
     que_id = _positive_int(selector.get("queId") or selector.get("que_id"))
     name = str(selector.get("name") or "")