@logicflow/core 2.1.10 → 2.1.11

package/es/model/edge/PolylineEdgeModel.js

@@ -449,7 +449,9 @@ var PolylineEdgeModel = /** @class */ (function (_super) {
             y: this.endPoint.y,
         }, this.sourceNode, this.targetNode, this.offset || 0);
         this.pointsList = this.orthogonalizePath(pointsList);
-        this.points = pointsList.map(function (point) { return "".concat(point.x, ",").concat(point.y); }).join(' ');
+        this.points = this.pointsList
+            .map(function (point) { return "".concat(point.x, ",").concat(point.y); })
+            .join(' ');
     };
     PolylineEdgeModel.prototype.updateStartPoint = function (anchor) {
         this.startPoint = Object.assign({}, anchor);

package/es/util/edge.d.ts

@@ -14,6 +14,15 @@ export declare const filterRepeatPoints: (points: Point[]) => Point[];
 export declare const getSimplePolyline: (sPoint: Point, tPoint: Point) => Point[];
 export declare const getExpandedBBox: (bbox: BoxBounds, offset: number) => BoxBounds;
 export declare const pointDirection: (point: Point, bbox: BoxBounds) => Direction;
+/**
+ * 计算扩展包围盒上的相邻点（起点或终点的下一个/上一个拐点）
+ * - 使用原始节点 bbox 来判定点相对中心的方向，避免 offset 扩展后宽高改变导致方向误判
+ * - 若 start 相对中心为水平方向，则返回扩展盒在 x 上的边界，y 保持不变
+ * - 若为垂直方向，则返回扩展盒在 y 上的边界，x 保持不变
+ * @param expendBBox 扩展后的包围盒（包含 offset）
+ * @param bbox 原始节点包围盒（用于正确的方向判定）
+ * @param point 起点或终点坐标
+ */
 export declare const getExpandedBBoxPoint: (expendBBox: BoxBounds, bbox: BoxBounds, point: Point) => Point;
 export declare const mergeBBox: (b1: BoxBounds, b2: BoxBounds) => BoxBounds;
 export declare const getBBoxOfPoints: (points?: Point[], offset?: number) => BoxBounds;
@@ -32,10 +41,36 @@ export declare const rebuildPath: (pathPoints: Point[], pointById: PolyPointMap,
 export declare const removeClosePointFromOpenList: (arr: Point[], item: Point) => void;
 export declare const isSegmentsIntersected: (p0: Point, p1: Point, p2: Point, p3: Point) => boolean;
 export declare const isSegmentCrossingBBox: (p1: Point, p2: Point, bbox: BoxBounds) => boolean;
+/**
+ * 基于轴对齐规则获取某点的相邻可连通点（不穿越节点）
+ * - 仅考虑 x 或 y 相同的候选点，保证严格水平/垂直
+ * - 使用 isSegmentCrossingBBox 校验线段不穿越源/目标节点
+ */
 export declare const getNextNeighborPoints: (points: Point[], point: Point, bbox1: BoxBounds, bbox2: BoxBounds) => Point[];
+/**
+ * 使用 A* + 曼哈顿启发式在候选点图上查找正交路径
+ * - 开放集/关闭集管理遍历
+ * - gScore 为累计实际代价，fScore = gScore + 启发式
+ * - 邻居仅为与当前点 x 或 y 相同且不穿越节点的点
+ * 参考：https://zh.wikipedia.org/wiki/A*%E6%90%9C%E5%B0%8B%E6%BC%94%E7%AE%97%E6%B3%95
+ */
 export declare const pathFinder: (points: Point[], start: Point, goal: Point, sBBox: BoxBounds, tBBox: BoxBounds, os: Point, ot: Point) => Point[];
 export declare const getBoxByOriginNode: (node: BaseNodeModel) => BoxBounds;
+/**
+ * 去除共线冗余中间点，保持每条直线段仅保留两端点
+ * - 若三点在同一水平线或同一垂直线，移除中间点
+ */
 export declare const pointFilter: (points: Point[]) => Point[];
+/**
+ * 计算折线点（正交候选点 + A* 路径）
+ * 步骤：
+ * 1) 取源/目标节点的扩展包围盒与相邻点 sPoint/tPoint
+ * 2) 若两个扩展盒重合，使用简单路径 getSimplePoints
+ * 3) 构造 lineBBox/sMixBBox/tMixBBox，并收集其角点与中心交点
+ * 4) 过滤掉落在两个扩展盒内部的点，形成 connectPoints
+ * 5) 以 sPoint/tPoint 为起止，用 A* 查找路径
+ * 6) 拼入原始 start/end，并用 pointFilter 去除冗余共线点
+ */
 export declare const getPolylinePoints: (start: Point, end: Point, sNode: BaseNodeModel, tNode: BaseNodeModel, offset: number) => Point[];
 /**
  * 获取折线中最长的一个线
@@ -47,6 +82,10 @@ export declare const isSegmentsCrossNode: (start: Point, end: Point, node: BaseN
 export declare const getCrossPointInRect: (start: Point, end: Point, node: BaseNodeModel) => Point | false | undefined;
 export declare const segmentDirection: (start: Point, end: Point) => Direction | undefined;
 export declare const points2PointsList: (points: string) => Point[];
+/**
+ * 当扩展 bbox 重合时的简化拐点计算
+ * - 根据起止段的方向（水平/垂直）插入 1~2 个中间点，避免折线重合与穿越
+ */
 export declare const getSimplePoints: (start: Point, end: Point, sPoint: Point, tPoint: Point) => Point[];
 export declare const getBytesLength: (word: string) => number;
 export declare const getTextWidth: (text: string, font: string) => number;

package/es/util/edge.js

@@ -113,6 +113,15 @@ export var pointDirection = function (point, bbox) {
         : SegmentDirection.VERTICAL;
 };
 /* 获取扩展图形上的点，即起始终点相邻的点，上一个或者下一个节点 */
+/**
+ * 计算扩展包围盒上的相邻点（起点或终点的下一个/上一个拐点）
+ * - 使用原始节点 bbox 来判定点相对中心的方向，避免 offset 扩展后宽高改变导致方向误判
+ * - 若 start 相对中心为水平方向，则返回扩展盒在 x 上的边界，y 保持不变
+ * - 若为垂直方向，则返回扩展盒在 y 上的边界，x 保持不变
+ * @param expendBBox 扩展后的包围盒（包含 offset）
+ * @param bbox 原始节点包围盒（用于正确的方向判定）
+ * @param point 起点或终点坐标
+ */
 export var getExpandedBBoxPoint = function (expendBBox, bbox, point) {
     // https://github.com/didi/LogicFlow/issues/817
     // 没有修复前传入的参数bbox实际是expendBBox
@@ -313,7 +322,11 @@ export var isSegmentCrossingBBox = function (p1, p2, bbox) {
         isSegmentsIntersected(p1, p2, pb, pc) ||
         isSegmentsIntersected(p1, p2, pc, pd));
 };
-/* 获取下一个相邻的点 */
+/**
+ * 基于轴对齐规则获取某点的相邻可连通点（不穿越节点）
+ * - 仅考虑 x 或 y 相同的候选点，保证严格水平/垂直
+ * - 使用 isSegmentCrossingBBox 校验线段不穿越源/目标节点
+ */
 export var getNextNeighborPoints = function (points, point, bbox1, bbox2) {
     var neighbors = [];
     points.forEach(function (p) {
@@ -328,9 +341,12 @@ export var getNextNeighborPoints = function (points, point, bbox1, bbox2) {
     });
     return filterRepeatPoints(neighbors);
 };
-/* 路径查找,AStar查找+曼哈顿距离
- * 算法wiki:https://zh.wikipedia.org/wiki/A*%E6%90%9C%E5%B0%8B%E6%BC%94%E7%AE%97%E6%B3%95
- * 方法无法复用，且调用了很多polyline相关的方法，暂不抽离到src/algorithm中
+/**
+ * 使用 A* + 曼哈顿启发式在候选点图上查找正交路径
+ * - 开放集/关闭集管理遍历
+ * - gScore 为累计实际代价，fScore = gScore + 启发式
+ * - 邻居仅为与当前点 x 或 y 相同且不穿越节点的点
+ * 参考：https://zh.wikipedia.org/wiki/A*%E6%90%9C%E5%B0%8B%E6%BC%94%E7%AE%97%E6%B3%95
  */
 export var pathFinder = function (points, start, goal, sBBox, tBBox, os, ot) {
     // 定义已经遍历过的点
@@ -371,6 +387,7 @@ export var pathFinder = function (points, start, goal, sBBox, tBBox, os, ot) {
         removeClosePointFromOpenList(openSet, current);
         closedSet.push(current);
         getNextNeighborPoints(points, current, sBBox, tBBox).forEach(function (neighbor) {
+            var _a;
             if (closedSet.indexOf(neighbor) !== -1) {
                 return;
             }
@@ -378,7 +395,8 @@ export var pathFinder = function (points, start, goal, sBBox, tBBox, os, ot) {
                 openSet.push(neighbor);
             }
             if ((current === null || current === void 0 ? void 0 : current.id) && (neighbor === null || neighbor === void 0 ? void 0 : neighbor.id)) {
-                var tentativeGScore = fScore[current.id] + estimateDistance(current, neighbor);
+                // 修复：累计代价应基于 gScore[current] 而非 fScore[current]
+                var tentativeGScore = ((_a = gScore[current.id]) !== null && _a !== void 0 ? _a : 0) + estimateDistance(current, neighbor);
                 if (gScore[neighbor.id] && tentativeGScore >= gScore[neighbor.id]) {
                     return;
                 }
@@ -400,7 +418,10 @@ export var pathFinder = function (points, start, goal, sBBox, tBBox, os, ot) {
 export var getBoxByOriginNode = function (node) {
     return getNodeBBox(node);
 };
-/* 保证一条直线上只有2个节点： 删除x/y相同的中间节点 */
+/**
+ * 去除共线冗余中间点，保持每条直线段仅保留两端点
+ * - 若三点在同一水平线或同一垂直线，移除中间点
+ */
 export var pointFilter = function (points) {
     var i = 1;
     while (i < points.length - 1) {
@@ -417,7 +438,16 @@ export var pointFilter = function (points) {
     }
     return points;
 };
-/* 计算折线点 */
+/**
+ * 计算折线点（正交候选点 + A* 路径）
+ * 步骤：
+ * 1) 取源/目标节点的扩展包围盒与相邻点 sPoint/tPoint
+ * 2) 若两个扩展盒重合，使用简单路径 getSimplePoints
+ * 3) 构造 lineBBox/sMixBBox/tMixBBox，并收集其角点与中心交点
+ * 4) 过滤掉落在两个扩展盒内部的点，形成 connectPoints
+ * 5) 以 sPoint/tPoint 为起止，用 A* 查找路径
+ * 6) 拼入原始 start/end，并用 pointFilter 去除冗余共线点
+ */
 export var getPolylinePoints = function (start, end, sNode, tNode, offset) {
     var sBBox = getBoxByOriginNode(sNode);
     var tBBox = getBoxByOriginNode(tNode);
@@ -554,6 +584,10 @@ export var points2PointsList = function (points) {
         });
     return pointsList;
 };
+/**
+ * 当扩展 bbox 重合时的简化拐点计算
+ * - 根据起止段的方向（水平/垂直）插入 1~2 个中间点，避免折线重合与穿越
+ */
 export var getSimplePoints = function (start, end, sPoint, tPoint) {
     var points = [];
     // start,sPoint的方向，水平或者垂直，即路径第一条线段的方向

package/lib/model/edge/PolylineEdgeModel.js

@@ -452,7 +452,9 @@ var PolylineEdgeModel = /** @class */ (function (_super) {
             y: this.endPoint.y,
         }, this.sourceNode, this.targetNode, this.offset || 0);
         this.pointsList = this.orthogonalizePath(pointsList);
-        this.points = pointsList.map(function (point) { return "".concat(point.x, ",").concat(point.y); }).join(' ');
+        this.points = this.pointsList
+            .map(function (point) { return "".concat(point.x, ",").concat(point.y); })
+            .join(' ');
     };
     PolylineEdgeModel.prototype.updateStartPoint = function (anchor) {
         this.startPoint = Object.assign({}, anchor);

package/lib/util/edge.d.ts

@@ -14,6 +14,15 @@ export declare const filterRepeatPoints: (points: Point[]) => Point[];
 export declare const getSimplePolyline: (sPoint: Point, tPoint: Point) => Point[];
 export declare const getExpandedBBox: (bbox: BoxBounds, offset: number) => BoxBounds;
 export declare const pointDirection: (point: Point, bbox: BoxBounds) => Direction;
+/**
+ * 计算扩展包围盒上的相邻点（起点或终点的下一个/上一个拐点）
+ * - 使用原始节点 bbox 来判定点相对中心的方向，避免 offset 扩展后宽高改变导致方向误判
+ * - 若 start 相对中心为水平方向，则返回扩展盒在 x 上的边界，y 保持不变
+ * - 若为垂直方向，则返回扩展盒在 y 上的边界，x 保持不变
+ * @param expendBBox 扩展后的包围盒（包含 offset）
+ * @param bbox 原始节点包围盒（用于正确的方向判定）
+ * @param point 起点或终点坐标
+ */
 export declare const getExpandedBBoxPoint: (expendBBox: BoxBounds, bbox: BoxBounds, point: Point) => Point;
 export declare const mergeBBox: (b1: BoxBounds, b2: BoxBounds) => BoxBounds;
 export declare const getBBoxOfPoints: (points?: Point[], offset?: number) => BoxBounds;
@@ -32,10 +41,36 @@ export declare const rebuildPath: (pathPoints: Point[], pointById: PolyPointMap,
 export declare const removeClosePointFromOpenList: (arr: Point[], item: Point) => void;
 export declare const isSegmentsIntersected: (p0: Point, p1: Point, p2: Point, p3: Point) => boolean;
 export declare const isSegmentCrossingBBox: (p1: Point, p2: Point, bbox: BoxBounds) => boolean;
+/**
+ * 基于轴对齐规则获取某点的相邻可连通点（不穿越节点）
+ * - 仅考虑 x 或 y 相同的候选点，保证严格水平/垂直
+ * - 使用 isSegmentCrossingBBox 校验线段不穿越源/目标节点
+ */
 export declare const getNextNeighborPoints: (points: Point[], point: Point, bbox1: BoxBounds, bbox2: BoxBounds) => Point[];
+/**
+ * 使用 A* + 曼哈顿启发式在候选点图上查找正交路径
+ * - 开放集/关闭集管理遍历
+ * - gScore 为累计实际代价，fScore = gScore + 启发式
+ * - 邻居仅为与当前点 x 或 y 相同且不穿越节点的点
+ * 参考：https://zh.wikipedia.org/wiki/A*%E6%90%9C%E5%B0%8B%E6%BC%94%E7%AE%97%E6%B3%95
+ */
 export declare const pathFinder: (points: Point[], start: Point, goal: Point, sBBox: BoxBounds, tBBox: BoxBounds, os: Point, ot: Point) => Point[];
 export declare const getBoxByOriginNode: (node: BaseNodeModel) => BoxBounds;
+/**
+ * 去除共线冗余中间点，保持每条直线段仅保留两端点
+ * - 若三点在同一水平线或同一垂直线，移除中间点
+ */
 export declare const pointFilter: (points: Point[]) => Point[];
+/**
+ * 计算折线点（正交候选点 + A* 路径）
+ * 步骤：
+ * 1) 取源/目标节点的扩展包围盒与相邻点 sPoint/tPoint
+ * 2) 若两个扩展盒重合，使用简单路径 getSimplePoints
+ * 3) 构造 lineBBox/sMixBBox/tMixBBox，并收集其角点与中心交点
+ * 4) 过滤掉落在两个扩展盒内部的点，形成 connectPoints
+ * 5) 以 sPoint/tPoint 为起止，用 A* 查找路径
+ * 6) 拼入原始 start/end，并用 pointFilter 去除冗余共线点
+ */
 export declare const getPolylinePoints: (start: Point, end: Point, sNode: BaseNodeModel, tNode: BaseNodeModel, offset: number) => Point[];
 /**
  * 获取折线中最长的一个线
@@ -47,6 +82,10 @@ export declare const isSegmentsCrossNode: (start: Point, end: Point, node: BaseN
 export declare const getCrossPointInRect: (start: Point, end: Point, node: BaseNodeModel) => Point | false | undefined;
 export declare const segmentDirection: (start: Point, end: Point) => Direction | undefined;
 export declare const points2PointsList: (points: string) => Point[];
+/**
+ * 当扩展 bbox 重合时的简化拐点计算
+ * - 根据起止段的方向（水平/垂直）插入 1~2 个中间点，避免折线重合与穿越
+ */
 export declare const getSimplePoints: (start: Point, end: Point, sPoint: Point, tPoint: Point) => Point[];
 export declare const getBytesLength: (word: string) => number;
 export declare const getTextWidth: (text: string, font: string) => number;

package/lib/util/edge.js

@@ -122,6 +122,15 @@ var pointDirection = function (point, bbox) {
 };
 exports.pointDirection = pointDirection;
 /* 获取扩展图形上的点，即起始终点相邻的点，上一个或者下一个节点 */
+/**
+ * 计算扩展包围盒上的相邻点（起点或终点的下一个/上一个拐点）
+ * - 使用原始节点 bbox 来判定点相对中心的方向，避免 offset 扩展后宽高改变导致方向误判
+ * - 若 start 相对中心为水平方向，则返回扩展盒在 x 上的边界，y 保持不变
+ * - 若为垂直方向，则返回扩展盒在 y 上的边界，x 保持不变
+ * @param expendBBox 扩展后的包围盒（包含 offset）
+ * @param bbox 原始节点包围盒（用于正确的方向判定）
+ * @param point 起点或终点坐标
+ */
 var getExpandedBBoxPoint = function (expendBBox, bbox, point) {
     // https://github.com/didi/LogicFlow/issues/817
     // 没有修复前传入的参数bbox实际是expendBBox
@@ -337,7 +346,11 @@ var isSegmentCrossingBBox = function (p1, p2, bbox) {
         (0, exports.isSegmentsIntersected)(p1, p2, pc, pd));
 };
 exports.isSegmentCrossingBBox = isSegmentCrossingBBox;
-/* 获取下一个相邻的点 */
+/**
+ * 基于轴对齐规则获取某点的相邻可连通点（不穿越节点）
+ * - 仅考虑 x 或 y 相同的候选点，保证严格水平/垂直
+ * - 使用 isSegmentCrossingBBox 校验线段不穿越源/目标节点
+ */
 var getNextNeighborPoints = function (points, point, bbox1, bbox2) {
     var neighbors = [];
     points.forEach(function (p) {
@@ -353,9 +366,12 @@ var getNextNeighborPoints = function (points, point, bbox1, bbox2) {
     return (0, exports.filterRepeatPoints)(neighbors);
 };
 exports.getNextNeighborPoints = getNextNeighborPoints;
-/* 路径查找,AStar查找+曼哈顿距离
- * 算法wiki:https://zh.wikipedia.org/wiki/A*%E6%90%9C%E5%B0%8B%E6%BC%94%E7%AE%97%E6%B3%95
- * 方法无法复用，且调用了很多polyline相关的方法，暂不抽离到src/algorithm中
+/**
+ * 使用 A* + 曼哈顿启发式在候选点图上查找正交路径
+ * - 开放集/关闭集管理遍历
+ * - gScore 为累计实际代价，fScore = gScore + 启发式
+ * - 邻居仅为与当前点 x 或 y 相同且不穿越节点的点
+ * 参考：https://zh.wikipedia.org/wiki/A*%E6%90%9C%E5%B0%8B%E6%BC%94%E7%AE%97%E6%B3%95
  */
 var pathFinder = function (points, start, goal, sBBox, tBBox, os, ot) {
     // 定义已经遍历过的点
@@ -396,6 +412,7 @@ var pathFinder = function (points, start, goal, sBBox, tBBox, os, ot) {
         (0, exports.removeClosePointFromOpenList)(openSet, current);
         closedSet.push(current);
         (0, exports.getNextNeighborPoints)(points, current, sBBox, tBBox).forEach(function (neighbor) {
+            var _a;
             if (closedSet.indexOf(neighbor) !== -1) {
                 return;
             }
@@ -403,7 +420,8 @@ var pathFinder = function (points, start, goal, sBBox, tBBox, os, ot) {
                 openSet.push(neighbor);
             }
             if ((current === null || current === void 0 ? void 0 : current.id) && (neighbor === null || neighbor === void 0 ? void 0 : neighbor.id)) {
-                var tentativeGScore = fScore[current.id] + (0, exports.estimateDistance)(current, neighbor);
+                // 修复：累计代价应基于 gScore[current] 而非 fScore[current]
+                var tentativeGScore = ((_a = gScore[current.id]) !== null && _a !== void 0 ? _a : 0) + (0, exports.estimateDistance)(current, neighbor);
                 if (gScore[neighbor.id] && tentativeGScore >= gScore[neighbor.id]) {
                     return;
                 }
@@ -427,7 +445,10 @@ var getBoxByOriginNode = function (node) {
     return (0, _1.getNodeBBox)(node);
 };
 exports.getBoxByOriginNode = getBoxByOriginNode;
-/* 保证一条直线上只有2个节点： 删除x/y相同的中间节点 */
+/**
+ * 去除共线冗余中间点，保持每条直线段仅保留两端点
+ * - 若三点在同一水平线或同一垂直线，移除中间点
+ */
 var pointFilter = function (points) {
     var i = 1;
     while (i < points.length - 1) {
@@ -445,7 +466,16 @@ var pointFilter = function (points) {
     return points;
 };
 exports.pointFilter = pointFilter;
-/* 计算折线点 */
+/**
+ * 计算折线点（正交候选点 + A* 路径）
+ * 步骤：
+ * 1) 取源/目标节点的扩展包围盒与相邻点 sPoint/tPoint
+ * 2) 若两个扩展盒重合，使用简单路径 getSimplePoints
+ * 3) 构造 lineBBox/sMixBBox/tMixBBox，并收集其角点与中心交点
+ * 4) 过滤掉落在两个扩展盒内部的点，形成 connectPoints
+ * 5) 以 sPoint/tPoint 为起止，用 A* 查找路径
+ * 6) 拼入原始 start/end，并用 pointFilter 去除冗余共线点
+ */
 var getPolylinePoints = function (start, end, sNode, tNode, offset) {
     var sBBox = (0, exports.getBoxByOriginNode)(sNode);
     var tBBox = (0, exports.getBoxByOriginNode)(tNode);
@@ -589,6 +619,10 @@ var points2PointsList = function (points) {
     return pointsList;
 };
 exports.points2PointsList = points2PointsList;
+/**
+ * 当扩展 bbox 重合时的简化拐点计算
+ * - 根据起止段的方向（水平/垂直）插入 1~2 个中间点，避免折线重合与穿越
+ */
 var getSimplePoints = function (start, end, sPoint, tPoint) {
     var points = [];
     // start,sPoint的方向，水平或者垂直，即路径第一条线段的方向

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logicflow/core",
-  "version": "2.1.10",
+  "version": "2.1.11",
   "description": "LogicFlow, help you quickly create flowcharts",
   "main": "lib/index.js",
   "module": "es/index.js",

package/src/model/edge/PolylineEdgeModel.ts

@@ -504,7 +504,9 @@ export class PolylineEdgeModel extends BaseEdgeModel {
       this.offset || 0,
     )
     this.pointsList = this.orthogonalizePath(pointsList)
-    this.points = pointsList.map((point) => `${point.x},${point.y}`).join(' ')
+    this.points = this.pointsList
+      .map((point) => `${point.x},${point.y}`)
+      .join(' ')
   }
 
   @action

package/src/util/edge.ts

@@ -107,6 +107,15 @@ export const pointDirection = (point: Point, bbox: BoxBounds): Direction => {
 }
 
 /* 获取扩展图形上的点，即起始终点相邻的点，上一个或者下一个节点 */
+/**
+ * 计算扩展包围盒上的相邻点（起点或终点的下一个/上一个拐点）
+ * - 使用原始节点 bbox 来判定点相对中心的方向，避免 offset 扩展后宽高改变导致方向误判
+ * - 若 start 相对中心为水平方向，则返回扩展盒在 x 上的边界，y 保持不变
+ * - 若为垂直方向，则返回扩展盒在 y 上的边界，x 保持不变
+ * @param expendBBox 扩展后的包围盒（包含 offset）
+ * @param bbox 原始节点包围盒（用于正确的方向判定）
+ * @param point 起点或终点坐标
+ */
 export const getExpandedBBoxPoint = (
   expendBBox: BoxBounds,
   bbox: BoxBounds,
@@ -377,7 +386,11 @@ export const isSegmentCrossingBBox = (
   )
 }
 
-/* 获取下一个相邻的点 */
+/**
+ * 基于轴对齐规则获取某点的相邻可连通点（不穿越节点）
+ * - 仅考虑 x 或 y 相同的候选点，保证严格水平/垂直
+ * - 使用 isSegmentCrossingBBox 校验线段不穿越源/目标节点
+ */
 export const getNextNeighborPoints = (
   points: Point[],
   point: Point,
@@ -400,9 +413,12 @@ export const getNextNeighborPoints = (
   return filterRepeatPoints(neighbors)
 }
 
-/* 路径查找,AStar查找+曼哈顿距离
- * 算法wiki:https://zh.wikipedia.org/wiki/A*%E6%90%9C%E5%B0%8B%E6%BC%94%E7%AE%97%E6%B3%95
- * 方法无法复用，且调用了很多polyline相关的方法，暂不抽离到src/algorithm中
+/**
+ * 使用 A* + 曼哈顿启发式在候选点图上查找正交路径
+ * - 开放集/关闭集管理遍历
+ * - gScore 为累计实际代价，fScore = gScore + 启发式
+ * - 邻居仅为与当前点 x 或 y 相同且不穿越节点的点
+ * 参考：https://zh.wikipedia.org/wiki/A*%E6%90%9C%E5%B0%8B%E6%BC%94%E7%AE%97%E6%B3%95
  */
 export const pathFinder = (
   points: Point[],
@@ -474,8 +490,9 @@ export const pathFinder = (
       }
 
       if (current?.id && neighbor?.id) {
+        // 修复：累计代价应基于 gScore[current] 而非 fScore[current]
         const tentativeGScore =
-          fScore[current.id] + estimateDistance(current, neighbor)
+          (gScore[current.id] ?? 0) + estimateDistance(current, neighbor)
         if (gScore[neighbor.id] && tentativeGScore >= gScore[neighbor.id]) {
           return
         }
@@ -494,7 +511,10 @@ export const pathFinder = (
 export const getBoxByOriginNode = (node: BaseNodeModel): BoxBounds => {
   return getNodeBBox(node)
 }
-/* 保证一条直线上只有2个节点： 删除x/y相同的中间节点 */
+/**
+ * 去除共线冗余中间点，保持每条直线段仅保留两端点
+ * - 若三点在同一水平线或同一垂直线，移除中间点
+ */
 export const pointFilter = (points: Point[]): Point[] => {
   let i = 1
   while (i < points.length - 1) {
@@ -513,7 +533,16 @@ export const pointFilter = (points: Point[]): Point[] => {
   return points
 }
 
-/* 计算折线点 */
+/**
+ * 计算折线点（正交候选点 + A* 路径）
+ * 步骤：
+ * 1) 取源/目标节点的扩展包围盒与相邻点 sPoint/tPoint
+ * 2) 若两个扩展盒重合，使用简单路径 getSimplePoints
+ * 3) 构造 lineBBox/sMixBBox/tMixBBox，并收集其角点与中心交点
+ * 4) 过滤掉落在两个扩展盒内部的点，形成 connectPoints
+ * 5) 以 sPoint/tPoint 为起止，用 A* 查找路径
+ * 6) 拼入原始 start/end，并用 pointFilter 去除冗余共线点
+ */
 export const getPolylinePoints = (
   start: Point,
   end: Point,
@@ -699,6 +728,10 @@ export const points2PointsList = (points: string): Point[] => {
   return pointsList
 }
 
+/**
+ * 当扩展 bbox 重合时的简化拐点计算
+ * - 根据起止段的方向（水平/垂直）插入 1~2 个中间点，避免折线重合与穿越
+ */
 export const getSimplePoints = (
   start: Point,
   end: Point,