topo-engine 0.1.8 → 0.1.10

package/docs/API.md

@@ -7,6 +7,7 @@
 ## 目录
 
 - [快速开始](#快速开始)
+- [引用规则（id / psrId / assetNo 统一）](#引用规则id--psrid--assetno-统一)
 - [类型定义](#类型定义)
 - [一、查询 API](#一查询-api)
 - [二、视图控制](#二视图控制)
@@ -24,6 +25,42 @@
 
 ---
 
+## 引用规则（id / psrId / assetNo 统一）
+
+> 引擎内所有「目标 / 节点 / 设备 / 用户」入参（下称 `ref`）**统一接受三种引用**，
+> 方法与场景无关，传内部 id、psrId 还是资产编号由调用方自由决定：
+
+| 引用 | 命中对象 | 典型值 |
+| --- | --- | --- |
+| 节点内部 `id` | 普通节点 | `'1'`、`'40'` |
+| `psrId`（设备编码） | 普通节点（变压器/开关/导线点/计量箱…） | `'8ff4786d548a7073a2517297e801518ff456732f4d'` |
+| `assetNo`（资产编号，兼容 `consNo`/`consId`） | 计量箱内该户 **电表户** | `'4230010007008084768'` |
+
+**命中「箱内电表户」后的语义（按函数类型）：**
+
+- **视觉 / 定位 / 动画**（`locateNode`、`highlightNode`、`setNodeGlow`、`setNodePulse`、
+  `setText`、`setNodeColor`、`getNodePosition`、组件 `selectNode`…）→ **精确作用在该户表位**：
+  光环/高亮环/脉动/文字/染色画在该格电表上，定位聚焦表位中心；
+- **查询 / 拓扑**（`getNode`、`getNeighbors`、`getStreamNodes`、`getSubtreeNodes`、
+  `getPath`、`getEdge*`…）→ 该户**按所在计量箱参与拓扑**：
+  `getNode(assetNo)` 返回所在箱节点副本并附带 `customer / customerIndex / customerCount / targetKind:'customer'`；
+- **通用节点样式**（`setNodeStyle` 等）→ 作用于其所在计量箱节点；
+- **卡片**（`showCard(assetNo)`）→ 卡片定位在该户表位旁，内容缺省按客户档案自动生成。
+
+**辅助解析（业务判断用）：**
+
+```js
+const t = topo.resolveRef('4230010007008084768');
+// → { kind:'customer', boxId:'40', boxNode, index:0, customer:{…}, key:'40#cust0', assetNo, name }
+const c = topo.getCustomer('4230010007008084768');
+// → { node, customer, index, count, boxId } | null
+```
+
+> 说明：`findNodes` / `getAllNodes` 等**无目标入参**的聚合查询保持原语义（返回模型节点，不含电表户，
+> 电表户从箱节点的 `_customers` 中读取）。连线/拓扑线端点本就支持 id/psrId/assetNo。
+
+---
+
 ## 快速开始
 
 ```vue
@@ -205,18 +242,19 @@ interface ConnectionOptions {
 
 ## 一、查询 API
 
-### `getNode(nodeId)`
+### `getNode(ref)`
 
-获取单个节点完整数据。
+获取单个目标（节点 / 箱内电表户）完整数据。
 
 ```ts
-getNode(nodeId: string): NodeData | null
+getNode(ref: string): NodeData | null
 ```
 
 **参数：**
-- `nodeId` — 节点 ID
+- `ref` — 节点 id / psrId / 资产编号 assetNo（见[引用规则](#引用规则id--psrid--assetno-统一)）
 
-**返回：** 节点数据对象，未找到返回 `null`
+**返回：** 命中普通节点返回模型节点；命中电表户返回**其所在计量箱节点副本**，
+并附带 `customer`（客户档案）、`customerIndex`、`customerCount`、`targetKind:'customer'`；未找到返回 `null`
 
 **示例：**
 ```js
@@ -391,12 +429,12 @@ getMainEdge(): EdgeData[]
 
 ---
 
-### `getNodePosition(nodeId)`
+### `getNodePosition(ref)`
 
-获取节点在画布中的坐标。
+获取节点 / 户表位中心坐标（assetNo → 该户表位中心）。
 
 ```ts
-getNodePosition(nodeId: string): { x: number; y: number } | null
+getNodePosition(ref: string): { x: number; y: number } | null
 ```
 
 ---
@@ -491,16 +529,16 @@ zoomOut(step?: number): void
 
 ---
 
-### `locateNode(nodeId, zoom?)`
+### `locateNode(ref, zoom?)`
 
-定位节点到视口中央，可选缩放。
+定位目标到视口中央（节点中心 / 户表位中心），可选缩放。
 
 ```ts
-locateNode(nodeId: string, zoom?: number): void
+locateNode(ref: string, zoom?: number): void
 ```
 
 **参数：**
-- `nodeId` — 要定位的节点 ID
+- `ref` — 节点 id / psrId / 资产编号 assetNo
 - `zoom` — 可选的目标缩放比例
 
 **示例：**
@@ -526,12 +564,12 @@ getViewport(): { zoom: number; center: { x: number; y: number } }
 
 ## 三、节点样式
 
-### `setNodeStyle(nodeId, style)`
+### `setNodeStyle(ref, style)`
 
-设置单个节点的视觉样式。
+设置单个目标的视觉样式（assetNo → 作用于所在计量箱节点）。
 
 ```ts
-setNodeStyle(nodeId: string, style: NodeStyle): void
+setNodeStyle(ref: string, style: NodeStyle): void
 ```
 
 **示例：**
@@ -730,12 +768,12 @@ resetEdgeStyle(srcId: string, tgtId: string): void
 
 ## 五、高亮与标注
 
-### `highlightNode(nodeId, options?)`
+### `highlightNode(ref, options?)`
 
-高亮节点（选中效果 + 可选文字标注）。
+高亮目标（节点 → 金框 + 可选标注；箱内电表户 → 该户表位高亮环 + 可选标注）。
 
 ```ts
-highlightNode(nodeId: string, options?: HighlightOptions): void
+highlightNode(ref: string, options?: HighlightOptions): void
 ```
 
 **示例：**
@@ -823,12 +861,12 @@ topo.dimOthers(keep, 0.15);
 
 ## 六、动画
 
-### `setNodePulse(nodeId, options?)`
+### `setNodePulse(ref, options?)`
 
-节点脉动/光晕动画。
+目标脉动动画（节点 → 图元透明度呼吸；箱内电表户 → 该户电表格淡入淡出）。
 
 ```ts
-setNodePulse(nodeId: string, options?: PulseOptions): void
+setNodePulse(ref: string, options?: { duration?: number; min?: number; max?: number }): void
 ```
 
 **示例：**
@@ -838,17 +876,95 @@ topo.setNodePulse('123', { color: '#FF0000', duration: 1500 });
 
 ---
 
-### `setNodeGlow(nodeId, options?)`
+### `setNodeGlow(ref, options?)`
+
+**节点光晕动画** —— 节点周围的霓虹式发光（多层光环 + 辉光 + 面光底衬），
+用于告警 / 定位 / 状态强调等场景；开启 `blink` 后图元本体还会「整体闪烁」。
+
+```ts
+setNodeGlow(ref: string, options?: {
+  color?: string;      // 光晕颜色，默认 '#00C8FF'（青）
+  spread?: number;     // 光环外扩半径 (px)，默认按图元大小自适应（短边 ×0.7，16~46px）
+  radius?: number;     // spread 的别名（兼容早期文档）
+  duration?: number;   // 一个周期时长 (ms)，默认 1600
+  opacity?: number;    // 光环最大透明度 (0-1)，默认 0.95
+  width?: number;      // 主环初始线宽 (px)，默认 5.6（户表位 3.6），随相位收细
+  intensity?: number;  // 强度倍率，默认 1（线宽 / 辉光 / 底光同时放大）
+  level?: number;      // intensity 的别名
+  strength?: number;   // intensity 的别名
+  blink?: boolean | number;  // 图元「整体闪烁」：默认 false（只画光环）
+  flash?: boolean | number;  // blink 的别名
+}): boolean
+```
+
+**渲染栈（由下到上，为什么现在远看也醒目）：**
+1. **blur 柔光底衬**：用 canvas `filter: blur()` 画一块弥散的同色面光，范围随 `spread`；
+2. **贴合图元轮廓的实心光块**：让节点“整块亮起来”，而不是只靠细线；
+3. 图元本体；
+4. **外扩散环 ×2**：扩散尾迹（最淡）+ 带辉光次环；
+5. **霓虹主环**：粗线 + canvas `shadowBlur` 辉光 —— 真正的“发光”而不是一根线；
+6. **亮芯环**：偏白的细高光，制造刺眼的发光中心。
+
+**参数说明：**
+- `intensity`：整体强度倍率，默认 `1`。想要更夸张给 `1.5`~`2.5`（辉光半径、线宽、面光同步放大），
+  觉得糊/太抢眼给 `0.5`~`0.7`；
+- `spread`：扩散范围。不传时按图元短边自适应（小图元至少 16px，大图元最多 46px）；
+- `blink`：`false`（默认）只有光环；`true` = 0.85；`0.3`~`1` 为自定义强度，
+  数值 = 图元最暗时被压掉的透明度幅度（`1` → 图元完全隐去）。开启后每个周期做一次
+  「图元变暗 ↔ 恢复」的明暗交替，图元最暗的瞬间正是底衬光块最亮之时（与光环相位互补，
+  任何时刻都有强视觉元素，不会出现“整段动画都看不清”的空档）；
+- `duration`：既控制光环扩散快慢，也控制闪烁频率（想要更“急”的告警感给 700~900）。
+
+**说明：**
+- `ref` 支持 **节点内部 id / psrId（设备编码）** → 图元光环；
+  **客户 assetNo（资产编号，兼容 consNo/consId）→ 该户表位光环**（多户箱只亮那一格，单户箱即整箱那只表）；
+- 多个目标可同时发光；`removeAllAnimations()` 会一并停止光晕与脉动；
+- 与「染色 / 高亮」互不冲突：光环画在图元之上、选中金框之下，随节点/表位对齐；
+  `blink` 只压图元本体透明度，光环、高亮框、标注文字始终清晰。
+
+**示例：**
+```js
+// 默认青色光晕（已经带辉光 + 底衬面光）
+topo.setNodeGlow('8ff4786d548a7073a2517297e801518ff456732f4d');
+
+// 红色告警：更大扩散 + 更快周期 + 整体闪烁 + 加强
+topo.setNodeGlow('8ff4…', { color: '#FF3B30', duration: 900, blink: true, intensity: 1.6 });
+
+// 最夸张一档（远看/投影上都醒目）
+topo.setNodeGlow('2', { color: '#FF2D2D', intensity: 2.4, spread: 34, width: 9, blink: 0.9, duration: 700 });
+
+// 收敛一点（只要一个柔和光环）
+topo.setNodeGlow('2', { intensity: 0.6, blink: false });
+
+// 温和闪烁（最暗只降到 30%）/ 强烈闪烁（图元近乎全灭）
+topo.setNodeGlow('2', { blink: 0.3 });
+topo.setNodeGlow('2', { blink: 1 });
+
+// 停止：removeNodeGlow(ref) / 停止全部 removeAllNodeGlows()
+topo.removeNodeGlow('8ff4…');
+```
+
+---
+
+### `removeNodeGlow(ref)`
 
-节点发光效果。
+停止指定节点的光晕动画。
 
 ```ts
-setNodeGlow(nodeId: string, options?: { color?: string; radius?: number }): void
+removeNodeGlow(ref: string): boolean
 ```
 
 ---
 
-### `setEdgeFlow(srcId, tgtId, options?)`
+### `removeAllNodeGlows()`
+
+停止全部节点的光晕动画。
+
+```ts
+removeAllNodeGlows(): void
+```
+
+---### `setEdgeFlow(srcId, tgtId, options?)`
 
 边流动动画（视觉流动效果）。
 
@@ -895,12 +1011,12 @@ removeAllAnimations(): void
 
 ## 七、文字标注
 
-### `setText(nodeId, text, options?)`
+### `setText(ref, text, options?)`
 
-在节点旁设置附加文字。
+在目标旁设置附加文字（节点 → 节点旁标注；箱内电表户 → 表位上方小标注）。
 
 ```ts
-setText(nodeId: string, text: string, options?: {
+setText(ref: string, text: string, options?: {
   fontSize?: number;   // 默认 12
   color?: string;      // 默认 '#FFFFFF'
   position?: 'top' | 'bottom' | 'left' | 'right';  // 默认 'top'
@@ -968,12 +1084,13 @@ changeUserName(mode: 'full' | 'short' | 'hidden'): void
 
 ## 八、卡片盒
 
-### `showCard(nodeId, content)`
+### `showCard(ref, content?)`
 
-在节点旁弹出信息卡片。
+在节点 / 箱内电表户旁弹出信息卡片（assetNo → 卡片定位在该户表位旁）。
+`content` 可省略：不传时自动按「设备信息 / 客户档案」生成 `title` 与 `fields`。
 
 ```ts
-showCard(nodeId: string, content: CardContent): void
+showCard(ref: string, content?: CardContent): void
 ```
 
 **示例：**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "topo-engine",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "private": false,
   "type": "module",
   "description": "配电台区单线图拓扑成图引擎 (Vue3 + G6 v5 + Node/Vite)",