@josephyan/qingflow-app-builder-mcp 0.2.0-beta.49 → 0.2.0-beta.50

package/src/qingflow_mcp/tools/record_tools.py

@@ -85,11 +85,20 @@ class FormField:
     raw: JSONObject
 
 
+@dataclass(slots=True)
+class SubtableLeafRef:
+    field: FormField
+    parent_field: FormField
+
+
 @dataclass(slots=True)
 class FieldIndex:
     by_id: dict[str, FormField]
     by_title: dict[str, list[FormField]]
     by_alias: dict[str, list[FormField]]
+    subtable_leaf_by_id: dict[str, list[SubtableLeafRef]]
+    subtable_leaf_by_title: dict[str, list[SubtableLeafRef]]
+    subtable_leaf_by_alias: dict[str, list[SubtableLeafRef]]
 
 
 @dataclass(slots=True)
@@ -351,6 +360,7 @@ class RecordTools(ToolBase):
             description=(
                 "Write Qingflow records with a SQL-like JSON DSL. "
                 "Use record_schema_get first, then choose operation=insert|update|delete. "
+                "Insert follows applicant-node write scope; update requires an explicit view selector and is constrained by that view plus real edit permission. "
                 "This tool performs internal preflight validation before any write is applied. "
                 "This route does not accept raw SQL strings or free-form WHERE clauses."
             )
@@ -363,6 +373,10 @@ class RecordTools(ToolBase):
             record_ids: list[int] | None = None,
             values: list[JSONObject] | None = None,
             set: list[JSONObject] | None = None,
+            view_id: str | None = None,
+            list_type: int | None = None,
+            view_key: str | None = None,
+            view_name: str | None = None,
             submit_type: str | int = "submit",
             verify_write: bool = True,
             output_profile: str = "normal",
@@ -375,6 +389,10 @@ class RecordTools(ToolBase):
                 record_ids=record_ids or [],
                 values=values or [],
                 set=set or [],
+                view_id=view_id,
+                list_type=list_type,
+                view_key=view_key,
+                view_name=view_name,
                 submit_type=submit_type,
                 verify_write=verify_write,
                 output_profile=output_profile,
@@ -401,6 +419,7 @@ class RecordTools(ToolBase):
         def runner(session_profile, context):
             warnings: list[JSONObject] = []
             resolved_view: AccessibleViewRoute | None = None
+            browse_scope: JSONObject | None = None
             if normalized_schema_mode == "applicant":
                 if any(item is not None for item in (view_id, list_type, view_key, view_name)):
                     raise_tool_error(
@@ -430,11 +449,19 @@ class RecordTools(ToolBase):
                             ),
                         }
                     )
+                browse_scope = self._build_browse_write_scope(
+                    profile,
+                    context,
+                    app_key,
+                    resolved_view,
+                    force_refresh=False,
+                )
             index = (
-                self._get_field_index(profile, context, app_key, force_refresh=False)
+                self._get_applicant_top_level_field_index(profile, context, app_key, force_refresh=False)
                 if normalized_schema_mode == "applicant"
-                else self._get_browse_field_index(profile, context, app_key, resolved_view, force_refresh=False)
+                else cast(FieldIndex, browse_scope["index"])
             )
+            browse_writable_field_ids = cast(set[int], browse_scope["writable_field_ids"]) if isinstance(browse_scope, dict) else set()
             fields = [
                 self._schema_field_payload(
                     profile,
@@ -443,6 +470,7 @@ class RecordTools(ToolBase):
                     workflow_node_id=None,
                     ws_id=session_profile.selected_ws_id,
                     schema_mode=normalized_schema_mode,
+                    browse_writable=field.que_id in browse_writable_field_ids if normalized_schema_mode == "browse" else None,
                 )
                 for field in self._schema_fields_for_mode(
                     profile,
@@ -965,14 +993,18 @@ class RecordTools(ToolBase):
         *,
         profile: str,
         app_key: str,
-        operation: str,
-        record_id: int | None,
-        record_ids: list[int],
-        values: list[JSONObject],
-        set: list[JSONObject],
-        submit_type: str | int,
-        verify_write: bool,
-        output_profile: str,
+        operation: str = "insert",
+        record_id: int | None = None,
+        record_ids: list[int] | None = None,
+        values: list[JSONObject] | None = None,
+        set: list[JSONObject] | None = None,
+        view_id: str | None = None,
+        list_type: int | None = None,
+        view_key: str | None = None,
+        view_name: str | None = None,
+        submit_type: str | int = "submit",
+        verify_write: bool = True,
+        output_profile: str = "normal",
         mode: str | None = None,
     ) -> JSONObject:
         normalized_output_profile = self._normalize_public_output_profile(output_profile)
@@ -987,15 +1019,24 @@ class RecordTools(ToolBase):
             )
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
-        normalized_record_ids = [item for item in record_ids if isinstance(item, int) and item > 0]
+        normalized_values = list(values or [])
+        normalized_set = list(set or [])
+        normalized_record_ids = [item for item in (record_ids or []) if isinstance(item, int) and item > 0]
         submit_type_value = self._normalize_record_write_submit_type(submit_type)
+        uses_view_scope = any(item is not None for item in (view_id, list_type, view_key, view_name))
 
         if normalized_operation == "insert":
+            if uses_view_scope:
+                raise_tool_error(
+                    QingflowApiError.config_error(
+                        "insert strictly follows applicant-node write scope and does not accept view selectors; use record_schema_get(schema_mode='applicant') first"
+                    )
+                )
             if record_id is not None or normalized_record_ids:
                 raise_tool_error(QingflowApiError.config_error("insert must not include record_id or record_ids"))
-            if set:
+            if normalized_set:
                 raise_tool_error(QingflowApiError.config_error("insert must use values, not set"))
