hap-cli 0.8.30__tar.gz → 0.9.0__tar.gz

{hap_cli-0.8.30 → hap_cli-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hap-cli
-Version: 0.8.30
+Version: 0.9.0
 Summary: CLI harness for Mingdao HAP - Enterprise no-code platform
 Author: hap-cli
 License: Apache-2.0
@@ -131,7 +131,9 @@ hap worksheet record list WORKSHEET_ID --page-size 10
 hap --json worksheet record list WORKSHEET_ID
 ```
 
-Every command supports `--json` for machine-readable output.
+Every command supports `--json` for machine-readable output. It can go
+before or after the command: `hap --json post list` and `hap post list --json`
+do the same thing.
 
 ---
 
@@ -164,9 +166,9 @@ discover every subcommand.
 | `app select APP_ID` / `app unselect` | Manage the default app used when `--app-id` is omitted |
 | `app create-section / edit-section / delete-section` | Section management |
 | `app sort-sections / sort-worksheets` | Reorder sections / a section's worksheets |
-| `app create-item` | Batch-create empty worksheets / custom pages |
 | `app backup / export / exports / backup-logs` | Backup & export |
-| `app usage / logs` | Statistics and operation logs |
+| `app usage / logs / log-archives` | Statistics, operation logs and their archives |
+| `app trash` | What was deleted from an application, and by whom |
 | `app role …` | Role CRUD, permissions, members, leave-all, applications |
 | `app optionset …` | Option set CRUD and cross-app moves |
 | `app knowledge list / search` | Vector knowledge bases |
@@ -175,24 +177,30 @@ discover every subcommand.
 
 | Command | Description |
 |---|---|
-| `worksheet list / info / fields / field-types` | Discover structure |
-| `worksheet create / update / copy / delete` | Worksheet lifecycle |
+| `worksheet list / info / fields / field-types` | Discover structure (`info --with-form --with-views` pulls the layout and views in the same call) |
+| `worksheet list --workflows / --without-workflows` | See which worksheets have automation, and which have none |
+| `worksheet references` | What else points at a worksheet — fields in other sheets, and workflow steps |
+| `worksheet create / update / copy / delete` | Worksheet lifecycle (`update --visibility` hides a sheet from the app navigation) |
+| `worksheet pair-relation` | Make a relation field point both ways (`--repair` fixes one paired by hand) |
+| `worksheet add-fields / update-fields` | Append fields, or replace the whole field layout |
+| `worksheet mount-subtable` | Embed an existing worksheet as a sub-table |
 | `worksheet rules / save-rule` | Business rules |
-| `worksheet switches / edit-switch` | Feature switches |
+| `worksheet switches / switch-types / edit-switch / batch-edit-switch` | Feature switches |
 | `worksheet form-settings / save-form-settings` | Form submission settings |
 | `worksheet custom-actions / create-custom-action / delete-custom-action` | Custom action buttons |
-| `worksheet create-chart` | Build a statistics chart on a worksheet |
-| `worksheet view list / info / create / copy / delete / sort` | View management |
+| `worksheet chart list / get / create / update / delete` | Statistics charts on a worksheet |
+| `worksheet view list / info / create / copy / delete / sort` | View management (`list --deleted` is the recycle bin; a spec can group a table, restrict its columns, or name a plugin) |
 
 ### worksheet record — record CRUD
 
 | Command | Description |
 |---|---|
 | `worksheet record list / get` | Query and read |
-| `worksheet record create / update / delete` | Single-row CRUD |
-| `worksheet record batch-create / batch-update` | Bulk operations (main-site path; relation/sub-table cells persist) |
+| `worksheet record create / update / delete` | Single-row CRUD (`update --lock` / `--unlock` locks a record against edits) |
+| `worksheet record batch-create / batch-update` | Bulk operations (relation/sub-table cells persist; `batch-create --single-request` writes them all in one call) |
 | `worksheet record relations / share-link` | Linked records and share URLs |
-| `worksheet record discussions / add-discussion / delete-discussion` | Discussion threads |
+| `worksheet record run-action` | Press a custom action button on one or more records (`--button` by name or ID, `--row-ids` comma-separated or repeated) |
+| `worksheet record discussions / add-discussion / delete-discussion` | Discussion threads (mention people with `--at-all` / `--at`) |
 | `worksheet record logs` | Per-record change log |
 | `worksheet record pivot / bottom-stats` | Aggregations and summary rows |
 
@@ -200,13 +208,12 @@ discover every subcommand.
 
 | Command | Description |
 |---|---|
-| `workflow list / get / structure / history / groups / stats` | Inspect |
-| `workflow create / update / copy / move / delete` | Lifecycle |
+| `workflow list / get / structure / history / groups / stats / pbp-parameters` | Inspect (`list --kind` filters by trigger) |
+| `workflow create / update / copy / move / delete / restore / purge` | Lifecycle (delete is the recycle bin; restore and purge are the way out) |
 | `workflow publish / rollback` | Versioning |
 | `workflow trigger / trigger-pbp` | Manual trigger |
 | `workflow config-get / config-set` | Global config |
-| `workflow create-approval / update-approval / delete-approval` | Approval blocks |
-| `workflow node …` | Node CRUD, batch-add / batch-update / batch-delete (and `*-approval` variants), test-code / test-webhook / test-ai, controls, types, code templates |
+| `workflow node …` | Node CRUD, batch-add, save-action / save-search / save-get-more, test-code / test-webhook / test-ai, controls, types, code templates |
 
 > Always run `hap workflow structure PROCESS_ID` before computing insertion
 > points, branch IDs, or approval block IDs. Don't fabricate node / block /
@@ -216,9 +223,9 @@ discover every subcommand.
 
 | Command | Description |
 |---|---|
-| `approval todo / todo-count / todo-filters / archived` | Pending and archived |
-| `approval get / get-by-row / list-by-row / work-item / operations / op-history / history / history-detail` | Read instance state |
-| `approval approve / reject / submit / sign / forward / urge` | Act on a task |
+| `approval todo / todo-count / done-count / todo-filters / archived` | Pending, finished and archived |
+| `approval get / work-item / operations / op-history / history / history-detail` | Read instance state |
+| `approval approve / reject / submit / sign / forward / transfer / undo-approval / urge` | Act on a task (signature, attachments and the next step's approvers included) |
 | `approval revoke / terminate / restart / retry` | Lifecycle |
 | `approval batch / retry-batch / end-batch` | Bulk variants |
 | `approval list-types` | Enum reference |
@@ -239,6 +246,7 @@ discover every subcommand.
 | `contact search / resolve` | Find members by keyword / name / email / phone |
 | `contact friends / friend-requests` | Address book |
 | `contact add-friend / accept-friend / reject-friend / ignore-friend / remove-friend` | Friend management |
+| `contact org-roles / org-role-members` | Organization roles and who holds them |
 
 ### department — directory
 
@@ -264,6 +272,7 @@ discover every subcommand.
 | `calendar list / get / create / update / delete` | Event lifecycle |
 | `calendar categories` | Built-in categories |
 | `calendar add-member / remove-member` | Membership |
+| `calendar add-discussion` | Comment on an event (attachments supported; mention people with `--at-all` / `--at`) |
 
 ### chat — chat & messaging
 
@@ -280,6 +289,7 @@ discover every subcommand.
 
 | Command | Description |
 |---|---|
+| `group list` | List open groups you have joined (`--org-id`, `--keywords`, and pagination options) |
 | `group info GROUP_ID` | Group metadata |
 | `group create` | Create a new group (`--name`, `--org-id`, optional `--member`) |
 | `group add-member` | Add one or more members (`--group-id`, `--account-id`) |
@@ -302,7 +312,7 @@ discover every subcommand.
 
 | Command | Description |
 |---|---|
-| `attachment share ADDRESS` | Create a link to a stored file that you can pass on (`--hours`, default 48) |
+| `attachment share [ADDRESS]` | Create a link to a stored file that you can pass on (`--hours`, default 48; `--file-id` to share by attachment id, `--short` for a landing page instead of the storage address) |
 
 > ADDRESS is the file's link — one that has already stopped working is fine, paste it as-is — or just the path part of it. The file itself does not expire, only the link does, so a dead link can always be revived.
 
@@ -310,7 +320,7 @@ discover every subcommand.
 
 | Command | Description |
 |---|---|
-| `guide` | Built-in usage guide: what this version can do, and the value formats that are easy to get wrong (`hap guide <topic>` for detail) |
+| `guide` | Built-in usage guide: what this version can do, and the value formats that are easy to get wrong. `hap guide` lists the topics, `hap guide <topic>` what one covers section by section, `hap guide <topic> <number or name>` one section |
 
 ### upload — file upload
 

{hap_cli-0.8.30/hap_cli → hap_cli-0.9.0}/README.md

@@ -102,7 +102,9 @@ hap worksheet record list WORKSHEET_ID --page-size 10
 hap --json worksheet record list WORKSHEET_ID
 ```
 
-Every command supports `--json` for machine-readable output.
+Every command supports `--json` for machine-readable output. It can go
+before or after the command: `hap --json post list` and `hap post list --json`
+do the same thing.
 
 ---
 
@@ -135,9 +137,9 @@ discover every subcommand.
 | `app select APP_ID` / `app unselect` | Manage the default app used when `--app-id` is omitted |
 | `app create-section / edit-section / delete-section` | Section management |
 | `app sort-sections / sort-worksheets` | Reorder sections / a section's worksheets |
-| `app create-item` | Batch-create empty worksheets / custom pages |
 | `app backup / export / exports / backup-logs` | Backup & export |
-| `app usage / logs` | Statistics and operation logs |
+| `app usage / logs / log-archives` | Statistics, operation logs and their archives |
+| `app trash` | What was deleted from an application, and by whom |
 | `app role …` | Role CRUD, permissions, members, leave-all, applications |
 | `app optionset …` | Option set CRUD and cross-app moves |
 | `app knowledge list / search` | Vector knowledge bases |
@@ -146,24 +148,30 @@ discover every subcommand.
 
 | Command | Description |
 |---|---|
-| `worksheet list / info / fields / field-types` | Discover structure |
-| `worksheet create / update / copy / delete` | Worksheet lifecycle |
+| `worksheet list / info / fields / field-types` | Discover structure (`info --with-form --with-views` pulls the layout and views in the same call) |
+| `worksheet list --workflows / --without-workflows` | See which worksheets have automation, and which have none |
+| `worksheet references` | What else points at a worksheet — fields in other sheets, and workflow steps |
+| `worksheet create / update / copy / delete` | Worksheet lifecycle (`update --visibility` hides a sheet from the app navigation) |
+| `worksheet pair-relation` | Make a relation field point both ways (`--repair` fixes one paired by hand) |
+| `worksheet add-fields / update-fields` | Append fields, or replace the whole field layout |
+| `worksheet mount-subtable` | Embed an existing worksheet as a sub-table |
 | `worksheet rules / save-rule` | Business rules |
-| `worksheet switches / edit-switch` | Feature switches |
+| `worksheet switches / switch-types / edit-switch / batch-edit-switch` | Feature switches |
 | `worksheet form-settings / save-form-settings` | Form submission settings |
 | `worksheet custom-actions / create-custom-action / delete-custom-action` | Custom action buttons |
-| `worksheet create-chart` | Build a statistics chart on a worksheet |
-| `worksheet view list / info / create / copy / delete / sort` | View management |
+| `worksheet chart list / get / create / update / delete` | Statistics charts on a worksheet |
+| `worksheet view list / info / create / copy / delete / sort` | View management (`list --deleted` is the recycle bin; a spec can group a table, restrict its columns, or name a plugin) |
 
 ### worksheet record — record CRUD
 
 | Command | Description |
 |---|---|
 | `worksheet record list / get` | Query and read |
-| `worksheet record create / update / delete` | Single-row CRUD |
-| `worksheet record batch-create / batch-update` | Bulk operations (main-site path; relation/sub-table cells persist) |
+| `worksheet record create / update / delete` | Single-row CRUD (`update --lock` / `--unlock` locks a record against edits) |
+| `worksheet record batch-create / batch-update` | Bulk operations (relation/sub-table cells persist; `batch-create --single-request` writes them all in one call) |
 | `worksheet record relations / share-link` | Linked records and share URLs |
-| `worksheet record discussions / add-discussion / delete-discussion` | Discussion threads |
+| `worksheet record run-action` | Press a custom action button on one or more records (`--button` by name or ID, `--row-ids` comma-separated or repeated) |
+| `worksheet record discussions / add-discussion / delete-discussion` | Discussion threads (mention people with `--at-all` / `--at`) |
 | `worksheet record logs` | Per-record change log |
 | `worksheet record pivot / bottom-stats` | Aggregations and summary rows |
 
@@ -171,13 +179,12 @@ discover every subcommand.
 
 | Command | Description |
 |---|---|
-| `workflow list / get / structure / history / groups / stats` | Inspect |
-| `workflow create / update / copy / move / delete` | Lifecycle |
+| `workflow list / get / structure / history / groups / stats / pbp-parameters` | Inspect (`list --kind` filters by trigger) |
+| `workflow create / update / copy / move / delete / restore / purge` | Lifecycle (delete is the recycle bin; restore and purge are the way out) |
 | `workflow publish / rollback` | Versioning |
 | `workflow trigger / trigger-pbp` | Manual trigger |
 | `workflow config-get / config-set` | Global config |
-| `workflow create-approval / update-approval / delete-approval` | Approval blocks |
-| `workflow node …` | Node CRUD, batch-add / batch-update / batch-delete (and `*-approval` variants), test-code / test-webhook / test-ai, controls, types, code templates |
+| `workflow node …` | Node CRUD, batch-add, save-action / save-search / save-get-more, test-code / test-webhook / test-ai, controls, types, code templates |
 
 > Always run `hap workflow structure PROCESS_ID` before computing insertion
 > points, branch IDs, or approval block IDs. Don't fabricate node / block /
@@ -187,9 +194,9 @@ discover every subcommand.
 
 | Command | Description |
 |---|---|
-| `approval todo / todo-count / todo-filters / archived` | Pending and archived |
-| `approval get / get-by-row / list-by-row / work-item / operations / op-history / history / history-detail` | Read instance state |
-| `approval approve / reject / submit / sign / forward / urge` | Act on a task |
+| `approval todo / todo-count / done-count / todo-filters / archived` | Pending, finished and archived |
+| `approval get / work-item / operations / op-history / history / history-detail` | Read instance state |
+| `approval approve / reject / submit / sign / forward / transfer / undo-approval / urge` | Act on a task (signature, attachments and the next step's approvers included) |
 | `approval revoke / terminate / restart / retry` | Lifecycle |
 | `approval batch / retry-batch / end-batch` | Bulk variants |
 | `approval list-types` | Enum reference |
@@ -210,6 +217,7 @@ discover every subcommand.
 | `contact search / resolve` | Find members by keyword / name / email / phone |
 | `contact friends / friend-requests` | Address book |
 | `contact add-friend / accept-friend / reject-friend / ignore-friend / remove-friend` | Friend management |
+| `contact org-roles / org-role-members` | Organization roles and who holds them |
 
 ### department — directory
 
@@ -235,6 +243,7 @@ discover every subcommand.
 | `calendar list / get / create / update / delete` | Event lifecycle |
 | `calendar categories` | Built-in categories |
 | `calendar add-member / remove-member` | Membership |
+| `calendar add-discussion` | Comment on an event (attachments supported; mention people with `--at-all` / `--at`) |
 
 ### chat — chat & messaging
 
@@ -251,6 +260,7 @@ discover every subcommand.
 
 | Command | Description |
 |---|---|
+| `group list` | List open groups you have joined (`--org-id`, `--keywords`, and pagination options) |
 | `group info GROUP_ID` | Group metadata |
 | `group create` | Create a new group (`--name`, `--org-id`, optional `--member`) |
 | `group add-member` | Add one or more members (`--group-id`, `--account-id`) |
@@ -273,7 +283,7 @@ discover every subcommand.
 
 | Command | Description |
 |---|---|
-| `attachment share ADDRESS` | Create a link to a stored file that you can pass on (`--hours`, default 48) |
+| `attachment share [ADDRESS]` | Create a link to a stored file that you can pass on (`--hours`, default 48; `--file-id` to share by attachment id, `--short` for a landing page instead of the storage address) |
 
 > ADDRESS is the file's link — one that has already stopped working is fine, paste it as-is — or just the path part of it. The file itself does not expire, only the link does, so a dead link can always be revived.
 
@@ -281,7 +291,7 @@ discover every subcommand.
 
 | Command | Description |
 |---|---|
-| `guide` | Built-in usage guide: what this version can do, and the value formats that are easy to get wrong (`hap guide <topic>` for detail) |
+| `guide` | Built-in usage guide: what this version can do, and the value formats that are easy to get wrong. `hap guide` lists the topics, `hap guide <topic>` what one covers section by section, `hap guide <topic> <number or name>` one section |
 
 ### upload — file upload
 

hap_cli-0.9.0/app_live_tests/fixtures/__init__.py

@@ -0,0 +1 @@
+"""Long-lived live fixtures. Built once, kept, reused by later work."""

hap_cli-0.9.0/app_live_tests/fixtures/feedback_scenario.py

@@ -0,0 +1,256 @@
+"""Build the FB- scenario: the shape the feedback report was written about.
+
+Twenty-odd near-identical document tables spread over sub-groups, copied
+from one template, wired together with sub-tables, relations, look-ups,
+roll-ups, formulas, dynamic defaults and one two-way pair. That shape is
+what made the report's problems visible, so the fixes need it standing.
+
+This is deliberately **not** torn down: it is the baseline later work
+reads from. Everything it makes is named ``FB-*`` and lives in the
+persistent live-test application.
+
+Every server interaction goes through the ``hap`` CLI. That is the point
+— the report's complaint was that none of this could be done with the
+CLI, so a fixture that reached for ``session.api_call`` would be
+assuming away the thing under test.
+
+Run:
+    python3 -m app_live_tests.fixtures.feedback_scenario          # build / repair
+    python3 -m app_live_tests.fixtures.feedback_scenario --show   # print ids
+
+It is idempotent: anything already there by name is reused, so a second
+run makes no new objects.
+
+FB-单据B-模板 is deliberately left in a damaged state — see below.
+
+Two-way pairing, and why one sheet here is broken on purpose
+-----------------------------------------------------------
+There is no supported way to pair a relation two-way from the CLI. The
+report's author worked one out (3.5): read the placeholder the server
+puts on the forward field's ``sourceControlId``, then create a field on
+the target sheet whose ``controlId`` is forced to that placeholder. It
+does produce a pair that reads as two-way — and it leaves the target
+sheet corrupting on every later save.
+
+Measured 2026-09-10 on this fixture:
+
+* ``FB-单据B-模板`` holds such a forged reverse end. Reading its 14
+  controls and posting the same 14 back answers ``操作成功`` and reads
+  back 15, the reverse-end control duplicated under one ``controlId``.
+  Repeated three times: 14 in, 15 out, every time. Sending a
+  de-duplicated layout does not help; the only clean layout is one that
+  drops the pairing altogether.
+* ``FB-明细-隐藏`` holds a reverse end created by ``mount-subtable``,
+  which pairs through the supported path. Same no-op replace: 5 in, 5
+  out, clean.
+* ``FB-单据A-模板`` is the forward side and carries all six bridge
+  fields. Same no-op replace: 22 in, 22 out, clean, every bridge intact.
+
+So a full-layout replace is not broadly unsafe, and this is not a
+server-side defect in ``SaveWorksheetControls``. What corrupts is a
+reverse end that was never registered as one — the server re-materialises
+the real far side beside the forged one on every save. Which means the
+recipe in report 3.5 quietly damages every sheet it is applied to, and
+sheets built that way accumulate a copy per edit.
+
+The damage is left standing here on purpose: a fix for report 3.4 has to
+classify this pair as two-way, and the ``--check`` validator asked for in
+3.7 has to notice the duplicate ``controlId``.
+"""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+from app_live_tests import state
+from app_live_tests.harness import hap
+
+STATE_PATH = Path(__file__).resolve().parent / "state" / "feedback_scenario.json"
+
+PREFIX = "FB-"
+TEMPLATE_GROUP = "FB-模板组"
+TARGET_GROUP = "FB-目标组"
+HELPER_GROUP = "FB-辅助组"
+
+# The twelve columns every document table in the report carries, plus the
+# title. Kept here as data so later work can rebuild or compare against
+# them without re-reading the report.
+STANDARD_FIELDS = [
+    {"type": "TEXT", "name": "名称", "required": True},
+    {"type": "DROP_DOWN", "name": "单据状态",
+     "options": ["草稿", "已提交", "已完成"]},
+    {"type": "DROP_DOWN", "name": "审核状态",
+     "options": ["待审核", "通过", "驳回"]},
+    {"type": "DATE", "name": "业务日期"},
+    {"type": "USER_PICKER", "name": "经手人"},
+    {"type": "DEPARTMENT", "name": "业务部门"},
+    {"type": "USER_PICKER", "name": "部门负责人"},
+    {"type": "USER_PICKER", "name": "待审核人"},
+    {"type": "USER_PICKER", "name": "已审核人"},
+    {"type": "TEXT", "name": "审核意见"},
+    {"type": "AUTO_ID", "name": "流水号"},
+    {"type": "TEXT", "name": "备注"},
+    {"type": "ATTACHMENT", "name": "附件"},
+]
+
+DETAIL_FIELDS = [
+    {"type": "TEXT", "name": "明细名称", "required": True},
+    {"type": "NUMBER", "name": "数量"},
+    {"type": "MONEY", "name": "单价"},
+    {"type": "TEXT", "name": "明细备注"},
+]
+
+TEMPLATE_SHEETS = ["FB-单据A-模板", "FB-单据B-模板", "FB-单据C-模板"]
+TARGET_SHEETS = ["FB-单据A-目标", "FB-单据B-目标", "FB-单据C-目标"]
+DETAIL_SHEET = "FB-明细-隐藏"
+
+
+def _load() -> dict:
+    if STATE_PATH.exists():
+        return json.loads(STATE_PATH.read_text(encoding="utf-8"))
+    return {}
+
+
+def _save(data: dict) -> None:
+    STATE_PATH.parent.mkdir(parents=True, exist_ok=True)
+    STATE_PATH.write_text(
+        json.dumps(data, ensure_ascii=False, indent=1) + "\n", encoding="utf-8")
+
+
+def _app_tree(app_id: str) -> dict:
+    detail = hap(["app", "info", "-a", app_id], check=False)
+    return detail.get("data", detail) if isinstance(detail, dict) else {}
+
+
+def _child_sections(app_id: str) -> dict[str, str]:
+    """Name → id for every second-level group under the app's root."""
+    out: dict[str, str] = {}
+    for sec in _app_tree(app_id).get("sections") or []:
+        for child in sec.get("childSections") or []:
+            if child.get("name"):
+                out[child["name"]] = child.get("id") or ""
+    return out
+
+
+def _items(app_id: str) -> dict[str, str]:
+    """Name → id for every worksheet anywhere in the app, groups included."""
+    out: dict[str, str] = {}
+
+    def walk(sections):
+        for sec in sections or []:
+            for item in sec.get("items") or []:
+                if item.get("type", 0) == 0 and item.get("name"):
+                    out[item["name"]] = item.get("id") or ""
+            walk(sec.get("childSections"))
+
+    walk(_app_tree(app_id).get("sections"))
+    return out
+
+
+def _fields(ws_id: str) -> list[dict]:
+    data = hap(["worksheet", "fields", ws_id, "--raw"], check=False)
+    return data if isinstance(data, list) else []
+
+
+def _by_name(ws_id: str, name: str) -> str:
+    for c in _fields(ws_id):
+        if c.get("controlName") == name:
+            return c.get("controlId") or ""
+    return ""
+
+
+def _ensure_section(app_id: str, root_id: str, name: str) -> str:
+    have = _child_sections(app_id)
+    if name in have:
+        return have[name]
+    made = hap(["app", "add-section", app_id, "-n", name,
+                "--parent-id", root_id], check=False)
+    return made if isinstance(made, str) else ""
+
+
+def build(show_only: bool = False) -> dict:
+    app_id, org_id = state.ensure_app()
+    root_id = state.first_section_id(app_id)
+    data = _load()
+    data.update({"app_id": app_id, "org_id": org_id, "root_section": root_id})
+    if show_only:
+        print(json.dumps(data, ensure_ascii=False, indent=1))
+        return data
+
+    # ── the three second-level groups ────────────────────────────────
+    sections = {}
+    for name in (TEMPLATE_GROUP, TARGET_GROUP, HELPER_GROUP):
+        sections[name] = _ensure_section(app_id, root_id, name)
+        print(f"  group {name}: {sections[name]}")
+    data["sections"] = sections
+
+    items = _items(app_id)
+
+    # ── the template table, then five copies of it ───────────────────
+    # Copies keep the source's controlIds — that is the product's own
+    # behaviour and the reason the report's author first suspected
+    # cross-sheet mis-references (report 3.10). The fixture keeps it.
+    template = TEMPLATE_SHEETS[0]
+    if template in items:
+        tpl_id = items[template]
+    else:
+        made = hap(["worksheet", "create", app_id, template,
+                    "--section-id", sections[TEMPLATE_GROUP]], check=False)
+        tpl_id = (made.get("workSheetId") or made.get("id")
+                  if isinstance(made, dict) else "") or ""
+        hap(["worksheet", "update-fields", tpl_id, "--title-name", "名称",
+             "--fields", json.dumps(STANDARD_FIELDS, ensure_ascii=False)],
+            check=False)
+    print(f"  template {template}: {tpl_id}")
+
+    sheets = {template: tpl_id}
+    plan = [(n, sections[TEMPLATE_GROUP]) for n in TEMPLATE_SHEETS[1:]]
+    plan += [(n, sections[TARGET_GROUP]) for n in TARGET_SHEETS]
+    for name, sec in plan:
+        if name in items:
+            sheets[name] = items[name]
+        else:
+            made = hap(["worksheet", "copy", tpl_id, name, "-a", app_id,
+                        "--section-id", sec], check=False)
+            sheets[name] = made if isinstance(made, str) else ""
+        print(f"  sheet {name}: {sheets[name]}")
+
+    # ── the hidden detail sheet, mounted as a sub-table ──────────────
+    if DETAIL_SHEET in items:
+        detail_id = items[DETAIL_SHEET]
+    else:
+        made = hap(["worksheet", "create", app_id, DETAIL_SHEET,
+                    "--section-id", sections[HELPER_GROUP]], check=False)
+        detail_id = (made.get("workSheetId") or made.get("id")
+                     if isinstance(made, dict) else "") or ""
+        hap(["worksheet", "update-fields", detail_id,
+             "--title-name", "明细名称",
+             "--fields", json.dumps(DETAIL_FIELDS, ensure_ascii=False)],
+            check=False)
+        hap(["worksheet", "mount-subtable", tpl_id, detail_id,
+             "--name", "明细子表", "-a", app_id], check=False)
+        hap(["worksheet", "update", detail_id, "-a", app_id,
+             "--visibility", "hidden"], check=False)
+    sheets[DETAIL_SHEET] = detail_id
+    print(f"  detail {DETAIL_SHEET}: {detail_id} (hidden)")
+
+    data["sheets"] = sheets
+    data["fields"] = {
+        name: {c.get("controlName"): c.get("controlId")
+               for c in _fields(wid) if c.get("controlName")}
+        for name, wid in sheets.items()
+    }
+    _save(data)
+    print(f"\nwrote {STATE_PATH}")
+    return data
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    build(show_only="--show" in argv)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())