@yss123/cage-cli 0.0.0-stage → 0.1.0

package/graph-ui/index.html

@@ -0,0 +1,197 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="theme-color" content="#f6f7f3" />
+    <title>Cage Atlas · 本体图谱</title>
+    <link
+      rel="icon"
+      href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 40 40'%3E%3Crect width='40' height='40' rx='10' fill='%232d665a'/%3E%3Cpath d='M11 12h18v16H11zm0 8h18m-9-8v16' stroke='%23fff' fill='none' stroke-width='2'/%3E%3C/svg%3E"
+    />
+    <link rel="stylesheet" href="/style.css" />
+  </head>
+  <body>
+    <div class="app-shell">
+      <header class="topbar">
+        <a class="brand" href="/" aria-label="Cage Atlas 首页"
+          ><span class="brand-mark"><i></i><i></i><i></i><i></i></span
+          ><strong>CAGE<span>ATLAS</span></strong></a
+        >
+        <div class="breadcrumb">
+          <span>开发者工作台</span><b>/</b><span id="project-name">正在读取项目</span>
+        </div>
+        <span class="local-badge"><i></i>本地声明</span>
+        <button
+          class="icon-button mobile-filters"
+          id="toggle-sidebar"
+          aria-label="展开筛选"
+          aria-expanded="false"
+        >
+          ☰
+        </button>
+      </header>
+
+      <aside class="sidebar" id="sidebar">
+        <div class="section-label">项目工作区 <span>01</span></div>
+        <div class="nav-active"><span class="nav-symbol">◇</span> 本体图谱 <span class="nav-dot"></span></div>
+        <div class="sidebar-heading">业务对象 <span id="aggregate-total"></span></div>
+        <div id="aggregate-list" class="aggregate-list"></div>
+        <div class="sidebar-heading" id="types-heading">
+          节点类型 <button id="reset-types" class="text-button">重置</button>
+        </div>
+        <div id="type-filters" class="type-filters"></div>
+        <div id="structure-note" class="structure-note">
+          <strong>一张卡片，一个业务对象</strong>
+          <p>字段收在卡片内，引用从字段连出。点击字段可查看业务用途。</p>
+          <small>＊ 必填　↗ 引用字段</small>
+        </div>
+        <label class="system-toggle"
+          ><input id="system-toggle" type="checkbox" /><span>包含系统组织模型</span></label
+        >
+        <div class="sidebar-note">
+          <span class="note-icon">⌘</span>
+          <div>
+            <strong>声明即地图</strong>
+            <p>修改 domain 后重新抽取，<br />让关系与代码保持同步。</p>
+          </div>
+        </div>
+        <a class="sidebar-footer" href="/api/graph" target="_blank" rel="noreferrer"
+          >查看原始图谱数据 <span>↗</span></a
+        >
+      </aside>
+
+      <main class="main">
+        <section class="page-heading">
+          <div>
+            <div class="eyebrow">业务关系探索</div>
+            <h1>本体图谱<span class="version-tag">v0.1</span></h1>
+            <p>从声明出发，看见业务如何连接。</p>
+          </div>
+          <div class="heading-actions">
+            <button id="download" class="button secondary"><span>↓</span> 导出 JSON</button
+            ><button id="refresh" class="button primary"><span class="refresh-icon">↻</span> 重新抽取</button>
+          </div>
+        </section>
+        <div id="notice" class="notice" role="status" hidden></div>
+        <section class="overview" aria-label="图谱统计">
+          <div class="overview-item">
+            <span class="metric-icon aggregate-icon">◇</span>
+            <div><small>业务对象</small><strong id="metric-aggregates">—</strong></div>
+          </div>
+          <div class="overview-item">
+            <span class="metric-icon node-icon">⠿</span>
+            <div><small>声明节点</small><strong id="metric-nodes">—</strong></div>
+          </div>
+          <div class="overview-item">
+            <span class="metric-icon edge-icon">↗</span>
+            <div><small>声明关系</small><strong id="metric-edges">—</strong></div>
+          </div>
+          <div class="overview-health">
+            <span id="health-dot" class="health-dot"></span>
+            <div><strong id="health">正在抽取声明</strong><small id="updated">稍候即可探索图谱</small></div>
+            <button id="show-findings" class="text-button" hidden>查看问题</button>
+          </div>
+        </section>
+
+        <section class="explorer" aria-label="交互式本体图谱">
+          <div class="graph-panel">
+            <div class="graph-toolbar">
+              <div class="tabs" role="group" aria-label="图谱视图">
+                <button data-mode="structure" class="active" aria-pressed="true">对象与字段</button
+                ><button data-mode="business" aria-pressed="false">业务流程</button
+                ><button data-mode="all" aria-pressed="false">完整本体</button>
+              </div>
+              <div class="search-wrap">
+                <span aria-hidden="true">⌕</span
+                ><input
+                  id="search"
+                  type="search"
+                  placeholder="搜索中文名称或代码标识"
+                  aria-label="搜索节点"
+                  autocomplete="off"
+                /><kbd>/</kbd>
+                <div id="search-results" class="search-results" hidden></div>
+              </div>
+            </div>
+            <div class="graph-subbar">
+              <span
+                ><i class="tiny-dot"></i><strong id="view-title">全部业务</strong
+                ><span id="view-count"></span></span
+              ><button id="exit-focus" class="text-button" hidden>退出聚焦 ×</button
+              ><span class="drag-hint">点击连线看解释 · 拖拽节点 · 滚轮缩放</span>
+            </div>
+            <div class="relation-guide">
+              <span>↗</span><span id="relation-guide">箭头按线上的文字阅读；点击连线查看原因和用途。</span>
+            </div>
+            <div id="canvas" class="canvas">
+              <svg id="graph" role="group" aria-label="本体节点与依赖关系" xmlns="http://www.w3.org/2000/svg">
+                <defs>
+                  <marker
+                    id="arrow"
+                    viewBox="0 0 10 10"
+                    refX="9"
+                    refY="5"
+                    markerWidth="5"
+                    markerHeight="5"
+                    orient="auto-start-reverse"
+                  >
+                    <path d="M0 0L10 5L0 10z" fill="#a4b4ad" />
+                  </marker>
+                  <marker
+                    id="arrow-active"
+                    viewBox="0 0 10 10"
+                    refX="9"
+                    refY="5"
+                    markerWidth="5"
+                    markerHeight="5"
+                    orient="auto-start-reverse"
+                  >
+                    <path d="M0 0L10 5L0 10z" fill="#357c6c" />
+                  </marker>
+                </defs>
+                <g id="viewport">
+                  <g id="edges"></g>
+                  <g id="nodes"></g>
+                </g>
+              </svg>
+              <div id="empty" class="empty-state" hidden>
+                <span>◇</span><strong>当前筛选下没有节点</strong>
+                <p>调整左侧类型，或恢复默认业务视图。</p>
+                <button id="reset-view" class="button secondary">恢复视图</button>
+              </div>
+              <div id="loading" class="loading-state">
+                <span class="loader"></span><strong>正在展开业务地图</strong>
+              </div>
+              <div class="canvas-signature">CAGE <span>/</span> 业务声明关系图</div>
+              <div class="zoom-controls" aria-label="画布操作">
+                <button id="zoom-out" aria-label="缩小">−</button><span id="zoom-level">100%</span
+                ><button id="zoom-in" aria-label="放大">＋</button><i></i
+                ><button id="fit" aria-label="适应画布" title="适应画布">⛶</button
+                ><button id="relayout" aria-label="重置布局" title="重置布局">↺</button>
+              </div>
+            </div>
+            <footer class="graph-footer">
+              <div id="edge-legend">
+                <span class="legend-line"></span> 声明关系 <span class="legend-line dashed"></span> 视图归属
+              </div>
+              <span id="canvas-status">读取声明中</span>
+            </footer>
+          </div>
+          <aside id="inspector" class="inspector" aria-label="节点与关系详情" aria-live="polite"></aside>
+        </section>
+        <footer class="page-footer">
+          <span id="domain-path">packages/domain/src/index.ts</span><span>只读探索 · 不连接业务数据库</span>
+        </footer>
+      </main>
+    </div>
+    <dialog id="findings-dialog">
+      <div class="dialog-heading">
+        <h2>声明检查</h2>
+        <button id="close-findings" class="icon-button" aria-label="关闭检查结果">×</button>
+      </div>
+      <div id="findings-list"></div>
+    </dialog>
+    <script type="module" src="/app.js"></script>
+  </body>
+</html>

