hap-cli 0.8.26__tar.gz → 0.8.27__tar.gz

{hap_cli-0.8.26 → hap_cli-0.8.27}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hap-cli
-Version: 0.8.26
+Version: 0.8.27
 Summary: CLI harness for Mingdao HAP - Enterprise no-code platform
 Author: hap-cli
 License: Apache-2.0

{hap_cli-0.8.26 → hap_cli-0.8.27}/hap_cli/__init__.py

@@ -1,3 +1,3 @@
 """CLI harness for Mingdao HAP (hap-cli)."""
 
-__version__ = "0.8.26"
+__version__ = "0.8.27"

{hap_cli-0.8.26 → hap_cli-0.8.27}/hap_cli/commands/instance_cmd.py

@@ -6,6 +6,11 @@ import click
 
 from hap_cli.context import pass_context
 from hap_cli.core import instance as inst_mod
+from hap_cli.core import record as rec_mod
+from hap_cli.commands.record_cmd import (
+    _fields_json_to_raw as _rec_fields_json_to_raw,
+    _parse_fields as _rec_parse_fields,
+)
 from hap_cli.utils.formatting import output_json, output_table, output_kv
 from hap_cli.i18n import t
 
@@ -165,15 +170,110 @@ def instance_sign(ctx, instance_id, sign_to, before, work_id, opinion):
         ctx.handle_error(e)
 
 
+def _unwritten_fields(session, worksheet_id, row_id, controls):
+    """Names of controls whose non-empty write did not land on the record.
+
+    A fill-in node only accepts the fields on its own form; anything else is
+    dropped silently. Only non-empty writes are checked, so deliberately
+    clearing a field is never reported.
+    """
+    intended = [
+        c["controlId"] for c in controls
+        if str(c.get("value") or "").strip() not in ("", "[]")
+    ]
+    if not intended:
+        return []
+    row = rec_mod.get_record(session, worksheet_id, row_id) or {}
+    # get_record returns the cell values as a JSON *string* under rowData.
+    values = row.get("rowData") or {}
+    if isinstance(values, str):
+        try:
+            values = _json.loads(values)
+        except ValueError:
+            return []          # unreadable read-back: don't block on a guess
+    if not isinstance(values, dict):
+        return []
+    return [cid for cid in intended
+            if str(values.get(cid) or "").strip() in ("", "[]")]
+
+
 @instance.command("submit")
 @click.argument("instance_id")
 @click.option("--work-id", "-w", default="", help="Work item ID")
 @click.option("--opinion", "-o", default="", help="Submit comment")
+@click.option("--field", "-f", multiple=True,
+              help="Field value to fill in before submitting: FIELD=VALUE "
+                   "(repeatable). FIELD is a field id, alias or name.")
+@click.option("--fields-json", default="",
+              help="Field values to fill in before submitting, as one JSON "
+                   "array: [{\"id\": \"<field id or alias>\", \"value\": ...}, ...]. "
+                   "Use either this or -f, not both. Value formats per field "
+                   "type are in `hap guide record`.")
+@click.option("--dry-run", is_flag=True,
+              help="Resolve the task's record and show what would be written, "
+                   "without filling anything in or submitting.")
 @pass_context
-def instance_submit(ctx, instance_id, work_id, opinion):
-    """Submit a fill-in task."""
+def instance_submit(ctx, instance_id, work_id, opinion, field, fields_json, dry_run):
+    """Submit a fill-in task, optionally filling in its form first.
+
+    The fields of a fill-in task are writable only while you hold the task,
+    so pass them here rather than editing the record separately. Working
+    through todos end to end is covered in `hap guide approval`.
+    """
+    if field and fields_json:
+        raise click.UsageError("Pass exactly one of -f or --fields-json.")
     try:
         session = ctx.get_session()
