@yss123/cage-cli 0.2.0 → 0.3.0

package/graph-ui/graph-approvals.js

@@ -0,0 +1,79 @@
+/** 只展开阶段的主要审批。details 中作为实现依据出现的审批不代表此处执行审批；
+ * 取消动作也不能被画成重新走一轮审批。步骤顺序完全来自绑定的 route。 */
+/**
+ * 为业务步骤提取主要审批的路线，不展开仅作为 details 的旁证审批。
+ * @param model 语义图。
+ * @param step 当前阅读步骤，取消和对象关联返回 undefined。
+ * @param labels 字段、状态与角色中文覆盖。
+ * @returns 审批与按顺序分组的任务；不运行条件、不选人、不检查授权。
+ */
+export function approvalFlowForStep(model, step, labels = {}) {
+    if (step.label === '取消审批' || step.mode === 'association')
+        return undefined;
+    const approval = step.node.kind === 'approval'
+        ? step.node
+        : step.node.kind === 'stage'
+            ? model.nodes.find((n) => n.kind === 'approval' && n.key === step.node.attrs.primary)
+            : undefined;
+    if (!approval)
+        return undefined;
+    const route = model.nodes.find((n) => n.kind === 'route' &&
+        model.edges.some((e) => e.kind === 'binds' && e.from === n.key && e.to === approval.key));
+    if (!route)
+        return { approval, groups: [] };
+    const owner = String(approval.attrs.aggregate);
+    const fieldName = (field) => labels[`field:${owner}.${field}`] ?? '待命名字段';
+    const valueName = (value) => typeof value === 'number'
+        ? value.toLocaleString('zh-CN', { maximumFractionDigits: 20 })
+        : typeof value === 'boolean'
+            ? value
+                ? '是'
+                : '否'
+            : (labels[`state:${owner}.${value}`] ?? value);
+    const conditionName = (condition) => {
+        const field = fieldName(condition.field);
+        if (condition.op === 'eq' && condition.value === true)
+            return field;
+        const op = { gt: '大于', gte: '大于等于', lt: '小于', lte: '小于等于', eq: '为', ne: '不为', in: '属于' };
+        const value = Array.isArray(condition.value)
+            ? condition.value.map(valueName).join('、')
+            : valueName(condition.value);
+        return `${field}${op[condition.op]}${value}`;
+    };
+    let number = 0;
+    const task = (item) => item.kind === 'ai' ? {
+        number: ++number, title: item.title, actor: 'AI 审核', rule: '通过继续；退回修改结束本轮；转人工由本节点接管人处理', mode: 'any',
+    } : ({
+        number: ++number,
+        title: item.title,
+        actor: item.approver.kind === 'deptLeader'
+            ? `${fieldName(item.approver.field)}的负责人`
+            : item.approver.kind === 'role'
+                ? (labels[`role:${item.approver.code}`] ?? '待命名审批角色')
+                : `指定用户 ${item.approver.userId}`,
+        rule: item.mode === 'all' ? '所有审批人同意后继续' : '任一审批人同意即可继续',
+        mode: item.mode,
+    });
+    return {
+        approval,
+        route,
+        groups: route.attrs.nodes.map((item) => item.kind !== 'when'
+            ? { tasks: [task(item)] }
+            : { condition: conditionName(item.cond), tasks: item.steps.map(task) }),
+    };
+}
+/** 从真实驳回结论绑定辨认出口，不依赖阶段标题里是否含有“驳回”二字。 */
+/**
+ * 用真实 onRejected 绑定辨认驳回出口，不从标题猜测。
+ * @param flow 当前审批投影。
+ * @param target 待检查的命令或业务阶段。
+ * @returns 目标主要命令是否等于驳回结论，纯计算无副作用。
+ */
+export function isApprovalRejection(flow, target) {
+    const command = target.node.kind === 'command'
+        ? target.node.key
+        : target.node.kind === 'stage'
+            ? target.node.attrs.primary
+            : undefined;
+    return command === `command:${flow.approval.attrs.onRejected}`;
+}

package/graph-ui/graph-business.js

