@qilitt-mickey/vue3-temp-skill 1.0.8

package/references/data-compare.md

@@ -0,0 +1,501 @@
+# 数据变更对比
+
+编辑页对比「当前值 vs 编辑前原值」：字段高亮、悬停原值提示、变更汇总弹窗、表格行增删改矩阵。
+
+> 示例页面：`src/views/form/moreForm/`（路由 `/form/moreFormAnchor`）  
+> 核心文件：`src/directives/compare/`、`src/store/modules/compareStore.ts`、`src/utils/changeSummaryService.ts`、`ChangeSummaryDialog.vue`
+
+---
+
+## 一、架构总览
+
+```
+页面 provide(oldDataInfo, compareEnabled)
+  └─ 子表单 inject → v-compare / compare-config
+       ├─ 高亮 .is-compare-changed + tooltip「原值:…」
+       └─ useCompareStore.addOrUpdateRecord
+            └─ ChangeSummaryDialog ← ChangeSummaryService.getChangeSummaryData()
+                 └─ 定位：scrollIntoView + data-compare-* DOM 回退
+```
+
+| 层级 | 职责 |
+|------|------|
+| `v-compare` | 读 DOM/Vue 当前值，与 `oldValue` 比（映射后显示值），写样式与 Store |
+| `useCompareStore` | 按模块聚合变更项；去重键 = module+label+context+tableFirstValue+tableRowOrder |
+| `ChangeSummaryService` | 读 Store；元素引用失效时用 `data-compare-label/module` 修复 |
+| `ChangeSummaryDialog` | 字段表 + 表格行矩阵；支持「定位」 |
+
+**对比的是映射后的显示文案**，不是原始 code（除非未配置 map）。空值统一显示为 `空`（`''` / `null` / `undefined` 视为相等）。
+
+---
+
+## 二、页面编排（必须先做）
+
+### 1. 父页 provide
+
+```typescript
+const formData = reactive<DataInfo>({ /* 当前编辑数据 */ })
+const oldDataInfo = ref<DataInfo | null>(null) // 编辑前快照（接口返回后赋值）
+const compareEnabled = ref(true) // true = 修改模式启用对比；新增模式设 false
+
+provide('oldDataInfo', oldDataInfo)
+provide('compareDisabled', compareEnabled) // 历史命名：变量叫 Disabled，语义却是「是否启用」
+
+// 打开编辑：拉取原数据
+async function fetchDetail(id: string) {
+  const res = await getDetailApi({ id })
+  Object.assign(formData, res.data)
+  oldDataInfo.value = cloneDeep(res.data)
+}
+```
+
+> **命名陷阱**：示例里 inject 的 key 是 `compareDisabled`，但 `enabled: compareDisabled` 时 **true 表示对比已启用**。新代码建议本地命名为 `compareEnabled`，provide key 仍用 `compareDisabled` 以兼容现有子组件。
+
+### 2. 子表单 inject
+
+```typescript
+const oldFormInfos = inject('oldDataInfo') as Ref<DataInfo | null>
+const compareDisabled = inject<Ref<boolean>>('compareDisabled', ref(false))
+```
+
+### 3. 变更汇总入口
+
+```vue
+<el-button :disabled="!compareDisabled" @click="showChangeSummary = true">
+  变更汇总
+</el-button>
+<ChangeSummaryDialog
+  v-model="showChangeSummary"
+  :module-order="['基本信息', '项目成员', '项目列表']"
+/>
+```
+
+离开编辑页时建议 `useCompareStoreHook().clearAllRecords()`。
+
+### 4. 嵌套弹窗
+
+弹窗内再 `provide('oldDataInfo', localOld)` / `provide('compareDisabled', …)`，与主表单同一套指令即可（见 `MultiFormDialog.vue`）。
+
+---
+
+## 三、指令 API
+
+### 绑定值 `CompareBindingValue`
+
+| 字段 | 说明 |
+|------|------|
+| `oldValue` | 编辑前原值（必填语义） |
+| `value` | **覆盖当前显示值**（树/级联等用名称字段，不用 code） |
+| `title` | 模块分组名（汇总按此分组；运行时优先于 `module`） |
+| `label` | 字段中文名（汇总列 + DOM `data-compare-label`） |
+| `enabled` | `false` 跳过对比（推荐开关） |
+| `showInSummary` | `false` 只高亮，不进汇总 |
+| `map` | 配合 `.map`：对象映射 `{ 1: '是' }` |
+| `mapArr` | 配合 `.mapArr`：选项映射 / 多选顺序无关比较 |
+| `format` | `(v) => string` 自定义显示 |
+| `tableFirstLabel` | 表格模式：业务主键列名 |
+| `tableFirstValue` | 表格模式：该行业务主键值 |
+| `tableRowStatus` | `I` 新增 / `U` 修改 / `D`\|`B` 删除（强制记入汇总） |
+| `tableRowOrder` | 行序号（与页面顺序一致） |
+
+### 修饰符 / 参数
+
+| 写法 | 作用 |
+|------|------|
+| `v-compare:fieldKey` | `arg` 为字段名（可读性；逻辑不依赖 arg） |
+| `.map` | 使用 `map` 对象做显示映射 |
+| `.mapArr` | 使用 `mapArr`；多选按集合比较（忽略顺序） |
+| `.table` | 表格行上下文，汇总走矩阵视图 |
+
+### 行为摘要
+
+- 变更 → 加 `.is-compare-changed`，悬停全局 tooltip「原值:xxx」
+- 写入 Store；改回原值 → `removeRecordByLabel`
+- DOM 标记：`data-v-compare`、`data-compare-label`、`data-compare-module`（定位回退用）
+- 全局恢复：`window.restoreCompareValue(el, originalValue)`（演示页未接 UI）
+
+---
+
+## 四、控件用法对照（逐类）
+
+### 1. 普通输入 `el-input`
+
+指令挂在组件根上即可。
+
+```vue
+<el-input
+  v-model="formInfos.projectName"
+  v-compare:projectName="{
+    oldValue: oldFormInfos?.projectName,
+    title: props.item.title,
+    label: '项目名称',
+    enabled: compareDisabled,
+  }"
+/>
+```
+
+`showInSummary: false` → 仍高亮，但不进汇总弹窗。
+
+### 2. 文本域 `el-input type="textarea"`
+
+同 `el-input`，挂在输入组件上。
+
+### 3. 日期/时间 `el-date-picker` / `el-time-picker`
+
+**必须包一层 `div` 挂指令**（picker 根节点才稳定可读 DOM）。
+
+```vue
+<div
+  v-compare:planStart="{
+    oldValue: oldFormInfos?.planStart,
+    title: props.item.title,
+    label: '计划开始时间',
+    enabled: compareDisabled,
+  }"
+  class="!w-[100%]"
+>
+  <el-date-picker v-model="formInfos.planStart" type="date" class="!w-[100%]" />
+</div>
+```
+
+适用：`date` / `datetime` / `month` / `year` / `daterange` / `datetimerange` / `time`。  
+范围值会按分隔符拼成字符串再比。
+
+### 4. 本地下拉 `el-select`（单选）→ `.map` + `composeOptions`
+
+```vue
+<el-select
+  v-model="formInfos.projectStatus"
+  v-compare:projectStatus.map="{
+    oldValue: oldFormInfos?.projectStatus,
+    title: props.item.title,
+    label: '项目状态',
+    map: composeOptions(localSelectOptions.projectStatus, 'value', 'label'),
+    enabled: compareDisabled,
+  }"
+>
+  <el-option v-for="s in localSelectOptions.projectStatus" :key="s.value" :label="s.label" :value="s.value" />
+</el-select>
+```
+
+`composeOptions(list, codeKey, labelKey)` → `{ [code]: label }`（见 `src/utils/utils.ts`）。
+
+异步选项列表加载完后同样用 `composeOptions(saleUnitList)`（默认 key 为 `code`/`value`）。
+
+### 5. 多选下拉 `el-select multiple` → `.mapArr`
+
+```vue
+<el-select
+  v-model="formInfos.multiSelectStatus"
+  multiple
+  v-compare:multiSelectStatus.mapArr="{
+    oldValue: oldFormInfos?.multiSelectStatus,
+    title: props.item.title,
+    label: '多选状态',
+    mapArr: composeOptions(localSelectOptions.projectStatus, 'value', 'label'),
+    enabled: compareDisabled,
+  }"
+/>
+```
+
+比较时忽略选项顺序；显示为逗号拼接的中文标签。
+
+### 6. `ReSelectQuery`（异步分页选择）→ props 桥接
+
+模板不能直接写 `v-compare` 时，用组件内置 props（内部 `withDirectives`）。
+
+```vue
+<!-- 单选：oldValue 用名称字段 -->
+<ReSelectQuery
+  v-model="formInfos.asyncSelectUser"
+  :compare-config="{
+    oldValue: oldFormInfos?.asyncSelectUserName,
+    label: '异步单选用户',
+    title: props.item.title,
+    enabled: compareDisabled,
+  }"
+  compare-key="asyncSelectUser"
+  :edit-data="formInfos.single1BackData"
+  url="..."
+  value="userCode"
+  label="userName"
+/>
+
+<!-- 多选 -->
+<ReSelectQuery
+  v-model="formInfos.asyncMultiSelectUser"
+  multiple
+  :compare-config="{
+    oldValue: oldFormInfos?.asyncMultiSelectUserNames,
+    label: '异步多选用户',
+    title: props.item.title,
+    enabled: compareDisabled,
+  }"
+  compare-key="asyncMultiSelectUser"
+  :compare-modifiers="{ mapArr: true }"
+/>
+```
+
+| Prop | 说明 |
+|------|------|
+| `compareConfig` | 同指令 binding value |
+| `compareKey` | 同 `v-compare:key` 的 arg |
+| `compareModifiers` | 如 `{ mapArr: true }` |
+
+### 7. `el-tree-select` → 用 `value` 覆盖显示名
+
+对比名称字符串，不要对比节点 code。
+
+```vue
+<el-tree-select
+  v-model="formInfos.value3"
+  v-compare:value3="{
+    oldValue: oldFormInfos?.value3Name,
+    value: formInfos.value3Name,
+    title: props.item.title,
+    label: '单选树',
+    enabled: compareDisabled,
+  }"
+  :cache-data="formInfos.value3Text"
+  ...
+/>
+
+<!-- 多选树 -->
+v-compare:multiple1.mapArr="{
+  oldValue: oldFormInfos?.multiple1Name,
+  value: formInfos.multiple1Name,
+  title, label, enabled: compareDisabled,
+}"
+```
+
+需在业务里维护 `*Name` / `*Text` 回写字段（与 data-writeback 模块配合）。
+
+### 8. `ReCascader` → 同 ReSelectQuery 桥接 + `value` 名称
+
+```vue
+<ReCascader
+  v-model="formInfos.singleBack"
+  :compare-config="{
+    oldValue: oldFormInfos?.singleBackName,
+    value: formInfos.singleBackName,
+    label: '级联器单选',
+    title: props.item.title,
+    enabled: compareDisabled,
+  }"
+  compare-key="singleBack"
+  @change="getSingleBackName"
+/>
+
+<!-- 多选加 modifiers -->
+:compare-modifiers="{ mapArr: true }"
+```
+
+### 9. `el-checkbox` / `el-switch` → `.map` 布尔/枚举文案
+
+```vue
+<el-checkbox
+  v-model="formInfos.isUrgent"
+  true-value="1"
+  false-value="0"
+  v-compare:isUrgent.map="{
+    oldValue: oldFormInfos?.isUrgent,
+    title: props.item.title,
+    label: '是否紧急',
+    map: { 1: '是', 0: '否' },
+    enabled: compareDisabled,
+  }"
+>
+  紧急项目
+</el-checkbox>
+```
+
+`el-switch` 同理，读取 `active-value` / `inactive-value`。
+
+### 10. `el-radio-group` / `el-checkbox-group` → `.map` / `.mapArr`
+
+```vue
+<el-radio-group
+  v-model="formInfos.approvalStatus"
+  v-compare:approvalStatus.map="{
+    oldValue: oldFormInfos?.approvalStatus,
+    title: props.item.title,
+    label: '审批状态',
+    map: composeOptions(options, 'value', 'label'),
+    enabled: compareDisabled,
+  }"
+>
+  <el-radio v-for="o in options" :key="o.value" :value="o.value">{{ o.label }}</el-radio>
+</el-radio-group>
+
+<el-checkbox-group
+  v-model="formInfos.tags"
+  v-compare:tags.mapArr="{
+    oldValue: oldFormInfos?.tags,
+    title: props.item.title,
+    label: '标签',
+    mapArr: composeOptions(tagOptions, 'value', 'label'),
+    enabled: compareDisabled,
+  }"
+>
+  ...
+</el-checkbox-group>
+```
+
+### 11. `el-input-number` / `el-rate` → `format`
+
+```vue
+<el-input-number
+  v-model="formInfos.completionRate"
+  v-compare:completionRate="{
+    oldValue: oldFormInfos?.completionRate,
+    title: props.item.title,
+    label: '完成率',
+    enabled: compareDisabled,
+    format: (v) => (v === null || v === undefined || v === '' ? '未设置' : `${v}%`),
+  }"
+/>
+
+<el-rate
+  v-model="formInfos.projectRating"
+  v-compare:projectRating="{
+    oldValue: oldFormInfos?.projectRating,
+    title: props.item.title,
+    label: '项目评分',
+    enabled: compareDisabled,
+    format: (v) => (v == null || v === '' ? '未评分' : `${v}分`),
+  }"
+/>
+```
+
+---
+
+## 五、表格行对比（`.table`）
+
+### 行标志约定
+
+| `flag` / `tableRowStatus` | 含义 | 行样式（`getRowClassByFlag`） | 汇总 |
+|---------------------------|------|------------------------------|------|
+| `I` | 新增 | `row-added` | 记入；类型「新增」 |
+| `U` | 修改 | `row-modified` | 按字段 diff |
+| `D` / `B` | 删除 | `row-deleted` | **强制记入**（值相等也保留） |
+
+```vue
+<el-table :data="formInfos.projectList" :row-class-name="({ row }) => getRowClassByFlag(row?.flag)">
+  <el-table-column label="项目公司">
+    <template #default="{ row, $index }">
+      <el-input
+        v-model="row.companyManager"
+        :disabled="row.flag === 'D' || row.flag === 'B'"
+        v-compare:companyManager.table="{
+          oldValue: oldFormInfos?.projectList?.[$index]?.companyManager,
+          title: props.item.title,
+          label: '项目公司',
+          tableFirstLabel: '名称',
+          tableFirstValue: row.name,
+          tableRowStatus: row.flag,
+          tableRowOrder: $index,
+          enabled: compareDisabled,
+        }"
+      />
+    </template>
+  </el-table-column>
+</el-table>
+```
+
+要点：
+
+- 每个可编辑列都挂 `.table`，共用同一 `tableFirstValue` / `tableRowOrder`
+- `tableFirstLabel` + `tableFirstValue` 决定汇总矩阵「业务名称」列
+- 新增行 `oldValue` 可为空；删除行即使字段未改也会进汇总
+
+---
+
+## 六、变更汇总
+
+### Store
+
+```typescript
+import { useCompareStoreHook } from '@/store/modules/compareStore'
+
+const store = useCompareStoreHook()
+store.getChangeSummaryData   // 按 module 分组
+store.getStatsNum            // { total, modules }
+store.clearAllRecords()
+store.clearModuleRecords(module)
+```
+
+### Service
+
+```typescript
+import { ChangeSummaryService } from '@/utils/changeSummaryService'
+
+const data = ChangeSummaryService.getChangeSummaryData()
+// 自动修复失效 element；失败则 DOM 回退扫描 [data-v-compare]
+```
+
+### Dialog
+
+```vue
+<ChangeSummaryDialog
+  v-model="visible"
+  :module-order="moduleTitles"  // 可选：模块展示顺序
+/>
+```
+
+- 普通字段：模块标题 + 表（字段 / 原值 / 新值 / 定位）
+- `.table` 项：按行折叠为矩阵（变更类型 + 各列旧→新）
+- 定位：`scrollIntoView` + 临时类 `locate-highlight`；引用失效时用  
+  `[data-v-compare][data-compare-label="…"][data-compare-module="…"]`  
+  （`escapeAttrSelector` 防特殊字符）
+
+可复制 `src/views/form/moreForm/ChangeSummaryDialog.vue` 到业务模块，或抽到 `components/`。
+
+---
+
+## 七、封装组件内挂指令（TSX/render）
+
+```typescript
+import { resolveDirective, withDirectives } from 'vue'
+
+const compareDirective = resolveDirective('compare')
+return withDirectives(vnode, [[
+  compareDirective,
+  compareConfig,
+  compareKey,
+  compareModifiers || {},
+]])
+```
+
+`ReSelectQuery` / `ReCascader` 已实现；新封装选择器应同样暴露三件套 props。
+
+---
+
+## 八、生成检查清单
+
+- [ ] 父页 `provide` 了 `oldDataInfo` + 启用开关；编辑拉取后写入 `oldDataInfo`
+- [ ] 新增模式 `enabled: false`；修改模式 `enabled: true`
+- [ ] 每个对比字段有稳定 `title`（模块）+ `label`（字段名）
+- [ ] 码值类控件用了 `.map` / `.mapArr` + `composeOptions`（或等价 map）
+- [ ] 日期类指令挂在外层 `div`，不是直接挂在 picker 不稳定节点
+- [ ] 树/级联/异步选择对比的是 **名称**（`oldValue`/`value` 用 `*Name`）
+- [ ] `ReSelectQuery`/`ReCascader` 用 `compare-config` + `compare-key`，多选加 `compare-modifiers.mapArr`
+- [ ] 表格列用 `.table` + `tableFirst*` + `tableRowStatus` + `tableRowOrder` + `getRowClassByFlag`
+- [ ] 接了汇总弹窗；离开页 `clearAllRecords`
+- [ ] 未使用文档里的错误写法：`newValue`（不存在）、数值比较数组语法（那是错误旧文档）
+
+---
+
+## 九、关联资产
+
+| 路径 | 说明 |
+|------|------|
+| `src/directives/compare/index.ts` | 指令实现 |
+| `src/directives/compare/types.ts` | 类型 |
+| `src/directives/compare/styles.css` | 高亮与 tooltip |
+| `src/store/modules/compareStore.ts` | 变更 Store |
+| `src/utils/changeSummaryService.ts` | 汇总读取/修复 |
+| `src/utils/utils.ts` | `composeOptions` / `getRowClassByFlag` / `escapeAttrSelector` |
+| `src/views/form/moreForm/*` | 完整示例 |
+| `ReSelectQuery` / `ReCascader` | 指令 props 桥接 |
+
+相关模块：`data-writeback`（名称回写）、`directives-advanced`（其它指令）、`crud-pages` / `detail-page`（编辑页骨架）。