-            normalized_answers = self._normalize_record_write_clauses(values, location="values")
+            normalized_answers = self._normalize_record_write_clauses(normalized_values, location="values")
             raw_preflight = self._preflight_record_write(
                 profile=profile,
                 operation="create",
@@ -1004,6 +1045,10 @@ class RecordTools(ToolBase):
                 answers=normalized_answers,
                 fields={},
                 force_refresh_form=False,
+                view_id=view_id,
+                list_type=list_type,
+                view_key=view_key,
+                view_name=view_name,
             )
             preflight_data = cast(JSONObject, raw_preflight.get("data", {}))
             normalized_payload: JSONObject = self._record_write_normalized_payload(
@@ -1012,6 +1057,7 @@ class RecordTools(ToolBase):
                 record_ids=[],
                 normalized_answers=cast(list[JSONObject], preflight_data.get("normalized_answers", [])),
                 submit_type=submit_type_value,
+                selection=cast(JSONObject | None, preflight_data.get("selection") if isinstance(preflight_data.get("selection"), dict) else None),
             )
             if preflight_data.get("blockers"):
                 return self._record_write_blocked_response(
@@ -1022,15 +1068,25 @@ class RecordTools(ToolBase):
                     human_review=False,
                     target_resource={"type": "record", "app_key": app_key, "record_id": None, "record_ids": []},
                 )
-            raw_apply = self.record_create(
-                profile=profile,
-                app_key=app_key,
-                answers=cast(list[JSONObject], preflight_data.get("normalized_answers", [])),
-                fields={},
-                submit_type=submit_type_value,
-                verify_write=verify_write,
-                force_refresh_form=False,
-            )
+            try:
+                raw_apply = self.record_create(
+                    profile=profile,
+                    app_key=app_key,
+                    answers=cast(list[JSONObject], preflight_data.get("normalized_answers", [])),
+                    fields={},
+                    submit_type=submit_type_value,
+                    verify_write=verify_write,
+                    force_refresh_form=False,
+                )
+            except QingflowApiError as exc:
+                self._raise_record_write_permission_error(
+                    exc,
+                    operation="insert",
+                    app_key=app_key,
+                    record_id=None,
+                    selection=cast(JSONObject | None, preflight_data.get("selection") if isinstance(preflight_data.get("selection"), dict) else None),
+                )
+                raise
             return self._record_write_apply_response(
                 raw_apply,
                 operation="insert",
@@ -1041,13 +1097,19 @@ class RecordTools(ToolBase):
             )
 
         if normalized_operation == "update":
+            if not uses_view_scope:
+                raise_tool_error(
+                    QingflowApiError.config_error(
+                        "update requires view_id/view_key/view_name/list_type; call app_get first to inspect accessible_views and choose a write scope"
+                    )
+                )
             if record_id is None or record_id <= 0:
                 raise_tool_error(QingflowApiError.config_error("update requires record_id"))
             if normalized_record_ids:
                 raise_tool_error(QingflowApiError.config_error("update does not support record_ids"))
-            if values:
+            if normalized_values:
                 raise_tool_error(QingflowApiError.config_error("update must use set, not values"))
-            normalized_answers = self._normalize_record_write_clauses(set, location="set")
+            normalized_answers = self._normalize_record_write_clauses(normalized_set, location="set")
             raw_preflight = self._preflight_record_write(
                 profile=profile,
                 operation="update",
@@ -1056,6 +1118,10 @@ class RecordTools(ToolBase):
                 answers=normalized_answers,
                 fields={},
                 force_refresh_form=False,
+                view_id=view_id,
+                list_type=list_type,
+                view_key=view_key,
+                view_name=view_name,
             )
             preflight_data = cast(JSONObject, raw_preflight.get("data", {}))
             normalized_payload = self._record_write_normalized_payload(
@@ -1064,6 +1130,7 @@ class RecordTools(ToolBase):
                 record_ids=[],
                 normalized_answers=cast(list[JSONObject], preflight_data.get("normalized_answers", [])),
                 submit_type=submit_type_value,
+                selection=cast(JSONObject | None, preflight_data.get("selection") if isinstance(preflight_data.get("selection"), dict) else None),
             )
             if preflight_data.get("blockers"):
                 return self._record_write_blocked_response(
@@ -1074,16 +1141,26 @@ class RecordTools(ToolBase):
                     human_review=True,
                     target_resource={"type": "record", "app_key": app_key, "record_id": record_id, "record_ids": []},
                 )
-            raw_apply = self.record_update(
-                profile=profile,
-                app_key=app_key,
-                apply_id=record_id,
-                answers=cast(list[JSONObject], preflight_data.get("normalized_answers", [])),
-                fields={},
-                role=1,
-                verify_write=verify_write,
-                force_refresh_form=False,
-            )
+            try:
+                raw_apply = self.record_update(
+                    profile=profile,
+                    app_key=app_key,
+                    apply_id=record_id,
+                    answers=cast(list[JSONObject], preflight_data.get("normalized_answers", [])),
+                    fields={},
+                    role=1,
+                    verify_write=verify_write,
+                    force_refresh_form=False,
+                )
+            except QingflowApiError as exc:
+                self._raise_record_write_permission_error(
+                    exc,
+                    operation="update",
+                    app_key=app_key,
+                    record_id=record_id,
+                    selection=cast(JSONObject | None, preflight_data.get("selection") if isinstance(preflight_data.get("selection"), dict) else None),
+                )
+                raise
             return self._record_write_apply_response(
                 raw_apply,
                 operation="update",
@@ -1093,7 +1170,13 @@ class RecordTools(ToolBase):
                 preflight=raw_preflight,
             )
 
-        if values or set:
+        if uses_view_scope:
+            raise_tool_error(
+                QingflowApiError.config_error(
+                    "delete does not accept view selectors yet; resolve target record_ids from the selected view first, then call delete by record_id/record_ids"
+                )
+            )
+        if normalized_values or normalized_set:
             raise_tool_error(QingflowApiError.config_error("delete must not include values or set"))
         delete_ids = normalized_record_ids or ([record_id] if record_id is not None and record_id > 0 else [])
         if not delete_ids:
@@ -1124,10 +1207,15 @@ class RecordTools(ToolBase):
         workflow_node_id: int | None,
         ws_id: int | None,
         schema_mode: str = "applicant",
+        browse_writable: bool | None = None,
     ) -> JSONObject:  # type: ignore[no-untyped-def]
         write_hints = self._schema_write_hints(field)
-        writable = write_hints["writable"] if schema_mode == "applicant" else False
-        supported_write_ops = write_hints["supported_write_ops"] if schema_mode == "applicant" else []
+        if schema_mode == "applicant":
+            writable = write_hints["writable"]
+            supported_write_ops = write_hints["supported_write_ops"]
+        else:
+            writable = bool(browse_writable)
+            supported_write_ops = ["update"] if writable else []
         payload = {
             "field_id": field.que_id,
             "title": field.que_title,
@@ -2426,10 +2514,27 @@ class RecordTools(ToolBase):
         answers: list[JSONObject] | None = None,
         fields: JSONObject | None = None,
         force_refresh_form: bool = False,
+        view_id: str | None = None,
+        list_type: int | None = None,
+        view_key: str | None = None,
+        view_name: str | None = None,
     ) -> JSONObject:
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
         inferred_operation = operation if operation in {"create", "update"} else ("update" if apply_id else "create")
+        uses_view_scope = any(item is not None for item in (view_id, list_type, view_key, view_name))
+        if inferred_operation == "create" and uses_view_scope:
+            raise_tool_error(
+                QingflowApiError.config_error(
+                    "insert/create strictly follows applicant-node write scope and does not accept view selectors; use record_schema_get(schema_mode='applicant') first"
+                )
+            )
+        if inferred_operation == "update" and not uses_view_scope:
+            raise_tool_error(
+                QingflowApiError.config_error(
+                    "update requires view_id/view_key/view_name/list_type; call app_get first to inspect accessible_views and choose a write scope"
+                )
+            )
 
         return self._preflight_record_write(
             profile=profile,
@@ -2439,6 +2544,10 @@ class RecordTools(ToolBase):
             answers=answers or [],
             fields=fields or {},
             force_refresh_form=force_refresh_form,
+            view_id=view_id,
+            list_type=list_type,
+            view_key=view_key,
+            view_name=view_name,
         )
 
     def _preflight_record_write(
@@ -2451,6 +2560,10 @@ class RecordTools(ToolBase):
         answers: list[JSONObject],
         fields: JSONObject,
         force_refresh_form: bool,
+        view_id: str | None,
+        list_type: int | None,
+        view_key: str | None,
+        view_name: str | None,
     ) -> JSONObject:
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
@@ -2465,6 +2578,10 @@ class RecordTools(ToolBase):
                 answers=answers,
                 fields=fields,
                 force_refresh_form=force_refresh_form,
+                view_id=view_id,
+                list_type=list_type,
+                view_key=view_key,
+                view_name=view_name,
             )
             return {
                 "profile": profile,
@@ -2487,25 +2604,75 @@ class RecordTools(ToolBase):
         answers: list[JSONObject],
         fields: JSONObject,
         force_refresh_form: bool,
+        view_id: str | None,
+        list_type: int | None,
+        view_key: str | None,
+        view_name: str | None,
     ) -> JSONObject:
         schema = self._get_form_schema(profile, context, app_key, force_refresh=force_refresh_form)
-        index = _build_field_index(schema)
+        index = _build_applicant_top_level_field_index(schema)
         normalized_fields = fields or {}
         normalized_answers_input = answers or []
-        resolved_fields = self._collect_write_plan_field_refs(fields=normalized_fields, answers=normalized_answers_input, index=index)
+        resolved_view: AccessibleViewRoute | None = None
+        selector_index = index
+        browse_writable_field_ids: set[int] = set()
+        visible_question_ids: set[int] = set()
+        if any(item is not None for item in (view_id, list_type, view_key, view_name)):
+            resolved_view, compatibility_warnings = self._resolve_accessible_view_route(
+                profile,
+                context,
+                app_key,
+                view_id=view_id,
+                list_type=list_type,
+                view_key=view_key,
+                view_name=view_name,
+                allow_default=False,
+            )
+            browse_scope = self._build_browse_write_scope(
+                profile,
+                context,
+                app_key,
+                resolved_view,
+                force_refresh=force_refresh_form,
+            )
+            selector_index = cast(FieldIndex, browse_scope["index"])
+            browse_writable_field_ids = cast(set[int], browse_scope["writable_field_ids"])
+            visible_question_ids = cast(set[int], browse_scope["visible_question_ids"])
+        else:
+            compatibility_warnings = []
+        resolved_fields = self._collect_write_plan_field_refs(fields=normalized_fields, answers=normalized_answers_input, index=selector_index)
         support_matrix = _summarize_write_support(resolved_fields)
         invalid_fields: list[JSONObject] = []
         normalized_answers: list[JSONObject] = []
         validation_warnings = [
             "record_write performs static preflight from form metadata before apply; runtime visibility and dynamic linkage can still reject writes."
         ]
+        if resolved_view is not None:
+            validation_warnings.append(
+                "view-scoped writes only narrow selectable fields; they do not grant record edit permission."
+            )
+        validation_warnings.extend(
+            str(item.get("message"))
+            for item in compatibility_warnings
+            if isinstance(item, dict) and item.get("message")
+        )
+        validation_warnings.extend(
+            str(item.get("message"))
+            for item in _view_filter_trust_warnings(resolved_view)
+            if isinstance(item, dict) and item.get("message")
+        )
         try:
+            scoped_answers_input, scoped_fields = self._canonicalize_write_scope_selectors(
+                answers=normalized_answers_input,
+                fields=normalized_fields,
+                selector_index=selector_index,
+            )
             normalized_answers = self._resolve_answers(
                 profile,
                 context,
                 app_key,
-                answers=normalized_answers_input,
-                fields=normalized_fields,
+                answers=scoped_answers_input,
+                fields=scoped_fields,
                 force_refresh_form=force_refresh_form,
             )
         except RecordInputError as error:
