Repository navigation
Commit 1ea3fe9
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
- .changeset
- content/docs/references/automation
- packages/spec/src/automation
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
0 commit comments