@qingflow-tech/qingflow-cli 1.1.44 → 1.1.45

package/README.md

@@ -7,7 +7,7 @@ Qingflow CLI 是轻流面向开发者和 AI Agent 的命令行工具。它把轻
 ## 安装
 
 ```bash
-npm install @qingflow-tech/qingflow-cli@1.1.44
+npm install @qingflow-tech/qingflow-cli@1.1.45
 ```
 
 推荐从官网复制这一条一键安装 Qingflow CLI：
@@ -21,7 +21,7 @@ npx qingflow-cli@latest install
 ## 运行
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-cli@1.1.44 qingflow
+npx -y -p @qingflow-tech/qingflow-cli@1.1.45 qingflow
 ```
 
 全局安装后可以直接运行：
@@ -62,7 +62,7 @@ qingflow-skills install --agent codex --scope user
 如果你通过一次性 `npx -p` 执行 skills 安装，建议加 `--copy`，避免 symlink 指向 npm 临时执行缓存：
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-cli@1.1.44 qingflow-skills install --agent codex --scope user --copy
+npx -y -p @qingflow-tech/qingflow-cli@1.1.45 qingflow-skills install --agent codex --scope user --copy
 ```
 
 `qingflow-skills install` 默认使用 symlink，且遇到同名 skill 不会覆盖；只有显式传入 `--force` 才会替换。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qingflow-tech/qingflow-cli",
-  "version": "1.1.44",
+  "version": "1.1.45",
   "description": "Human-friendly Qingflow command line interface for auth, record operations, import, tasks, and stable builder flows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "1.1.44"
+version = "1.1.45"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/skills/qingflow-cli/reference/builder/30-schema-fields.md

@@ -219,6 +219,8 @@ current CLI payload.
 | `data_relation` | 数据关联/引用填充 |
 | `subtable` | 子表（**`subfields[]`**） |
 
+历史表单中的后端 `queType=1` 是“描述文字”布局控件，不属于上述新建字段类型。`app-form get` 为了保持完整声明可校验，会将它兼容输出为 `long_text`；`app-form apply` 会根据已有字段模板恢复原始 `queType=1` 和 `queDefaultValue`，所以修改其他字段时不会丢失描述文字。新建可填写多行文本仍使用 `long_text`，不要用它创建描述文字控件。
+
 **`config.relationMode`**：仅 **`relation`** 使用，取值为 **`single`** 或 **`multiple`**。一个应用可以有多个 `relation` 字段；不要因为 relation 数量超过 1 就改成文本字段。
 
 ### 1.1 历史字段类型别名
@@ -246,6 +248,10 @@ current CLI payload.
 | `q_linker` | **`config.qLinkerBinding`**：`inputs`、`request`、**`outputs[]` 每项须含 `targetField`**（能解析到本表单字段） | `request.url` 等须符合**租户/后端远程查询策略**；以字段类型 Schema 返回的配置为准 |
 | `code_block` | **`config.codeBlockBinding`**：`inputs`、`code`、**`outputs[]` + `targetField`**；配置 outputs 时，代码必须显式写 **`qf_output = {...}`**，仅 `return {...}` 不会产生可回写结果，且每个 `outputs[].path` 必须从 `qf_output` 取值 | 以字段类型 Schema 返回的 camelCase 配置为准 |
 
+部门字段的 `defaultDepartments` 也遵循同一约束：`custom` 模式必须包含至少一个部门。读取历史后端数据时，如果默认部门值存在但部门列表为空，AppForm 归一化会将其视为“未配置默认部门”并省略 `defaultDepartments`；不要在新声明中写 `departments: []`。
+
+读取历史数据时，空的应用/段落/字段标题会按稳定 ID 生成兼容名称，空行和空筛选组会被忽略；选择项、子表列、序列号组件、Q-Linker 输出和代码源码等语义必需值无法安全推断时，读取会返回结构化 `UNSUPPORTED_FIELD_CONFIG`，不会伪造声明值。`validate/apply` 对新声明仍保持严格 Schema 约束。
+
 别名：契约会把 `title`/`label` 映射到 **`name`** 等；字段类型自然别名见 §1.1。
 
 ### 2.1 `relation` 选择器形态

package/src/qingflow_mcp/builder_facade/app_form.py

