chartflow 0.1__py3-none-any.whl

chartflow/node/_node_ports.py

@@ -0,0 +1,536 @@
+"""
+节点端口 Mixin 模块
+
+定义 _NodePortMixin —— 端口(port)相关的全部行为。
+本类不含 __init__, 通过覆写 _NodeCore._init_ports 钩子创建端口
+label 计时器; 并提供 ports 属性、端口布局、端口 hover、端口字体刷新等。
+
+依赖关系: _NodePortMixin 不继承 _NodeCore(避免循环导入与 MRO 问题);
+运行时由 NodeItem(_NodePortMixin, _NodeInteractionMixin, _NodeCore) 组合,
+所有 self.xxx 调用经 MRO 在 _NodeCore/NodeItem 上解析。
+"""
+
+import math
+from typing import Optional, Dict
+
+from PyQt6.QtCore import Qt, QPointF, QRectF, QTimer
+
+from chartflow.node.enums import NodeShape
+from chartflow.node.port_item import (
+    QNodePortSpec,
+    QNodePort,
+    VALID_PORT_SHAPES,
+    PORT_LABEL_HOVER_DELAY_MS,
+    HIT_GAP,
+    port_from_dict,
+    port_to_dict,
+    port_depth,
+)
+
+# 端口布局相关常量(与 _node_base 保持一致; 此处单独导入以防散落)
+from chartflow.node._node_base import (
+    PORT_MIN_GAP,
+    CIRCLE_PORT_WINDOW_DEG,
+    CIRCLE_PORT_MAX_STEP_DEG,
+)
+
+
+class _NodePortMixin:
+    """端口 Mixin
+
+    提供 ports 属性(get/set)、端口规范化、端口渲染项的构建/移除/布局
+    (矩形/菱形轴向排布、圆形径向排布)、端口 hover(label 显示全部/solo)、
+    端口字体刷新, 以及供 _NodeCore._calculateHalfSize 使用的几何辅助计算
+    (_hasPorts/_halfHeightForPorts/_portInwardExtent/_circlePortRadius)。
+    """
+
+    # ------------------------------------------------------------------ #
+    # 初始化钩子(覆写 _NodeCore._init_ports)
+    # ------------------------------------------------------------------ #
+    def _init_ports(self) -> None:
+        """创建端口 label 计时器(节点 hover 超过阈值后显示全部端口 label)"""
+        # 端口 spec/items 在 _NodeCore.__init__ 中已初始化, 此处只补 timer
+        self._port_label_timer: QTimer = QTimer()
+        self._port_label_timer.setSingleShot(True)
+        self._port_label_timer.setInterval(PORT_LABEL_HOVER_DELAY_MS)
+        self._port_label_timer.timeout.connect(self._showAllPortLabels)
+
+    # ------------------------------------------------------------------ #
+    # ports 属性
+    # ------------------------------------------------------------------ #
+    @property
+    def ports(self) -> Dict[str, list]:
+        """端口配置: {"left": [QNodePortSpec...], "right": [QNodePortSpec...]}
+
+        仅识别 'left' 与 'right' 两个键。可赋值为同类字典以重建端口；
+        列表元素可为 QNodePortSpec 或 dict(自动转换为 QNodePortSpec)。
+        """
+        return self._ports_spec
+
+    @ports.setter
+    def ports(self, value: Optional[Dict[str, list]]) -> None:
+        self._ports_spec = self._normalize_ports(value)
+        self._rebuildPortItems()
+
+    def setPorts(self, value: Optional[Dict[str, list]]) -> None:
+        """设置端口(等价于直接赋值 ``node.ports = value``)"""
+        self.ports = value
+
+    def _normalize_ports(self, value) -> Dict[str, list]:
+        """校验并规范化端口配置"""
+        result: Dict[str, list] = {"left": [], "right": []}
+        if value is None:
+            return result
+        if not isinstance(value, dict):
+            raise TypeError(f"ports 必须是 dict，得到 {type(value).__name__}")
+
+        for key in ("left", "right"):
+            raw = value.get(key, [])
+            if raw is None:
+                raw = []
+            if not isinstance(raw, (list, tuple)):
+                raise TypeError(f"ports['{key}'] 必须是列表，得到 {type(raw).__name__}")
+            ports: list = []
+            seen_names: set = set()  # 本侧已出现的非空 name(用于查重)
+            for p in raw:
+                if isinstance(p, QNodePortSpec):
+                    port = p
+                elif isinstance(p, dict):
+                    port = port_from_dict(p)
+                else:
+                    raise TypeError(
+                        f"端口项必须是 QNodePortSpec 或 dict，得到 {type(p).__name__}"
+                    )
+                if port.shape not in VALID_PORT_SHAPES:
+                    raise ValueError(
+                        f"QNodePortSpec.shape 必须是 {VALID_PORT_SHAPES} 之一，"
+                        f"得到: {port.shape!r}"
+                    )
+                if not port.name and port.label is None:
+                    # name 与 label 均空时无法显示任何文本，但仍然允许(仅 dot)
+                    pass
+                # 同侧 name 唯一性: 非空 name 不得在同侧重复(用作连线的稳定标识)。
+                # 空 name 的端口可多个(仅 dot, 无法被连线按 name 引用)。
+                if port.name:
+                    if port.name in seen_names:
+                        raise ValueError(
+                            f"同侧({key})端口 name 重复: {port.name!r}；"
+                            f"同一侧的端口 name 必须唯一"
+                        )
+                    seen_names.add(port.name)
+                ports.append(port)
+            result[key] = ports
+        return result
+
+    # ------------------------------------------------------------------ #
+    # 端口渲染项构建/移除
+    # ------------------------------------------------------------------ #
+    def _rebuildPortItems(self) -> None:
+        """根据 _ports_spec 重建端口渲染项(端口变化时重算节点尺寸)"""
+        self._removePortItems()
+        self._hovered_port_count = 0
+        # 端口变化可能改变所需尺寸(矩形+端口 -> 长宽可不等); 此时端口项已清空,
+        # 仅更新矩形, 待重建端口项后再 _layoutPorts
+        if not getattr(self, "_custom_radius", None):
+            rw, rh = self._calculateHalfSize()
+            if (rw, rh) != (self._rw, self._rh):
+                self._setSize(rw, rh)
+        for side in ("left", "right"):
+            for spec in self._ports_spec.get(side, []):
+                item = QNodePort(spec, side, self)
+                self._port_items[side].append(item)
+        self._layoutPorts()
+
+    def _removePortItems(self) -> None:
+        """移除全部端口渲染项"""
+        for side in ("left", "right"):
+            for item in self._port_items[side]:
+                try:
+                    scene = item.scene()
+                    if scene is not None:
+                        scene.removeItem(item)
+                    else:
+                        item.setParentItem(None)
+                except RuntimeError:
+                    pass
+            self._port_items[side] = []
+
+    # ------------------------------------------------------------------ #
+    # 端口布局
+    # ------------------------------------------------------------------ #
+    def _layoutPorts(self) -> None:
+        """分布端口: 圆形沿侧弧径向; 菱形沿左/右斜边贴合排布; 矩形沿边缘轴向。"""
+        is_circle = self._shape == NodeShape.ELLIPSE
+        is_diamond = self._shape == NodeShape.DIAMOND
+        for side in ("left", "right"):
+            for it in self._port_items[side]:
+                # 互斥的排布模式: _radial(圆形) / _diamond(菱形) / 皆 False(矩形)
+                if it._radial != is_circle:
+                    it._radial = is_circle
+                    it.update()
+                if it._diamond != is_diamond:
+                    it._diamond = is_diamond
+                    it.update()
+        if is_circle:
+            self._layoutPortsOnCircle()
+        elif is_diamond:
+            self._layoutPortsOnDiamond()
+        else:
+            self._layoutPortsAxisAligned()
+
+    def _layoutPortsAxisAligned(self) -> None:
+        """矩形/菱形: 紧凑排列(PORT_MIN_GAP 间距), 围绕 y=0 居中, dot 外缘贴边界、向内。"""
+        rect = self.rect()
+        cy = rect.center().y()
+        for side in ("left", "right"):
+            items = self._port_items[side]
+            n = len(items)
+            if n == 0:
+                continue
+            sizes = [max(1, it.spec.size) for it in items]
+            total = sum(sizes) + (n - 1) * PORT_MIN_GAP
+            running = -total / 2.0  # 整组居中于 y=0
+            for it, s in zip(items, sizes):
+                y = running + s / 2.0
+                running += s + PORT_MIN_GAP
+                ax = self._portAnchorX(side, y, s)
+                it.setPos(QPointF(ax, cy + y))
+
+    def _layoutPortsOnCircle(self) -> None:
+        """圆形: 端口分布在左右侧弧(CIRCLE_PORT_WINDOW_DEG 窗口, 避开极点),
+        dot 放置在圆上并对准圆心(底边贴合该处切线)。"""
+        rect = self.rect()
+        cx, cy = rect.center().x(), rect.center().y()
+        R = rect.width() / 2.0
+        W = CIRCLE_PORT_WINDOW_DEG
+        max_step = CIRCLE_PORT_MAX_STEP_DEG
+        for side in ("left", "right"):
+            items = self._port_items[side]
+            n = len(items)
+            if n == 0:
+                continue
+            center_deg = 180.0 if side == "left" else 0.0
+            if n == 1:
+                offs = [0.0]
+            else:
+                step = min(max_step, (2.0 * W) / (n - 1))
+                offs = [(i - (n - 1) / 2.0) * step for i in range(n)]
+            for it, off in zip(items, offs):
+                th = math.radians(center_deg + off)
+                x = cx + R * math.cos(th)
+                y = cy + R * math.sin(th)
+                it._orient_angle = center_deg + off + 180.0
+                it.setPos(QPointF(x, y))
+                it.update()
+
+    def _layoutPortsOnDiamond(self) -> None:
+        """菱形: 端口沿左/右两条斜边贴合排布, dot 旋转使底边贴合斜边、
+        apex 沿斜边内法线(指向节点内部), 出射方向沿斜边外法线。
+
+        每侧(right/left)对应两条斜边(上、下), 总弧长 2L(L=单条斜边长)。
+        端口沿弧长以 PORT_MIN_GAP 紧凑排布, 整组围绕侧顶点(右顶点/左顶点,
+        即赤道)居中。**所有四个顶点(top/side/bottom 及对侧顶点)附近都预留
+        顶点间隙**, 故端口自然落在斜边中段, 不压在任何菱角上。
+
+        注意: 菱形斜边的内法线是**该斜边的常量法线**(垂直于斜边), 而非"指向
+        圆心"的方向 —— 二者仅在斜边中点重合。dot 底边须平行于斜边, 故
+        _orient_angle 必须取斜边内法线方向(使旋转后底边贴合斜边)。
+        """
+        rect = self.rect()
+        cx, cy = rect.center().x(), rect.center().y()
+        hw = rect.width() / 2.0
+        hh = rect.height() / 2.0
+        if hw <= 0 or hh <= 0:
+            return
+        L = math.hypot(hw, hh)  # 单条斜边长
+        # 斜边内法线(指向节点内部, 垂直于斜边)。菱形四条斜边, 内法线方向固定。
+        #   右上(TR: top->right) 斜边方向 (hw, hh), 内法线 (-hh, hw)
+        #   右下(RB: right->bottom) 方向 (-hw, hh), 内法线 (-hh, -hw)
+        #   左下(BL: bottom->left) 方向 (-hw, -hh), 内法线 (hh, -hw)
+        #   左上(LT: left->top) 方向 (hw, -hh), 内法线 (hh, hw)
+        def inward_normal(ix, iy):
+            nl = math.hypot(ix, iy)
+            return (ix / nl, iy / nl) if nl > 1e-6 else (0.0, 0.0)
+
+        NORM_TR = inward_normal(-hh, hw)   # 右上斜边内法线
+        NORM_RB = inward_normal(-hh, -hw)  # 右下斜边内法线
+        NORM_BL = inward_normal(hh, -hw)   # 左下斜边内法线
+        NORM_LT = inward_normal(hh, hw)    # 左上斜边内法线
+
+        # 四个顶点处的弧长预留(像素, 沿弧长方向): 避免端口压在任何菱角上。
+        # top/bottom 顶点处一条斜边交汇, side 顶点处两条斜边交汇, 均需避让。
+        vertex_gap = self._diamondVertexGap()
+        # 弧长参数 s∈[0,2L]: top=0, 侧顶点=L, bottom=2L。
+        # 每条斜边的中段 = [vertex_gap, L-vertex_gap](上) / [L+vertex_gap, 2L-vertex_gap](下)。
+        # 端口按"上半斜边优先填满"分配到上下两条斜边: 前 n_up 个走上半,
+        # 其余走下半。每条斜边内的端口围绕一个**偏向侧顶点的逻辑中点**居中
+        # (t=bias, bias∈(0.5,1)): 既避开四个顶点, 又贴近左右两侧(符合"左右两侧"
+        # 构想), 不会像物理中点那样分散到斜边正中。
+        bias = self._diamondSideBias()  # 逻辑中点在斜边上的参数(0=远端顶点, 1=侧顶点)
+        for side in ("left", "right"):
+            items = self._port_items[side]
+            n = len(items)
+            if n == 0:
+                continue
+            sizes = [max(1, it.spec.size) for it in items]
+            seg_len = max(0.0, L - 2.0 * vertex_gap)
+            # 上半斜边端口数: ceil(n/2); 下半: floor(n/2)
+            n_up = (n + 1) // 2
+            n_lo = n - n_up
+            # 每段内紧凑排布(间距 PORT_MIN_GAP, 超出则压缩); 围绕"逻辑中点"居中。
+            # upper 段: t 沿 [0,1] 从 top 顶点(vertex_gap) 到侧顶点(L-vertex_gap),
+            #   逻辑中点 t=bias -> 段内偏移 bias*seg_len。
+            # lower 段: t 沿 [0,1] 从侧顶点(L+vertex_gap) 到 bottom(2L-vertex_gap),
+            #   逻辑中点(靠近侧顶点) t=1-bias -> 段内偏移 (1-bias)*seg_len。
+            def seg_positions(count: int, seg_sizes: list, center_off: float) -> list:
+                # 返回该段内各端口中心相对于段起点(vertex_gap)的偏移
+                if count == 0:
+                    return []
+                span = sum(seg_sizes) + (count - 1) * PORT_MIN_GAP
+                if span > seg_len and count > 1:
+                    g = max(0.0, (seg_len - sum(seg_sizes)) / (count - 1))
+                else:
+                    g = PORT_MIN_GAP
+                span = sum(seg_sizes) + (count - 1) * g
+                base = center_off - span / 2.0  # 围绕逻辑中点居中
+                offs = []
+                acc = base
+                for sz in seg_sizes:
+                    offs.append(acc + sz / 2.0)
+                    acc += sz + g
+                return offs
+
+            up_offs = seg_positions(n_up, sizes[:n_up], bias * seg_len)
+            lo_offs = seg_positions(n_lo, sizes[n_up:], (1.0 - bias) * seg_len)
+            # 组装每个端口的物理弧长 s, 并钳制到该斜边中段内(双保险: 避开顶点)
+            s_values = []
+            for off in up_offs:
+                off_c = max(0.0, min(seg_len, off))
+                s_values.append(vertex_gap + off_c)            # 上半中段内
+            for off in lo_offs:
+                off_c = max(0.0, min(seg_len, off))
+                s_values.append(L + vertex_gap + off_c)        # 下半中段内
+            for it, s in zip(items, s_values):
+                # s ∈ [0, 2L]; 上半斜边 s∈[0,L](top→侧顶点), 下半 s∈[L,2L](侧顶点→bottom)
+                if side == "right":
+                    if s <= L:
+                        # 上半(TR): top(0,-hh) -> right(+hw,0), t=s/L
+                        t = max(0.0, min(1.0, s / L))
+                        px = cx + hw * t
+                        py = cy + (-hh) + hh * t
+                        nx, ny = NORM_TR
+                    else:
+                        # 下半(RB): right(+hw,0) -> bottom(0,+hh), t=(s-L)/L
+                        t = max(0.0, min(1.0, (s - L) / L))
+                        px = cx + hw + (-hw) * t
+                        py = cy + hh * t
+                        nx, ny = NORM_RB
+                else:  # left
+                    if s <= L:
+                        # 上半(LT): top(0,-hh) -> left(-hw,0), t=s/L
+                        t = max(0.0, min(1.0, s / L))
+                        px = cx + (-hw) * t
+                        py = cy + (-hh) + hh * t
+                        nx, ny = NORM_LT
+                    else:
+                        # 下半(BL): left(-hw,0) -> bottom(0,+hh), t=(s-L)/L
+                        t = max(0.0, min(1.0, (s - L) / L))
+                        px = cx + (-hw) + hw * t
+                        py = cy + hh * t
+                        nx, ny = NORM_BL
+                it._orient_angle = math.degrees(math.atan2(ny, nx))
+                it.setPos(QPointF(px, py))
+                it.update()
+
+    def _diamondSideBias(self) -> float:
+        """菱形每条斜边上端口组的"逻辑中点"参数(0=远端顶点, 1=侧顶点)。
+
+        取 0.7: 端口组偏向侧顶点(左右两角), 体现"左右两侧"的视觉聚类,
+        同时仍处于斜边中段(避开顶点预留区), 不会压在任何菱角上。
+        """
+        return 0.7
+
+    def _diamondVertexGap(self) -> float:
+        """菱形每个顶点处沿弧长预留的间隙(像素)。
+
+        四个顶点(top/底/左/右)处斜边交汇, 法线方向不连续, 端口压在顶点上
+        视觉突兀。预留固定像素间隙使端口落在斜边中段。取 10px: 对常见尺寸
+        的菱形足以避开顶点, 又不过度压缩可用弧长。
+        """
+        return 10.0
+
+    def _portVerticalMargin(self) -> float:
+        """端口纵向分布时避开上下圆角/尖端的边距(相对中心 y=0)"""
+        rect = self.rect()
+        half_h = rect.height() / 2.0
+        if self._shape == NodeShape.RECTANGLE:
+            corner = min(rect.width(), rect.height()) * 0.2
+            return corner + 4.0
+        if self._shape == NodeShape.DIAMOND:
+            return half_h * 0.30
+        # ELLIPSE
+        return half_h * 0.22
+
+    def _portAnchorX(self, side: str, y: float, dot_h: float) -> float:
+        """端口锚点 x(本地坐标): dot 外缘贴在节点当前形状边界上, 向内延伸。
+
+        用 dot 纵向跨度最外侧的 y(更靠近上下边界)计算边界 x, 保证整个 dot
+        纵向跨度都不超出凸形状边界。
+        """
+        rect = self.rect()
+        half_w = rect.width() / 2.0
+        half_h = rect.height() / 2.0
+        y_tip = min(abs(y) + dot_h / 2.0, max(0.0, half_h - 1.0))
+        if self._shape == NodeShape.RECTANGLE:
+            mag = half_w
+        elif self._shape == NodeShape.DIAMOND:
+            mag = half_w * max(0.0, 1.0 - y_tip / half_h) if half_h > 0 else 0.0
+        else:  # ELLIPSE
+            ratio = 1.0 - (y_tip / half_h) ** 2 if half_h > 0 else 1.0
+            mag = half_w * math.sqrt(max(0.0, ratio))
+        return -mag if side == "left" else mag
+
+    # ------------------------------------------------------------------ #
+    # 端口字体刷新
+    # ------------------------------------------------------------------ #
+    def _refreshPortFonts(self) -> None:
+        """节点字体变化后刷新端口文本字号"""
+        for side in ("left", "right"):
+            for item in self._port_items[side]:
+                item.applyNodeFont()
+        self._layoutPorts()
+
+    # ------------------------------------------------------------------ #
+    # 端口 hover(label 显示全部 / solo)
+    # ------------------------------------------------------------------ #
+    def _setAllPortsShowAll(self, on: bool) -> None:
+        for side in ("left", "right"):
+            for item in self._port_items[side]:
+                item.setNodeHoverShowAll(on)
+
+    def _showAllPortLabels(self) -> None:
+        """节点 hover 计时到期: 显示全部端口 label(仅当未悬停某个 dot 时)"""
+        if self._hovered_port_count == 0:
+            self._setAllPortsShowAll(True)
+
+    def _maybeStartPortShowAll(self) -> None:
+        """仅当悬停节点本体(非 dot)时, 才计时显示全部端口 label"""
+        if self._node_hovered and self._hovered_port_count == 0:
+            self._port_label_timer.start()
+        else:
+            self._port_label_timer.stop()
+
+    def _onPortHoverEnter(self, port) -> None:
+        """某个 dot 被悬停: 取消'显示全部', 仅保留该 dot(solo)"""
+        self._hovered_port_count += 1
+        self._port_label_timer.stop()
+        self._setAllPortsShowAll(False)
+
+    def _onPortHoverLeave(self, port) -> None:
+        """离开某个 dot: 若回到节点本体则恢复'显示全部'计时"""
+        self._hovered_port_count = max(0, self._hovered_port_count - 1)
+        self._hover_anchor = None  # 回到本体后重新建立静止锚点
+        self._maybeStartPortShowAll()
+
+    def _resetPortHover(self) -> None:
+        """重置全部端口的 hover 视觉(离开节点时调用)"""
+        self._hovered_port_count = 0
+        self._setAllPortsShowAll(False)
+        for side in ("left", "right"):
+            for item in self._port_items[side]:
+                item.clearHoverVisuals()
+
+    # ------------------------------------------------------------------ #
+    # port 连线拖拽(转发到画布)
+    # ------------------------------------------------------------------ #
+    def _findCanvas(self):
+        """定位本节点所属的 NodeCanvas(通过 scene().views() 查找)。
+
+        连线只存在于画布, 节点/port 本身不持有; 需要 canvas 时调用本方法。
+        返回 ``None`` 表示节点尚未加入场景或所在视图非 NodeCanvas。
+        """
+        from chartflow.node.node_canvas import QNodeCanvas  # deferred: 避免循环导入
+        scene = self.scene()
+        if scene is None:
+            return None
+        for view in scene.views():
+            if isinstance(view, QNodeCanvas):
+                return view
+        return None
+
+    def _onPortDragStart(self, port_graphic, scene_pos) -> None:
+        """某个 dot 被左键按下: 转发到画布开始 port 连线拖拽。
+
+        Args:
+            port_graphic: 被按下的 ``QNodePort``(起点端点)。
+            scene_pos: 按下位置(场景坐标)。
+        """
+        canvas = self._findCanvas()
+        if canvas is not None:
+            canvas._onPortConnectionDragStart(port_graphic, scene_pos)
+
+    # ------------------------------------------------------------------ #
+    # 端口几何辅助(供 _NodeCore._calculateHalfSize 使用)
+    # ------------------------------------------------------------------ #
+    def _hasPorts(self) -> bool:
+        """是否配置了任意端口"""
+        return bool(self._ports_spec.get("left")) or bool(self._ports_spec.get("right"))
+
+    def _halfHeightForPorts(self, rw: float) -> float:
+        """根据端口最密集的一侧计算所需半高(矩形)。
+
+        端口紧凑排列, 间距 PORT_MIN_GAP, 并避开圆角区域(margin = corner + 4)。
+        """
+        max_total = 0.0
+        for side in ("left", "right"):
+            sizes = [max(1, p.size) for p in self._ports_spec.get(side, [])]
+            if not sizes:
+                continue
+            total = sum(sizes) + (len(sizes) - 1) * PORT_MIN_GAP
+            if total > max_total:
+                max_total = total
+        if max_total <= 0:
+            return 0.0
+        # 迭代求解 rh >= max_total/2 + corner + 4, corner = 0.4*min(rw,rh)
+        rh = max_total / 2.0 + 4.0
+        for _ in range(4):
+            corner = 0.4 * min(rw, rh)
+            rh = max_total / 2.0 + corner + 4.0
+        return rh
+
+    def _portInwardExtent(self) -> float:
+        """端口向内占据的横向深度: dot 深度 + HIT_GAP + 最宽 hit 文本宽度。
+
+        取 left/right 两侧中的较大值, 用于在计算宽度时为 hit 预留空间。
+        """
+        hit_font = self._hitFont()
+        max_extent = 0.0
+        for side in ("left", "right"):
+            ports = self._ports_spec.get(side, [])
+            if not ports:
+                continue
+            max_depth = max(port_depth(p) for p in ports)
+            max_hit_w = 0.0
+            for p in ports:
+                if p.hit:
+                    w = self._textWidth(p.hit, hit_font)
+                    if w > max_hit_w:
+                        max_hit_w = w
+            extent = max_depth + HIT_GAP + max_hit_w
+            if extent > max_extent:
+                max_extent = extent
+        return max_extent
+
+    def _circlePortRadius(self) -> float:
+        """圆形节点为容纳端口所需的半径(按侧弧窗口长度容纳紧凑排列的端口)"""
+        w_rad = math.radians(CIRCLE_PORT_WINDOW_DEG)
+        denom = 2.0 * w_rad if w_rad > 0 else 1.0
+        max_total = 0.0
+        for side in ("left", "right"):
+            sizes = [max(1, p.size) for p in self._ports_spec.get(side, [])]
+            if not sizes:
+                continue
+            total = sum(sizes) + (len(sizes) - 1) * PORT_MIN_GAP
+            if total > max_total:
+                max_total = total
+        return max_total / denom if max_total > 0 else 0.0

