@yss123/cage-cli 0.1.0 → 0.3.0

package/graph-ui/app.js

@@ -1,8 +1,14 @@
-import { kinds, nodeLabel, matchesNode, projectGraph, neighborhood, isSystem, layoutGraph, edgePath, NODE_WIDTH, NODE_HEIGHT, } from './model.js';
+import { kinds, nodeLabel, projectGraph, neighborhood, isSystem, layoutGraph, edgePath, NODE_WIDTH, NODE_HEIGHT, } from './model.js';
 import { explainEdge } from './relations.js';
+import { searchGraphNodes as rankGraphNodes } from './graph-search.js';
+import { businessBlocks, businessConstraintLabel, businessJourneys } from './graph-business.js';
+import { renderBusiness, disposeBusiness, sourcePreview } from './business.js';
 import { tableCards, tableOwner, layoutTables, tableEdgePath, fieldType, TABLE_WIDTH, TABLE_HEADER, TABLE_ROW, } from './structure.js';
 // 页面不引入图形框架或远程 CDN。百级声明图使用 SVG，即可保留清晰缩放、
 // 键盘选择和可检查的节点语义；所有数据都由本地 CLI 抽取服务提供。
+/**
+ * 获取 index.html 约定的固定 DOM 锚点并标注调用方类型；这些 ID 由静态骨架提供。
+ */
 const element = (id) => document.getElementById(id);
 const svg = document.getElementById('graph');
 const viewport = document.getElementById('viewport');
@@ -19,7 +25,7 @@ let selectedEdge = null;
 let emphasizeSelection = false;
 let aggregate = null;
 let focus = null;
-let mode = 'structure';
+let mode = 'business';
 let cards = [];
 let visibleCards = [];
 let searchTarget = null;