+        raw = None
+        if field or fields_json:
+            raw = (_rec_fields_json_to_raw(fields_json) if fields_json
+                   else _rec_parse_fields(field))
+        # Read-only resolution first: a fill-in task carries the record it
+        # writes to, which the caller should not have to look up.
+        target = None
+        if raw is not None:
+            target = inst_mod.get_work_item(session, instance_id, work_id=work_id)
+            if not (target or {}).get("worksheetId"):
+                raise click.ClickException(
+                    "Could not resolve the record behind this task, so there "
+                    "is nothing to fill in. Check the instance and work id.")
+        if dry_run:
+            ctx.output(
+                {"instanceId": instance_id, "workId": work_id,
+                 "target": target, "fields": raw, "submitted": False},
+                lambda d: click.echo(
+                    f"Would fill {len(raw or [])} field(s) on "
+                    f"{(target or {}).get('worksheetId', '-')}/"
+                    f"{(target or {}).get('rowId', '-')} and submit."),
+            )
+            return
+        if raw is not None:
+            ws_id, row_id = target["worksheetId"], target.get("rowId", "")
+            controls = rec_mod.encode_controls_by_id(
+                session, ws_id, raw, for_update=True)
+            # The record itself may be read-only outside the task; the
+            # instance/work pair is what grants the write.
+            rec_mod.update_record(
+                session, ws_id, row_id, controls,
+                instance_id=instance_id, work_id=work_id,
+            )
+            # A field the task's form does not contain is dropped by the
+            # server without any error, so the write must be read back
+            # before the task is submitted — otherwise the value is lost
+            # and the task is gone with it.
+            dropped = _unwritten_fields(session, ws_id, row_id, controls)
+            if dropped:
+                # Report the names the caller typed, not internal ids.
+                labels = dict(zip(
+                    [c.get("controlId") for c in controls],
+                    [str(r.get("controlId")) for r in raw],
+                )) if len(controls) == len(raw) else {}
+                shown = [labels.get(cid, cid) for cid in dropped]
+                raise click.ClickException(
+                    "These values were not saved, so the task was NOT "
+                    "submitted: " + ", ".join(shown) + ". A fill-in task "
+                    "only accepts the fields on its own form; fill the rest "
+                    "separately, or drop them and submit again.")
         data = inst_mod.submit(session, instance_id, work_id, opinion)
         ctx.output(data, lambda d: click.echo("Submitted."))
     except Exception as e:

{hap_cli-0.8.26 → hap_cli-0.8.27}/hap_cli/commands/record_cmd.py

@@ -162,8 +162,17 @@ def _fields_json_to_raw(fields_json):
     "--app-id", "-a", default="",
     help="Application ID. Optional — the worksheet id is enough on its own; this only scopes the field lookup.",
 )
+@click.option("--instance-id", default="",
+              help="Workflow instance the edit belongs to. Pass together with "
+                   "--work-id to fill in the form of a fill-in task, whose "
+                   "fields are only writable while you hold that task. To fill "
+                   "a task and submit it in one step use `approval submit -f`; "
+                   "see `hap guide approval`.")
+@click.option("--work-id", default="",
+              help="Workflow work-item the edit belongs to. Use with --instance-id.")
 @pass_context
-def record_update(ctx, worksheet_id, row_id, field, fields_json, no_workflow, app_id):
+def record_update(ctx, worksheet_id, row_id, field, fields_json, no_workflow, app_id,
+                  instance_id, work_id):
     """Update a record.
 
     Pass values either as repeated -f CONTROL_ID=VALUE pairs or as one
@@ -193,6 +202,7 @@ def record_update(ctx, worksheet_id, row_id, field, fields_json, no_workflow, ap
         data = rec_mod.update_record(
             session, worksheet_id, row_id, controls,
             trigger_workflow=not no_workflow, app_id=app_id,
+            instance_id=instance_id, work_id=work_id,
         )
         ctx.output(data, lambda d: click.echo(f"Updated: {d}"))
     except Exception as e:

{hap_cli-0.8.26 → hap_cli-0.8.27}/hap_cli/core/record.py

@@ -965,6 +965,8 @@ def update_record(
     controls: list[dict[str, Any]],
     trigger_workflow: bool = True,
     app_id: str = "",
+    instance_id: str = "",
+    work_id: str = "",
 ) -> dict[str, Any]:
     """Update an existing record.
 