@@ -2538,10 +2705,35 @@ class RecordTools(ToolBase):
                 "system": entry.get("system"),
                 "source": entry.get("source"),
                 "requested": entry.get("requested"),
+                "reason_code": (
+                    "system"
+                    if bool(entry.get("system"))
+                    else "view_readonly"
+                    if resolved_view is not None
+                    else "readonly"
+                ),
             }
             for entry in resolved_fields
-            if bool(entry.get("resolved")) and (bool(entry.get("readonly")) or bool(entry.get("system")))
+            if bool(entry.get("resolved"))
+            and (
+                bool(entry.get("system"))
+                or (
+                    resolved_view is not None
+                    and _coerce_count(entry.get("que_id")) is not None
+                    and _coerce_count(entry.get("que_id")) not in browse_writable_field_ids
+                )
+                or (resolved_view is None and bool(entry.get("readonly")))
+            )
         ]
+        if resolved_view is not None and visible_question_ids:
+            invalid_fields.extend(
+                self._validate_view_scoped_subtable_answers(
+                    normalized_answers=normalized_answers,
+                    full_index=index,
+                    selector_index=selector_index,
+                    visible_question_ids=visible_question_ids,
+                )
+            )
         provided_field_ids = {
             str(answer.get("queId"))
             for answer in validation_answers
@@ -2606,7 +2798,11 @@ class RecordTools(ToolBase):
         if missing_required_fields:
             blockers.append("required fields are missing")
         if readonly_or_system_fields:
-            blockers.append("payload writes readonly or system-managed fields")
+            blockers.append(
+                "payload writes fields that are not writable in the selected view"
+                if resolved_view is not None
+                else "payload writes readonly or system-managed fields"
+            )
         actions = ["Use record_schema_get when field titles or field ids are ambiguous."]
         if support_matrix["restricted"]:
             actions.append("Review write_format.required_presteps for restricted fields before submit.")
@@ -2615,7 +2811,11 @@ class RecordTools(ToolBase):
         if missing_required_fields:
             actions.append("Fill missing required fields before applying the write.")
         if readonly_or_system_fields:
-            actions.append("Remove readonly/system fields from payload before applying the write.")
+            actions.append(
+                "Remove fields that the selected view does not allow for update, or choose a view that exposes those fields as writable."
+                if resolved_view is not None
+                else "Remove readonly/system fields from payload before applying the write."
+            )
         if question_relations:
             actions.append("Treat static preflight as conservative only because linked fields can still appear at runtime.")
         return {
@@ -2632,6 +2832,9 @@ class RecordTools(ToolBase):
                 "question_relations": question_relations,
                 "option_links": option_links,
             },
+            "selection": {
+                "view": _accessible_view_payload(resolved_view),
+            },
             "ready_to_submit": validation["valid"],
             "blockers": blockers,
             "recommended_next_actions": actions,
@@ -2653,6 +2856,49 @@ class RecordTools(ToolBase):
         answers = record.get("answers") if isinstance(record, dict) else None
         return [item for item in answers if isinstance(item, dict)] if isinstance(answers, list) else []
 
+    def _validate_view_scoped_subtable_answers(
+        self,
+        *,
+        normalized_answers: list[JSONObject],
+        full_index: FieldIndex,
+        selector_index: FieldIndex,
+        visible_question_ids: set[int],
+    ) -> list[JSONObject]:
+        invalid_fields: list[JSONObject] = []
+        if not visible_question_ids:
+            return invalid_fields
+        for answer in normalized_answers:
+            table_values = answer.get("tableValues") if isinstance(answer.get("tableValues"), list) else []
+            if not table_values:
+                continue
+            parent_que_id = _coerce_count(answer.get("queId"))
+            if parent_que_id is None:
+                continue
+            parent_field = full_index.by_id.get(str(parent_que_id)) or selector_index.by_id.get(str(parent_que_id))
+            if parent_field is None:
+                continue
+            subtable_index = self._subtable_field_index_optional(parent_field)
+            for row_ordinal, row in enumerate(table_values, start=1):
+                row_cells = [item for item in row if isinstance(item, dict)] if isinstance(row, list) else []
+                for cell in row_cells:
+                    que_id = _coerce_count(cell.get("queId"))
+                    if que_id is None or que_id in visible_question_ids:
+                        continue
+                    subfield = subtable_index.by_id.get(str(que_id)) if subtable_index is not None else None
+                    invalid_fields.append(
+                        {
+                            "location": f"{parent_field.que_title}[{row_ordinal}].{subfield.que_title if subfield is not None else que_id}",
+                            "message": (
+                                f"subtable field '{subfield.que_title if subfield is not None else que_id}' is not visible in the selected view"
+                            ),
+                            "error_code": "VIEW_SCOPE_FIELD_HIDDEN",
+                            "field": _field_ref_payload(subfield) if subfield is not None else {"que_id": que_id},
+                            "expected_format": _write_format_for_field(parent_field),
+                            "received_value": cell.get("values"),
+                        }
+                    )
+        return invalid_fields
+
     def _merge_record_answers(
         self,
         existing_answers: list[JSONObject],
@@ -3387,6 +3633,18 @@ class RecordTools(ToolBase):
     def _get_field_index(self, profile: str, context, app_key: str, *, force_refresh: bool) -> FieldIndex:  # type: ignore[no-untyped-def]
         return _build_field_index(self._get_form_schema(profile, context, app_key, force_refresh=force_refresh))
 
+    def _get_applicant_top_level_field_index(
+        self,
+        profile: str,
+        context,  # type: ignore[no-untyped-def]
+        app_key: str,
+        *,
+        force_refresh: bool,
+    ) -> FieldIndex:
+        return _build_applicant_top_level_field_index(
+            self._get_form_schema(profile, context, app_key, force_refresh=force_refresh)
+        )
+
     def _resolve_applicant_node(self, profile: str, context, app_key: str, *, force_refresh: bool) -> WorkflowNodeRef:  # type: ignore[no-untyped-def]
         cache_key = (profile, app_key)
         if not force_refresh and cache_key in self._applicant_node_cache:
@@ -3512,17 +3770,112 @@ class RecordTools(ToolBase):
         *,
         force_refresh: bool,
     ) -> FieldIndex:
+        return self._build_browse_write_scope(
+            profile,
+            context,
+            app_key,
+            resolved_view,
+            force_refresh=force_refresh,
+        )["index"]
+
+    def _build_browse_write_scope(
+        self,
+        profile: str,
+        context,  # type: ignore[no-untyped-def]
+        app_key: str,
+        resolved_view: AccessibleViewRoute | None,
+        *,
+        force_refresh: bool,
+    ) -> JSONObject:
+        applicant_index: FieldIndex | None
+        applicant_writable_field_ids: set[int]
+        try:
+            applicant_index = self._get_applicant_top_level_field_index(profile, context, app_key, force_refresh=force_refresh)
+        except QingflowApiError as exc:
+            if exc.backend_code != 40002:
+                raise
+            applicant_index = None
+            applicant_writable_field_ids = set()
+        else:
+            applicant_writable_field_ids = {
+                field.que_id
+                for field in applicant_index.by_id.values()
+                if bool(self._schema_write_hints(field)["writable"])
+            }
         if resolved_view is not None and resolved_view.kind == "custom" and resolved_view.view_selection is not None:
-            return self._get_view_field_index(profile, context, resolved_view.view_selection.view_key, force_refresh=force_refresh)
-        if resolved_view is not None and resolved_view.kind == "system" and resolved_view.list_type is not None:
-            return self._get_system_browse_field_index(
+            schema = self._get_view_form_schema(profile, context, resolved_view.view_selection.view_key, force_refresh=force_refresh)
+            index = _build_top_level_field_index(schema)
+            visible_question_ids = self._get_view_question_ids(profile, context, resolved_view.view_selection.view_key)
+            if not visible_question_ids:
+                visible_question_ids = _question_ids_from_schema(schema)
+        elif resolved_view is not None and resolved_view.kind == "system" and resolved_view.list_type is not None:
+            schema = self._get_system_browse_schema(
                 profile,
                 context,
                 app_key,
                 list_type=resolved_view.list_type,
                 force_refresh=force_refresh,
             )
-        return self._get_field_index(profile, context, app_key, force_refresh=force_refresh)
+            index = _build_top_level_field_index(schema)
+            visible_question_ids = _question_ids_from_schema(schema)
+        else:
+            index = applicant_index or _build_top_level_field_index(
+                self._get_form_schema(profile, context, app_key, force_refresh=force_refresh)
+            )
+            visible_question_ids = {field.que_id for field in index.by_id.values()}
+            return {
+                "index": index,
+                "writable_field_ids": (
+                    set(applicant_writable_field_ids)
+                    if applicant_index is not None
+                    else {
+                        field.que_id
+                        for field in index.by_id.values()
+                        if bool(self._schema_write_hints(field)["writable"])
+                    }
+                ),
+                "visible_question_ids": set(visible_question_ids),
+            }
+
+        if applicant_index is None:
+            return {
+                "index": index,
+                "writable_field_ids": {
+                    field.que_id
+                    for field in index.by_id.values()
+                    if bool(self._schema_write_hints(field)["writable"])
+                },
+                "visible_question_ids": visible_question_ids,
+            }
+
+        augmented_fields = [
+            _clone_form_field(applicant_index.by_id.get(str(field.que_id)) or field)
+            for field in index.by_id.values()
+        ]
+        augmented_field_ids = {field.que_id for field in augmented_fields}
+        writable_field_ids = {
+            field_id
+            for field_id in visible_question_ids
+            if field_id in applicant_writable_field_ids
+        }
+        for field in applicant_index.by_id.values():
+            descendant_ids = _subtable_descendant_ids(field)
+            field_visible = field.que_id in visible_question_ids
+            descendant_visible = bool(descendant_ids and (descendant_ids & visible_question_ids))
+            if not field_visible and not descendant_visible:
+                continue
+            if field.que_id not in augmented_field_ids:
+                augmented_fields.append(_clone_form_field(field))
+                augmented_field_ids.add(field.que_id)
+            if descendant_visible:
+                visible_question_ids.add(field.que_id)
+            if field.que_id in applicant_writable_field_ids and (field_visible or descendant_visible):
+                writable_field_ids.add(field.que_id)
+        return {
+            "index": _build_top_level_field_index({"formQues": [[_form_field_to_question(field) for field in augmented_fields]]}),
+            "writable_field_ids": writable_field_ids,
+            "visible_question_ids": visible_question_ids,
+        }
 
     def _get_view_question_ids(self, profile: str, context, view_key: str) -> set[int]:  # type: ignore[no-untyped-def]
         try:
@@ -3552,14 +3905,7 @@ class RecordTools(ToolBase):
         schema_mode: str,
         resolved_view: AccessibleViewRoute | None,
     ) -> list[FormField]:
-        fields = list(index.by_id.values())
-        if schema_mode != "browse" or resolved_view is None or resolved_view.kind != "custom" or resolved_view.view_selection is None:
-            return fields
-        question_ids = self._get_view_question_ids(profile, context, resolved_view.view_selection.view_key)
-        if not question_ids:
-            return fields
-        filtered = [field for field in fields if field.que_id in question_ids]
-        return filtered or fields
+        return list(index.by_id.values())
 
     def _probe_list_type_access(
         self,
@@ -4583,14 +4929,45 @@ class RecordTools(ToolBase):
         record_ids: list[int],
         normalized_answers: list[JSONObject],
         submit_type: int,
+        selection: JSONObject | None = None,
     ) -> JSONObject:
-        return {
+        payload: JSONObject = {
             "operation": operation,
             "record_id": record_id,
             "record_ids": record_ids,
             "answers": normalized_answers,
             "submit_type": submit_type,
         }
+        if selection:
+            payload["selection"] = selection
+        return payload
+
+    def _canonicalize_write_scope_selectors(
+        self,
+        *,
+        answers: list[JSONObject],
+        fields: JSONObject,
+        selector_index: FieldIndex,
+    ) -> tuple[list[JSONObject], JSONObject]:
+        canonical_answers: list[JSONObject] = []
+        for item in answers:
+            if not isinstance(item, dict):
+                raise RecordInputError(
+                    message="answer item must be an object",
+                    error_code="INVALID_ANSWER_ITEM",
+                    fix_hint="Provide each answer as an object with a field selector and value.",
+                )
+            field = self._resolve_field_from_answer_item(item, selector_index)
+            payload = dict(item)
+            payload["queId"] = field.que_id
+            for key in ("field_id", "fieldId", "que_id", "queTitle", "que_title"):
+                payload.pop(key, None)
+            canonical_answers.append(payload)
+        canonical_fields: JSONObject = {}
+        for requested_key, value in fields.items():
+            field = self._resolve_field_selector(cast(str | int, requested_key), selector_index, location="fields")
+            canonical_fields[str(field.que_id)] = value
+        return canonical_answers, canonical_fields
 
     def _record_write_human_review_payload(self, operation: str, *, enabled: bool) -> JSONObject | None:
         if not enabled:
@@ -4601,6 +4978,39 @@ class RecordTools(ToolBase):
             "message": "Read the current record first and confirm the exact target before applying this high-risk write.",
         }
 
+    def _raise_record_write_permission_error(
+        self,
+        exc: QingflowApiError,
+        *,
+        operation: str,
+        app_key: str,
+        record_id: int | None,
+        selection: JSONObject | None,
+    ) -> None:
+        if exc.backend_code != 40002:
+            raise exc
+        raise_tool_error(
+            QingflowApiError(
+                category="permission",
+                message="record_write was blocked because the current user does not have permission to edit this record.",
+                backend_code=exc.backend_code,
+                request_id=exc.request_id,
+                http_status=exc.http_status,
+                details={
+                    "error_code": "WRITE_PERMISSION_DENIED",
+                    "operation": operation,
+                    "app_key": app_key,
+                    "record_id": record_id,
+                    "selection": selection,
+                    "fix_hint": (
+                        "View visibility only narrows field scope and does not grant edit rights. "
+                        "If this is workflow work, prefer task_list -> task_get -> task_action_execute; "
+                        "otherwise ask an operator/admin account with record edit permission to perform the update."
+                    ),
+                },
+            )
+        )
+
     def _record_write_blocked_response(
         self,
         raw_preflight: JSONObject,
@@ -4734,10 +5144,20 @@ class RecordTools(ToolBase):
                 }
             )
         for item in readonly_or_system_fields:
+            reason_code = _normalize_optional_text(item.get("reason_code")) or "readonly"
+            if reason_code == "view_readonly":
+                error_code = "VIEW_FIELD_READONLY"
+                message = "field is not writable in the selected view"
+            elif reason_code == "system":
+                error_code = "READONLY_OR_SYSTEM_FIELD"
+                message = "field is system-managed"
+            else:
+                error_code = "READONLY_OR_SYSTEM_FIELD"
+                message = "field is readonly or system-managed"
             errors.append(
                 {
-                    "error_code": "READONLY_OR_SYSTEM_FIELD",
-                    "message": "field is readonly or system-managed",
+                    "error_code": error_code,
+                    "message": message,
                     "field": {
                         "que_id": item.get("que_id"),
                         "que_title": item.get("que_title"),
@@ -4796,6 +5216,9 @@ class RecordTools(ToolBase):
             field = index.by_id.get(str(int(requested)))
             if field is not None:
                 return field
+            leaf_matches = index.subtable_leaf_by_id.get(str(int(requested)), [])
+            if leaf_matches:
+                raise self._subtable_leaf_field_error(location=location, requested=requested, matches=leaf_matches, matched_via="id")
             raise RecordInputError(
                 message=f"{location} references unknown queId '{requested}'",
                 error_code="FIELD_NOT_FOUND",
@@ -4818,6 +5241,9 @@ class RecordTools(ToolBase):
                     "candidates": [_field_ref_payload(item) for item in matches],
                 },
             )
+        leaf_matches = index.subtable_leaf_by_title.get(requested_key, [])
+        if leaf_matches:
+            raise self._subtable_leaf_field_error(location=location, requested=requested, matches=leaf_matches, matched_via="title")
         alias_matches = index.by_alias.get(requested_key, [])
         if len(alias_matches) == 1:
             return alias_matches[0]
@@ -4834,6 +5260,9 @@ class RecordTools(ToolBase):
                     "candidates": [_field_ref_payload(item) for item in alias_matches],
                 },
             )
