topo-engine 0.1.7 → 0.1.9

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
 ```
 
 **示例：**
@@ -575,6 +613,118 @@ resetAllNodeStyles(): void
 
 ---
 
+### 节点 / 箱内电表户染色（psrId / 资产编号）
+
+> 给图元“换颜色”。引用规则与 `addConnection` 完全一致：
+> - **普通节点** —— 节点内部 id 或 **`psrId`（设备编码）**：变压器 / 开关 / 熔丝 /
+>   导线连接点 / 母线 / 用户接入点 / 计量箱本体均可；
+> - **箱内电表户** —— 客户档案里的 **`assetNo`（资产编号）**（兼容 `consNo`/`consId`）：
+>   命中计量箱内该户的**电表图标 + 户名**（单户箱即整箱那一只表；多户箱只染该格）。
+>
+> 渲染效果：
+> - 普通节点为**整图单色换装**——主体 / 引线 / 描边全部换成指定色，
+>   白字与浅色细节（开关 Kxx 标签、内高光、装饰条）保留以保证可读；
+> - 箱内电表户染该户表体 / 显示窗 / 脉冲点与户名颜色；悬停（青）与选中（金）优先级更高，
+>   取消悬停 / 选中后自动回到所染颜色。
+>
+> 染色记录保存在 API 内部，**主题切换 / 数据重渲染后自动保留并重放**（同一次会话内
+> 无需重新调用；`resetNodeColor` / `resetAllNodeColors` 可清除）。
+
+#### `setNodeColor(ref, color)`
+
+按 **节点 psrId / id** 或 **用户 assetNo（资产编号）** 染色。
+
+```ts
+setNodeColor(ref: string, color: string | null): boolean
+// color 传 null / '' / undefined 等价于清除该处染色（回到主题默认配色）
+```
+
+**示例：**
+```js
+// 1) 普通节点：按 psrId（设备编码）把变压器染红
+topo.setNodeColor('8ff4786d548a7073a2517297e801518ff456732f4d', '#FF0000');
+
+// 2) 电表户：按资产编号（assetNo）把某户电表染橙
+topo.setNodeColor('4230010007008084768', '#FF6600');
+
+// 3) 也支持节点内部 id
+topo.setNodeColor('5', '#00FF00');
+
+// 4) 清除染色（回到主题默认色）
+topo.setNodeColor('4230010007008084768', null);
+```
+
+---
+
+#### `batchSetNodeColor(entries, color?)`
+
+批量染色（如后端返回「psrId → 状态色」「assetNo → 状态色」列表时一次性下发）。
+三种入参形式：
+
+```ts
+batchSetNodeColor(entries: any, color?: string): {
+  total: number;
+  ok: number;
+  failed: Array<{ ref: string, reason: string }>;
+}
+```
+
+**示例：**
+```js
+// 形式 1：[ref, color] 数组
+topo.batchSetNodeColor([
+  ['8ff4786d548a7073a2517297e801518ff456732f4d', '#FF0000'],
+  ['4230010007008084768', '#FF6600'],
+]);
+
+// 形式 2：对象数组（color 缺省时用第 2 参）
+topo.batchSetNodeColor([
+  { psrId: '8ff4…', color: '#FF0000' },
+  { assetNo: '4230…' },
+], '#FF6600');
+
+// 形式 3：ref → color 对象
+topo.batchSetNodeColor({
+  '8ff4786d548a7073a2517297e801518ff456732f4d': '#FF0000',
+  '4230010007008084768': '#FF6600',
+});
+```
+
+---
+
+#### `resetNodeColor(ref)`
+
+清除指定节点 / 电表户的染色。
+
+```ts
+resetNodeColor(ref: string): boolean
+```
+
+---
+
+#### `resetAllNodeColors()`
+
+清除全部染色（所有节点与电表户回到主题默认配色）。
+
+```ts
+resetAllNodeColors(): void
+```
+
+---
+
+#### `getNodeColor(ref)`
+
+查询某处当前生效的染色（未命中返回 `null`）。
+
+```ts
+getNodeColor(ref: string):
+  | { kind: 'node', id: string, color: string | null }
+  | { kind: 'customer', id: string, boxId: string, index: number, color: string | null }
+  | null
+```
+
+---
+
 ## 四、边样式
 
 ### `setEdgeStyle(srcId, tgtId, style)`
@@ -618,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
 ```
 
 **示例：**
@@ -711,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
 ```
 
 **示例：**
@@ -726,17 +876,60 @@ topo.setNodePulse('123', { color: '#FF0000', duration: 1500 });
 
 ---
 
-### `setNodeGlow(nodeId, options?)`
+### `setNodeGlow(ref, options?)`
+
+**节点光晕动画** —— 节点周围“扩散 + 渐隐”的发光环（两层光环、呼吸式循环），
+用于告警 / 定位 / 状态强调等场景。
+
+```ts
+setNodeGlow(ref: string, options?: {
+  color?: string;     // 光晕颜色，默认 '#00C8FF'（青）
+  spread?: number;    // 光环外扩半径 (px)，默认 14
+  radius?: number;    // spread 的别名（兼容早期文档）
+  duration?: number;  // 一个周期时长 (ms)，默认 1600
+  opacity?: number;   // 光环最大透明度 (0-1)，默认 0.9
+}): boolean
+```
+
+**说明：**
+- `ref` 支持 **节点内部 id / psrId（设备编码）** → 图元光环；
+  **客户 assetNo（资产编号，兼容 consNo/consId）→ 该户表位光环**（多户箱只亮那一格，单户箱即整箱那只表）；
+- 多个目标可同时发光；`removeAllAnimations()` 会一并停止光晕与脉动；
+- 与「染色 / 高亮」互不冲突：光环画在图元之上、选中金框之下，随节点/表位对齐。
+
+**示例：**
+```js
+// 默认青色光晕
+topo.setNodeGlow('8ff4786d548a7073a2517297e801518ff456732f4d');
+
+// 红色告警光晕（更亮、扩散更大、周期更快）
+topo.setNodeGlow('8ff4…', { color: '#FF0000', spread: 20, duration: 900, opacity: 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?)`
 
 边流动动画（视觉流动效果）。
 
@@ -783,12 +976,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'
@@ -856,12 +1049,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.7",
+  "version": "0.1.9",
   "private": false,
   "type": "module",
   "description": "配电台区单线图拓扑成图引擎 (Vue3 + G6 v5 + Node/Vite)",