chartflow 0.1__py3-none-any.whl

chartflow/node/node_item.py

@@ -0,0 +1,754 @@
+"""
+节点项模块 - 表示节点图中的一个节点
+支持圆形、矩形、菱形三种形状
+
+重构说明:
+    本模块原为一个 1945 行的单体类, 现已按关注点拆分为多层继承结构,
+    分散于以下模块:
+      - _node_interface.py : INodeItem(Protocol) —— 纯类型契约(不参与运行时继承)
+      - _node_base.py      : _NodeCore(QGraphicsEllipseItem) —— 常量/信号/几何核心/样式核心/属性
+      - _node_ports.py     : _NodePortMixin —— 端口属性/布局/hover/字体刷新
+      - _node_interaction.py : _NodeInteractionMixin —— hover/鼠标/名称编辑/选中/标记
+      - _node_markers.py   : HoverButton/StartMarker/SingleMarker/CustomMarker —— 标记辅助类
+
+    NodeItem 继承上述 Mixin/Core, 并承载依赖跨层方法的最终实现:
+    paint / getEdgePoint / toDict / fromDict。
+
+    对外 API(公开成员、外部依赖的私有成员、模块常量、辅助类)完全保持不变:
+      - ``from chartflow.node.node_item import NodeItem`` 不变
+      - ``from chartflow.node.node_item import INNER_RATIO, CIRCLE_PORT_WINDOW_DEG`` 不变
+      - ``from chartflow.node.node_item import HoverButton, StartMarker, ...`` 不变
+      - ``node._port_items`` / ``node._style`` / ``node._custom_fill_color`` 等私有成员不变
+"""
+
+import copy
+import math
+from typing import Optional, Dict, Any
+
+from PyQt6.QtCore import Qt, QPointF, QRectF, QPropertyAnimation, QEasingCurve, QTimer
+from PyQt6.QtGui import QBrush, QPen, QColor, QPainterPath
+from PyQt6.QtWidgets import QGraphicsItem
+
+from chartflow.node.enums import NodeShape, NodeState
+from chartflow.node.port_item import port_to_dict
+
+# 分层基类
+from chartflow.node._node_base import _NodeCore
+from chartflow.node._node_ports import _NodePortMixin
+from chartflow.node._node_interaction import _NodeInteractionMixin
+
+# 辅助类 + 信号辅助类 re-export(保持历史导入路径)
+from chartflow.node._node_markers import (
+    HoverButton, StartMarker, SingleMarker, CustomMarker,
+)
+from chartflow.node._node_base import NodeSignalHelper
+
+# 模块常量 re-export(保持 ``from chartflow.node.node_item import XXX`` 可用)
+from chartflow.node._node_base import (  # noqa: F401
+    MIN_RADIUS,
+    PADDING,
+    TEXT_EDIT_PADDING,
+    BUTTON_RADIUS_RATIO,
+    ANIMATION_DURATION_SHOW,
+    ANIMATION_DURATION_HIDE,
+    Z_VALUE_NODE,
+    Z_VALUE_BUTTON,
+    Z_VALUE_MARKER,
+    INNER_RATIO,
+    PORT_MIN_GAP,
+    NAME_INNER_PAD,
+    HOVER_MOVE_THRESHOLD_SQ,
+    CIRCLE_PORT_WINDOW_DEG,
+    CIRCLE_PORT_MAX_STEP_DEG,
+)
+
+# Protocol 接口 re-export(便于外部做类型检查/类型提示)
+from chartflow.node._node_interface import INodeItem  # noqa: F401
+
+
+class QNodeItem(_NodePortMixin, _NodeInteractionMixin, _NodeCore):
+    """
+    节点项 - 表示节点图中的一个节点
+    支持圆形、矩形、菱形三种形状
+
+    继承自 _NodePortMixin + _NodeInteractionMixin + _NodeCore, 结构上满足
+    INodeItem(Protocol) 契约。本类承载依赖跨层方法的最终实现:
+    paint(绘制各形状 + 边缘指示器 + 更名虚线框)、getEdgePoint(各形状边缘交点)、
+    toDict/fromDict(序列化)。
+
+    所有对外成员(含外部依赖的私有成员)路径与重构前完全一致。
+    """
+
+    # ------------------------------------------------------------------ #
+    # 外环(可连线边缘指示器)可见性
+    # ------------------------------------------------------------------ #
+    def setEdgeIndicatorVisible(self, visible: bool) -> None:
+        """设置节点外环(可连线边缘指示器)是否显示。
+
+        外环是绘制在节点边缘、提示可从此处拖拽创建连线的浅灰色环。
+        关闭后不再绘制, 但边缘的连线命中判定不变(仍由
+        ``node_canvas._is_on_node_edge`` 决定)。
+
+        Args:
+            visible: ``True`` 显示外环, ``False`` 隐藏。
+        """
+        self._edge_indicator_visible = visible
+        self.update()
+
+    def isEdgeIndicatorVisible(self) -> bool:
+        """查询节点外环(可连线边缘指示器)当前是否显示。
+
+        Returns:
+            ``True`` 表示显示中, ``False`` 表示已隐藏。
+        """
+        return self._edge_indicator_visible
+
+    # ------------------------------------------------------------------ #
+    # 连线落点高亮(画布在 port/edge 连线拖拽中手动驱动)
+    # ------------------------------------------------------------------ #
+    def setDropTarget(self, on: bool) -> None:
+        """标记/取消本节点作为连线落点(目标端)的高亮态。
+
+        连线拖拽期间画布接管鼠标移动事件, 光标下的目标节点不会收到
+        hoverEnter/hoverLeave(场景 hover 派发被压制), 故由画布在
+        mouseMoveEvent 中手动命中检测后调用本方法驱动描边。
+        使用与 port 描边一致的 DodgerBlue(#1E90FF)描边, 与选中态描边
+        同色但优先级最高(覆盖 hover/selected 的描边视觉), 不改变
+        ``_state`` 本身。
+        """
+        if self._drop_target == on:
+            return
+        self._drop_target = on
+        self.update()
+
+    # ------------------------------------------------------------------ #
+    # 不合规连接反馈
+    # ------------------------------------------------------------------ #
+    def flashError(self) -> None:
+        """红色描边闪烁(试图创建不合规连接时的反馈)。
+
+        QTimer 驱动 3 次闪烁(150ms 间隔), 在红色描边与正常描边间 toggle。
+        """
+        # 停掉正在进行的闪烁, 重新开始
+        if self._flash_timer is not None:
+            self._flash_timer.stop()
+            self._flash_timer.deleteLater()
+            self._flash_timer = None
+        self._flash_error = True
+        self.update()
+
+        flash_count = [0]
+
+        def toggleFlash():
+            flash_count[0] += 1
+            # 奇数次: 显示红色描边(_flash_error=True); 偶数次: 关闭
+            self._flash_error = (flash_count[0] % 2 == 0)
+            self.update()
+            if flash_count[0] >= 6:  # 3 次闪烁 = 6 次切换
+                self._flash_timer.stop()
+                self._flash_timer.deleteLater()
+                self._flash_timer = None
+                self._flash_error = False
+                self.update()
+
+        self._flash_timer = QTimer()
+        self._flash_timer.timeout.connect(toggleFlash)
+        self._flash_timer.start(150)
+
+    # ------------------------------------------------------------------ #
+    # 连线能力(是否可参与连线)
+    # ------------------------------------------------------------------ #
+    def setConnectable(self, connectable: bool) -> None:
+        """设置节点是否可参与连线。
+
+        设为 ``False`` 时:
+        - 清除该节点已有的全部连线(两端任一为本节点即删除);
+        - 软联动隐藏外环(此后用户仍可单独调用
+          :meth:`setEdgeIndicatorVisible` 重新开启, 不会被强制覆盖);
+        - 后续任何新建连线(边缘拖拽 / 箭头重连 / 导入)只要涉及本节点,
+          都会被 :meth:`~NodeCanvas.addConnection` 拒绝。
+
+        设为 ``True`` 时仅恢复连线能力, 不重建已删连线, 也不自动恢复外环。
+
+        Args:
+            connectable: ``True`` 允许参与连线, ``False`` 禁止并清除已有连线。
+        """
+        if self._connectable == connectable:
+            return
+        self._connectable = connectable
+        # 软联动: 不可连线时自动隐藏外环(不硬性限制, 用户可随后自行再开)
+        if not connectable:
+            self._edge_indicator_visible = False
+        self.update()
+        # 清除已有连线
+        if not connectable:
+            self._removeAllConnections()
+
+    def isConnectable(self) -> bool:
+        """查询节点当前是否可参与连线。
+
+        Returns:
+            ``True`` 可参与连线(默认), ``False`` 已被禁止。
+        """
+        return self._connectable
+
+    # ------------------------------------------------------------------ #
+    # 自指规则(selfrefs)
+    # ------------------------------------------------------------------ #
+    @property
+    def selfrefs(self) -> Dict[str, bool]:
+        """自指规则: 控制同节点内 6 类自指连接是否允许创建。
+
+        只读 property, 但返回的是内部 dict(**非副本**), 可直接修改其中的
+        bool 值, 修改立即对后续 :meth:`NodeCanvas.addConnection` 生效::
+
+            node.selfrefs["node->node"] = False   # 禁止 node 自环
+            node.selfrefs["port->port"] = True    # 允许同 port 自指
+
+        六个键(默认值 = 既有逻辑):
+
+        - ``"node->node"`` (默认 True): 同节点、两端均无 port 的自环。
+        - ``"port->port"`` (默认 False): 同节点、同极或同一 port 的自指
+          (不含异极 left↔right)。
+        - ``"node->port"`` (默认 False): 同节点、源为节点边缘、目标为本节点 port。
+        - ``"port->node"`` (默认 False): 同节点、源为本节点 port、目标为节点边缘。
+        - ``"left->right"`` (默认 True): 同节点、源=left port、目标=right port。
+        - ``"right->left"`` (默认 True): 同节点、源=right port、目标=left port。
+
+        ``left->right`` 与 ``right->left`` 是两条**独立**方向的自指边,
+        各自独立开关, 互不去重(可同时存在两条不同方向的环)。
+
+        所有被允许的自指都会被 :class:`ConnectionItem` 绘制为环/椭圆环。
+        """
+        return self._selfrefs
+
+    def _removeAllConnections(self) -> None:
+        """删除场景中所有与本节点相连的连线。
+
+        通过 ``_findCanvas()`` 定位所属 ``NodeCanvas``, 复用其
+        ``removeConnection``(会清理箭头、更新场景、置脏)。
+        连线只存在于画布的 ``_connections``, 节点本身不持有列表。
+        """
+        canvas = self._findCanvas()
+        if canvas is None:
+            return
+        # connections 属性返回副本, 可安全边删边遍历
+        attached = [c for c in canvas.connections
+                    if c.sourceNode is self or c.targetNode is self]
+        for c in attached:
+            canvas.removeConnection(c)
+
+    # ------------------------------------------------------------------ #
+    # 几何: 边缘交点
+    # ------------------------------------------------------------------ #
+    def getEdgePoint(self, target_pos: QPointF) -> QPointF:
+        """
+        计算从节点中心到目标方向的边缘点
+        根据节点形状不同，计算方式不同
+
+        Args:
+            target_pos: 目标位置
+
+        Returns:
+            边缘点坐标
+        """
+        center = self.sceneBoundingRect().center()
+
+        if self._shape == NodeShape.ELLIPSE:
+            # 圆形：使用角度计算边缘点
+            dx = target_pos.x() - center.x()
+            dy = target_pos.y() - center.y()
+            angle = math.atan2(dy, dx)
+
+            return QPointF(
+                center.x() + self._radius * math.cos(angle),
+                center.y() + self._radius * math.sin(angle)
+            )
+
+        elif self._shape == NodeShape.RECTANGLE:
+            # 圆角矩形处理 - 参考老版本实现
+            rect = self.rect()
+            local_target = self.mapFromScene(target_pos)
+            local_center = rect.center()
+
+            dx = local_target.x() - local_center.x()
+            dy = local_target.y() - local_center.y()
+
+            if abs(dx) < 1e-6 and abs(dy) < 1e-6:
+                return center
+
+            half_w = rect.width() / 2
+            half_h = rect.height() / 2
+            corner_radius = min(half_w, half_h) * 0.2
+
+            # 计算与外层矩形的交点
+            t_x = half_w / abs(dx) if abs(dx) > 1e-6 else float('inf')
+            t_y = half_h / abs(dy) if abs(dy) > 1e-6 else float('inf')
+            t_rect = min(t_x, t_y)
+
+            # 矩形交点（本地坐标）
+            ix = local_center.x() + dx * t_rect
+            iy = local_center.y() + dy * t_rect
+
+            # 内矩形边界（不含圆角的区域）
+            inner_w = half_w - corner_radius
+            inner_h = half_h - corner_radius
+
+            # 检查是否在圆角区域（同时超出内矩形的x和y边界）
+            in_corner = abs(ix - local_center.x()) > inner_w and abs(iy - local_center.y()) > inner_h
+
+            if not in_corner:
+                # 在直线边上，直接返回矩形交点
+                return self.mapToScene(QPointF(ix, iy))
+
+            # 在圆角区域，计算与圆的精确交点
+            sign_x = 1 if dx > 0 else -1
+            sign_y = 1 if dy > 0 else -1
+
+            # 圆角圆心（本地坐标）
+            cx = local_center.x() + sign_x * inner_w
+            cy = local_center.y() + sign_y * inner_h
+
+            # 解二次方程：|t*V - (C - O)|^2 = r^2
+            a = dx * dx + dy * dy
+            b = -2 * (dx * (cx - local_center.x()) + dy * (cy - local_center.y()))
+            c = (cx - local_center.x()) ** 2 + (cy - local_center.y()) ** 2 - corner_radius ** 2
+
+            discriminant = b * b - 4 * a * c
+
+            if discriminant < 0:
+                return self.mapToScene(QPointF(ix, iy))
+
+            sqrt_d = math.sqrt(discriminant)
+            t1 = (-b - sqrt_d) / (2 * a)
+            t2 = (-b + sqrt_d) / (2 * a)
+
+            # 边界限制
+            min_x = local_center.x() - half_w
+            max_x = local_center.x() + half_w
+            min_y = local_center.y() - half_h
+            max_y = local_center.y() + half_h
+
+            valid_ts = []
+            for t in [t1, t2]:
+                if t > 1e-6:
+                    px = local_center.x() + dx * t
+                    py = local_center.y() + dy * t
+
+                    # 检查是否在正确的象限
+                    in_quad_x = (sign_x > 0 and px >= cx) or (sign_x < 0 and px <= cx)
+                    in_quad_y = (sign_y > 0 and py >= cy) or (sign_y < 0 and py <= cy)
+                    in_bounds = (min_x <= px <= max_x) and (min_y <= py <= max_y)
+
+                    if in_quad_x and in_quad_y and in_bounds:
+                        valid_ts.append(t)
+
+            if not valid_ts:
+                return self.mapToScene(QPointF(ix, iy))
+
+            # 取较近的有效交点
+            t_arc = min(valid_ts)
+            local_edge_x = local_center.x() + dx * t_arc
+            local_edge_y = local_center.y() + dy * t_arc
+
+            return self.mapToScene(QPointF(local_edge_x, local_edge_y))
+
+        elif self._shape == NodeShape.DIAMOND:
+            # 菱形：计算与菱形边界的交点
+            dx = target_pos.x() - center.x()
+            dy = target_pos.y() - center.y()
+
+            if dx == 0 and dy == 0:
+                return center
+
+            # 菱形由四个顶点组成，使用参数方程计算交点
+            abs_dx = abs(dx)
+            abs_dy = abs(dy)
+
+            if abs_dx + abs_dy == 0:
+                return center
+
+            scale = self._radius / (abs_dx + abs_dy)
+
+            return QPointF(
+                center.x() + dx * scale,
+                center.y() + dy * scale
+            )
+
+        return center
+
+    # ------------------------------------------------------------------ #
+    # 序列化
+    # ------------------------------------------------------------------ #
+    def toDict(self) -> dict:
+        """
+        将节点转换为字典
+
+        Returns:
+            包含节点所有数据的字典
+        """
+        # deepcopy: data 中可能含列表/字典等可变嵌套(如 _importDict 写入的
+        # targets/decorates), 浅拷贝会让外部就地修改污染原节点 _data。
+        result = {
+            "id": self._node_id,
+            "name": self._name,
+            "shape": self._shape.name,
+            "position": {"x": self.pos().x(), "y": self.pos().y()},
+            "data": copy.deepcopy(self._data),
+        }
+
+        # 装饰器类型(semantic 描边色: recursive/behavior/sequence/selector/parallel)。
+        # 此前完全未序列化, 导出再导入后彩色边框丢失。
+        if self._decorator is not None:
+            result["decorator"] = self._decorator
+
+        # 添加样式信息（如果有自定义样式）
+        style_data = {}
+        if hasattr(self, '_custom_fill_color') and self._custom_fill_color:
+            style_data["fill_color"] = self._custom_fill_color.name()
+        if hasattr(self, '_custom_stroke_color') and self._custom_stroke_color:
+            style_data["stroke_color"] = self._custom_stroke_color.name()
+        if hasattr(self, '_custom_stroke_width') and self._custom_stroke_width is not None:
+            style_data["stroke_width"] = self._custom_stroke_width
+        if hasattr(self, '_custom_font_family') and self._custom_font_family:
+            style_data["font_family"] = self._custom_font_family
+        if hasattr(self, '_custom_font_size') and self._custom_font_size:
+            style_data["font_size"] = self._custom_font_size
+        if hasattr(self, '_custom_radius') and self._custom_radius:
+            style_data["radius"] = self._custom_radius
+
+        if style_data:
+            result["style"] = style_data
+
+        # 添加 custom 标记配置（如果有）
+        if self._custom_marker is not None:
+            result["custom"] = self._custom_marker.getStyle()
+            # 标记可见性: 此前只存样式不存可见性, 导致导入后 marker 对象重建
+            # 但 opacity 仍为初始 0(隐藏), 用户可见的标记变看不见。
+            if self._is_custom_marker_visible:
+                result["custom_marker_visible"] = True
+
+        # single 标记可见性: 此前完全未序列化, 导入后 single 标记丢失。
+        if self._is_single_marker_visible:
+            result["single_marker_visible"] = True
+
+        # 添加端口配置（如果有）
+        if self._ports_spec.get("left") or self._ports_spec.get("right"):
+            result["ports"] = {
+                "left": [port_to_dict(p) for p in self._ports_spec["left"]],
+                "right": [port_to_dict(p) for p in self._ports_spec["right"]],
+            }
+
+        # 外环可见性（仅在隐藏时序列化，避免污染默认导出）
+        if not self._edge_indicator_visible:
+            result["edge_indicator_visible"] = False
+
+        # 连线能力（仅在不可连线时序列化，避免污染默认导出）
+        if not self._connectable:
+            result["connectable"] = False
+
+        # 自指规则: 仅序列化与默认值不同的键(避免污染默认导出)。
+        # 必须序列化, 否则导入新节点 selfrefs 全为默认值, 用户放宽过的
+        # port->port / node->port / port->node 等自指连接会被 addConnection
+        # 以规则 False 拒绝, 静默丢失。
+        selfref_defaults = {
+            "node->node": True, "port->port": False, "node->port": False,
+            "port->node": False, "left->right": True, "right->left": True,
+        }
+        selfref_diff = {
+            k: v for k, v in self._selfrefs.items()
+            if selfref_defaults.get(k) != v
+        }
+        if selfref_diff:
+            result["selfrefs"] = selfref_diff
+
+        return result
+
+    def fromDict(self, data: dict) -> None:
+        """
+        从字典更新节点数据
+
+        Args:
+            data: 节点数据字典
+        """
+        # 还原稳定唯一标识(供画布导出/导入时连线按 id 引用本节点)
+        if "id" in data and data["id"]:
+            self._node_id = data["id"]
+
+        # 更新名称
+        if "name" in data:
+            self.name = data["name"]
+
+        # 更新形状
+        if "shape" in data:
+            try:
+                self._shape = NodeShape[data["shape"]]
+            except KeyError:
+                pass
+
+        # 还原装饰器类型(semantic 描边色)。直接写字段, 末尾由 _layoutPorts
+        # 触发的 update 在下一帧重绘; 装饰器仅影响描边色, 不改几何。
+        if "decorator" in data and data["decorator"]:
+            self._decorator = data["decorator"]
+
+        # 更新位置
+        if "position" in data:
+            pos = data["position"]
+            self.setPos(QPointF(pos.get("x", 0), pos.get("y", 0)))
+
+        # 更新数据
+        if "data" in data:
+            self._data.update(data["data"])
+
+        # 加载端口配置（可选）
+        if "ports" in data:
+            self.ports = data["ports"]
+
+        # 加载样式
+        if "style" in data:
+            style = data["style"]
+            if "fill_color" in style:
+                self._custom_fill_color = QColor(style["fill_color"])
+                self._style.idle_fill = self._custom_fill_color
+            if "stroke_color" in style:
+                self._custom_stroke_color = QColor(style["stroke_color"])
+                self._style.idle_stroke = self._custom_stroke_color
+                self._style.selected_stroke = self._custom_stroke_color
+            if "stroke_width" in style:
+                self._custom_stroke_width = style["stroke_width"]
+                self._style.stroke_width = self._custom_stroke_width
+            if "font_family" in style:
+                self._custom_font_family = style["font_family"]
+                font = self._text_item.font()
+                font.setFamily(self._custom_font_family)
+                self._text_item.setFont(font)
+            if "font_size" in style:
+                self._custom_font_size = style["font_size"]
+                font = self._text_item.font()
+                font.setPointSize(self._custom_font_size)
+                self._text_item.setFont(font)
+            if "radius" in style:
+                self._custom_radius = style["radius"]
+                self._applySize(self._custom_radius, self._custom_radius)
+            self._applyStyle()
+            # stroke_width<=0 表示"无边框"(对应 setBorder 的 NoPen 分支)。
+            # 但 _applyStyle 内部用 setPen(QPen(color, 0)) —— Qt 中宽度 0 的
+            # cosmetic pen 仍会画 1px 线, 并不等同 NoPen。故显式补一次 NoPen。
+            if self._custom_stroke_width is not None and self._custom_stroke_width <= 0:
+                self.setPen(QPen(Qt.PenStyle.NoPen))
+
+        # 加载 custom 标记配置（可选）
+        if "custom" in data:
+            custom_data = data["custom"]
+            if isinstance(custom_data, dict):
+                # 创建并配置 custom 标记
+                if self._custom_marker is None:
+                    self._custom_marker = CustomMarker(self)
+                    self._custom_marker_animation = QPropertyAnimation(self._custom_marker, b"opacity")
+                    self._custom_marker_animation.setEasingCurve(QEasingCurve.Type.InOutQuad)
+
+                # 解析颜色值
+                def parseColor(value):
+                    if isinstance(value, str):
+                        return QColor(value)
+                    return None
+
+                self._custom_marker.setStyle(
+                    text=custom_data.get("text"),
+                    bg_color=parseColor(custom_data.get("bg_color")),
+                    fg_color=parseColor(custom_data.get("fg_color")),
+                    border_color=parseColor(custom_data.get("border_color")),
+                    border_width=custom_data.get("border_width"),
+                    radius=custom_data.get("radius")
+                )
+
+                # 如果标记设置为可见，显示它
+                # 注意：这里不自动显示，由调用者通过 setCustomMarkerVisible 控制
+
+        # 加载外环可见性（可选，缺省保持当前默认值 True）
+        if "edge_indicator_visible" in data:
+            self._edge_indicator_visible = bool(data["edge_indicator_visible"])
+
+        # 加载连线能力（可选, 缺省保持默认值 True）
+        # 仅改字段, 不调 setConnectable, 避免反序列化中途触发清除连线
+        if "connectable" in data:
+            self._connectable = bool(data["connectable"])
+
+        # 加载自指规则(增量合并: 仅覆盖字典中出现的键, 缺失键保持默认)
+        if "selfrefs" in data and isinstance(data["selfrefs"], dict):
+            for k, v in data["selfrefs"].items():
+                if k in self._selfrefs:
+                    self._selfrefs[k] = bool(v)
+
+        # 样式(可能改了半径)应用完成后，重新排布端口
+        self._layoutPorts()
+
+        # 标记可见性(放在几何/样式就绪之后, 动画与位置依赖节点已布局完成)。
+        # 此前 custom 只还原样式不还原可见性、single 完全未持久化, 导致导入
+        # 后用户可见的标记消失。
+        if data.get("custom_marker_visible"):
+            self.setCustomMarkerVisible(True)
+        if data.get("single_marker_visible"):
+            self.setSingleMarkerVisible(True)
+
+    # ------------------------------------------------------------------ #
+    # 绘制
+    # ------------------------------------------------------------------ #
+    def paint(self, painter, option, widget=None) -> None:
+        """绘制节点，根据形状绘制圆形、矩形或菱形"""
+        # 获取当前样式
+        base_color = self._style.idle_fill
+
+        # 获取装饰器边框颜色（如果有）
+        decorator_color = self._getDecoratorStrokeColor()
+
+        if self._state == NodeState.IDLE:
+            fill_color = base_color
+            stroke_color = decorator_color if decorator_color else self._style.idle_stroke
+        elif self._state == NodeState.HOVER:
+            fill_color = self._blendColors(base_color, self._style.hover_overlay)
+            stroke_color = decorator_color if decorator_color else self._style.idle_stroke
+        elif self._state == NodeState.SELECTED:
+            fill_color = self._blendColors(base_color, self._style.selected_overlay)
+            # 选中状态下，如果节点有装饰器，稍微加亮装饰器颜色
+            if decorator_color:
+                # 混合装饰器颜色和选中颜色
+                stroke_color = self._blendColors(decorator_color, self._style.selected_stroke, 0.3)
+            else:
+                stroke_color = self._style.selected_stroke
+        else:
+            fill_color = base_color
+            stroke_color = decorator_color if decorator_color else self._style.idle_stroke
+
+        # 连线落点高亮: 覆盖描边为 DodgerBlue(与 port 描边一致), 描边略加粗;
+        # 不改变填充(保留 hover/selected 的填充反馈), 不改 _state
+        if self._drop_target:
+            stroke_color = self._style.selected_stroke
+
+        # 不合规连接闪烁: 红色描边覆盖(优先级最高), 描边加粗
+        if self._flash_error:
+            stroke_color = QColor("#E53935")
+
+        painter.setBrush(QBrush(fill_color))
+        if self._flash_error:
+            drop_width = self._style.stroke_width + 2.0
+        elif self._drop_target:
+            drop_width = self._style.stroke_width + 1.0
+        else:
+            drop_width = self._style.stroke_width
+        painter.setPen(QPen(stroke_color, drop_width))
+
+        rect = self.rect()
+
+        # 根据形状绘制
+        if self._shape == NodeShape.ELLIPSE:
+            painter.drawEllipse(rect)
+        elif self._shape == NodeShape.RECTANGLE:
+            corner_radius = min(rect.width(), rect.height()) * 0.2
+            painter.drawRoundedRect(rect, corner_radius, corner_radius)
+        else:  # DIAMOND
+            # 绘制菱形
+            center = rect.center()
+            path = QPainterPath()
+            path.moveTo(center.x(), rect.top())
+            path.lineTo(rect.right(), center.y())
+            path.lineTo(center.x(), rect.bottom())
+            path.lineTo(rect.left(), center.y())
+            path.closeSubpath()
+            painter.drawPath(path)
+
+        # 绘制可连线边缘区域的视觉指示（外环）
+        if self._edge_indicator_visible:
+            self._draw_edge_indicator(painter)
+
+        # 绘制名称编辑区域的虚线框（浅浅浅灰色）
+        self._draw_name_edit_area(painter)
+
+    def _draw_name_edit_area(self, painter) -> None:
+        """
+        绘制名称编辑区域的虚线框
+        使用浅浅浅灰色虚线框包围文本区域，提示用户可以点击更名
+        """
+        if self._is_editing_name:
+            return  # 编辑时不显示虚线框
+
+        # 浅浅浅灰色虚线（带透明度）
+        dash_pen = QPen(QColor(220, 220, 220, 120), 1)  # 浅浅浅灰色，半透明
+        dash_pen.setStyle(Qt.PenStyle.DashLine)
+        painter.setPen(dash_pen)
+        painter.setBrush(Qt.BrushStyle.NoBrush)
+
+        # 绘制虚线矩形（使用本地坐标）
+        painter.drawRect(self._name_edit_area)
+
+    def _draw_edge_indicator(self, painter) -> None:
+        """
+        绘制可连线边缘区域的视觉指示
+        在节点边缘显示一个浅灰色的环，指示用户可以从此处拖拽创建连线
+        """
+        # 边缘区域的起始比例（与 node_canvas.py 中 _is_on_node_edge 一致）
+        inner_ratio = 0.75  # 边缘区域起始位置（半径的75%处）
+
+        # 非常浅的灰色，半透明
+        indicator_color = QColor(200, 200, 200, 60)  # 浅灰色，半透明
+        indicator_pen = QPen(indicator_color, 1)
+        indicator_pen.setStyle(Qt.PenStyle.SolidLine)
+        painter.setPen(indicator_pen)
+        painter.setBrush(QBrush(indicator_color))
+
+        rect = self.rect()
+
+        if self._shape == NodeShape.ELLIPSE:
+            # 圆环: 外椭圆减去内椭圆, 半轴取自 rect(与节点本体一致, 永不错位)
+            center = rect.center()
+            rx = rect.width() / 2.0
+            ry = rect.height() / 2.0
+            path = QPainterPath()
+            path.addEllipse(center, rx, ry)
+            path.addEllipse(center, rx * inner_ratio, ry * inner_ratio)
+            painter.drawPath(path)
+        elif self._shape == NodeShape.RECTANGLE:
+            # 矩形：绘制圆角矩形环
+            corner_radius = min(rect.width(), rect.height()) * 0.2
+
+            # 内矩形（不包含边缘环的区域）
+            margin = (1 - inner_ratio) * min(rect.width(), rect.height()) / 2
+            inner_rect = rect.adjusted(margin, margin, -margin, -margin)
+
+            # 创建矩形环路径（外矩形减去内矩形）
+            path = QPainterPath()
+            path.addRoundedRect(rect, corner_radius, corner_radius)
+            inner_corner = max(0, corner_radius - margin)
+            path.addRoundedRect(inner_rect, inner_corner, inner_corner)
+            painter.drawPath(path)
+        else:  # DIAMOND
+            # 菱形：绘制菱形环
+            center = rect.center()
+            margin = (1 - inner_ratio) * min(rect.width(), rect.height()) / 2
+
+            # 外菱形
+            outer_path = QPainterPath()
+            outer_path.moveTo(center.x(), rect.top())
+            outer_path.lineTo(rect.right(), center.y())
+            outer_path.lineTo(center.x(), rect.bottom())
+            outer_path.lineTo(rect.left(), center.y())
+            outer_path.closeSubpath()
+
+            # 内菱形（按比例缩小）
+            inner_path = QPainterPath()
+            inner_top = center.y() - (center.y() - rect.top()) * inner_ratio
+            inner_right = center.x() + (rect.right() - center.x()) * inner_ratio
+            inner_bottom = center.y() + (rect.bottom() - center.y()) * inner_ratio
+            inner_left = center.x() - (center.x() - rect.left()) * inner_ratio
+
+            inner_path.moveTo(center.x(), inner_top)
+            inner_path.lineTo(inner_right, center.y())
+            inner_path.lineTo(center.x(), inner_bottom)
+            inner_path.lineTo(inner_left, center.y())
+            inner_path.closeSubpath()
+
+            # 创建菱形环路径
+            path = QPainterPath()
+            path.addPath(outer_path)
+            path.addPath(inner_path)
+            painter.drawPath(path)