@yss123/cage-cli 0.3.0 → 0.3.1

package/graph-ui/approval-flow.js

@@ -1,7 +1,8 @@
+import { layoutStructuredApproval } from './approval-parallel.js';
 /**
  * 按中英文近似字宽换行，返回完整文字行；不是浏览器字体精确测量。
  */
-function wrap(text, limit) {
+export function wrapApprovalText(text, limit) {
     const lines = [];
     let line = '', length = 0;
     for (const char of text) {
@@ -18,6 +19,14 @@ function wrap(text, limit) {
         lines.push(line);
     return lines;
 }
+/** 结构化条件或并行需要递归布局；只有原始平面顺序组时沿用既有紧凑图。 */
+export function hasStructuredApproval(groups) {
+    return groups.some(group => !!group.parallel || !!group.groups);
+}
+/** 标题只在存在真实 AND 容器时说明同时启动，嵌套 when 本身仍是条件顺序而非并行。 */
+function hasParallel(groups) {
+    return groups.some(group => !!group.parallel || (group.groups && hasParallel(group.groups)));
+}
 /** 审批始终在容器内纵向阅读，外部主流程可以横排。先测量再参与全图布局，
  * 条件与审批步骤都不会越出容器，跳过线在侧边汇合后才进入下一条条件。 */
 /**
@@ -27,7 +36,9 @@ function wrap(text, limit) {
  * @returns 相对坐标、文本行与连线；不读取具体审批任务。
  */
 export function layoutApprovalFlow(flow, name) {
-    const title = wrap(name, 18);
+    if (hasStructuredApproval(flow.groups))
+        return layoutStructuredApproval(flow, name);
+    const title = wrapApprovalText(name, 18);
     const boxes = [];
     const paths = [];
     const merges = [];
@@ -45,7 +56,7 @@ export function layoutApprovalFlow(flow, name) {
      * 测量任务标题、选人与规则，推进纵向游标并连接前驱；条件组首任务可标记“是”分支。
      */
     const addTask = (task, firstLabel) => {
-        const title = wrap(task.title, 14), actor = wrap(`审批人：${task.actor}`, 19), rule = wrap(task.rule, 18);
+        const title = wrapApprovalText(task.title, 14), actor = wrapApprovalText(`审批人：${task.actor}`, 19), rule = wrapApprovalText(task.rule, 18);
         const height = 18 + title.length * 18 + actor.length * 16 + rule.length * 16;
         connect(y, firstLabel);
         boxes.push({ kind: 'task', x: left, y, width, height, title, actor, rule, task });
@@ -57,7 +68,7 @@ export function layoutApprovalFlow(flow, name) {
             group.tasks.forEach((task) => addTask(task));
             continue;
         }
-        const title = wrap(`${group.condition}？`, 13);
+        const title = wrapApprovalText(`${group.condition}？`, 13);
         const height = Math.max(64, title.length * 36);
         connect(y);
         const top = y;
@@ -101,9 +112,11 @@ export function renderApprovalFlow(layout) {
     layout.title.forEach((line, index) => content.append(text(24, 31 + index * 20, line, 'approval-flow-title', 'start')));
     content.append(text(24, 32 + layout.title.length * 20, !layout.flow.route
         ? '审批步骤待补充 · 点击查看声明'
-        : layout.flow.groups.some((group) => group.condition)
-            ? '按顺序审批 · 条件满足时加审'
-            : '按顺序审批 · 每一步通过后继续', 'approval-flow-subtitle', 'start'));
+        : hasParallel(layout.flow.groups)
+            ? '分支同时启动 · 全部分支完成后汇合'
+            : layout.flow.groups.some((group) => group.condition)
+                ? '按顺序审批 · 条件满足时加审'
+                : '按顺序审批 · 每一步通过后继续', 'approval-flow-subtitle', 'start'));
     for (const path of layout.paths) {
         content.append(vector('path', {
             d: path.d,
@@ -132,7 +145,7 @@ export function renderApprovalFlow(layout) {
             }));
             box.title.forEach((line, index) => item.append(text(box.x + box.width / 2, box.y + box.height / 2 + 4 + (index - (box.title.length - 1) / 2) * 16, line, 'approval-condition-title')));
         }
-        else {
+        else if (box.kind === 'task') {
             item.append(vector('rect', {
                 x: box.x,
                 y: box.y,
@@ -148,6 +161,13 @@ export function renderApprovalFlow(layout) {
             box.actor.forEach((line, index) => item.append(text(center, box.y + 24 + box.title.length * 18 + index * 16, line, 'approval-task-actor')));
             box.rule.forEach((line, index) => item.append(text(center, box.y + 24 + box.title.length * 18 + box.actor.length * 16 + index * 16, line, 'approval-task-rule')));
         }
+        else {
+            // 网关与分支标题不冒充可审批任务，也不显示全局序号；AND 的两条入口/出口由真实布局路径表达。
+            const gateway = box.kind === 'fork' || box.kind === 'join';
+            item.append(vector('rect', { x: box.x, y: box.y, width: box.width, height: box.height,
+                rx: gateway ? 3 : 8, class: gateway ? 'approval-gateway-shape' : 'approval-branch-shape' }));
+            box.title.forEach((line, index) => item.append(text(box.x + box.width / 2, box.y + (box.height - box.title.length * 17) / 2 + 13 + index * 17, line, gateway ? 'approval-gateway-title' : 'approval-task-title')));
+        }
         content.append(item);
     }
     for (const merge of layout.merges)

package/graph-ui/approval-parallel.js

@@ -0,0 +1,110 @@
+import { wrapApprovalText } from './approval-flow.js';
+/** 创建空容器；空条件分支仍有一条可连接直线，不假造审批节点或已经运行的票。 */
+function fragment(width = 348, height = 0) {
+    return { width, height, axis: width / 2, boxes: [], paths: [], merges: [] };
+}
+/**
+ * 把已测量子图复制平移到父图，路径坐标只由本模块产生的 M/L/H/V 绝对指令转换。
+ * 不改源片段，递归兄弟分支共享文本对象也不会互相污染；标题与输入不拼入 SVG path。
+ */
+function append(parent, child, dx, dy) {
+    parent.boxes.push(...child.boxes.map(box => ({ ...box, x: box.x + dx, y: box.y + dy })));
+    for (const path of child.paths)
+        parent.paths.push({ ...path,
+            d: path.d.replace(/([ML])(-?[\d.]+),(-?[\d.]+)|([HV])(-?[\d.]+)/g, (_match, point, x, y, axis, value) => point ? `${point}${Number(x) + dx},${Number(y) + dy}` : `${axis}${Number(value) + (axis === 'H' ? dx : dy)}`),
+            ...(path.x === undefined ? {} : { x: path.x + dx }), ...(path.y === undefined ? {} : { y: path.y + dy }) });
+    parent.merges.push(...child.merges.map(point => ({ x: point.x + dx, y: point.y + dy })));
+}
+/** 把一个审批叶节点测量成普通任务框；编号只是声明定位，不决定并行分支的实际运行顺序。 */
+function taskFragment(task) {
+    const title = wrapApprovalText(task.title, 14), actor = wrapApprovalText(`审批人：${task.actor}`, 19), rule = wrapApprovalText(task.rule, 18);
+    const height = 18 + title.length * 18 + actor.length * 16 + rule.length * 16, result = fragment(348, height);
+    result.boxes.push({ kind: 'task', x: 50, y: 0, width: 248, height, title, actor, rule, task });
+    return result;
+}
+/** 各顺序子片段在最大宽度中心对齐，连接只经过相邻片段之间的空隙。 */
+function sequence(parts) {
+    // 条件旁路使子图左右不对称，按中心轴两侧的最大占用测量，不能只取原始 width 后居中导致右侧越界。
+    const result = fragment(Math.max(348, ...parts.map(part => 2 * Math.max(part.axis, part.width - part.axis))));
+    if (!parts.length) {
+        result.height = 20;
+        result.paths.push({ d: `M${result.axis},0 V20` });
+        return result;
+    }
+    for (const [index, part] of parts.entries()) {
+        if (index) {
+            result.paths.push({ d: `M${result.axis},${result.height} V${result.height + 28}` });
+            result.height += 28;
+        }
+        append(result, part, result.axis - part.axis, result.height);
+        result.height += part.height;
+    }
+    return result;
+}
+/**
+ * 条件未满足的路径在整个子树外侧绕行并汇合，包含并行网关时也不能跳过一半后进入内部支路。
+ * 中心轴保持子树入口，额外宽度只用于右侧旁路；祖先会按 axis 平移，避免嵌套时斜穿节点。
+ */
+function conditional(body, condition) {
+    const result = fragment(body.width + 76), title = wrapApprovalText(`${condition}？`, 13), height = Math.max(64, title.length * 36);
+    result.axis = body.axis;
+    result.boxes.push({ kind: 'condition', x: result.axis - 124, y: 0, width: 248, height, title, actor: [], rule: [] });
+    const top = height + 30, merge = top + body.height + 26;
+    append(result, body, 0, top);
+    result.paths.push({ d: `M${result.axis},${height} V${top}`, label: '是', x: result.axis + 16, y: height + 18 }, { d: `M${result.axis},${top + body.height} V${merge}` }, { d: `M${result.axis + 124},${height / 2} H${body.width + 38} V${merge} H${result.axis}`,
+        label: '否 · 跳过', x: body.width + 38, y: (height / 2 + merge) / 2, skip: true });
+    result.merges.push({ x: result.axis, y: merge });
+    result.height = merge;
+    return result;
+}
+/**
+ * 并行分支分别测量，入口共享同一 fork，出口统一接 join；短分支等待线停留在自己通道内。
+ * 分支内部可以有条件或嵌套并行，所有子树完成后才绘制后续出口，不把任一分支画成可独自通过。
+ */
+function parallelFragment(parallel) {
+    const branches = parallel.branches.map(branch => ({ title: wrapApprovalText(branch.title, 14), body: groupsFragment(branch.groups) }));
+    const gap = 30, width = branches.reduce((sum, branch) => sum + branch.body.width, 0) + gap * (branches.length - 1);
+    const result = fragment(Math.max(348, width)), title = wrapApprovalText(`${parallel.title} · AND 分叉`, 24), forkHeight = 20 + title.length * 17;
+    result.boxes.push({ kind: 'fork', x: result.axis - 150, y: 0, width: 300, height: forkHeight, title, actor: [], rule: [] });
+    const splitY = forkHeight + 20, branchTop = splitY + 20;
+    let dx = 0, bottom = branchTop;
+    const ends = [];
+    for (const branch of branches) {
+        const axis = dx + branch.body.axis, labelHeight = 16 + branch.title.length * 17;
+        result.boxes.push({ kind: 'branch', x: axis - 124, y: branchTop, width: 248, height: labelHeight,
+            title: branch.title, actor: [], rule: [] });
+        const bodyTop = branchTop + labelHeight + 24;
+        result.paths.push({ d: `M${result.axis},${forkHeight} V${splitY} H${axis} V${branchTop}` }, { d: `M${axis},${branchTop + labelHeight} V${bodyTop}` });
+        append(result, branch.body, dx, bodyTop);
+        const end = bodyTop + branch.body.height;
+        ends.push({ x: axis, y: end });
+        bottom = Math.max(bottom, end);
+        dx += branch.body.width + gap;
+    }
+    const mergeY = bottom + 24, joinY = mergeY + 20, joinHeight = 40;
+    for (const end of ends)
+        result.paths.push({ d: `M${end.x},${end.y} V${mergeY} H${result.axis} V${joinY}` });
+    result.boxes.push({ kind: 'join', x: result.axis - 150, y: joinY, width: 300, height: joinHeight,
+        title: ['AND 汇合 · 等待全部活动分支'], actor: [], rule: [] });
+    result.height = joinY + joinHeight;
+    return result;
+}
+/** 将保留的声明组递归转换为几何，条件包裹整个子树，parallel 和普通 tasks 不混为串行。 */
+function groupsFragment(groups) {
+    return sequence(groups.map(group => {
+        const body = group.parallel ? parallelFragment(group.parallel) : group.groups ? groupsFragment(group.groups) : sequence(group.tasks.map(taskFragment));
+        return group.condition ? conditional(body, group.condition) : body;
+    }));
+}
+/**
+ * 为带嵌套容器的审批投影生成完整布局；外层主流程使用返回宽高避免与邻接业务节点重叠。
+ * 结构输入由已校验声明派生；此处不重新执行条件，也不猜测当前实例哪些分支已跳过。
+ */
+export function layoutStructuredApproval(flow, name) {
+    const title = wrapApprovalText(name, 18), body = groupsFragment(flow.groups), top = 64 + title.length * 20;
+    const framed = fragment(body.width + 52);
+    append(framed, body, 26, top);
+    const footer = top + body.height + 42;
+    framed.paths.push({ d: `M${26 + body.axis},${top + body.height} V${footer - 16}` });
+    return { flow, title, width: framed.width, height: footer + 60, boxes: framed.boxes, paths: framed.paths, merges: framed.merges, footer };
+}

package/graph-ui/approval-tree.js

@@ -0,0 +1,17 @@
+/**
+ * 审批声明 JSON 的只读结构与遍历工具，供本体抽取、字段关系说明和静态流程图共同消费。
+ * 仅遍历 when、parallel 和 branch 保留的声明树，不执行条件、选人、审批引擎或实际实例状态。
+ * 浏览器可引用这些类型和纯函数，不引入 approval 运行时；标题和依赖始终来自抽取快照。
+ */
+/**
+ * 按声明的深度优先次序遍历全部节点，保留容器供条件解释使用，分支本身不是可执行步骤。
+ * 本函数不排序或改写源树；声明深度/数量由注册器限制，序号只能作为静态定位，不能当执行先后。
+ */
+export function approvalRouteNodes(nodes) {
+    return nodes.flatMap(node => [node, ...(node.kind === 'when' ? approvalRouteNodes(node.steps) :
+            node.kind === 'parallel' ? node.branches.flatMap(branch => approvalRouteNodes(branch.nodes)) : [])]);
+}
+/** 收集全部人工/AI 叶节点，用于取证与选人依赖；并行结构仍需由调用方从原树单独保留。 */
+export function approvalRouteSteps(nodes) {
+    return approvalRouteNodes(nodes).filter((node) => node.kind === 'step' || node.kind === 'ai');
+}

package/graph-ui/business.css

@@ -553,6 +553,22 @@
   font-size: 12px;
   font-weight: 500;
 }
+/* AND 网关与分支标题使用独立形状，不能被误认成一个需要审批的任务；坐标由递归测量布局提供。 */
+.approval-gateway-shape {
+  fill: #e9f0e4;
+  stroke: #72916f;
+  stroke-width: 1.5;
+}
+.approval-gateway-title {
+  fill: #35573b;
+  font-size: 12px;
+  font-weight: 600;
+}
+.approval-branch-shape {
+  fill: #f2f5ed;
+  stroke: #b5c5ab;
+  stroke-dasharray: 4 3;
+}
 .approval-flow-merge {
   fill: #8ba28e;
 }
@@ -781,6 +797,16 @@
 .business-approval-steps p {
   font-size: 10px;
 }
+/* 并行分支在规则详情中保留树层级，独立左边线区分分支，不靠列表编号暗示执行先后。 */
+.business-approval-branches {
+  margin: 8px 0;
+  padding-left: 16px;
+  list-style: none;
+  border-left: 2px solid #b5c5ab;
+}
+.business-approval-branches > li {
+  margin: 10px 0 14px;
+}
 /* 源码预览按行显示并保留原始缩进，横向溢出在代码框内滚动；行号只参与显示。 */
 .source-preview {
   min-width: 0;

package/graph-ui/business.js

@@ -496,20 +496,37 @@ export function renderBusiness(host, model, snapshot, actions) {
         }
         const approvalFlow = approvals.get(selected.id);
         if (approvalFlow) {
-            const rules = section('审批步骤与条件', '按下列顺序执行；条件不满足时跳过该组审批。');
-            const list = h('ol', 'business-approval-steps');
-            for (const group of approvalFlow.groups) {
-                const row = h('li');
-                if (group.condition)
-                    row.append(h('strong', '', `当${group.condition}时`));
-                for (const task of group.tasks) {
-                    row.append(h('strong', '', `${task.number}. ${task.title}`));
-                    row.append(h('p', '', `审批人：${task.actor} · ${task.rule}`));
+            const rules = section('审批步骤与条件', '顺序节点依次执行；并行分支同时开始，全部活动分支完成后汇合。条件在启动时判断。');
+            /** 阅读说明与图保持同一嵌套结构，编号只作定位，不把兄弟分支写成前后执行。 */
+            const describeGroups = (groups) => {
+                const list = h('ol', 'business-approval-steps');
+                for (const group of groups) {
+                    const row = h('li');
+                    if (group.condition)
+                        row.append(h('strong', '', `当${group.condition}时`));
+                    for (const task of group.tasks) {
+                        row.append(h('strong', '', `${task.number}. ${task.title}`));
+                        row.append(h('p', '', `审批人：${task.actor} · ${task.rule}`));
+                    }
+                    if (group.groups)
+                        row.append(describeGroups(group.groups));
+                    if (group.parallel) {
+                        row.append(h('strong', '', `${group.parallel.title} · AND 并行`));
+                        const branches = h('ul', 'business-approval-branches');
+                        for (const branch of group.parallel.branches) {
+                            const branchRow = h('li');
+                            branchRow.append(h('strong', '', branch.title), describeGroups(branch.groups));
+                            branches.append(branchRow);
+                        }
+                        row.append(branches, h('p', 'source-note', '各分支同时开始；全部活动分支完成 → AND 汇合后继续'));
+                    }
+                    if (group.condition)
+                        row.append(h('p', 'source-note', '条件不满足 → 跳过整组，继续后续步骤'));
+                    list.append(row);
                 }
-                if (group.condition)
-                    row.append(h('p', 'source-note', '条件不满足 → 跳过，继续后续步骤'));
-                list.append(row);
-            }
+                return list;
+            };
+            const list = describeGroups(approvalFlow.groups);
             rules.append(list, h('p', '', approvalFlow.route
                 ? '所需步骤全部通过后继续业务；任一步骤驳回则结束本轮审批。'
                 : '未抽取到绑定的审批步骤，请查看审批声明或外部流程配置。'));

package/graph-ui/graph-approvals.js

@@ -50,16 +50,29 @@ export function approvalFlowForStep(model, step, labels = {}) {
             ? `${fieldName(item.approver.field)}的负责人`
             : item.approver.kind === 'role'
                 ? (labels[`role:${item.approver.code}`] ?? '待命名审批角色')
-                : `指定用户 ${item.approver.userId}`,
-        rule: item.mode === 'all' ? '所有审批人同意后继续' : '任一审批人同意即可继续',
+                : item.approver.kind === 'field' ? `${fieldName(item.approver.field)}指定的审批人` : `指定用户 ${item.approver.userId}`,
+        rule: [item.mode === 'all' ? '所有审批人同意后继续' : item.actions?.addSign ? '任一原审批人同意' : '任一审批人同意即可继续',
+            ...(item.assignment === 'candidate' ? ['候选共享一项任务，领取后处理'] : []),
+            ...(item.actions?.addSign ? ['支持前签、后签和并行加签，全部加签人同意后继续'] : []),
+            ...(item.actions?.transfer ? ['允许转办'] : []), ...(item.actions?.delegate ? ['允许委派，归还后由原负责人决定'] : []),
+            ...(item.sla ? [`节点总时限 ${item.sla.durationMinutes} 自然分钟${item.sla.remindBeforeMinutes ? `，提前 ${item.sla.remindBeforeMinutes} 分钟提醒` : ''}；超时仅提醒`] : [])].join('；'),
         mode: item.mode,
     });
+    /** 条件内只有普通叶步骤时保留原协议；含嵌套条件/并行时保留树，避免旧图把分支误连成一条链。 */
+    const groups = (nodes) => nodes.map(item => {
+        if (item.kind === 'parallel')
+            return { tasks: [], parallel: { title: item.title,
+                    branches: item.branches.map(branch => ({ title: branch.title, groups: groups(branch.nodes) })) } };
+        if (item.kind === 'when')
+            return { condition: conditionName(item.cond),
+                ...(item.steps.every(node => node.kind === 'step' || node.kind === 'ai') ?
+                    { tasks: item.steps.map(node => task(node)) } : { tasks: [], groups: groups(item.steps) }) };
+        return { tasks: [task(item)] };
+    });
     return {
         approval,
         route,
-        groups: route.attrs.nodes.map((item) => item.kind !== 'when'
-            ? { tasks: [task(item)] }
-            : { condition: conditionName(item.cond), tasks: item.steps.map(task) }),
+        groups: groups(route.attrs.nodes),
     };
 }
 /** 从真实驳回结论绑定辨认出口，不依赖阶段标题里是否含有“驳回”二字。 */

package/graph-ui/graph-relations.js

@@ -4,6 +4,7 @@
  * 不求值 handler、映射或审批条件；存在连线只代表对应声明关系，不证明某次操作已发生。
  */
 import { kindLabels, nodeLabel } from './graph-model.js';
+import { approvalRouteNodes, approvalRouteSteps } from './approval-tree.js';
 /**
  * 按真实关系种类解释连线，补充声明来源和证据强度。
  * @param edge 已投影且两端有效的边。
@@ -76,13 +77,14 @@ export function explainEdge(edge, model, labels = {}) {
             const as = edge.as ?? '';
             if (as === '可路由字段')
                 return result('允许审批读取', '审批可用字段', `“${a}”把“${b}”列入 routable，允许该字段作为审批流程变量。`, '明确审批可以拿到哪些业务数据。这里只表示允许使用；是否真的参与分支或审批选人，要查看审批路由的字段关系。', [`${from.id}.routable 包含 ${field}`]);
+            if (as === '催办申请人')
+                return result('确定催办申请人', '流程运营依赖', `“${a}”以提交时“${b}”的用户标识确定可催办申请人。`, '字段必须进入 routable；催办仍校验当前对象可见性、运行节点、业务版本及冷却，不赋予审批权限。字段也可能被选人或条件使用，完整用途见路由声明。', [`route.reminders.requesterField = ${JSON.stringify(field)}`]);
             if (as === '路由条件') {
-                // fieldsUsed 同时包含 when 条件和 deptLeader 选人字段，不能一律解释成条件判断。
+                // fieldsUsed 同时包含 when 条件、部门负责人和单据人员字段，必须区分实际选人方式。
                 const nodes = from.attrs.nodes;
-                const conditions = nodes.filter((n) => n.kind === 'when' && n.cond.field === field);
-                const steps = nodes
-                    .flatMap((n) => (n.kind !== 'when' ? [n] : n.steps))
-                    .filter((s) => (s.approver ?? s.handoff)?.kind === 'deptLeader' && (s.approver ?? s.handoff)?.field === field);
+                const conditions = approvalRouteNodes(nodes).filter((n) => n.kind === 'when' && n.cond.field === field);
+                const steps = approvalRouteSteps(nodes).map(step => ({ ...step, selector: step.kind === 'ai' ? step.handoff : step.approver }))
+                    .filter(step => (step.selector.kind === 'deptLeader' || step.selector.kind === 'field') && step.selector.field === field);
                 const operators = {
                     gt: '大于',
                     gte: '大于等于',
@@ -93,11 +95,11 @@ export function explainEdge(edge, model, labels = {}) {
                     in: '属于',
                 };
                 const reasons = [
-                    ...steps.map((s) => `“${s.title}”步骤根据“${b}”找到对应部门的负责人`),
-                    ...conditions.map((n) => `当“${b}”${operators[n.cond.op]} ${JSON.stringify(n.cond.value)} 时，加入${n.steps.map((s) => `“${s.title}”`).join('、')}步骤`),
+                    ...steps.map((s) => s.selector.kind === 'field' ? `“${s.title}”步骤读取“${b}”保存的审批人员` : `“${s.title}”步骤根据“${b}”找到对应部门的负责人`),
+                    ...conditions.map((n) => `当“${b}”${operators[n.cond.op]} ${JSON.stringify(n.cond.value)} 时，加入${approvalRouteSteps(n.steps).map((s) => `“${s.title}”`).join('、')}步骤（内部顺序或并行关系见路由）`),
                 ];
                 return result(steps.length && conditions.length ? '选人和分支依据' : steps.length ? '确定审批人' : '判断审批分支', '审批路由依赖', `${reasons.join('；')}。`, '字段值会影响审批人或需要经过的审批步骤；修改字段含义时，应一起检查这些路由配置。', [
-                    ...steps.map((s) => `${s.title}: approver.deptLeader(${JSON.stringify(field)})`),
+                    ...steps.map((s) => `${s.title}: approver.${s.selector.kind}(${JSON.stringify(field)})`),
                     ...conditions.map((n) => `when(${n.cond.op}(${JSON.stringify(field)}, ${JSON.stringify(n.cond.value)}))`),
                 ]);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yss123/cage-cli",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "cage 命令行：init、gen、check、graph、context、impact、test、verify、budget、sync、upgrade、dev、migrate",
   "type": "module",
   "bin": {
@@ -31,11 +31,11 @@
     "typescript": "~5.9.3",
     "vitest": "^4.1.12",
     "zod": "^4.1.5",
-    "@yss123/cage-ontology": "0.3.0",
-    "@yss123/cage-admin": "0.3.0",
-    "@yss123/cage-kernel": "0.3.0",
-    "@yss123/cage-lint": "0.3.0",
-    "@yss123/cage-testkit": "0.3.0"
+    "@yss123/cage-ontology": "0.3.1",
+    "@yss123/cage-admin": "0.3.1",
+    "@yss123/cage-lint": "0.3.1",
+    "@yss123/cage-kernel": "0.3.1",
+    "@yss123/cage-testkit": "0.3.1"
   },
   "devDependencies": {
     "@types/pg": "^8.15.5"

package/templates/app/AGENTS.md

@@ -10,7 +10,7 @@
 
 本节位于托管区之外，cage sync 会保留。下面的托管区提供框架工作方法。
 
-<!-- cage:begin v0.3.0 -->
+<!-- cage:begin v0.3.1 -->
 ## Cage 业务开发约定（框架托管）
 
 ### 先读，再按需求改业务
@@ -85,7 +85,7 @@
 - 多页面业务必须有独立 URL，不用 useState/tab 模拟整页导航；详情从 URL 取 ID 并独立加载。前端路由集中在 app，页面从模块公开入口接入 Outlet。登录后保留原路径/query/hash，401 回登录，403 展示权限提示；/admin/ 使用普通链接进入独立系统管理。前端路由不替代后端授权。实现、SPA 部署回退和浏览器配方见 docs/ai/routing.md。
 - 跨聚合写入通过 reaction 调用命令。`tx: 'same'` 共同提交/回滚，默认 outbox 异步执行。资源 acquires/releases 是图规则标签，实际占用/释放仍由命令完成；离开持有状态要检查每条释放路径。
 - 批量调用同一命令使用 reactionEach，声明 maxItems、唯一排序字段 orderBy、items 和 map；稳定键排序后串行执行。步骤依赖用 order，同事件同事务分组不得混用有序/无序或重复顺序。保持同事务回滚边界，见 docs/ai/primitives.md。
-- 审批通过 approval + route 配置，结论是 process 命令；选中审批人不等于已具备能力、范围和额度。第三方 IO 通过连接器，回调验签后调用 external 命令。
+- 审批通过 approval + route 配置，结论是 process 命令；选中审批人不等于已具备能力、范围和额度。parallel(title, ...branch(...)) 声明结构化 AND：分支同时开始，内部顺序独立，全部活动分支完成后汇合；when 支持嵌套并仍按提交快照求值，声明有深度/数量边界，不支持任意跳转。currentSteps 表示当前活动节点集合，兼容字段 currentStep 只是最小活动索引，不能据此隐藏其他分支。人工节点 assignment: 'candidate' 开放候选领取/释放，approver.field 从 routable 字段选人；actions 开放转办、委派归还和前后/并行必签。任务操作与决定携带 revision，waiting 任务只能查看。approvalOperations() 为框架通用时效运行时：step.sla 配置自然分钟节点总时限，route.reminders 配置申请人催办；迁移并运行 worker 后提供持久站内提醒、已读与 Admin 通用页面，不自动批准或授予权限。政策、SDK 和边界见 docs/ai/approvals.md。第三方 IO 通过连接器，回调验签后调用 external 命令。
 - job 的读取与调用必须列入 reads/calls。业务导入/导出放在需要的业务页面调用通用任务接口，202 只代表任务已接受；worker 必须运行。
 - 已部署事件只做兼容扩展；新增字段设为 optional，不兼容含义用新事件。已执行/已发布迁移不能改写，结构更新新增迁移。
 - 不手改生成物，不关闭门禁掩盖错误，不因方便自动授予生产角色新能力。unsafe 必须写明 reason/owner，不能替代普通业务声明。

package/templates/app/README.md

@@ -59,10 +59,11 @@ pnpm dev
 1. 管理员在“库存台账”登记 `A-01` 等物料。
 2. 进入 `/admin/` 创建采购员、经理，分别分配采购命令和审批能力；经理的 `PurchaseOrder.approve` 参数配置 `ceiling`。
 3. 把经理设为采购员所在部门的负责人。提单人与审批人必须不同。
-4. 采购员新建并提交采购单；worker 建立审批待办。
-5. 经理在“审批待办”通过，内核同事务生成库存锁；worker 调用 fake ERP 并回写单号。
-6. 超过 50,000 元的采购走财务第二步，需另建 code 为 `finance` 的角色并分配审批人。
-7. 取消单据或收到 ERP 收货回调后，通过异步反应释放锁。回调需要 `ERP_WEBHOOK_SECRET` 对原始 JSON 的 HMAC-SHA256 签名。
+4. 为需要选人的采购参与者授予 `ApprovalMember.read` 与该聚合 `all` 范围，通过 `ApprovalMember.create` 登记审批协作人的公开业务姓名与专业领域；名录不授予实际审批能力。
+5. 采购员新建采购单，可开启专业复核并选择 1–5 人；草稿使用 `PurchaseOrder.setReviewers` 调整名单，提交时重新校验。worker 先执行 AI 材料预审；未配置模型或模型失败时按声明转人工接管。
+6. AI 预审/人工接管之后进入经理节点；启用专业复核时，经理后由所选人员全部会签。经理、专业和财务节点开放转办、委派归还和前置/后置/并行加签。
+7. 超过 50,000 元的采购继续进入财务共享候选池，需另建 code 为 `finance` 的角色并给实际用户配置权限、范围和额度；财务必须先领取，恰好 50,000 元跳过该步骤。
+8. 全部必签完成后，最终审批命令同事务生成库存锁；worker 调用 fake ERP 并回写单号。取消单据或收到 ERP 收货回调后异步释放锁；回调需要 `ERP_WEBHOOK_SECRET` 对原始 JSON 的 HMAC-SHA256 签名。
 
 `Inventory.available` 是演示台账数量。本例验证库存锁生命周期，尚未实现仓库级的并发扣减、实物库存及退货核算。
 

package/templates/app/apps/api/package.json

@@ -10,7 +10,7 @@
   },
   "dependencies": {
     "@app/domain": "workspace:*",
-    "@yss123/cage-http": "0.3.0",
-    "@yss123/cage-connectors": "0.3.0"
+    "@yss123/cage-http": "0.3.1",
+    "@yss123/cage-connectors": "0.3.1"
   }
 }

package/templates/app/apps/web/package.json

@@ -10,7 +10,7 @@
   "dependencies": {
     "@app/contracts": "workspace:*",
     "@tanstack/react-query": "^5.87.1",
-    "@yss123/cage-client": "0.3.0",
+    "@yss123/cage-client": "0.3.1",
     "react": "^19.1.1",
     "react-dom": "^19.1.1",
     "react-markdown": "^10.1.0",

package/templates/app/apps/web/src/modules/approval/components/task-operation-dialog.tsx

@@ -0,0 +1,61 @@
+/**
+ * 人工待办的转办、委派和三种加签操作表单，由审批收件箱按当前任务快照打开。
+ * 选择来自业务协作名录，提交携带任务 revision 和必填原因；权限/同节点重复责任由引擎重查。
+ * 失败保留选人和原因；成功刷新真实任务并关闭。等待/受托任务不从页面打开本表单，不在前端改流程状态。
+ */
+import { useState, type FormEvent } from 'react';
+import { client } from '@app/contracts';
+import type { ApprovalTask, ApprovalTaskAction } from '@yss123/cage-client';
+import { ApprovalMemberPicker } from '../../../shared/ui/approval-member-picker';
+import { errorMessage } from '../../../shared/lib/error-message';
+import { useQueryClient } from '@tanstack/react-query';
+
+/** 页面允许发起的人员管理操作，归还/领取/释放在任务行直接处理。 */
+export type PersonnelOperation = 'transfer' | 'delegate' | 'parallel' | 'before' | 'after';
+/** 业务名称与引擎 placement 对应；不引入额外执行步骤或暗示自动授予权限。 */
+const labels = { transfer: '转办审批', delegate: '委派协助', parallel: '并行加签', before: '前加签', after: '后加签' } as const;
+const descriptions = {
+  transfer: '将这项审批责任交给另一位人员，你将不再处理此任务。',
+  delegate: '请他人核对材料，受托人归还后仍由你决定。',
+  parallel: '你与新增人员可以同时处理，所有追加意见都是必签。',
+  before: '先请新增人员签署，全部完成后这项任务才回到你手中。',
+  after: '你先签署，随后激活新增人员的必签任务。',
+};
+
+/**
+ * task 与 operation 在打开时固定；任务变化以服务端冲突响应为准，不自动改用新版本重试。
+ * close 返回当前收件箱，成功通过查询缓存刷新；无效输入禁用提交，Esc/取消不产生写入。
+ */
+export function TaskOperationDialog({ task, operation, close }: { task: ApprovalTask; operation: PersonnelOperation; close: () => void }) {
+  const [userIds, setUserIds] = useState<string[]>([]), [reason, setReason] = useState('');
+  const [busy, setBusy] = useState(false), [error, setError] = useState('');
+  const cache = useQueryClient();
+  const single = operation === 'transfer' || operation === 'delegate';
+  /**
+   * 将人员选择映射为对应动作；每次携带打开弹窗时的 revision，旧任务冲突时保留输入供用户核对。
+   * 只在服务端确认成功后刷新并关闭，不能把选中人员或提交请求本身视为已经完成交接。
+   */
+  async function submit(event: FormEvent) {
+    event.preventDefault();
+    if (busy || !userIds.length || !reason.trim()) return;
+    setBusy(true); setError('');
+    const input: ApprovalTaskAction = single
+      ? { action: operation, targetUserId: userIds[0], reason, expectedRevision: task.revision }
+      : { action: 'addSign', placement: operation, userIds, reason, expectedRevision: task.revision };
+    const result = await client.approvalTaskAction(task.id, input);
+    setBusy(false);
+    if (!result.ok) { setError(errorMessage(result)); return; }
+    await cache.invalidateQueries(); close();
+  }
+  return <div className="modal-backdrop"><section className="modal approval-operation-dialog" role="dialog" aria-modal="true" aria-labelledby="approval-operation-title"
+    onKeyDown={event => { if (event.key === 'Escape' && !busy) close(); }}>
+    <div className="section-head"><div><h2 id="approval-operation-title">{labels[operation]}</h2><p className="muted">{task.title}</p></div>
+      <button type="button" disabled={busy} onClick={close} aria-label="关闭操作">×</button></div>
+    <form onSubmit={submit}><p>{descriptions[operation]}</p>
+      <ApprovalMemberPicker value={userIds} onChange={setUserIds} max={single ? 1 : 20} exclude={[task.assigneeId, task.ownerId].filter((id): id is string => !!id)} disabled={busy} />
+      <label>操作原因<textarea autoFocus rows={3} maxLength={1000} required value={reason} disabled={busy} onChange={event => setReason(event.target.value)} placeholder="说明业务原因，供单据参与者查看" /></label>
+      {error && <p className="error" role="alert">{error}</p>}
+      <div className="actions"><button type="button" disabled={busy} onClick={close}>取消</button><button className="primary" disabled={busy || !userIds.length || !reason.trim()}>{busy ? '提交中…' : `确认${labels[operation]}`}</button></div>
+    </form>
+  </section></div>;
+}

package/templates/app/apps/web/src/modules/approval/hooks/use-approval-tasks.ts

@@ -1,29 +1,26 @@
 /**
- * 当前账号审批待办的共享查询入口，供审批页及 app 的数量组合复用同一缓存键。
+ * 当前账号本人、候选或等待加签任务的共享查询入口，默认待办供 app 数量组合复用。
  * 任务分配与实际决策授权均来自服务端，不从角色名称在前端自行推导。
  */
 import { useQuery } from '@tanstack/react-query';
 import { client } from '@app/contracts';
 import { errorMessage } from '../../../shared/lib/error-message';
 
-/**
- * 待办列表展示所需字段：id 是任务标识，businessKey 是业务记录键，title 为任务标题，createdAt 为创建时间字符串。
- */
-type Task = { id: string; businessKey: string; title: string; createdAt: string };
-
 /**
  * 审批是框架通用接口，不属于某个聚合的生成方法，因此请求封装在审批模块内。
  * 待办页面和导航角标复用同一缓存键，调用方不需要了解接口地址或响应形状。
  */
 /**
  * 在 React Query 中读取审批待办，非 ok 结果转为查询错误。
+ * view 默认 pending，与导航角标共享；candidates/waiting 使用独立缓存，不混入可决定的任务数量。
  * 返回查询状态及 refetch；空数组表示当前结果没有待办，未加载或失败不等同于零条。
  */
-export function useApprovalTasks() {
+export function useApprovalTasks(view: 'pending' | 'candidates' | 'waiting' = 'pending') {
   return useQuery({
-    queryKey: ['tasks'],
+    queryKey: ['tasks', view],
     queryFn: async () => {
-      const result = await client.get<Task[]>('/api/approval/tasks');
+      // 使用框架任务协议保留 revision，避免页面决定丢失任务流转后的并发校验。
+      const result = await (view === 'candidates' ? client.approvalCandidateTasks() : client.approvalTasks(view));
       if (!result.ok) throw new Error(errorMessage(result));
       return result.data;
     },