@mx-sose-front/mx-sose-graph 1.0.0

package/src/utils/pinUtils.ts

@@ -0,0 +1,484 @@
+import type { Shape, Bounds } from '../types'
+import { getBounds } from './geom'
+
+const PortKeys = ['OperationalPort']
+/**
+ * 计算点到矩形边的距离
+ */
+function pointToEdgeDistance(
+  point: { x: number; y: number },
+  rect: { x: number; y: number; width: number; height: number },
+  edge: 'top' | 'right' | 'bottom' | 'left'
+): number {
+  const { x, y, width, height } = rect
+  const px = point.x
+  const py = point.y
+
+  switch (edge) {
+    case 'top':
+      return Math.abs(py - y)
+    case 'right':
+      return Math.abs(px - (x + width))
+    case 'bottom':
+      return Math.abs(py - (y + height))
+    case 'left':
+      return Math.abs(px - x)
+    default:
+      return Infinity
+  }
+}
+
+/**
+ * 找到距离鼠标点最近的边
+ */
+export function findNearestEdge(
+  mousePoint: { x: number; y: number },
+  blockBounds: { x: number; y: number; width: number; height: number }
+): 'top' | 'right' | 'bottom' | 'left' {
+  const distances = {
+    top: pointToEdgeDistance(mousePoint, blockBounds, 'top'),
+    right: pointToEdgeDistance(mousePoint, blockBounds, 'right'),
+    bottom: pointToEdgeDistance(mousePoint, blockBounds, 'bottom'),
+    left: pointToEdgeDistance(mousePoint, blockBounds, 'left'),
+  }
+
+  // 找到距离最小的边
+  let nearestEdge: 'top' | 'right' | 'bottom' | 'left' = 'top'
+  let minDistance = distances.top
+
+  for (const [edge, distance] of Object.entries(distances) as Array<['top' | 'right' | 'bottom' | 'left', number]>) {
+    if (distance < minDistance) {
+      minDistance = distance
+      nearestEdge = edge
+    }
+  }
+
+  return nearestEdge
+}
+
+/**
+ * 计算 pin 附着在 block 边缘上的位置（完全贴边，且 pin 在父外侧露出）
+ * 不改变父元素的高宽
+ *
+ * 规则：
+ * - 右边：x = 父.x + 父.width，y 使用当前 pin 的 y（再按父高做约束）
+ * - 左边：x = 父.x - pin.width，y 使用当前 pin 的 y（再按父高做约束）
+ * - 上边：y = 父.y - pin.height，x 使用当前 pin 的 x（再按父宽做约束）
+ * - 下边：y = 父.y + 父.height，x 使用当前 pin 的 x（再按父宽做约束）
+ *
+ * @param pinBounds - pin 的 bounds
+ * @param blockBounds - block 的 bounds
+ * @param mousePoint - 鼠标位置（仅用于判定最近的边）
+ * @returns 计算后的 pin bounds（左上角坐标 + 宽高）
+ */
+export function calculatePinAttachmentPosition(
+  pinShape: Shape,
+  blockBounds: Bounds,
+  mousePoint: { x: number; y: number },
+  _opts?: { overlap?: number }
+): Bounds {
+  const block = getBounds({ bounds: blockBounds })
+  const pin = getBounds(pinShape)
+
+  // 统一取整，避免亚像素导致的视觉缝隙/抖动
+  const bX = Math.round(block.x || 0)
+  const bY = Math.round(block.y || 0)
+  const bW = Math.max(1, Math.round(block.width || 0))
+  const bH = Math.max(1, Math.round(block.height || 0))
+  const pW = Math.max(1, Math.round(pin.width || 100))
+  const pH = Math.max(1, Math.round(pin.height || 40))
+  const pX = Math.round(pin.x || 0)
+  const pY = Math.round(pin.y || 0)
+
+  if (bW === 0 || bH === 0) {
+    return { x: pX, y: pY, width: pW, height: pH }
+  }
+
+  // 找到最近的边（基于鼠标点）
+  const nearestEdge = findNearestEdge(mousePoint, { x: bX, y: bY, width: bW, height: bH })
+  const isPort = PortKeys.includes((pinShape as any).shapeKey)
+
+  // 沿着该边的“平移方向”做范围约束，保证 pin 在该边范围内滑动
+  const clamp = (v: number, min: number, max: number) => Math.min(Math.max(v, min), max)
+
+  // 当 pin 尺寸大于父尺寸时，沿边滑动轴向无法形成 [min,max] 区间，退化为居中
+  const centerXOnEdge = () => bX + (bW - pW) / 2
+  const centerYOnEdge = () => bY + (bH - pH) / 2
+
+  let x = pX
+  let y = pY
+
+  // 用鼠标点来决定沿边方向的位置（新建时 pX/pY 常为 0，导致总贴在左/上角）
+  const mx = Math.round(mousePoint.x)
+  const my = Math.round(mousePoint.y)
+
+  switch (nearestEdge) {
+    case 'top': {
+      // 顶边：pin 完全在父外侧上方露出
+      const minX = bX
+      const maxX = bX + bW - pW
+      if (minX <= maxX) {
+        // 以鼠标为参考，让 pin 在该边“居中于鼠标”（左上为原点，需减半宽）
+        x = clamp(mx - Math.round(pW / 2), minX, maxX)
+      } else {
+        x = Math.round(centerXOnEdge())
+      }
+      y = bY - pH
+      break
+    }
+    case 'right': {
+      // 右边：pin 完全在父外侧右侧露出
+      const minY = bY
+      const maxY = bY + bH - pH
+      x = bX + bW
+      if (minY <= maxY) {
+        y = clamp(my - Math.round(pH / 2), minY, maxY)
+      } else {
+        y = Math.round(centerYOnEdge())
+      }
+      break
+    }
+    case 'bottom': {
+      // 底边：pin 完全在父外侧下方露出
+      const minX = bX
+      const maxX = bX + bW - pW
+      if (minX <= maxX) {
+        x = clamp(mx - Math.round(pW / 2), minX, maxX)
+      } else {
+        x = Math.round(centerXOnEdge())
+      }
+      y = bY + bH
+      break
+    }
+    case 'left': {
+      // 左边：pin 完全在父外侧左侧露出
+      const minY = bY
+      const maxY = bY + bH - pH
+      x = bX - pW
+      if (minY <= maxY) {
+        y = clamp(my - Math.round(pH / 2), minY, maxY)
+      } else {
+        y = Math.round(centerYOnEdge())
+      }
+      break
+    }
+    default: {
+      x = pX
+      y = pY
+    }
+  }
+
+  return {
+    x: Math.round(x),
+    y: Math.round(y),
+    width: pW,
+    height: pH,
+  }
+}
+
+/**
+ * 当拖动 pin 到 block 上时，计算附着位置
+ * 
+ * @param pinShape - pin 的 shape 对象
+ * @param parentBlock - 父 block 的 shape 对象
+ * @param mousePoint - 鼠标位置（本地坐标）
+ * @returns 计算后的 pin bounds
+ */
+export function attachPinToBlock(
+  pinShape: Shape,
+  parentBlock: Shape,
+  mousePoint: { x: number; y: number }
+): Bounds {
+  const blockBounds = getBounds(parentBlock)
+  
+  return calculatePinAttachmentPosition(pinShape, blockBounds, mousePoint)
+}
+
+/**
+ * 吸附 pin 到父图元最近的边上，返回调整后的坐标
+ * 保持“完全贴边且在外侧露出”，不再做向内重叠缝隙处理
+ * @param dropPoint 落点坐标
+ * @param parentShape 父 shape
+ * @param pinShape pin shape
+ * @returns 调整后的 x, y 坐标
+ */
+export function snapPinToParentEdge(
+  dropPoint: { x: number; y: number },
+  parentShape: Shape,
+  pinShape: Shape
+): { x: number; y: number } {
+  const attachedBounds = attachPinToBlock(pinShape, parentShape, dropPoint);
+
+  // 最近边用于判断箭头朝向
+  const nearestEdge = findNearestEdge(dropPoint, getBounds(parentShape))
+
+  // 如果是 Port，则调整其最终位置以使其居中
+  const isPort = PortKeys.includes((pinShape as any).shapeKey)
+  if (isPort) {
+    const parent = getBounds(parentShape)
+    const pin = getBounds(pinShape)
+    const pW = Math.max(1, Math.round(pin.width || 1))
+    const pH = Math.max(1, Math.round(pin.height || 1))
+
+    switch (nearestEdge) {
+      case 'top':
+        attachedBounds.y = parent.y - pH / 2
+        break
+      case 'bottom':
+        attachedBounds.y = parent.y + parent.height - pH / 2
+        break
+      case 'left':
+        attachedBounds.x = parent.x - pW / 2
+        break
+      case 'right':
+        attachedBounds.x = parent.x + parent.width - pW / 2
+        break
+    }
+  }
+
+  // 输出引脚始终朝外，输入引脚始终朝内
+  const isInput = (pinShape as any).shapeKey === 'InputPin'
+  const outward = !isInput
+
+  // 计算箭头方向（up/down/left/right）并写入 direction
+  let arrow: 'up' | 'down' | 'left' | 'right'
+  switch (nearestEdge) {
+    case 'top': arrow = outward ? 'up' : 'down'; break
+    case 'right': arrow = outward ? 'right' : 'left'; break
+    case 'bottom': arrow = outward ? 'down' : 'up'; break
+    case 'left': arrow = outward ? 'left' : 'right'; break
+  }
+  pinShape.direction = arrow
+
+  // 根据方向为 Pin 计算 nameBounds 与 nameStyle（用于 Pin.vue 定位名称）
+  try {
+    const pb = getBounds(pinShape)
+    const W = pb.width || (pinShape as any).bounds?.width || 100
+    const H = pb.height || (pinShape as any).bounds?.height || 40
+    const pad = 4
+    const fontH = Math.max(10, Math.min(14, Math.floor(H * 0.28)))
+
+    const key = String((pinShape as any).shapeKey || '').toLowerCase()
+    const isInputPin = key.includes('input')
+
+    let nx = W / 2
+    let ny = H + pad
+    let anchor: 'start' | 'middle' | 'end' = 'middle'
+    let baseline: 'alphabetic' | 'middle' | 'text-before-edge' | 'text-after-edge' = 'text-before-edge'
+
+    switch (pinShape.direction) {
+      case 'up': {
+        nx = W / 2
+        if (isInputPin) {
+          ny = H + pad
+          baseline = 'text-before-edge'
+        } else {
+          ny = -pad
+          baseline = 'text-after-edge'
+        }
+        anchor = 'middle'
+        break
+      }
+      case 'down': {
+        nx = W / 2
+        if (isInputPin) {
+          ny = -pad
+          baseline = 'text-after-edge'
+        } else {
+          ny = H + pad
+          baseline = 'text-before-edge'
+        }
+        anchor = 'middle'
+        break
+      }
+      case 'left': {
+        ny = H / 2
+        if (isInputPin) {
+          nx = W + pad
+          anchor = 'start'
+        } else {
+          nx = -pad
+          anchor = 'end'
+        }
+        baseline = 'middle'
+        break
+      }
+      case 'right': {
+        ny = H / 2
+        if (isInputPin) {
+          nx = -pad
+          anchor = 'end'
+        } else {
+          nx = W + pad
+          anchor = 'start'
+        }
+        baseline = 'middle'
+        break
+      }
+    }
+
+    ;(pinShape as any).nameBounds = {
+      x: Math.round(nx),
+      y: Math.round(ny),
+      width: 0,
+      height: fontH,
+    }
+    ;(pinShape as any).nameStyle = {
+      ...(pinShape as any).nameStyle,
+      textAnchor: anchor,
+      dominantBaseline: baseline,
+    }
+  } catch {}
+  console.log(dropPoint, attachedBounds)
+
+  // 直接返回“完全贴边并在外侧”的坐标（已在 calculatePinAttachmentPosition 中确定）
+  return { x: Math.round(attachedBounds.x || 0), y: Math.round(attachedBounds.y || 0) };
+}
+
+/**
+ * 仅用于“移动时”的吸附：
+ * - 计算 pin 应贴边后的目标左上角
+ * - 再加上拖拽偏移 dragOffset，返回“应当传给 moveDraggedShape 的指针坐标”
+ * 这样可避免直接把左上角传入导致的位移误差（产生你看到的缝隙）
+ */
+export function snapPinPointerOnMove(
+  pointer: { x: number; y: number },
+  parentShape: Shape,
+  pinShape: Shape,
+  dragOffset?: { x: number; y: number }
+): { x: number; y: number } {
+  const parent = getBounds(parentShape)
+  const pin = getBounds(pinShape)
+  const ox = dragOffset?.x ?? 0
+  const oy = dragOffset?.y ?? 0
+  const right = parent.x + parent.width
+  const bottom = parent.y + parent.height
+  const pW = Math.max(1, Math.round(pin.width || 1))
+  const pH = Math.max(1, Math.round(pin.height || 1))
+  const clamp = (v: number, min: number, max: number) => Math.min(Math.max(v, min), max)
+
+  // 判定鼠标位置相对父元素的区域
+  const above = pointer.y < parent.y
+  const below = pointer.y > bottom
+  const leftOf = pointer.x < parent.x
+  const rightOf = pointer.x > right
+
+  let edge: 'top' | 'right' | 'bottom' | 'left'
+
+  // 核心逻辑：决定吸附到哪条边
+  if (above || below) {
+    // 场景：鼠标在父元素上方或下方
+    if (pointer.x >= parent.x && pointer.x <= right) {
+      // 子场景：鼠标X坐标在父元素宽度内 -> 吸附到上/下边
+      edge = above ? 'top' : 'bottom'
+    } else {
+      // 子场景：鼠标X坐标在父元素宽度外 -> 吸附到左/右边
+      edge = leftOf ? 'left' : 'right'
+    }
+  } else if (leftOf || rightOf) {
+    // 场景：鼠标在父元素左侧或右侧
+    edge = leftOf ? 'left' : 'right'
+  } else {
+    // 场景：鼠标在父元素内部 -> 按最近的边处理
+    edge = findNearestEdge(pointer, parent)
+  }
+
+  // 根据确定的 edge，计算 pin 的最终左上角坐标 (ltx, lty)
+  let ltx = 0, lty = 0
+  const isPort = PortKeys.includes((pinShape as any).shapeKey)
+  console.log(isPort, 111)
+
+  switch (edge) {
+    case 'top': {
+      const minX = parent.x
+      const maxX = parent.x + parent.width - pW
+      ltx = clamp(pointer.x - ox, minX, maxX)
+      lty = isPort ? parent.y - pH / 2 : parent.y - pH
+      break
+    }
+    case 'bottom': {
+      const minX = parent.x
+      const maxX = parent.x + parent.width - pW
+      ltx = clamp(pointer.x - ox, minX, maxX)
+      lty = isPort ? bottom - pH : bottom // NOTE: 按用户要求，port 在下边缘时，y = bottom - pH
+      break
+    }
+    case 'left': {
+      const minY = parent.y
+      const maxY = parent.y + parent.height - pH
+      ltx = isPort ? parent.x - pW / 2 : parent.x - pW
+      lty = clamp(pointer.y - oy, minY, maxY)
+      break
+    }
+    case 'right': {
+      const minY = parent.y
+      const maxY = parent.y + parent.height - pH
+      ltx = isPort ? right - pW / 2 : right
+      lty = clamp(pointer.y - oy, minY, maxY)
+      break
+    }
+  }
+
+  // 设置方向（输出 pin 朝外、输入 pin 朝内）
+  const isInput = (pinShape as any).shapeKey === 'InputPin'
+  const outward = !isInput
+  let arrow: 'up' | 'down' | 'left' | 'right'
+  switch (edge) {
+    case 'top': arrow = outward ? 'up' : 'down'; break
+    case 'right': arrow = outward ? 'right' : 'left'; break
+    case 'bottom': arrow = outward ? 'down' : 'up'; break
+    case 'left': arrow = outward ? 'left' : 'right'; break
+  }
+  pinShape.direction = arrow
+
+  // 同步名称定位（拖动中也更新）
+  try {
+    const W = pW
+    const H = pH
+    const pad = 4
+    const fontH = Math.max(10, Math.min(14, Math.floor(H * 0.28)))
+    const key = String((pinShape as any).shapeKey || '').toLowerCase()
+    const isInputPin = key.includes('input')
+
+    let nx = W / 2
+    let ny = H + pad
+    let anchor: 'start' | 'middle' | 'end' = 'middle'
+    let baseline: 'alphabetic' | 'middle' | 'text-before-edge' | 'text-after-edge' = 'text-before-edge'
+
+    switch (pinShape.direction) {
+      case 'up': {
+        nx = W / 2
+        if (isInputPin) { ny = H + pad; baseline = 'text-before-edge' } else { ny = -pad; baseline = 'text-after-edge' }
+        anchor = 'middle'
+        break
+      }
+      case 'down': {
+        nx = W / 2
+        if (isInputPin) { ny = -pad; baseline = 'text-after-edge' } else { ny = H + pad; baseline = 'text-before-edge' }
+        anchor = 'middle'
+        break
+      }
+      case 'left': {
+        ny = H / 2
+        if (isInputPin) { nx = W + pad; anchor = 'start' } else { nx = -pad; anchor = 'end' }
+        baseline = 'middle'
+        break
+      }
+      case 'right': {
+        ny = H / 2
+        if (isInputPin) { nx = -pad; anchor = 'end' } else { nx = W + pad; anchor = 'start' }
+        baseline = 'middle'
+        break
+      }
+    }
+
+    ;(pinShape as any).nameBounds = { x: Math.round(nx), y: Math.round(ny), width: 0, height: fontH }
+    ;(pinShape as any).nameStyle = { ...(pinShape as any).nameStyle, textAnchor: anchor, dominantBaseline: baseline }
+  } catch {}
+
+  // 返回“应传给 moveDraggedShape 的指针坐标”（pointer = leftTop + dragOffset）
+  return {
+    x: ltx + ox,
+    y: lty + oy,
+  }
+}

