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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hap-cli
-Version: 0.8.25
+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.25 → hap_cli-0.8.27}/hap_cli/__init__.py

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

{hap_cli-0.8.25 → hap_cli-0.8.27}/hap_cli/commands/chart_cmd.py

@@ -123,7 +123,8 @@ def _resolve_app_id_for_filter(session, worksheet_id: str, extra: dict) -> str:
     return (data or {}).get("appId", "") if isinstance(data, dict) else ""
 
 
-@chart.command("create")
+@chart.command("create", help="Create a new chart on a worksheet. "
+                              "Chart spec shapes are in `hap guide chart`.")
 @click.argument("worksheet_id")
 @click.option("--name", required=True, help="Chart display name.")
 @click.option("--report-type", "report_type", type=int, required=True,
@@ -163,7 +164,9 @@ def chart_create(ctx, worksheet_id, name, report_type, app_type, app_id,
         ctx.handle_error(e)
 
 
-@chart.command("update")
+@chart.command("update", help="Update an existing chart's configuration. "
+                              "Read the config with `chart get`, edit it, submit "
+                              "it back — see `hap guide chart`.")
 @click.argument("report_id")
 @click.option("--app-id", "-a", required=True, help="Worksheet ID the chart attaches to.")
 @click.option("--name", required=True, help="Chart display name.")

{hap_cli-0.8.25 → 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.25 → 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:
@@ -374,16 +384,28 @@ def record_discussions(ctx, worksheet_id, row_id, page_size, page):
 @click.option("--app-id", default="", help="Application ID (auto-detected from the worksheet if omitted)")
 @click.option("--view-id", default="", help="View ID the discussion originates from")
 @click.option("--reply-id", default="", help="ID of the discussion being replied to")
+@click.option("--file", "-f", "files", multiple=True,
+              help="Attach a file to the comment (repeatable). Accepts a local "
+                   "path or an http(s) URL.")
 @pass_context
-def record_add_discussion(ctx, worksheet_id, row_id, message, app_id, view_id, reply_id):
+def record_add_discussion(ctx, worksheet_id, row_id, message, app_id, view_id, reply_id, files):
     """Add a discussion/comment to a record."""
     try:
         session = ctx.get_session()
+        attachments = None
+        if files:
+            from hap_cli.core import upload as up_mod
+            descriptors = up_mod.source_descriptors(list(files))
+            attachments = up_mod.upload_files(
+                session, descriptors,
+                worksheet_id=worksheet_id, app_id=app_id,
+            )
         data = rec_mod.add_discussion(
             session, worksheet_id, row_id, message,
             app_id=app_id, view_id=view_id, reply_id=reply_id,
+            attachments=attachments,
         )
-        ctx.output(data, lambda d: click.echo(f"Discussion added."))
+        ctx.output(data, lambda d: click.echo("Discussion added."))
     except Exception as e:
         ctx.handle_error(e)
 

{hap_cli-0.8.25 → hap_cli-0.8.27}/hap_cli/core/chart.py

@@ -44,6 +44,30 @@ from hap_cli.core.session import Session
 
 logger = logging.getLogger("hap_cli.chart")
 
+# A chart that is saved without a ``filter`` block saves successfully but
+# never renders: the statistics backend cannot scope the query and
+# ``report/getData`` answers status -1/0, which the UI paints as
+# "无法形成图表 / 构成要素不存在或已删除". The chart looks fine in the editor
+# (which supplies its own default scope) and only breaks after save — the
+# single most common way a hand-written ``chart create`` spec silently
+# produces a blank chart. The frontend's ``getNewReport`` always injects a
+# default time filter for a new worksheet chart; we mirror that here, but
+# default to ``rangeType: 0`` (全部时间 / all-time) instead of the UI's
+# "last 365 days" so the chart is never blank merely because the default
+# window excluded older data. Callers that supply their own ``filter``
+# (any non-empty dict) keep it untouched.
+_DEFAULT_CHART_FILTER: dict[str, Any] = {
+    "filterRangeId": "ctime",
+    "filterRangeName": "创建时间",
+    "rangeType": 0,
+    "rangeValue": None,
+    "today": False,
+    "dynamicFilter": {
+        "startType": 1, "startCount": 1, "startUnit": 1,
+        "endType": 1, "endCount": 1, "endUnit": 1,
+    },
+}
+
 
 def list_charts(
     session: Session,
@@ -218,6 +242,12 @@ def save_chart(
         split_control_id = body["split"].get("controlId")
         if split_control_id:
             body["splitId"] = split_control_id
+    # A chart with no filter block saves but never renders (blank after
+    # save — see _DEFAULT_CHART_FILTER). Inject an all-time default when the
+    # caller omitted it; a caller-supplied filter (any non-empty value) is
+    # left untouched so an explicit scope always wins.
+    if not body.get("filter"):
+        body["filter"] = dict(_DEFAULT_CHART_FILTER)
     # Resolve the chart's filter block before sending saveReportConfig.
     if isinstance(body.get("filter"), dict):
         body["filter"] = _ensure_filter_id(

{hap_cli-0.8.25 → 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",
     )
 
@@ -1089,6 +1102,7 @@ def add_discussion(
     app_id: str = "",
     view_id: str = "",
     reply_id: str = "",
+    attachments: Optional[list[dict[str, Any]]] = None,
 ) -> dict[str, Any]:
     """Add a discussion/comment to a record (sourceType 8 / worksheet-row).
 
@@ -1117,6 +1131,12 @@ def add_discussion(
     }
     if reply_id:
         data["replyId"] = reply_id
+    # ``attachments`` carries uploaded-file descriptors (from
+    # hap_cli.core.upload). The frontend WorkSheetCommenter sends them as a
+    # JSON-encoded string under ``attachments`` (see pd-openweb
+    # components/comment/commenter.jsx), so match that shape.
+    if attachments:
+        data["attachments"] = json.dumps(attachments, ensure_ascii=False)
     result = session.api_call("Discussion", "AddDiscussion", data)
     _ensure_discussion_ok(result, "add discussion")
     return result

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.27/hap_cli/guide/en/chart.md

@@ -0,0 +1,150 @@
+# Charts: create, update, place on a custom page
+
+`hap worksheet chart` builds a chart (report) on a worksheet; `hap custom-page`
+places charts into a custom page to form a dashboard. This topic covers how to
+shape a chart spec, the right way to edit a chart, and the most common trap —
+"saved fine, blank on the page".
+
+> 🚨 Core risk of this topic: **an under-specified chart still saves
+> successfully but renders blank**, showing "无法形成图表 / 构成要素不存在或已删除"
+> (cannot draw chart / component missing or deleted). It looks right in the
+> editor and only breaks after save. Root cause is in section 3 — the CLI now
+> backfills the missing filter scope, but you still need the model.
+
+## 1. What a chart is made of
+
+A chart hangs off **one worksheet** and needs at least three things:
+
+- **Data source**: the worksheet ID (`WORKSHEET_ID` in the command, `appId` in
+  the spec). Note HAP's chart spec calls the worksheet `appId` — it is NOT the
+  application ID. When editing a chart, do not fill this with the app ID.
+- **Dimension `xaxes`**: the grouping, e.g. by date (year) or by status. A
+  number chart (`report_type=10`) may have no dimension — just a value.
+- **Value `yaxisList`**: what to aggregate, e.g. sum of amount, record count.
+
+Plus a **required filter scope `filter`** (section 3).
+
+## 2. Chart types (reportType integer)
+
+Pass an integer to `--report-type`. **There is no 4** — an old API doc labels 4
+as the number chart, which is wrong; the number chart is **10**.
+
+| # | type | # | type |
+|---|------|---|------|
+| 1 | column | 10 | number |
+| 2 | line | 11 | bidirectional bar |
+| 3 | pie | 12 | scatter |
+| 5 | radar | 13 | word cloud |
+| 6 | funnel | 14 | gauge |
+| 7 | dual-axis | 15 | progress |
+| 8 | pivot | 16 | ranking |
+| 9 | region map | 17 | world map |
+
+## 3. Why "saved but blank": a missing filter
+
+A chart **saves successfully even with no `filter` block** (`create` still
+returns a `reportId`), but at render time the backend cannot scope the query and
+`report/getData` returns status -1/0, so the page shows "cannot draw chart". This
+is exactly the "fine in editor, blank after save" symptom: the editor supplies
+its own default scope, the stored spec does not.
+
+**The CLI now injects a default all-time filter when you omit `filter`**, so a
+plain `chart create` no longer goes blank. You only need to write `filter`
+yourself to **restrict the time range**:
+
+```jsonc
+"filter": {
+  "filterRangeId": "ctime",          // which date field to scope by; "ctime"=create time
+  "filterRangeName": "创建时间",
+  "rangeType": 0,                     // 0=all time; 8=this month; 18=last N days (with rangeValue)
+  "rangeValue": null,
+  "today": false
+}
+```
+
+Common `rangeType`: `0` all, `4` this week, `8` this month, `11` this quarter,
+`15` this year, `16` last year, `18` last N days (`rangeValue` = day count, e.g. 365).
+
+## 4. Create: `hap worksheet chart create`
+
+Pass the spec via `-j/--spec-json` (inline) or `-f/--spec-file` (file). Reference
+fields by **controlId**; read fields with `hap worksheet fields WS_ID`.
+
+**Column chart (amount by status):**
+
+```bash
+hap worksheet chart create WS_ID --name "Amount by status" --report-type 1 -j '{
+  "xaxes": {"controlId": "<status field>", "controlType": 11},
+  "yaxisList": [{"controlId": "<amount field>", "controlType": 6, "normType": 1}]
+}'
+```
+
+**Number chart (no dimension, one value):** `--report-type 10`, spec with only `yaxisList`.
+
+`yaxisList[].normType` aggregation: `1` sum, `2` max, `3` min, `4` avg, `5` count,
+`6` distinct count. Numeric fields default to `1`, text/option fields use `5`.
+Record count uses the special column
+`{"controlId": "record_count", "controlName": "记录数量", "controlType": 10000000, "normType": 5}`.
+
+**Date dimension**: add `particleSizeType` to `xaxes`: `5` year, `4` quarter,
+`3` month, `2` week, `1` day.
+
+**Condition filter** (not a time range but "status = done"): put a high-level
+`items` array in `filter`; the CLI stores it as a saved filter and backfills the id:
+
+```jsonc
+"filter": {"items": [{"controlId": "<status field>", "dataType": 11, "spliceType": 1,
+                      "filterType": 2, "values": ["<option key>"]}]}
+```
+
+When using `items`, pass `--app-id <application id>` (the app, not the worksheet)
+so the CLI can store the filter.
+
+## 5. Update: read the config, change a few params, submit back
+
+You don't rebuild a spec from scratch. **Read the current config, change what you
+need, submit the whole thing back:**
+
+```bash
+# 1. read the current config
+hap --json worksheet chart get REPORT_ID --app-id WS_ID > chart.json
+# 2. edit chart.json (name / normType / xaxes / add a filter, etc.)
+# 3. submit it back (update needs --app-id=worksheetId, --name, --report-type)
+hap worksheet chart update REPORT_ID --app-id WS_ID --name "New name" --report-type 1 -f chart.json
+```
+
+Extra fields `get` returns (`controls`, `account`, `createdDate`) can be passed
+back as-is; the server ignores them. `update` replaces the whole config, so edit
+on top of the read config — don't send only the fields you changed.
+
+## 6. Place on a custom page (dashboard)
+
+Once the chart exists and you have its `reportId`, add it as a component with
+`custom-page save`.
+
+```bash
+# page version: read it first with hap --json custom-page info PAGE_ID, pass the same value
+hap custom-page save PAGE_ID --version <current version> --components '[
+  {"type": 1, "value": "<reportId>", "worksheetId": "<WS_ID>",
+   "name": "Amount by status", "reportType": 1,
+   "config": {"objectId": "<32 hex chars>"},
+   "web": {"title": "", "titleVisible": false, "visible": true,
+           "layout": {"x": 0, "y": 0, "w": 24, "h": 10, "minW": 2, "minH": 4}},
+   "mobile": {"title": "", "titleVisible": false, "visible": true, "layout": null}}
+]'
+```
+
+Key points:
+
+- A chart component has `type` **1**, `value` = `reportId`, plus `worksheetId`
+  and `reportType`.
+- `config.objectId` is a unique 32-hex string per component (used by linked filters).
+- Layout is a **48-column grid**: `w` max 48; two charts per row at `w:24` each.
+- `--version` must equal the page's current version, else "自定义页面保存失败";
+  a successful save bumps version by 1.
+- `save` replaces the whole page: to keep existing components, read them via
+  `custom-page info` first and append the new one before submitting.
+
+For building a whole app with dashboards, prefer the `hap-cli-app-creator` skill:
+it generates full chart specs and page layouts from a friendly config. Use the
+commands above to hand-edit a single chart or add one chart to an existing page.

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

@@ -24,6 +24,22 @@
         "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": "统计图与看板"},
+      "summary": {
+        "en": "Chart spec shape, editing a chart, placing it on a custom page. Miss a field and it saves fine but renders blank.",
+        "zh-Hans": "图表规格怎么写、怎么改图、怎么放进自定义页。写少了照样保存成功，页面却空白。"
+      }
+    },
     {
       "name": "skills",
       "title": {"en": "When to hand off", "zh-Hans": "什么时候转交专项 skill"},