+        leaf_alias_matches = index.subtable_leaf_by_alias.get(requested_key, [])
+        if leaf_alias_matches:
+            raise self._subtable_leaf_field_error(location=location, requested=requested, matches=leaf_alias_matches, matched_via="alias")
         raise RecordInputError(
             message=f"{location} cannot resolve field '{requested}'",
             error_code="FIELD_NOT_FOUND",
@@ -4846,6 +5275,57 @@ class RecordTools(ToolBase):
             },
         )
 
+    def _subtable_leaf_field_error(
+        self,
+        *,
+        location: str,
+        requested: str,
+        matches: list[SubtableLeafRef],
+        matched_via: str,
+    ) -> RecordInputError:
+        if len(matches) > 1:
+            return RecordInputError(
+                message=f"{location} field '{requested}' matches subtable leaf fields under multiple parent tables",
+                error_code="AMBIGUOUS_SUBTABLE_LEAF_FIELD",
+                fix_hint="Use the parent subtable field with rows/tableValues, or inspect record_schema_get to choose the correct parent table.",
+                details={
+                    "location": location,
+                    "requested": requested,
+                    "matched_via": matched_via,
+                    "candidates": [
+                        {
+                            "parent_field": _field_ref_payload(item.parent_field),
+                            "subfield": _field_ref_payload(item.field),
+                        }
+                        for item in matches
+                    ],
+                },
+            )
+        match = matches[0]
+        return RecordInputError(
+            message=(
+                f"{location} field '{requested}' is a subtable leaf field and cannot be written at the top level; "
+                f"use parent field '{match.parent_field.que_title}' with rows/tableValues instead"
+            ),
+            error_code="SUBTABLE_LEAF_REQUIRES_PARENT_ROWS",
+            fix_hint=(
+                f"Write subtable leaf '{match.field.que_title}' under parent field '{match.parent_field.que_title}', "
+                "for example {'"
+                + match.parent_field.que_title
+                + "': [{'"
+                + match.field.que_title
+                + "': '值'}]}."
+            ),
+            details={
+                "location": location,
+                "requested": requested,
+                "matched_via": matched_via,
+                "field": _field_ref_payload(match.field),
+                "parent_field": _field_ref_payload(match.parent_field),
+                "expected_format": _write_format_for_field(match.parent_field),
+            },
+        )
+
     def _resolve_field_from_answer_item(self, item: JSONObject, index: FieldIndex) -> FormField:
         for key in ("queId", "que_id", "queTitle", "que_title", "field_id", "fieldId"):
             if key in item:
