chartflow 0.1__py3-none-any.whl

chartflow/node/test_qnode.py

@@ -0,0 +1,2336 @@
+"""
+qnode库测试模块
+
+使用PyQt6的测试框架测试所有功能
+"""
+
+from PyQt6.QtGui import QColor
+from PyQt6.QtWidgets import QApplication
+from PyQt6.QtCore import QPoint
+
+
+import sys
+import unittest
+from typing import Optional
+
+from PyQt6.QtWidgets import QApplication, QGraphicsScene
+from PyQt6.QtCore import Qt, QPointF, QRectF
+from PyQt6.QtTest import QTest
+
+from chartflow.node import (
+    QNodeCanvas, QNodeItem, ConnectionItem, ArrowItem,
+    NodeState, NodeShape, ArrowState, ConnectionType,
+    NodeStyle, ConnectionStyle, ArrowStyle,
+    SelectionRect, QNodeEditor, QNodePortSpec
+)
+
+
+class TestEnums(unittest.TestCase):
+    """测试枚举类"""
+    
+    def testNodeState(self) -> None:
+        """测试NodeState枚举"""
+        self.assertEqual(NodeState.IDLE.name, "IDLE")
+        self.assertEqual(NodeState.HOVER.name, "HOVER")
+        self.assertEqual(NodeState.SELECTED.name, "SELECTED")
+    
+    def testNodeShape(self) -> None:
+        """测试NodeShape枚举"""
+        self.assertEqual(NodeShape.ELLIPSE.name, "ELLIPSE")
+        self.assertEqual(NodeShape.RECTANGLE.name, "RECTANGLE")
+        self.assertEqual(NodeShape.DIAMOND.name, "DIAMOND")
+    
+    def testArrowState(self) -> None:
+        """测试ArrowState枚举"""
+        self.assertEqual(ArrowState.IDLE.name, "IDLE")
+        self.assertEqual(ArrowState.HOVER.name, "HOVER")
+        self.assertEqual(ArrowState.SELECTED.name, "SELECTED")
+    
+    def testConnectionType(self) -> None:
+        """测试ConnectionType枚举"""
+        self.assertEqual(ConnectionType.BEZIER.name, "BEZIER")
+        self.assertEqual(ConnectionType.STRAIGHT.name, "STRAIGHT")
+
+
+class TestStyles(unittest.TestCase):
+    """测试样式类"""
+    
+    def testNodeStyle(self) -> None:
+        """测试NodeStyle"""
+        style = NodeStyle()
+        self.assertIsNotNone(style.idle_fill)
+        self.assertIsNotNone(style.idle_stroke)
+        self.assertIsNotNone(style.hover_overlay)
+        self.assertIsNotNone(style.selected_stroke)
+        self.assertIsNotNone(style.selected_overlay)
+        self.assertEqual(style.stroke_width, 2.0)
+        self.assertIsNotNone(style.text_color)
+    
+    def testConnectionStyle(self) -> None:
+        """测试ConnectionStyle"""
+        style = ConnectionStyle()
+        self.assertIsNotNone(style.normal_color)
+        self.assertIsNotNone(style.selected_color)
+        self.assertIsNotNone(style.hover_color)
+        self.assertEqual(style.stroke_width, 2.0)
+        self.assertEqual(style.selected_stroke_width, 3.0)
+    
+    def testArrowStyle(self) -> None:
+        """测试ArrowStyle"""
+        style = ArrowStyle()
+        self.assertIsNotNone(style.normal_color)
+        self.assertIsNotNone(style.selected_color)
+        self.assertIsNotNone(style.hover_color)
+        self.assertEqual(style.arrow_size, 12.0)
+        self.assertEqual(style.stroke_width, 2.0)
+
+
+class TestNodeItem(unittest.TestCase):
+    """测试NodeItem类"""
+    
+    @classmethod
+    def setUpClass(cls) -> None:
+        """设置测试类"""
+        cls.app = QApplication.instance()
+        if cls.app is None:
+            cls.app = QApplication(sys.argv)
+    
+    def setUp(self) -> None:
+        """设置每个测试"""
+        self.scene = QGraphicsScene()
+        self.node = QNodeItem("TestNode", QPointF(100, 100), NodeShape.ELLIPSE)
+        self.scene.addItem(self.node)
+    
+    def tearDown(self) -> None:
+        """清理每个测试"""
+        self.scene.clear()
+    
+    def testNodeCreation(self) -> None:
+        """测试节点创建"""
+        self.assertEqual(self.node.name, "TestNode")
+        self.assertEqual(self.node.pos(), QPointF(100, 100))
+        self.assertEqual(self.node.nodeShape, NodeShape.ELLIPSE)
+        self.assertEqual(self.node.state, NodeState.IDLE)
+    
+    def testNodeNameChange(self) -> None:
+        """测试节点名称修改"""
+        self.node.name = "NewName"
+        self.assertEqual(self.node.name, "NewName")
+    
+    def testNodeShapeChange(self) -> None:
+        """测试节点形状修改"""
+        self.node.nodeShape = NodeShape.RECTANGLE
+        self.assertEqual(self.node.nodeShape, NodeShape.RECTANGLE)
+        
+        self.node.nodeShape = NodeShape.DIAMOND
+        self.assertEqual(self.node.nodeShape, NodeShape.DIAMOND)
+    
+    def testNodeData(self) -> None:
+        """测试节点数据"""
+        # 数据字典应该是可修改的
+        self.node.data["key"] = "value"
+        self.assertEqual(self.node.data["key"], "value")
+        
+        self.node.data["number"] = 42
+        self.assertEqual(self.node.data["number"], 42)
+    
+    def testNodeEditorClass(self) -> None:
+        """测试节点编辑器类"""
+        self.assertIsNone(self.node.editorClass)
+        
+        # 设置编辑器类
+        class TestEditor(QNodeEditor):
+            pass
+        
+        self.node.editorClass = TestEditor
+        self.assertEqual(self.node.editorClass, TestEditor)
+    
+    def testNodeSelection(self) -> None:
+        """测试节点选择"""
+        self.node.setSelected(True)
+        self.assertTrue(self.node.isSelected())
+        self.assertEqual(self.node.state, NodeState.SELECTED)
+        
+        self.node.setSelected(False)
+        self.assertFalse(self.node.isSelected())
+        self.assertEqual(self.node.state, NodeState.IDLE)
+    
+    def testNodeToDict(self) -> None:
+        """测试节点转字典"""
+        self.node.data["test"] = "data"
+        data = self.node.toDict()
+        
+        self.assertIn("id", data)
+        self.assertEqual(data["name"], "TestNode")
+        self.assertEqual(data["shape"], "ELLIPSE")
+        self.assertIn("position", data)
+        self.assertIn("data", data)
+        self.assertEqual(data["data"]["test"], "data")
+    
+    def testNodeFromDict(self) -> None:
+        """测试节点从字典更新"""
+        data = {
+            "name": "UpdatedName",
+            "shape": "RECTANGLE",
+            "position": {"x": 200, "y": 300},
+            "data": {"custom": "value"}
+        }
+        self.node.fromDict(data)
+        
+        self.assertEqual(self.node.name, "UpdatedName")
+        self.assertEqual(self.node.nodeShape, NodeShape.RECTANGLE)
+        self.assertEqual(self.node.pos(), QPointF(200, 300))
+        self.assertEqual(self.node.data["custom"], "value")
+    
+    def testGetEdgePointEllipse(self) -> None:
+        """测试圆形节点边缘点计算"""
+        self.node.shape = NodeShape.ELLIPSE
+        center = self.node.sceneBoundingRect().center()
+        target = QPointF(center.x() + 200, center.y())
+        edge = self.node.getEdgePoint(target)
+        
+        # 边缘点应该在中心右侧
+        self.assertGreater(edge.x(), center.x())
+    
+    def testGetEdgePointRectangle(self) -> None:
+        """测试矩形节点边缘点计算"""
+        self.node.shape = NodeShape.RECTANGLE
+        center = self.node.sceneBoundingRect().center()
+        target = QPointF(center.x() + 200, center.y())
+        edge = self.node.getEdgePoint(target)
+        
+        # 边缘点应该在中心右侧
+        self.assertGreater(edge.x(), center.x())
+    
+    def testGetEdgePointDiamond(self) -> None:
+        """测试菱形节点边缘点计算"""
+        self.node.shape = NodeShape.DIAMOND
+        center = self.node.sceneBoundingRect().center()
+        target = QPointF(center.x() + 200, center.y())
+        edge = self.node.getEdgePoint(target)
+
+        # 边缘点应该在中心右侧
+        self.assertGreater(edge.x(), center.x())
+
+    def testSetColor(self) -> None:
+        """测试设置节点颜色"""
+
+        # 设置新颜色
+        new_color = QColor(255, 0, 0)  # 红色
+        self.node.setColor(new_color)
+
+        # 验证颜色已设置
+        self.assertEqual(self.node._style.idle_fill, new_color)
+
+    def testSetBorder(self) -> None:
+        """测试设置节点边框"""
+
+        # 设置边框宽度和颜色
+        border_color = QColor(0, 255, 0)  # 绿色
+        self.node.setBorder(3, border_color)
+
+        # 验证边框设置
+        self.assertEqual(self.node._style.stroke_width, 3)
+        self.assertEqual(self.node._style.idle_stroke, border_color)
+
+        # 测试无边框（宽度<=0）
+        self.node.setBorder(0)
+        # 应该设置NoPen
+        pen = self.node.pen()
+        self.assertEqual(pen.style(), Qt.PenStyle.NoPen)
+
+    def testNodeNameEditingState(self) -> None:
+        """测试节点名称编辑状态"""
+        # 初始状态应该不在编辑
+        self.assertFalse(self.node.isEditingName)
+
+        # 开始编辑
+        self.node._startNameEdit()
+        self.assertTrue(self.node.isEditingName)
+
+        # 完成编辑
+        self.node._finishNameEdit()
+        self.assertFalse(self.node.isEditingName)
+
+    def testNodeNameEditCancel(self) -> None:
+        """测试编辑节点名称后确认，名称应更新为新文本"""
+        # 开始编辑
+        self.node._startNameEdit()
+        self.assertTrue(self.node.isEditingName)
+
+        # 原位编辑：文本保存在 _text_item 中（旧版 _name_edit/QLineEdit 已弃用）
+        self.node._text_item.setPlainText("NewName")
+
+        # 完成编辑（_finishNameEdit 读取 _text_item 文本并更新名称）
+        self.node._finishNameEdit()
+        self.assertFalse(self.node.isEditingName)
+        self.assertEqual(self.node.name, "NewName")
+
+    def testNodeNameEditInPlace(self) -> None:
+        """测试节点名称编辑使用原位 QGraphicsTextItem 编辑"""
+        # 开始编辑
+        self.node._startNameEdit()
+        self.assertTrue(self.node.isEditingName)
+
+        # 原位编辑：_text_item 启用文本编辑交互
+        flags = self.node._text_item.textInteractionFlags()
+        self.assertEqual(flags, Qt.TextInteractionFlag.TextEditorInteraction)
+
+        # _startNameEdit 会选中全部文本，方便覆盖输入（不依赖视图焦点）
+        self.assertTrue(self.node._text_item.textCursor().hasSelection())
+
+        # 完成编辑
+        self.node._finishNameEdit()
+        self.assertFalse(self.node.isEditingName)
+        # 完成后恢复为不可编辑
+        flags = self.node._text_item.textInteractionFlags()
+        self.assertEqual(flags, Qt.TextInteractionFlag.NoTextInteraction)
+
+
+class TestConnectionItem(unittest.TestCase):
+    """测试ConnectionItem类"""
+    
+    @classmethod
+    def setUpClass(cls) -> None:
+        """设置测试类"""
+        cls.app = QApplication.instance()
+        if cls.app is None:
+            cls.app = QApplication(sys.argv)
+    
+    def setUp(self) -> None:
+        """设置每个测试"""
+        self.scene = QGraphicsScene()
+        self.source_node = QNodeItem("Source", QPointF(0, 0))
+        self.target_node = QNodeItem("Target", QPointF(200, 0))
+        self.scene.addItem(self.source_node)
+        self.scene.addItem(self.target_node)
+        
+        self.connection = ConnectionItem(
+            self.source_node, self.target_node,
+            is_bidirectional=False,
+            connection_type=ConnectionType.BEZIER
+        )
+        self.scene.addItem(self.connection)
+        self.scene.addItem(self.connection.targetArrow)
+    
+    def tearDown(self) -> None:
+        """清理每个测试"""
+        self.connection.removeArrows()
+        self.scene.removeItem(self.connection)
+        self.scene.clear()
+    
+    def testConnectionCreation(self) -> None:
+        """测试连接创建"""
+        self.assertEqual(self.connection.sourceNode, self.source_node)
+        self.assertEqual(self.connection.targetNode, self.target_node)
+        self.assertFalse(self.connection.isBidirectional)
+        self.assertEqual(self.connection.connectionType, ConnectionType.BEZIER)
+    
+    def testConnectionTypeToggle(self) -> None:
+        """测试连接类型切换"""
+        self.assertEqual(self.connection.connectionType, ConnectionType.BEZIER)
+        
+        self.connection.toggleConnectionType()
+        self.assertEqual(self.connection.connectionType, ConnectionType.STRAIGHT)
+        
+        self.connection.toggleConnectionType()
+        self.assertEqual(self.connection.connectionType, ConnectionType.BEZIER)
+    
+    def testBidirectionalToggle(self) -> None:
+        """测试双向连接切换"""
+        self.assertFalse(self.connection.isBidirectional)
+        
+        self.connection.isBidirectional = True
+        self.assertTrue(self.connection.isBidirectional)
+        self.assertIsNotNone(self.connection.sourceArrow)
+        
+        self.connection.isBidirectional = False
+        self.assertFalse(self.connection.isBidirectional)
+        self.assertIsNone(self.connection.sourceArrow)
+    
+    def testSwapDirection(self) -> None:
+        """测试连接方向交换"""
+        original_source = self.connection.sourceNode
+        original_target = self.connection.targetNode
+        
+        self.connection.swapDirection()
+
+        self.assertEqual(self.connection.sourceNode, original_target)
+        self.assertEqual(self.connection.targetNode, original_source)
+
+    def testConnectionSetColor(self) -> None:
+        """测试设置连接线颜色"""
+
+        new_color = QColor(255, 0, 0)  # 红色
+        self.connection.setColor(new_color)
+
+        # 验证颜色已设置
+        self.assertEqual(self.connection._style.normal_color, new_color)
+
+    def testConnectionSetBorder(self) -> None:
+        """测试设置连接线边框（线宽）"""
+
+        # 设置线宽和颜色
+        border_color = QColor(0, 255, 0)  # 绿色
+        self.connection.setBorder(5, border_color)
+
+        # 验证设置
+        self.assertEqual(self.connection._style.stroke_width, 5)
+
+
+class TestArrowItem(unittest.TestCase):
+    """测试ArrowItem类"""
+    
+    @classmethod
+    def setUpClass(cls) -> None:
+        """设置测试类"""
+        cls.app = QApplication.instance()
+        if cls.app is None:
+            cls.app = QApplication(sys.argv)
+    
+    def setUp(self) -> None:
+        """设置每个测试"""
+        self.scene = QGraphicsScene()
+        self.source_node = QNodeItem("Source", QPointF(0, 0))
+        self.target_node = QNodeItem("Target", QPointF(200, 0))
+        self.scene.addItem(self.source_node)
+        self.scene.addItem(self.target_node)
+        
+        self.connection = ConnectionItem(self.source_node, self.target_node)
+        self.scene.addItem(self.connection)
+        self.arrow = self.connection.targetArrow
+    
+    def tearDown(self) -> None:
+        """清理每个测试"""
+        self.connection.removeArrows()
+        self.scene.removeItem(self.connection)
+        self.scene.clear()
+    
+    def testArrowCreation(self) -> None:
+        """测试箭头创建"""
+        self.assertEqual(self.arrow.connection, self.connection)
+        self.assertFalse(self.arrow.isSourceArrow)
+    
+    def testArrowSelection(self) -> None:
+        """测试箭头选择"""
+        self.arrow.setSelected(True)
+        self.assertTrue(self.arrow.isSelected())
+
+        self.arrow.setSelected(False)
+        self.assertFalse(self.arrow.isSelected())
+
+    def testArrowSetColor(self) -> None:
+        """测试设置箭头颜色"""
+
+        new_color = QColor(255, 0, 0)  # 红色
+        self.arrow.setColor(new_color)
+
+        # 验证颜色已设置
+        self.assertEqual(self.arrow._style.normal_color, new_color)
+
+    def testArrowSetBorder(self) -> None:
+        """测试设置箭头边框"""
+
+        # 设置边框宽度和颜色
+        border_color = QColor(0, 255, 0)  # 绿色
+        self.arrow.setBorder(3, border_color)
+
+        # 验证设置
+        self.assertEqual(self.arrow._style.stroke_width, 3)
+
+
+class TestSelectionRect(unittest.TestCase):
+    """测试SelectionRect类"""
+    
+    @classmethod
+    def setUpClass(cls) -> None:
+        """设置测试类"""
+        cls.app = QApplication.instance()
+        if cls.app is None:
+            cls.app = QApplication(sys.argv)
+    
+    def setUp(self) -> None:
+        """设置每个测试"""
+        self.scene = QGraphicsScene()
+        self.selection_rect = SelectionRect()
+        self.scene.addItem(self.selection_rect)
+    
+    def tearDown(self) -> None:
+        """清理每个测试"""
+        self.scene.clear()
+    
+    def testSelectionRectCreation(self) -> None:
+        """测试框选矩形创建"""
+        self.assertIsNotNone(self.selection_rect)
+        self.assertEqual(self.selection_rect.zValue(), 1000)
+
+    def testSelectionRectSetColor(self) -> None:
+        """测试设置框选矩形颜色"""
+
+        new_color = QColor(255, 0, 0, 100)  # 半透明红色
+        self.selection_rect.setColor(new_color)
+
+        # 验证颜色已设置
+        self.assertEqual(self.selection_rect._fill_color, new_color)
+
+    def testSelectionRectSetBorder(self) -> None:
+        """测试设置框选矩形边框"""
+
+        # 设置边框宽度和颜色
+        border_color = QColor(0, 255, 0)  # 绿色
+        self.selection_rect.setBorder(3, border_color)
+
+        # 验证设置
+        self.assertEqual(self.selection_rect._border_width, 3)
+        self.assertEqual(self.selection_rect._border_color, border_color)
+
+
+class TestNodeCanvas(unittest.TestCase):
+    """测试NodeCanvas类"""
+    
+    @classmethod
+    def setUpClass(cls) -> None:
+        """设置测试类"""
+        cls.app = QApplication.instance()
+        if cls.app is None:
+            cls.app = QApplication(sys.argv)
+    
+    def setUp(self) -> None:
+        """设置每个测试"""
+        self.canvas = QNodeCanvas()
+        self.canvas.resize(800, 600)
+        self.canvas.show()
+    
+    def tearDown(self) -> None:
+        """清理每个测试"""
+        self.canvas.close()
+    
+    def testCanvasCreation(self) -> None:
+        """测试画布创建"""
+        self.assertIsNotNone(self.canvas.scene())
+        self.assertEqual(len(self.canvas.nodes), 0)
+        self.assertEqual(len(self.canvas.connections), 0)
+    
+    def testAddNode(self) -> None:
+        """测试添加节点"""
+        node = self.canvas.addNode("TestNode", QPointF(100, 100))
+        self.assertIn(node, self.canvas.nodes)
+        self.assertEqual(node.name, "TestNode")
+    
+    def testRemoveNode(self) -> None:
+        """测试移除节点"""
+        node = self.canvas.addNode("TestNode")
+        self.canvas.removeNode(node)
+        self.assertNotIn(node, self.canvas.nodes)
+    
+    def testAddConnection(self) -> None:
+        """测试添加连接"""
+        node1 = self.canvas.addNode("Node1", QPointF(0, 0))
+        node2 = self.canvas.addNode("Node2", QPointF(200, 0))
+        
+        connection = self.canvas.addConnection(node1, node2)
+        self.assertIn(connection, self.canvas.connections)
+        self.assertEqual(connection.sourceNode, node1)
+        self.assertEqual(connection.targetNode, node2)
+    
+    def testRemoveConnection(self) -> None:
+        """测试移除连接"""
+        node1 = self.canvas.addNode("Node1")
+        node2 = self.canvas.addNode("Node2")
+        connection = self.canvas.addConnection(node1, node2)
+        
+        self.canvas.removeConnection(connection)
+        self.assertNotIn(connection, self.canvas.connections)
+    
+    def testStartNode(self) -> None:
+        """测试起点节点"""
+        node = self.canvas.addNode("StartNode")
+        self.canvas.startNode = node
+        
+        self.assertEqual(self.canvas.startNode, node)
+    
+    def testExportImport(self) -> None:
+        """测试导出导入"""
+        # 创建一些节点和连接
+        node1 = self.canvas.addNode("Node1", QPointF(0, 0))
+        node2 = self.canvas.addNode("Node2", QPointF(100, 100))
+        self.canvas.addConnection(node1, node2)
+        self.canvas.startNode = node1
+        
+        # 导出（现在返回字典）
+        data = self.canvas.export()
+        self.assertIsInstance(data, dict)
+        self.assertIn("nodes", data)
+        self.assertIn("connections", data)
+
+        # 测试导出为 JSON 字符串
+        json_str = self.canvas.exportToJson()
+        self.assertIsInstance(json_str, str)
+        self.assertIn("nodes", json_str)
+
+        # 清空
+        self.canvas.clear()
+        self.assertEqual(len(self.canvas.nodes), 0)
+        self.assertEqual(len(self.canvas.connections), 0)
+
+        # 导入字典
+        self.canvas.importData(data)
+        self.assertEqual(len(self.canvas.nodes), 2)
+        self.assertEqual(len(self.canvas.connections), 1)
+    
+    def testClear(self) -> None:
+        """测试清空画布"""
+        node1 = self.canvas.addNode("Node1")
+        node2 = self.canvas.addNode("Node2")
+        self.canvas.addConnection(node1, node2)
+        
+        self.canvas.clear()
+        self.assertEqual(len(self.canvas.nodes), 0)
+        self.assertEqual(len(self.canvas.connections), 0)
+    
+    def testChangedState(self) -> None:
+        """测试修改状态"""
+        self.assertFalse(self.canvas.changed)
+
+        self.canvas.addNode("TestNode")
+        self.assertTrue(self.canvas.changed)
+
+    def testClickOutsideToCancelNameEdit(self) -> None:
+        """测试点击画布外部取消节点名称编辑"""
+        # 添加节点
+        node = self.canvas.addNode("TestNode", QPointF(100, 100))
+
+        # 开始编辑
+        node._startNameEdit()
+        self.assertTrue(node.isEditingName)
+
+        # 原位编辑无独立代理控件，使用节点自身的场景边界来定位
+        node_rect = node.sceneBoundingRect()
+        edit_center = node_rect.center()
+
+        # 模拟点击画布外部（远离节点）
+        outside_pos = QPointF(edit_center.x() + 200, edit_center.y() + 200)
+
+        # 创建鼠标事件
+
+        # 将场景坐标转换为视图坐标
+        view_pos = self.canvas.mapFromScene(outside_pos)
+
+        # 发送鼠标按下事件
+        QTest.mouseClick(self.canvas.viewport(), Qt.MouseButton.LeftButton,
+                        pos=view_pos)
+
+        # 检查编辑是否被取消
+        self.assertFalse(node.isEditingName)
+
+    def testEdgeDetectionEllipse(self) -> None:
+        """测试圆形节点边缘检测"""
+        node = self.canvas.addNode("EllipseNode", QPointF(100, 100), NodeShape.ELLIPSE)
+        center = node.sceneBoundingRect().center()
+        radius = node.radius
+
+        # 边缘位置（应该检测到）
+        edge_pos = QPointF(center.x() + radius * 0.9, center.y())
+        self.assertTrue(self.canvas._is_on_node_edge(node, edge_pos))
+
+        # 中心位置（不应该检测到）
+        center_pos = QPointF(center.x() + radius * 0.5, center.y())
+        self.assertFalse(self.canvas._is_on_node_edge(node, center_pos))
+
+        # 外部位置（不应该检测到）
+        outside_pos = QPointF(center.x() + radius * 1.2, center.y())
+        self.assertFalse(self.canvas._is_on_node_edge(node, outside_pos))
+
+    def testEdgeDetectionRectangle(self) -> None:
+        """测试矩形节点边缘检测，包括角落区域"""
+        node = self.canvas.addNode("RectNode", QPointF(100, 100), NodeShape.RECTANGLE)
+        center = node.sceneBoundingRect().center()
+        rect = node.rect()
+        half_w = rect.width() / 2
+        half_h = rect.height() / 2
+
+        # 右边缘位置（应该检测到）
+        right_edge = QPointF(center.x() + half_w * 0.9, center.y())
+        self.assertTrue(self.canvas._is_on_node_edge(node, right_edge))
+
+        # 左边缘位置（应该检测到）
+        left_edge = QPointF(center.x() - half_w * 0.9, center.y())
+        self.assertTrue(self.canvas._is_on_node_edge(node, left_edge))
+
+        # 上边缘位置（应该检测到）
+        top_edge = QPointF(center.x(), center.y() - half_h * 0.9)
+        self.assertTrue(self.canvas._is_on_node_edge(node, top_edge))
+
+        # 下边缘位置（应该检测到）
+        bottom_edge = QPointF(center.x(), center.y() + half_h * 0.9)
+        self.assertTrue(self.canvas._is_on_node_edge(node, bottom_edge))
+
+        # 角落区域（应该检测到）- 在圆角边缘附近
+        # 计算一个更靠近实际边界的测试点
+        inner_w = half_w - min(half_w, half_h) * 0.2
+        inner_h = half_h - min(half_w, half_h) * 0.2
+        # 在角落附近，稍微超出内矩形边界
+        corner_pos = QPointF(center.x() + inner_w * 1.05, center.y() + inner_h * 1.05)
+        self.assertTrue(self.canvas._is_on_node_edge(node, corner_pos))
+
+        # 中心位置（不应该检测到）
+        center_pos = QPointF(center.x(), center.y())
+        self.assertFalse(self.canvas._is_on_node_edge(node, center_pos))
+
+        # 外部位置（不应该检测到）
+        outside_pos = QPointF(center.x() + half_w * 1.2, center.y())
+        self.assertFalse(self.canvas._is_on_node_edge(node, outside_pos))
+
+    def testEdgeDetectionRectangleCorners(self) -> None:
+        """测试矩形节点四个角落的边缘检测"""
+        node = self.canvas.addNode("RectNode", QPointF(100, 100), NodeShape.RECTANGLE)
+        center = node.sceneBoundingRect().center()
+        rect = node.rect()
+        half_w = rect.width() / 2
+        half_h = rect.height() / 2
+        corner_radius = min(half_w, half_h) * 0.2
+        inner_w = half_w - corner_radius
+        inner_h = half_h - corner_radius
+
+        # 测试四个角落（在圆角边缘附近）
+        # 需要确保测试点在 inner_w/h 之外，但在 half_w/h 之内
+        # 使用 inner_w * 1.1 确保在圆角区域内
+        corners = [
+            ("左下", QPointF(center.x() - inner_w * 1.1, center.y() + inner_h * 1.1)),
+            ("右下", QPointF(center.x() + inner_w * 1.1, center.y() + inner_h * 1.1)),
+            ("左上", QPointF(center.x() - inner_w * 1.1, center.y() - inner_h * 1.1)),
+            ("右上", QPointF(center.x() + inner_w * 1.1, center.y() - inner_h * 1.1)),
+        ]
+
+        for name, pos in corners:
+            with self.subTest(corner=name):
+                self.assertTrue(
+                    self.canvas._is_on_node_edge(node, pos),
+                    f"{name}角落应该被检测为边缘区域"
+                )
+
+    def testEdgeDetectionDiamond(self) -> None:
+        """测试菱形节点边缘检测"""
+        node = self.canvas.addNode("DiamondNode", QPointF(100, 100), NodeShape.DIAMOND)
+        center = node.sceneBoundingRect().center()
+        radius = node.radius
+
+        # 右顶点边缘位置（应该检测到）
+        right_edge = QPointF(center.x() + radius * 0.9, center.y())
+        self.assertTrue(self.canvas._is_on_node_edge(node, right_edge))
+
+        # 上顶点边缘位置（应该检测到）
+        top_edge = QPointF(center.x(), center.y() - radius * 0.9)
+        self.assertTrue(self.canvas._is_on_node_edge(node, top_edge))
+
+        # 中心位置（不应该检测到）
+        center_pos = QPointF(center.x() + radius * 0.3, center.y() + radius * 0.3)
+        self.assertFalse(self.canvas._is_on_node_edge(node, center_pos))
+
+        # 外部位置（不应该检测到）
+        outside_pos = QPointF(center.x() + radius * 1.2, center.y())
+        self.assertFalse(self.canvas._is_on_node_edge(node, outside_pos))
+
+    def testDuplicateConnectionFlashError(self) -> None:
+        """测试重复连接时触发错误闪烁"""
+        node1 = self.canvas.addNode("Node1", QPointF(0, 0))
+        node2 = self.canvas.addNode("Node2", QPointF(200, 0))
+
+        # 创建第一个连接
+        conn1 = self.canvas.addConnection(node1, node2)
+        self.assertEqual(len(self.canvas.connections), 1)
+
+        # 尝试创建重复连接，应该返回已存在的连接并触发 flashError
+        conn2 = self.canvas.addConnection(node1, node2)
+        self.assertEqual(conn1, conn2)  # 返回同一个连接
+        self.assertEqual(len(self.canvas.connections), 1)  # 连接数量不变
+
+    def testReverseConnectionBecomesBidirectional(self) -> None:
+        """测试反向连接转换为双向连接"""
+        node1 = self.canvas.addNode("Node1", QPointF(0, 0))
+        node2 = self.canvas.addNode("Node2", QPointF(200, 0))
+
+        # 创建 node1 -> node2 的连接
+        conn1 = self.canvas.addConnection(node1, node2)
+        self.assertFalse(conn1.isBidirectional)
+        self.assertEqual(len(self.canvas.connections), 1)
+
+        # 创建反向连接 node2 -> node1，应该将原连接变为双向
+        conn2 = self.canvas.addConnection(node2, node1)
+        self.assertTrue(conn1.isBidirectional)  # 原连接变为双向
+        self.assertEqual(conn1, conn2)  # 返回同一个连接
+        self.assertEqual(len(self.canvas.connections), 1)  # 连接数量不变
+
+    def testDuplicateBidirectionalConnectionFlashError(self) -> None:
+        """测试重复双向连接时触发错误闪烁"""
+        node1 = self.canvas.addNode("Node1", QPointF(0, 0))
+        node2 = self.canvas.addNode("Node2", QPointF(200, 0))
+
+        # 创建双向连接
+        conn1 = self.canvas.addConnection(node1, node2, is_bidirectional=True)
+        self.assertTrue(conn1.isBidirectional)
+
+        # 尝试创建反向连接，应该触发 flashError
+        conn2 = self.canvas.addConnection(node2, node1)
+        self.assertEqual(conn1, conn2)
+        self.assertTrue(conn1.isBidirectional)  # 保持双向
+
+
+class TestQNodeEditor(unittest.TestCase):
+    """测试QNodeEditor类"""
+    
+    @classmethod
+    def setUpClass(cls) -> None:
+        """设置测试类"""
+        cls.app = QApplication.instance()
+        if cls.app is None:
+            cls.app = QApplication(sys.argv)
+    
+    def setUp(self) -> None:
+        """设置每个测试"""
+        self.scene = QGraphicsScene()
+        self.node = QNodeItem("TestNode")
+        self.scene.addItem(self.node)
+        self.editor = QNodeEditor(self.node)
+    
+    def tearDown(self) -> None:
+        """清理每个测试"""
+        self.editor.close()
+        self.scene.clear()
+    
+    def testEditorCreation(self) -> None:
+        """测试编辑器创建"""
+        self.assertEqual(self.editor.node, self.node)
+    
+    def testEditorTitle(self) -> None:
+        """测试编辑器标题"""
+        title = self.editor.getTitle()
+        self.assertIn("TestNode", title)
+    
+    def testEditorSaveLoad(self) -> None:
+        """测试编辑器保存和加载"""
+        self.assertTrue(self.editor.save())
+        self.assertTrue(self.editor.load())
+
+
+class TestNodeShapes(unittest.TestCase):
+    """测试不同节点形状"""
+    
+    @classmethod
+    def setUpClass(cls) -> None:
+        """设置测试类"""
+        cls.app = QApplication.instance()
+        if cls.app is None:
+            cls.app = QApplication(sys.argv)
+    
+    def testEllipseShape(self) -> None:
+        """测试椭圆形"""
+        node = QNodeItem("EllipseNode", shape=NodeShape.ELLIPSE)
+        self.assertEqual(node.nodeShape, NodeShape.ELLIPSE)
+        
+        # 测试边缘点计算
+        center = QPointF(100, 100)
+        node.setPos(center)
+        target = QPointF(200, 100)
+        edge = node.getEdgePoint(target)
+        self.assertIsNotNone(edge)
+    
+    def testRectangleShape(self) -> None:
+        """测试矩形"""
+        node = QNodeItem("RectNode", shape=NodeShape.RECTANGLE)
+        self.assertEqual(node.nodeShape, NodeShape.RECTANGLE)
+        
+        # 测试边缘点计算
+        center = QPointF(100, 100)
+        node.setPos(center)
+        target = QPointF(200, 100)
+        edge = node.getEdgePoint(target)
+        self.assertIsNotNone(edge)
+    
+    def testDiamondShape(self) -> None:
+        """测试菱形"""
+        node = QNodeItem("DiamondNode", shape=NodeShape.DIAMOND)
+        self.assertEqual(node.nodeShape, NodeShape.DIAMOND)
+        
+        # 测试边缘点计算
+        center = QPointF(100, 100)
+        node.setPos(center)
+        target = QPointF(200, 100)
+        edge = node.getEdgePoint(target)
+        self.assertIsNotNone(edge)
+
+
+class TestArrowDragFunctionality(unittest.TestCase):
+    """测试箭头拖拽创建新连接功能"""
+
+    @classmethod
+    def setUpClass(cls) -> None:
+        """设置测试类"""
+        cls.app = QApplication.instance()
+        if cls.app is None:
+            cls.app = QApplication(sys.argv)
+
+    def setUp(self) -> None:
+        """设置每个测试"""
+        self.canvas = QNodeCanvas()
+        self.canvas.show()
+        # 添加三个节点用于测试
+        self.nodeA = self.canvas.addNode("NodeA", QPointF(0, 0))
+        self.nodeB = self.canvas.addNode("NodeB", QPointF(300, 0))
+        self.nodeC = self.canvas.addNode("NodeC", QPointF(600, 0))
+
+    def tearDown(self) -> None:
+        """清理每个测试"""
+        self.canvas.close()
+
+    def testArrowDragStateTracking(self) -> None:
+        """测试箭头拖拽状态追踪属性"""
+        # 创建连接
+        conn = self.canvas.addConnection(self.nodeA, self.nodeB)
+        self.assertIsNotNone(conn)
+
+        # 获取目标箭头
+        arrow = conn.targetArrow
+        self.assertIsNotNone(arrow)
+
+        # 检查isDragging初始状态
+        self.assertFalse(arrow.isDragging)
+        self.assertFalse(arrow.isSourceArrow)
+
+    def testArrowDragSourceArrowProperty(self) -> None:
+        """测试源端箭头属性"""
+        # 创建双向连接
+        conn = self.canvas.addConnection(self.nodeA, self.nodeB, is_bidirectional=True)
+        self.assertIsNotNone(conn)
+        self.assertTrue(conn.isBidirectional)
+
+        # 检查目标箭头
+        target_arrow = conn.targetArrow
+        self.assertIsNotNone(target_arrow)
+        self.assertFalse(target_arrow.isSourceArrow)
+
+        # 检查源端箭头
+        source_arrow = conn.sourceArrow
+        self.assertIsNotNone(source_arrow)
+        self.assertTrue(source_arrow.isSourceArrow)
+
+    def testAddConnectionWithCheckPartners(self) -> None:
+        """测试addConnection的checkPartners参数"""
+        # 创建 A -> B 连接
+        conn1 = self.canvas.addConnection(self.nodeA, self.nodeB)
+        self.assertIsNotNone(conn1)
+        self.assertEqual(len(self.canvas.connections), 1)
+
+        # 使用 check_partners=False 尝试创建新连接（应该成功）
+        conn2 = self.canvas.addConnection(self.nodeA, self.nodeC, check_partners=False)
+        self.assertIsNotNone(conn2)
+        self.assertEqual(len(self.canvas.connections), 2)
+        self.assertIn(conn2, self.canvas.connections)
+
+    def testAddConnectionSelfConnection(self) -> None:
+        """node→node 自环: 允许并创建为环线; port 自指一律拒绝"""
+        # node→node 自环: 允许(绘制为一个向外的小圆环)
+        conn = self.canvas.addConnection(self.nodeA, self.nodeA)
+        self.assertIsNotNone(conn)
+        self.assertTrue(conn.isSelfLoop())
+        self.assertEqual(len(self.canvas.connections), 1)
+        # 重复创建同一自环: 命中已存在, 闪烁并返回已存在连线(不新增)
+        conn2 = self.canvas.addConnection(self.nodeA, self.nodeA)
+        self.assertIs(conn2, conn)
+        self.assertEqual(len(self.canvas.connections), 1)
+
+    def testAddConnectionPortSelfReference(self) -> None:
+        """同节点 port 连接: 异极自环允许, 同极/单端 port 拒绝"""
+        from chartflow.node.port_item import QNodePortSpec
+        self.nodeA.ports = {
+            "left": [QNodePortSpec(name="in")],
+            "right": [QNodePortSpec(name="out")],
+        }
+        in_port = self.nodeA._port_items["left"][0]
+        out_port = self.nodeA._port_items["right"][0]
+
+        # port→port 同极(left→left / right→right): 拒绝
+        self.assertIsNone(self.canvas.addConnection(
+            self.nodeA, self.nodeA, source_port=in_port, target_port=in_port))
+        self.assertIsNone(self.canvas.addConnection(
+            self.nodeA, self.nodeA, source_port=out_port, target_port=out_port))
+        # port→其所在 node: 拒绝(单端 port, 无意义)
+        self.assertIsNone(self.canvas.addConnection(
+            self.nodeA, self.nodeA, source_port=out_port))
+        # node→其 port: 拒绝(单端 port)
+        self.assertIsNone(self.canvas.addConnection(
+            self.nodeA, self.nodeA, target_port=in_port))
+        self.assertEqual(len(self.canvas.connections), 0)
+
+        # port→port 异极自环(right→left): 允许, 画为绕外侧的环
+        loop = self.canvas.addConnection(
+            self.nodeA, self.nodeA, source_port=out_port, target_port=in_port)
+        self.assertIsNotNone(loop)
+        self.assertTrue(loop.isSelfLoop())
+        # left→right 是独立方向: 与 right→left 互不去重, 各自一条
+        loop2 = self.canvas.addConnection(
+            self.nodeA, self.nodeA, source_port=in_port, target_port=out_port)
+        self.assertIsNotNone(loop2)
+        self.assertIsNot(loop, loop2)
+        self.assertEqual(len(self.canvas.connections), 2)
+
+    def testAddConnectionPortPolarity(self) -> None:
+        """port→port 极性冲突(left→left / right→right)被拒绝, 异极允许"""
+        from chartflow.node.port_item import QNodePortSpec
+        # A: left=in, right=out; B: left=in, right=out
+        self.nodeA.ports = {"left": [QNodePortSpec(name="in")], "right": [QNodePortSpec(name="out")]}
+        self.nodeB.ports = {"left": [QNodePortSpec(name="in")], "right": [QNodePortSpec(name="out")]}
+        a_in = self.nodeA._port_items["left"][0]
+        a_out = self.nodeA._port_items["right"][0]
+        b_in = self.nodeB._port_items["left"][0]
+        b_out = self.nodeB._port_items["right"][0]
+
+        # 同极拒绝: left→left, right→right
+        self.assertIsNone(self.canvas.addConnection(
+            self.nodeA, self.nodeB, source_port=a_in, target_port=b_in))
+        self.assertIsNone(self.canvas.addConnection(
+            self.nodeA, self.nodeB, source_port=a_out, target_port=b_out))
+        # 异极允许: right→left, left→right
+        self.assertIsNotNone(self.canvas.addConnection(
+            self.nodeA, self.nodeB, source_port=a_out, target_port=b_in))
+        self.assertIsNotNone(self.canvas.addConnection(
+            self.nodeA, self.nodeB, source_port=a_in, target_port=b_out))
+        # 仅异极两条被创建
+        self.assertEqual(len(self.canvas.connections), 2)
+
+    def testSelfRefsProperty(self) -> None:
+        """selfrefs: 只读 property 返回内部 dict(可直接改值), 默认值=既有逻辑"""
+        from chartflow.node.port_item import QNodePortSpec
+        # 默认值 = 既有逻辑(6 个键, right->left 与 left->right 独立)
+        self.assertEqual(self.nodeA.selfrefs, {
+            "node->node": True,
+            "port->port": False,
+            "node->port": False,
+            "port->node": False,
+            "left->right": True,
+            "right->left": True,
+        })
+        # 返回内部 dict(非副本): 直接改值立即生效
+        self.assertIs(self.nodeA.selfrefs, self.nodeA._selfrefs)
+
+        # 配置端口
+        self.nodeA.ports = {"left": [QNodePortSpec(name="in")], "right": [QNodePortSpec(name="out")]}
+        a_in = self.nodeA._port_items["left"][0]
+        a_out = self.nodeA._port_items["right"][0]
+
+        # 默认: node->port / port->node / port->port 被拒
+        self.assertIsNone(self.canvas.addConnection(self.nodeA, self.nodeA, target_port=a_in))
+        self.assertIsNone(self.canvas.addConnection(self.nodeA, self.nodeA, source_port=a_out))
+        self.assertIsNone(self.canvas.addConnection(self.nodeA, self.nodeA, source_port=a_out, target_port=a_out))
+        # 默认: node->node / right->left / left->right 允许
+        self.assertIsNotNone(self.canvas.addConnection(self.nodeA, self.nodeA))
+        # right->left 与 left->right 是两条独立边, 各自可创建(不互相去重)
+        rl = self.canvas.addConnection(self.nodeA, self.nodeA, source_port=a_out, target_port=a_in)
+        lr = self.canvas.addConnection(self.nodeA, self.nodeA, source_port=a_in, target_port=a_out)
+        self.assertIsNotNone(rl)
+        self.assertIsNotNone(lr)
+        self.assertIsNot(rl, lr)  # 两条独立连线
+        self.assertEqual(len(self.canvas.connections), 3)
+
+        # 开启其余三类, 验证可创建
+        self.nodeA.selfrefs["node->port"] = True
+        self.nodeA.selfrefs["port->node"] = True
+        self.nodeA.selfrefs["port->port"] = True
+        self.assertIsNotNone(self.canvas.addConnection(self.nodeA, self.nodeA, target_port=a_in))
+        self.assertIsNotNone(self.canvas.addConnection(self.nodeA, self.nodeA, source_port=a_out))
+        self.assertIsNotNone(self.canvas.addConnection(self.nodeA, self.nodeA, source_port=a_out, target_port=a_out))
+
+        # 关闭 node->node 不影响已创建, 但阻止新建
+        self.nodeA.selfrefs["node->node"] = False
+        self.assertIsNone(self.canvas.addConnection(self.nodeA, self.nodeA))
+
+        # 仅关闭 right->left: 该方向被拒, left->right 仍可(dedup 命中已存在的 lr)
+        self.nodeA.selfrefs["right->left"] = False
+        self.assertIsNone(self.canvas.addConnection(self.nodeA, self.nodeA, source_port=a_out, target_port=a_in))
+
+        # 全部自指都应渲染为环(isSelfLoop)
+        for c in self.canvas.connections:
+            if c.sourceNode is c.targetNode:
+                self.assertTrue(c.isSelfLoop())
+
+    def testLinkablesDefaults(self) -> None:
+        """linkables: 默认值 = 既有逻辑(7 键齐全, 同极 port 禁止)"""
+        from chartflow.node.node_canvas import _LINKABLES_DEFAULTS
+        self.assertEqual(self.canvas.linkables, {
+            "node->node": True,
+            "node->port": True,
+            "port->node": True,
+            "left->right": True,
+            "right->left": True,
+            "left->left": False,
+            "right->right": False,
+        })
+        # 返回内部 dict(非副本): 直接改值立即生效, 但不自动清理
+        self.assertIs(self.canvas.linkables, self.canvas._linkables)
+        self.assertEqual(self.canvas.linkables, _LINKABLES_DEFAULTS)
+
+    def testLinkablesBlocksCreation(self) -> None:
+        """关闭某 linkables 键后, 对应跨节点连接无法新建"""
+        self.nodeA.ports = {"left": [QNodePortSpec(name="in")], "right": [QNodePortSpec(name="out")]}
+        self.nodeB.ports = {"left": [QNodePortSpec(name="in")], "right": [QNodePortSpec(name="out")]}
+        a_out = self.nodeA._port_items["right"][0]
+        b_in = self.nodeB._port_items["left"][0]
+        a_in = self.nodeA._port_items["left"][0]
+        b_out = self.nodeB._port_items["right"][0]
+
+        # 默认: node->node / right->left / left->right 允许, 同极禁止
+        self.assertIsNotNone(self.canvas.addConnection(self.nodeA, self.nodeB))
+        self.assertIsNotNone(self.canvas.addConnection(
+            self.nodeA, self.nodeB, source_port=a_out, target_port=b_in))
+        # 关闭 node->node: 阻止新建(已存在的不受影响)
+        self.canvas.setLinkables(node__node=False)
+        self.assertIsNone(self.canvas.addConnection(self.nodeB, self.nodeC))
+        # 恢复, 再关闭 right->left: 阻止新建 right->left
+        self.canvas.setLinkables(node__node=True, right__left=False)
+        self.assertIsNone(self.canvas.addConnection(
+            self.nodeB, self.nodeC, source_port=b_out, target_port=a_in))
+        # left->right 仍允许(默认 True)
+        self.assertIsNotNone(self.canvas.addConnection(
+            self.nodeB, self.nodeC, source_port=b_in, target_port=a_out))
+
+    def testLinkablesEnforceRemovesConnections(self) -> None:
+        """整体赋值/部分修改 linkables 后, 已存在的不合规连接被自动移除"""
+        self.nodeA.ports = {"left": [QNodePortSpec(name="in")], "right": [QNodePortSpec(name="out")]}
+        self.nodeB.ports = {"left": [QNodePortSpec(name="in")], "right": [QNodePortSpec(name="out")]}
+        a_out = self.nodeA._port_items["right"][0]
+        b_in = self.nodeB._port_items["left"][0]
+
+        nn = self.canvas.addConnection(self.nodeA, self.nodeB)
+        rl = self.canvas.addConnection(self.nodeA, self.nodeB,
+                                       source_port=a_out, target_port=b_in)
+        self.assertEqual(len(self.canvas.connections), 2)
+
+        # 整体赋值关闭 node->node: enforceLinkables 应移除 nn, 保留 rl
+        self.canvas.linkables = {"node->node": False}
+        self.assertEqual(len(self.canvas.connections), 1)
+        self.assertIn(rl, self.canvas.connections)
+        self.assertNotIn(nn, self.canvas.connections)
+
+        # 直接改内部 dict(不触发清理): 连接仍在; 手动 enforce 后才移除。
+        # rl 是 right->left(a_out→b_in), 故关闭 right->left 使其违规。
+        self.canvas.linkables["right->left"] = False
+        self.assertEqual(len(self.canvas.connections), 1)
+        removed = self.canvas.enforceLinkables()
+        self.assertEqual(len(self.canvas.connections), 0)
+        self.assertIn(rl, removed)
+
+    def testLinkablesDoesNotAffectSelfRefs(self) -> None:
+        """linkables 只管跨节点; 同节点自指不受 linkables 影响"""
+        self.nodeA.ports = {"left": [QNodePortSpec(name="in")], "right": [QNodePortSpec(name="out")]}
+        a_in = self.nodeA._port_items["left"][0]
+        a_out = self.nodeA._port_items["right"][0]
+        # 全部 linkables 关闭
+        self.canvas.linkables = {k: False for k in self.canvas.linkables}
+        # 同节点自指仍由 selfrefs 控制(默认 node->node / left->right / right->left 允许)
+        self.assertIsNotNone(self.canvas.addConnection(self.nodeA, self.nodeA))
+        self.assertIsNotNone(self.canvas.addConnection(
+            self.nodeA, self.nodeA, source_port=a_out, target_port=a_in))
+        # enforceLinkables 不会动自指连线
+        self.canvas.enforceLinkables()
+        self.assertEqual(len(self.canvas.connections), 2)
+
+    def testLinkablesValidation(self) -> None:
+        """未知键 / 类型错误应抛错"""
+        with self.assertRaises(KeyError):
+            self.canvas.linkables = {"bogus": True}
+        with self.assertRaises(TypeError):
+            self.canvas.linkables = {"node->node": "yes"}
+        with self.assertRaises(KeyError):
+            self.canvas.setLinkables(unknown__key=True)
+
+    def testLinkablesRoundTrip(self) -> None:
+        """linkables 经 export/import 往返(仅差异项序列化)"""
+        self.canvas.linkables = {"left->left": True, "node->node": False}
+        data = self.canvas.export()
+        self.assertEqual(data.get("linkables"), {"left->left": True, "node->node": False})
+
+        self.canvas.clear()
+        self.canvas.importData(data)
+        self.assertTrue(self.canvas.linkables["left->left"])
+        self.assertFalse(self.canvas.linkables["node->node"])
+        # 未序列化的键取默认值
+        self.assertTrue(self.canvas.linkables["right->left"])
+        self.assertFalse(self.canvas.linkables["right->right"])
+
+    def testDragTargetArrowCreatesNewConnection(self) -> None:
+        """测试拖拽目标端箭头创建新连接"""
+        # 创建 A -> B 的单向连接
+        conn = self.canvas.addConnection(self.nodeA, self.nodeB)
+        self.assertEqual(len(self.canvas.connections), 1)
+
+        # 获取目标箭头（从A指向B的箭头）
+        arrow = conn.targetArrow
+
+        # 设置箭头拖拽状态（模拟拖拽开始）
+        arrow._is_dragging = True
+        drag_pos = self.nodeC.sceneBoundingRect().center()
+
+        self.canvas._onArrowDragStarted(drag_pos)
+
+        # 验证临时连接线已创建
+        self.assertIsNotNone(self.canvas._temp_new_connection)
+        self.assertEqual(self.canvas._dragged_arrow, arrow)
+        self.assertEqual(self.canvas._original_connection, conn)
+
+        # 模拟拖拽移动
+        self.canvas._onArrowDragMoved(drag_pos)
+
+        # 模拟拖拽结束到NodeC
+        self.canvas._onArrowDragFinished(drag_pos, is_success=True)
+
+        # 验证新连接已创建 A -> C
+        self.assertEqual(len(self.canvas.connections), 1)
+        new_conn = self.canvas.connections[0]
+        self.assertEqual(new_conn.sourceNode, self.nodeA)
+        self.assertEqual(new_conn.targetNode, self.nodeC)
+
+    def testDragSourceArrowCreatesNewConnection(self) -> None:
+        """测试拖拽源端箭头创建新连接（双向连接情况）"""
+        # 创建 A <-> B 的双向连接
+        conn = self.canvas.addConnection(self.nodeA, self.nodeB, is_bidirectional=True)
+        self.assertEqual(len(self.canvas.connections), 1)
+
+        # 获取源端箭头（从B指向A的箭头）
+        source_arrow = conn.sourceArrow
+        self.assertIsNotNone(source_arrow)
+
+        # 设置箭头拖拽状态（模拟拖拽开始）
+        source_arrow._is_dragging = True
+        drag_pos = self.nodeC.sceneBoundingRect().center()
+        self.canvas._onArrowDragStarted(drag_pos)
+
+        # 验证状态已设置
+        self.assertEqual(self.canvas._dragged_arrow, source_arrow)
+        self.assertEqual(self.canvas._original_connection, conn)
+        self.assertTrue(self.canvas._original_is_bidirectional)
+        self.assertIsNotNone(self.canvas._temp_new_connection)
+
+        # 模拟拖拽结束到NodeC
+        self.canvas._onArrowDragFinished(drag_pos, is_success=True)
+
+        # 验证：原连接变为单向 A -> B
+        # 新连接创建 B -> C
+        self.assertEqual(len(self.canvas.connections), 2)
+
+        # 检查连接：应该有 A->B 和 B->C
+        a_to_b = [c for c in self.canvas.connections
+                  if c.sourceNode == self.nodeA and c.targetNode == self.nodeB]
+        b_to_c = [c for c in self.canvas.connections
+                  if c.sourceNode == self.nodeB and c.targetNode == self.nodeC]
+        self.assertEqual(len(a_to_b), 1)
+        self.assertEqual(len(b_to_c), 1)
+        self.assertFalse(a_to_b[0].isBidirectional)
+
+    def testDragArrowToSameTargetNoChange(self) -> None:
+        """测试拖拽箭头到相同目标不创建新连接"""
+        # 创建 A -> B 连接
+        conn = self.canvas.addConnection(self.nodeA, self.nodeB)
+        self.assertEqual(len(self.canvas.connections), 1)
+
+        # 获取目标箭头
+        arrow = conn.targetArrow
+
+        # 设置箭头拖拽状态（模拟拖拽开始）
+        arrow._is_dragging = True
+        drag_pos = self.nodeB.sceneBoundingRect().center()
+        self.canvas._onArrowDragStarted(drag_pos)
+
+        # 模拟拖拽结束到同一目标
+        self.canvas._onArrowDragFinished(drag_pos, is_success=True)
+
+        # 验证：连接数量不变，原连接保持不变
+        self.assertEqual(len(self.canvas.connections), 1)
+        self.assertEqual(self.canvas.connections[0], conn)
+        self.assertEqual(conn.sourceNode, self.nodeA)
+        self.assertEqual(conn.targetNode, self.nodeB)
+
+    def testDragArrowToSameNodeFlashError(self) -> None:
+        """测试拖拽箭头到源节点本身触发错误闪烁"""
+        # 创建 A -> B 连接
+        conn = self.canvas.addConnection(self.nodeA, self.nodeB)
+
+        # 获取目标箭头
+        arrow = conn.targetArrow
+
+        # 设置箭头拖拽状态（模拟拖拽开始）
+        arrow._is_dragging = True
+        drag_pos = self.nodeA.sceneBoundingRect().center()
+        self.canvas._onArrowDragStarted(drag_pos)
+
+        # 模拟拖拽结束到源节点（自身）
+        self.canvas._onArrowDragFinished(drag_pos, is_success=True)
+
+        # 验证：连接数量不变，原连接保持不变
+        self.assertEqual(len(self.canvas.connections), 1)
+
+    def testDragArrowFailureFlashError(self) -> None:
+        """测试拖拽失败触发错误闪烁"""
+        # 创建 A -> B 连接
+        conn = self.canvas.addConnection(self.nodeA, self.nodeB)
+
+        # 获取目标箭头
+        arrow = conn.targetArrow
+
+        # 设置箭头拖拽状态（模拟拖拽开始）
+        arrow._is_dragging = True
+        drag_pos = QPointF(1000, 1000)  # 远离所有节点的位置
+        self.canvas._onArrowDragStarted(drag_pos)
+
+        # 模拟拖拽失败
+        self.canvas._onArrowDragFinished(drag_pos, is_success=False)
+
+        # 验证状态已重置
+        self.assertIsNone(self.canvas._dragged_arrow)
+        self.assertIsNone(self.canvas._original_connection)
+
+    def testBidirectionalToUnidirectionalConversion(self) -> None:
+        """测试双向连接拖拽后转换为单向连接"""
+        # 创建 A <-> B 的双向连接
+        conn = self.canvas.addConnection(self.nodeA, self.nodeB, is_bidirectional=True)
+        self.assertTrue(conn.isBidirectional)
+        self.assertEqual(len(self.canvas.connections), 1)
+
+        # 获取目标箭头（A->B）
+        target_arrow = conn.targetArrow
+
+        # 设置箭头拖拽状态（模拟拖拽开始）
+        target_arrow._is_dragging = True
+        drag_pos = self.nodeC.sceneBoundingRect().center()
+        self.canvas._onArrowDragStarted(drag_pos)
+
+        # 验证状态已设置
+        self.assertEqual(self.canvas._dragged_arrow, target_arrow)
+        self.assertTrue(self.canvas._original_is_bidirectional)
+
+        # 模拟拖拽结束
+        self.canvas._onArrowDragFinished(drag_pos, is_success=True)
+
+        # 验证：原连接变为 B -> A（单向）
+        # 新连接 A -> C 创建
+        self.assertEqual(len(self.canvas.connections), 2)
+
+        # 找到 B -> A 的连接
+        b_to_a = [c for c in self.canvas.connections
+                  if c.sourceNode == self.nodeB and c.targetNode == self.nodeA]
+        self.assertEqual(len(b_to_a), 1)
+        self.assertFalse(b_to_a[0].isBidirectional)
+
+        # 找到 A -> C 的连接
+        a_to_c = [c for c in self.canvas.connections
+                  if c.sourceNode == self.nodeA and c.targetNode == self.nodeC]
+        self.assertEqual(len(a_to_c), 1)
+
+    def testDuplicateConnectionWithCheckPartnersFalse(self) -> None:
+        """测试已存在连接时addConnection返回已存在连接"""
+        # 创建 A -> B 连接
+        conn1 = self.canvas.addConnection(self.nodeA, self.nodeB)
+        self.assertIsNotNone(conn1)
+
+        # 尝试再次创建 A -> B，即使 check_partners=False 也应该返回已存在的连接
+        conn2 = self.canvas.addConnection(self.nodeA, self.nodeB, check_partners=False)
+        self.assertEqual(conn1, conn2)
+
+    def testDragArrowToExistingConnectionArrow(self) -> None:
+        """测试拖拽箭头到已存在连接的箭头上（不删除原连接）"""
+        # 创建 A -> B 和 A -> C 两个连接
+        conn_ab = self.canvas.addConnection(self.nodeA, self.nodeB)
+        conn_ac = self.canvas.addConnection(self.nodeA, self.nodeC)
+        self.assertEqual(len(self.canvas.connections), 2)
+        self.assertIn(conn_ab, self.canvas.connections)
+        self.assertIn(conn_ac, self.canvas.connections)
+
+        # 获取 A->B 的目标箭头
+        arrow_ab = conn_ab.targetArrow
+
+        # 拖拽 A->B 的箭头到 C 节点
+        arrow_ab._is_dragging = True
+        drag_pos = self.nodeC.sceneBoundingRect().center()
+        self.canvas._onArrowDragStarted(drag_pos)
+
+        # 验证临时连接线已创建
+        self.assertIsNotNone(self.canvas._temp_new_connection)
+
+        # 模拟拖拽结束到C节点（A->C已存在）
+        self.canvas._onArrowDragFinished(drag_pos, is_success=True)
+
+        # 验证：两个连接都应该仍然存在
+        self.assertEqual(len(self.canvas.connections), 2)
+        self.assertIn(conn_ab, self.canvas.connections)
+        self.assertIn(conn_ac, self.canvas.connections)
+
+        # 验证 A->B 连接没有被删除
+        self.assertEqual(conn_ab.sourceNode, self.nodeA)
+        self.assertEqual(conn_ab.targetNode, self.nodeB)
+
+    def testBidirectionalSourceArrowHasCallbacks(self) -> None:
+        """测试双向连接的 source_arrow 有拖拽回调"""
+        # 创建 A -> B 连接
+        conn = self.canvas.addConnection(self.nodeA, self.nodeB)
+
+        # 创建 B -> A 连接，使 A<->B 成为双向连接
+        # 注意：addConnection 会返回已存在的连接（现在变为双向）
+        conn2 = self.canvas.addConnection(self.nodeB, self.nodeA)
+
+        # 验证是同一个连接且已变为双向
+        self.assertEqual(conn, conn2)
+        self.assertTrue(conn.isBidirectional)
+
+        # 获取 source_arrow（从 B 指向 A 的箭头）
+        source_arrow = conn.sourceArrow
+        self.assertIsNotNone(source_arrow)
+
+        # 验证 source_arrow 有拖拽回调
+        self.assertIsNotNone(source_arrow._drag_started_callback)
+        self.assertIsNotNone(source_arrow._drag_moved_callback)
+        self.assertIsNotNone(source_arrow._drag_finished_callback)
+
+    def testDragBidirectionalSourceArrow(self) -> None:
+        """测试拖拽双向连接的 source_arrow（从 B 指向 A 的箭头）到 C"""
+        # 创建双向连接 A<->B
+        conn = self.canvas.addConnection(self.nodeA, self.nodeB, is_bidirectional=True)
+        self.assertTrue(conn.isBidirectional)
+        self.assertEqual(len(self.canvas.connections), 1)
+
+        # 获取 source_arrow（从 B 指向 A 的箭头）
+        source_arrow = conn.sourceArrow
+        self.assertIsNotNone(source_arrow)
+        self.assertTrue(source_arrow.isSourceArrow)
+
+        # 验证回调已设置
+        self.assertIsNotNone(source_arrow._drag_started_callback)
+
+        # 拖拽 source_arrow 到 C
+        source_arrow._is_dragging = True
+        drag_pos = self.nodeC.sceneBoundingRect().center()
+        self.canvas._onArrowDragStarted(drag_pos)
+
+        # 验证临时连接线已创建
+        self.assertIsNotNone(self.canvas._temp_new_connection)
+        self.assertEqual(self.canvas._dragged_arrow, source_arrow)
+
+        # 模拟拖拽结束到C节点
+        self.canvas._onArrowDragFinished(drag_pos, is_success=True)
+
+        # 验证：应该有两个连接：A->B 和 B->C
+        # 原双向连接 A<->B 变为单向 A->B，新连接 B->C 创建
+        self.assertEqual(len(self.canvas.connections), 2)
+
+        # 验证 B->C 连接已创建（source_arrow 起点是 B）
+        b_to_c = [c for c in self.canvas.connections
+                  if c.sourceNode == self.nodeB and c.targetNode == self.nodeC]
+        self.assertEqual(len(b_to_c), 1)
+
+
+class TestConnectionTypes(unittest.TestCase):
+    """测试不同连接类型"""
+
+    @classmethod
+    def setUpClass(cls) -> None:
+        """设置测试类"""
+        cls.app = QApplication.instance()
+        if cls.app is None:
+            cls.app = QApplication(sys.argv)
+
+    def setUp(self) -> None:
+        """设置每个测试"""
+        self.scene = QGraphicsScene()
+        self.source_node = QNodeItem("Source", QPointF(0, 0))
+        self.target_node = QNodeItem("Target", QPointF(200, 0))
+        self.scene.addItem(self.source_node)
+        self.scene.addItem(self.target_node)
+
+    def tearDown(self) -> None:
+        """清理每个测试"""
+        self.scene.clear()
+
+    def testBezierConnection(self) -> None:
+        """测试贝塞尔曲线连接"""
+        connection = ConnectionItem(
+            self.source_node, self.target_node,
+            connection_type=ConnectionType.BEZIER
+        )
+        self.scene.addItem(connection)
+        self.scene.addItem(connection.targetArrow)
+        
+        self.assertEqual(connection.connectionType, ConnectionType.BEZIER)
+        
+        connection.removeArrows()
+        self.scene.removeItem(connection)
+    
+    def testStraightConnection(self) -> None:
+        """测试直线连接"""
+        connection = ConnectionItem(
+            self.source_node, self.target_node,
+            connection_type=ConnectionType.STRAIGHT
+        )
+        self.scene.addItem(connection)
+        self.scene.addItem(connection.targetArrow)
+        
+        self.assertEqual(connection.connectionType, ConnectionType.STRAIGHT)
+        
+        connection.removeArrows()
+        self.scene.removeItem(connection)
+
+
+class TestDecorator(unittest.TestCase):
+    """测试装饰器节点边框颜色"""
+
+    @classmethod
+    def setUpClass(cls) -> None:
+        """设置测试类"""
+        cls.app = QApplication.instance()
+        if cls.app is None:
+            cls.app = QApplication(sys.argv)
+
+    def setUp(self) -> None:
+        """设置每个测试"""
+        self.scene = QGraphicsScene()
+        self.node = QNodeItem("TestNode", QPointF(100, 100))
+        self.scene.addItem(self.node)
+
+    def tearDown(self) -> None:
+        """清理每个测试"""
+        self.scene.clear()
+
+    def testDecoratorProperty(self) -> None:
+        """测试装饰器属性"""
+        # 初始状态应该没有装饰器
+        self.assertIsNone(self.node.decorator)
+
+        # 设置 recursive 装饰器
+        self.node.decorator = "recursive"
+        self.assertEqual(self.node.decorator, "recursive")
+
+        # 设置 behavior 装饰器
+        self.node.decorator = "behavior"
+        self.assertEqual(self.node.decorator, "behavior")
+
+        # 清除装饰器
+        self.node.decorator = None
+        self.assertIsNone(self.node.decorator)
+
+    def testRecursiveDecoratorColor(self) -> None:
+        """测试 recursive 装饰器返回紫罗兰色"""
+        self.node.decorator = "recursive"
+        color = self.node._getDecoratorStrokeColor()
+
+        self.assertIsNotNone(color)
+        # 紫罗兰色: RGB(238, 130, 238)
+        self.assertEqual(color.red(), 238)
+        self.assertEqual(color.green(), 130)
+        self.assertEqual(color.blue(), 238)
+
+    def testBehaviorDecoratorColor(self) -> None:
+        """测试 behavior 装饰器返回皇家蓝色"""
+        self.node.decorator = "behavior"
+        color = self.node._getDecoratorStrokeColor()
+
+        self.assertIsNotNone(color)
+        # 皇家蓝色: RGB(65, 105, 225)
+        self.assertEqual(color.red(), 65)
+        self.assertEqual(color.green(), 105)
+        self.assertEqual(color.blue(), 225)
+
+    def testSequenceDecoratorColor(self) -> None:
+        """测试 sequence 装饰器返回皇家蓝色"""
+        self.node.decorator = "sequence"
+        color = self.node._getDecoratorStrokeColor()
+        self.assertIsNotNone(color)
+
+    def testSelectorDecoratorColor(self) -> None:
+        """测试 selector 装饰器返回皇家蓝色"""
+        self.node.decorator = "selector"
+        color = self.node._getDecoratorStrokeColor()
+        self.assertIsNotNone(color)
+
+    def testParallelDecoratorColor(self) -> None:
+        """测试 parallel 装饰器返回皇家蓝色"""
+        self.node.decorator = "parallel"
+        color = self.node._getDecoratorStrokeColor()
+        self.assertIsNotNone(color)
+
+    def testNoDecoratorReturnsNone(self) -> None:
+        """测试无装饰器时返回 None"""
+        color = self.node._getDecoratorStrokeColor()
+        self.assertIsNone(color)
+
+    def testUnknownDecoratorReturnsNone(self) -> None:
+        """测试未知装饰器返回 None"""
+        self.node.decorator = "unknown"
+        color = self.node._getDecoratorStrokeColor()
+        self.assertIsNone(color)
+
+    def testDecoratorCaseInsensitive(self) -> None:
+        """测试装饰器类型不区分大小写"""
+        # 大写的 RECURSIVE
+        self.node.decorator = "RECURSIVE"
+        color = self.node._getDecoratorStrokeColor()
+        self.assertIsNotNone(color)
+
+        # 混合大小写的 Behavior
+        self.node.decorator = "Behavior"
+        color = self.node._getDecoratorStrokeColor()
+        self.assertIsNotNone(color)
+
+
+class TestPorts(unittest.TestCase):
+    """测试节点端口(ports)属性字段"""
+
+    @classmethod
+    def setUpClass(cls) -> None:
+        cls.app = QApplication.instance()
+        if cls.app is None:
+            cls.app = QApplication(sys.argv)
+
+    def setUp(self) -> None:
+        self.scene = QGraphicsScene()
+        self.node = QNodeItem("Counter", QPointF(0, 0), NodeShape.RECTANGLE)
+        self.scene.addItem(self.node)
+
+    def tearDown(self) -> None:
+        self.scene.clear()
+
+    def _assignSamplePorts(self) -> None:
+        self.node.ports = {
+            "left": [
+                QNodePortSpec(name="clk", shape="triangle", size=10, hit="1"),
+                QNodePortSpec(name="data", shape="trapezoid", size=12, hit="16",
+                          label="data[15:0]"),
+            ],
+            "right": [
+                QNodePortSpec(name="out", shape="circle", size=10, hit="1"),
+                QNodePortSpec(name="flag", shape="square", size=10),
+            ],
+        }
+
+    def testPortsDefaultEmpty(self) -> None:
+        """默认 ports 为空字典(left/right)"""
+        self.assertEqual(self.node.ports, {"left": [], "right": []})
+
+    def testPortsAssignmentBuildsItems(self) -> None:
+        """赋值后按 left/right 构建渲染项"""
+        self._assignSamplePorts()
+        self.assertEqual(len(self.node._port_items["left"]), 2)
+        self.assertEqual(len(self.node._port_items["right"]), 2)
+
+    def testPortsPositionedOnEdges(self) -> None:
+        """端口锚点落在节点左右边缘上"""
+        self._assignSamplePorts()
+        rect = self.node.rect()
+        for it in self.node._port_items["left"]:
+            self.assertAlmostEqual(it.pos().x(), rect.left())
+        for it in self.node._port_items["right"]:
+            self.assertAlmostEqual(it.pos().x(), rect.right())
+
+    def testLabelDefaultsToName(self) -> None:
+        """label 未指定时默认等同 name"""
+        self._assignSamplePorts()
+        clk = self.node._port_items["left"][0]
+        self.assertIsNotNone(clk._label_item)
+        self.assertEqual(clk._label_item.toPlainText(), "clk")
+        # 默认隐藏
+        self.assertFalse(clk._label_item.isVisible())
+
+    def testLabelExplicitValue(self) -> None:
+        """显式 label 优先于 name"""
+        self._assignSamplePorts()
+        data = self.node._port_items["left"][1]
+        self.assertEqual(data._label_item.toPlainText(), "data[15:0]")
+
+    def testShowAllLabelsToggle(self) -> None:
+        """节点级显示/隐藏全部 label(断言逻辑目标态; 实际可见受动画时序影响)"""
+        self._assignSamplePorts()
+        self.node._setAllPortsShowAll(True)
+        for it in self.node._port_items["left"] + self.node._port_items["right"]:
+            # 显示是立即 show(), item 可见且逻辑态为真
+            self.assertTrue(it._label_item.isVisible())
+            self.assertTrue(it._label_visible)
+        self.node._setAllPortsShowAll(False)
+        for it in self.node._port_items["left"] + self.node._port_items["right"]:
+            # 隐藏走淡出动画, 逻辑态立即翻转(动画结束后才真正 hide)
+            self.assertFalse(it._label_visible)
+
+    def testDotHoverShowsOnlyThatDot(self) -> None:
+        """悬停某个 dot 时只显示该 dot 的 label, 不触发显示全部
+
+        断言逻辑目标态(_label_visible); 实际可见性受动画时序影响。
+        """
+        self._assignSamplePorts()
+        clk = self.node._port_items["left"][0]
+        other = self.node._port_items["right"][0]
+        # 模拟节点已 hover 且 show-all 已开启
+        self.node._node_hovered = True
+        self.node._setAllPortsShowAll(True)
+        self.assertTrue(other._label_visible)
+        # 悬停 clk -> 只剩 clk
+        clk._hovered = True
+        clk._solo = True
+        clk._updateLabelVisible()
+        self.node._onPortHoverEnter(clk)
+        self.assertTrue(clk._label_visible)   # solo
+        self.assertFalse(other._label_visible)  # 被收起
+        # 离开 clk -> 计时恢复(此处直接验证计数回落)
+        clk._hovered = False
+        clk._solo = False
+        clk._updateLabelVisible()
+        self.node._onPortHoverLeave(clk)
+        self.assertEqual(self.node._hovered_port_count, 0)
+
+    def testHitTextCreated(self) -> None:
+        """hit 文本被创建"""
+        self._assignSamplePorts()
+        self.assertIsNotNone(self.node._port_items["left"][0]._hit_item)
+
+    def testInvalidShapeRejected(self) -> None:
+        """非法 shape 抛出 ValueError"""
+        with self.assertRaises(ValueError):
+            self.node.ports = {"left": [QNodePortSpec(name="x", shape="hexagon")],
+                               "right": []}
+
+    def testDictCoercion(self) -> None:
+        """dict 元素自动转换为 QNodePortSpec"""
+        self.node.ports = {"left": [{"name": "d", "shape": "circle",
+                                     "size": 8, "hit": "2"}],
+                           "right": []}
+        self.assertIsInstance(self.node.ports["left"][0], QNodePortSpec)
+        self.assertEqual(self.node.ports["left"][0].name, "d")
+
+    def testRoundTrip(self) -> None:
+        """toDict/fromDict 端口往返"""
+        self._assignSamplePorts()
+        data = self.node.toDict()
+        self.assertIn("ports", data)
+        other = QNodeItem("X", QPointF(0, 0))
+        other.fromDict(data)
+        self.assertEqual(len(other.ports["left"]), 2)
+        self.assertEqual(other.ports["left"][0].name, "clk")
+
+    def testReassignTeardown(self) -> None:
+        """重新赋值会移除旧端口项"""
+        self._assignSamplePorts()
+        self.node.ports = {"left": [], "right": []}
+        self.assertEqual(self.node._port_items["left"], [])
+        self.assertEqual(self.node._port_items["right"], [])
+
+    def testClicksPassThrough(self) -> None:
+        """端口不拦截鼠标按键(点击穿透回节点)"""
+        from PyQt6.QtCore import Qt
+        self._assignSamplePorts()
+        for it in self.node._port_items["left"] + self.node._port_items["right"]:
+            self.assertEqual(it.acceptedMouseButtons(), Qt.MouseButton.NoButton)
+
+    def testPortsRelayoutOnRadiusChange(self) -> None:
+        """节点改半径后端口锚点跟随新边缘"""
+        self._assignSamplePorts()
+        old_left_x = self.node._port_items["left"][0].pos().x()
+        self.node.setRadius(self.node.radius * 2)
+        new_left_x = self.node._port_items["left"][0].pos().x()
+        self.assertNotAlmostEqual(old_left_x, new_left_x)
+        self.assertAlmostEqual(new_left_x, self.node.rect().left())
+
+    def testFromDictWithCustomRadiusRelayoutsPorts(self) -> None:
+        """fromDict 同时加载端口与自定义半径时端口位置正确"""
+        self._assignSamplePorts()
+        data = self.node.toDict()
+        data.setdefault("style", {})["radius"] = self.node.radius * 2.5
+        other = QNodeItem("Y", QPointF(0, 0), NodeShape.RECTANGLE)
+        other.fromDict(data)
+        for it in other._port_items["left"]:
+            self.assertAlmostEqual(it.pos().x(), other.rect().left())
+
+    def testRectangleWithPortsNonSquareAndPacked(self) -> None:
+        """矩形+多端口: 长宽可不等; 端口紧凑不重叠(>=5px), 不压圆角"""
+        self.node.ports = {
+            "left": [QNodePortSpec(name=f"in{i}", shape="trapezoid", size=14,
+                               hit="") for i in range(5)],
+            "right": [],
+        }
+        rect = self.node.rect()
+        half_h = rect.height() / 2
+        corner = min(rect.width(), rect.height()) * 0.2
+
+        # 端口很多(无 hit 撑宽) -> 高度由端口决定, 高于宽度
+        self.assertGreaterEqual(rect.height(), rect.width() - 1e-6)
+
+        ordered = sorted(self.node._port_items["left"], key=lambda it: it.pos().y())
+        # 相邻端口边缘间距 >= 5px
+        for a, b in zip(ordered, ordered[1:]):
+            gap = (b.pos().y() - b.spec.size / 2) - (a.pos().y() + a.spec.size / 2)
+            self.assertGreaterEqual(gap, 5.0 - 1e-6)
+        # 上下端口不进入圆角区域
+        top_edge = ordered[0].pos().y() - ordered[0].spec.size / 2
+        bot_edge = ordered[-1].pos().y() + ordered[-1].spec.size / 2
+        self.assertGreaterEqual(top_edge, -(half_h - corner) - 1e-6)
+        self.assertLessEqual(bot_edge, (half_h - corner) + 1e-6)
+
+    def testHitTextAddsWidth(self) -> None:
+        """有 hit 文本时, 节点宽度比无 hit 时更大(为 hit 预留空间)"""
+        base = QNodeItem("M", QPointF(0, 0), NodeShape.RECTANGLE)
+        base.ports = {"left": [QNodePortSpec(name="a", shape="trapezoid",
+                                         size=14, hit="")], "right": []}
+        w_no_hit = base.rect().width()
+
+        with_hit = QNodeItem("M", QPointF(0, 0), NodeShape.RECTANGLE)
+        with_hit.ports = {"left": [QNodePortSpec(name="a", shape="trapezoid",
+                                             size=14, hit="16")], "right": []}
+        w_hit = with_hit.rect().width()
+        self.assertGreater(w_hit, w_no_hit)
+
+    def testHitCloserThanLabel(self) -> None:
+        """hit 紧贴 dot(间距小), label 在外侧(间距大)"""
+        self._assignSamplePorts()
+        it = self.node._port_items["left"][0]   # left: dot 在边界, 向内 +x
+        depth = it._depth()
+        # hit 在 dot 内侧, 距边界 depth + HIT_GAP
+        hit_x = it._hit_item.pos().x()
+        from chartflow.node.port_item import HIT_GAP, LABEL_GAP
+        self.assertAlmostEqual(hit_x, depth + HIT_GAP, delta=1e-6)
+        self.assertLess(HIT_GAP, LABEL_GAP)
+
+    def testEllipseAlwaysPerfectCircle(self) -> None:
+        """椭圆(圆形)节点固定为标准圆: 任何尺寸操作后宽高相等"""
+        node = QNodeItem("DSP", QPointF(0, 0), NodeShape.ELLIPSE)
+        self.scene.addItem(node)
+        node.ports = {
+            "left": [QNodePortSpec(name="a", shape="triangle", size=10, hit="1"),
+                     QNodePortSpec(name="b", shape="trapezoid", size=14, hit="16")],
+            "right": [QNodePortSpec(name="o", shape="circle", size=12, hit="8")],
+        }
+        r = node.rect()
+        self.assertEqual(r.width(), r.height())
+
+        # 即使强行传入不等宽高, 也被校正为圆
+        node._setSize(120.0, 60.0)
+        r = node.rect()
+        self.assertEqual(r.width(), r.height())
+        self.assertAlmostEqual(r.width(), 240.0)  # 取较大者 -> 直径 240
+
+        # setRadius 后仍为圆
+        node.setRadius(70)
+        r = node.rect()
+        self.assertEqual(r.width(), r.height())
+        self.assertAlmostEqual(r.width(), 140.0)
+
+        # 改名/改字号后仍为圆
+        node.name = "a very long node name"
+        node.setFont(size=16)
+        r = node.rect()
+        self.assertEqual(r.width(), r.height())
+
+    def testRectangleToEllipseBecomesCircle(self) -> None:
+        """矩形(带端口, 非方形)切换为椭圆后, 本体被校正为标准圆"""
+        node = QNodeItem("DSP", QPointF(0, 0), NodeShape.RECTANGLE)
+        self.scene.addItem(node)
+        node.ports = {
+            "left": [QNodePortSpec(name=f"d{i}", shape="trapezoid", size=14, hit="16")
+                     for i in range(6)],
+            "right": [],
+        }
+        # 矩形带端口 -> 非方形
+        self.assertNotEqual(node.rect().width(), node.rect().height())
+        # 切换为椭圆 -> 标准圆, 本体/选中区与环一致
+        node.nodeShape = NodeShape.ELLIPSE
+        r = node.rect()
+        self.assertEqual(r.width(), r.height())
+        # 端口变为径向
+        for it in node._port_items["left"]:
+            self.assertTrue(it._radial)
+
+    def testCirclePortsRadialOnArc(self) -> None:
+        """圆形节点: dot 落在圆上, apex 对准圆心, 分布在侧弧窗口内(避开极点), label 水平"""
+        import math
+        node = QNodeItem("circ", QPointF(0, 0), NodeShape.ELLIPSE)
+        self.scene.addItem(node)
+        node.ports = {
+            "left": [QNodePortSpec(name=f"L{i}", shape="trapezoid", size=12, hit="16")
+                     for i in range(4)],
+            "right": [QNodePortSpec(name=f"R{i}", shape="triangle", size=10, hit="1")
+                      for i in range(3)],
+        }
+        R = node.rect().width() / 2.0
+        c = node.rect().center()
+        from chartflow.node.node_item import CIRCLE_PORT_WINDOW_DEG
+        for side in ("left", "right"):
+            for it in node._port_items[side]:
+                self.assertTrue(it._radial)
+                p = it.pos()
+                d = math.hypot(p.x() - c.x(), p.y() - c.y())
+                self.assertAlmostEqual(d, R, delta=1e-3)          # 在圆上
+                ang = math.degrees(math.atan2(p.y() - c.y(), p.x() - c.x()))
+                center = 180.0 if side == "left" else 0.0
+                # 折算到 (-180,180], 距侧中心不超过窗口
+                off = (ang - center + 180.0) % 360.0 - 180.0
+                self.assertLessEqual(abs(off), CIRCLE_PORT_WINDOW_DEG + 1e-6)
+                # apex 方向应等于朝心方向
+                oa = math.radians(it._orient_angle)
+                apex = (math.cos(oa), math.sin(oa))
+                inward = (-(p.x() - c.x()) / d, -(p.y() - c.y()) / d)
+                self.assertAlmostEqual(apex[0], inward[0], delta=1e-6)
+                self.assertAlmostEqual(apex[1], inward[1], delta=1e-6)
+                # label 文本保持水平
+                self.assertEqual(it._label_item.rotation(), 0.0)
+
+    def testDiamondPortsOnFacet(self) -> None:
+        """菱形: dot 贴在左/右斜边上, _orient_angle = 该斜边内法线(垂直于斜边,
+        指向节点内部), 使旋转后底边贴合斜边; label 水平"""
+        import math
+        node = QNodeItem("dia", QPointF(0, 0), NodeShape.DIAMOND)
+        self.scene.addItem(node)
+        node.ports = {
+            "left": [QNodePortSpec(name=f"L{i}", shape="trapezoid", size=12, hit="16")
+                     for i in range(4)],
+            "right": [QNodePortSpec(name=f"R{i}", shape="triangle", size=10, hit="1")
+                      for i in range(3)],
+        }
+        rect = node.rect()
+        hw = rect.width() / 2.0
+        hh = rect.height() / 2.0
+        c = rect.center()
+        for side in ("left", "right"):
+            sgn = -1.0 if side == "left" else 1.0
+            for it in node._port_items[side]:
+                self.assertTrue(it._diamond)
+                self.assertFalse(it._radial)
+                p = it.pos()
+                # 1) 点必须在菱形斜边上: |x/hw| + |y/hh| == 1(在边界上)
+                denom_x = hw if hw > 0 else 1.0
+                denom_y = hh if hh > 0 else 1.0
+                boundary = abs(p.x() - c.x()) / denom_x + abs(p.y() - c.y()) / denom_y
+                self.assertAlmostEqual(boundary, 1.0, delta=1e-3)
+                # 2) 点位于正确侧: x 与 sgn 同号(右端口 x>0, 左端口 x<0)
+                self.assertGreater((p.x() - c.x()) * sgn, -1e-6)
+                # 3) _orient_angle 必须等于该点所在斜边的内法线(垂直于斜边)。
+                #    斜边内法线是常量: 由斜边方向旋转 90° 得到。
+                #    上半斜边(顶点->侧顶点): 右侧方向(hw,hh)内法线(-hh,hw);
+                #                            左侧方向(-hw,hh)内法线(hh,hw)
+                #    下半斜边(侧顶点->底顶点): 右侧方向(-hw,hh)内法线(-hh,-hw);
+                #                             左侧方向(hw,hh)内法线(hh,-hw)
+                upper = (p.y() - c.y()) < 0
+                if side == "right":
+                    ix, iy = (-hh, hw) if upper else (-hh, -hw)
+                else:
+                    ix, iy = (hh, hw) if upper else (hh, -hw)
+                nl = math.hypot(ix, iy)
+                expected_ang = math.degrees(math.atan2(iy / nl, ix / nl))
+                oa = it._orient_angle % 360.0
+                ea = expected_ang % 360.0
+                diff = min(abs(oa - ea), 360.0 - abs(oa - ea))
+                self.assertLess(diff, 1e-3)
+                # 4) 验证旋转后底边确实平行于斜边: 底边原为垂直(x=0), 旋转
+                #    _orient_angle 后方向 = (sin(ang), cos(ang)*-1)... 用法线检验:
+                #    dot 底边法线应平行于斜边内法线(即 _orient_angle 方向)
+                # 5) label 文本保持水平
+                self.assertEqual(it._label_item.rotation(), 0.0)
+        # 6) 所有端口都避开四个顶点: 距任一顶点 >= vertex_gap
+        vg = node._diamondVertexGap()
+        vertices = [QPointF(c.x(), c.y() - hh), QPointF(c.x() + hw, c.y()),
+                    QPointF(c.x(), c.y() + hh), QPointF(c.x() - hw, c.y())]
+        for side in ("left", "right"):
+            for it in node._port_items[side]:
+                p = it.pos()
+                for v in vertices:
+                    self.assertGreaterEqual(
+                        math.hypot(p.x() - v.x(), p.y() - v.y()), vg - 1e-6,
+                        f"端口 {it.spec.name} 过于靠近顶点 {v}")
+
+    def testDiamondPortsClusterTowardSide(self) -> None:
+        """菱形端口偏向侧顶点(左右两角): 端口组中心比物理中点更靠近侧顶点"""
+        import math
+        node = QNodeItem("dia", QPointF(0, 0), NodeShape.DIAMOND)
+        self.scene.addItem(node)
+        node.ports = {
+            "left": [QNodePortSpec(name=f"L{i}", shape="triangle", size=10, hit="1")
+                     for i in range(2)],
+            "right": [QNodePortSpec(name=f"R{i}", shape="triangle", size=10, hit="1")
+                      for i in range(2)],
+        }
+        c = node.rect().center()
+        for side in ("left", "right"):
+            sgn = -1.0 if side == "left" else 1.0
+            # 端口应偏向侧顶点: |x| 较大(靠近侧顶点 hw), 而非靠近垂直中线
+            for it in node._port_items[side]:
+                self.assertGreater(it.pos().x() * sgn, 1.0,
+                                   f"{side} 端口应偏向侧顶点而非中线")
+
+    def testDiamondPortEmissionDirection(self) -> None:
+        """菱形端口连线出射方向 = 该端口所在斜边的外法线(单位向量, 指向节点外)"""
+        import math
+        node = QNodeItem("dia", QPointF(0, 0), NodeShape.DIAMOND)
+        self.scene.addItem(node)
+        # 多端口: 保证每个端口明确落在某一条斜边上(非赤道顶点)
+        node.ports = {
+            "left": [QNodePortSpec(name=f"L{i}", shape="triangle", size=10, hit="1")
+                     for i in range(2)],
+            "right": [QNodePortSpec(name=f"R{i}", shape="triangle", size=10, hit="1")
+                      for i in range(2)],
+        }
+        rect = node.rect()
+        hw = rect.width() / 2.0
+        hh = rect.height() / 2.0
+        c = rect.center()
+        conn = ConnectionItem(node, node)  # 临时对象, 仅用于调用方法
+        for side in ("left", "right"):
+            for it in node._port_items[side]:
+                d = conn._portRadialDirection(it)
+                self.assertIsNotNone(d)
+                # 单位向量
+                self.assertAlmostEqual(math.hypot(d.x(), d.y()), 1.0, delta=1e-6)
+                # 外法线 = _orient_angle(内法线)的反方向
+                oa = math.radians(it._orient_angle)
+                expected = QPointF(-math.cos(oa), -math.sin(oa))
+                self.assertAlmostEqual(d.x(), expected.x(), delta=1e-3)
+                self.assertAlmostEqual(d.y(), expected.y(), delta=1e-3)
+                # 外法线应指向节点外: 与(点->外)同向, 即外法线在 x 方向的符号
+                # 应与"点相对中心"的 x 符号一致
+                p = it.pos()
+                self.assertEqual(d.x() > 0, (p.x() - c.x()) > 0)
+
+    def testRectanglePortEmissionPerpendicularToEdge(self) -> None:
+        """矩形端口连线出射方向恒为水平(垂直于左/右边缘), 不随目标位置变化"""
+        import math
+        node = QNodeItem("rect", QPointF(0, 0), NodeShape.RECTANGLE)
+        self.scene.addItem(node)
+        node.ports = {
+            "left": [QNodePortSpec(name="L0", shape="triangle", size=10, hit="1")],
+            "right": [QNodePortSpec(name="R0", shape="triangle", size=10, hit="1")],
+        }
+        conn = ConnectionItem(node, node)  # 临时对象, 仅用于调用方法
+        # right port -> +x(水平向右, 垂直于右边缘)
+        d = conn._portRadialDirection(node._port_items["right"][0])
+        self.assertIsNotNone(d)
+        self.assertAlmostEqual(d.x(), 1.0, delta=1e-6)
+        self.assertAlmostEqual(d.y(), 0.0, delta=1e-6)
+        # left port -> -x(水平向左, 垂直于左边缘)
+        d = conn._portRadialDirection(node._port_items["left"][0])
+        self.assertIsNotNone(d)
+        self.assertAlmostEqual(d.x(), -1.0, delta=1e-6)
+        self.assertAlmostEqual(d.y(), 0.0, delta=1e-6)
+
+    def testShowAllRequiresStillness(self) -> None:
+        """显示全部端口要求鼠标静止: 移动超过阈值会打断并重置等待
+
+        断言逻辑目标态(_label_visible); 实际可见性受动画时序影响。
+        """
+        self._assignSamplePorts()
+        other = self.node._port_items["left"][1]
+
+        # 模拟已 hover 节点本体: 进入等待, 锚点在 (0,0)
+        self.node._node_hovered = True
+        self.node._hover_anchor = QPointF(0, 0)
+        self.node._maybeStartPortShowAll()
+        self.assertTrue(self.node._port_label_timer.isActive())
+
+        # 假设已显示全部 label
+        self.node._setAllPortsShowAll(True)
+        self.assertTrue(other._label_visible)
+
+        # 大幅移动(>5px) -> 打断: 隐藏全部 + 重新计时 + 更新锚点
+        self.node._handleHoverAnchorMove(QPointF(100, 100))
+        self.assertFalse(other._label_visible)
+        self.assertTrue(self.node._port_label_timer.isActive())
+        self.assertEqual(self.node._hover_anchor, QPointF(100, 100))
+
+        # 小幅移动(<5px) -> 不重置, label 保持
+        self.node._setAllPortsShowAll(True)
+        self.node._handleHoverAnchorMove(QPointF(102, 101))
+        self.assertTrue(other._label_visible)
+
+    def testNameFitsInnerRegion(self) -> None:
+        """名称容纳在内部区域(INNER_RATIO 以内)"""
+        from chartflow.node.node_item import INNER_RATIO
+        rect = self.node.rect()
+        text_rect = self.node._text_item.boundingRect()
+        inner_half_w = rect.width() / 2 * INNER_RATIO
+        # 名称半宽 <= 内部区域半宽
+        self.assertLessEqual(text_rect.width() / 2, inner_half_w + 1e-6)
+
+    def testFillColorRespectsCustomColor(self) -> None:
+        """_fill_color 优先使用 port.color"""
+        red = QColor(255, 0, 0)
+        self.node.ports = {
+            "left": [QNodePortSpec(name="a", color=red)],
+            "right": [QNodePortSpec(name="b", color=red)],
+        }
+        self.assertEqual(self.node._port_items["left"][0]._fill_color(), red)
+        self.assertEqual(self.node._port_items["right"][0]._fill_color(), red)
+
+    def testFillColorFallsBackToSideDefault(self) -> None:
+        """color=None 时按所在侧使用 LEFT_COLOR / RIGHT_COLOR"""
+        self.node.ports = {
+            "left": [QNodePortSpec(name="a")],
+            "right": [QNodePortSpec(name="b")],
+        }
+        self.assertEqual(self.node._port_items["left"][0]._fill_color(),
+                         QNodePortSpec.LEFT_COLOR)
+        self.assertEqual(self.node._port_items["right"][0]._fill_color(),
+                         QNodePortSpec.RIGHT_COLOR)
+
+    def testFillColorFollowsLeftColorOverride(self) -> None:
+        """改写 QNodePortSpec.LEFT_COLOR/RIGHT_COLOR 后, 默认色跟随变化"""
+        original = (QColor(QNodePortSpec.LEFT_COLOR), QColor(QNodePortSpec.RIGHT_COLOR))
+        try:
+            new_left = QColor("#123456")
+            new_right = QColor("#654321")
+            QNodePortSpec.LEFT_COLOR = new_left
+            QNodePortSpec.RIGHT_COLOR = new_right
+            self.node.ports = {
+                "left": [QNodePortSpec(name="a")],
+                "right": [QNodePortSpec(name="b")],
+            }
+            self.assertEqual(self.node._port_items["left"][0]._fill_color(), new_left)
+            self.assertEqual(self.node._port_items["right"][0]._fill_color(), new_right)
+        finally:
+            QNodePortSpec.LEFT_COLOR, QNodePortSpec.RIGHT_COLOR = original
+
+    def testPortColorActuallyRendered(self) -> None:
+        """端到端: 自定义色端口经 paint 后, 像素确实呈现该颜色"""
+        from PyQt6.QtWidgets import QGraphicsView
+        # 用一个不易与节点本体/背景混淆的紫色
+        purple = QColor("#9B30FF")
+        self.node.ports = {
+            "left": [QNodePortSpec(name="a", shape="circle", size=14, color=purple)],
+            "right": [],
+        }
+        # 校验端口确实使用自定义色(逻辑层)
+        self.assertEqual(self.node._port_items["left"][0]._fill_color(), purple)
+
+        scene = self.node.scene()
+        self.assertIsNotNone(scene)
+        # 通过 view.grab 光栅化(对半圆 dot 的抗锯齿更稳定)
+        view = QGraphicsView(scene)
+        view.resize(300, 300)
+        view.show()
+        self.app.processEvents()
+        img = view.grab().toImage()
+
+        # 在渲染图中应能找到接近紫色的像素(抗锯齿混色 -> 容差 60)
+        found = 0
+        for y in range(img.height()):
+            for x in range(img.width()):
+                c = img.pixelColor(x, y)
+                if (abs(c.red() - purple.red()) < 60
+                        and abs(c.green() - purple.green()) < 60
+                        and abs(c.blue() - purple.blue()) < 60):
+                    found += 1
+        self.assertGreater(found, 0, "渲染图中未找到端口自定义色像素")
+
+
+class TestColorUtils(unittest.TestCase):
+    """测试颜色感知亮度工具(连线端口渐变用)"""
+
+    @classmethod
+    def setUpClass(cls) -> None:
+        cls.app = QApplication.instance()
+        if cls.app is None:
+            cls.app = QApplication(sys.argv)
+
+    def testRelativeLuminanceBounds(self) -> None:
+        """相对亮度在 [0,1], 黑=0 白=1"""
+        from chartflow.node.color_utils import relative_luminance
+        self.assertAlmostEqual(relative_luminance(QColor("#000000")), 0.0, places=6)
+        self.assertAlmostEqual(relative_luminance(QColor("#FFFFFF")), 1.0, places=6)
+
+    def testConstantMatchesConnectionGrey(self) -> None:
+        """PORT_GRADIENT_NEUTRAL_LUMINANCE 取自默认连线灰 #8B93A1"""
+        from chartflow.node.color_utils import (
+            PORT_GRADIENT_NEUTRAL_LUMINANCE, relative_luminance,
+        )
+        grey = QColor("#8B93A1")  # DEFAULT_CONNECTION_NORMAL
+        self.assertAlmostEqual(
+            PORT_GRADIENT_NEUTRAL_LUMINANCE, relative_luminance(grey),
+            places=3,
+        )
+
+    def testAdjustToRelativeLuminanceConverges(self) -> None:
+        """任意颜色调整到目标亮度后, 相对亮度近似等于目标(8bit 量化误差内)"""
+        from chartflow.node.color_utils import (
+            PORT_GRADIENT_NEUTRAL_LUMINANCE, color_at_relative_luminance,
+            relative_luminance,
+        )
+        for hexc in ("#1E7C5A", "#EE7942", "#1E90FF", "#9AA1AB", "#FF0000"):
+            adj = color_at_relative_luminance(QColor(hexc), PORT_GRADIENT_NEUTRAL_LUMINANCE)
+            self.assertLess(
+                abs(relative_luminance(adj) - PORT_GRADIENT_NEUTRAL_LUMINANCE),
+                0.01,  # 8bit 量化误差
+                f"{hexc} 调整后亮度未收敛到 L0",
+            )
+
+    def testAdjustPreservesHue(self) -> None:
+        """调整亮度尽量保留色相: 红/绿/蓝调整后主通道仍占主导"""
+        from chartflow.node.color_utils import (
+            PORT_GRADIENT_NEUTRAL_LUMINANCE, color_at_relative_luminance,
+        )
+        # 纯红: R 仍应是最大通道
+        adj_r = color_at_relative_luminance(QColor("#FF0000"), PORT_GRADIENT_NEUTRAL_LUMINANCE)
+        self.assertGreater(adj_r.red(), adj_r.green())
+        self.assertGreater(adj_r.red(), adj_r.blue())
+        # 纯绿: G 最大
+        adj_g = color_at_relative_luminance(QColor("#00FF00"), PORT_GRADIENT_NEUTRAL_LUMINANCE)
+        self.assertGreater(adj_g.green(), adj_g.red())
+        self.assertGreater(adj_g.green(), adj_g.blue())
+
+    def testNeutralGreyIsAchromatic(self) -> None:
+        """中性灰 R=G=B"""
+        from chartflow.node.color_utils import (
+            PORT_GRADIENT_NEUTRAL_LUMINANCE, neutral_grey_at_relative_luminance,
+        )
+        g = neutral_grey_at_relative_luminance(PORT_GRADIENT_NEUTRAL_LUMINANCE)
+        self.assertEqual(g.red(), g.green())
+        self.assertEqual(g.green(), g.blue())
+
+    def testAdjustBlackFallbackToGrey(self) -> None:
+        """纯黑无色相: 回退为与目标亮度等价的灰度"""
+        from chartflow.node.color_utils import (
+            PORT_GRADIENT_NEUTRAL_LUMINANCE, color_at_relative_luminance,
+        )
+        adj = color_at_relative_luminance(QColor("#000000"), PORT_GRADIENT_NEUTRAL_LUMINANCE)
+        self.assertEqual(adj.red(), adj.green())
+        self.assertEqual(adj.green(), adj.blue())
+
+
+class TestPortGradient(unittest.TestCase):
+    """测试端口渐变连线: 某端为 port 时该端为端口色(L0), 向中点过渡到中性灰"""
+
+    @classmethod
+    def setUpClass(cls) -> None:
+        cls.app = QApplication.instance()
+        if cls.app is None:
+            cls.app = QApplication(sys.argv)
+
+    def setUp(self) -> None:
+        self.scene = QGraphicsScene()
+        self.nodeA = QNodeItem("A", QPointF(0, 0))
+        self.nodeB = QNodeItem("B", QPointF(200, 0))
+        self.scene.addItem(self.nodeA)
+        self.scene.addItem(self.nodeB)
+
+    def tearDown(self) -> None:
+        self.scene.clear()
+
+    def _addPorts(self) -> None:
+        self.nodeA.ports = {"right": [QNodePortSpec(name="out", color=QColor("#1E90FF"))]}
+        self.nodeB.ports = {"left": [QNodePortSpec(name="in", color=QColor("#EE7942"))]}
+
+    def testNodeToNodeNoGradient(self) -> None:
+        """node→node 连线不启用渐变"""
+        conn = ConnectionItem(self.nodeA, self.nodeB)
+        self.scene.addItem(conn)
+        self.assertFalse(conn._hasPortGradient())
+        self.assertIsNone(conn._buildGradientBrush())
+
+    def testPortConnectionHasGradient(self) -> None:
+        """含 port 的连线启用渐变, 且能构造渐变画刷"""
+        self._addPorts()
+        src_port = self.nodeA._port_items["right"][0]
+        tgt_port = self.nodeB._port_items["left"][0]
+        conn = ConnectionItem(
+            self.nodeA, self.nodeB, source_port=src_port, target_port=tgt_port,
+        )
+        self.scene.addItem(conn)
+        self.assertTrue(conn._hasPortGradient())
+        self.assertIsNotNone(conn._buildGradientBrush())
+
+    def testGradientDisabledWhenSelected(self) -> None:
+        """选中态禁用渐变(使用选中色 pen)"""
+        self._addPorts()
+        src_port = self.nodeA._port_items["right"][0]
+        conn = ConnectionItem(self.nodeA, self.nodeB, source_port=src_port)
+        self.scene.addItem(conn)
+        conn.setSelected(True)
+        self.assertTrue(conn._is_selected)
+        # paint 走渐变的条件: 非选中且非闪烁
+        active = conn._hasPortGradient() and not conn._is_selected and not conn._is_flashing
+        self.assertFalse(active)
+        conn.setSelected(False)
+        active = conn._hasPortGradient() and not conn._is_selected and not conn._is_flashing
+        self.assertTrue(active)
+
+    def testPortColorFromSideDefault(self) -> None:
+        """port.color 为 None 时取所在侧默认色(left/right), 经亮度调整后返回"""
+        self.nodeA.ports = {"left": [QNodePortSpec(name="in")]}  # 无自定义色 -> LEFT_COLOR
+        self.nodeB.ports = {"right": [QNodePortSpec(name="out")]}
+        src_port = self.nodeA._port_items["left"][0]
+        tgt_port = self.nodeB._port_items["right"][0]
+        conn = ConnectionItem(
+            self.nodeA, self.nodeB, source_port=src_port, target_port=tgt_port,
+        )
+        self.scene.addItem(conn)
+        from chartflow.node.port_item import QNodePortSpec as _QP
+        from chartflow.node.color_utils import (
+            PORT_GRADIENT_NEUTRAL_LUMINANCE, color_at_relative_luminance,
+            relative_luminance,
+        )
+        # 返回值是 LEFT/RIGHT_COLOR 调整到 L0 后的颜色(亮度一致, 色相保留)
+        src_adj = conn._portSideColor(True)
+        # 色相保留: 绿(left)的绿色通道应最大
+        self.assertGreaterEqual(src_adj.green(), src_adj.red())
+        self.assertGreaterEqual(src_adj.green(), src_adj.blue())
+        # 亮度一致
+        self.assertLess(
+            abs(relative_luminance(src_adj) - PORT_GRADIENT_NEUTRAL_LUMINANCE), 0.01
+        )
+        # 与直接对 LEFT_COLOR 调整的结果应一致
+        self.assertEqual(
+            src_adj.name(),
+            color_at_relative_luminance(_QP.LEFT_COLOR, PORT_GRADIENT_NEUTRAL_LUMINANCE).name(),
+        )
+        tgt_adj = conn._portSideColor(False)
+        self.assertEqual(
+            tgt_adj.name(),
+            color_at_relative_luminance(_QP.RIGHT_COLOR, PORT_GRADIENT_NEUTRAL_LUMINANCE).name(),
+        )
+
+    def testPortColorAdjustedToNeutralLuminance(self) -> None:
+        """端口侧颜色已调整到 PORT_GRADIENT_NEUTRAL_LUMINANCE(亮度一致)"""
+        self._addPorts()
+        src_port = self.nodeA._port_items["right"][0]
+        conn = ConnectionItem(self.nodeA, self.nodeB, source_port=src_port)
+        self.scene.addItem(conn)
+        from chartflow.node.color_utils import (
+            PORT_GRADIENT_NEUTRAL_LUMINANCE, relative_luminance,
+        )
+        adj = conn._portSideColor(True)
+        self.assertLess(
+            abs(relative_luminance(adj) - PORT_GRADIENT_NEUTRAL_LUMINANCE), 0.01
+        )
+
+
+def RunAllTests() -> None:
+    """运行所有测试"""
+    # 创建测试套件
+    loader = unittest.TestLoader()
+    suite = unittest.TestSuite()
+    
+    # 添加所有测试类
+    suite.addTests(loader.loadTestsFromTestCase(TestEnums))
+    suite.addTests(loader.loadTestsFromTestCase(TestStyles))
+    suite.addTests(loader.loadTestsFromTestCase(TestNodeItem))
+    suite.addTests(loader.loadTestsFromTestCase(TestConnectionItem))
+    suite.addTests(loader.loadTestsFromTestCase(TestArrowItem))
+    suite.addTests(loader.loadTestsFromTestCase(TestSelectionRect))
+    suite.addTests(loader.loadTestsFromTestCase(TestNodeCanvas))
+    suite.addTests(loader.loadTestsFromTestCase(TestQNodeEditor))
+    suite.addTests(loader.loadTestsFromTestCase(TestNodeShapes))
+    suite.addTests(loader.loadTestsFromTestCase(TestArrowDragFunctionality))
+    suite.addTests(loader.loadTestsFromTestCase(TestConnectionTypes))
+    suite.addTests(loader.loadTestsFromTestCase(TestDecorator))
+    suite.addTests(loader.loadTestsFromTestCase(TestPorts))
+    suite.addTests(loader.loadTestsFromTestCase(TestColorUtils))
+    suite.addTests(loader.loadTestsFromTestCase(TestPortGradient))
+
+    # 运行测试
+    runner = unittest.TextTestRunner(verbosity=2)
+    result = runner.run(suite)
+    
+    # 返回测试结果
+    return result.wasSuccessful()
+
+
+if __name__ == "__main__":
+    success = RunAllTests()
+    sys.exit(0 if success else 1)