feat(approvals): quorum + per-group sign-off (会签) + decision attachments (#3266)

Node-internal multi-approver semantics — the钉钉/Salesforce-style patterns that
deliver "legal AND finance both approve" and "M-of-N" without any flow-engine
change (topology-level parallel branches remain #3267). Community-core; weighted
voting + approval-matrix governance stay enterprise (objectstack-ai/cloud#861).

Spec (approval.zod.ts):
- behavior enum += 'quorum' (M-of-N) and 'per_group' (one — or minApprovals —
  from EACH group), plus a `minApprovals` threshold and an optional `group`
  label on each approver. A single rejection is always a veto. Corrected the
  stale "quorum is enterprise" comment.

Engine (approval-service.ts):
- expandApprovers refactored to resolveApproverSpec + a group collector, so each
  resolved approver (OOO-substituted included) is tagged with its group; the
  map is snapshotted at open so the tally is stable.
- decideNode: unified quorum/per_group/unanimous finalization via
  isApprovalSatisfied; thresholds clamp to the resolvable count / group size so
  a mis-set value can never deadlock. reassign transfers a slot's group so the
  new approver still counts.

Attachments (#3266):
- sys_approval_action gains a `Field.file` `attachments` column; decide/comment
  accept + persist file references, threaded through the contract, REST
  decide/comment routes, and the client approve/reject helpers.

Showcase: ExpenseSignoffFlow — manager + finance per_group 会签 on a submitted
expense report.

Tests: 9 new (quorum boundary + clamp + veto, per_group each-group /
two-in-one-group / minApprovals=2 / OOO-substituted member counts, attachments);
132 green in plugin-approvals.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016ypkQikZ55oWUHUnMebwXA

Author: claude

examples/app-showcase/src/automation/flows/index.ts

@@ -1379,8 +1379,60 @@ export const InquiryPurgeFlow = defineFlow({
   ],
 });
 
+/**
+ * Expense Sign-off (#3266) — a `per_group` approval demonstrating 会签: a
+ * MANAGER **and** a FINANCE/audit approver must EACH sign off (one from each
+ * group) before a submitted expense report is approved; either rejection
+ * vetoes. Where {@link BudgetApprovalFlow} chains position steps in series,
+ * this gates a SINGLE node on two groups at once — the node-internal parallel
+ * pattern (钉钉/Salesforce style) that needs no parallel branches. Set
+ * `minApprovals` > 1 for "two from each group"; use `behavior: 'quorum'` +
+ * `minApprovals` for M-of-N collective sign-off.
+ */
+export const ExpenseSignoffFlow = defineFlow({
+  name: 'showcase_expense_signoff',
+  label: 'Expense Report Sign-off',
+  description: 'Manager + finance per-group sign-off (会签) on a submitted expense report (#3266).',
+  type: 'autolaunched',
+  status: 'active',
+  nodes: [
+    {
+      id: 'start',
+      type: 'start',
+      label: 'On Submitted',
+      config: {
+        objectName: 'showcase_expense_report',
+        triggerType: 'record-after-update',
+        condition: 'status == "submitted" && previous.status != "submitted"',
+      },
+    },
+    {
+      id: 'dual_signoff',
+      type: 'approval',
+      label: 'Manager + Finance Sign-off',
+      config: {
+        approvers: [
+          { type: 'position', value: 'manager', group: 'manager' },
+          { type: 'position', value: 'auditor', group: 'finance' },
+        ],
+        behavior: 'per_group',
+        minApprovals: 1,
+        lockRecord: true,
+      },
+    },
+    { id: 'approved', type: 'end', label: 'Approved' },
+    { id: 'rejected', type: 'end', label: 'Rejected' },
+  ],
+  edges: [
+    { id: 'e1', source: 'start', target: 'dual_signoff' },
+    { id: 'e2', source: 'dual_signoff', target: 'approved', label: 'approve' },
+    { id: 'e3', source: 'dual_signoff', target: 'rejected', label: 'reject' },
+  ],
+});
+
 export const allFlows = [
   TaskCompletedFlow,
+  ExpenseSignoffFlow,
   ReassignWizardFlow,
   InquiryPurgeFlow,
   BudgetApprovalFlow,

packages/client/src/index.ts

@@ -2493,11 +2493,11 @@ export class ObjectStackClient {
      * Record an approve decision on a request. Finalises the request when the
      * node's behaviour is satisfied and resumes the owning flow run.
      */
-    approve: async (requestId: string, decision?: { actorId?: string; comment?: string }): Promise<ApprovalDecisionResult> => {
+    approve: async (requestId: string, decision?: { actorId?: string; comment?: string; attachments?: string[] }): Promise<ApprovalDecisionResult> => {
       const route = this.getRoute('approvals');
       const res = await this.fetch(`${this.baseUrl}${route}/requests/${encodeURIComponent(requestId)}/approve`, {
         method: 'POST',
-        body: JSON.stringify({ actorId: decision?.actorId, comment: decision?.comment })
+        body: JSON.stringify({ actorId: decision?.actorId, comment: decision?.comment, attachments: decision?.attachments })
       });
       return this.unwrapResponse<ApprovalDecisionResult>(res);
     },
@@ -2506,11 +2506,11 @@ export class ObjectStackClient {
      * Record a reject decision on a request. Resumes the owning flow run down
      * the `reject` edge.
      */
-    reject: async (requestId: string, decision?: { actorId?: string; comment?: string }): Promise<ApprovalDecisionResult> => {
+    reject: async (requestId: string, decision?: { actorId?: string; comment?: string; attachments?: string[] }): Promise<ApprovalDecisionResult> => {
       const route = this.getRoute('approvals');
       const res = await this.fetch(`${this.baseUrl}${route}/requests/${encodeURIComponent(requestId)}/reject`, {
         method: 'POST',
-        body: JSON.stringify({ actorId: decision?.actorId, comment: decision?.comment })
+        body: JSON.stringify({ actorId: decision?.actorId, comment: decision?.comment, attachments: decision?.attachments })
       });
       return this.unwrapResponse<ApprovalDecisionResult>(res);
     },

packages/plugins/plugin-approvals/src/approval-service.test.ts

@@ -1287,3 +1287,106 @@ describe('sys_approval_delegation write guard (#1322)', () => {
     )).rejects.toThrow(/FORBIDDEN/);
   });
 });
+
+// ── Quorum & per-group sign-off (#3266) ───────────────────────────────
+//
+// quorum = M-of-N collective sign-off; per_group = one (or minApprovals) from
+// EACH group (会签). A single rejection is always a veto. Group membership is
+// snapshotted at open, so OOO-substituted approvers count for their group.
+describe('ApprovalService — quorum & per_group (#3266)', () => {
+  let engine: ReturnType<typeof makeFakeEngine>;
+  let svc: ApprovalService;
+  const base = new Date('2026-08-01T10:00:00Z').getTime();
+
+  beforeEach(() => {
+    engine = makeFakeEngine();
+    let n = 0;
+    svc = new ApprovalService({ engine: engine as any, clock: { now: () => new Date(base + (n++) * 1000) } });
+  });
+
+  // Build an openNodeRequest input with explicit approver specs + behavior.
+  const cfg = (approvers: any[], behavior: string, extra: Record<string, any> = {}) => ({
+    ...openInput([]),
+    config: { approvers, behavior, lockRecord: true, ...extra },
+  });
+  const U = (v: string, group?: string) => (group ? { type: 'user', value: v, group } : { type: 'user', value: v });
+
+  it('quorum: holds until minApprovals reached, then finalizes', async () => {
+    const req = await svc.openNodeRequest(cfg([U('u1'), U('u2'), U('u3')], 'quorum', { minApprovals: 2 }), CTX);
+    const a = await svc.decideNode(req.id, { decision: 'approve', actorId: 'u1' }, SYS);
+    expect(a.finalized).toBe(false);
+    expect(a.request.status).toBe('pending');
+    const b = await svc.decideNode(req.id, { decision: 'approve', actorId: 'u2' }, SYS);
+    expect(b.finalized).toBe(true);
+    expect(b.request.status).toBe('approved');
+  });
+
+  it('quorum: minApprovals clamps to the approver count (no deadlock)', async () => {
+    const req = await svc.openNodeRequest(cfg([U('u1'), U('u2')], 'quorum', { minApprovals: 5 }), CTX);
+    await svc.decideNode(req.id, { decision: 'approve', actorId: 'u1' }, SYS);
+    const b = await svc.decideNode(req.id, { decision: 'approve', actorId: 'u2' }, SYS);
+    expect(b.finalized).toBe(true);
+  });
+
+  it('quorum: any reject is a veto', async () => {
+    const req = await svc.openNodeRequest(cfg([U('u1'), U('u2'), U('u3')], 'quorum', { minApprovals: 2 }), CTX);
+    const r = await svc.decideNode(req.id, { decision: 'reject', actorId: 'u1' }, SYS);
+    expect(r.finalized).toBe(true);
+    expect(r.request.status).toBe('rejected');
+  });
+
+  it('per_group: advances only when EACH group approves', async () => {
+    const req = await svc.openNodeRequest(cfg([U('l1', 'legal'), U('f1', 'finance')], 'per_group'), CTX);
+    const a = await svc.decideNode(req.id, { decision: 'approve', actorId: 'l1' }, SYS);
+    expect(a.finalized).toBe(false); // finance still pending
+    const b = await svc.decideNode(req.id, { decision: 'approve', actorId: 'f1' }, SYS);
+    expect(b.finalized).toBe(true);
+    expect(b.request.status).toBe('approved');
+  });
+
+  it('per_group: two approvals in ONE group do not satisfy another group', async () => {
+    const req = await svc.openNodeRequest(
+      cfg([U('l1', 'legal'), U('l2', 'legal'), U('f1', 'finance')], 'per_group'), CTX);
+    await svc.decideNode(req.id, { decision: 'approve', actorId: 'l1' }, SYS);
+    const b = await svc.decideNode(req.id, { decision: 'approve', actorId: 'l2' }, SYS);
+    expect(b.finalized).toBe(false); // finance still missing
+  });
+
+  it('per_group: minApprovals=2 needs two from each group', async () => {
+    const req = await svc.openNodeRequest(cfg(
+      [U('l1', 'legal'), U('l2', 'legal'), U('f1', 'finance'), U('f2', 'finance')],
+      'per_group', { minApprovals: 2 }), CTX);
+    for (const u of ['l1', 'f1', 'l2']) {
+      const r = await svc.decideNode(req.id, { decision: 'approve', actorId: u }, SYS);
+      expect(r.finalized).toBe(false);
+    }
+    const done = await svc.decideNode(req.id, { decision: 'approve', actorId: 'f2' }, SYS);
+    expect(done.finalized).toBe(true);
+  });
+
+  it('per_group: reject is a veto', async () => {
+    const req = await svc.openNodeRequest(cfg([U('l1', 'legal'), U('f1', 'finance')], 'per_group'), CTX);
+    const r = await svc.decideNode(req.id, { decision: 'reject', actorId: 'l1' }, SYS);
+    expect(r.request.status).toBe('rejected');
+  });
+
+  it('per_group: an OOO-substituted member still counts for their group', async () => {
+    engine._tables['sys_approval_delegation'] = [
+      { id: 'd', delegator_id: 'l1', delegate_id: 'lb', organization_id: 't1', valid_from: null, valid_until: null, reason: 'leave' },
+    ];
+    const req = await svc.openNodeRequest(cfg([U('l1', 'legal'), U('f1', 'finance')], 'per_group'), CTX);
+    expect(req.pending_approvers).toContain('lb');
+    expect(req.pending_approvers).not.toContain('l1');
+    const a = await svc.decideNode(req.id, { decision: 'approve', actorId: 'lb' }, SYS); // delegate covers legal
+    expect(a.finalized).toBe(false);
+    const b = await svc.decideNode(req.id, { decision: 'approve', actorId: 'f1' }, SYS);
+    expect(b.finalized).toBe(true);
+  });
+
+  it('records decision attachments on the audit row', async () => {
+    const req = await svc.openNodeRequest(openInput(['u9']), CTX);
+    await svc.decideNode(req.id, { decision: 'approve', actorId: 'u9', attachments: ['file_1', 'file_2'] }, SYS);
+    const act = engine._tables['sys_approval_action'].find((a: any) => a.action === 'approve');
+    expect(act.attachments).toEqual(['file_1', 'file_2']);
+  });
+});