package/graph-ui/model.js

@@ -0,0 +1,141 @@
+export const kinds = {
+    aggregate: { label: '业务对象', color: '#197c72', short: '表', column: 0 },
+    command: { label: '命令', color: '#547db2', short: '令', column: 1 },
+    event: { label: '事件', color: '#c08c36', short: '事', column: 2 },
+    reaction: { label: '反应', color: '#aa7288', short: '应', column: 3 },
+    query: { label: '查询', color: '#648c5b', short: '查', column: 1 },
+    approval: { label: '审批', color: '#9c739f', short: '审', column: 3 },
+    route: { label: '审批路由', color: '#9c739f', short: '路', column: 3 },
+    job: { label: '定时任务', color: '#7f82a0', short: '时', column: 0 },
+    connector: { label: '连接器', color: '#b57452', short: '连', column: 4 },
+    outbound: { label: '出站映射', color: '#b57452', short: '出', column: 3 },
+    inbound: { label: '入站回调', color: '#b57452', short: '入', column: 4 },
+    field: { label: '字段', color: '#67998f', short: '字', column: 1 },
+    state: { label: '状态', color: '#898b69', short: '态', column: 2 },
+    capability: { label: '能力点', color: '#81949f', short: '权', column: 1 },
+    entry: { label: '新建入口', color: '#89938e', short: '+', column: 0 },
+};
+export const edgeLabels = {
+    transition: '状态迁移',
+    reads: '读取',
+    emits: '发出',
+    uses: '使用字段',
+    triggers: '触发',
+    targets: '调用目标',
+    queries: '查询',
+    refs: '引用',
+    calls: '调用',
+    binds: '审批绑定',
+    field: '声明字段',
+    ownership: '归属（视图推导）',
+};
+/** 中文用于展示，英文仍作为复制、搜索和查源码的稳定标识。
+ * 没有配置业务名称的未知节点保留原标识，不能猜测业务含义后悄悄改名。 */
+export function nodeLabel(node, labels = {}) {
+    if (node.kind === 'entry')
+        return '新建入口';
+    return labels[node.key] || String(node.attrs.description || node.id);
+}
+export function matchesNode(node, query, labels) {
+    return `${nodeLabel(node, labels)} ${node.id} ${kinds[node.kind].label}`
+        .toLowerCase()
+        .includes(query.toLowerCase());
+}
+export function projectGraph(graph) {
+    const nodes = graph.nodes.map((n) => ({ ...n, key: `${n.kind}:${n.id}` }));
+    const edges = [];
+    // 节点身份包含 kind。能力点和命令可能同名，不能单用显示名作为 SVG 的主键。
+    const find = (id) => nodes.find((n) => n.id === id && n.kind !== 'capability') ?? nodes.find((n) => n.id === id);
+    for (const e of graph.edges) {
+        let from = find(e.from);
+        const to = find(e.to);
+        // [new] 是迁移的起点，并不属于声明状态；在视图中显式标为虚拟入口。
+        if (!from && e.kind === 'transition' && e.from.endsWith('.[new]')) {
+            from = { key: `entry:${e.from}`, id: e.from, kind: 'entry', hash: '', attrs: {} };
+            nodes.push(from);
+        }
+        if (from && to)
+            edges.push({ ...e, from: from.key, to: to.key, key: `edge:${edges.length}`, derived: false });
+    }
+    for (const n of nodes) {
+        if (!['command', 'state', 'capability', 'entry'].includes(n.kind))
+            continue;
+        const owner = nodes.find((a) => a.kind === 'aggregate' && n.id.startsWith(`${a.id}.`));
+        if (owner)
+            edges.push({ key: `owner:${n.key}`, kind: 'ownership', from: owner.key, to: n.key, derived: true });
+    }
+    return { nodes, edges };
+}
+export const isSystem = (n) => /^(User|Role|Dept)(\.|$)/.test(n.id);
+export function neighborhood(model, key) {
+    const connected = new Set([key]);
+    for (const e of model.edges) {
+        if (e.from === key)
+            connected.add(e.to);
+        if (e.to === key)
+            connected.add(e.from);
+    }
+    return connected;
+}
+export const NODE_WIDTH = 190;
+export const NODE_HEIGHT = 56;
+/** 按类型分组的平衡列 + 邻接排序。相同声明每次打开位置相同，没有持续运动的力导向
+ * 动画；读长名称、比较刷新前后的关系时不会被随机布局打断。 */
+export function layoutGraph(nodes, edges, focusKey) {
+    const positions = new Map();
+    // 小范围聚焦按关系方向排布：依赖方在左、当前节点居中、目标在右。
+    // 大图继续使用平衡列，避免高连接度聚合把所有邻居挤成一条长列。
+    if (focusKey && nodes.some((n) => n.key === focusKey) && nodes.length <= 12) {
+        positions.set(focusKey, { x: 330, y: 0 });
+        const incoming = new Set(edges.filter((e) => e.to === focusKey).map((e) => e.from));
+        const neighbors = nodes.filter((n) => n.key !== focusKey);
+        for (const [column, items] of [
+            neighbors.filter((n) => incoming.has(n.key)),
+            neighbors.filter((n) => !incoming.has(n.key)),
+        ].entries()) {
+            items.forEach((n, row) => positions.set(n.key, { x: column * 660, y: (row - (items.length - 1) / 2) * 105 }));
+        }
+        return positions;
+    }
+    // 命令通常远多于其他节点；强制“一类一列”会形成极长列，适应画布后字体
+    // 小到无法阅读。保持语义排序，再均衡分列，让概览尽量利用二维空间。
+    const ordered = [...nodes].sort((a, b) => kinds[a.kind].column - kinds[b.kind].column || a.id.localeCompare(b.id));
+    const columnCount = Math.min(4, Math.max(1, Math.ceil(Math.sqrt(nodes.length / 1.6))));
+    const perColumn = Math.ceil(nodes.length / columnCount);
+    const columns = Array.from({ length: columnCount }, (_, i) => ordered.slice(i * perColumn, (i + 1) * perColumn));
+    const place = () => columns.forEach((items, column) => items.forEach((n, row) => {
+        positions.set(n.key, { x: column * 330, y: (row - (items.length - 1) / 2) * 105 });
+    }));
+    place();
+    // 只做排序，节点仍各占一行；邻居平均纵坐标让同一业务链尽量接近。
+    for (let pass = 0; pass < 4; pass++) {
+        for (const items of columns) {
+            const score = (node) => {
+                const ys = edges
+                    .filter((e) => e.from === node.key || e.to === node.key)
+                    .map((e) => positions.get(e.from === node.key ? e.to : e.from)?.y)
+                    .filter((y) => y !== undefined);
+                return ys.length ? ys.reduce((a, b) => a + b, 0) / ys.length : 0;
+            };
+            items.sort((a, b) => score(a) - score(b) || a.id.localeCompare(b.id));
+            place();
+        }
+    }
+    return positions;
+}
+export function edgePath(from, to, self) {
+    if (self)
+        return `M${from.x + NODE_WIDTH - 25},${from.y} C${from.x + NODE_WIDTH + 50},${from.y - 65} ${from.x + NODE_WIDTH + 50},${from.y + 100} ${from.x + NODE_WIDTH - 25},${from.y + NODE_HEIGHT}`;
+    // 同列关系从右侧绕行，给标签留出空间，也避免穿过中间节点。
+    if (from.x === to.x) {
+        const x = from.x + NODE_WIDTH;
+        const y1 = from.y + NODE_HEIGHT / 2, y2 = to.y + NODE_HEIGHT / 2;
+        const bend = 110 + Math.abs(y2 - y1) * 0.12;
+        return `M${x},${y1} C${x + bend},${y1} ${x + bend},${y2} ${x},${y2}`;
+    }
+    const forward = to.x >= from.x;
+    const x1 = from.x + (forward ? NODE_WIDTH : 0), x2 = to.x + (forward ? 0 : NODE_WIDTH);
+    const y1 = from.y + NODE_HEIGHT / 2, y2 = to.y + NODE_HEIGHT / 2;
+    const bend = Math.max(60, Math.abs(x2 - x1) / 2) * (forward ? 1 : -1);
+    return `M${x1},${y1} C${x1 + bend},${y1} ${x2 - bend},${y2} ${x2},${y2}`;
+}