package/src/utils/policy.ts

@@ -0,0 +1,212 @@
+import type { CheckNested, NestingConfig, Shape } from '@/types'
+import type { EdgeFlags } from './geom'
+import { eventBus } from '../store/eventBus'
+import { getUuid } from './index'
+// 元素行为策略
+export type ElementPolicy = {
+  draggable: boolean
+  resizable: boolean
+  constrainToDiagram: EdgeFlags
+}
+
+// 默认策略
+export const DEFAULT_POLICY: ElementPolicy = {
+  draggable: true,
+  resizable: true,
+  // 只限制左/上
+  constrainToDiagram: { left: true, top: true },
+}
+
+// 各类型差异化策略
+export const POLICY_BY_TYPE: Record<string, Partial<ElementPolicy>> = {
+  diagram: { draggable: false, resizable: true, constrainToDiagram: {} },
+  shape: { draggable: true, resizable: true, constrainToDiagram: { left: true, top: true } },
+  port: { draggable: true, resizable: false, constrainToDiagram: { left: true, top: true, right: true, bottom: true } },
+  edge: { draggable: false, resizable: false, constrainToDiagram: {} },
+}
+
+// 根据 shape 读取策略
+export function getPolicy(s: any): ElementPolicy {
+  const t = String(s?.shapeType ?? '').trim().toLowerCase()
+  const p = POLICY_BY_TYPE[t] || {}
+  return {
+    ...DEFAULT_POLICY,
+    ...p,
+    constrainToDiagram: { ...DEFAULT_POLICY.constrainToDiagram, ...(p.constrainToDiagram || {}) },
+  }
+}
+
+//判定元素是否可嵌套
+export const nestingConfig: NestingConfig = {
+  // onlyUnderSameType: ['Strategic',],
+  // disallowSameType: ['EnterpriseGoal',],
+  // allowedParents: {
+  //   geopoliticalextenttype: ['capability'],
+  // },
+}
+const getType = (s: any) => String(s?.shapeKey ?? s?.type ?? '').toLowerCase()
+
+export function canNest(
+  child: Shape | null,
+  parent: Shape | null,
+  all: Shape[],
+  cfg: NestingConfig = nestingConfig
+): boolean {
+  if (!child || !parent) return false
+  if (child.id == parent.id) return false
+  const ct = getType(child)
+  const pt = getType(parent)
+  const sameType = ct === pt
+  // 全局禁同类互嵌
+  if (cfg.disallowSameTypeAll) return false
+  // 按类型禁同类互嵌
+  if (cfg.disallowSameTypeAll && sameType) return false
+  if (sameType && cfg.disallowSameType?.map(x => x.toLowerCase()).includes(ct)) return false
+  //  配置化硬规则
+  if (cfg.disallowAsChild?.map(x => x.toLowerCase()).includes(ct)) return false
+  if (cfg.disallowAsParent?.map(x => x.toLowerCase()).includes(pt)) return false
+  if (cfg.onlyUnderSameType?.map(x => x.toLowerCase()).includes(ct) && ct !== pt) return false
+
+  // 子→父 白名单
+  if (cfg.allowedParents?.[ct] && !cfg.allowedParents[ct].map(x => x.toLowerCase()).includes(pt)) {
+    return false
+  }
+  //  父→子 白/黑名单
+  if (cfg.allowedChildren?.[pt] && !cfg.allowedChildren[pt].map(x => x.toLowerCase()).includes(ct)) {
+    return false
+  }
+  if (cfg.rejectChildTypes?.[pt]?.map(x => x.toLowerCase()).includes(ct)) {
+    return false
+  }
+
+  // 容量限制（按父类型；固定 parenShapeId）
+  const parenField = 'parenShapeId' as const
+  if (typeof cfg.maxChildren?.[pt] === 'number') {
+    const pid = parent.id
+    const count = all.filter(s => (s as any)[parenField] === pid).length
+    if (count >= (cfg.maxChildren as any)[pt]) return false
+  }
+
+  // 与现有 policy 对接（
+  const pPol: any = getPolicy(parent)
+  if (Array.isArray(pPol.acceptChildTypes) &&
+    !pPol.acceptChildTypes.map((x: string) => x.toLowerCase()).includes(ct)) return false
+  if (Array.isArray(pPol.rejectChildTypes) &&
+    pPol.rejectChildTypes.map((x: string) => x.toLowerCase()).includes(ct)) return false
+  if (typeof pPol.maxChildren === 'number') {
+    const pid = parent.id
+    const cnt = all.filter(s => (s as any)[parenField] === pid).length
+    if (cnt >= pPol.maxChildren) return false
+  }
+
+  // 父不能是子孙
+  // if (collectDescendantIds(all as any, child.id).includes(parent.id)) return false
+
+  return true
+}
+/** ==================统一的“远端校验工具” ================== */
+/** 画布的类型 key，作为“落到画布”的 parentType */
+export const DIAGRAM_TYPE_KEY = 'diagram'
+
+/** 解析 hover 目标：返回目标 id 与类型（shape 或 diagram） */
+export type NestTarget =
+  | { kind: 'diagram'; parentId: null; parentType: typeof DIAGRAM_TYPE_KEY }
+  | { kind: 'shape'; parentId: string; parentType: string }
+
+export function resolveNestTarget(hoverId: string | null, shapes: Shape[]): NestTarget {
+  if (!hoverId) return { kind: 'diagram', parentId: null, parentType: DIAGRAM_TYPE_KEY }
+  const p = shapes.find(s => s.id === hoverId)
+  if (!p) return { kind: 'diagram', parentId: null, parentType: DIAGRAM_TYPE_KEY }
+  return { kind: 'shape', parentId: p.id, parentType: getType(p) }
+}
+
+/**
+ * 统一入口：先做本地 canNest，再做远端校验。
+ * - hoverId 为空 => 落在画布（parentType = 'diagram'）
+ * - 返回 true 表示“可以放”；返回 false 表示“不能放”（外部直接把 hoverNestable 置 false 即可）
+ */
+export interface CheckNestedResult {
+  ok: boolean;
+}
+/** 组装后端需要的校验参数 */
+// 组装后端需要的校验参数：支持 parent = null（表示画布）
+export const buildCheckNestedPayload = (
+  dragged: Shape | null,
+  parent: Shape | null,   // shape 父级，画布时为 null
+  diagram: Shape | null   // 当前画布
+): CheckNested | null => {
+  // 1. 被拖动图元 和 画布 必须存在
+  if (!dragged || !diagram) return null
+  const modelId =  dragged.modelId || ''
+
+  const modelType = String((dragged as any).shapeKey || '')
+  // 只要存在 inert 字段（不论 true/false），就清空 modelShapeId
+  const hasInertField = Object.prototype.hasOwnProperty.call(dragged as any, 'inert')
+  const modelShapeId = hasInertField ? '' : String((dragged as any).id || '')
+
+  let targetModelType = ''
+  let targetModelShapeId = ''
+
+  if (parent) {
+    // 2. 正常情况：挂到某个父 shape 下面
+    targetModelType = String((parent as any).shapeKey || '')
+    targetModelShapeId = String((parent as any).id || '')
+  } else {
+    // 3. parent 为空 => 落在画布根
+    //    用统一的 DIAGRAM_TYPE_KEY + diagram.id 通知后端“目标是画布”
+    targetModelType = diagram.shapeKey || ''     // 'diagram'
+    targetModelShapeId = String((diagram as any).id || '')
+  }
+
+  const diagramCode = String(
+    (diagram as any)?.shapeKey || (diagram as any)?.diagramCode || ''
+  )
+
+  if (!modelType || !targetModelType || !targetModelShapeId || !diagramCode) return null
+
+  return {
+    modelType,          // 被拖图元类型
+    modelShapeId,       // 被拖图元 id（虚拟节点时可以为空）
+    targetModelType,    // 目标类型：可能是具体 shapeType，或者 'diagram'
+    targetModelShapeId, // 目标 shapeId 或 diagramId
+    diagramCode,        // 当前画布的业务编码
+    modelId,
+  }
+}
+/**
+ *  front 去调后端进行“是否允许嵌套/放置”的校验。
+ * - front 侧约定：收到 'check-nest:req' 后调接口，回 'check-nest:ok' 时携带 { reqId, ok: boolean }
+ * - 若发生异常，front 回 'check-nest:err'；若 front 没回，则超时返回 { ok:false }
+ */
+export const checkNestViaFront = async (
+  dragged: Shape | null,
+  parent: Shape | null,
+  diagram: Shape | null,
+  timeout = 5000
+): Promise<CheckNestedResult> => {
+  const payload = buildCheckNestedPayload(dragged, parent, diagram)
+  if (!payload) return { ok: false }
+
+  const reqId = getUuid()
+
+  return new Promise<CheckNestedResult>((resolve) => {
+    const onOk = (res: { reqId: string; ok: boolean }) => {
+      if (res?.reqId !== reqId) return
+      cleanup(); resolve({ ok: !!res.ok })
+    }
+    const onErr = (res: { reqId: string }) => {
+      if (res?.reqId !== reqId) return
+      cleanup(); resolve({ ok: false })
+    }
+    const cleanup = () => {
+      clearTimeout(tid)
+      eventBus.off('check-nest:ok', onOk)
+      eventBus.off('check-nest:err', onErr)
+    }
+    const tid = setTimeout(() => { cleanup(); resolve({ ok: false }) }, timeout)
+
+    eventBus.emit('check-nest:req', { reqId, payload })
+    eventBus.on('check-nest:ok', onOk)
+    eventBus.on('check-nest:err', onErr)
+  })
+}