@@ -973,6 +975,14 @@ def update_record(
     AddWorksheetRow, UpdateWorksheetRow's schema has no ``appId``, and
     inventing one would diverge from the frontend.
 
+    ``instance_id`` / ``work_id`` identify a workflow step the caller is
+    acting inside. A fill-in node (填写节点) grants write permission on the
+    fields of its own form for the duration of that step; the record itself
+    may well be read-only otherwise, in which case a plain update answers
+    "权限不足". Passing the pair makes the write happen under the node's
+    permission, exactly as the web form does (UpdateWorksheetRow's
+    ``instanceId`` / ``workId`` params).
+
     Args:
         session: Active session
         worksheet_id: Worksheet ID
@@ -980,21 +990,24 @@ def update_record(
         controls: List of {controlId, value} dicts
         trigger_workflow: Whether to trigger workflows
         app_id: Optional application ID (metadata scope only)
+        instance_id: Workflow instance ID the write belongs to
+        work_id: Workflow work-item ID the write belongs to
 
     Returns:
         Update result
     """
     _reject_workflow_suppression(trigger_workflow)
+    payload: dict[str, Any] = {
+        "worksheetId": worksheet_id,
+        "rowId": row_id,
+        "newOldControl": controls,
+    }
+    if instance_id:
+        payload["instanceId"] = instance_id
+    if work_id:
+        payload["workId"] = work_id
     return _raise_on_failed_write(
-        session.api_call(
-            "Worksheet",
-            "UpdateWorksheetRow",
-            {
-                "worksheetId": worksheet_id,
-                "rowId": row_id,
-                "newOldControl": controls,
-            },
-        ),
+        session.api_call("Worksheet", "UpdateWorksheetRow", payload),
         "update",
     )
 

hap_cli-0.8.27/hap_cli/guide/en/approval.md

@@ -0,0 +1,118 @@
+# Todos and approvals: find, fill, act
+
+`hap approval` handles workflow todos: listing them, filling in the form of a
+fill-in task, approving or rejecting, withdrawing and re-initiating. This topic
+covers which command each kind of todo needs, plus the traps you will hit
+without reading it.
+
+> 🚨 Core risk of this topic: **the fields of a fill-in task cannot be written
+> with a plain record update**. `hap worksheet record update` answers
+> 权限不足 (insufficient permission), and that error points you in entirely the
+> wrong direction (it reads as "your account lacks permission"). The right way
+> is section 3.
+
+## 1. See what is waiting
+
+```bash
+hap approval todo-count                 # counts per kind
+hap approval todo --type 3              # only "waiting for me to fill in"
+```
+
+`--type` values: `-1` all, `0` initiated by me, `3` fill in, `4` approve,
+`5` carbon copy.
+
+Each todo carries two IDs that every later command needs:
+
+- `id` — the **workflow instance id** (instanceId). It is named `id`, which is
+  easy to mistake for an id of the todo itself.
+- `workId` — the **work-item id**, identifying this step for this person.
+
+To find which business record a todo belongs to:
+
+```bash
+hap approval work-item <instanceId> --work-id <workId>   # -> {worksheetId, rowId}
+```
+
+## 2. Approval tasks (type 4)
+
+```bash
+hap approval approve <instanceId> --work-id <workId> -o "Agreed"
+hap approval reject  <instanceId> --work-id <workId> -o "Does not qualify"
+hap approval operations <instanceId> --work-id <workId>   # what this step actually allows
+```
+
+When unsure which buttons a task supports, read `operations` first rather than
+guessing.
+
+## 3. Fill-in tasks (type 3): fill the form and submit
+
+**Do it in one command, not two:**
+
+```bash
+hap approval submit <instanceId> --work-id <workId> \
+  -f 'Frontend owner=谭宏' -f 'Backend owner=陈旭' -o "Assigned"
+```
+
+For richer values use `--fields-json` (same shape as writing a record; per-type
+value formats are in `hap guide record`):
+
+```bash
+hap approval submit <instanceId> --work-id <workId> \
+  --fields-json '[{"id":"Frontend owner","value":["<member accountId>"]}]'
+```
+
+To see which record would be written without touching anything:
+
+```bash
+hap approval submit <instanceId> --work-id <workId> -f 'Amount=100' --dry-run
+```
+
+### Why it has to go this way
+
+A fill-in node's fields are writable **only while you hold the task, and only
+when the write carries the workflow identity**. So:
+
+- A plain `hap worksheet record update <ws> <row> -f 'field=value'` returns
+  **权限不足**. This is not an account-permission problem; do not go asking an
+  admin for rights.
+- If you must edit the record separately, carry the workflow identity:
+  `hap worksheet record update <ws> <row> --instance-id <instanceId> --work-id <workId> ...`
+  That is exactly what `approval submit -f` does internally.
+
+### Only fields on the form can be filled
+
+A fill-in node accepts **only the fields configured on its own form**. Anything
+else is **discarded by the server with no error at all**. `approval submit`
+therefore reads the write back before submitting; if a value did not land it
+stops, names the field, and **does not submit** (the task survives, so you can
+correct and retry). When you see that message, drop the field from the command
+or have the flow designer add it to the node's form.
+
+## 4. Withdraw and re-initiate
+
+```bash
+hap approval revoke <instanceId>            # withdraw a flow you initiated
+hap approval restart <instanceId>           # re-initiate one you withdrew
+```
+
+Notes:
+
+- **Withdrawing uses the work item of the initiating step, not the approver's.**
+  Omit `--work-id` and let the CLI find that initiating work; it is more
+  reliable than filling one in by hand.
+- `restart` requires the flow to have "allow re-initiation" enabled and
+  published, and the instance to actually be in the withdrawn state.
+
+## 5. Other common commands
+
+```bash
+hap approval get <instanceId>               # instance detail
+hap approval op-history <instanceId>        # processing history
+hap approval urge <instanceId> --work-id <workId>   # send a reminder
+hap approval batch ...                      # bulk approve / reject
+hap approval todo-filters ...               # richer todo filtering
+```
+
+The selection for a bulk operation is an **array of objects** (each with the
+instance id and workId), not a list of id strings; see
+`hap approval batch --help` for the exact parameters.

{hap_cli-0.8.26 → hap_cli-0.8.27}/hap_cli/guide/index.json

@@ -24,6 +24,14 @@
         "zh-Hans": "顺着通知或讨论找到它所属的那条应用记录。"
       }
     },
+    {
+      "name": "approval",
+      "title": {"en": "Todos and approvals", "zh-Hans": "待办与审批"},
+      "summary": {
+        "en": "Find, fill in and act on workflow todos. A fill-in task's fields need the workflow identity, or the write is refused.",
+        "zh-Hans": "查看、填写、办理工作流待办。填写类待办的字段必须带工作流身份写，否则报权限不足。"
+      }
+    },
     {
       "name": "chart",
       "title": {"en": "Charts and dashboards", "zh-Hans": "统计图与看板"},

hap_cli-0.8.27/hap_cli/guide/zh-Hans/approval.md

@@ -0,0 +1,105 @@
+# 待办与审批：查、填、办
+
+`hap approval` 处理工作流待办：查看待办、填写「填写节点」的表单、审批通过/否决、
+撤回与重新发起。本主题讲清楚每类待办该用哪个命令，以及几个「不看文档必然踩」的坑。
+
+> 🚨 本主题核心风险：**填写类待办的字段不能用普通的记录更新去写**。直接
+> `hap worksheet record update` 会报「权限不足」，而那个报错会把你引向完全错误的方向
+> （以为是账号没权限）。正确做法见第 3 节。
+
+## 1. 先看有哪些待办
+
+```bash
+hap approval todo-count                 # 各类待办数量
+hap approval todo --type 3              # 只看「待我填写」
+```
+
+`--type` 的取值：`-1` 全部、`0` 我发起的、`3` 填写、`4` 审批、`5` 抄送查看。
+
+列表里每条待办有两个关键 ID，后续所有命令都要用：
+
+- `id` —— **流程实例 ID**（instanceId）。字段名叫 id，容易误以为是待办自己的 id。
+- `workId` —— **工作项 ID**，标识「这一步、这个人」的那条待办。
+
+要知道这条待办对应哪条业务记录，用：
+
+```bash
+hap approval work-item <实例ID> --work-id <工作项ID>   # 返回 {worksheetId, rowId}
+```
+
+## 2. 审批类待办（type 4）
+
+```bash
+hap approval approve <实例ID> --work-id <工作项ID> -o "同意"
+hap approval reject  <实例ID> --work-id <工作项ID> -o "不符合要求"
+hap approval operations <实例ID> --work-id <工作项ID>   # 这一步到底允许哪些操作
+```
+
+拿不准某条待办支持什么按钮时，先 `operations` 看一眼，不要硬猜。
+
+## 3. 填写类待办（type 3）：填字段 + 提交
+
+**用一条命令完成，不要分开做：**
+
+```bash
+hap approval submit <实例ID> --work-id <工作项ID> \
+  -f '前端负责人=谭宏' -f '后端负责人=陈旭' -o "已分配"
+```
+
+复杂取值用 `--fields-json`（形态与写记录一致，各字段类型该传什么见 `hap guide record`）：
+
+```bash
+hap approval submit <实例ID> --work-id <工作项ID> \
+  --fields-json '[{"id":"前端负责人","value":["<成员accountId>"]}]'
+```
+
+不确定会写到哪条记录时，先干跑一次，它只做只读解析、不写也不提交：
+
+```bash
+hap approval submit <实例ID> --work-id <工作项ID> -f '金额=100' --dry-run
+```
+
+### 为什么必须走这条路
+
+填写节点的字段**只在你持有这条待办期间可写，而且必须带着工作流身份写**。
+所以：
+
+- 直接 `hap worksheet record update <表> <行> -f '字段=值'` → **权限不足**。
+  这不是账号权限问题，别去找管理员要权限。
+- 一定要单独改记录时，带上工作流身份即可：
+  `hap worksheet record update <表> <行> --instance-id <实例ID> --work-id <工作项ID> ...`
+  `approval submit -f` 内部就是这么做的。
+
+### 只有表单上的字段能填
+
+一个填写节点只接受**它自己表单里配置的那些字段**。传了表单之外的字段，服务端
+**不报错、直接丢弃**。`approval submit` 会在提交前把写入读回来核对，发现某个值没落库
+就停下并告诉你是哪个字段、且**不会提交**（待办还在，可以改完重来）。看到这个提示时，
+把该字段从命令里去掉，或让流程设计者把它加进节点表单。
+
+## 4. 撤回与重新发起
+
+```bash
+hap approval revoke <实例ID>            # 撤回自己发起的流程
+hap approval restart <实例ID>           # 重新发起已被撤回的流程
+```
+
+要点：
+
+- **撤回用的是「最初发起节点」的工作项，不是当前审批人的**。省略 `--work-id` 让 CLI
+  自己找那条发起 work，比手填可靠。
+- `restart` 要求该审批流程开启了「允许重新发起」并已发布，且实例确实处于撤回后的状态；
+  否则会失败。
+
+## 5. 其它常用
+
+```bash
+hap approval get <实例ID>               # 实例详情
+hap approval op-history <实例ID>        # 办理过程
+hap approval urge <实例ID> --work-id <工作项ID>   # 催办
+hap approval batch ...                  # 批量通过/否决
+hap approval todo-filters ...           # 需要更复杂的待办筛选条件时
+```
+
+批量操作的选择项是**对象数组**（每项带实例 id 与 workId），不是 id 字符串列表；
+具体参数以 `hap approval batch --help` 为准。

{hap_cli-0.8.26 → hap_cli-0.8.27}/hap_cli/locale/messages.json

@@ -2010,8 +2010,20 @@
       "zh-Hans": "工作项 ID"
     },
     "approval submit": {
-      "en": "Submit a fill-in task.",
-      "zh-Hans": "提交填写任务"
+      "en": "Submit a fill-in task, optionally filling in its form first.\n\nThe fields of a fill-in task are writable only while you hold the task,\nso pass them here rather than editing the record separately. Working\nthrough todos end to end is covered in `hap guide approval`.",
+      "zh-Hans": "提交填写任务，可同时填写表单字段。填写节点的字段只有在你持有该待办期间才可写，所以直接在这里传，不要单独去改记录。完整的待办处理流程见 `hap guide approval`。"
+    },
+    "approval submit --dry-run": {
+      "en": "Resolve the task's record and show what would be written, without filling anything in or submitting.",
+      "zh-Hans": "只解析该待办对应的记录并显示将写入什么，不填写也不提交。"
+    },
+    "approval submit --field": {
+      "en": "Field value to fill in before submitting: FIELD=VALUE (repeatable). FIELD is a field id, alias or name.",
+      "zh-Hans": "提交前要填写的字段值：字段=值（可重复）。字段可用字段 ID、别名或名称。"
+    },
+    "approval submit --fields-json": {
+      "en": "Field values to fill in before submitting, as one JSON array: [{\"id\": \"<field id or alias>\", \"value\": ...}, ...]. Use either this or -f, not both. Value formats per field type are in `hap guide record`.",
+      "zh-Hans": "提交前要填写的字段值，一个 JSON 数组：[{\"id\":\"<字段 ID 或别名>\",\"value\":...}, ...]。与 -f 二选一。各字段类型的取值格式见 `hap guide record`。"
     },
     "approval submit --opinion": {
       "en": "Submit comment",
@@ -4573,10 +4585,18 @@
       "en": "All field values as one JSON array: [{\"id\": \"<field id or alias>\", \"value\": ...}, ...]. Values follow the field's kind (option fields take a list of option names or keys; member/relation fields a list of ids). Use either this or -f, not both.",
       "zh-Hans": "所有字段值组成一个 JSON 数组：[{\"id\": \"<field id or alias>\", \"value\": ...}, ...]。值随字段类型而定（选项字段取选项名称或 key 列表；成员/关联字段取 ID 列表）。与 -f 二选一，不可同时使用"
     },
+    "worksheet record update --instance-id": {
+      "en": "Workflow instance the edit belongs to. Pass together with --work-id to fill in the form of a fill-in task, whose fields are only writable while you hold that task. To fill a task and submit it in one step use `approval submit -f`; see `hap guide approval`.",
+      "zh-Hans": "本次修改所属的工作流实例。与 --work-id 一起使用，可填写「填写节点」待办的表单——这些字段只有在你持有该待办期间才可写。若要一步完成填写并提交，用 `approval submit -f`，见 `hap guide approval`。"
+    },
     "worksheet record update --no-workflow": {
       "en": "Don't trigger workflows",
       "zh-Hans": "不触发工作流"
     },
+    "worksheet record update --work-id": {
+      "en": "Workflow work-item the edit belongs to. Use with --instance-id.",
+      "zh-Hans": "本次修改所属的工作流工作项。与 --instance-id 配合使用。"
+    },
     "worksheet rules": {
       "en": "Get business rules for a worksheet.",
       "zh-Hans": "获取工作表的业务规则"

hap_cli-0.8.27/hap_cli/tests/test_approval_submit_fill_cli.py

@@ -0,0 +1,143 @@
+"""CLI tests for filling in a task's form as part of `approval submit`.
+
+A fill-in node's fields are writable only while the task is held, and only
+through the workflow: a plain record update answers 权限不足, while
+``instance/submit`` accepts a ``formData`` payload, reports success and
+silently discards it (verified live, 2026-09-04). So the command composes
+two proven calls — write the record under the instance/work pair, then
+submit — and refuses to submit when the write did not land.
+"""
+
+import json
+from unittest.mock import patch
+
+import pytest
+from click.testing import CliRunner
+
+from hap_cli.hap_cli import cli
+
+
+def _row(**cells):
+    """A get_record response: cell values live in rowData as a JSON string."""
+    return {"rowData": json.dumps(cells)}
+
+
+class TestApprovalSubmitFill:
+    def test_field_and_fields_json_are_mutually_exclusive(self):
+        runner = CliRunner()
+        with patch("hap_cli.context.Context.get_session") as mock_sess:
+            result = runner.invoke(cli, [
+                "approval", "submit", "i1", "-w", "w1",
+                "-f", "a=1", "--fields-json", "[]",
+            ])
+        assert result.exit_code != 0
+        assert not mock_sess.called
+
+    def test_plain_submit_still_works_without_fields(self):
+        """No fields means no record lookup and no write — just submit."""
+        runner = CliRunner()
+        with patch("hap_cli.context.Context.get_session"), \
+                patch("hap_cli.core.instance.get_work_item") as mock_item, \
+                patch("hap_cli.core.record.update_record") as mock_upd, \
+                patch("hap_cli.core.instance.submit") as mock_submit:
+            mock_submit.return_value = True
+            result = runner.invoke(cli, ["approval", "submit", "i1", "-w", "w1"])
+        assert result.exit_code == 0, result.output
+        assert not mock_item.called
+        assert not mock_upd.called
+        assert mock_submit.called
+
+    def test_dry_run_resolves_but_never_mutates(self):
+        runner = CliRunner()
+        with patch("hap_cli.context.Context.get_session"), \
+                patch("hap_cli.core.instance.get_work_item") as mock_item, \
+                patch("hap_cli.core.record.update_record") as mock_upd, \
+                patch("hap_cli.core.instance.submit") as mock_submit:
+            mock_item.return_value = {"worksheetId": "ws1", "rowId": "r1"}
+            result = runner.invoke(cli, [
+                "approval", "submit", "i1", "-w", "w1",
+                "-f", "opinion=ok", "--dry-run",
+            ])
+        assert result.exit_code == 0, result.output
+        assert mock_item.called          # read-only resolution happened
+        assert not mock_upd.called       # but nothing was written
+        assert not mock_submit.called    # and nothing was submitted
+
+    def test_fields_are_written_under_the_workflow_before_submitting(self):
+        runner = CliRunner()
+        with patch("hap_cli.context.Context.get_session"), \
+                patch("hap_cli.core.instance.get_work_item") as mock_item, \
+                patch("hap_cli.core.record.encode_controls_by_id") as mock_enc, \
+                patch("hap_cli.core.record.update_record") as mock_upd, \
+                patch("hap_cli.core.record.get_record") as mock_get, \
+                patch("hap_cli.core.instance.submit") as mock_submit:
+            mock_item.return_value = {"worksheetId": "ws1", "rowId": "r1"}
+            mock_enc.return_value = [{"controlId": "c1", "value": "ok"}]
+            mock_get.return_value = _row(c1="ok")
+            mock_submit.return_value = True
+            result = runner.invoke(cli, [
+                "approval", "submit", "i1", "-w", "w1", "-f", "opinion=ok",
+            ])
+        assert result.exit_code == 0, result.output
+        # The write must carry the workflow identity, or it is 权限不足.
+        kwargs = mock_upd.call_args[1]
+        assert kwargs["instance_id"] == "i1"
+        assert kwargs["work_id"] == "w1"
+        assert mock_submit.called
+
+    def test_silently_dropped_field_blocks_the_submit(self):
+        """The server drops fields outside the node's form without erroring.
+
+        Submitting anyway would lose the value and consume the task, so the
+        command must stop and name the field.
+        """
+        runner = CliRunner()
+        with patch("hap_cli.context.Context.get_session"), \
+                patch("hap_cli.core.instance.get_work_item") as mock_item, \
+                patch("hap_cli.core.record.encode_controls_by_id") as mock_enc, \
+                patch("hap_cli.core.record.update_record"), \
+                patch("hap_cli.core.record.get_record") as mock_get, \
+                patch("hap_cli.core.instance.submit") as mock_submit:
+            mock_item.return_value = {"worksheetId": "ws1", "rowId": "r1"}
+            mock_enc.return_value = [{"controlId": "cAmt", "value": "8888"}]
+            mock_get.return_value = _row(cAmt="")     # write did not land
+            result = runner.invoke(cli, [
+                "approval", "submit", "i1", "-w", "w1", "-f", "金额=8888",
+            ])
+        assert result.exit_code != 0
+        assert "金额" in result.output          # named, not a raw control id
+        assert not mock_submit.called           # task must survive
+
+    def test_write_succeeds_but_submit_fails_surfaces_the_error(self):
+        """Partial state must be reported, not swallowed."""
+        runner = CliRunner()
+        with patch("hap_cli.context.Context.get_session"), \
+                patch("hap_cli.core.instance.get_work_item") as mock_item, \
+                patch("hap_cli.core.record.encode_controls_by_id") as mock_enc, \
+                patch("hap_cli.core.record.update_record") as mock_upd, \
+                patch("hap_cli.core.record.get_record") as mock_get, \
+                patch("hap_cli.core.instance.submit") as mock_submit:
+            mock_item.return_value = {"worksheetId": "ws1", "rowId": "r1"}
+            mock_enc.return_value = [{"controlId": "c1", "value": "ok"}]
+            mock_get.return_value = _row(c1="ok")
+            mock_submit.side_effect = RuntimeError("submit blew up")
+            result = runner.invoke(cli, [
+                "approval", "submit", "i1", "-w", "w1", "-f", "opinion=ok",
+            ])
+        assert result.exit_code != 0
+        assert mock_upd.called          # the write did happen
+        assert "submit blew up" in result.output
+
+    def test_unresolvable_record_fails_before_writing(self):
+        runner = CliRunner()
+        with patch("hap_cli.context.Context.get_session"), \
+                patch("hap_cli.core.instance.get_work_item") as mock_item, \
+                patch("hap_cli.core.record.update_record") as mock_upd, \
+                patch("hap_cli.core.instance.submit") as mock_submit:
+            mock_item.return_value = {}
+            result = runner.invoke(cli, [
+                "approval", "submit", "i1", "-w", "w1", "-f", "opinion=ok",
+            ])
+        assert result.exit_code != 0
+        assert not mock_upd.called
+        assert not mock_submit.called