@@ -31,6 +31,10 @@ from .service import (
 
 API_VERSION = "builder.qingflow.com/v1alpha1"
 QUE_TYPE_TO_CANONICAL = {
+    # Historical description-text controls are read as long_text for the
+    # public declaration shape; the compiler restores queType=1 from the
+    # existing backend template when writing them back.
+    1: "long_text",
     2: "text",
     3: "long_text",
     5: "member",
@@ -227,23 +231,33 @@ def _canonical_member_scope(scope: Any, scope_type: Any, *, department: bool = F
     }
     if department:
         result["departments"] = [
-            _without_none({"deptId": _positive_int(item.get("deptId") or item.get("id")), "deptName": item.get("deptName") or item.get("name")})
+            _without_none(
+                {
+                    "deptId": _positive_int(item.get("deptId") or item.get("id")),
+                    "deptName": _compat_label(item.get("deptName") or item.get("name"), "Department", item.get("deptId") or item.get("id")),
+                }
+            )
             for item in _scope_items(raw, "depart")
             if _positive_int(item.get("deptId") or item.get("id")) is not None
         ]
     else:
         result["members"] = [
-            _without_none({"uid": _positive_int(item.get("uid")), "nickName": item.get("nickName")})
+            _without_none({"uid": _positive_int(item.get("uid")), "nickName": _compat_label(item.get("nickName"), "Member", item.get("uid"))})
             for item in _scope_items(raw, "member")
             if _positive_int(item.get("uid")) is not None
         ]
         result["departments"] = [
-            _without_none({"deptId": _positive_int(item.get("deptId")), "deptName": item.get("deptName")})
+            _without_none(
+                {
+                    "deptId": _positive_int(item.get("deptId")),
+                    "deptName": _compat_label(item.get("deptName"), "Department", item.get("deptId")),
+                }
+            )
             for item in _scope_items(raw, "depart")
             if _positive_int(item.get("deptId")) is not None
         ]
         result["roles"] = [
-            _without_none({"roleId": _positive_int(item.get("roleId")), "roleName": item.get("roleName")})
+            _without_none({"roleId": _positive_int(item.get("roleId")), "roleName": _compat_label(item.get("roleName"), "Role", item.get("roleId"))})
             for item in _scope_items(raw, "role")
             if _positive_int(item.get("roleId")) is not None
         ]
@@ -281,11 +295,12 @@ def _canonical_scope_relation(relation: Any) -> JSONObject | None:
         return None
     displayed = relation.get("displayedQueInfo") if isinstance(relation.get("displayedQueInfo"), dict) else {}
     displayed_id = _positive_int(relation.get("displayedQueId") or displayed.get("queId"))
-    if displayed_id is None or not displayed.get("appKey"):
+    target_app_key = str(displayed.get("appKey") or "")
+    if displayed_id is None or not target_app_key.strip():
         return None
     result: JSONObject = {
         "displayedField": _selector(displayed_id, displayed.get("queTitle")),
-        "targetAppKey": displayed.get("appKey"),
+        "targetAppKey": target_app_key,
         "targetAppTitle": displayed.get("appTitle"),
         "displayedFieldType": displayed.get("queType"),
         "matchRuleType": relation.get("matchRuleType"),
@@ -334,6 +349,22 @@ def _selector(que_id: Any, name: Any) -> JSONObject:
     return result
 
 
+def _compat_label(value: Any, kind: str, identity: Any) -> str:
+    """Give legacy records with an empty display label a stable, non-empty name."""
+    label = str(value or "")
+    if label.strip():
+        return label
+    normalized_identity = str(identity or "").strip()
+    return f"{kind} {normalized_identity}" if normalized_identity else f"Unnamed {kind}"
+
+
+def _required_text(value: Any, *, message: str, details: JSONObject | None = None) -> str:
+    text = str(value or "")
+    if not text.strip():
+        raise AppFormFailure("UNSUPPORTED_FIELD_CONFIG", message, "NORMALIZE", details=details)
+    return text
+
+
 def _require_selector(que_id: Any, name: Any, *, message: str, details: JSONObject | None = None) -> JSONObject:
     result = _selector(que_id, name)
     if not result:
@@ -620,21 +651,40 @@ class AppFormNormalizer:
                 section_id = _positive_int(section.get("queId")) or _positive_int(section.get("sectionId"))
                 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, 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
-                ]
+                rows = []
+                for inner in section.get("innerQuestions") or []:
+                    if not isinstance(inner, list) or not inner:
+                        continue
+                    fields = [
+                        self._field(question, relations, select_scope_relations, field_names, supports_reference_default_formula)
+                        for question in inner
+                        if isinstance(question, dict)
+                    ]
+                    if fields:
+                        rows.append({"fields": fields})
                 if not rows:
                     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})