chartflow/node/_port_interface.py

@@ -0,0 +1,111 @@
+"""
+端口项接口契约模块
+
+定义 IQNodePort(Protocol) —— 端口渲染项的对外类型契约。
+Protocol 仅用于静态类型检查与文档, 不参与运行时继承(不进入 MRO),
+因此可安全地与 QGraphicsObject 继承体系并存。
+
+IQNodePort 声明了 QNodePort(原 _PortGraphic) 对外暴露的全部公开属性与方法签名,
+是端口渲染项的"契约说明"。具体实现 QNodePort 在运行时通过继承
+QGraphicsObject 实现该契约, 但并不显式继承 Protocol。
+
+约定: 本模块只含类型声明, 不得有运行时依赖, 以避免循环导入。
+"""
+
+from typing import Optional, Protocol, runtime_checkable, TYPE_CHECKING
+
+from PyQt6.QtCore import QPointF
+
+if TYPE_CHECKING:
+    from chartflow.node.node_item import QNodeItem
+    from chartflow.node.port_item import QNodePortSpec
+
+
+@runtime_checkable
+class IQNodePort(Protocol):
+    """端口渲染项接口契约
+
+    声明一个端口渲染项(场景中的 dot / hit 文本 / label 文本)应具备的
+    对外属性与方法。具体实现由 :class:`~chartflow.node.port_item.QNodePort`
+    承担(原 ``_PortGraphic`` 公开化)。
+
+    注: Protocol 不参与运行时继承, 实现类无需显式声明 ``class X(IQNodePort)``;
+    只要结构(属性/方法签名)匹配即视为满足契约(结构子类型, duck typing)。
+
+    契约按职责分为若干组:
+
+    - **身份与归属**: :attr:`side` / :attr:`spec` / :attr:`node`
+    - **几何与命中**: :meth:`scenePos` / :meth:`isPointOnDot`
+    - **hover/连线态**: :meth:`setActive` / :meth:`setDropTarget`
+
+    所有坐标默认为 **场景坐标(scene coordinate)**, 几何单位为像素。
+    """
+
+    # ---- 身份与归属 ----
+    @property
+    def side(self) -> str:
+        """端口所在侧(只读), 取值 ``'left'``(input) 或 ``'right'``(output)。
+
+        决定 dot 的默认配色(左侧绿/右侧橙)与文本排布朝向。
+        """
+        ...
+
+    @property
+    def spec(self) -> "QNodePortSpec":
+        """端口的纯数据描述(只读), 返回 :class:`~chartflow.node.port_item.QNodePortSpec`
+        (字段: name / shape / size / hit / label / outline / color)。
+
+        修改 spec 需通过节点重新 ``ports = {...}`` 重建, 而非直接改返回值。
+        """
+        ...
+
+    @property
+    def node(self) -> "QNodeItem":
+        """端口所属的节点(只读)。"""
+        ...
+
+    # ---- 几何与命中 ----
+    def scenePos(self) -> QPointF:
+        """端口锚点(节点边界上)的 **场景坐标**(只读)。
+
+        连线端点锚定时取此点作为该端端点。
+        """
+        ...
+
+    def isPointOnDot(self, scene_pos: QPointF) -> bool:
+        """场景坐标是否落在 dot 的真实几何(非放大的 12px 命中区)内。
+
+        供画布区分"点击 port dot 本身"与"点击节点外环"—— ``shape()`` 为方便
+        hover 故意放大到至少 12px, 会误吞节点外环点击。
+
+        Args:
+            scene_pos: 待判定的场景坐标。
+
+        Returns:
+            ``True`` 落在 dot 真实几何内, ``False`` 否则。
+        """
+        ...
+
+    # ---- hover/连线态 ----
+    def setActive(self, active: bool) -> None:
+        """标记/取消连线进行中的起点态。
+
+        置 ``True`` 时, 即使光标已离开本 port, 描边仍保持(复用 hover 描边视觉);
+        由画布在连线成功或失败后调用 ``setActive(False)`` 清除。
+
+        Args:
+            active: ``True`` 保持起点描边, ``False`` 清除。
+        """
+        ...
+
+    def setDropTarget(self, on: bool) -> None:
+        """标记/取消本 port 作为连线落点(目标端)的高亮态。
+
+        连线拖拽期间画布接管鼠标移动事件, 光标下的目标 port 不会收到
+        hoverEnter/hoverLeave(场景 hover 派发被压制), 故由画布在
+        mouseMoveEvent 中手动命中检测后调用本方法驱动描边与 label。
+
+        Args:
+            on: ``True`` 高亮为落点(并显示 label), ``False`` 取消。
+        """
+        ...