From ce4112b7b3ca3c5d1a4a8dd21f3ca26e321aefd4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=8C=85=E5=91=A8=E6=B6=9B?= <baozhoutao@hotoa.com>
Date: Wed, 29 Jul 2026 05:11:09 -0700
Subject: [PATCH 1/2] fix(approvals): decision outputs reach both decision
 surfaces (#2955)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

An approval node's `decisionOutputs` (framework#3447 P2) never made it to the
approver on either Console surface, though the server has shipped the typed
declaration on the request row all along.

The Approval Center DID synthesize a typed picker per declared output
(#2831), but spelled the picker target `referenceTo`. Every collected param
passes through `resolveActionParams()` first, and its inline branch rebuilds
the param from a fixed key list, reading the target from `reference` — so the
target was dropped and `paramToField()` degraded the targetless picker to a
plain text input labelled "<label> 的记录 ID". `user` outputs were unaffected
(that widget needs no target); `department`/`position`/`team` were all broken.

The record header collected nothing at all: its Approve/Reject shipped their
inputs under `collectParams`, a key nothing reads (ActionRunner collects from
`actionParams`). No dialog had opened there since ADR-0019 — the comment was
silently dropped on every record-page decision, and a node declaring
`decisionOutputs` resumed the flow with `vars.<node>.<key>` missing, so the
next node's `expression` approver faulted or fell through to
`onEmptyApprovers` with no hint to anyone.

The widget mapping now lives in `utils/decisionOutputParams` so the two
surfaces cannot drift again; the header collects through `actionParams`, folds
`outputs.<key>` into the decide body, and its comment box is a real textarea
(the resolver drops `multiline`). Tests pin the round trip through param
resolution — the stage that actually broke — not just the emitted shape.

Verified end to end against the app-showcase runtime: an approval node
declaring a `position`-typed multi-select renders a sys_position picker in
both the Approval Center drawer and the record header, and deciding from the
record page carries the outputs through to `vars.*` — the co-sign node's
`expression` approver resolved to the user picked in the dialog.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 ...on-outputs-reach-both-decision-surfaces.md |  47 +++++
 ...seRecordApprovals.decisionOutputs.test.tsx | 106 +++++++++++
 .../app-shell/src/hooks/useRecordApprovals.ts |  39 ++++-
 .../src/utils/decisionOutputParams.test.ts    | 165 ++++++++++++++++++
 .../src/utils/decisionOutputParams.ts         | 159 +++++++++++++++++
 .../src/views/DeclaredActionsBar.tsx          |  52 ++----
 ...etailView.approvalDecisionActions.test.tsx | 110 ++++++++++++
 .../app-shell/src/views/RecordDetailView.tsx  | 131 +++++++++-----
 .../__tests__/DeclaredActionsBar.test.tsx     |  43 +++++
 9 files changed, 761 insertions(+), 91 deletions(-)
 create mode 100644 .changeset/decision-outputs-reach-both-decision-surfaces.md
 create mode 100644 packages/app-shell/src/hooks/useRecordApprovals.decisionOutputs.test.tsx
 create mode 100644 packages/app-shell/src/utils/decisionOutputParams.test.ts
 create mode 100644 packages/app-shell/src/utils/decisionOutputParams.ts
 create mode 100644 packages/app-shell/src/views/RecordDetailView.approvalDecisionActions.test.tsx

diff --git a/.changeset/decision-outputs-reach-both-decision-surfaces.md b/.changeset/decision-outputs-reach-both-decision-surfaces.md
new file mode 100644
index 0000000000..3fb19a21aa
--- /dev/null
+++ b/.changeset/decision-outputs-reach-both-decision-surfaces.md
@@ -0,0 +1,47 @@
+---
+"@object-ui/app-shell": minor
+---
+
+fix(approvals): decision outputs reach both decision surfaces (objectui#2955, framework#3447 P2)
+
+An approval node can ask the approver for structured data with their decision
+(`decisionOutputs`) — typically to route the next node's approvers, which the
+flow then reads as `vars.<nodeId>.<key>`. The server has shipped this since
+framework#3447 P2 and surfaces the typed declaration on the request row
+(`decision_output_defs`), but neither Console decision surface actually
+delivered it.
+
+**The Approval Center asked for a record id instead of showing a picker.** The
+typed pickers landed in objectui#2831 and the drawer really did synthesize a
+`lookup` param per declared output — but it spelled the picker target
+`referenceTo`, and `resolveActionParams()` (which every collected param passes
+through before the dialog renders it) rebuilds an inline param from a fixed key
+list, reading the target from `reference`. The target was dropped there, and
+`paramToField()` degrades a targetless picker to a plain text input — so a
+`position` output rendered as a box labelled "<label> 的记录 ID". The approver
+had to go find the record id somewhere else and paste it back. `user`-typed
+outputs were unaffected (that widget needs no target), which is why this
+survived: `department` / `position` / `team` were the broken three.
+
+**The record header decided without collecting anything at all.** Approve /
+Reject on the detail page shipped their inputs under `collectParams` — a key
+nothing in the codebase reads (`ActionRunner` collects from `actionParams`).
+No dialog had opened on that surface since the ADR-0019 rework: the approver's
+comment was silently dropped on every record-page decision, and a node
+declaring `decisionOutputs` got no inputs either, so the flow resumed with
+`vars.<node>.<key>` missing — the next node's `expression` approver then failed
+with `EXPRESSION_FAILED`, or fell through to `onEmptyApprovers`, with nothing
+surfaced to the approver or the flow author. The header now collects through
+`actionParams`, renders the node's declared outputs with the same pickers the
+Approval Center uses, and posts them under `outputs` on the decide call. The
+comment box works again as a side effect, and it is a real textarea (the param
+resolver drops `multiline`, so the intent has to ride the type).
+
+The widget mapping now lives in one place (`utils/decisionOutputParams`), so
+the two surfaces cannot drift apart again, and the round trip through param
+resolution — the stage that actually broke — is pinned by tests.
+
+Not fixed here: `DecisionOutputDef` has no `required`, so a flow author still
+cannot demand that an approver fill an output before approving. That needs the
+spec-side field first (framework), and `onEmptyApprovers` remains the only
+backstop until then.
diff --git a/packages/app-shell/src/hooks/useRecordApprovals.decisionOutputs.test.tsx b/packages/app-shell/src/hooks/useRecordApprovals.decisionOutputs.test.tsx
new file mode 100644
index 0000000000..d06a9b4573
--- /dev/null
+++ b/packages/app-shell/src/hooks/useRecordApprovals.decisionOutputs.test.tsx
@@ -0,0 +1,106 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * What the record header actually POSTs when an approver decides
+ * (objectui#2955).
+ *
+ * The hook used to send `{ actorId, comment }` and nothing else, so an approval
+ * node that declared `decisionOutputs` lost them on this surface: the flow
+ * resumed with `vars.<node>.<key>` missing, and the next node's `expression`
+ * approver either faulted (`EXPRESSION_FAILED`) or fell through to
+ * `onEmptyApprovers`. Nothing surfaced to the approver.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { renderHook, waitFor, act } from '@testing-library/react';
+import { useRecordApprovals } from './useRecordApprovals';
+
+const PENDING = {
+  id: 'req_1',
+  process_name: 'flow:showcase_dynamic_approval',
+  object_name: 'showcase_announcement',
+  record_id: 'a1',
+  status: 'pending',
+  pending_approvers: ['user_1'],
+  decision_output_defs: [
+    { key: 'parallel_positions', label: '并行会审岗位', type: 'position', multiple: true },
+  ],
+};
+
+/** POST bodies captured per decide call. */
+let posts: Array<{ url: string; body: any }>;
+
+beforeEach(() => {
+  posts = [];
+  vi.stubGlobal(
+    'fetch',
+    vi.fn(async (url: string, init?: RequestInit) => {
+      if (init?.method === 'POST') {
+        posts.push({ url: String(url), body: JSON.parse(String(init.body)) });
+        return { ok: true, json: async () => ({ request: { ...PENDING, status: 'approved' } }) } as any;
+      }
+      return { ok: true, json: async () => ({ data: [PENDING] }) } as any;
+    }),
+  );
+});
+
+const mount = async () => {
+  const view = renderHook(() => useRecordApprovals('showcase_announcement', 'a1', 'user_1'));
+  await waitFor(() => expect(view.result.current.canDecide).toBe(true));
+  return view;
+};
+
+describe('useRecordApprovals — decision outputs in the decide body (objectui#2955)', () => {
+  it('posts the collected outputs under the nested `outputs` key', async () => {
+    const { result } = await mount();
+    await act(async () => {
+      await result.current.approve({
+        comment: 'ok',
+        outputs: { parallel_positions: ['pos_1', 'pos_2'] },
+      });
+    });
+    expect(posts).toHaveLength(1);
+    expect(posts[0].url).toContain('/approvals/requests/req_1/approve');
+    expect(posts[0].body).toEqual({
+      actorId: 'user_1',
+      comment: 'ok',
+      outputs: { parallel_positions: ['pos_1', 'pos_2'] },
+    });
+  });
+
+  it('rejects with outputs too — a send-back can route the next round as well', async () => {
+    const { result } = await mount();
+    await act(async () => {
+      await result.current.reject({ outputs: { parallel_positions: ['pos_1'] } });
+    });
+    expect(posts[0].url).toContain('/approvals/requests/req_1/reject');
+    expect(posts[0].body).toEqual({
+      actorId: 'user_1',
+      outputs: { parallel_positions: ['pos_1'] },
+    });
+  });
+
+  it('omits `outputs` entirely when the node declares none', async () => {
+    // The unchanged body for every approval without `decisionOutputs` — the
+    // service must not start seeing an empty object where nothing was sent.
+    const { result } = await mount();
+    await act(async () => {
+      await result.current.approve({ comment: 'ok', outputs: {} });
+    });
+    expect(posts[0].body).toEqual({ actorId: 'user_1', comment: 'ok' });
+    expect('outputs' in posts[0].body).toBe(false);
+  });
+
+  it('surfaces the node declaration so the header can build its pickers', async () => {
+    const { result } = await mount();
+    expect(result.current.pendingRequest?.decision_output_defs).toEqual(
+      PENDING.decision_output_defs,
+    );
+  });
+});
diff --git a/packages/app-shell/src/hooks/useRecordApprovals.ts b/packages/app-shell/src/hooks/useRecordApprovals.ts
index 51664e68c8..580ff8da3f 100644
--- a/packages/app-shell/src/hooks/useRecordApprovals.ts
+++ b/packages/app-shell/src/hooks/useRecordApprovals.ts
@@ -20,6 +20,7 @@
 
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { bearerAuthHeaders } from '../utils/authToken';
+import type { DecisionOutputDef } from '../utils/decisionOutputParams';
 
 export interface ApprovalRequestLite {
   id: string;
@@ -44,6 +45,19 @@ export interface ApprovalRequestLite {
    * have allowed. See {@link recordLockedByApproval}.
    */
   lock_record?: boolean;
+  /**
+   * Structured data THIS pending node asks the approver to submit with their
+   * decision (framework#3447 P2) — the flow reads it back as
+   * `vars.<nodeId>.<key>`, typically to route the next node's approvers.
+   *
+   * `decision_output_defs` carries the typed declaration (`type` /`multiple`),
+   * `decision_outputs` the bare key list a pre-typed backend sends; both are
+   * absent on a backend that predates the feature. The record header collects
+   * them exactly like the Approval Center does — a decision that silently
+   * skipped them left the next node reading a missing key (objectui#2955).
+   */
+  decision_outputs?: string[] | null;
+  decision_output_defs?: DecisionOutputDef[] | null;
 }
 
 /**
@@ -71,11 +85,20 @@ interface UseRecordApprovalsResult {
   latestRequest: ApprovalRequestLite | null;
   /** The current user is among the pending approvers and may record a decision. */
   canDecide: boolean;
-  approve: (input?: { comment?: string }) => Promise<ApprovalRequestLite | undefined>;
-  reject: (input?: { comment?: string }) => Promise<ApprovalRequestLite | undefined>;
+  approve: (input?: DecisionInput) => Promise<ApprovalRequestLite | undefined>;
+  reject: (input?: DecisionInput) => Promise<ApprovalRequestLite | undefined>;
   refresh: () => Promise<void>;
 }
 
+/**
+ * What an approver submits with a decision: the free-text comment, plus the
+ * node's declared decision outputs keyed by their declared `key` (objectui#2955).
+ */
+export interface DecisionInput {
+  comment?: string;
+  outputs?: Record<string, any>;
+}
+
 function apiBase() {
   const url = (import.meta as any).env?.VITE_SERVER_URL || '';
   return `${String(url).replace(/\/$/, '')}/api/v1`;
@@ -162,8 +185,9 @@ export function useRecordApprovals(
     && (pendingRequest.pending_approvers ?? []).includes(currentUserId);
 
   const decide = useCallback(
-    async (decision: 'approve' | 'reject', input?: { comment?: string }) => {
+    async (decision: 'approve' | 'reject', input?: DecisionInput) => {
       if (!pendingRequest) throw new Error('No pending request');
+      const outputs = input?.outputs && Object.keys(input.outputs).length > 0 ? input.outputs : undefined;
       const out = await fetchJson<{ request?: ApprovalRequestLite }>(
         `/approvals/requests/${encodeURIComponent(pendingRequest.id)}/${decision}`,
         {
@@ -171,6 +195,11 @@ export function useRecordApprovals(
           body: JSON.stringify({
             ...(currentUserId ? { actorId: currentUserId } : {}),
             ...(input?.comment ? { comment: input.comment } : {}),
+            // The node's declared decision outputs, under the same nested key
+            // the Approval Center's `type:'api'` decide actions post
+            // (objectui#2955). Omitted entirely when nothing was collected, so
+            // a node without `decisionOutputs` posts the body it always did.
+            ...(outputs ? { outputs } : {}),
           }),
         },
       );
@@ -180,8 +209,8 @@ export function useRecordApprovals(
     [pendingRequest, currentUserId, refresh],
   );
 
-  const approve = useCallback((input?: { comment?: string }) => decide('approve', input), [decide]);
-  const reject = useCallback((input?: { comment?: string }) => decide('reject', input), [decide]);
+  const approve = useCallback((input?: DecisionInput) => decide('approve', input), [decide]);
+  const reject = useCallback((input?: DecisionInput) => decide('reject', input), [decide]);
 
   return {
     loading,
diff --git a/packages/app-shell/src/utils/decisionOutputParams.test.ts b/packages/app-shell/src/utils/decisionOutputParams.test.ts
new file mode 100644
index 0000000000..fa46eb1cc3
--- /dev/null
+++ b/packages/app-shell/src/utils/decisionOutputParams.test.ts
@@ -0,0 +1,165 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Decision outputs — the params an approval node's `decisionOutputs`
+ * declaration becomes, and the round trip that decides whether the approver
+ * gets a picker or a box asking for a raw record id (objectui#2955).
+ *
+ * The bug these pin: the synthesized params were spelled `referenceTo`, but
+ * `resolveActionParams()` — which every decision surface runs them through
+ * before the dialog sees them — rebuilds an inline param from a fixed key list
+ * and reads the picker target from `reference`. The target was dropped there,
+ * `paramToField()` degraded the targetless picker to `text`, and the Approval
+ * Center rendered "<label> 的记录 ID" where a `sys_position` multi-select
+ * belonged. A unit test on the mapping ALONE cannot catch that (the emitted
+ * object looked right), so the round trip through both stages is the pin.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  decisionOutputDefs,
+  decisionOutputParams,
+  foldDecisionOutputs,
+} from './decisionOutputParams';
+import { resolveActionParams } from './resolveActionParams';
+import { paramToField } from './paramToField';
+
+const t = (key: string) => `t:${key}`;
+
+/** The full path a synthesized param takes before it reaches a widget. */
+const widgetFor = (param: Record<string, unknown>) => {
+  const [resolved] = resolveActionParams([param] as any, {
+    objectName: 'sys_approval_request',
+    objects: [],
+    fieldLabel: (_o: string, _f: string, d: string) => d,
+    fieldOptionLabel: (_o: string, _f: string, _v: any, d: string) => d,
+  } as any);
+  return paramToField(resolved);
+};
+
+describe('decisionOutputDefs', () => {
+  it('prefers the typed declarations', () => {
+    expect(
+      decisionOutputDefs({
+        decision_outputs: ['parallel_positions'],
+        decision_output_defs: [{ key: 'parallel_positions', type: 'position', multiple: true }],
+      }),
+    ).toEqual([{ key: 'parallel_positions', type: 'position', multiple: true }]);
+  });
+
+  it('falls back to the bare key list a pre-typed backend sends', () => {
+    expect(decisionOutputDefs({ decision_outputs: ['next_reviewers', 'note'] })).toEqual([
+      { key: 'next_reviewers' },
+      { key: 'note' },
+    ]);
+  });
+
+  it('reads nothing off a request without declared outputs', () => {
+    expect(decisionOutputDefs({ id: 'r1' })).toEqual([]);
+    expect(decisionOutputDefs(null)).toEqual([]);
+    expect(decisionOutputDefs({ decision_output_defs: [] })).toEqual([]);
+  });
+});
+
+describe('decisionOutputParams — declaration → param', () => {
+  it('names every param under the `outputs.` prefix the decide body folds on', () => {
+    const [param] = decisionOutputParams([{ key: 'parallel_positions', type: 'position' }], t);
+    expect(param.name).toBe('outputs.parallel_positions');
+  });
+
+  it('humanizes a label the backend did not send', () => {
+    const [param] = decisionOutputParams([{ key: 'next_reviewers' }], t);
+    expect(param.label).toBe('Next Reviewers');
+  });
+
+  it('keeps the declared label and multiplicity', () => {
+    const [param] = decisionOutputParams(
+      [{ key: 'parallel_positions', label: '并行会审岗位', type: 'position', multiple: true }],
+      t,
+    );
+    expect(param).toMatchObject({ label: '并行会审岗位', multiple: true });
+  });
+
+  it('localizes the help text (the literal IS what renders — #2762 P0-3)', () => {
+    const [typed] = decisionOutputParams([{ key: 'r', type: 'user' }], t);
+    const [free] = decisionOutputParams([{ key: 'note' }], t);
+    expect(typed.helpText).toBe('t:actions.decisionOutput.help');
+    expect(free.helpText).toBe('t:actions.decisionOutput.helpMultiValue');
+  });
+
+  it('declares no output as required — the flow author cannot demand one yet', () => {
+    // `DecisionOutputDef` carries no `required` flag (objectui#2955 follow-up);
+    // until it does, a hard-required picker would be unreachable metadata.
+    expect(decisionOutputParams([{ key: 'r', type: 'user' }], t)[0].required).toBe(false);
+  });
+});
+
+describe('decisionOutputParams — the params survive resolution (objectui#2955)', () => {
+  it.each([
+    ['department', 'sys_business_unit'],
+    ['position', 'sys_position'],
+    ['team', 'sys_team'],
+  ])('a %s output reaches the widget as a %s picker', (type, referenceTo) => {
+    const [param] = decisionOutputParams([{ key: 'k', type, multiple: true }], t);
+    // The spec spelling — `referenceTo` is dropped by the resolver.
+    expect(param).toMatchObject({ type: 'lookup', reference: referenceTo });
+    expect(param.referenceTo).toBeUndefined();
+    expect(widgetFor(param)).toMatchObject({
+      type: 'lookup',
+      reference_to: referenceTo,
+      multiple: true,
+    });
+  });
+
+  it('a user output reaches the widget as the user picker', () => {
+    const [param] = decisionOutputParams([{ key: 'next_reviewers', type: 'user', multiple: true }], t);
+    expect(widgetFor(param)).toMatchObject({ type: 'user', multiple: true });
+  });
+
+  it('an untyped output stays free text', () => {
+    const [param] = decisionOutputParams([{ key: 'note' }], t);
+    expect(widgetFor(param)).toMatchObject({ type: 'text' });
+  });
+
+  it('never degrades a typed picker to a record-id text box', () => {
+    // The #2955 symptom, stated as the invariant: no declared record kind may
+    // arrive at the widget as `text` (that is the "paste a UUID" fallback).
+    for (const type of ['user', 'department', 'position', 'team']) {
+      const [param] = decisionOutputParams([{ key: 'k', type }], t);
+      expect(widgetFor(param).type).not.toBe('text');
+    }
+  });
+});
+
+describe('foldDecisionOutputs', () => {
+  it('folds the dotted params into the nested decide body', () => {
+    expect(
+      foldDecisionOutputs({ comment: 'ok', 'outputs.parallel_positions': ['p1', 'p2'] }),
+    ).toEqual({ rest: { comment: 'ok' }, outputs: { parallel_positions: ['p1', 'p2'] } });
+  });
+
+  it('omits `outputs` entirely when nothing was collected', () => {
+    expect(foldDecisionOutputs({ comment: 'ok' })).toEqual({ rest: { comment: 'ok' } });
+    expect(foldDecisionOutputs(undefined)).toEqual({ rest: {} });
+  });
+
+  it('drops untouched optional outputs instead of writing blanks to `vars.*`', () => {
+    expect(
+      foldDecisionOutputs({ 'outputs.a': '', 'outputs.b': null, 'outputs.c': [], 'outputs.d': 'x' }),
+    ).toEqual({ rest: {}, outputs: { d: 'x' } });
+  });
+
+  it('leaves a literal `outputs` param and the prefix alone', () => {
+    // Only the dotted prefix folds — a param actually named `outputs.` (empty
+    // key) or `outputs` is not an output.
+    expect(foldDecisionOutputs({ outputs: 'literal', 'outputs.': 'x' })).toEqual({
+      rest: { outputs: 'literal', 'outputs.': 'x' },
+    });
+  });
+});
diff --git a/packages/app-shell/src/utils/decisionOutputParams.ts b/packages/app-shell/src/utils/decisionOutputParams.ts
new file mode 100644
index 0000000000..c9684a2dd3
--- /dev/null
+++ b/packages/app-shell/src/utils/decisionOutputParams.ts
@@ -0,0 +1,159 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * decisionOutputParams — the ONE place an approval node's declared decision
+ * outputs (framework#3447 P2) become action params.
+ *
+ * An approval node may declare `decisionOutputs: [{ key, label, type, multiple }]`;
+ * the approver fills them in while deciding and the flow reads them back as
+ * `vars.<nodeId>.<key>`. The key set is PER-REQUEST, so these can never be
+ * static action params — every decision surface has to synthesize them from the
+ * request row (`decision_output_defs`, or the bare `decision_outputs` key list
+ * from a pre-typed backend).
+ *
+ * Both decision surfaces — the Approval Center's declared approve/reject
+ * actions (`DeclaredActionsBar`) and the record header's Approve/Reject
+ * (`RecordDetailView`) — go through here, so a typed output renders the SAME
+ * picker in both places (objectui#2955).
+ *
+ * ## The `reference` key is load-bearing
+ *
+ * Params are handed to `resolveActionParams()` before the dialog sees them, and
+ * its inline branch REBUILDS the param from a fixed key list: the picker target
+ * is read from `reference` (the spec's `ActionParamSchema.reference` spelling)
+ * and re-emitted as `referenceTo`. A param that arrives already spelled
+ * `referenceTo` loses its target there, and `paramToField()` then degrades a
+ * targetless picker to a raw record-id text box — which is exactly how the
+ * Approval Center shipped "请填写记录 ID" text inputs where a `position` picker
+ * belonged (objectui#2955). Emit `reference`, never `referenceTo`.
+ */
+
+/** An approval node's declared decision output, as the server surfaces it. */
+export interface DecisionOutputDef {
+  key: string;
+  label?: string;
+  /** Record kind to pick (`user` / `department` / `position` / `team`); absent → free text. */
+  type?: string;
+  multiple?: boolean;
+}
+
+/** Param-name prefix the api handler folds back into the nested `outputs` body. */
+export const DECISION_OUTPUT_PARAM_PREFIX = 'outputs.';
+
+/**
+ * Record kinds that ride a `lookup` param pointed at a system object. `user`
+ * is absent on purpose — it has its own picker widget and needs no target.
+ */
+const OUTPUT_LOOKUP_OBJECTS: Record<string, string> = {
+  department: 'sys_business_unit',
+  position: 'sys_position',
+  team: 'sys_team',
+};
+
+/**
+ * Read the declared outputs off an approval request row. Prefers the typed
+ * declarations; falls back to the bare key list an older backend sends.
+ */
+export function decisionOutputDefs(record: unknown): DecisionOutputDef[] {
+  const row = record != null && typeof record === 'object' ? (record as Record<string, any>) : {};
+  const typed = row.decision_output_defs;
+  if (Array.isArray(typed) && typed.length > 0) {
+    return (typed as DecisionOutputDef[]).filter((d) => d && d.key);
+  }
+  const bare = row.decision_outputs;
+  if (Array.isArray(bare) && bare.length > 0) {
+    return bare.map((k) => ({ key: String(k) })).filter((d) => d.key);
+  }
+  return [];
+}
+
+/** Title-case a bare output key for the label a pre-typed backend didn't send. */
+function humanizeKey(key: string): string {
+  return key
+    .split(/[_-]+/)
+    .filter(Boolean)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(' ');
+}
+
+/**
+ * Build the action params that collect an approval's decision outputs.
+ *
+ * Params are named `outputs.<key>`; `useConsoleActionRuntime`'s api handler
+ * folds that dotted prefix back into the nested `outputs` object the decide
+ * route expects. `t` localizes the help text — these params are synthesized,
+ * so no `_actions.<action>.params.*` bundle entry can ever match them and the
+ * literal we pass IS what renders (objectui#2762 P0-3).
+ *
+ * Every output is optional: `DecisionOutputDef` carries no `required` flag, so
+ * a flow author cannot yet demand one (objectui#2955 follow-up) — an omitted
+ * output simply isn't sent.
+ */
+export function decisionOutputParams(
+  defs: DecisionOutputDef[],
+  t: (key: string) => string,
+): Array<Record<string, unknown>> {
+  return defs.filter((d) => d && d.key).map((d) => {
+    const base = {
+      name: `${DECISION_OUTPUT_PARAM_PREFIX}${d.key}`,
+      label: d.label ?? humanizeKey(d.key),
+      required: false,
+    };
+    if (d.type === 'user') {
+      return {
+        ...base,
+        type: 'user',
+        multiple: d.multiple === true,
+        helpText: t('actions.decisionOutput.help'),
+      };
+    }
+    const lookupObject = d.type ? OUTPUT_LOOKUP_OBJECTS[d.type] : undefined;
+    if (lookupObject) {
+      return {
+        ...base,
+        type: 'lookup',
+        // NOT `referenceTo` — see the module note above.
+        reference: lookupObject,
+        multiple: d.multiple === true,
+        helpText: t('actions.decisionOutput.help'),
+      };
+    }
+    return {
+      ...base,
+      type: 'text',
+      helpText: t('actions.decisionOutput.helpMultiValue'),
+    };
+  });
+}
+
+/**
+ * Split a collected param-values map into the decide body's `outputs` object
+ * and everything else. The Approval Center's decide actions are `type: 'api'`
+ * and get this folding from the shared api handler; the record header decides
+ * through `useRecordApprovals`, which posts the body itself — so it folds here.
+ *
+ * Blank values are dropped: an untouched optional output must not overwrite
+ * `vars.<node>.<key>` with an empty string.
+ */
+export function foldDecisionOutputs(
+  values: Record<string, any> | undefined,
+): { rest: Record<string, any>; outputs?: Record<string, any> } {
+  const rest: Record<string, any> = {};
+  let outputs: Record<string, any> | undefined;
+  for (const [k, v] of Object.entries(values ?? {})) {
+    if (k.startsWith(DECISION_OUTPUT_PARAM_PREFIX) && k.length > DECISION_OUTPUT_PARAM_PREFIX.length) {
+      if (v === undefined || v === null || v === '') continue;
+      if (Array.isArray(v) && v.length === 0) continue;
+      (outputs ??= {})[k.slice(DECISION_OUTPUT_PARAM_PREFIX.length)] = v;
+      continue;
+    }
+    rest[k] = v;
+  }
+  return outputs ? { rest, outputs } : { rest };
+}
diff --git a/packages/app-shell/src/views/DeclaredActionsBar.tsx b/packages/app-shell/src/views/DeclaredActionsBar.tsx
index a8cc08eec9..15ba47c2b7 100644
--- a/packages/app-shell/src/views/DeclaredActionsBar.tsx
+++ b/packages/app-shell/src/views/DeclaredActionsBar.tsx
@@ -44,6 +44,7 @@ import { Loader2 } from 'lucide-react';
 import { useConsoleActionRuntime } from '../hooks/useConsoleActionRuntime';
 import { useAdapter } from '../providers/AdapterProvider';
 import { useMetadataItem } from '../providers/MetadataProvider';
+import { decisionOutputDefs, decisionOutputParams } from '../utils/decisionOutputParams';
 import { getIcon } from '../utils/getIcon';
 
 export interface DeclaredActionsBarProps {
@@ -138,50 +139,19 @@ const DeclaredActionButton: React.FC<{
       const { params: rawParams, ...rest } = action as ActionDef & { params?: unknown };
       // #3447: an approval decision may carry author-declared structured
       // outputs. The key set is PER-REQUEST (each approval node declares its
-      // own `decisionOutputs`, surfaced on the row as `decision_outputs`), so
-      // it cannot be a static action param — synthesize one text param per key
+      // own `decisionOutputs`, surfaced on the row as `decision_output_defs`),
+      // so it cannot be a static action param — synthesize one param per key
       // for the decide actions. Params are named `outputs.<key>`; the api
       // handler folds them into the nested `outputs` body the decide route
-      // expects. Comma-separated values are legal (the service accepts CSV for
-      // multi-id outputs).
+      // expects. A free-text output accepts comma-separated values (the
+      // service accepts CSV for multi-id outputs).
       const isDecideAction = /\/(approve|reject)$/.test(String((action as any).target ?? ''));
-      // Prefer the typed declarations (framework#3447 follow-up); fall back to
-      // the bare key list from an older backend.
-      const declaredOutputs: Array<{ key: string; label?: string; type?: string; multiple?: boolean }> =
-        isDecideAction && Array.isArray(recordData.decision_output_defs) && recordData.decision_output_defs.length
-          ? (recordData.decision_output_defs as Array<{ key: string; label?: string; type?: string; multiple?: boolean }>)
-          : isDecideAction && Array.isArray(recordData.decision_outputs)
-            ? (recordData.decision_outputs as unknown[]).map((k) => ({ key: String(k) }))
-            : [];
-      // Widget mapping: `user` has a dedicated sys_user picker widget; the
-      // other record kinds ride a lookup param pointed at the system object.
-      const OUTPUT_LOOKUP_OBJECTS: Record<string, string> = {
-        department: 'sys_business_unit',
-        position: 'sys_position',
-        team: 'sys_team',
-      };
-      const outputParams = declaredOutputs.filter((d) => d.key).map((d) => {
-        const label = d.label
-          ?? d.key.split(/[_-]+/).filter(Boolean).map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
-        const base = { name: `outputs.${d.key}`, label, required: false } as Record<string, unknown>;
-        if (d.type === 'user') {
-          return {
-            ...base, type: 'user', multiple: d.multiple === true,
-            helpText: t('actions.decisionOutput.help'),
-          };
-        }
-        const lookupObject = d.type ? OUTPUT_LOOKUP_OBJECTS[d.type] : undefined;
-        if (lookupObject) {
-          return {
-            ...base, type: 'lookup', referenceTo: lookupObject, multiple: d.multiple === true,
-            helpText: t('actions.decisionOutput.help'),
-          };
-        }
-        return {
-          ...base, type: 'text',
-          helpText: t('actions.decisionOutput.helpMultiValue'),
-        };
-      });
+      // Widget mapping (typed picker vs free text) lives in the shared helper,
+      // so the record header's Approve/Reject renders the same controls
+      // (objectui#2955).
+      const outputParams = isDecideAction
+        ? decisionOutputParams(decisionOutputDefs(recordData), t)
+        : [];
       const dispatch: any = {
         ...rest,
         // Localized copies ride the dispatch: the runner reads `label` for the
diff --git a/packages/app-shell/src/views/RecordDetailView.approvalDecisionActions.test.tsx b/packages/app-shell/src/views/RecordDetailView.approvalDecisionActions.test.tsx
new file mode 100644
index 0000000000..9eaa37dd0c
--- /dev/null
+++ b/packages/app-shell/src/views/RecordDetailView.approvalDecisionActions.test.tsx
@@ -0,0 +1,110 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * The record header's Approve / Reject param contract (objectui#2955).
+ *
+ * Two things were broken on this surface and both are invisible from the
+ * outside — the buttons rendered and the decision went through:
+ *
+ *  1. the collected inputs shipped under `collectParams`, a key NOTHING in the
+ *     codebase reads (`ActionRunner` collects from `actionParams`, or `params`
+ *     when it is an array). No dialog ever opened, so the approver's comment
+ *     was dropped on every record-page decision — dead since ADR-0019;
+ *  2. a node declaring `decisionOutputs` got no inputs at all here, so the
+ *     decision resumed the flow with `vars.<node>.<key>` missing and the next
+ *     node's `expression` approver failed or fell through to `onEmptyApprovers`
+ *     — with no hint to the approver that anything was skipped.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { buildApprovalDecisionActions } from './RecordDetailView';
+
+/** Object-translation stub: echoes the key, honouring `defaultValue`. */
+const t = (key: string, opts?: any) => (opts?.defaultValue ?? `t:${key}`) as string;
+
+const pending = (over: Record<string, any> = {}) => ({
+  id: 'req_1',
+  status: 'pending',
+  ...over,
+});
+
+const byName = (actions: any[]) => Object.fromEntries(actions.map((a) => [a.name, a]));
+
+describe('buildApprovalDecisionActions — param key (objectui#2955)', () => {
+  it('collects through `actionParams`, the key the runner reads', () => {
+    const actions = byName(buildApprovalDecisionActions(pending(), t) as any[]);
+    for (const name of ['approve_request', 'reject_request']) {
+      expect(Array.isArray(actions[name].actionParams)).toBe(true);
+      // The dead key must not come back — it is why no dialog ever opened.
+      expect(actions[name].collectParams).toBeUndefined();
+    }
+  });
+
+  it('always offers the comment box, as a long-form input', () => {
+    const [approve] = buildApprovalDecisionActions(pending(), t) as any[];
+    // `multiline` does not survive param resolution — the type has to carry it.
+    expect(approve.actionParams[0]).toMatchObject({ name: 'comment', type: 'textarea' });
+  });
+
+  it('keeps the decision buttons ahead of app header actions', () => {
+    const actions = byName(buildApprovalDecisionActions(pending(), t) as any[]);
+    expect(actions.approve_request.order).toBe(-100);
+    expect(actions.reject_request.order).toBe(-99);
+    expect(actions.reject_request.confirmText).toBeDefined();
+  });
+});
+
+describe('buildApprovalDecisionActions — decision outputs (objectui#2955)', () => {
+  it('adds one typed param per declared output', () => {
+    const actions = byName(
+      buildApprovalDecisionActions(
+        pending({
+          decision_outputs: ['parallel_positions'],
+          decision_output_defs: [
+            { key: 'parallel_positions', label: '并行会审岗位', type: 'position', multiple: true },
+          ],
+        }),
+        t,
+      ) as any[],
+    );
+    for (const name of ['approve_request', 'reject_request']) {
+      const params = actions[name].actionParams as any[];
+      expect(params.map((p) => p.name)).toEqual(['comment', 'outputs.parallel_positions']);
+      expect(params[1]).toMatchObject({
+        type: 'lookup',
+        // The spec spelling — `referenceTo` is dropped by `resolveActionParams`
+        // and the picker would degrade to a record-id text box.
+        reference: 'sys_position',
+        multiple: true,
+        label: '并行会审岗位',
+      });
+    }
+  });
+
+  it('collects nothing extra when the node declares no outputs', () => {
+    const [approve] = buildApprovalDecisionActions(pending(), t) as any[];
+    expect((approve.actionParams as any[]).map((p) => p.name)).toEqual(['comment']);
+  });
+
+  it('still collects from a backend that only sends the bare key list', () => {
+    const [approve] = buildApprovalDecisionActions(
+      pending({ decision_outputs: ['next_reviewers'] }),
+      t,
+    ) as any[];
+    expect((approve.actionParams as any[])[1]).toMatchObject({
+      name: 'outputs.next_reviewers',
+      type: 'text',
+    });
+  });
+
+  it('collects nothing extra when there is no pending request', () => {
+    const [approve] = buildApprovalDecisionActions(null, t) as any[];
+    expect((approve.actionParams as any[]).map((p) => p.name)).toEqual(['comment']);
+  });
+});
diff --git a/packages/app-shell/src/views/RecordDetailView.tsx b/packages/app-shell/src/views/RecordDetailView.tsx
index 4f21a44096..8ff942445b 100644
--- a/packages/app-shell/src/views/RecordDetailView.tsx
+++ b/packages/app-shell/src/views/RecordDetailView.tsx
@@ -33,6 +33,7 @@ import { RelatedRecordActionsBridge } from './RelatedRecordActionsBridge';
 import { withPageTabsUrlSync } from '../utils/pageTabsUrlSync';
 import { RECORD_DETAIL_TAB_PARAM, RECORD_TRAIL_PARAM, decodeRecordTrail, buildRecordTrailHref } from '../urlParams';
 import { resolveActionParams } from '../utils/resolveActionParams';
+import { decisionOutputDefs, decisionOutputParams, foldDecisionOutputs } from '../utils/decisionOutputParams';
 import { useRecordBreadcrumbTitle } from '../context/NavigationContext';
 import type { FeedItem } from '@object-ui/types';
 import type { ActionDef, ActionParamDef } from '@object-ui/core';
@@ -140,6 +141,79 @@ export function resolveRecordHeaderActionGates(
   return { edit: affordances.edit, delete: affordances.delete };
 }
 
+/**
+ * The record header's Approve / Reject actions for the pending request.
+ *
+ * Pure and exported so the param contract is testable without the detail
+ * render tree — that contract is where objectui#2955 bit:
+ *
+ *  • the collected inputs must ride **`actionParams`**, the key `ActionRunner`
+ *    reads (the header dispatches the action object verbatim). They shipped as
+ *    `collectParams`, which nothing in the codebase consumes, so no dialog ever
+ *    opened: the comment was silently dropped on every record-page decision,
+ *    and the node's declared decision outputs with it;
+ *  • a node that declares `decisionOutputs` contributes one `outputs.<key>`
+ *    param each, through the same helper the Approval Center uses — so the
+ *    approver gets the same typed picker on both surfaces instead of the
+ *    record page quietly deciding without them.
+ *
+ * `t` is the object-translation function; params are localized here because
+ * synthesized `outputs.<key>` names can never match an `_actions.*` bundle key.
+ */
+export function buildApprovalDecisionActions(
+  pendingRequest: unknown,
+  t: (key: string, opts?: any) => string,
+): ActionDef[] {
+  const commentParam = {
+    name: 'comment',
+    label: t('approvals.comment', { defaultValue: 'Comment (optional)' }),
+    // `textarea`, not `text` + `multiline`: the param resolver rebuilds inline
+    // params from a fixed key list and drops `multiline`, so the long-form
+    // intent has to ride the type.
+    type: 'textarea',
+  };
+  const decisionParams = [
+    commentParam,
+    ...decisionOutputParams(decisionOutputDefs(pendingRequest), (key: string) => t(key)),
+  ];
+  // A pending approval is THE decision the approver came to make, so the
+  // decision buttons must outrank app `record_header` actions rather than being
+  // appended after them (and buried in overflow). A strongly negative `order`
+  // floats them into the primary slot; the action:bar stable-sorts by `order`,
+  // so app actions keep their relative order just after the decision. Approve
+  // gets the highlighted `primary` variant; Reject stays `destructive`.
+  // (#2670 / objectui#2339)
+  return [
+    {
+      name: 'approve_request',
+      type: 'approval',
+      target: 'approve_request',
+      label: t('approvals.approve', { defaultValue: 'Approve' }),
+      icon: 'check',
+      variant: 'primary',
+      order: -100,
+      locations: ['record_header'],
+      refreshAfter: true,
+      actionParams: decisionParams,
+      successMessage: t('approvals.approveSuccess', { defaultValue: 'Approved' }),
+    },
+    {
+      name: 'reject_request',
+      type: 'approval',
+      target: 'reject_request',
+      label: t('approvals.reject', { defaultValue: 'Reject' }),
+      icon: 'x',
+      variant: 'destructive',
+      order: -99,
+      locations: ['record_header'],
+      refreshAfter: true,
+      confirmText: t('approvals.rejectConfirm', { defaultValue: 'Reject this approval request?' }),
+      actionParams: decisionParams,
+      successMessage: t('approvals.rejectSuccess', { defaultValue: 'Rejected' }),
+    },
+  ] as unknown as ActionDef[];
+}
+
 export function RecordDetailView({ dataSource, objects, onEdit, objectNameOverride, recordIdOverride, embedded }: RecordDetailViewProps) {
 
   const params = useParams<{
@@ -900,11 +974,15 @@ export function RecordDetailView({ dataSource, objects, onEdit, objectNameOverri
     const params = (action.params && !Array.isArray(action.params))
       ? (action.params as Record<string, any>)
       : {};
+    // The node's declared decision outputs arrive as `outputs.<key>` params
+    // (objectui#2955) — fold them back into the nested object the decide route
+    // expects, exactly like the Approval Center's api handler does.
+    const { outputs } = foldDecisionOutputs(params);
     try {
       if (target === 'approve_request') {
-        await approvalsRef.current.approve({ comment: params.comment });
+        await approvalsRef.current.approve({ comment: params.comment, outputs });
       } else if (target === 'reject_request') {
-        await approvalsRef.current.reject({ comment: params.comment });
+        await approvalsRef.current.reject({ comment: params.comment, outputs });
       } else {
         return { success: false, error: `Unknown approval target: ${target}` };
       }
@@ -1634,48 +1712,7 @@ export function RecordDetailView({ dataSource, objects, onEdit, objectNameOverri
       // node, so there is no manual submit/recall; an approver records a
       // decision that resumes the flow down its approve/reject edge).
       if (approvals.available && approvals.canDecide) {
-        const commentParam = {
-          name: 'comment',
-          label: t('approvals.comment', { defaultValue: 'Comment (optional)' }),
-          type: 'text',
-          multiline: true,
-        };
-        // A pending approval is THE decision the approver came to make, so the
-        // decision buttons must outrank app `record_header` actions rather than
-        // being appended after them (and buried in overflow). A strongly
-        // negative `order` floats them into the primary slot; the action:bar
-        // stable-sorts by `order`, so app actions keep their relative order
-        // just after the decision. Approve gets the highlighted `primary`
-        // variant; Reject stays `destructive`. (#2670 / objectui#2339)
-        base.push({
-          name: 'approve_request',
-          type: 'approval',
-          target: 'approve_request',
-          label: t('approvals.approve', { defaultValue: 'Approve' }),
-          icon: 'check',
-          variant: 'primary',
-          order: -100,
-          locations: ['record_header'],
-          refreshAfter: true,
-          collectParams: [commentParam],
-          successMessage: t('approvals.approveSuccess', { defaultValue: 'Approved' }),
-        });
-        base.push({
-          name: 'reject_request',
-          type: 'approval',
-          target: 'reject_request',
-          label: t('approvals.reject', { defaultValue: 'Reject' }),
-          icon: 'x',
-          variant: 'destructive',
-          order: -99,
-          locations: ['record_header'],
-          refreshAfter: true,
-          confirmText: t('approvals.rejectConfirm', {
-            defaultValue: 'Reject this approval request?',
-          }),
-          collectParams: [commentParam],
-          successMessage: t('approvals.rejectSuccess', { defaultValue: 'Rejected' }),
-        });
+        base.push(...buildApprovalDecisionActions(approvals.pendingRequest, t));
       }
 
       return base;
@@ -1744,7 +1781,11 @@ export function RecordDetailView({ dataSource, objects, onEdit, objectNameOverri
       }),
     };
   // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [objectDef?.name, childRelations, t, objectLabel, objects, historyEnabled, historyEntries, historyLoading, approvals.available, approvals.canDecide]);
+  // `approvals.pendingRequest` is in the deps for its `decision_output_defs`:
+  // the header's decision params are synthesized from the pending node's
+  // declaration, so they must be rebuilt when the request (and therefore the
+  // node) changes (objectui#2955).
+  }, [objectDef?.name, childRelations, t, objectLabel, objects, historyEnabled, historyEntries, historyLoading, approvals.available, approvals.canDecide, approvals.pendingRequest]);
 
   if (isLoading) {
     return <SkeletonDetail />;
diff --git a/packages/app-shell/src/views/__tests__/DeclaredActionsBar.test.tsx b/packages/app-shell/src/views/__tests__/DeclaredActionsBar.test.tsx
index 075f1ba44c..ea1ce5a432 100644
--- a/packages/app-shell/src/views/__tests__/DeclaredActionsBar.test.tsx
+++ b/packages/app-shell/src/views/__tests__/DeclaredActionsBar.test.tsx
@@ -269,6 +269,49 @@ describe('DeclaredActionsBar chrome localization (objectui#2762)', () => {
     expect(screen.getByRole('toolbar')).toHaveAttribute('aria-label', '决策');
   });
 
+  it('hands the picker target under `reference`, the key that survives resolution', async () => {
+    // objectui#2955: the params are spelled for `resolveActionParams`, which
+    // rebuilds an inline param from a fixed key list and reads the target from
+    // `reference`. Spelled `referenceTo` the target was dropped, and the
+    // Approval Center rendered a "paste a record id" text box where a
+    // sys_position multi-select belonged. The full round trip is pinned in
+    // `utils/decisionOutputParams.test.ts`; this pins what the BAR emits.
+    const decideAction = {
+      name: 'approval_approve',
+      type: 'api',
+      label: 'Approve',
+      target: '/api/v1/approvals/requests/{id}/approve',
+      locations: ['record_section'],
+    };
+    render(
+      <DeclaredActionsBar
+        objectName="sys_approval_request"
+        record={{
+          ...REQUEST,
+          decision_output_defs: [
+            { key: 'parallel_positions', label: '并行会审岗位', type: 'position', multiple: true },
+          ],
+        }}
+        location="record_section"
+        actions={[decideAction] as any}
+      />,
+    );
+
+    fireEvent.click(screen.getByText('Approve'));
+    await waitFor(() => expect(executeSpy).toHaveBeenCalled());
+
+    const params = executeSpy.mock.calls[0][0].actionParams as Array<Record<string, unknown>>;
+    expect(params).toHaveLength(1);
+    expect(params[0]).toMatchObject({
+      name: 'outputs.parallel_positions',
+      label: '并行会审岗位',
+      type: 'lookup',
+      reference: 'sys_position',
+      multiple: true,
+    });
+    expect(params[0].referenceTo).toBeUndefined();
+  });
+
   it('localizes the decision-output help text', async () => {
     const decideAction = {
       name: 'approval_approve',

From 3a6ec4fcc2ab650a8f683612803904da58017ea3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=8C=85=E5=91=A8=E6=B6=9B?= <baozhoutao@hotoa.com>
Date: Wed, 29 Jul 2026 06:21:14 -0700
Subject: [PATCH 2/2] feat(approvals): block a decision on a required output
 (#2955)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The platform half of this issue gives `decisionOutputs` a `required` flag: the
server rejects an approve that carries no value for one, before any write, so
the run can never resume past the node with the key a downstream `expression`
approver reads still missing.

The console mirrors it where the approver actually is. A required output is
marked required on the param it synthesizes, so the dialog flags the empty
field and refuses Confirm instead of sending a decision the server will 400.
APPROVE only, matching the server: a reject leaves down the reject edge where
nothing reads the outputs, so the reject dialog offers the same fields without
blocking on them — the two dialogs now differ in exactly that flag. Both
decision surfaces get it from the one shared helper, and a backend that
predates the field requires nothing, which is the behaviour of the previous
commit unchanged.

Verified against the showcase runtime (its dynamic-approval flow declares the
flag): the record header's Approve refuses with "Next Reviewers 为必填项" and
sends no request, its Reject offers the field unmarked, the Approval Center
drawer agrees on both, and a filled approve routes the co-sign node to the
picked user.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 ...on-outputs-reach-both-decision-surfaces.md | 14 +++++--
 .../src/utils/decisionOutputParams.test.ts    | 39 +++++++++++++++++--
 .../src/utils/decisionOutputParams.ts         | 19 +++++++--
 .../src/views/DeclaredActionsBar.tsx          | 13 +++++--
 ...etailView.approvalDecisionActions.test.tsx | 19 +++++++++
 .../app-shell/src/views/RecordDetailView.tsx  | 12 ++++--
 .../__tests__/DeclaredActionsBar.test.tsx     | 25 ++++++++++++
 7 files changed, 122 insertions(+), 19 deletions(-)

diff --git a/.changeset/decision-outputs-reach-both-decision-surfaces.md b/.changeset/decision-outputs-reach-both-decision-surfaces.md
index 3fb19a21aa..8a2a5c1e33 100644
--- a/.changeset/decision-outputs-reach-both-decision-surfaces.md
+++ b/.changeset/decision-outputs-reach-both-decision-surfaces.md
@@ -41,7 +41,13 @@ The widget mapping now lives in one place (`utils/decisionOutputParams`), so
 the two surfaces cannot drift apart again, and the round trip through param
 resolution — the stage that actually broke — is pinned by tests.
 
-Not fixed here: `DecisionOutputDef` has no `required`, so a flow author still
-cannot demand that an approver fill an output before approving. That needs the
-spec-side field first (framework), and `onEmptyApprovers` remains the only
-backstop until then.
+**And a `required` output is now enforced at the field.** The spec grew
+`decisionOutputs[].required` (the platform half of this issue, shipping in
+`@objectstack/spec` + `@objectstack/plugin-approvals`) — the server rejects an
+approve carrying no value for one, before any write. The dialog marks those params
+required, so the approver is stopped at the empty field with the Confirm button
+refusing rather than by a 400 after the round trip. Only on APPROVE: the server
+never requires them on a reject (the run leaves down the reject edge, where
+nothing reads the outputs), so the two dialogs differ in exactly that flag. On a
+backend that predates the field nothing is required, which is the behavior above
+unchanged.
diff --git a/packages/app-shell/src/utils/decisionOutputParams.test.ts b/packages/app-shell/src/utils/decisionOutputParams.test.ts
index fa46eb1cc3..afec456bbb 100644
--- a/packages/app-shell/src/utils/decisionOutputParams.test.ts
+++ b/packages/app-shell/src/utils/decisionOutputParams.test.ts
@@ -93,10 +93,31 @@ describe('decisionOutputParams — declaration → param', () => {
     expect(free.helpText).toBe('t:actions.decisionOutput.helpMultiValue');
   });
 
-  it('declares no output as required — the flow author cannot demand one yet', () => {
-    // `DecisionOutputDef` carries no `required` flag (objectui#2955 follow-up);
-    // until it does, a hard-required picker would be unreachable metadata.
-    expect(decisionOutputParams([{ key: 'r', type: 'user' }], t)[0].required).toBe(false);
+  it('leaves an undeclared output optional', () => {
+    expect(decisionOutputParams([{ key: 'r', type: 'user' }], t, { decision: 'approve' })[0].required)
+      .toBe(false);
+  });
+
+  it('marks a `required` output required on the APPROVE dialog', () => {
+    // The server rejects a blank required output before any write; marking it
+    // here stops the approver at the field instead of at a 400.
+    expect(
+      decisionOutputParams([{ key: 'r', type: 'position', required: true }], t, { decision: 'approve' })[0].required,
+    ).toBe(true);
+  });
+
+  it('never marks it required on the REJECT dialog', () => {
+    // Mirrors the server: a reject leaves down the reject edge where nothing
+    // reads the outputs, so demanding them would trap the rejection.
+    expect(
+      decisionOutputParams([{ key: 'r', type: 'position', required: true }], t, { decision: 'reject' })[0].required,
+    ).toBe(false);
+  });
+
+  it('requires nothing when the caller names no decision', () => {
+    // A surface that has not said which decision it is collecting for must not
+    // block — and a pre-`required` backend sends the flag on nothing anyway.
+    expect(decisionOutputParams([{ key: 'r', required: true }], t)[0].required).toBe(false);
   });
 });
 
@@ -122,6 +143,16 @@ describe('decisionOutputParams — the params survive resolution (objectui#2955)
     expect(widgetFor(param)).toMatchObject({ type: 'user', multiple: true });
   });
 
+  it('the required flag survives resolution, so the dialog can block on it', () => {
+    // `paramToField` feeds `ActionParamDialog`'s required check — if the flag
+    // were dropped in resolution the dialog would submit a blank value and let
+    // the server 400 instead.
+    const [param] = decisionOutputParams(
+      [{ key: 'k', type: 'position', required: true }], t, { decision: 'approve' },
+    );
+    expect(widgetFor(param)).toMatchObject({ type: 'lookup', required: true });
+  });
+
   it('an untyped output stays free text', () => {
     const [param] = decisionOutputParams([{ key: 'note' }], t);
     expect(widgetFor(param)).toMatchObject({ type: 'text' });
diff --git a/packages/app-shell/src/utils/decisionOutputParams.ts b/packages/app-shell/src/utils/decisionOutputParams.ts
index c9684a2dd3..6bfbecd265 100644
--- a/packages/app-shell/src/utils/decisionOutputParams.ts
+++ b/packages/app-shell/src/utils/decisionOutputParams.ts
@@ -41,6 +41,13 @@ export interface DecisionOutputDef {
   /** Record kind to pick (`user` / `department` / `position` / `team`); absent → free text. */
   type?: string;
   multiple?: boolean;
+  /**
+   * The approver must supply this one to APPROVE. The server enforces it
+   * (`decide()` rejects a blank required output before any write); the dialog
+   * mirrors it so the approver is stopped at the field rather than by a 400.
+   * Absent on a backend that predates the flag — then nothing is required.
+   */
+  required?: boolean;
 }
 
 /** Param-name prefix the api handler folds back into the nested `outputs` body. */
@@ -91,19 +98,23 @@ function humanizeKey(key: string): string {
  * so no `_actions.<action>.params.*` bundle entry can ever match them and the
  * literal we pass IS what renders (objectui#2762 P0-3).
  *
- * Every output is optional: `DecisionOutputDef` carries no `required` flag, so
- * a flow author cannot yet demand one (objectui#2955 follow-up) — an omitted
- * output simply isn't sent.
+ * A `required` output is marked required on the APPROVE dialog only — pass
+ * `{ decision: 'approve' }`. That mirrors the server, which enforces `required`
+ * on approve and never on reject (the run leaves down the reject edge, where
+ * nothing reads the outputs, so demanding routing data to say "no" would trap
+ * the rejection). Marking it here is what turns the server's 400 into a
+ * blocked Confirm button with the field flagged, instead of a round trip.
  */
 export function decisionOutputParams(
   defs: DecisionOutputDef[],
   t: (key: string) => string,
+  opts: { decision?: 'approve' | 'reject' } = {},
 ): Array<Record<string, unknown>> {
   return defs.filter((d) => d && d.key).map((d) => {
     const base = {
       name: `${DECISION_OUTPUT_PARAM_PREFIX}${d.key}`,
       label: d.label ?? humanizeKey(d.key),
-      required: false,
+      required: opts.decision === 'approve' && d.required === true,
     };
     if (d.type === 'user') {
       return {
diff --git a/packages/app-shell/src/views/DeclaredActionsBar.tsx b/packages/app-shell/src/views/DeclaredActionsBar.tsx
index 15ba47c2b7..14beb77326 100644
--- a/packages/app-shell/src/views/DeclaredActionsBar.tsx
+++ b/packages/app-shell/src/views/DeclaredActionsBar.tsx
@@ -145,12 +145,19 @@ const DeclaredActionButton: React.FC<{
       // handler folds them into the nested `outputs` body the decide route
       // expects. A free-text output accepts comma-separated values (the
       // service accepts CSV for multi-id outputs).
-      const isDecideAction = /\/(approve|reject)$/.test(String((action as any).target ?? ''));
+      // Which decision this action records — `required` outputs are enforced
+      // on approve only (server and dialog agree), so the reject dialog offers
+      // the same fields without blocking on them.
+      const decision = /\/approve$/.test(String((action as any).target ?? ''))
+        ? 'approve' as const
+        : /\/reject$/.test(String((action as any).target ?? ''))
+          ? 'reject' as const
+          : undefined;
       // Widget mapping (typed picker vs free text) lives in the shared helper,
       // so the record header's Approve/Reject renders the same controls
       // (objectui#2955).
-      const outputParams = isDecideAction
-        ? decisionOutputParams(decisionOutputDefs(recordData), t)
+      const outputParams = decision
+        ? decisionOutputParams(decisionOutputDefs(recordData), t, { decision })
         : [];
       const dispatch: any = {
         ...rest,
diff --git a/packages/app-shell/src/views/RecordDetailView.approvalDecisionActions.test.tsx b/packages/app-shell/src/views/RecordDetailView.approvalDecisionActions.test.tsx
index 9eaa37dd0c..164299c4a1 100644
--- a/packages/app-shell/src/views/RecordDetailView.approvalDecisionActions.test.tsx
+++ b/packages/app-shell/src/views/RecordDetailView.approvalDecisionActions.test.tsx
@@ -103,6 +103,25 @@ describe('buildApprovalDecisionActions — decision outputs (objectui#2955)', ()
     });
   });
 
+  it('requires a `required` output to approve, but never to reject', () => {
+    const actions = byName(
+      buildApprovalDecisionActions(
+        pending({
+          decision_output_defs: [
+            { key: 'parallel_positions', type: 'position', multiple: true, required: true },
+          ],
+        }),
+        t,
+      ) as any[],
+    );
+    const paramOf = (name: string) =>
+      (actions[name].actionParams as any[]).find((p) => p.name === 'outputs.parallel_positions');
+    expect(paramOf('approve_request').required).toBe(true);
+    // Mirrors the server, which enforces `required` on approve only — a reject
+    // blocked on routing data the reject edge never reads would trap it.
+    expect(paramOf('reject_request').required).toBe(false);
+  });
+
   it('collects nothing extra when there is no pending request', () => {
     const [approve] = buildApprovalDecisionActions(null, t) as any[];
     expect((approve.actionParams as any[]).map((p) => p.name)).toEqual(['comment']);
diff --git a/packages/app-shell/src/views/RecordDetailView.tsx b/packages/app-shell/src/views/RecordDetailView.tsx
index 8ff942445b..c891624728 100644
--- a/packages/app-shell/src/views/RecordDetailView.tsx
+++ b/packages/app-shell/src/views/RecordDetailView.tsx
@@ -172,9 +172,13 @@ export function buildApprovalDecisionActions(
     // intent has to ride the type.
     type: 'textarea',
   };
-  const decisionParams = [
+  // `required` outputs are enforced on approve only — the server rejects a
+  // blank one there and never on reject, so the two dialogs differ in exactly
+  // that flag and nothing else.
+  const defs = decisionOutputDefs(pendingRequest);
+  const decisionParams = (decision: 'approve' | 'reject') => [
     commentParam,
-    ...decisionOutputParams(decisionOutputDefs(pendingRequest), (key: string) => t(key)),
+    ...decisionOutputParams(defs, (key: string) => t(key), { decision }),
   ];
   // A pending approval is THE decision the approver came to make, so the
   // decision buttons must outrank app `record_header` actions rather than being
@@ -194,7 +198,7 @@ export function buildApprovalDecisionActions(
       order: -100,
       locations: ['record_header'],
       refreshAfter: true,
-      actionParams: decisionParams,
+      actionParams: decisionParams('approve'),
       successMessage: t('approvals.approveSuccess', { defaultValue: 'Approved' }),
     },
     {
@@ -208,7 +212,7 @@ export function buildApprovalDecisionActions(
       locations: ['record_header'],
       refreshAfter: true,
       confirmText: t('approvals.rejectConfirm', { defaultValue: 'Reject this approval request?' }),
-      actionParams: decisionParams,
+      actionParams: decisionParams('reject'),
       successMessage: t('approvals.rejectSuccess', { defaultValue: 'Rejected' }),
     },
   ] as unknown as ActionDef[];
diff --git a/packages/app-shell/src/views/__tests__/DeclaredActionsBar.test.tsx b/packages/app-shell/src/views/__tests__/DeclaredActionsBar.test.tsx
index ea1ce5a432..18f008749c 100644
--- a/packages/app-shell/src/views/__tests__/DeclaredActionsBar.test.tsx
+++ b/packages/app-shell/src/views/__tests__/DeclaredActionsBar.test.tsx
@@ -269,6 +269,31 @@ describe('DeclaredActionsBar chrome localization (objectui#2762)', () => {
     expect(screen.getByRole('toolbar')).toHaveAttribute('aria-label', '决策');
   });
 
+  it.each([
+    ['/api/v1/approvals/requests/{id}/approve', true],
+    ['/api/v1/approvals/requests/{id}/reject', false],
+  ])('marks a required output required on %s → %s', async (target, expected) => {
+    // The server enforces `required` on approve and never on reject; the two
+    // dialogs must differ in exactly that flag (objectui#2955).
+    render(
+      <DeclaredActionsBar
+        objectName="sys_approval_request"
+        record={{
+          ...REQUEST,
+          decision_output_defs: [{ key: 'parallel_positions', type: 'position', required: true }],
+        }}
+        location="record_section"
+        actions={[{
+          name: 'decide', type: 'api', label: 'Decide', target, locations: ['record_section'],
+        }] as any}
+      />,
+    );
+    fireEvent.click(screen.getByText('Decide'));
+    await waitFor(() => expect(executeSpy).toHaveBeenCalled());
+    const params = executeSpy.mock.calls[0][0].actionParams as Array<Record<string, unknown>>;
+    expect(params[0].required).toBe(expected);
+  });
+
   it('hands the picker target under `reference`, the key that survives resolution', async () => {
     // objectui#2955: the params are spelled for `resolveActionParams`, which
     // rebuilds an inline param from a fixed key list and reads the target from