package/graph-ui/relations.js

@@ -0,0 +1,125 @@
+import { kinds, nodeLabel } from './model.js';
+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);
+    const a = nodeLabel(from, labels), b = nodeLabel(to, labels);
+    const field = to.id.slice(to.id.indexOf('.') + 1);
+    const resource = (id) => labels[`resource:${id}`] ?? id;
+    const result = (label, category, why, purpose, evidence, source = from) => ({
+        label,
+        category,
+        why,
+        purpose,
+        evidence,
+        source,
+        direction: `“${a}” → “${b}”：${label}。`,
+    });
+    switch (edge.kind) {
+        case 'field':
+            return result('包含字段', '数据结构', `“${a}”的字段声明中包含“${b}”。`, '说明业务对象由哪些数据组成；调整字段时，可以继续沿线查看受影响的查询、审批和事件。', [`${from.id}.fields.${field}`]);
+        case 'refs':
+            return result('引用对象', '数据关联', `“${a}”声明为引用“${b}”的字段，保存所关联对象的标识。`, `用于理解这条数据关联到哪个${kinds[to.kind].label}。例如部门字段关联部门对象；具体查询仍受数据范围约束。这条线本身不执行查询。`, [`${from.id}: ref(${JSON.stringify(to.id)})`]);
+        case 'ownership':
+            return result(`拥有${kinds[to.kind].label}`, '视图归属 · 虚线', `“${b}”的标识位于“${from.id}.”之下，页面据此将它归入“${a}”。`, '帮助整理同一业务对象的命令、状态和能力点。这是页面推导的归属，不是抽取器声明的依赖，也不会触发命令。', [`${to.id} → 所属聚合 ${from.id}`]);
+        case 'transition': {
+            const command = model.nodes.find((n) => n.kind === 'command' && n.id === edge.via);
+            const name = nodeLabel(command, labels);
+            const stays = edge.from === edge.to;
+            return result(stays ? '保持状态' : '迁移状态', '状态变化', `“${name}”声明${stays ? `在“${a}”状态执行后保持原状态` : `从“${a}”进入“${b}”`}。`, `用于检查业务生命周期是否完整。只有命令通过权限、约束并成功提交，${stays ? '操作才生效' : '状态才改变'}。`, [
+                `命令：${command.id}`,
+                `from: ${JSON.stringify(command.attrs.from)}`,
+                `to: ${JSON.stringify(command.attrs.to)}`,
+            ], command);
+        }
+        case 'reads':
+        case 'queries':
+            return result('读取数据', '读取依赖', `“${a}”在 reads 中声明读取“${b}”${edge.alias ? `，使用别名 ${edge.alias}` : ''}。`, '明确可读取的业务对象，并让影响分析找到依赖方；实际读取通过安全视图，受权限和数据范围约束。箭头指向数据来源，不表示先执行它。', [`${from.id}.reads${edge.alias ? `.${edge.alias}` : ''} → ${to.id}`]);
+        case 'emits':
+            return result('产生事件', '事件协作', `“${a}”的 emits 中声明了“${b}”事件。`, '命令成功执行时按声明生成事件，连接后续反应、审批或外部同步；事务失败时不能当作已经发生。', [`${from.id}.emits → ${to.id}`]);
+        case 'uses': {
+            const as = edge.as ?? '';
+            if (as === '可路由字段')
+                return result('允许审批读取', '审批可用字段', `“${a}”把“${b}”列入 routable，允许该字段作为审批流程变量。`, '明确审批可以拿到哪些业务数据。这里只表示允许使用；是否真的参与分支或审批选人，要查看审批路由的字段关系。', [`${from.id}.routable 包含 ${field}`]);
+            if (as === '路由条件') {
+                // fieldsUsed 同时包含 when 条件和 deptLeader 选人字段，不能一律解释成条件判断。
+                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);
+                const operators = {
+                    gt: '大于',
+                    gte: '大于等于',
+                    lt: '小于',
+                    lte: '小于等于',
+                    eq: '等于',
+                    ne: '不等于',
+                    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('、')}步骤`),
+                ];
+                return result(steps.length && conditions.length ? '选人和分支依据' : steps.length ? '确定审批人' : '判断审批分支', '审批路由依赖', `${reasons.join('；')}。`, '字段值会影响审批人或需要经过的审批步骤；修改字段含义时，应一起检查这些路由配置。', [
+                    ...steps.map((s) => `${s.title}: approver.deptLeader(${JSON.stringify(field)})`),
+                    ...conditions.map((n) => `when(${n.cond.op}(${JSON.stringify(field)}, ${JSON.stringify(n.cond.value)}))`),
+                ]);
+            }
+            if (as === '事件载荷')
+                return result('携带字段', '事件数据依赖', `“${a}”的默认事件载荷按同名字段从业务对象取“${b}”。`, '订阅方可以用事件中的这份数据处理后续业务；字段变更需要检查事件及订阅方的数据约定。箭头指向载荷的数据来源。', [`事件 ${from.id} 的同名字段 ${field} ← ${to.id}`]);
+            if (as === '查询')
+                return result('查询使用字段', '查询字段线索', `抽取器在“${a}”的 SQL 或查询构造函数文本中匹配到了“${b}”的字段名。`, '提供检查查询依赖的线索。这里基于字段名文本匹配，可能匹配到注释或同名内容；实际筛选、分组或计算用途请核对查询声明。', [`${from.id}: SQL / build 文本匹配 ${field}`]);
+            if (as === '出站映射')
+                return result('映射外发字段', '外部同步数据', `“${a}”的 fields 声明包含“${b}”对应的字段名；抽取器将它关联到发出事件的聚合中同名字段。`, '用于核对外发字段范围和字段变更的同步影响；具体取值及转换由事件载荷与 map 函数决定。', [`${from.id}.fields 包含 ${field}`, `同名聚合字段：${to.id}`]);
+            if (as.startsWith('约束 ')) {
+                const rule = as.slice(3);
+                const purpose = rule.startsWith('ceiling(')
+                    ? `用于校验“${b}”是否超出调用人的审批额度。`
+                    : rule.startsWith('sod.notSameAs(')
+                        ? `用于校验调用人与“${b}”记录的人不同，避免同一人完成需要分离的职责。`
+                        : `该约束读取“${b}”执行命令前的业务检查；字段变更时应一起复核约束。`;
+                return result('执行约束检查', '命令校验依赖', `“${a}”声明的约束 ${rule} 使用“${b}”。`, purpose, [
+                    `${from.id}.constraints → ${rule}`,
+                    `约束 fields 包含 ${field}`,
+                ]);
+            }
+            return result('使用字段', '字段依赖', `“${a}”声明使用“${b}”。`, '用于追踪字段变更的影响范围。', [
+                as || edge.kind,
+            ]);
+        }
+        case 'triggers': {
+            const label = to.kind === 'approval' ? '启动审批' : to.kind === 'outbound' ? '触发外部同步' : '触发反应';
+            return result(label, '事件触发', `“${b}”订阅“${a}”作为${to.kind === 'approval' ? '启动' : '触发'}事件。`, to.kind === 'approval'
+                ? '事件发生后启动对应审批流程，生成流程中的审批任务。'
+                : to.kind === 'outbound'
+                    ? '事件发生后由 worker 处理外部推送，失败按投递策略重试。'
+                    : `事件发生后执行订阅的反应${to.attrs.tx === 'same' ? '，该反应与原命令处于同一事务' : '；执行方式由反应的事务声明决定'}。`, [`${to.id}.${to.kind === 'approval' ? 'start' : 'event'} → ${from.id}`], to);
+        }
+        case 'targets': {
+            if (to.kind === 'connector')
+                return result('调用外部系统', '连接器调用', `“${a}”声明通过“${b}”执行操作 ${labels[`operation:${from.attrs.operation}`] ?? from.attrs.operation}。`, '由连接器统一处理地址与字段白名单、密钥、限流和超时，让外部同步保持可管控。', [`${from.id}.connector → ${to.id}`, `operation: ${from.attrs.operation}`]);
+            if (from.kind === 'outbound')
+                return result('成功后回写', '同步成功回调', `“${a}”的 onSuccess 绑定“${b}”。`, '外部操作成功后调用该命令，将返回结果按映射写回业务；失败时不执行成功回写。', [`${from.id}.onSuccess → ${to.id}`]);
+            if (from.kind === 'inbound')
+                return result('回调转为命令', '外部回调', `“${a}”将接收的外部回调映射到“${b}”。`, '外部回调通过验签和数据校验后，使用业务命令处理，统一遵守状态和业务约束。', [`${from.id}.command → ${to.id}`]);
+            const resources = [
+                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]);
+        }
+        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 ? '通过' : '驳回';
+            return result(`${outcome}后执行`, '审批结论回写', `“${a}”${outcome}时绑定执行“${b}”。`, '将审批结论交给业务命令推进单据状态，并统一执行权限和业务约束。', [
+                approved ? `${from.id}.onApproved → ${to.id}` : '',
+                rejected ? `${from.id}.onRejected → ${to.id}` : '',
+            ].filter(Boolean));
+        }
+        case 'calls':
+            return result('允许调用命令', '任务调用范围', `“${a}”在 calls 中声明可以调用“${b}”。`, '明确任务能执行哪些业务写入，并支持影响分析。每次任务是否实际调用该命令，取决于 run 中的业务逻辑。', [`${from.id}.calls → ${to.id}`]);
+    }
+}

package/graph-ui/structure.js

@@ -0,0 +1,74 @@
+export const TABLE_WIDTH = 336;
+export const TABLE_HEADER = 58;
+export const TABLE_ROW = 38;
+export const TABLE_FOOTER = 34;
+/** 对象卡片展示声明字段，而不是猜测完整数据库结构。系统自动添加的列不在
+ * 抽取结果中，因此这里不补造 id、主键、外键约束或一对多基数。
+ * 字段仍保留原节点身份，搜索、点击和关系解释都能回到同一份声明。 */
+export function tableCards(model) {
+    return model.nodes
+        .filter((n) => n.kind === 'aggregate')
+        .map((node) => {
+        const fieldKeys = model.edges.filter((e) => e.kind === 'field' && e.from === node.key).map((e) => e.to);
+        const fields = fieldKeys.map((key) => model.nodes.find((n) => n.key === key));
+        return { node, fields, height: TABLE_HEADER + fields.length * TABLE_ROW + TABLE_FOOTER };
+    });
+}
+/** 用真实字段归属解析端点；不能把两个同名字段合并，也不能把命令算成列。 */
+export function tableOwner(cards, key) {
+    return cards.find((card) => card.node.key === key || card.fields.some((field) => field.key === key));
+}
+/** 关联较多的对象优先放置，再按实际卡片高度分配到最短列。
+ * 两列上限保持字段字可读；卡片高度由字段数决定，避免固定网格裁掉长表。 */
+export function layoutTables(cards, edges, columns) {
+    const positions = new Map();
+    const heights = Array.from({ length: Math.min(columns, cards.length) }, () => 0);
+    const degree = (card) => edges.filter((e) => e.to === card.node.key || card.fields.some((f) => f.key === e.from)).length;
+    const ordered = [...cards].sort((a, b) => degree(b) - degree(a) || b.height - a.height || a.node.id.localeCompare(b.node.id));
+    for (const card of ordered) {
+        const column = heights.indexOf(Math.min(...heights));
+        positions.set(card.node.key, { x: column * (TABLE_WIDTH + 155), y: heights[column] });
+        heights[column] += card.height + 84;
+    }
+    return positions;
+}
+/** 引用线从具体字段行连接到目标对象表头。端点随卡片拖动一起计算，
+ * 不把整张卡片的中心当成字段位置；同列时从侧边绕开表体。 */
+export function tableEdgePath(edge, cards, positions) {
+    const source = tableOwner(cards, edge.from);
+    const target = tableOwner(cards, edge.to);
+    const from = positions.get(source.node.key);
+    const to = positions.get(target.node.key);
+    const row = source.fields.findIndex((f) => f.key === edge.from);
+    const y1 = from.y + TABLE_HEADER + row * TABLE_ROW + TABLE_ROW / 2;
+    const y2 = to.y + TABLE_HEADER / 2;
+    if (from.x === to.x) {
+        const x = from.x + TABLE_WIDTH;
+        const bend = 88 + row * 14;
+        return `M${x},${y1} C${x + bend},${y1} ${x + bend},${y2} ${x},${y2}`;
+    }
+    const forward = to.x > from.x;
+    const x1 = from.x + (forward ? TABLE_WIDTH : 0);
+    const x2 = to.x + (forward ? 0 : TABLE_WIDTH);
+    const bend = Math.max(65, Math.abs(x2 - x1) / 2) * (forward ? 1 : -1);
+    return `M${x1},${y1} C${x1 + bend},${y1} ${x2 - bend},${y2} ${x2},${y2}`;
+}
+export function fieldType(field) {
+    const types = {
+        text: '文本',
+        int: '整数',
+        money: '金额',
+        decimal: '小数',
+        float: '浮点数',
+        bool: '布尔',
+        boolean: '布尔',
+        id: '标识',
+        ref: '引用',
+        list: '列表',
+        json: 'JSON',
+        date: '日期',
+        datetime: '时间',
+        enum: '枚举',
+    };
+    return types[String(field.attrs.kind)] ?? String(field.attrs.kind);
+}