@@ -0,0 +1,403 @@
+/**
+ * 把语义图整理为业务板块、显式流程、对象生命周期和操作触发树。
+ * 供图谱浏览器使用，优先采用 businessProcess 声明，旧项目按模块或聚合归属组织。
+ * 所有投影只辅助阅读，不调度操作；状态迁移、读取依赖、声明调用能力与真实自动触发分别处理。
+ */
+import { nodeLabel } from './graph-model.js';
+/**
+ * 识别 User、Role、Dept 及其成员的系统组织前缀，供默认隐藏开关使用；不表示权限检查。
+ */
+export const isSystemObject = (node) => /^(User|Role|Dept)(\.|$)/.test(node.id);
+/**
+ * 只对有明确标识归属的节点寻找聚合，取最长匹配前缀。
+ * @param model 语义图。
+ * @param node 待定位节点。
+ * @returns 聚合或 undefined；事件/查询等任意名称不会按前缀误归属。
+ */
+export function businessOwner(model, node) {
+    if (node.kind === 'aggregate')
+        return node;
+    // 查询、事件等可任意命名，不能凭同名前缀把它们归入某个对象。
+    if (!['command', 'state', 'field', 'capability', 'entry'].includes(node.kind))
+        return undefined;
+    return model.nodes
+        .filter((n) => n.kind === 'aggregate' && node.id.startsWith(`${n.id}.`))
+        .sort((a, b) => b.id.length - a.id.length)[0];
+}
+/** 板块只组织展示，不新增本体关系。模块目录提供归属，旧的平铺项目按对象分组；
+ * 查询与任务允许出现在多个相关板块，但不会沿读取关系扩散出一整张业务图。 */
+/**
+ * 按显式业务区、模块路径或聚合整理板块，并附声明相关查询与任务。
+ * @param model 语义图，不被修改。
+ * @param labels 显示覆盖。
+ * @param showSystem 是否保留系统组织对象。
+ * @returns 稳定排序的板块；同一操作可出现在多个相关板块，不表示重复执行。
+ */
+export function businessBlocks(model, labels = {}, showSystem = false) {
+    const blocks = new Map();
+    const owners = new Map();
+    const commands = model.nodes.filter((n) => n.kind === 'command');
+    const count = (n) => commands.filter((c) => businessOwner(model, c)?.key === n.key).length;
+    const objects = model.nodes
+        .filter((n) => n.kind === 'aggregate')
+        .sort((a, b) => count(b) - count(a) || a.id.localeCompare(b.id));
+    const processes = model.nodes.filter((n) => n.kind === 'process');
+    for (const node of objects) {
+        const system = isSystemObject(node);
+        if (system && !showSystem)
+            continue;
+        const module = node.file?.replaceAll('\\', '/').match(/(?:^|\/)modules\/([^/]+)\//)?.[1];
+        const process = processes.find((p) => p.attrs.subject === node.id);
+        const area = process?.attrs.area;
+        const id = system
+            ? 'system:organization'
+            : area
+                ? `module:${area.id}`
+                : module
+                    ? `module:${module}`
+                    : node.key;
+        let block = blocks.get(id);
+        if (!block) {
+            block = {
+                id,
+                title: system ? '组织与权限' : (area?.title ?? businessLabel(node, labels)),
+                description: area?.description,
+                objects: [],
+                flows: [],
+                processes: [],
+                system,
+            };
+            blocks.set(id, block);
+        }
+        block.objects.push(node);
+        owners.set(node.id, block);
+    }
+    for (const block of blocks.values()) {
+        block.title = labels[block.id] || block.title;
+    }
+    for (const process of processes) {
+        const subject = model.nodes.find((n) => n.kind === 'aggregate' && n.id === process.attrs.subject);
+        if (subject && isSystemObject(subject) && !showSystem)
+            continue;
+        const area = process.attrs.area;
+        const id = `module:${area.id}`;
+        let block = blocks.get(id);
+        if (!block) {
+            block = {
+                id,
+                title: labels[id] || area.title,
+                description: area.description,
+                objects: [],
+                flows: [],
+                processes: [],
+                system: false,
+            };
+            blocks.set(id, block);
+        }
+        block.title = labels[id] || area.title;
+        block.description = area.description;
+        block.processes.push(process);
+    }
+    const byKey = new Map(model.nodes.map((n) => [n.key, n]));
+    for (const node of model.nodes) {
+        if (!['command', 'query', 'job', 'inbound'].includes(node.kind))
+            continue;
+        const related = new Set();
+        const addOwner = (target) => {
+            const owner = target && businessOwner(model, target);
+            const block = owner && owners.get(owner.id);
+            if (block)
+                related.add(block);
+        };
+        addOwner(node);
+        for (const edge of model.edges) {
+            if (edge.from !== node.key || !['queries', 'calls', 'targets'].includes(edge.kind))
+                continue;
+            addOwner(byKey.get(edge.to));
+        }
+        // 组织模型在开关关闭时不借“其他业务”重新出现。
+        if (!related.size && businessOwner(model, node) && !showSystem)
+            continue;
+        if (!related.size) {
+            const belongsToHiddenSystem = model.edges.some((e) => e.from === node.key &&
+                ['queries', 'calls', 'targets'].includes(e.kind) &&
+                isSystemObject(byKey.get(e.to)));
+            if (belongsToHiddenSystem && !showSystem)
+                continue;
+            const id = 'other:collaboration';
+            if (!blocks.has(id))
+                blocks.set(id, {
+                    id,
+                    title: '其他业务协作',
+                    objects: [],
+                    flows: [],
+                    processes: [],
+                    system: false,
+                });
+            related.add(blocks.get(id));
+        }
+        for (const block of related)
+            block.flows.push(node);
+    }
+    for (const block of blocks.values())
+        block.flows.sort((a, b) => {
+            const rank = (n) => n.kind !== 'command'
+                ? 3
+                : n.attrs.from === 'new'
+                    ? 0
+                    : n.attrs.invokedBy?.includes('user')
+                        ? 1
+                        : 2;
+            return (rank(a) - rank(b) ||
+                (a.file ?? '').localeCompare(b.file ?? '') ||
+                (a.line ?? 0) - (b.line ?? 0) ||
+                a.id.localeCompare(b.id));
+        });
+    return [...blocks.values()].sort((a, b) => Number(a.system) - Number(b.system) || b.flows.length - a.flows.length || a.id.localeCompare(b.id));
+}
+/** 业务页面缺少文案时明确提示补充，不用程序标识替代业务名称。完整本体仍保留标识。 */
+/**
+ * 优先使用中文覆盖与声明文案，缺失时明确显示待命名。
+ * @param node 展示节点。
+ * @param labels 中文标签映射。
+ * @returns 阅读标题，不改实际标识。
+ */
+export function businessLabel(node, labels = {}) {
+    if (node.kind === 'entry')
+        return '新建业务';
+    if (labels[node.key] || node.attrs.title || node.attrs.description)
+        return nodeLabel(node, labels);
+    return `待命名${{ aggregate: '业务对象', command: '操作', state: '状态', process: '流程', stage: '阶段', event: '业务结果', reaction: '自动处理', approval: '审批', inbound: '外部通知', outbound: '外部同步', query: '查询', job: '定时处理' }[node.kind] ?? '声明'}`;
+}
+/**
+ * 优先返回板块显式流程并保持源码顺序；没有流程规格时返回有状态迁移的对象供生命周期阅读。
+ */
+export const businessJourneys = (block, model) => block.processes.length
+    ? [...block.processes].sort((a, b) => (a.file ?? '').localeCompare(b.file ?? '') ||
+        (a.line ?? 0) - (b.line ?? 0) ||
+        a.id.localeCompare(b.id))
+    : block.objects.filter((object) => model.edges.some((e) => e.kind === 'transition' && e.to.startsWith(`state:${object.id}.`)));
+/** 显式流程的阶段是唯一身份。汇合与循环回连已有阶段，避免复制成多份业务。 */
+/**
+ * 把显式流程阶段组织成阅读树，汇合/循环只保留回连标记。
+ * @param model 语义图。
+ * @param process 已声明业务流程。
+ * @param options branches 控制次要分支，related 控制对象关联。
+ * @returns 流程入口树；关联不充当下一步，遍历不执行命令。
+ */
+export function traceBusinessProcess(model, process, options) {
+    const nodes = new Map(model.nodes.map((n) => [n.key, n]));
+    const seen = new Set();
+    const walk = (key, incoming) => {
+        const node = nodes.get(key);
+        const repeated = seen.has(key);
+        const mode = incoming?.mode;
+        const step = {
+            id: repeated ? `${incoming.from}>${key}` : key,
+            node,
+            via: model.edges.filter((e) => e.from === key && e.kind === 'implements').map((e) => nodes.get(e.to)),
+            label: incoming
+                ? `${{ manual: '人工', automatic: '自动', wait: '等待' }[mode]} · ${incoming.label}`
+                : '流程起点',
+            note: mode === 'automatic'
+                ? '由实际声明触发；执行条件、事务与映射以实现为准。'
+                : mode === 'wait'
+                    ? '等待外部通知或定时处理，流程图本身不发起调用。'
+                    : '由参与人发起，仍需通过权限和业务规则检查。',
+            mode,
+            branch: incoming?.branch,
+            children: [],
+            repeated,
+            boundary: false,
+        };
+        if (repeated)
+            return step;
+        seen.add(key);
+        step.children = model.edges
+            .filter((e) => e.kind === 'follows' && e.from === key && (options.branches || !e.branch))
+            .map((e) => walk(e.to, e));
+        if (options.related)
+            for (const relation of model.edges.filter((e) => e.kind === 'relates' && e.from === key)) {
+                const object = nodes.get(relation.to);
+                step.children.push({
+                    id: `${key}>${object.key}`,
+                    node: object,
+                    via: relation.via && nodes.has(relation.via) ? [nodes.get(relation.via)] : [],
+                    label: relation.label ?? '关联对象',
+                    note: '业务对象关联；不表示下一步操作或额外触发。',
+                    mode: 'association',
+                    children: [],
+                    repeated: false,
+                    boundary: false,
+                });
+            }
+        return step;
+    };
+    return walk(`stage:${process.attrs.entry}`);
+}
+/** 旧项目按实际状态迁移阅读；只表达允许的操作，绝不推断成自动调用链。 */
+/**
+ * 对没有业务流程规格的对象沿允许状态迁移生成阅读树。
+ * @param model 语义图。
+ * @param object 目标聚合。
+ * @param labels 中文文案。
+ * @returns 从新建入口或初始状态开始的树；只表示允许操作，不推断自动触发。
+ */
+export function traceBusinessLifecycle(model, object, labels) {
+    const nodes = new Map(model.nodes.map((n) => [n.key, n]));
+    const seen = new Set();
+    const entry = nodes.get(`entry:${object.id}.[new]`) ??
+        model.nodes.find((n) => n.kind === 'state' && n.id.startsWith(`${object.id}.`) && n.attrs.initial);
+    const walk = (node, via = [], parent = '') => {
+        const repeated = seen.has(node.key);
+        const action = via[0];
+        const actor = (action?.attrs.invokedBy ?? []);
+        const label = action
+            ? `${actor.includes('user') ? '人工' : actor.includes('external') ? '外部通知' : actor.includes('process') ? '审批结论' : '业务操作'} · ${businessLabel(action, labels)}`
+            : '生命周期起点';
+        const step = {
+            id: repeated ? `${parent}>${node.key}` : node.key,
+            node,
+            via,
+            label,
+            note: '根据已声明状态迁移整理，表示允许执行的操作；条件与触发方式请查看实现。',
+            mode: 'lifecycle',
+            repeated,
+            boundary: false,
+            children: [],
+        };
+        if (repeated)
+            return step;
+        seen.add(node.key);
+        step.children = model.edges
+            .filter((e) => e.kind === 'transition' && e.from === node.key)
+            .map((e) => walk(nodes.get(e.to), [nodes.get(`command:${e.via}`)], node.key));
+        return step;
+    };
+    return walk(entry);
+}
+/** 只沿会驱动后续操作的声明追踪。状态可达性和 reads 均不当作调用顺序。
+ * 事件与反应收进步骤的实现依据，但保留事务、条件映射、取消及审批结论语义。 */
+/**
+ * 沿事件、反应、审批结论及外部回写构建有界操作树。
+ * @param model 语义图。
+ * @param root 完整节点 key。
+ * @param maxDepth 默认 6，另以累计步骤计数限制膨胀。
+ * @returns 入口树或 undefined；取消审批停止展开，循环/上限通过 repeated/boundary 显示。
+ */
+export function traceBusinessFlow(model, root, maxDepth = 6) {
+    const nodes = new Map(model.nodes.map((n) => [n.key, n]));
+    const outgoing = (key) => model.edges.filter((e) => e.from === key && !e.derived);
+    const next = (node) => {
+        const result = [];
+        const add = (key, via, label, note = '') => {
+            const target = nodes.get(key);
+            if (target)
+                result.push({ node: target, via, label, note });
+        };
+        for (const edge of outgoing(node.key)) {
+            const target = nodes.get(edge.to);
+            if (node.kind === 'command' && edge.kind === 'emits') {
+                const effects = outgoing(target.key).filter((e) => ['triggers', 'cancels'].includes(e.kind));
+                if (!effects.length)
+                    add(target.key, [], '成功后产生的结果');
+                for (const effect of effects) {
+                    const handler = nodes.get(effect.to);
+                    if (effect.kind === 'cancels') {
+                        add(handler.key, [target], '取消审批', '该分支终止审批，不继续执行审批结论。');
+                    }
+                    else if (handler.kind === 'reaction') {
+                        for (const call of outgoing(handler.key).filter((e) => e.kind === 'targets')) {
+                            add(call.to, [target, handler], handler.attrs.tx === 'same' ? '成功后 · 同一事务' : '成功后 · 异步处理', '是否调用及输入由映射函数决定；返回 null 时跳过。');
+                        }
+                    }
+                    else {
+                        add(handler.key, [target], handler.kind === 'approval' ? '成功后 · 异步启动审批' : '成功后 · 异步外部同步');
+                    }
+                }
+            }
+            else if (node.kind === 'approval' && edge.kind === 'binds' && target.kind === 'command') {
+                add(target.key, [], node.attrs.onApproved === target.id ? '审批通过时' : '审批驳回时', '审批结论仍须通过目标业务操作的权限与规则检查。');
+            }
+            else if (node.kind === 'outbound' && edge.kind === 'targets' && target.kind === 'command') {
+                add(target.key, [], '外部调用成功后回写');
+            }
+            else if (node.kind === 'inbound' && edge.kind === 'targets' && target.kind === 'command') {
+                add(target.key, [], '验签与映射后');
+            }
+            else if (node.kind === 'job' && edge.kind === 'calls') {
+                add(target.key, [], '任务声明可调用', '实际调用条件和次数由任务实现决定。');
+            }
+            else if (node.kind === 'reaction' && edge.kind === 'targets') {
+                add(target.key, [], node.attrs.tx === 'same' ? '同一事务' : '异步处理', '是否调用由映射函数决定。');
+            }
+            else if (node.kind === 'event' && edge.kind === 'triggers') {
+                add(target.key, [], '结果触发的后续处理');
+            }
+        }
+        return result;
+    };
+    let count = 0;
+    const walk = (item, path, seen, depth) => {
+        const nextPath = [...path, ...item.via.map((n) => n.key), item.node.key];
+        const id = nextPath.join('>');
+        const repeated = seen.has(item.node.key);
+        // 取消审批是终止动作，不能再展示“通过/驳回”的后续调用。
+        const children = item.label === '取消审批' ? [] : next(item.node);
+        const boundary = !repeated && children.length > 0 && (depth >= maxDepth || count >= 60);
+        count++;
+        const step = { ...item, id, children: [], repeated, boundary };
+        if (!repeated && !boundary) {
+            const visited = new Set([...seen, item.node.key]);
+            step.children = children.map((child) => walk(child, nextPath, visited, depth + 1));
+        }
+        return step;
+    };
+    const node = nodes.get(root);
+    return node && walk({ node, via: [], label: '业务入口', note: '' }, [], new Set(), 0);
+}
+/**
+ * 按先序把已经有界的阅读树展开成列表。
+ * @param root 由追踪函数生成的根。
+ * @returns 包含重复引用占位节点的数组，不去重、不执行关系。
+ */
+export function flattenBusinessSteps(root) {
+    return [root, ...root.children.flatMap(flattenBusinessSteps)];
+}
+/**
+ * 把命令 from/to 转成中文状态摘要。
+ * @param node 非命令返回空字符串。
+ * @param labels 状态名称覆盖。
+ * @returns 允许起始状态与目标，to=null 描述保持当前状态。
+ */
+export function businessStateSummary(node, labels) {
+    if (node.kind !== 'command')
+        return '';
+    const owner = node.id.slice(0, node.id.lastIndexOf('.'));
+    const name = (s) => (s === 'new' ? '新建' : (labels[`state:${owner}.${s}`] ?? '待命名状态'));
+    const from = (Array.isArray(node.attrs.from) ? node.attrs.from : [node.attrs.from]);
+    return `${from.filter(Boolean).map(name).join(' / ')} → ${node.attrs.to == null ? '保持当前状态' : name(String(node.attrs.to))}`;
+}
+/**
+ * 把已知约束名翻译为业务提示，并解析额度与职责分离字段。
+ * @param name 内核约束标识。
+ * @param owner 所属聚合 ID。
+ * @param labels 字段中文标签。
+ * @returns 展示文案，未知约束保留原名，不求值或授予能力。
+ */
+export function businessConstraintLabel(name, owner, labels) {
+    const field = (id) => labels[`field:${owner}.${id}`] ?? id;
+    const ceiling = /^ceiling\((.+)\)$/.exec(name);
+    if (ceiling)
+        return `${field(ceiling[1])}不超过审批额度`;
+    const sod = /^sod\.notSameAs\((.+)\)$/.exec(name);
+    if (sod)
+        return `审批人与${field(sod[1])}不同`;
+    return ({
+        stepUp: '需要二次认证',
+        knownCapability: '能力点必须已声明',
+        noEscalation: '不能授予超出自身的能力',
+        noWiderScope: '不能授予超出自身的数据范围',
+        noEscalationViaRoles: '不能通过分配角色提权',
+    }[name] ?? name);
+}

package/graph-ui/graph-model.js

@@ -1,3 +1,6 @@
+/**
+ * 节点类型的固定中文词汇，CLI 报告和浏览器共用；只影响呈现，不改变本体 kind。
+ */
 export const kindLabels = {
     aggregate: '业务对象',
     command: '命令',
@@ -14,7 +17,12 @@ export const kindLabels = {
     state: '状态',
     capability: '能力点',
     entry: '新建入口',
+    process: '业务流程',
+    stage: '业务阶段',
 };
+/**
+ * 本体及展示归属边的中文短名，未知扩展关系由具体解释层处理。
+ */
 export const edgeLabels = {
     transition: '状态迁移',
     reads: '读取',
@@ -29,14 +37,29 @@ export const edgeLabels = {
     binds: '审批绑定',
     field: '声明字段',
     ownership: '归属（标识推导）',
+    contains: '包含业务阶段',
+    implements: '阶段实现',
+    follows: '业务下一步',
+    relates: '关联业务对象',
 };
 /** graph.labels 的显示覆盖不参与本体哈希；声明内的 description 仍由抽取器
  * 按该声明的含义处理。中文展示不会替换路由、权限或数据表使用的稳定标识。 */
+/**
+ * 按显示覆盖、标题、description、原 ID 的顺序选择文案。
+ * @param node 展示节点，虚拟 entry 固定使用新建入口文案。
+ * @param labels 仅用于显示的中文映射。
+ * @returns 展示名称，不修改节点或业务标识。
+ */
 export function nodeLabel(node, labels = {}) {
     if (node.kind === 'entry')
         return '新建入口';
-    return labels[node.key] || String(node.attrs.description || node.id);
+    return labels[node.key] || String(node.attrs.title || node.attrs.description || node.id);
 }
+/**
+ * 将本体 ID 按关系端点类型转成唯一 key，并补新建入口及归属边。
+ * @param graph 原始本体，不会被修改。
+ * @returns 新展示模型；无法匹配两端的关系不输出，派生 ownership 不代表调用。
+ */
 export function projectGraph(graph) {
     const nodes = graph.nodes.map((n) => ({ ...n, key: `${n.kind}:${n.id}` }));
     const edges = [];
@@ -61,11 +84,15 @@ export function projectGraph(graph) {
             ['approval', 'command'],
         ],
         uses: [['command', 'event', 'query', 'approval', 'route', 'outbound'], ['field']],
+        contains: [['process'], ['stage']],
+        implements: [['stage'], ['command', 'event', 'reaction', 'query', 'approval', 'job', 'inbound', 'outbound']],
+        follows: [['stage'], ['stage']],
+        relates: [['process', 'stage'], ['aggregate']],
     };
     for (const edge of graph.edges) {
         const [fromKinds, toKinds] = endpoints[edge.kind];
-        let from = find(edge.from, fromKinds);
-        const to = find(edge.to, toKinds);
+        let from = find(edge.from, edge.fromKind ? [edge.fromKind] : fromKinds);
+        const to = find(edge.to, edge.toKind ? [edge.toKind] : toKinds);
         if (!from && edge.kind === 'transition' && edge.from.endsWith('.[new]')) {
             from = { key: `entry:${edge.from}`, id: edge.from, kind: 'entry', hash: '', attrs: {} };
             nodes.push(from);
@@ -88,6 +115,12 @@ export function projectGraph(graph) {
     }
     return { nodes, edges };
 }
+/**
+ * 计算节点的一跳无向邻域，供画布高亮。
+ * @param model 展示图。
+ * @param key 完整节点身份。
+ * @returns 包含自身和直接邻居的集合；不继续传递，不区分执行方向。
+ */
 export function neighborhood(model, key) {
     const connected = new Set([key]);
     for (const edge of model.edges) {

package/graph-ui/graph-relations.js

@@ -1,4 +1,16 @@
+/**
+ * 将每种本体连线翻译为中文原因、用途、方向与证据，供 CLI 和浏览器详情复用。
+ * 解释基于投影端点及已抽取属性，分别标注显式声明、规则推导与文本匹配。
+ * 不求值 handler、映射或审批条件；存在连线只代表对应声明关系，不证明某次操作已发生。
+ */
 import { kindLabels, nodeLabel } from './graph-model.js';
+/**
+ * 按真实关系种类解释连线，补充声明来源和证据强度。
+ * @param edge 已投影且两端有效的边。
+ * @param model 展示图，提供端点和辅助声明。
+ * @param labels 中文名称覆盖。
+ * @returns 中文解释；只读元数据，不执行审批、映射、查询或业务命令。
+ */
 export function explainEdge(edge, model, labels = {}) {
     const from = model.nodes.find((n) => n.key === edge.from);
     const to = model.nodes.find((n) => n.key === edge.to);
@@ -20,6 +32,16 @@ export function explainEdge(edge, model, labels = {}) {
         direction: `“${a}” → “${b}”：${label}。`,
     });
     switch (edge.kind) {
+        case 'contains':
+            return result('包含业务阶段', '业务流程', `“${a}”声明了“${b}”阶段。`, '组织完整业务过程；阶段本身不执行命令。', [`${from.id}.stages → ${to.id}`]);
+        case 'implements':
+            return result('阶段实现', '实现依据', `“${a}”引用“${b}”作为实现。`, '从业务阶段追到实际声明；引用顺序不表示执行顺序。', [`${from.id}.action / details → ${to.id}`]);
+        case 'follows': {
+            const mode = { manual: '人工下一步', automatic: '自动触发', wait: '等待后继续' }[edge.mode ?? 'manual'];
+            return result(edge.label ?? mode, mode, `“${a}” → “${b}”：${edge.label}（${mode}）。`, edge.mode === 'automatic' ? '检查实际触发链是否存在；映射条件、事务和权限仍以引用的实现为准。' : '这是业务规格中的后续步骤，不会自动调度目标操作。', [`${from.attrs.process}.transitions`, `mode: ${edge.mode}`]);
+        }
+        case 'relates':
+            return result(edge.label ?? '关联业务对象', '业务关联', `“${a}”关联“${b}”：${edge.label}。`, '展示这个环节涉及的业务对象；数据引用、读取和写入由对应实现决定。', [edge.via ?? `${from.id}.subject`]);
         case 'field':
             return result(to.attrs.virtual ? '声明关联字段' : '包含字段', '数据结构', `“${a}”的字段声明中包含“${b}”。`, to.attrs.virtual
                 ? '这是 fields 中的集合关系，不占主表列；点击它指向目标的连线，查看关系基数、存储和读写方式。'
@@ -59,8 +81,8 @@ export function explainEdge(edge, model, labels = {}) {
                 const nodes = from.attrs.nodes;
                 const conditions = nodes.filter((n) => n.kind === 'when' && n.cond.field === field);
                 const steps = nodes
-                    .flatMap((n) => (n.kind === 'step' ? [n] : n.steps))
-                    .filter((s) => s.approver.kind === 'deptLeader' && s.approver.field === field);
+                    .flatMap((n) => (n.kind !== 'when' ? [n] : n.steps))
+                    .filter((s) => (s.approver ?? s.handoff)?.kind === 'deptLeader' && (s.approver ?? s.handoff)?.field === field);
                 const operators = {
                     gt: '大于',
                     gte: '大于等于',
@@ -122,17 +144,25 @@ export function explainEdge(edge, model, labels = {}) {
                 edge.acquires ? `获取“${resource(edge.acquires)}”` : '',
                 edge.releases ? `释放“${resource(edge.releases)}”` : '',
             ].filter(Boolean);
-            return result('调用业务命令', '反应调用', `“${a}”把事件映射后交给“${b}”处理。`, `将后续业务操作交给受约束的命令执行。${resources.length ? `此声明还标记${resources.join('、')}，用于检查资源获取与释放是否成对。` : ''}`, [`${from.id}.command → ${to.id}`, ...resources]);
+            const collection = from.attrs.collection;
+            const execution = [
+                from.attrs.tx === 'same' ? '同一事务，任意一项失败共同回滚' : '异步投递',
+                from.attrs.order !== null && from.attrs.order !== undefined ? `步骤顺序 ${from.attrs.order}` : '',
+                collection ? `最多 ${collection.maxItems} 项，按 ${collection.orderBy} 排序，串行调用` : '',
+            ].filter(Boolean);
+            return result('调用业务命令', '反应调用', `“${a}”把事件映射后交给“${b}”处理。`, `将后续业务操作交给受约束的命令执行。${execution.join('；')}。${resources.length ? `此声明还标记${resources.join('、')}，用于检查资源获取与释放是否成对。` : ''}`, [`${from.id}.command → ${to.id}`, ...execution, ...resources]);
         }
         case 'binds': {
             if (from.kind === 'route')
                 return result('定义审批步骤', '流程配置', `“${a}”与“${b}”使用同一流程标识 ${from.attrs.process}。`, '这份路由定义流程里的审批步骤、选人方式和条件分支，供代码内审批引擎使用。', [`process: ${from.attrs.process}`]);
             const approved = from.attrs.onApproved === to.id;
             const rejected = from.attrs.onRejected === to.id;
-            const outcome = approved && rejected ? '结束' : approved ? '通过' : '驳回';
+            const returned = from.attrs.onReturned === to.id;
+            const outcome = approved && rejected ? '结束' : approved ? '通过' : returned ? '退回修改' : '驳回';
             return result(`${outcome}后执行`, '审批结论回写', `“${a}”${outcome}时绑定执行“${b}”。`, '将审批结论交给业务命令推进单据状态，并统一执行权限和业务约束。', [
                 approved ? `${from.id}.onApproved → ${to.id}` : '',
                 rejected ? `${from.id}.onRejected → ${to.id}` : '',
+                returned ? `${from.id}.onReturned → ${to.id}` : '',
             ].filter(Boolean));
         }
         case 'calls':