+                body.append(
+                    {
+                        "kind": "section",
+                        "sectionId": str(section_id),
+                        "title": _compat_label(section.get("queTitle"), "Section", section_id),
+                        "rows": rows,
+                    }
+                )
             else:
-                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)]})
+                fields = [
+                    self._field(question, relations, select_scope_relations, field_names, supports_reference_default_formula)
+                    for question in row
+                    if isinstance(question, dict)
+                ]
+                if fields:
+                    body.append({"kind": "row", "fields": fields})
         resource = {
             "apiVersion": context.api_version,
             "appKey": app_key,
             "spec": {
-                "appName": str(form.get("formTitle") or ""),
+                "appName": _compat_label(form.get("formTitle"), "App", app_key),
                 "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,
@@ -676,18 +726,27 @@ class AppFormNormalizer:
                 details={"queId": que_id, "queType": que_type},
             )
         field: JSONObject = {
-            "name": str(question.get("queTitle") or ""),
+            "name": _compat_label(question.get("queTitle"), "Field", que_id),
             "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 (
+        raw_default_value = question.get("queDefaultValue")
+        decoded_default_value = (
+            _decode_formula_default(raw_default_value)
+            if isinstance(raw_default_value, (str, int, float, bool))
+            else raw_default_value
+        )
+        empty_formula_default = default_type == 3 and (
+            decoded_default_value is None
+            or (isinstance(decoded_default_value, str) and not decoded_default_value.strip())
+        )
+        if default_type is not None and not empty_formula_default and (
             question.get("queDefaultValue") is not None
             or (default_type != 1 and field_type != "relation")
         ):
             field["defaultType"] = default_type
-        raw_default_value = question.get("queDefaultValue")
         if isinstance(raw_default_value, (dict, list)) and field_type not in {"address", "attachment", "relation", "subtable"}:
             raise AppFormFailure(
                 "UNSUPPORTED_FIELD_CONFIG",
@@ -695,9 +754,14 @@ class AppFormNormalizer:
                 "NORMALIZE",
                 details={"queId": que_id, "type": field_type},
             )
-        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 (
+            "queDefaultValue" in question
+            and raw_default_value is not None
+            and not isinstance(raw_default_value, (dict, list))
+            and not empty_formula_default
+            and not (default_type == 2 and isinstance(decoded_default_value, str) and not decoded_default_value.strip())
+        ):
+            field["defaultValue"] = decoded_default_value
         if que_id is not None:
             field["queId"] = que_id
         width = _positive_int(question.get("queWidth"))
@@ -735,9 +799,20 @@ class AppFormNormalizer:
             if config:
                 field["config"] = config
         elif field_type in CHOICE_TYPES:
-            options = [str(item.get("optValue")) for item in question.get("options") or [] if isinstance(item, dict) and item.get("optValue") is not None]
+            options = [
+                str(item.get("optValue"))
+                for item in question.get("options") or []
+                if isinstance(item, dict) and item.get("optValue") is not None and str(item.get("optValue")).strip()
+            ]
             if not options and field_type == "single_choice":
                 options = ["是", "否"]
+            if not options:
+                raise AppFormFailure(
+                    "UNSUPPORTED_FIELD_CONFIG",
+                    "choice field has no options",
+                    "NORMALIZE",
+                    details={"queId": que_id, "type": field_type, "path": "/config/options"},
+                )
             field["config"] = _without_none({
                 "options": options,
                 "minOpts": _canonical_unlimited(question.get("minOpts")),
@@ -745,7 +820,14 @@ class AppFormNormalizer:
                 "optDirection": question.get("optDirection") if question.get("optDirection") not in {None, 0} else None,
                 "optSelectMode": question.get("optSelectMode"),
                 "beingShowColor": question.get("beingShowColor"),
-                "defaultOptions": [str(item.get("optValue")) for item in question.get("options") or [] if isinstance(item, dict) and item.get("beingDefault") is True],
+                "defaultOptions": [
+                    str(item.get("optValue"))
+                    for item in question.get("options") or []
+                    if isinstance(item, dict)
+                    and item.get("beingDefault") is True
+                    and item.get("optValue") is not None
+                    and str(item.get("optValue")).strip()
+                ],
             })
             if not field["config"].get("defaultOptions"):
                 field["config"].pop("defaultOptions", None)
@@ -766,7 +848,12 @@ class AppFormNormalizer:
             scope = question.get("deptSelectScope") if isinstance(question.get("deptSelectScope"), dict) else {}
             departments = scope.get("depart") if isinstance(scope.get("depart"), list) else []
             canonical_departments = [
-                _without_none({"deptId": _positive_int(item.get("deptId") or item.get("id")), "deptName": item.get("deptName") or item.get("name")})
+                _without_none(
+                    {
+                        "deptId": _positive_int(item.get("deptId") or item.get("id")),
+                        "deptName": _compat_label(item.get("deptName") or item.get("name"), "Department", item.get("deptId") or item.get("id")),
+                    }
+                )
                 for item in departments
                 if isinstance(item, dict) and _positive_int(item.get("deptId") or item.get("id")) is not None
             ]
@@ -791,7 +878,10 @@ class AppFormNormalizer:
             else:
                 field["config"] = {"departmentScope": {"mode": "all", "includeSubDeparts": bool(scope.get("includeSubDeparts"))}}
             if question.get("deptDftValue") is not None:
-                field["config"]["defaultDepartments"] = _canonical_member_scope(question.get("deptDftValue"), 2, department=True)
+                default_scope = _canonical_member_scope(question.get("deptDftValue"), 2, department=True)
+                # Older backend responses may include an empty default-value container when no default department is set.
+                if default_scope.get("departments"):
+                    field["config"]["defaultDepartments"] = default_scope
             relation = next((item for item in select_scope_relations if _positive_int(item.get("queId")) == que_id), None)
             scope_relation = _canonical_scope_relation(relation)
             if scope_relation is not None:
@@ -800,9 +890,14 @@ class AppFormNormalizer:
                 if question.get(key) is not None:
                     field["config"][key] = question[key]
         elif field_type == "attachment":
+            file_types = question.get("fileType")
+            if isinstance(file_types, list):
+                file_types = [item for item in file_types if str(item or "").strip()]
+            elif isinstance(file_types, str) and not file_types.strip():
+                file_types = None
             field["config"] = _without_none({
                 "fileSize": question.get("fileSize"),
-                "fileType": question.get("fileType"),
+                "fileType": file_types,
                 "fileBeingCaptureOnly": question.get("fileBeingCaptureOnly"),
                 "imageCompress": question.get("imageCompress"),
                 "pluginStatus": question.get("pluginStatus"),
@@ -826,14 +921,22 @@ 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]
+            target_app_key = str(reference.get("referAppKey") or "")
+            if not target_app_key.strip():
+                raise AppFormFailure(
+                    "UNSUPPORTED_FIELD_CONFIG",
+                    "relation target app cannot be normalized",
+                    "NORMALIZE",
+                    details={"queId": que_id, "path": "/config/targetAppKey"},
+                )
             relation_config: JSONObject = {
-                "targetAppKey": reference.get("referAppKey"),
+                "targetAppKey": target_app_key,
                 "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},
+                    details={"queId": que_id, "path": "/config/displayField"},
                 ),
                 "visibleFields": [
                     _require_selector(
@@ -849,7 +952,8 @@ class AppFormNormalizer:
                 "defaultValues": question.get("queDefaultValues") if isinstance(question.get("queDefaultValues"), dict) else None,
             }
             if supports_reference_default_formula:
-                relation_config["defaultValueFormula"] = reference.get("defaultValueFormula")
+                formula = reference.get("defaultValueFormula")
+                relation_config["defaultValueFormula"] = formula if not isinstance(formula, str) or formula.strip() else None
             field["config"] = _without_none(relation_config)
         elif field_type == "q_linker":
             field["config"] = {"qLinkerBinding": self._q_linker_binding(question, relations, field_names)}
@@ -858,34 +962,54 @@ class AppFormNormalizer:
         elif field_type == "data_relation":
             field["config"] = self._data_relation_config(question, relations)
         elif field_type == "subtable":
-            field["subfields"] = [
+            subfields = [
                 self._field(item, relations, select_scope_relations, field_names, supports_reference_default_formula)
                 for item in question.get("subQuestions") or []
                 if isinstance(item, dict)
             ]
+            if not subfields:
+                raise AppFormFailure(
+                    "UNSUPPORTED_FIELD_CONFIG",
+                    "subtable has no subfields",
+                    "NORMALIZE",
+                    details={"queId": que_id, "path": "/subfields"},
+                )
+            field["subfields"] = subfields
             for subfield in field["subfields"]:
                 subfield.pop("width", None)
+            row_height = question.get("tableRowHeight")
+            if isinstance(row_height, str) and not row_height.strip():
+                row_height = None
             field["config"] = _without_none({
                 "tableRowsLimit": question.get("tableRowsLimit"),
                 "tableNoRepeatStatus": question.get("tableNoRepeatStatus"),
                 "tableNoRepeatQuestion": [_selector(item, field_names.get(_positive_int(item))) for item in question.get("tableNoRepeatQuestion") or [] if _positive_int(item) is not None],
-                "tableRowHeight": question.get("tableRowHeight"),
+                "tableRowHeight": row_height,
                 "defaultValues": question.get("queDefaultValues") if isinstance(question.get("queDefaultValues"), dict) and (question.get("queDefaultValues", {}).get("values") or question.get("queDefaultValues", {}).get("tableValues")) else None,
             })
         return field
 
     @staticmethod
     def _attachments(value: Any) -> list[JSONObject]:
+        def attachment_text(item: JSONObject, *keys: str) -> Any:
+            for key in keys:
+                candidate = item.get(key)
+                if candidate:
+                    return candidate
+            return None
+
         result = [
             _without_none(
                 {
                     "attachId": _positive_int(item.get("attachId") or item.get("id")),
-                    "fileName": item.get("fileName") or item.get("name"),
-                    "fileUrl": item.get("fileUrl") or item.get("url"),
+                    "fileName": attachment_text(item, "fileName", "name"),
+                    "fileUrl": attachment_text(item, "fileUrl", "url"),
                 }
             )
             for item in value or []
-            if isinstance(item, dict) and (item.get("fileName") or item.get("name")) and (item.get("fileUrl") or item.get("url"))
+            if isinstance(item, dict)
+            and str(attachment_text(item, "fileName", "name") or "").strip()
+            and str(attachment_text(item, "fileUrl", "url") or "").strip()
         ]
         return sorted(result, key=lambda item: (item.get("attachId", 0), item["fileName"], item["fileUrl"]))
 
@@ -907,12 +1031,28 @@ class AppFormNormalizer:
             elif kind == "submit_datetime":
                 component["dateFormat"] = date_names.get(item.get("dateFormat"), "year_month_day")
             elif kind == "fixed_text":
-                component["value"] = str(item.get("customTitle") or "")
+                component["value"] = _required_text(
+                    item.get("customTitle"),
+                    message="custom serial number fixed text is empty",
+                    details={"componentId": _positive_int(item.get("id")), "path": "/spec/serialNumber/components/value"},
+                )
             else:
-                component["field"] = _selector(item.get("queId"), item.get("queTitle"))
+                component["field"] = _require_selector(
+                    item.get("queId"),
+                    item.get("queTitle"),
+                    message="custom serial number field cannot be normalized",
+                    details={"componentId": _positive_int(item.get("id")), "path": "/spec/serialNumber/components/field"},
+                )
                 if item.get("dateFormat") is not None:
                     component["dateFormat"] = date_names.get(item.get("dateFormat"), "year_month_day")
             components.append(component)
+        if not components:
+            raise AppFormFailure(
+                "UNSUPPORTED_FIELD_CONFIG",
+                "custom serial number has no components",
+                "NORMALIZE",
+                details={"path": "/spec/serialNumber/components"},
+            )
         return {"mode": "custom", "components": components}
 
     @staticmethod
@@ -926,9 +1066,11 @@ class AppFormNormalizer:
                     for inner in item.get("innerQuestions") or []:
                         for nested in inner if isinstance(inner, list) else []:
                             if isinstance(nested, dict) and _positive_int(nested.get("queId")):
-                                result[_positive_int(nested.get("queId")) or 0] = str(nested.get("queTitle") or "")
+                                nested_id = _positive_int(nested.get("queId")) or 0
+                                result[nested_id] = _compat_label(nested.get("queTitle"), "Field", nested_id)
                 elif _positive_int(item.get("queId")):
-                    result[_positive_int(item.get("queId")) or 0] = str(item.get("queTitle") or "")
+                    item_id = _positive_int(item.get("queId")) or 0
+                    result[item_id] = _compat_label(item.get("queTitle"), "Field", item_id)
         return result
 
     @staticmethod
@@ -939,7 +1081,16 @@ class AppFormNormalizer:
         for alias in config.get("resultFormatPath") or []:
             if not isinstance(alias, dict):
                 continue
-            name = str(alias.get("aliasName") or "")
+            name = _required_text(
+                alias.get("aliasName"),
+                message="Q-Linker output alias is empty",
+                details={"queId": source_id, "path": "/config/qLinkerBinding/outputs/alias"},
+            )
+            path = _required_text(
+                alias.get("aliasPath"),
+                message="Q-Linker output path is empty",
+                details={"queId": source_id, "alias": name, "path": "/config/qLinkerBinding/outputs/path"},
+            )
             relation = next(
                 (
                     item
@@ -953,7 +1104,7 @@ class AppFormNormalizer:
                 _without_none(
                     {
                         "alias": name,
-                        "path": str(alias.get("aliasPath") or ""),
+                        "path": path,
                         "aliasId": _positive_int(alias.get("aliasId")) or _positive_int((relation.get("aliasConfig") or {}).get("aliasId")),
                         "targetField": _require_selector(
                             relation.get("queId"),
@@ -973,15 +1124,30 @@ class AppFormNormalizer:
                     continue
                 if _positive_int(item.get("type")) == 2:
                     input_que_id = _positive_int(item.get("value"))
+                    input_key = _required_text(
+                        item.get("key"),
+                        message="Q-Linker input key is empty",
+                        details={"queId": source_id, "source": source, "path": "/config/qLinkerBinding/inputs/key"},
+                    )
                     inputs.append(
                         {
-                            "field": _selector(input_que_id, field_names.get(input_que_id or -1)),
-                            "key": str(item.get("key") or ""),
+                            "field": _require_selector(
+                                input_que_id,
+                                field_names.get(input_que_id or -1),
+                                message="Q-Linker input field cannot be normalized",
+                                details={"queId": source_id, "key": input_key},
+                            ),
+                            "key": input_key,
                             "source": source,
                         }
                     )
                 else:
-                    static[key].append({"key": str(item.get("key") or ""), "value": item.get("value")})
+                    static_key = _required_text(
+                        item.get("key"),
+                        message="Q-Linker request key is empty",
+                        details={"queId": source_id, "source": source, "path": f"/config/qLinkerBinding/request/{source}/key"},
+                    )
+                    static[key].append({"key": static_key, "value": item.get("value")})
         request_values = {
             "url": config.get("url"),
             "jsonValue": config.get("jsonValue"),
@@ -1013,9 +1179,14 @@ class AppFormNormalizer:
 
             request_values[request_key] = Q_LINKER_VALUE_REFERENCE_RE.sub(replace_reference, raw_value)
         inputs.extend(json_path_inputs.values())
+        request_url = _required_text(
+            request_values["url"],
+            message="Q-Linker request URL is empty",
+            details={"queId": source_id, "path": "/config/qLinkerBinding/request/url"},
+        )
         request = _without_none(
             {
-                "url": request_values["url"],
+                "url": request_url,
                 "method": config.get("method") or "GET",
                 **static,
                 "bodyType": {1: "url_encoded", 2: "json", 3: "xml"}.get(_positive_int(config.get("bodyType")) or 1, "url_encoded"),
@@ -1029,6 +1200,13 @@ class AppFormNormalizer:
                 "hideOnForm": bool(config.get("beingHideOnForm")),
             }
         )
+        if not outputs:
+            raise AppFormFailure(
+                "UNSUPPORTED_FIELD_CONFIG",
+                "Q-Linker has no output mapping",
+                "NORMALIZE",
+                details={"queId": source_id, "path": "/config/qLinkerBinding/outputs"},
+            )
         return {"inputs": inputs, "request": request, "outputs": outputs}
 
     @staticmethod
@@ -1039,7 +1217,16 @@ class AppFormNormalizer:
         for alias in config.get("resultAliasPath") or []:
             if not isinstance(alias, dict):
                 continue
-            name = str(alias.get("aliasName") or "")
+            name = _required_text(
+                alias.get("aliasName"),
+                message="code block output alias is empty",
+                details={"queId": source_id, "path": "/config/codeBlockBinding/outputs/alias"},
+            )
+            path = _required_text(
+                alias.get("aliasPath"),
+                message="code block output path is empty",
+                details={"queId": source_id, "alias": name, "path": "/config/codeBlockBinding/outputs/path"},
+            )
             relation = next(
                 (
                     item
@@ -1051,7 +1238,7 @@ class AppFormNormalizer:
             )
             output = {
                 "alias": name,
-                "path": str(alias.get("aliasPath") or ""),
+                "path": path,
                 "targetField": _require_selector(
                     relation.get("queId"),
                     relation.get("queTitle") or field_names.get(_positive_int(relation.get("queId")) or -1),
@@ -1069,11 +1256,29 @@ class AppFormNormalizer:
             line = lines.pop(0).strip()
             var = line[6:].split("=", 1)[0].strip()
             name = line.split("qf_field.{", 1)[1].split("$$", 1)[0]
-            inputs.append({"field": {"name": name}, "var": var})
+            input_name = _required_text(
+                name,
+                message="code block input field is empty",
+                details={"queId": source_id, "path": "/config/codeBlockBinding/inputs/field"},
+            )
+            inputs.append(
+                {
+                    "field": {"name": input_name},
+                    "var": var,
+                }
+            )
+        code = "\n".join(lines).lstrip("\n")
+        if not code.strip():
+            raise AppFormFailure(
+                "UNSUPPORTED_FIELD_CONFIG",
+                "code block has no code",
+                "NORMALIZE",
+                details={"queId": source_id, "path": "/config/codeBlockBinding/code"},
+            )
         return _without_none(
             {
                 "inputs": inputs,
-                "code": "\n".join(lines).lstrip("\n"),
+                "code": code,
                 "autoTrigger": question.get("autoTrigger"),
                 "customButtonTextEnabled": question.get("customBtnTextStatus"),
                 "customButtonText": question.get("customBtnText"),
@@ -1092,7 +1297,8 @@ class AppFormNormalizer:
         displayed = relation.get("displayedQueInfo") if isinstance(relation.get("displayedQueInfo"), dict) else {}
         alias = relation.get("aliasConfig") if isinstance(relation.get("aliasConfig"), dict) else {}
         if relation_type == 1:
-            if not str(displayed.get("appKey") or "").strip():
+            source_app_key = str(displayed.get("appKey") or "")
+            if not source_app_key.strip():
                 raise AppFormFailure(
                     "UNSUPPORTED_FIELD_CONFIG",
                     "data_relation source app cannot be normalized",
@@ -1101,7 +1307,7 @@ class AppFormNormalizer:
                 )
             source = {
                 "kind": "app",
-                "appKey": displayed.get("appKey"),
+                "appKey": source_app_key,
                 "field": _require_selector(
                     relation.get("displayedQueId"),
                     displayed.get("queTitle"),
@@ -1143,7 +1349,9 @@ class AppFormNormalizer:
             for group in relation.get("matchRules") or []:
                 if not isinstance(group, list):
                     raise AppFormFailure("UNSUPPORTED_FIELD_CONFIG", "data_relation match rules are malformed", "NORMALIZE", details={"queId": que_id})
-                groups.append([AppFormNormalizer._data_relation_condition(item, que_id=que_id) for item in group if isinstance(item, dict)])
+                conditions = [AppFormNormalizer._data_relation_condition(item, que_id=que_id) for item in group if isinstance(item, dict)]
+                if conditions:
+                    groups.append(conditions)
             result["filters"] = {"mode": "simple", "groups": groups}
         sort = relation.get("sortConfig") if isinstance(relation.get("sortConfig"), dict) else None
         if sort is not None:
@@ -2173,6 +2381,11 @@ class AppFormCompiler:
                 "queHint": field.get("questionDescription") or "",
             }
         )
+        if _positive_int((template or {}).get("queType")) == 1 and field_type == "long_text":
+            # queType=1 is a non-data description control. Keep its backend
+            # type and template-only settings while allowing the declaration
+            # to carry its stable identity and default content.
+            question["queType"] = 1
         config = field.get("config") if isinstance(field.get("config"), dict) else {}
         if field_type in {"text", "long_text", "link", "phone", "email"}:
             for key in ("minWordCount", "maxWordCount", "noRepeat", "canScan", "scanType"):