package/references/data-mapping.md

@@ -0,0 +1,213 @@
+# JsPlumb 数据映射
+
+## 依赖
+
+`jsplumb` — 拖拽连线、字段映射组件。
+
+## 页面结构
+
+```vue
+<script setup lang="ts">
+import { jsPlumb } from 'jsplumb'
+import { message } from '@/utils/message'
+
+defineOptions({ name: 'FieldMapping' })
+
+interface Field {
+  id: string
+  name: string
+  type: string
+  value?: string
+}
+
+const sourceFields = ref<Field[]>([
+  { id: 'src_1', name: 'id', type: 'int', value: '1001' },
+  { id: 'src_2', name: 'organizationid', type: 'int', value: 'ORG_01' },
+  { id: 'src_3', name: 'brand_id', type: 'int' },
+  { id: 'src_4', name: 'source', type: 'string' },
+])
+
+const targetFields = ref<Field[]>([
+  { id: 'target_1', name: 'id', type: 'BIGINT', value: '' },
+  { id: 'target_2', name: 'pid', type: 'BIGINT', value: '' },
+  { id: 'target_3', name: 'tn_id', type: 'BIGINT' },
+  { id: 'target_4', name: 'vpdm', type: 'STRING' },
+])
+
+let jsPlumbInstance: any = null
+</script>
+```
+
+## 初始化 jsPlumb
+
+```typescript
+const initJsPlumb = () => {
+  jsPlumbInstance = jsPlumb.getInstance({
+    // 连接线：Straight(直线) / Bezier(贝塞尔) / Flowchart(折线) / StateMachine(状态机)
+    Connector: ['Straight', { stub: 0, gap: 1 }],
+    PaintStyle: { stroke: '#409eff', strokeWidth: 2 },
+    HoverPaintStyle: { stroke: '#66b1ff', strokeWidth: 3 },
+    Endpoint: ['Dot', { radius: 6 }],
+    EndpointStyle: { fill: 'transparent', stroke: 'transparent' },
+    EndpointHoverStyle: { fill: '#fff', stroke: '#66b1ff' },
+    Container: 'mapping-container', // 必须指定容器 ID
+    ConnectionOverlays: [
+      ['Arrow', {
+        width: 10, length: 10, location: 1,
+        id: 'arrow', foldback: 0.8,
+      }],
+    ],
+    ConnectionsDetachable: true,   // 允许拖动重连
+    ReattachConnections: false,
+  })
+
+  // 点击连线删除
+  jsPlumbInstance.bind('click', (conn: any) => {
+    jsPlumbInstance.deleteConnection(conn)
+  })
+
+  // 注册源和目标
+  nextTick(() => {
+    sourceFields.value.forEach((item) => {
+      jsPlumbInstance.makeSource(item.id, {
+        anchor: 'Right',
+        allowLoopback: false,
+        maxConnections: 1,
+        filter: 'input, select, textarea, .el-input, .el-select',
+        filterExclude: true,
+      })
+    })
+    targetFields.value.forEach((item) => {
+      jsPlumbInstance.makeTarget(item.id, {
+        anchor: 'Left',
+        allowLoopback: false,
+        maxConnections: 2,
+      })
+    })
+  })
+}
+```
+
+## 常用操作
+
+```typescript
+// 同行映射（按顺序一一对应）
+const handleSameLineMapping = () => {
+  jsPlumbInstance.deleteEveryConnection()
+  const len = Math.min(sourceFields.value.length, targetFields.value.length)
+  for (let i = 0; i < len; i++) {
+    jsPlumbInstance.connect({
+      source: sourceFields.value[i].id,
+      target: targetFields.value[i].id,
+    })
+  }
+}
+
+// 清空所有连线
+const clearAll = () => {
+  jsPlumbInstance.deleteEveryConnection()
+}
+
+// 获取映射结果
+const getMappingResult = () => {
+  const connections = jsPlumbInstance.getAllConnections()
+  return connections.map((conn: any) => ({
+    source: sourceFields.value.find(f => f.id === conn.sourceId),
+    target: targetFields.value.find(f => f.id === conn.targetId),
+  }))
+}
+```
+
+## 模板结构
+
+```vue
+<template>
+  <div class="mapping-page p-4 flex flex-col">
+    <!-- 操作栏 -->
+    <el-card shadow="never" class="mb-4">
+      <div class="flex justify-center gap-4 mt-4">
+        <el-button @click="handleSameLineMapping">同行映射</el-button>
+        <el-button type="danger" plain @click="clearAll">清空所有</el-button>
+        <el-button type="primary" @click="getMappingResult">保存映射</el-button>
+      </div>
+    </el-card>
+
+    <!-- 映射区域 -->
+    <div id="mapping-container" class="flex-1 relative flex justify-between bg-white p-8">
+      <!-- 左侧源字段 -->
+      <div class="w-[40%] flex flex-col border rounded">
+        <div v-for="item in sourceFields" :id="item.id" :key="item.id"
+          class="field-item flex border-b hover:bg-gray-50 cursor-pointer relative">
+          <div class="flex-1 p-2">{{ item.name }}</div>
+          <div class="w-[80px] p-2 text-center">{{ item.type }}</div>
+          <!-- 连接点 -->
+          <div :id="`handle-${item.id}`"
+            class="connector-handle-right absolute right-0 top-1/2 -mt-[6px] translate-x-1/2" />
+        </div>
+      </div>
+
+      <!-- 中间留白给连线 -->
+      <div class="w-[20%]" />
+
+      <!-- 右侧目标字段 -->
+      <div class="w-[40%] flex flex-col border rounded">
+        <div v-for="item in targetFields" :id="item.id" :key="item.id"
+          class="field-item flex border-b hover:bg-gray-50 cursor-pointer relative">
+          <div :id="`handle-${item.id}`"
+            class="connector-handle-left absolute left-0 top-1/2 -mt-[6px] -translate-x-1/2" />
+          <div class="flex-1 p-2">{{ item.name }}</div>
+          <div class="w-[80px] p-2 text-center">{{ item.type }}</div>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+```
+
+## 样式
+
+```scss
+.connector-handle-right,
+.connector-handle-left {
+  z-index: 10;
+  width: 12px;
+  height: 12px;
+  background-color: #fff;
+  border: 1px solid #409eff;
+  border-radius: 50%;
+}
+.connector-handle-right:hover,
+.connector-handle-left:hover {
+  background-color: #e6f7ff;
+  border-color: #1890ff;
+}
+:deep(.jtk-endpoint) { z-index: 20; }
+:deep(.jtk-connector) { z-index: 10; }
+:deep(.jtk-connector.jtk-hover) { z-index: 30; }
+```
+
+## 生命周期
+
+```typescript
+onMounted(() => {
+  nextTick(() => initJsPlumb())
+})
+
+onUnmounted(() => {
+  jsPlumbInstance?.reset()
+})
+```
+
+## 关键约定
+
+1. `Container` 必须指定为映射区域的 DOM ID，否则连线定位错误。
+2. 源端点用 `makeSource`，目标端点用 `makeTarget`，锚点分别在 `Right` 和 `Left`。
+3. `filter` 排除表单元素，避免点击输入框时触发连线拖动。
+4. 连线删除通过 `bind('click')` 事件实现，点击连线即删除。
+5. `onUnmounted` 中必须调用 `jsPlumbInstance.reset()` 清理。
+6. 字段行必须有唯一 `id`，jsPlumb 通过 ID 绑定源/目标。
+7. 中间留白区域（`w-[20%]`）给连线绘制空间。
+
+## 关联文件
+
+- [src/views/workflow/jsplumb/index.vue](file:///e:/work/vue3-web-temp/src/views/workflow/jsplumb/index.vue)