@yss123/cage-cli 0.0.0-stage → 0.1.0

package/graph-ui/app.js

@@ -0,0 +1,1065 @@
+import { kinds, nodeLabel, matchesNode, projectGraph, neighborhood, isSystem, layoutGraph, edgePath, NODE_WIDTH, NODE_HEIGHT, } from './model.js';
+import { explainEdge } from './relations.js';
+import { tableCards, tableOwner, layoutTables, tableEdgePath, fieldType, TABLE_WIDTH, TABLE_HEADER, TABLE_ROW, } from './structure.js';
+// 页面不引入图形框架或远程 CDN。百级声明图使用 SVG，即可保留清晰缩放、
+// 键盘选择和可检查的节点语义；所有数据都由本地 CLI 抽取服务提供。
+const element = (id) => document.getElementById(id);
+const svg = document.getElementById('graph');
+const viewport = document.getElementById('viewport');
+const edgeLayer = document.getElementById('edges');
+const nodeLayer = document.getElementById('nodes');
+const ns = 'http://www.w3.org/2000/svg';
+let snapshot;
+let model = { nodes: [], edges: [] };
+let visibleNodes = [];
+let visibleEdges = [];
+let positions = new Map();
+let selected = null;
+let selectedEdge = null;
+let emphasizeSelection = false;
+let aggregate = null;
+let focus = null;
+let mode = 'structure';
+let cards = [];
+let visibleCards = [];
+let searchTarget = null;
+let showSystem = false;
+let camera = { x: 0, y: 0, scale: 1 };
+const businessKinds = Object.keys(kinds).filter((k) => !['field', 'state', 'capability', 'entry'].includes(k));
+let enabled = new Set(businessKinds);
+const nodeElements = new Map();
+const edgeElements = new Map();
+function html(tag, className = '', text = '') {
+    const node = document.createElement(tag);
+    node.className = className;
+    node.textContent = text;
+    return node;
+}
+function vector(tag, attrs = {}, text = '') {
+    const node = document.createElementNS(ns, tag);
+    for (const [key, value] of Object.entries(attrs))
+        node.setAttribute(key, String(value));
+    node.textContent = text;
+    return node;
+}
+const byKey = (key) => model.nodes.find((n) => n.key === key);
+const displayName = (node) => nodeLabel(node, snapshot.presentation.labels);
+// 中文字符约占两个半角字宽，不能沿用英文按字符数截断，否则标题会溢出卡片。
+function shortName(text, width = 23) {
+    let result = '', used = 0;
+    for (const char of text) {
+        used += /[\u0000-\u00ff]/.test(char) ? 1 : 2;
+        if (used > width)
+            return `${result}…`;
+        result += char;
+    }
+    return result;
+}
+const named = (id, kind) => {
+    const node = model.nodes.find((n) => n.id === id && (!kind || n.kind === kind));
+    return node
+        ? displayName(node)
+        : ((kind ? snapshot.presentation.labels[`${kind}:${id}`] : undefined) ?? String(id));
+};
+function notify(message) {
+    element('notice').textContent = message;
+    element('notice').hidden = !message;
+}
+async function load(refresh = false) {
+    const button = element('refresh');
+    button.disabled = true;
+    button.textContent = refresh ? '正在重新抽取…' : '读取中…';
+    notify('');
+    try {
+        const response = await fetch(refresh ? '/api/refresh' : '/api/graph', {
+            method: refresh ? 'POST' : 'GET',
+        });
+        const data = await response.json();
+        if (!response.ok)
+            throw new Error(data.error);
+        snapshot = data;
+        model = projectGraph(snapshot.graph);
+        cards = tableCards(model);
+        // 边的序号可能因重新抽取而变化，清除旧边，避免把解释套到另一条关系上。
+        selectedEdge = null;
+        // 刷新保留用户筛选与有效选中项，已删除节点不继续显示旧详情。
+        if (selected && !model.nodes.some((n) => n.key === selected))
+            selected = null;
+        if (focus && !model.nodes.some((n) => n.key === focus))
+            focus = null;
+        if (aggregate && !model.nodes.some((n) => n.kind === 'aggregate' && n.id === aggregate))
+            aggregate = null;
+        if (!selected) {
+            const aggregates = model.nodes.filter((n) => n.kind === 'aggregate' && !isSystem(n));
+            const commands = (a) => model.nodes.filter((n) => n.kind === 'command' && n.id.startsWith(`${a.id}.`)).length;
+            selected = aggregates.sort((a, b) => commands(b) - commands(a))[0]?.key ?? model.nodes[0]?.key ?? null;
+        }
+        renderSummary();
+        renderFilters();
+        renderGraph();
+        renderInspector();
+        renderFindings();
+    }
+    catch (error) {
+        // 抽取失败时保留上次成功的视图，并明确告诉用户它是旧数据。
+        notify(`${snapshot ? '重新抽取失败，当前保留上次成功的图谱。' : '图谱加载失败。'}\n${error.message}`);
+        if (!snapshot) {
+            element('health').textContent = '尚未取得图谱';
+            element('updated').textContent = '修复问题后点击重新抽取';
+        }
+    }
+    finally {
+        button.disabled = false;
+        button.textContent = '↻ 重新抽取';
+        element('loading').hidden = true;
+    }
+}
+function renderSummary() {
+    element('project-name').textContent = snapshot.presentation.title;
+    element('project-name').title = snapshot.project;
+    document.title = `${snapshot.presentation.title} · Cage 本体图谱`;
+    element('domain-path').textContent = snapshot.domain;
+    element('metric-aggregates').textContent = String(snapshot.graph.nodes.filter((n) => n.kind === 'aggregate').length);
+    element('metric-nodes').textContent = String(snapshot.graph.nodes.length);
+    element('metric-edges').textContent = String(snapshot.graph.edges.length);
+    const errors = snapshot.findings.filter((f) => f.severity !== 'warning').length;
+    const warnings = snapshot.findings.length - errors;
+    element('health').textContent = errors
+        ? `${errors} 个声明问题`
+        : warnings
+            ? `${warnings} 个检查提醒`
+            : '声明与图规则通过';
+    element('health-dot').classList.toggle('warning', snapshot.findings.length > 0);
+    element('show-findings').hidden = !snapshot.findings.length;
+    const time = new Date(snapshot.generatedAt).toLocaleTimeString('zh-CN', { hour12: false });
+    element('updated').textContent = `最近抽取 ${time}`;
+}
+function renderFilters() {
+    element('types-heading').hidden = mode === 'structure';
+    element('type-filters').hidden = mode === 'structure';
+    element('structure-note').hidden = mode !== 'structure';
+    const aggregates = model.nodes.filter((n) => n.kind === 'aggregate' && (showSystem || !isSystem(n)));
+    element('aggregate-total').textContent = String(aggregates.length);
+    const list = element('aggregate-list');
+    list.replaceChildren();
+    const addAggregate = (id, label, count) => {
+        const button = html('button', `aggregate-button${aggregate === id ? ' active' : ''}`);
+        button.setAttribute('aria-pressed', String(aggregate === id));
+        button.append(html('span', '', id ? '◇' : '⊞'), html('span', '', label), html('b', '', String(count)));
+        button.onclick = () => {
+            aggregate = id;
+            focus = null;
+            renderFilters();
+            renderGraph();
+        };
+        list.append(button);
+    };
+    addAggregate(null, '全部业务', aggregates.length);
+    for (const a of aggregates)
+        addAggregate(a.id, displayName(a), model.nodes.filter((n) => n.id.startsWith(`${a.id}.`)).length);
+    const filters = element('type-filters');
+    filters.replaceChildren();
+    for (const [kind, meta] of Object.entries(kinds)) {
+        if (kind === 'entry')
+            continue;
+        const count = model.nodes.filter((n) => n.kind === kind && (showSystem || !isSystem(n))).length;
+        if (!count)
+            continue;
+        const label = html('label', 'type-filter');
+        const input = html('input');
+        input.type = 'checkbox';
+        input.checked = enabled.has(kind);
+        input.setAttribute('aria-label', `显示${meta.label}`);
+        input.onchange = () => {
+            input.checked ? enabled.add(kind) : enabled.delete(kind);
+            if (kind === 'state')
+                input.checked ? enabled.add('entry') : enabled.delete('entry');
+            renderGraph();
+        };
+        const dot = html('span', 'type-dot');
+        dot.style.backgroundColor = meta.color;
+        label.append(input, dot, html('span', '', meta.label), html('small', '', String(count)));
+        filters.append(label);
+    }
+    element('system-toggle').checked = showSystem;
+    document.querySelectorAll('[data-mode]').forEach((button) => {
+        button.classList.toggle('active', button.dataset.mode === mode);
+        button.setAttribute('aria-pressed', String(button.dataset.mode === mode));
+    });
+}
+/** 选一个聚合时，先纳入它自己的声明，再沿真实关系扩展业务链。
+ * 不沿其他聚合的归属边扩散，避免选采购单却展开所有组织管理命令。 */
+function aggregateNodes(id) {
+    const keys = new Set(model.nodes.filter((n) => n.id === id || n.id.startsWith(`${id}.`)).map((n) => n.key));
+    for (let hop = 0; hop < 3; hop++) {
+        const previous = new Set(keys);
+        for (const edge of model.edges.filter((e) => !e.derived)) {
+            if (previous.has(edge.from))
+                keys.add(edge.to);
+            if (previous.has(edge.to) && ['uses', 'reads', 'queries', 'triggers'].includes(edge.kind))
+                keys.add(edge.from);
+        }
+    }
+    return keys;
+}
+function renderGraph(resetLayout = true) {
+    searchTarget = null;
+    const scope = aggregate ? aggregateNodes(aggregate) : null;
+    const focused = focus ? neighborhood(model, focus) : null;
+    visibleNodes = model.nodes.filter((n) => enabled.has(n.kind) &&
+        (showSystem || !isSystem(n)) &&
+        (!scope || scope.has(n.key)) &&
+        (!focused || focused.has(n.key)));
+    const visible = new Set(visibleNodes.map((n) => n.key));
+    visibleEdges = model.edges.filter((e) => visible.has(e.from) && visible.has(e.to) && (!focus || e.from === focus || e.to === focus));
+    if (mode === 'structure') {
+        const center = focus ? tableOwner(cards, focus) : cards.find((c) => c.node.id === aggregate);
+        const focusedField = focus && byKey(focus).kind === 'field' ? focus : null;
+        const refs = model.edges.filter((e) => e.kind === 'refs' &&
+            (focusedField
+                ? e.from === focusedField
+                : !center || e.to === center.node.key || tableOwner(cards, e.from)?.node.key === center.node.key));
+        const related = center ? new Set([center.node.key]) : null;
+        // 选对象后只展开直接引用它、或被它引用的对象；不沿命令与事件扩散。
+        if (center)
+            for (const edge of refs) {
+                const source = tableOwner(cards, edge.from);
+                if (source.node.key === center.node.key)
+                    related.add(edge.to);
+                if (edge.to === center.node.key)
+                    related.add(source.node.key);
+            }
+        visibleCards = cards.filter((card) => (showSystem || !isSystem(card.node)) && (!related || related.has(card.node.key)));
+        const keys = new Set(visibleCards.flatMap((card) => [card.node.key, ...card.fields.map((f) => f.key)]));
+        visibleNodes = visibleCards.map((card) => card.node);
+        visibleEdges = refs.filter((edge) => keys.has(edge.from) && keys.has(edge.to));
+    }
+    if (selectedEdge && !visibleEdges.some((e) => e.key === selectedEdge.key)) {
+        selectedEdge = null;
+        renderInspector();
+    }
+    if (resetLayout)
+        positions =
+            mode === 'structure'
+                ? layoutTables(visibleCards, visibleEdges, svg.clientWidth < 680 ? 1 : 2)
+                : layoutGraph(visibleNodes, visibleEdges, focus);
+    nodeLayer.replaceChildren();
+    edgeLayer.replaceChildren();
+    nodeElements.clear();
+    edgeElements.clear();
+    for (const edge of visibleEdges) {
+        const explanation = explainEdge(edge, model, snapshot.presentation.labels);
+        const group = vector('g', {
+            class: `edge-group${edge.derived ? ' derived' : ''}`,
+            tabindex: 0,
+            role: 'button',
+            'data-key': edge.key,
+            'aria-label': `${displayName(byKey(edge.from))} → ${displayName(byKey(edge.to))}：${explanation.label}，查看关系说明`,
+        });
+        const path = vector('path', {
+            class: 'edge',
+            'marker-end': 'url(#arrow)',
+        });
+        // 透明描边扩大点击范围；文字牌与线属于同一按钮，鼠标和键盘看到同一解释。
+        const hit = vector('path', { class: 'edge-hit' });
+        const label = vector('g', { class: 'edge-label' });
+        const width = explanation.label.length * 14 + 20;
+        label.append(vector('rect', { x: -width / 2, y: -12, width, height: 24, rx: 12 }), vector('text', { 'text-anchor': 'middle', y: 4 }, explanation.label));
+        group.append(vector('title', {}, `${explanation.why}\n点击查看用途与声明依据`), hit, path, label);
+        group.onclick = () => selectEdge(edge);
+        group.onkeydown = (event) => {
+            if (event.key === 'Enter' || event.key === ' ') {
+                event.preventDefault();
+                selectEdge(edge);
+            }
+        };
+        edgeLayer.append(group);
+        edgeElements.set(edge.key, { group, path, hit, label, width });
+    }
+    for (const node of visibleNodes) {
+        if (mode === 'structure') {
+            renderTable(visibleCards.find((card) => card.node.key === node.key));
+            continue;
+        }
+        const meta = kinds[node.kind];
+        const g = vector('g', {
+            class: 'node',
+            tabindex: 0,
+            role: 'button',
+            'aria-label': `${meta.label} ${displayName(node)} ${node.id}`,
+            'data-key': node.key,
+        });
+        g.append(vector('title', {}, `${meta.label} · ${displayName(node)}\n${node.id}`));
+        g.append(vector('rect', {
+            class: 'selected-ring',
+            x: -5,
+            y: -5,
+            width: NODE_WIDTH + 10,
+            height: NODE_HEIGHT + 10,
+            rx: 12,
+        }));
+        g.append(vector('rect', { class: 'node-box', width: NODE_WIDTH, height: NODE_HEIGHT, rx: 8 }));
+        g.append(vector('rect', { x: 10, y: 14, width: 27, height: 27, rx: 6, fill: meta.color, 'fill-opacity': 0.1 }));
+        g.append(vector('text', { class: 'node-code', x: 23.5, y: 31, 'text-anchor': 'middle', fill: meta.color }, meta.short));
+        g.append(vector('text', { class: 'node-title', x: 46, y: 25 }, shortName(displayName(node), 18)));
+        g.append(vector('text', { class: 'node-subtitle', x: 46, y: 40 }, shortName(node.id, 23)));
+        g.onkeydown = (event) => {
+            if (event.key === 'Enter' || event.key === ' ') {
+                event.preventDefault();
+                selectNode(node.key);
+            }
+        };
+        nodeLayer.append(g);
+        nodeElements.set(node.key, g);
+    }
+    updatePositions();
+    highlight();
+    element('empty').hidden = visibleNodes.length > 0;
+    element('view-title').textContent = focus
+        ? `聚焦 · ${displayName(byKey(focus))}`
+        : aggregate
+            ? named(aggregate, 'aggregate')
+            : '全部业务';
+    element('view-count').textContent =
+        mode === 'structure'
+            ? ` / ${visibleCards.length} 个对象 · ${visibleCards.reduce((sum, card) => sum + card.fields.length, 0)} 个字段`
+            : ` / ${visibleNodes.length} 个节点`;
+    element('exit-focus').hidden = !focus;
+    element('canvas-status').textContent = `${visibleEdges.filter((e) => !e.derived).length} 条声明关系`;
+    element('relation-guide').textContent =
+        mode === 'structure'
+            ? '字段收在对象卡片内；点击字段看详情，点击引用线看连接原因。'
+            : visibleEdges.length > 18
+                ? '概览标注选中节点的关系；悬停或点击其他连线查看说明。'
+                : '按“起点 → 关系名称 → 终点”阅读；点击连线查看为什么连接、有什么用。';
+    if (mode === 'structure') {
+        const hiddenRefs = model.edges.filter((e) => e.kind === 'refs' && tableOwner(visibleCards, e.from) && !tableOwner(visibleCards, e.to)).length;
+        element('canvas-status').textContent =
+            `${visibleEdges.length} 条对象引用${hiddenRefs ? ` · ${hiddenRefs} 条指向隐藏对象` : ''}`;
+        element('edge-legend').textContent = '↗ 字段引用　＊ 必填　卡片展示声明字段';
+    }
+    else {
+        element('edge-legend').replaceChildren(html('span', 'legend-line'), document.createTextNode(' 声明关系 '), html('span', 'legend-line dashed'), document.createTextNode(' 视图归属'));
+    }
+    if (resetLayout)
+        requestAnimationFrame(fit);
+}
+/** 绿色表头、逐行字段和表名保持在同一 SVG 卡片里。字段是可选择的原始节点，
+ * 表头负责拖动卡片，字段点击不会误触画布拖动或把数据结构重新拆散。 */
+function renderTable(card) {
+    const { node, fields, height } = card;
+    const group = vector('g', {
+        class: 'node table-card',
+        'data-key': node.key,
+        role: 'group',
+        'aria-label': `业务对象 ${displayName(node)}，${fields.length} 个字段`,
+    });
+    group.append(vector('rect', {
+        class: 'table-shadow',
+        x: -5,
+        y: -5,
+        width: TABLE_WIDTH + 10,
+        height: height + 10,
+        rx: 10,
+    }));
+    group.append(vector('rect', { class: 'table-body', width: TABLE_WIDTH, height, rx: 6 }));
+    const header = vector('g', {
+        class: 'table-header',
+        role: 'button',
+        tabindex: 0,
+        'aria-label': `查看业务对象 ${displayName(node)} ${node.id}`,
+    });
+    header.append(vector('path', {
+        d: `M6,0H${TABLE_WIDTH - 6}Q${TABLE_WIDTH},0 ${TABLE_WIDTH},6V${TABLE_HEADER}H0V6Q0,0 6,0Z`,
+    }));
+    header.append(vector('text', { x: 16, y: 34, class: 'table-icon' }, '▦'), vector('text', { x: 39, y: 34, class: 'table-name' }, shortName(displayName(node), 18)), vector('text', { x: TABLE_WIDTH - 15, y: 33, 'text-anchor': 'end', class: 'table-id' }, shortName(node.id, 20)));
+    header.append(vector('title', {}, `${displayName(node)} · ${node.id}\n拖动表头移动；点击查看业务对象详情`));
+    header.onkeydown = (event) => {
+        if (event.key === 'Enter' || event.key === ' ') {
+            event.preventDefault();
+            selectNode(node.key);
+        }
+    };
+    group.append(header);
+    for (const [index, field] of fields.entries()) {
+        const code = field.id.slice(node.id.length + 1);
+        const name = displayName(field);
+        const row = vector('g', {
+            class: 'table-field',
+            transform: `translate(0,${TABLE_HEADER + index * TABLE_ROW})`,
+            role: 'button',
+            tabindex: 0,
+            'aria-label': `字段 ${name} ${field.id}，${fieldType(field)}${field.attrs.optional ? '，可选' : '，必填'}`,
+        });
+        row.append(vector('rect', { width: TABLE_WIDTH, height: TABLE_ROW, class: index % 2 ? 'alternate' : '' }));
+        row.append(vector('text', { x: 14, y: 24, class: field.attrs.ref ? 'field-ref' : 'field-dot' }, field.attrs.ref ? '↗' : '·'));
+        row.append(vector('text', { x: 34, y: 24, class: 'field-code' }, shortName(code, 16)));
+        if (!field.attrs.optional)
+            row.append(vector('text', { x: 150, y: 24, class: 'field-required' }, '*'));
+        row.append(vector('text', { x: 166, y: 24, class: 'field-name' }, shortName(name, 14)), vector('text', { x: TABLE_WIDTH - 13, y: 24, 'text-anchor': 'end', class: 'field-type' }, fieldType(field)));
+        row.append(vector('title', {}, `${name} · ${field.id}\n${fieldType(field)}${field.attrs.optional ? ' · 可选' : ' · 必填'}${field.attrs.ref ? ` · 引用 ${named(field.attrs.ref, 'aggregate')}` : ''}`));
+        row.onclick = (event) => {
+            event.stopPropagation();
+            selectNode(field.key);
+        };
+        row.onkeydown = (event) => {
+            if (event.key === 'Enter' || event.key === ' ') {
+                event.preventDefault();
+                event.stopPropagation();
+                selectNode(field.key);
+            }
+        };
+        group.append(row);
+        nodeElements.set(field.key, row);
+    }
+    const footerY = height - 34;
+    group.append(vector('line', { x1: 0, x2: TABLE_WIDTH, y1: footerY, y2: footerY, class: 'table-divider' }));
+    const states = model.nodes.filter((n) => n.kind === 'state' && n.id.startsWith(`${node.id}.`)).length;
+    group.append(vector('text', { x: 14, y: footerY + 21, class: 'table-footer' }, `${fields.length} 字段 · ${states} 状态`));
+    group.append(vector('text', { x: TABLE_WIDTH - 13, y: footerY + 21, 'text-anchor': 'end', class: 'table-sql' }, shortName(String(node.attrs.table), 28)));
+    nodeLayer.append(group);
+    nodeElements.set(node.key, group);
+}
+const nodeSize = (key) => mode === 'structure'
+    ? { width: TABLE_WIDTH, height: tableOwner(visibleCards, key).height }
+    : { width: NODE_WIDTH, height: NODE_HEIGHT };
+function updatePositions() {
+    for (const n of visibleNodes) {
+        const p = positions.get(n.key);
+        nodeElements.get(n.key).setAttribute('transform', `translate(${p.x},${p.y})`);
+    }
+    // 在曲线上选标签落点，优先避开节点和已放置标签。文字始终贴在线上，
+    // 不为避让随意挪到空白区域，免得用户认错对应关系。
+    const occupied = visibleNodes.map((node) => ({
+        x: positions.get(node.key).x - 8,
+        y: positions.get(node.key).y - 8,
+        width: nodeSize(node.key).width + 16,
+        height: nodeSize(node.key).height + 16,
+    }));
+    for (const e of visibleEdges) {
+        const { path, hit, label, width } = edgeElements.get(e.key);
+        const d = mode === 'structure'
+            ? tableEdgePath(e, visibleCards, positions)
+            : edgePath(positions.get(e.from), positions.get(e.to), e.from === e.to);
+        path.setAttribute('d', d);
+        hit.setAttribute('d', d);
+        const length = path.getTotalLength();
+        const candidates = [0.5, 0.35, 0.65, 0.23, 0.77].map((t) => {
+            const p = path.getPointAtLength(length * t);
+            return { x: p.x - width / 2, y: p.y - 12, width, height: 24 };
+        });
+        const collisions = (a) => occupied.filter((b) => a.x < b.x + b.width && a.x + a.width > b.x && a.y < b.y + b.height && a.y + a.height > b.y).length;
+        candidates.sort((a, b) => collisions(a) - collisions(b));
+        const box = candidates[0];
+        label.setAttribute('transform', `translate(${box.x + width / 2},${box.y + 12})`);
+        occupied.push(box);
+    }
+}
+function highlight() {
+    const connected = selectedEdge
+        ? new Set([selectedEdge.from, selectedEdge.to])
+        : emphasizeSelection && selected && nodeElements.has(selected)
+            ? neighborhood(model, selected)
+            : null;
+    for (const [key, g] of nodeElements) {
+        if (mode === 'structure') {
+            const owner = tableOwner(visibleCards, key);
+            const related = selectedEdge
+                ? [selectedEdge.from, selectedEdge.to].some((end) => tableOwner(visibleCards, end)?.node.key === owner.node.key)
+                : tableOwner(visibleCards, selected ?? '')?.node.key === owner.node.key;
+            g.classList.toggle('selected', g.classList.contains('table-card') ? related : selectedEdge ? connected.has(key) : key === selected);
+            // 保留其他表和字段的文字对比度，选中态用边框表达，不把整张数据字典褪成背景。
+            g.classList.remove('dim');
+            g.setAttribute('aria-pressed', String(!selectedEdge && key === selected));
+            continue;
+        }
+        g.classList.toggle('selected', selectedEdge ? connected.has(key) : key === selected);
+        g.classList.toggle('dim', !!connected && !connected.has(key));
+        g.setAttribute('aria-pressed', String(!selectedEdge && key === selected));
+    }
+    for (const e of visibleEdges) {
+        const active = selectedEdge
+            ? e.key === selectedEdge.key
+            : e.from === selected ||
+                e.to === selected ||
+                (mode === 'structure' && tableOwner(cards, e.from)?.node.key === selected);
+        const { group, path } = edgeElements.get(e.key);
+        group.classList.toggle('active', active);
+        group.classList.toggle('chosen', e.key === selectedEdge?.key);
+        group.classList.toggle('dim', !!connected && !active);
+        group.classList.toggle('show-label', visibleEdges.length <= 18 || active);
+        group.setAttribute('aria-pressed', String(e.key === selectedEdge?.key));
+        path.setAttribute('marker-end', active ? 'url(#arrow-active)' : 'url(#arrow)');
+    }
+}
+function selectNode(key, reveal = false) {
+    searchTarget = null;
+    selectedEdge = null;
+    selected = key;
+    emphasizeSelection = true;
+    if (mode === 'structure' && !tableOwner(cards, key)) {
+        mode = ['state', 'capability', 'entry'].includes(byKey(key).kind) ? 'all' : 'business';
+        enabled = new Set(mode === 'all' ? Object.keys(kinds) : businessKinds);
+        aggregate = null;
+        focus = null;
+        renderFilters();
+        renderGraph();
+    }
+    if (reveal && !nodeElements.has(key)) {
+        // 搜索覆盖整张图：命中隐藏类型时显式取消作用域并开启该类型，不能点击后无反应。
+        const node = byKey(key);
+        enabled.add(node.kind);
+        showSystem ||= isSystem(node);
+        aggregate = null;
+        focus = null;
+        renderFilters();
+        renderGraph();
+    }
+    highlight();
+    renderInspector();
+    if (reveal && mode === 'structure') {
+        searchTarget = key;
+        requestAnimationFrame(centerSearchResult);
+    }
+}
+/** 搜索到长画布下方的字段时将该行移入视口。窄屏详情高度变化可能再次触发
+ * ResizeObserver，适应画布后仍需保留搜索位置，否则字段会瞬间跳回屏幕外。 */
+function centerSearchResult() {
+    // 等待绘制期间切换视图会清除目标，这一帧就不再执行旧的搜索定位。
+    if (!searchTarget)
+        return;
+    const card = tableOwner(visibleCards, searchTarget);
+    const position = positions.get(card.node.key);
+    const row = card.fields.findIndex((field) => field.key === searchTarget);
+    const offset = row >= 0
+        ? TABLE_HEADER + (row + 0.5) * TABLE_ROW
+        : Math.min(card.height / 2, svg.clientHeight / (2 * camera.scale));
+    camera.x = svg.clientWidth / 2 - (position.x + TABLE_WIDTH / 2) * camera.scale;
+    camera.y = svg.clientHeight / 2 - (position.y + offset) * camera.scale;
+    applyCamera();
+}
+function selectEdge(edge) {
+    searchTarget = null;
+    selectedEdge = edge;
+    if (mode === 'structure' && edge.kind !== 'refs') {
+        // 卡片中包含字段的关系已经用行表达；显式查看其他关系时进入完整本体，
+        // 保留原始端点和上一次实现的关系解释，而不是伪造一条表间连线。
+        mode = 'all';
+        enabled = new Set(Object.keys(kinds));
+        aggregate = null;
+        focus = null;
+        renderFilters();
+    }
+    // 右侧关系列表也包含当前筛选隐藏的邻居；选中后显式展示两端，解释有图可对照。
+    if (!edgeElements.has(edge.key)) {
+        for (const key of [edge.from, edge.to]) {
+            const node = byKey(key);
+            enabled.add(node.kind);
+            showSystem ||= isSystem(node);
+        }
+        aggregate = null;
+        focus = null;
+        renderFilters();
+        renderGraph();
+    }
+    highlight();
+    renderInspector();
+    element('inspector').scrollTop = 0;
+}
+function renderEdgeInspector(panel, edge) {
+    const explanation = explainEdge(edge, model, snapshot.presentation.labels);
+    const top = html('div', 'inspector-top');
+    top.append(html('span', '', '关系说明'), html('span', '', edge.derived ? '虚线 · 视图推导' : '实线 · 声明抽取'));
+    panel.append(top, html('span', 'relation-category', explanation.category), html('h2', '', explanation.label));
+    const route = html('div', 'relation-route');
+    for (const [index, key] of [edge.from, edge.to].entries()) {
+        if (index)
+            route.append(html('span', 'relation-arrow', `↓ ${explanation.label}`));
+        const node = byKey(key);
+        const button = html('button', 'relation-endpoint');
+        button.title = `查看${displayName(node)}的节点详情`;
+        button.append(html('small', '', `${index ? '终点' : '起点'} · ${kinds[node.kind].label}`), html('strong', '', displayName(node)), html('code', '', node.id));
+        button.onclick = () => selectNode(key, true);
+        route.append(button);
+    }
+    panel.append(route);
+    const section = (title, text) => {
+        const box = html('section', 'relation-explanation');
+        box.append(html('h3', '', title), html('p', '', text));
+        panel.append(box);
+        return box;
+    };
+    section('为什么连接', explanation.why);
+    section('连接有什么用', explanation.purpose);
+    section('箭头怎么读', explanation.direction);
+    const source = section('声明依据', '以下是抽取到的声明属性，可与源码核对。');
+    for (const evidence of explanation.evidence)
+        source.append(html('div', 'source-location', evidence));
+    const node = explanation.source;
+    const owner = model.nodes.find((n) => n.kind === 'aggregate' && node.id.startsWith(`${n.id}.`));
+    const location = node.file ? node : owner?.file ? owner : null;
+    source.append(html('p', 'source-note', location
+        ? `${location.file}:${location.line ?? 1}${location !== node ? '（所属业务对象声明）' : ''}`
+        : '来自框架包，当前项目未记录源码位置。'));
+}
+function renderInspector() {
+    const panel = element('inspector');
+    panel.replaceChildren();
+    if (selectedEdge) {
+        renderEdgeInspector(panel, selectedEdge);
+        return;
+    }
+    if (!selected) {
+        panel.append(html('p', 'inspector-description', '选择节点查看属性，或点击连线了解为什么连接、连接有什么用。'));
+        return;
+    }
+    const node = byKey(selected), meta = kinds[node.kind];
+    const top = html('div', 'inspector-top');
+    top.append(html('span', '', '节点详情'), html('span', '', '↗'));
+    panel.append(top);
+    const icon = html('div', 'inspector-icon', meta.short);
+    icon.style.color = meta.color;
+    icon.style.backgroundColor = `${meta.color}12`;
+    panel.append(icon);
+    panel.append(html('h2', '', displayName(node)), html('div', 'node-identifier', node.id));
+    const pill = html('span', 'kind-pill', meta.label);
+    pill.style.color = meta.color;
+    pill.style.backgroundColor = `${meta.color}12`;
+    panel.append(pill);
+    panel.append(html('p', 'inspector-description', String(node.attrs.description ?? descriptions[node.kind])));
+    if (node.kind === 'aggregate') {
+        const note = html('div', 'aggregate-explainer');
+        note.append(html('strong', '', '什么是业务对象（聚合）？'), html('p', '', '框架把一组需要一起遵守业务规则的数据和操作作为一个整体管理，技术上称为“聚合”。它包含字段、状态和命令，不一定只对应一张数据库表。'));
+        panel.append(note);
+    }
+    const actions = html('div', 'inspector-actions');
+    const focusButton = html('button', 'button secondary', '◎ 聚焦关联');
+    focusButton.onclick = () => {
+        focus = node.key;
+        aggregate = null;
+        if (mode === 'structure') {
+            const card = tableOwner(cards, node.key);
+            const refs = model.edges.filter((edge) => edge.kind === 'refs' &&
+                (edge.to === card.node.key || card.fields.some((field) => field.key === edge.from)));
+            showSystem ||= refs.some((edge) => isSystem(byKey(edge.to)) || isSystem(byKey(edge.from)));
+            renderFilters();
+            renderGraph();
+            return;
+        }
+        const adjacent = neighborhood(model, node.key);
+        for (const n of model.nodes.filter((n) => adjacent.has(n.key))) {
+            enabled.add(n.kind);
+            showSystem ||= isSystem(n);
+        }
+        renderFilters();
+        renderGraph();
+    };
+    const copy = html('button', 'button secondary', '复制标识');
+    copy.onclick = async () => {
+        try {
+            await navigator.clipboard.writeText(node.id);
+            copy.textContent = '已复制';
+        }
+        catch (error) {
+            notify(`复制失败：${error.message}`);
+        }
+    };
+    actions.append(focusButton, copy);
+    panel.append(actions);
+    const section = (title, count) => {
+        const div = html('section', 'detail-section'), h = html('h3', '', title);
+        if (count !== undefined)
+            h.append(html('span', '', String(count)));
+        div.append(h);
+        panel.append(div);
+        return div;
+    };
+    const info = section('声明属性');
+    const row = (label, value) => {
+        if (value === undefined || value === null)
+            return;
+        const div = html('div', 'detail-row');
+        div.append(html('span', '', label), html('span', '', typeof value === 'object' ? JSON.stringify(value) : String(value)));
+        info.append(div);
+    };
+    row('类型', meta.label);
+    if (node.kind === 'aggregate') {
+        row('数据表', node.attrs.table);
+        const scope = node.attrs.scope;
+        row('部门范围', scope?.dept ? named(`${node.id}.${scope.dept}`, 'field') : undefined);
+        row('归属字段', scope?.owner ? named(`${node.id}.${scope.owner}`, 'field') : undefined);
+        row('状态数量', model.nodes.filter((n) => n.kind === 'state' && n.id.startsWith(`${node.id}.`)).length);
+        row('命令数量', model.nodes.filter((n) => n.kind === 'command' && n.id.startsWith(`${node.id}.`)).length);
+    }
+    else if (node.kind === 'command') {
+        const agg = node.id.split('.')[0];
+        const stateName = (state) => (state === 'new' ? '新建' : named(`${agg}.${state}`, 'state'));
+        row('起始状态', Array.isArray(node.attrs.from)
+            ? node.attrs.from.map(stateName).join('、')
+            : stateName(String(node.attrs.from)));
+        row('目标状态', node.attrs.to ? stateName(String(node.attrs.to)) : '保持当前状态');
+        const actors = {
+            user: '用户',
+            process: '审批流程',
+            external: '外部系统',
+            job: '定时任务',
+            reaction: '事件反应',
+            system: '系统',
+        };
+        row('调用身份', node.attrs.invokedBy.map((kind) => actors[kind] ?? kind).join('、'));
+        row('约束', node.attrs.constraints.map((name) => constraintLabel(name, agg)).join('；') || '无');
+    }
+    else {
+        for (const [key, label] of Object.entries({
+            event: '事件',
+            command: '调用命令',
+            process: '审批流程',
+            cron: '调度表达式',
+            connector: '连接器',
+            operation: '操作',
+            sensitive: '敏感类型',
+            kind: '字段类型',
+            ref: '引用对象',
+            optional: '可选字段',
+            acquires: '获取资源',
+            releases: '释放资源',
+            terminal: '终态',
+            initial: '初态',
+        })) {
+            const value = node.attrs[key];
+            if (value === undefined || value === null)
+                continue;
+            row(label, detailValue(key, value));
+        }
+    }
+    const source = section('声明位置');
+    // 字段、状态没有独立源码位置时只引用所属聚合，并在文案上说明来源。
+    const owner = model.nodes.find((n) => n.kind === 'aggregate' && node.id.startsWith(`${n.id}.`));
+    const location = node.file ? node : owner?.file ? owner : null;
+    if (location) {
+        source.append(html('div', 'source-location', `${location.file}:${location.line ?? 1}`));
+        if (location !== node)
+            source.append(html('p', 'source-note', '位置来自所属业务对象声明。'));
+    }
+    else
+        source.append(html('p', 'source-note', node.kind === 'entry' ? '由新建命令的迁移关系推导。' : '来自框架包，当前项目未记录源码位置。'));
+    const relations = model.edges.filter((e) => e.from === node.key || e.to === node.key);
+    const relationSection = section('关联关系', relations.length);
+    if (relations.length)
+        relationSection.append(html('p', 'source-note', '点击一项，查看连接原因与用途。'));
+    if (!relations.length)
+        relationSection.append(html('p', 'source-note', '当前声明没有关联关系。'));
+    for (const edge of relations) {
+        const explanation = explainEdge(edge, model, snapshot.presentation.labels);
+        const outgoing = edge.from === node.key;
+        const target = byKey(outgoing ? edge.to : edge.from);
+        const button = html('button', 'relation-button');
+        const dot = html('span', 'relation-dot');
+        dot.style.backgroundColor = kinds[target.kind].color;
+        const text = html('div');
+        text.append(html('strong', '', displayName(target)), html('small', '', `${outgoing ? '→' : '←'} ${explanation.label}`), html('small', 'relation-code', target.id));
+        button.append(dot, text, html('span', '', '解释 ›'));
+        button.onclick = () => selectEdge(edge);
+        relationSection.append(button);
+    }
+    const details = html('details');
+    details.append(html('summary', '', '查看声明元数据'), html('pre', 'detail-json', JSON.stringify(node.attrs, null, 2)));
+    panel.append(details);
+}
+/** 把会直接影响阅读理解的属性值翻译为业务名称；SQL 表名、cron 和折叠的
+ * 原始元数据仍保持技术原文，方便开发者核对实现。 */
+function detailValue(key, value) {
+    if (typeof value === 'boolean')
+        return value ? '是' : '否';
+    if (key === 'event' || key === 'command')
+        return named(value, key);
+    if (key === 'ref')
+        return named(value, 'aggregate');
+    if (key === 'process') {
+        const binding = model.nodes.find((n) => n.kind === 'approval' && n.attrs.process === value);
+        return binding ? displayName(binding) : String(value);
+    }
+    if (key === 'connector')
+        return named(`connector:${value}`, 'connector');
+    if (key === 'acquires' || key === 'releases')
+        return snapshot.presentation.labels[`resource:${value}`] ?? String(value);
+    if (key === 'operation')
+        return snapshot.presentation.labels[`operation:${value}`] ?? String(value);
+    const types = {
+        money: '金额',
+        text: '文本',
+        int: '整数',
+        decimal: '小数',
+        float: '浮点数',
+        bool: '布尔值',
+        boolean: '布尔值',
+        id: '唯一标识',
+        ref: '关联引用',
+        list: '列表',
+        json: '结构化数据',
+        date: '日期',
+        datetime: '日期时间',
+        enum: '枚举',
+        phone: '电话号码',
+        email: '电子邮箱',
+        name: '姓名',
+    };
+    return ['kind', 'sensitive'].includes(key) ? (types[String(value)] ?? String(value)) : String(value);
+}
+function constraintLabel(name, aggregateId) {
+    const ceiling = /^ceiling\((.+)\)$/.exec(name);
+    if (ceiling)
+        return `${named(`${aggregateId}.${ceiling[1]}`, 'field')}不超过审批额度`;
+    const sod = /^sod\.notSameAs\((.+)\)$/.exec(name);
+    if (sod)
+        return `审批人与${named(`${aggregateId}.${sod[1]}`, 'field')}不同`;
+    const builtins = {
+        stepUp: '需要二次认证',
+        knownCapability: '能力点必须已声明',
+        noEscalation: '不能授予超出自身的能力',
+        noWiderScope: '不能授予超出自身的数据范围',
+        noEscalationViaRoles: '不能通过分配角色提权',
+    };
+    return builtins[name] ?? name;
+}
+const descriptions = {
+    aggregate: '统一管理字段、状态、业务操作和数据范围的业务对象。',
+    command: '受权限和状态约束的业务写入入口。',
+    event: '命令产生的领域事件，用于连接后续业务协作。',
+    reaction: '订阅领域事件并调用命令，可声明资源获取与释放。',
+    query: '通过已声明的读依赖查询安全视图。',
+    approval: '把业务事件、审批流程与结论命令连接起来。',
+    route: '代码中声明的审批步骤与分支条件。',
+    job: '按调度表达式触发、显式声明读取与调用范围的任务。',
+    connector: '声明第三方地址及可调用的操作。',
+    outbound: '将领域事件映射为第三方调用。',
+    inbound: '将验签后的外部回调映射为业务命令。',
+    field: '业务字段的类型、范围与敏感属性。',
+    state: '业务对象生命周期中的一个状态。',
+    capability: '从聚合声明派生的访问能力点。',
+    entry: '新建命令进入初始业务状态的虚拟起点。',
+};
+function renderFindings() {
+    const list = element('findings-list');
+    list.replaceChildren();
+    for (const f of snapshot.findings) {
+        const item = html('article', 'finding');
+        item.append(html('code', '', f.code), html('p', '', f.reason));
+        if (f.fix)
+            item.append(html('p', '', `修复：${f.fix}`));
+        if (f.at)
+            item.append(html('small', '', f.at));
+        list.append(item);
+    }
+}
+function searchNodes() {
+    const query = element('search').value.trim().toLowerCase();
+    const results = element('search-results');
+    results.replaceChildren();
+    results.hidden = !query;
+    if (!query)
+        return;
+    const matches = model.nodes.filter((n) => matchesNode(n, query, snapshot.presentation.labels));
+    for (const n of matches.slice(0, 30)) {
+        const button = html('button', 'search-result');
+        const names = html('span', 'search-names');
+        names.append(html('strong', '', displayName(n)), html('span', '', n.id));
+        button.append(html('small', '', kinds[n.kind].label), names);
+        button.onclick = () => {
+            selectNode(n.key, true);
+            results.hidden = true;
+            element('search').value = '';
+        };
+        results.append(button);
+    }
+    if (!matches.length)
+        results.append(html('div', 'search-empty', '没有匹配的声明，试试命令名或字段名。'));
+}
+function applyCamera() {
+    viewport.setAttribute('transform', `translate(${camera.x},${camera.y}) scale(${camera.scale})`);
+    element('zoom-level').textContent = `${Math.round(camera.scale * 100)}%`;
+}
+function fit() {
+    if (!visibleNodes.length)
+        return;
+    const bounds = svg.getBoundingClientRect();
+    const xs = [...positions.values()].map((p) => p.x), ys = [...positions.values()].map((p) => p.y);
+    const minX = Math.min(...xs), minY = Math.min(...ys), width = Math.max(...visibleNodes.map((node) => positions.get(node.key).x + nodeSize(node.key).width)) - minX, height = Math.max(...visibleNodes.map((node) => positions.get(node.key).y + nodeSize(node.key).height)) - minY;
+    camera.scale = Math.min((bounds.width - 65) / width, (bounds.height - 85) / height, mode === 'structure' ? 1 : 1.2);
+    // 表字段是正文，默认不把它们缩成难读的小字。长表可纵向平移，适当留白
+    // 比为了容纳全图而把所有字段缩到 35% 更适合阅读。
+    if (mode === 'structure')
+        camera.scale = Math.max(Math.min(0.8, (bounds.width - 40) / TABLE_WIDTH), camera.scale);
+    camera.x = (bounds.width - width * camera.scale) / 2 - minX * camera.scale;
+    camera.y =
+        (mode === 'structure'
+            ? Math.max(30, (bounds.height - height * camera.scale) / 2)
+            : (bounds.height - height * camera.scale) / 2 - 7) -
+            minY * camera.scale;
+    applyCamera();
+    if (mode === 'structure' && searchTarget)
+        centerSearchResult();
+}
+function zoom(factor, x = svg.clientWidth / 2, y = svg.clientHeight / 2) {
+    searchTarget = null;
+    const scale = Math.min(2.5, Math.max(0.15, camera.scale * factor));
+    camera.x = x - ((x - camera.x) * scale) / camera.scale;
+    camera.y = y - ((y - camera.y) * scale) / camera.scale;
+    camera.scale = scale;
+    applyCamera();
+}
+// 指针捕获同时支持鼠标和触控。节点拖动修改布局坐标，空白拖动修改视口；
+// 拖动结束不触发选择，避免移动节点时不断切换右侧详情。
+let drag = null;
+svg.addEventListener('pointerdown', (event) => {
+    if (event.button !== 0)
+        return;
+    searchTarget = null;
+    // 连线由自身 click/键盘处理；不进入画布平移，否则 pointer capture 会吞掉点击。
+    if (event.target.closest('.edge-group'))
+        return;
+    if (event.target.closest('.table-field'))
+        return;
+    const target = event.target.closest('.node');
+    const key = target?.dataset.key;
+    drag = {
+        id: event.pointerId,
+        key,
+        x: event.clientX,
+        y: event.clientY,
+        initial: key ? { ...positions.get(key) } : { ...camera },
+        moved: false,
+    };
+    svg.setPointerCapture(event.pointerId);
+    svg.classList.add('dragging');
+});
+svg.addEventListener('pointermove', (event) => {
+    if (!drag || drag.id !== event.pointerId)
+        return;
+    const dx = event.clientX - drag.x, dy = event.clientY - drag.y;
+    drag.moved ||= Math.abs(dx) + Math.abs(dy) > 4;
+    if (drag.key) {
+        positions.set(drag.key, { x: drag.initial.x + dx / camera.scale, y: drag.initial.y + dy / camera.scale });
+        updatePositions();
+    }
+    else {
+        camera.x = drag.initial.x + dx;
+        camera.y = drag.initial.y + dy;
+        applyCamera();
+    }
+});
+const endDrag = (event) => {
+    if (!drag || drag.id !== event.pointerId)
+        return;
+    if (event.type === 'pointerup' && !drag.moved) {
+        if (drag.key)
+            selectNode(drag.key);
+        else {
+            selected = null;
+            selectedEdge = null;
+            highlight();
+            renderInspector();
+        }
+    }
+    drag = null;
+    svg.classList.remove('dragging');
+};
+svg.addEventListener('pointerup', endDrag);
+svg.addEventListener('pointercancel', endDrag);
+svg.addEventListener('wheel', (event) => {
+    event.preventDefault();
+    const rect = svg.getBoundingClientRect();
+    zoom(Math.exp(-event.deltaY * 0.0015), event.clientX - rect.left, event.clientY - rect.top);
+}, { passive: false });
+new ResizeObserver(() => {
+    if (snapshot) {
+        if (mode === 'structure') {
+            positions = layoutTables(visibleCards, visibleEdges, svg.clientWidth < 680 ? 1 : 2);
+            updatePositions();
+        }
+        fit();
+    }
+}).observe(svg);
+function resetView() {
+    mode = 'structure';
+    aggregate = null;
+    focus = null;
+    showSystem = false;
+    enabled = new Set(businessKinds);
+    renderFilters();
+    renderGraph();
+}
+element('reset-view').onclick = resetView;
+element('reset-types').onclick = () => {
+    enabled = new Set(mode === 'business' ? businessKinds : Object.keys(kinds));
+    renderFilters();
+    renderGraph();
+};
+element('exit-focus').onclick = () => {
+    focus = null;
+    renderGraph();
+};
+element('system-toggle').onchange = (event) => {
+    showSystem = event.target.checked;
+    aggregate = null;
+    focus = null;
+    renderFilters();
+    renderGraph();
+};
+document.querySelectorAll('[data-mode]').forEach((button) => {
+    button.onclick = () => {
+        mode = button.dataset.mode;
+        selectedEdge = null;
+        enabled = new Set(mode === 'business' ? businessKinds : Object.keys(kinds));
+        focus = null;
+        if (mode === 'structure' && selected)
+            selected =
+                tableOwner(cards, selected)?.node.key ?? cards.find((card) => !isSystem(card.node))?.node.key ?? null;
+        renderFilters();
+        renderGraph();
+        renderInspector();
+    };
+});
+element('refresh').onclick = () => void load(true);
+element('search').addEventListener('input', searchNodes);
+element('search').addEventListener('focus', searchNodes);
+element('search').addEventListener('keydown', (event) => {
+    if (event.key === 'Enter')
+        element('search-results').querySelector('button')?.click();
+    if (event.key === 'Escape')
+        element('search-results').hidden = true;
+});
+document.addEventListener('pointerdown', (event) => {
+    if (!event.target.closest('.search-wrap'))
+        element('search-results').hidden = true;
+});
+document.addEventListener('keydown', (event) => {
+    if (event.key === '/' &&
+        !(event.target instanceof HTMLInputElement) &&
+        !element('findings-dialog').open) {
+        event.preventDefault();
+        element('search').focus();
+    }
+});
+element('zoom-in').onclick = () => zoom(1.2);
+element('zoom-out').onclick = () => zoom(1 / 1.2);
+element('fit').onclick = () => {
+    searchTarget = null;
+    fit();
+};
+element('relayout').onclick = () => renderGraph();
+element('show-findings').onclick = () => element('findings-dialog').showModal();
+element('close-findings').onclick = () => element('findings-dialog').close();
+element('toggle-sidebar').onclick = () => {
+    const open = element('sidebar').classList.toggle('open');
+    element('toggle-sidebar').setAttribute('aria-expanded', String(open));
+};
+element('download').onclick = () => {
+    const url = URL.createObjectURL(new Blob([JSON.stringify(snapshot.graph, null, 2)], { type: 'application/json' }));
+    const link = html('a');
+    link.href = url;
+    link.download = 'ontology.json';
+    link.click();
+    setTimeout(() => URL.revokeObjectURL(url), 1000);
+};
+void load();