@@ -5862,47 +6342,208 @@ def _compile_view_conditions(config: JSONObject) -> list[list[ViewFilterConditio
     return compiled
 
 
-def _build_field_index(schema: JSONObject) -> FieldIndex:
+def _collect_top_level_questions(payload: JSONValue) -> list[JSONObject]:
+    questions: list[JSONObject] = []
+    if isinstance(payload, dict):
+        is_question = "queId" in payload or "queTitle" in payload
+        if is_question:
+            que_type = _coerce_count(payload.get("queType"))
+            if _should_index_question(payload):
+                questions.append(payload)
+                if que_type in SUBTABLE_QUE_TYPES:
+                    return questions
+            if not _question_is_container_wrapper(payload):
+                return questions
+        for key in ("baseQues", "formQues"):
+            value = payload.get(key)
+            if isinstance(value, list):
+                questions.extend(_collect_top_level_questions(value))
+        for key in ("innerQuestions", "subQues", "subQuestions"):
+            value = payload.get(key)
+            if isinstance(value, list):
+                questions.extend(_collect_top_level_questions(value))
+        return questions
+    if isinstance(payload, list):
+        for item in payload:
+            questions.extend(_collect_top_level_questions(item))
+    return questions
+
+
+def _question_to_form_field(question: JSONObject, *, is_base_question: bool) -> FormField | None:
+    if not _should_index_question(question):
+        return None
+    que_id = _coerce_count(question.get("queId"))
+    title = _stringify_json(question.get("queTitle")).strip()
+    if que_id is None or que_id < 0 or not title:
+        return None
+    can_edit = question.get("canEdit")
+    field = FormField(
+        que_id=que_id,
+        que_title=title,
+        que_type=_coerce_count(question.get("queType")),
+        required=bool(question.get("required") or question.get("beingRequired")),
+        readonly=bool(question.get("readonly") or question.get("beingReadonly") or is_base_question or can_edit is False),
+        system=bool(question.get("system") or question.get("beingSystem") or is_base_question),
+        options=_extract_question_options(question),
+        aliases=[],
+        target_app_key=_extract_relation_target_app_key(question),
+        target_app_name_hint=_extract_relation_target_app_name_hint(question),
+        member_select_scope_type=_coerce_count(question.get("memberSelectScopeType")),
+        member_select_scope=_normalize_scope_payload(question.get("memberSelectScope")),
+        dept_select_scope_type=_coerce_count(question.get("deptSelectScopeType")),
+        dept_select_scope=_normalize_scope_payload(question.get("deptSelectScope")),
+        raw=question,
+    )
+    field.aliases = sorted(_field_alias_candidates(field))
+    return field
+
+
+def _add_subtable_leaf_ref(
+    target: dict[str, list[SubtableLeafRef]],
+    key: str,
+    ref: SubtableLeafRef,
+) -> None:
+    if not key:
+        return
+    refs = target.setdefault(key, [])
+    if any(existing.parent_field.que_id == ref.parent_field.que_id and existing.field.que_id == ref.field.que_id for existing in refs):
+        return
+    refs.append(ref)
+
+
+def _subtable_question_payload(question: JSONObject) -> list[JSONObject]:
+    for key in ("subQuestions", "innerQuestions", "subQues"):
+        value = question.get(key)
+        if isinstance(value, list):
+            return [item for item in _flatten_questions(value) if isinstance(item, dict)]
+    return []
+
+
+def _build_field_index(
+    schema: JSONObject,
+    *,
+    include_subtable_leaf_fields: bool = True,
+    force_subtable_parents_writable: bool = False,
+) -> FieldIndex:
     by_id: dict[str, FormField] = {}
     by_title: dict[str, list[FormField]] = {}
     by_alias: dict[str, list[FormField]] = {}
+    subtable_leaf_by_id: dict[str, list[SubtableLeafRef]] = {}
+    subtable_leaf_by_title: dict[str, list[SubtableLeafRef]] = {}
+    subtable_leaf_by_alias: dict[str, list[SubtableLeafRef]] = {}
     all_questions = [
-        *[(question, True) for question in _flatten_questions(schema.get("baseQues"))],
-        *[(question, False) for question in _flatten_questions(schema.get("formQues"))],
+        *[
+            (question, True)
+            for question in (
+                _flatten_questions(schema.get("baseQues"))
+                if include_subtable_leaf_fields
+                else _collect_top_level_questions(schema.get("baseQues"))
+            )
+        ],
+        *[
+            (question, False)
+            for question in (
+                _flatten_questions(schema.get("formQues"))
+                if include_subtable_leaf_fields
+                else _collect_top_level_questions(schema.get("formQues"))
+            )
+        ],
     ]
     for question, is_base_question in all_questions:
-        if not _should_index_question(question):
+        field = _question_to_form_field(question, is_base_question=is_base_question)
+        if field is None:
             continue
-        que_id = _coerce_count(question.get("queId"))
-        title = _stringify_json(question.get("queTitle")).strip()
-        if que_id is None or que_id < 0 or not title:
+        if force_subtable_parents_writable and field.que_type in SUBTABLE_QUE_TYPES and not field.system:
+            field = _clone_form_field(field, readonly=False)
+        if str(field.que_id) in by_id:
             continue
-        can_edit = question.get("canEdit")
-        field = FormField(
-            que_id=que_id,
-            que_title=title,
-            que_type=_coerce_count(question.get("queType")),
-            required=bool(question.get("required") or question.get("beingRequired")),
-            readonly=bool(question.get("readonly") or question.get("beingReadonly") or is_base_question or can_edit is False),
-            system=bool(question.get("system") or question.get("beingSystem") or is_base_question),
-            options=_extract_question_options(question),
-            aliases=[],
-            target_app_key=_extract_relation_target_app_key(question),
-            target_app_name_hint=_extract_relation_target_app_name_hint(question),
-            member_select_scope_type=_coerce_count(question.get("memberSelectScopeType")),
-            member_select_scope=_normalize_scope_payload(question.get("memberSelectScope")),
-            dept_select_scope_type=_coerce_count(question.get("deptSelectScopeType")),
-            dept_select_scope=_normalize_scope_payload(question.get("deptSelectScope")),
-            raw=question,
-        )
-        if str(que_id) in by_id:
-            continue
-        field.aliases = sorted(_field_alias_candidates(field))
-        by_id[str(que_id)] = field
-        by_title.setdefault(_normalize_field_lookup_key(title), []).append(field)
+        by_id[str(field.que_id)] = field
+        by_title.setdefault(_normalize_field_lookup_key(field.que_title), []).append(field)
         for alias in field.aliases:
             by_alias.setdefault(_normalize_field_lookup_key(alias), []).append(field)
-    return FieldIndex(by_id=by_id, by_title=by_title, by_alias=by_alias)
+        if field.que_type not in SUBTABLE_QUE_TYPES:
+            continue
+        for sub_question in _subtable_question_payload(question):
+            sub_field = _question_to_form_field(cast(JSONObject, sub_question), is_base_question=False)
+            if sub_field is None:
+                continue
+            ref = SubtableLeafRef(field=sub_field, parent_field=field)
+            _add_subtable_leaf_ref(subtable_leaf_by_id, str(sub_field.que_id), ref)
+            _add_subtable_leaf_ref(subtable_leaf_by_title, _normalize_field_lookup_key(sub_field.que_title), ref)
+            for alias in sub_field.aliases:
+                _add_subtable_leaf_ref(subtable_leaf_by_alias, _normalize_field_lookup_key(alias), ref)
+    return FieldIndex(
+        by_id=by_id,
+        by_title=by_title,
+        by_alias=by_alias,
+        subtable_leaf_by_id=subtable_leaf_by_id,
+        subtable_leaf_by_title=subtable_leaf_by_title,
+        subtable_leaf_by_alias=subtable_leaf_by_alias,
+    )
+
+
+def _build_top_level_field_index(schema: JSONObject) -> FieldIndex:
+    return _build_field_index(schema, include_subtable_leaf_fields=False)
+
+
+def _build_applicant_top_level_field_index(schema: JSONObject) -> FieldIndex:
+    return _build_field_index(
+        schema,
+        include_subtable_leaf_fields=False,
+        force_subtable_parents_writable=True,
+    )
+
+
+def _clone_form_field(field: FormField, *, readonly: bool | None = None) -> FormField:
+    return FormField(
+        que_id=field.que_id,
+        que_title=field.que_title,
+        que_type=field.que_type,
+        required=field.required,
+        readonly=field.readonly if readonly is None else readonly,
+        system=field.system,
+        options=list(field.options),
+        aliases=list(field.aliases),
+        target_app_key=field.target_app_key,
+        target_app_name_hint=field.target_app_name_hint,
+        member_select_scope_type=field.member_select_scope_type,
+        member_select_scope=field.member_select_scope,
+        dept_select_scope_type=field.dept_select_scope_type,
+        dept_select_scope=field.dept_select_scope,
+        raw=field.raw,
+    )
+
+
+def _form_field_to_question(field: FormField) -> JSONObject:
+    question = dict(field.raw) if isinstance(field.raw, dict) else {}
+    question.setdefault("queId", field.que_id)
+    question.setdefault("queTitle", field.que_title)
+    if field.que_type is not None:
+        question.setdefault("queType", field.que_type)
+    question["readonly"] = field.readonly
+    question["beingReadonly"] = field.readonly
+    question["required"] = field.required
+    question["beingRequired"] = field.required
+    question["system"] = field.system
+    question["beingSystem"] = field.system
+    return question
+
+
+def _question_ids_from_schema(schema: JSONObject) -> set[int]:
+    question_ids: set[int] = set()
+    for question in _flatten_questions(schema):
+        que_id = _coerce_count(question.get("queId"))
+        if que_id is not None and que_id >= 0:
+            question_ids.add(que_id)
+    return question_ids
+
+
+def _subtable_descendant_ids(field: FormField) -> set[int]:
+    return {
+        item["que_id"]
+        for item in _subtable_columns_for_field(field)
+        if isinstance(item.get("que_id"), int)
+    }
 
 
 def _extract_relation_target_app_key(question: JSONObject) -> str | None:
@@ -5952,6 +6593,10 @@ def _flatten_questions(payload: JSONValue) -> list[JSONObject]:
     return flattened
 
 
+def _question_is_container_wrapper(question: JSONObject) -> bool:
+    return not _should_index_question(question)
+
+
 def _should_index_question(question: JSONObject) -> bool:
     if bool(question.get("beingHide") or question.get("hidden")):
         return False