Skip to content

Commit 1ea3fe9

Browse files
fix(spec): approval node field help opens in business words (#28233)
<!-- claude-projects-attribution: {"github_login":"os-tesla"} --> _Requested by **Tesla** · [project thread](https://claude.ai/code/project/chan_01AXsQkLFKRdQCqQ3RTr6Jao?thread=cmsg_01AXsQkLFKRdQCqQ3RTr6JaoDRgRqEPbxpERstAz6UbjtK)_ Fixes #27838 Clause-②: no Metadata-protocol: none ## 维护者速读 - 改了什么:审批节点在 Studio 流程检查器里显示的字段说明全部改写为业务语言,每条第一句讲这个设置对审批请求起什么作用;“排除提交人”和审批人“组织”两条不再以 ADR 编号、库表字段名或枚举值开头,工程细节移到代码注释(JSDoc)。 - 为什么改:Studio 把这些说明直接当作字段帮助显示,只露两行,超长折叠到“了解更多”;旧文案写给工程师,管理员看了不知道该怎么选。 - 风险与回滚:只改说明文字,配置键、类型、默认值、可接受值都不变,旧的审批流程照常解析;回滚即 revert 本 PR。 - 先看:packages/spec/src/automation/approval.zod.ts(excludeSubmitter、organization、onEmptyApprovers 三处 describe)、packages/spec/src/automation/approval-describe-business-words-27838.test.ts、content/docs/references/automation/approval.mdx(重新生成)。 - 两分钟验证:`pnpm --filter @objectstack/spec exec vitest run src/automation/approval-describe-business-words-27838.test.ts`,预期 7 个用例全绿;或在 Studio 打开审批节点,看“Exclude Submitter”下的提示第一句是“Stops people approving their own requests”。 - 需要你做的:无,席位落地。 ## What changes The Studio flow inspector renders the approval node's property form from the engine-published JSON schema (`getApprovalNodeConfigJsonSchema`), and each property's `description` is the help line under the field, clamped to two lines behind "Learn more" (`FLOW_HELP_CLAMP_CHARS = 120`). Several of those descriptions opened with engineer detail: `excludeSubmitter` named `submitter_id`, `onEmptyApprovers`, `admin_rescue`, `fallbackApprovers` and quoted enum values; the approver `organization` opened with "ADR-0105 D9" and the `$root` / `$parent` tokens. - `packages/spec/src/automation/approval.zod.ts`: every `.describe()` / `.meta({ description })` in the file now opens with one sentence in business words: what the setting does to the request, with no decision id, storage column, key or enum literal. The key or literal an author has to write (the `onEmptyApprovers` policy names, `$root` / `$parent`, the `escalateTo` address forms, the CEL roots) follows the first sentence, and the engineer detail moved to the JSDoc. Swept: the approver type, value, resolveAs, group and organization; the decision-output key, type, multiple and required; the escalation enabled, timeoutHours, action, escalateTo and notifySubmitter; the node's approvers, excludeSubmitter, behavior, minApprovals, lockRecord, approvalStatusField, onEmptyApprovers, fallbackApprovers, decisionOutputs, escalation and maxRevisions. Refusal messages (`strictObject` history/guidance, the pairing and escalation-target refusals) are not field help and are unchanged. - `content/docs/references/automation/approval.mdx`: regenerated (`check:generated --fix`, which named `check:docs` as the only stale artifact). - Measured: the describes feed no translation bundle (`git grep` of the old strings hits only the reference page and `ui/` tests that carry their own fixtures), so no bundle is regenerated. - No key, type, default or accepted value changed: `check:authorable-surface` and `check:api-surface` are green on the built `dist`. ## Tests - New `approval-describe-business-words-27838.test.ts`: walks every `description` in the published JSON schema (nested approver, escalation and decision-output shapes included, with path controls so a walk that stops at the top level reds) and asserts no first sentence carries a decision id, a backtick, a quoted enum literal, a snake_case or camelCase identifier, or an organization symbol. The prose itself is not pinned. - `approval-exclude-submitter-25609.test.ts` §5: the pins that required `submitter_id` in the describe and the "Segregation of duties" opening now assert the first sentence names no key, column or policy literal, that `onEmptyApprovers` and `'auto_approve'` are still named, and that `submitter_id` stays in the JSDoc. - Existing pins kept unchanged and green: `ApproverType.describe()` still routes to `approval-approvers-may-resolve-empty` and names `onEmptyApprovers`; `minApprovals` still states the per-behavior default; `onEmptyApprovers` still names `fallbackApprovers` and `'fallback'`. ## Acceptance notes - **Part 2 is out of scope here** (outside `domain:spec`): the node descriptor descriptions in `packages/services/service-automation/src/builtin/http-nodes.ts` and `packages/plugins/plugin-approvals/src/approval-node.ts`. The exact strings and proposed business wording are in the os-dev report for the seat's follow-up card. - `ui/packages/app-shell/src/views/metadata-admin/inspectors/FlowNodeInspector.escalationOff-11660.test.tsx` quotes the old `enabled` describe in its header comment as "the governing text". Its meaning is kept (the engineer reading now sits in a comment above `enabled` in `approval.zod.ts`), but the quotation is stale; it is a `ui/` comment, so it is left for a `ui/` touch. - The Studio static fallback form (`flow-node-config.ts`) carries its own hand-written help strings for the approval node; it is only used when the engine publishes no `configSchema`, and it is a `ui/` file. ## Verification All readings at head `fc57c565` on objectstack-ai/objectstack (merge base `3a2f4c00`; `origin/main` has since moved by 3 commits that touch no file in this diff). <details><summary>Tests</summary> - `pnpm --filter @objectstack/spec test`: Test Files 758/758, Tests 22559 passed, 1 todo; lock VERDICT command-exit 0. - `pnpm --filter @objectstack/spec typecheck`: lock VERDICT command-exit 0. - Reverse verification: the committed fix in place, `approval.zod.ts` restored from `3a2f4c00` (on-disk count of the old "ADR-0105 D9 — organization" opening = 1), the two describe test files red 8 failed / 36 (all six first-sentence shapes plus the two new §5 pins); restored with `git checkout HEAD --`, `git diff HEAD` empty. </details> <details><summary>Gates</summary> - `dispatch-gates --commands` at `fc57c565`: 103 families, each run with stdin from `/dev/null`, exit codes recorded before any pipe. `--ran`: 103 derived, 103 run, 0 NOT MEASURED, 0 unrun, 0 red. - Seven families first answered exit 3 (prerequisite not met: unbuilt `lint` / `formula` / `client` / `objectql` dist, the full workspace dist for `check:dual-build-cjs-loads`, and a shallow clone for `check-plugin-teardown-shape --self-test`). Re-run after a workspace build (`turbo run build`, 116/116 tasks, lock VERDICT command-exit 0) and `git fetch --unshallow`, all exit 0. - `pnpm --filter @objectstack/spec check:generated`: after `--fix`, every artifact up to date. - The full CI farm (`test:repo`, the UI lanes) is CI's. </details> --- _Generated by [Claude Code](https://claude.ai/code/session_01L9qibyR1YFTVfiVFt8svQ3)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent a426d36 commit 1ea3fe9

5 files changed

Lines changed: 238 additions & 97 deletions

File tree

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
'@objectstack/spec': patch
3+
---
4+
5+
Clause-②: no
6+
Metadata-protocol: none
7+
8+
The approval node's field help now opens in business words. Every `.describe()` on the approval
9+
node config (approvers, the approver row, escalation and decision outputs) is the help line the
10+
Studio flow inspector shows under the field, and several opened with a decision id, a storage
11+
column or an enum literal — `excludeSubmitter` named `submitter_id` and the empty-slate policy
12+
values, and the approver `organization` opened with a decision id and the `$root` / `$parent`
13+
tokens. Each first sentence now says what the setting does to the request; the key or literal an
14+
author has to write follows it, and the engineer detail moved to the JSDoc. No key, type, default
15+
or accepted value changed.

0 commit comments

Comments
 (0)