@@ -29,12 +35,18 @@ const businessKinds = Object.keys(kinds).filter((k) => !['field', 'state', 'capa
 let enabled = new Set(businessKinds);
 const nodeElements = new Map();
 const edgeElements = new Map();
+/**
+ * 创建页面元素并用 textContent 写文本，避免把抽取文案当作 HTML 执行；返回未挂载节点。
+ */
 function html(tag, className = '', text = '') {
     const node = document.createElement(tag);
     node.className = className;
     node.textContent = text;
     return node;
 }
+/**
+ * 创建 SVG 命名空间元素并设置属性/文本，供节点和连线绘制；不进行布局计算。
+ */
 function vector(tag, attrs = {}, text = '') {
     const node = document.createElementNS(ns, tag);
     for (const [key, value] of Object.entries(attrs))
@@ -42,9 +54,71 @@ function vector(tag, attrs = {}, text = '') {
     node.textContent = text;
     return node;
 }
+/**
+ * 在当前展示模型按完整 key 查找节点；调用者只传入模型或检索结果中的已知 key。
+ */
 const byKey = (key) => model.nodes.find((n) => n.key === key);
+/**
+ * 使用当前快照的中文覆盖获取显示名，保留底层业务 ID。
+ */
 const displayName = (node) => nodeLabel(node, snapshot.presentation.labels);
+/**
+ * 按 patch 修改当前查询参数，null 表示移除，并按 replace 决定替换或新增历史。
+ * 不自行重渲染；调用方必须同步页面状态，避免地址和视图分离。
+ */
+function address(patch, replace = false) {
+    const url = new URL(location.href);
+    for (const [key, value] of Object.entries(patch)) {
+        if (value === null)
+            url.searchParams.delete(key);
+        else
+            url.searchParams.set(key, value);
+    }
+    if (url.href !== location.href)
+        history[replace ? 'replaceState' : 'pushState'](null, '', url);
+}
+/**
+ * 切回业务视图并更新 URL、筛选及画布；仅换场景时滚到入口，窄屏选步骤时滚到详情。
+ */
+function navigateBusiness(patch) {
+    const previousScene = element('business-view').dataset.scene;
+    mode = 'business';
+    selectedEdge = null;
+    address({ view: 'business', node: null, object: null, ...patch });
+    renderFilters();
+    renderGraph();
+    if (previousScene !== element('business-view').dataset.scene)
+        element('explorer').scrollIntoView({ block: 'start' });
+    if (patch.step && matchMedia('(max-width: 800px)').matches)
+        element('business-view').querySelector('.business-detail')?.scrollIntoView({ block: 'start' });
+}
+/**
+ * 从 URL 恢复可用视图、选中对象与系统开关，删除或无效节点不被强行选中。
+ * 清除临时聚焦和边选择，供首次加载及浏览器前进后退复用。
+ */
+function restoreAddress() {
+    const params = new URLSearchParams(location.search);
+    const view = params.get('view');
+    mode = view === 'structure' || view === 'all' ? view : 'business';
+    const node = params.get('node');
+    if (node && byKey(node))
+        selected = node;
+    if (mode === 'structure' && selected)
+        selected =
+            tableOwner(cards, selected)?.node.key ?? cards.find((card) => !isSystem(card.node))?.node.key ?? null;
+    const object = params.get('object');
+    aggregate = model.nodes.some((n) => n.kind === 'aggregate' && n.id === object) ? object : null;
+    showSystem = params.get('system') === '1';
+    if (selected && mode !== 'business')
+        showSystem ||= isSystem(byKey(selected));
+    focus = null;
+    selectedEdge = null;
+    enabled = new Set(mode === 'all' ? Object.keys(kinds) : businessKinds);
+}
 // 中文字符约占两个半角字宽，不能沿用英文按字符数截断，否则标题会溢出卡片。
+/**
+ * 按半角/中文近似宽度截断画布短标题，超限添加省略号；不是精确字体测量。
+ */
 function shortName(text, width = 23) {
     let result = '', used = 0;
     for (const char of text) {
@@ -55,16 +129,26 @@ function shortName(text, width = 23) {
     }
     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;
 }
+/**
+ * 读取或重新抽取快照，再重建投影、卡片与详情。
+ * refresh 为 true 时调用 POST；期间禁用刷新按钮，失败保留旧图并提示其来源，finally 恢复按钮。
+ */
 async function load(refresh = false) {
     const button = element('refresh');
     button.disabled = true;
@@ -94,6 +178,8 @@ async function load(refresh = false) {
             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;
         }
+        if (!refresh)
+            restoreAddress();
         renderSummary();
         renderFilters();
         renderGraph();
@@ -114,6 +200,9 @@ async function load(refresh = false) {
         element('loading').hidden = true;
     }
 }
+/**
+ * 从当前快照更新项目标题、节点统计和规则状态；通过只表示声明规则，不表示业务测试通过。
+ */
 function renderSummary() {
     element('project-name').textContent = snapshot.presentation.title;
     element('project-name').title = snapshot.project;
@@ -133,13 +222,25 @@ function renderSummary() {
     element('show-findings').hidden = !snapshot.findings.length;
     const time = new Date(snapshot.generatedAt).toLocaleTimeString('zh-CN', { hour12: false });
     element('updated').textContent = `最近抽取 ${time}`;
+    const health = element('business-health');
+    health.replaceChildren(html('span', '', `${element('health').textContent} · 最近抽取 ${time}`));
+    if (snapshot.findings.length) {
+        const findings = html('button', 'text-button', '查看声明问题 ↗');
+        findings.onclick = () => element('findings-dialog').showModal();
+        health.append(findings);
+    }
 }
+/**
+ * 按当前视图重建板块/对象与类型筛选，回调更新内存状态并请求重绘，不修改声明。
+ */
 function renderFilters() {
-    element('types-heading').hidden = mode === 'structure';
-    element('type-filters').hidden = mode === 'structure';
+    element('types-heading').hidden = mode !== 'all';
+    element('type-filters').hidden = mode !== 'all';
     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 blocks = businessBlocks(model, snapshot.presentation.labels, showSystem);
+    element('objects-heading-label').textContent = mode === 'business' ? '业务板块' : '业务对象';
+    element('aggregate-total').textContent = String(mode === 'business' ? blocks.length : aggregates.length);
     const list = element('aggregate-list');
     list.replaceChildren();
     const addAggregate = (id, label, count) => {
@@ -149,14 +250,42 @@ function renderFilters() {
         button.onclick = () => {
             aggregate = id;
             focus = null;
+            address({ view: mode, object: id });
             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);
+    if (mode === 'business') {
+        const selectedBlock = new URLSearchParams(location.search).get('block');
+        for (const block of [{ id: null, title: '全部业务', count: blocks.length }, ...blocks.map(b => ({ id: b.id, title: b.title, count: businessJourneys(b, model).length }))]) {
+            const button = html('a', `aggregate-button${selectedBlock === block.id ? ' active' : ''}`);
+            const url = new URL(location.href);
+            for (const key of ['flow', 'step', 'source', 'tab', 'node', 'object'])
+                url.searchParams.delete(key);
+            url.searchParams.set('view', 'business');
+            if (block.id)
+                url.searchParams.set('block', block.id);
+            else
+                url.searchParams.delete('block');
+            button.href = url.pathname + url.search;
+            button.append(html('span', '', block.id ? '◇' : '⊞'), html('span', '', block.title), html('b', '', String(block.count)));
+            button.onclick = (event) => {
+                if (event.button || event.ctrlKey || event.metaKey || event.shiftKey || event.altKey)
+                    return;
+                event.preventDefault();
+                navigateBusiness({ block: block.id, flow: null, step: null, tab: null, source: null });
+                element('sidebar').classList.remove('open');
+                element('toggle-sidebar').setAttribute('aria-expanded', 'false');
+            };
+            list.append(button);
+        }
+    }
+    else {
+        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)) {
@@ -189,6 +318,9 @@ function renderFilters() {
 }
 /** 选一个聚合时，先纳入它自己的声明，再沿真实关系扩展业务链。
  * 不沿其他聚合的归属边扩散，避免选采购单却展开所有组织管理命令。 */
+/**
+ * 围绕指定聚合沿有限三跳显式关系收集相关节点，避免归属虚线扩散为所有组织命令。
+ */
 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++) {
@@ -202,7 +334,47 @@ function aggregateNodes(id) {
     }
     return keys;
 }
+/**
+ * 按业务、结构或完整模式重建可见画布，应用类型/系统/对象/邻域筛选。
+ * resetLayout 决定是否重新排布；切走业务视图先释放专属监听器，绘制不修改语义图。
+ */
 function renderGraph(resetLayout = true) {
+    const business = mode === 'business';
+    element('explorer').classList.toggle('business-mode', business);
+    element('main').classList.toggle('business-page', business);
+    element('business-view').hidden = !business;
+    element('page-title').textContent = business ? '业务地图' : '本体图谱';
+    element('page-description').textContent = business
+        ? '先理解业务，再沿流程找到实现。'
+        : '从声明出发，看见业务如何连接。';
+    element('metric-first-label').textContent = business ? '业务板块' : '业务对象';
+    element('metric-second-label').textContent = business ? '业务流程' : '声明节点';
+    element('metric-third-label').textContent = business ? '业务对象' : '声明关系';
+    const blocks = businessBlocks(model, snapshot.presentation.labels, showSystem);
+    element('metric-aggregates').textContent = String(business ? blocks.length : cards.length);
+    element('metric-nodes').textContent = String(business ? new Set(blocks.flatMap((b) => businessJourneys(b, model).map((n) => n.key))).size : snapshot.graph.nodes.length);
+    element('metric-edges').textContent = String(business ? blocks.flatMap((b) => b.objects).length : snapshot.graph.edges.length);
+    if (business) {
+        renderBusiness(element('business-view'), model, snapshot, {
+            showSystem,
+            navigate: navigateBusiness,
+            inspect: (key, view) => {
+                mode = view;
+                enabled = new Set(Object.keys(kinds));
+                selected = key;
+                selectedEdge = null;
+                focus = null;
+                aggregate = view === 'structure' ? byKey(key).id : null;
+                showSystem ||= isSystem(byKey(key));
+                address({ view, node: key, object: aggregate, system: showSystem ? '1' : null });
+                renderFilters();
+                renderGraph();
+                renderInspector();
+            },
+        });
+        return;
+    }
+    disposeBusiness(element('business-view'));
     searchTarget = null;
     const scope = aggregate ? aggregateNodes(aggregate) : null;
     const focused = focus ? neighborhood(model, focus) : null;
@@ -336,7 +508,7 @@ function renderGraph(resetLayout = true) {
         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 = '↗ 字段引用　＊ 必填　卡片展示声明字段';
+        element('edge-legend').textContent = '↗ 外键引用　⇄ 集合关系（非主表列）　＊ 必填';
     }
     else {
         element('edge-legend').replaceChildren(html('span', 'legend-line'), document.createTextNode(' 声明关系 '), html('span', 'legend-line dashed'), document.createTextNode(' 视图归属'));
@@ -346,6 +518,10 @@ function renderGraph(resetLayout = true) {
 }
 /** 绿色表头、逐行字段和表名保持在同一 SVG 卡片里。字段是可选择的原始节点，
  * 表头负责拖动卡片，字段点击不会误触画布拖动或把数据结构重新拆散。 */
+/**
+ * 为一个真实聚合绘制字段卡片，保留字段身份供点击、键盘和关系解释使用。
+ * 卡片尺寸来自字段数量，敏感/可选/关系标记只展示声明事实。
+ */
 function renderTable(card) {
     const { node, fields, height } = card;
     const group = vector('g', {
@@ -389,15 +565,15 @@ function renderTable(card) {
             transform: `translate(0,${TABLE_HEADER + index * TABLE_ROW})`,
             role: 'button',
             tabindex: 0,
-            'aria-label': `字段 ${name} ${field.id}，${fieldType(field)}${field.attrs.optional ? '，可选' : '，必填'}`,
+            'aria-label': `字段 ${name} ${field.id}，${fieldType(field)}${field.attrs.virtual ? '，集合关系，不占主表列' : 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: 14, y: 24, class: field.attrs.ref ? 'field-ref' : 'field-dot' }, field.attrs.virtual ? '⇄' : field.attrs.ref ? '↗' : '·'));
         row.append(vector('text', { x: 34, y: 24, class: 'field-code' }, shortName(code, 16)));
-        if (!field.attrs.optional)
+        if (!field.attrs.optional && !field.attrs.virtual)
             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.append(vector('title', {}, `${name} · ${field.id}\n${fieldType(field)}${field.attrs.virtual ? ' · 集合关系，不占主表列' : field.attrs.optional ? ' · 可选' : ' · 必填'}${field.attrs.ref ? ` · 关联 ${named(field.attrs.ref, 'aggregate')}` : ''}`));
         row.onclick = (event) => {
             event.stopPropagation();
             selectNode(field.key);
@@ -420,9 +596,16 @@ function renderTable(card) {
     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 };
+/**
+ * 将内存节点位置同步到 SVG 并重算连线，随后在候选线段位置选择碰撞较少的标签落点。
+ * 标签仍贴近对应线，拖动只变展示坐标，不保存后端数据。
+ */
 function updatePositions() {
     for (const n of visibleNodes) {
         const p = positions.get(n.key);
@@ -455,6 +638,9 @@ function updatePositions() {
         occupied.push(box);
     }
 }
+/**
+ * 同步节点/边选择高亮及无障碍状态，结构视图保留其他字段的可读对比度。
+ */
 function highlight() {
     const connected = selectedEdge
         ? new Set([selectedEdge.from, selectedEdge.to])
@@ -492,14 +678,41 @@ function highlight() {
         path.setAttribute('marker-end', active ? 'url(#arrow-active)' : 'url(#arrow)');
     }
 }
+/**
+ * 根据节点选择切到合适业务入口或技术视图，必要时显式解除隐藏筛选再定位。
+ * reveal 请求把目标带入视口，不代表执行该节点的业务操作。
+ */
 function selectNode(key, reveal = false) {
+    if (mode === 'business') {
+        const node = byKey(key);
+        const processKey = node.kind === 'stage' ? `process:${node.attrs.process}` : key;
+        const blocks = businessBlocks(model, snapshot.presentation.labels, showSystem || isSystem(byKey(key)));
+        const block = blocks.find((b) => b.objects.some((n) => n.key === key) || b.flows.some((n) => n.key === key) || b.processes.some(n => n.key === processKey));
+        if (block) {
+            showSystem ||= block.system;
+            navigateBusiness({
+                block: block.id,
+                flow: node.kind === 'aggregate' ? (businessJourneys(block, model).some(n => n.key === key) ? key : null) : processKey,
+                step: node.kind === 'stage' ? key : null,
+                branches: node.kind === 'stage' ? '1' : null,
+                tab: null,
+                source: null,
+                system: showSystem ? '1' : null,
+            });
+            return;
+        }
+        mode = 'all';
+        enabled = new Set(Object.keys(kinds));
+        renderFilters();
+        renderGraph();
+    }
     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);
+        mode = 'all';
+        enabled = new Set(Object.keys(kinds));
         aggregate = null;
         focus = null;
         renderFilters();
@@ -517,6 +730,7 @@ function selectNode(key, reveal = false) {
     }
     highlight();
     renderInspector();
+    address({ view: mode, node: key, object: aggregate, system: showSystem ? '1' : null });
     if (reveal && mode === 'structure') {
         searchTarget = key;
         requestAnimationFrame(centerSearchResult);
@@ -524,6 +738,9 @@ function selectNode(key, reveal = false) {
 }
 /** 搜索到长画布下方的字段时将该行移入视口。窄屏详情高度变化可能再次触发
  * ResizeObserver，适应画布后仍需保留搜索位置，否则字段会瞬间跳回屏幕外。 */
+/**
+ * 把结构视图搜索到的具体字段行移入视口，保留 resize 后的阅读目标；目标已清除则忽略旧帧。
+ */
 function centerSearchResult() {
     // 等待绘制期间切换视图会清除目标，这一帧就不再执行旧的搜索定位。
     if (!searchTarget)
@@ -538,6 +755,9 @@ function centerSearchResult() {
     camera.y = svg.clientHeight / 2 - (position.y + offset) * camera.scale;
     applyCamera();
 }
+/**
+ * 选中真实关系并确保两端可见；结构模式不能表达的关系切到完整本体，随后刷新解释面板。
+ */
 function selectEdge(edge) {
     searchTarget = null;
     selectedEdge = edge;
@@ -566,6 +786,9 @@ function selectEdge(edge) {
     renderInspector();
     element('inspector').scrollTop = 0;
 }
+/**
+ * 渲染连线原因、用途、端点及源码依据，解释复用 CLI 的共享规则，不按布局猜测执行关系。
+ */
 function renderEdgeInspector(panel, edge) {
     const explanation = explainEdge(edge, model, snapshot.presentation.labels);
     const top = html('div', 'inspector-top');
@@ -602,7 +825,13 @@ function renderEdgeInspector(panel, edge) {
         ? `${location.file}:${location.line ?? 1}${location !== node ? '（所属业务对象声明）' : ''}`
         : '来自框架包，当前项目未记录源码位置。'));
 }
+/**
+ * 重建技术详情面板，优先显示选中边，再按节点类型显示字段、规则、实现与关联入口。
+ * 业务视图有独立详情故直接返回；所有动态文字通过 DOM 文本节点呈现。
+ */
 function renderInspector() {
+    if (mode === 'business')
+        return;
     const panel = element('inspector');
     panel.replaceChildren();
     if (selectedEdge) {
@@ -666,6 +895,31 @@ function renderInspector() {
     };
     actions.append(focusButton, copy);
     panel.append(actions);
+    // 把当前节点交给编程工具时交付可追溯的文字，而不是让 AI 猜截图中的连线。
+    // 入口与 CLI 使用同一上下文构建器，复制失败明确报告，保留原来的节点详情。
+    const handoff = html('section', 'context-handoff');
+    const contextButton = html('button', 'button secondary', '⌘ 复制 AI 上下文');
+    const contextHint = html('p', '', '包含业务链路、连接原因、源码位置和验证候选。基于当前图谱，改代码后先重新抽取。');
+    contextButton.onclick = async () => {
+        contextButton.disabled = true;
+        contextButton.textContent = '正在整理上下文…';
+        try {
+            const response = await fetch(`/api/context?node=${encodeURIComponent(node.key)}&format=md`);
+            if (!response.ok)
+                throw new Error((await response.json()).error);
+            await navigator.clipboard.writeText(await response.text());
+            contextButton.textContent = '✓ 已复制，粘贴给编程工具';
+        }
+        catch (error) {
+            contextButton.textContent = '⌘ 复制 AI 上下文';
+            notify(`上下文复制失败：${error.message}`);
+        }
+        finally {
+            contextButton.disabled = false;
+        }
+    };
+    handoff.append(contextButton, contextHint);
+    panel.append(handoff);
     const section = (title, count) => {
         const div = html('section', 'detail-section'), h = html('h3', '', title);
         if (count !== undefined)
@@ -713,6 +967,9 @@ function renderInspector() {
         for (const [key, label] of Object.entries({
             event: '事件',
             command: '调用命令',
+            tx: '事务边界',
+            order: '同事件执行顺序',
+            collection: '有界集合',
             process: '审批流程',
             cron: '调度表达式',
             connector: '连接器',
@@ -720,6 +977,11 @@ function renderInspector() {
             sensitive: '敏感类型',
             kind: '字段类型',
             ref: '引用对象',
+            mappedBy: '对方外键',
+            through: '自动中间表',
+            virtual: '不占主表列',
+            readOnly: '只读关联',
+            filePolicy: '文件限制',
             optional: '可选字段',
             acquires: '获取资源',
             releases: '释放资源',
@@ -743,6 +1005,7 @@ function renderInspector() {
     }
     else
         source.append(html('p', 'source-note', node.kind === 'entry' ? '由新建命令的迁移关系推导。' : '来自框架包，当前项目未记录源码位置。'));
+    source.append(sourcePreview(node.key, false));
     const relations = model.edges.filter((e) => e.from === node.key || e.to === node.key);
     const relationSection = section('关联关系', relations.length);
     if (relations.length)
@@ -768,7 +1031,16 @@ function renderInspector() {
 }
 /** 把会直接影响阅读理解的属性值翻译为业务名称；SQL 表名、cron 和折叠的
  * 原始元数据仍保持技术原文，方便开发者核对实现。 */
+/**
+ * 把节点属性转成可读值，特别保留事务、集合上限和资源标签语义；未知值按字符串展示。
+ */
 function detailValue(key, value) {
+    if (key === 'collection') {
+        const collection = value;
+        return `最多 ${collection.maxItems} 项，按 ${collection.orderBy} 排序；串行执行，失败遵循事务边界`;
+    }
+    if (key === 'tx')
+        return value === 'same' ? '与触发命令共同提交或回滚' : '异步 outbox';
     if (typeof value === 'boolean')
         return value ? '是' : '否';
     if (key === 'event' || key === 'command')
@@ -795,6 +1067,8 @@ function detailValue(key, value) {
         boolean: '布尔值',
         id: '唯一标识',
         ref: '关联引用',
+        hasMany: '一对多（反查）',
+        manyToMany: '多对多（自动中间表）',
         list: '列表',
         json: '结构化数据',
         date: '日期',
@@ -806,23 +1080,15 @@ function detailValue(key, value) {
     };
     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;
+    return businessConstraintLabel(name, aggregateId, snapshot.presentation.labels);
 }
 const descriptions = {
+    process: '引用真实业务声明的完整流程，区分人工下一步、自动触发和等待。',
+    stage: '业务流程中的一个阶段，可展开查看规则、业务对象与实现代码。',
     aggregate: '统一管理字段、状态、业务操作和数据范围的业务对象。',
     command: '受权限和状态约束的业务写入入口。',
     event: '命令产生的领域事件，用于连接后续业务协作。',
@@ -839,6 +1105,9 @@ const descriptions = {
     capability: '从聚合声明派生的访问能力点。',
     entry: '新建命令进入初始业务状态的虚拟起点。',
 };
+/**
+ * 按当前快照展示规则错误码、原因、修复建议和位置，不自动修复源码。
+ */
 function renderFindings() {
     const list = element('findings-list');
     list.replaceChildren();
@@ -852,6 +1121,10 @@ function renderFindings() {
         list.append(item);
     }
 }
+/**
+ * 复用共享排名检索节点并同时检索板块，显示有限候选和命中依据。
+ * 点击候选更新导航并清空搜索框；未命中只提示换关键词，不判定业务不存在。
+ */
 function searchNodes() {
     const query = element('search').value.trim().toLowerCase();
     const results = element('search-results');
@@ -859,12 +1132,31 @@ function searchNodes() {
     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 matches = rankGraphNodes(model, query, snapshot.presentation.labels, {
+        descriptions: snapshot.presentation.descriptions,
+    });
+    const matchingBlocks = businessBlocks(model, snapshot.presentation.labels, showSystem).filter((block) => block.title.toLowerCase().includes(query) || block.id.toLowerCase().includes(query));
+    for (const block of matchingBlocks.slice(0, 5)) {
+        const button = html('button', 'search-result');
+        const names = html('span', 'search-names');
+        names.append(html('strong', '', block.title), html('span', '', `${businessJourneys(block, model).length} 个业务流程`));
+        button.append(html('small', '', '业务板块'), names);
+        button.onclick = () => {
+            navigateBusiness({ block: block.id, flow: null, step: null, tab: null, source: null });
+            results.hidden = true;
+            element('search').value = '';
+        };
+        results.append(button);
+    }
+    for (const hit of matches.slice(0, 30)) {
+        const n = byKey(hit.key);
         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.title = hit.matches
+            .map((match) => `${match.field}：${match.value}（命中 ${match.terms.join('、')}）`)
+            .join('\n');
         button.onclick = () => {
             selectNode(n.key, true);
             results.hidden = true;
@@ -872,13 +1164,19 @@ function searchNodes() {
         };
         results.append(button);
     }
-    if (!matches.length)
-        results.append(html('div', 'search-empty', '没有匹配的声明，试试命令名或字段名。'));
+    if (!matches.length && !matchingBlocks.length)
+        results.append(html('div', 'search-empty', '没有匹配的业务，试试业务名称、操作或代码标识。'));
 }
+/**
+ * 把当前平移和缩放应用到 SVG 并更新百分比显示，节点业务坐标保持不变。
+ */
 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;
@@ -900,6 +1198,9 @@ function fit() {
     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));
@@ -948,6 +1249,9 @@ svg.addEventListener('pointermove', (event) => {
         applyCamera();
     }
 });
+/**
+ * 结束本次指针拖动；只有正常 pointerup 且未移动才按点击选择，取消不触发选择。
+ */
 const endDrag = (event) => {
     if (!drag || drag.id !== event.pointerId)
         return;
@@ -972,7 +1276,7 @@ svg.addEventListener('wheel', (event) => {
     zoom(Math.exp(-event.deltaY * 0.0015), event.clientX - rect.left, event.clientY - rect.top);
 }, { passive: false });
 new ResizeObserver(() => {
-    if (snapshot) {
+    if (snapshot && mode !== 'business') {
         if (mode === 'structure') {
             positions = layoutTables(visibleCards, visibleEdges, svg.clientWidth < 680 ? 1 : 2);
             updatePositions();
@@ -980,12 +1284,26 @@ new ResizeObserver(() => {
         fit();
     }
 }).observe(svg);
+/**
+ * 恢复业务首页并清除 URL 中板块、流程、步骤及技术选择，保留当前抽取快照。
+ */
 function resetView() {
-    mode = 'structure';
+    mode = 'business';
     aggregate = null;
     focus = null;
     showSystem = false;
     enabled = new Set(businessKinds);
+    address({
+        view: 'business',
+        block: null,
+        flow: null,
+        step: null,
+        tab: null,
+        source: null,
+        node: null,
+        object: null,
+        system: null,
+    });
     renderFilters();
     renderGraph();
 }
@@ -1003,6 +1321,7 @@ element('system-toggle').onchange = (event) => {
     showSystem = event.target.checked;
     aggregate = null;
     focus = null;
+    address({ system: showSystem ? '1' : null });
     renderFilters();
     renderGraph();
 };
@@ -1015,11 +1334,24 @@ document.querySelectorAll('[data-mode]').forEach((button) => {
         if (mode === 'structure' && selected)
             selected =
                 tableOwner(cards, selected)?.node.key ?? cards.find((card) => !isSystem(card.node))?.node.key ?? null;
+        address({
+            view: mode,
+            node: mode === 'business' ? null : selected,
+            object: mode === 'business' ? null : aggregate,
+        });
         renderFilters();
         renderGraph();
         renderInspector();
     };
 });
+window.addEventListener('popstate', () => {
+    if (!snapshot)
+        return;
+    restoreAddress();
+    renderFilters();
+    renderGraph();
+    renderInspector();
+});
 element('refresh').onclick = () => void load(true);
 element('search').addEventListener('input', searchNodes);
 element('search').addEventListener('focus', searchNodes);