diff --git a/docs/reports/2026-07-20-npm-designer-quality-report.md b/docs/reports/2026-07-20-npm-designer-quality-report.md
new file mode 100644
index 0000000000000000000000000000000000000000..3e03c09873e77c77bffbf9c9bdf6152fd838c4dd
--- /dev/null
+++ b/docs/reports/2026-07-20-npm-designer-quality-report.md
@@ -0,0 +1,254 @@
+<!-- 由代码质量审查任务生成（2026-07-20，分支 feature-ui-npm）。
+     纯只读审查产物（含 tsc 探针/产物实测）；Top 级发现已由主流程抽查核实
+     （dist-lib 缺 FlowDesigner.vue.d.ts、body overflow 未恢复、window._markDrawer* 未清理）。
+     注：报告审查基线早于本日 IJVBTJ/IJV7GC 修复提交，行号可能有 ±20 行漂移。 -->
+
+# warm-flow-vue-designer 只读质量审查报告
+
+审查对象：`warm-flow-vue-designer`（`@dromara/warm-flow-designer` v1.8.2，工作树含未提交改动）+ 三个 demo + 与 `warm-flow-ui` 基线的关系。所有结论均基于当前代码与 `dist-lib` 产物的实际检查（含 tsc 探针实测），未做任何修改。
+
+---
+
+## 一、缺陷（bug）
+
+### 发布面 / 类型
+
+**1.【P1】`FlowDesigner` 组件在发布类型中退化为 `any`**
+【文件】`dist-lib/src/designer/index.d.ts:2` ← `dist-lib/src/components/design/` 缺 `FlowDesigner.vue.d.ts`
+【问题】主入口 d.ts `import { default as FlowDesigner } from '../components/design/FlowDesigner.vue'`，但 dts 产物只有 `FlowDesignerHeader/Toolbar.vue.d.ts`，`FlowDesigner.vue.d.ts` 未生成（同批缺失：`selectUser.vue`、`nodeExtList.vue`、`UserPicker*.vue`、`plugins/modal.ts`、`store/index.ts`）。已用 tsc 探针实测：`const n: number = FlowDesigner` 编译通过（应报 TS2322），即旗舰组件 props/事件对消费方全部失去类型。`todo.md`「发布类型退化为 any——已修复」的验证只覆盖了类型导出（`FlowDesignerInstance` 等），没覆盖组件本体。
+【建议】排查 vite-plugin-dts 对这批文件静默跳过 emit 的原因（大概率文件内 TS 诊断错误，如 `proxy.$refs.*` 调用链）；修复后在 `build:lib` 加「d.ts 覆盖率断言」（对比 src 文件清单与 dist-lib 产物清单），防回归。
+
+**2.【P2】`package.json` 声明 `vue-router` 为必选 peer，但库零引用**
+【文件】`warm-flow-vue-designer/package.json:72`
+【问题】`src/` 与 `dist-lib/warm-flow-designer.es.js` 均无 vue-router import（实测产物外部 import 仅 `vue/pinia/@logicflow/*`）。消费方被迫安装无用 peer；三个 demo 的 `dependencies` 也跟着带上了。
+【建议】从 peerDependencies/devDependencies/README:233/demo 依赖中移除。
+
+**3.【P3】`file-saver` 声明为打包运行时依赖但源码零使用**
+【文件】`package.json:96`；模块 `AGENTS.md` 也写「file-saver 导出」
+【问题】`rg file-saver|saveAs` 在 `src/` 无命中（`downJson` 用手写 `<a download>` 实现，`useLogicFlowCanvas.ts:664-676`）。死依赖 + 文档漂移。
+【建议】删除依赖并同步 AGENTS。
+
+**4.【P3】ESM-only 形态与 `sideEffects` 风险**
+【文件】`package.json:19-47`
+【问题】无 `main`、exports 无 `require` 条件（ESM-only 是可接受决策但 README 未声明）；`sideEffects: ["**/*.css"]` 把 JS 全部标记为无副作用，而主入口 import 时执行 `addCollection(epIcons/wfIcons)`（`src/icons/index.ts:15-16`）注册图标，理论上在激进 tree-shake 场景可被裁剪。其余方面 exports/types/style 路径与 dist-lib 实物一一对上（已核）。
+【建议】README 标注 ESM-only；将图标注册改为 `install()` 内显式调用，或在 sideEffects 中补主入口文件。
+
+### 运行时逻辑 / 内存泄漏
+
+**5.【P1】卸载后不恢复 `document.body.style.overflow`，宿主页面永久失去滚动**
+【文件】`src/components/design/FlowDesigner.vue:343`（`onMounted` 设 `hidden`）、`420-423`（`onUnmounted` 只复位 `__WF_FLOW_DESIGN_MODE__`）
+【问题】作为 npm 组件嵌入业务系统时，关闭设计器后整页不能滚动。`docs/warm-flow-npm-refactoring-plan.md` C8 早已规划「NPM 场景条件化」，未落地。
+【建议】mount 时记录原值、unmount 恢复；或按 C8 仅 iframe（`window.parent !== window`）场景设置。
+
+**6.【P1】`window._markDrawerOpen/_markDrawerClosed` 挂载后永不清理（内存泄漏 + 多实例互踩）**
+【文件】`src/composables/useLogicFlowCanvas.ts:244-258`（赋值）、`694-698`（onUnmounted 只移除 resize 与 `__WF_DESIGNER_DISABLED__`）
+【问题】闭包持有 `lf`/`containerRef`，组件卸载后 LogicFlow 实例与 DOM 不能被回收；两个设计器实例并存时后挂载者覆盖前者。同族问题：`window.__WF_FLOW_DESIGN_MODE__`（FlowDesigner.vue:345/422，卸载置 `false` 而非恢复，多实例互踩）、`window.isTooltipHovered`（EdgeTooltip.vue:64-68）。
+【建议】unmount 时删除回调；根治方案是抽屉状态经 props/事件或模块级注册表传递，放弃 window 通道。
+
+**7.【P2】`propertySetting.vue` 匿名 resize 监听器永不解绑**
+【文件】`src/components/design/common/vue/propertySetting.vue:42-44`
+【问题】setup 时 `window.addEventListener('resize', () => …)`，无对应 remove（对照 `baseInfo.vue:152-163` 是成对的）。每次挂载泄漏一个监听器与组件引用。
+【建议】`onUnmounted` 解绑，或用 `useWindowWidth` 类小 composable 统一管理（`between.vue:656-659`、`useUserPicker.ts:47` 还有多处 `window.innerWidth` 一次性读取，行为也不响应）。
+
+**8.【P2】`between.vue` 校验链两处失效：`slice` 恒空 + Promise 竞态**
+【文件】`src/components/design/common/vue/between.vue:686`、`670-683`（`warm-flow-ui/src/.../between.vue:708` 同病，属复制继承）
+【问题】① `tabsList.value.slice(tabsList.value.length)` 永远返回 `[]`，「扩展页签（type=2 节点扩展）必填校验」是死代码；② `validate()` 中 `formRef.validate(callback)` 的异步 `reject` 与同步 `tabsValidate → resolve(true)` 赛跑，后端无节点扩展数据时（`nodeBase` 不存在）主表单校验结果被直接绕过——票签比例、监听器必填在关抽屉时可能不拦截。
+【建议】`slice(3)`（或记录初始 tab 数）；`await` Promise 形态的 validate 后再串行执行 tabs 校验。
+
+**9.【P2】`json2LogicFlowJson` 对缺省 `nodeRatio` 直接崩溃，demo 在替库兜底**
+【文件】`src/components/design/common/js/tool.ts:59`（`node.nodeRatio.toString()`）；佐证 `warm-flow-designer-demo/warm-flow-ep-designer-demo/demoProvider.ts:98-106`（注释明说「避免 …undefined.toString() 崩溃（如 nodeRatio）」）
+【问题】`initialJson` / `v-model:json` 是新的公开契约，消费方手写 JSON 少个 `nodeRatio` 字段组件即抛 TypeError 白屏。
+【建议】库内 `String(node.nodeRatio ?? '0')` 兜底，demo 的规范化逻辑随之删除。
+
+**10.【P2】`request.ts` 请求拦截器错误分支吞错**
+【文件】`src/utils/request.ts:68-70`
+【问题】`error => { Promise.reject(error) }` 缺 `return`，拦截器错误被吞、请求链以 undefined 继续（ruoyi 继承 bug）。另：line 45 `Object.keys(JSON.stringify(...)).length` 求字符串长度的写法晦涩；响应拦截器 `getUiAdapter()` 在未注册适配器时会抛错掩盖原始网络错误。
+【建议】补 `return Promise.reject(error)`；长度用 `.length`。
+
+**11.【P2】`FlowDesigner` 保存链路无 catch + `JSON.parse` 无防护**
+【文件】`src/components/design/FlowDesigner.vue:494-514`（`saveJson(...).then(...).finally(...)` 无 `.catch` → unhandled rejection）、`354`（`JSON.parse(localSource)` 对非法字符串直接抛出导致挂载失败）
+【建议】补 catch（保存失败提示）与 try/catch（进入 `isEmpty` 空态）。
+
+**12.【P3】`eventCenter.on('edge:click  ', …)` 事件名带两个尾随空格**
+【文件】`src/components/design/FlowDesigner.vue:602`
+【问题】恰好 LogicFlow 内部对事件名做 `split(',') + trim()`（已在 `@logicflow/core` min 包实测）才得以工作，极脆弱。
+【建议】去掉空格。
+
+**13.【P3】`propertySetting.vue` 跨选中切换时 watcher 误发**
+【文件】`src/components/design/common/vue/propertySetting.vue:206-213`（`nodeName` watcher 无节点类型 guard）对照 `271-280`（`skipName` watcher 有 `['skip'].includes(...)` guard）
+【问题】节点→边切换时会对边执行 `updateText(edgeId, undefined)` 与 `setProperties({nodeName: undefined})`，靠后注册的 `skipName` watcher 顺序恢复文本，属侥幸正确。
+【建议】所有 watcher 按 `props.node.type` 对称加 guard，或改为显式表单提交而非 12 个细粒度 watcher。
+
+### UI 适配层（三适配器对齐）
+
+28 个语义键三家均已注册（已逐一核对 elementPlusAdapter:71-100 / antdvAdapter:718-748 / naiveAdapter:770-799，无键位缺失），但行为面有实际缺口：
+
+**14.【P2】非 EP 适配器下 ref 方法转发缺失 → 运行时 TypeError**
+【文件】`src/components/design/common/vue/start.vue:129`、`end.vue:50`（`proxy.$refs.nodeInput.focus()`）；`UserPickerTree.vue:94-95`（`treeRef.value?.filter(value)` / `setCurrentKey`）；根因 `src/ui/antdvAdapter.ts:118-140`（AntInput）、`568-588`（AntTree）、naive 同构——包装组件均未 `expose` `focus/filter/setCurrentKey`，而 `createNeutralComponent.ts:27-43` 的 ref 代理只能转发到包装组件实例。
+【问题】antd/naive 下：开始/结束节点名称输入触发 `change` 即抛 `focus is not a function`（antd 的 a-input `change` 每击键触发一次）；人员选择弹窗部门搜索框输入即抛 `filter is not a function`，且 `filter-node-method` 语义本身未翻译（部门过滤在非 EP 下不可用）。
+【建议】适配器包装组件统一 `expose` 常用方法（focus/blur/filter/setCurrentKey…）转发内层实例；树过滤在 antd/naive 侧用受控 `filteredData`/`pattern` 实现。
+
+**15.【P2】naive 抽屉丢弃 `before-close` → 关抽屉前校验与节点编码改名链路失效**
+【文件】`src/ui/naiveAdapter.ts:529`（把 `before-close` 直接 delete，`onUpdate:show` 直改 v-model）对照 `antdvAdapter.ts:505-516`（映射为 `onClose`）、EP 原生支持；消费点 `propertySetting.vue:11`（`:before-close="handleClose"`，内含表单校验 + `changeNodeId/changeEdgeId`）
+【问题】naive 下点遮罩/关闭按钮直接关闭：必填不校验、修改的节点编码不落到画布 id。三栈行为不一致。
+【建议】NaiveDrawer 把 `before-close` 接到 `onUpdate:show` 前置调用（或 `onMaskClick`/`onEsc`）。
+
+**16.【P2】antd `AntSelect` 未映射 `multiple`**
+【文件】`src/ui/antdvAdapter.ts:217-247`（只处理 `allow-create→tags`）；对照 `naiveAdapter.ts:231`（`multiple: !!multiple`）与 EP 原生；消费点 `nodeExtList.vue:18-19`（`<wf-select :multiple="item.multiple">`）
+【问题】antd 下「节点扩展属性」的多选下拉退化为单选，数组值塞进单选 Select 行为未定义。同类小缺口：`wf-time-picker :is-range`（nodeExtList.vue:66）在 antd/naive 均未翻译成 RangePicker。
+【建议】AntSelect 补 `mode: multiple ? 'multiple' : (allowCreate ? 'tags' : undefined)`；时间范围按需补映射。
+
+**17.【P2】`isDrawerOpen` 用 `.el-drawer` DOM class 判定，非 EP 栈移动端触摸拦截失效**
+【文件】`src/composables/useLogicFlowCanvas.ts:350-360`
+【问题】「UI 无关」核心里写死 EP 的 DOM 结构；antd（`.ant-drawer-open`）/naive（`.n-drawer`）下抽屉打开时触摸事件照常转发给画布，移动端会隔着抽屉拖动画布。
+【建议】仅依赖 `_drawerActive` 标志（本就由 show/close 维护），删除 EP class 探测。
+
+**18.【P3】适配器命令式反馈默认文案不一致 + 未接 i18n**
+【文件】`elementPlusAdapter.ts:10`（`系统提示`）、`antdvAdapter.ts:659`（notify 默认 `提示`）/`664/671-674`（`系统提示/确定/取消`）、`naiveAdapter.ts:703/709-711/721-724`
+【问题】同一 `notify` 三家默认标题不同（`系统提示` vs `提示`）；所有按钮/标题硬编码中文，`setLocale('en')` 后仍是中文（`request.ts:59/91-96` 网络错误、`useFlowDesigner.ts:74` 亦同）。
+【建议】适配器内文案走 `translate('common.confirm')` 等既有 key（catalog 已有 confirm/cancel/tip）。
+
+**19.【P3】`getUiAdapter()` 报错文案与现实相反**
+【文件】`src/ui/uiAdapter.ts:83-91`（「或 app.use(WarmFlowDesigner)（会默认注册 Element Plus 适配器）」）、`43`（「默认实现为 Element Plus」）
+【问题】主入口已 UI 无关，`install()`（designer/index.ts:78-91）不注册任何适配器；按报错提示操作无效，误导排障。
+【建议】改为「请先 setUiAdapter(elementPlusAdapter/antdvAdapter/naiveAdapter)（分别来自 /element-plus、/antdv、/naive 子入口）」。
+
+### 数据层 / i18n / 杂项
+
+**20.【未发现问题】DataProvider 契约与 api 委托层完全一致**：`provider.ts` 接口 11 个方法（saveJson…listenerList + config）与 `httpProvider.ts`、`mockProvider.ts` 实现、`api/flow/definition.ts` + `api/anony.ts` 委托一一对齐，`setDataProvider` 部分覆盖合并语义正确。仅注意 `AGENTS.md` 还提「DataProvider 的表单方法（getFormContent 等）暂保留」——实际已删除，文档漂移。
+
+**21.【未发现问题】i18n 中英 catalog 完全对齐**：脚本实测 zh/en 均 187 个叶子 key，双向差集为空。次级问题【P3】：`FlowDesigner.vue:309` 注释行引用的 `flowDesigner.stepFormDesign` 不在 catalog（一旦启用表单设计步骤即回落 key 原文）；`i18n/index.ts:17` 文档示例用了不存在的 `common.deleteConfirm`；12 个 `common.*` key（cancel/delete/tip/success…）暂无人使用；`setMessages`/`WfLocale` 类型是闭合联合 `'zh'|'en'`，与注释「可新增语言」矛盾。
+
+**22.【P2】`useDark().initFromUrl` 在库形态下形同虚设 + pinia 隐性耦合**
+【文件】`src/composables/useDark.ts:28`（`useAppStore().appParams`）、`src/store/app.ts:11`（`fetchTokenName` 全库无调用点、未导出）
+【问题】`appParams` 只能由 `fetchTokenName()` 填充，而它在纯库/所有 demo 中都不被调用 → `initFromUrl` 读到的 params 恒为 null，`?theme=theme-dark`、`darkColors` URL 能力实际失效（warm-flow-ui 的 App 壳才会调它）。且 `useDark` 一被调用即触达 pinia，是 pinia 成为必选 peer 的唯一实质原因。另有死 import（useDark.ts:1 的 `onMounted, onUnmounted` 未使用）。
+【建议】`initFromUrl` 直接读 `window.location.search`（不再绕 store），可顺带把 pinia 降级为可选；或导出 `fetchTokenName` 并文档化。
+
+**23.【P2】auto-import + `tsconfig.include` 残缺 → 类型质量塌陷**
+【文件】`vite/plugins/auto-import.js:10`（`dts: false`）、`src/store/app.ts:4`（`defineStore` 无 import）、`src/store/index.ts:1`（`createPinia` 无 import）、`SvgIcon/index.vue:10`（`defineComponent/computed` 无 import）、`tsconfig.json:24`（include 不含 `src/components`/`store`/`plugins`/`utils`）
+【问题】`dist-lib/src/store/app.d.ts` 实测内容为 `declare const useAppStore: any`；不在 include 的目录对 tsc/dts 是盲区（与缺陷 1 的 d.ts 缺失同源）。库代码依赖 auto-import 也降低可移植性。
+【建议】库源码全部显式 import（组件库不该依赖 auto-import）；tsconfig include 覆盖整个 `src`。
+
+**24.【P3】`SvgIcon` 的 `<style scope>` 拼写错误**
+【文件】`src/components/SvgIcon/index.vue:40`
+【问题】`scope` ≠ `scoped`，样式意外全局生效；其中 `.sub-el-icon/.nav-icon`（41-47）是 ruoyi 侧栏死选择器。
+【建议】改 `scoped` 并删死规则。
+
+**25.【P3】`isMockEnabled` 的构建期开关在产物中已失效**
+【文件】`src/data/index.ts:26`；产物 `dist-lib/warm-flow-designer.es.js:9518` 编译为 `up.VITE_USE_MOCK === "true"`（`up = {}` 空对象）
+【问题】`.env.production` 未定义 `VITE_USE_MOCK`，Vite 以空对象残留，构建期分支恒 false——对 npm 消费方只有 `?mock=true` 有效，文档口径需一致。`VITE_URL_PREFIX` 则被内联为 `"../"`（webjar 语义），npm 消费方无法配置前缀、只能整体换 provider，建议文档化或提供 `setUrlPrefix`。
+
+---
+
+## 二、重复造轮子（库内部）
+
+**1.【P2】antdv 与 naive 适配器复制同一套基础设施（约 150 行逐字重复）**
+【文件对】`antdvAdapter.ts:35-46` = `naiveAdapter.ts:45-56`（clickOutside 指令）；`49-88` = `59-98`（applyLoading/removeLoading/loadingDirective）；`402-415` = `101-114`（collectByName）；`390-399` = `117-126`（rowKeyOf + 各自独立的 WeakMap/序号）；`258-280` = `135-157`（vModelComp 工厂）
+【建议】抽 `src/ui/adapterShared.ts`，新适配器（Arco/TDesign）直接复用。
+
+**2.【P2】`plugins/modal.ts` 是 uiAdapter 的全量重复包装且基本失联**
+【文件】`src/plugins/modal.ts`（14 个方法全部一行转发 `getUiAdapter()`）、`plugins/index.ts:4`（`installPlugins` 全库无调用点）、唯一引用 `FlowDesigner.vue:497`（对宿主 `$modal` 的可选降级）
+【建议】删除 modal.ts/installPlugins（或仅保留说明「宿主可自备 $modal」），`$cache` 同理只余 request.ts 用到的 `cache.session`。
+
+**3.【P2】listener 字符串编解码逻辑 4 处手写**
+【文件】`baseInfo.vue:241-253`（setListenerData）、`between.vue:515-523`（getPermissionFlag 内嵌同款）、`propertySetting.vue:175-180`（watch 内第三份）、反向 join 在 `baseInfo.vue:293-295` 与 `propertySetting.vue:244-257`
+【问题】`listenerType.split(",")` / `listenerPath.split("@@")` ↔ `listenerRows` 的映射是与后端共享的契约，四处各写一遍，改分隔符必漏。
+【建议】抽 `utils/listener.ts`（encode/decode 纯函数）。
+
+**4.【P3】`handleListenerPathChange` 与增删行函数逐字重复**
+【文件】`baseInfo.vue:309-325` ≡ `between.vue:566-582`；`handleAddRow/handleDeleteRow` 在 `baseInfo.vue:256-264`、`between.vue:641-648`、`start.vue:142-149` 三份。TAB_ICONS 的 base/listener path 在 `between.vue:308-313` 与 `start.vue:102-105` 重复。
+
+**5.【P3】mock 数据两份且已漂移**
+【文件】`src/data/mockProvider.ts:22-42`（角色 4 条/部门 4 条/用户 6 条）vs `mock/server.mjs`（角色 2 条起）；server.mjs 头注释自称「与 mockProvider.ts 对齐」但实际已不齐。
+【建议】server.mjs 从共享 JSON 或直接 import mockProvider 数据源。
+
+**6.【未发现】** lodash 级轮子（深拷贝/防抖/uuid/树遍历）未见重复实现（全库 0 处 `JSON.parse(JSON.stringify)`/`debounce`/`cloneDeep`；下载文件仅 `useLogicFlowCanvas.downJson` 一处）。与 `warm-flow-ui` 的关系符合预期的「整树复制」：同路径文件 26 个字节级相同、20 个已漂移（如 between.vue）、67 个为 designer 独有——历史事实，不展开。
+
+---
+
+## 三、重复样式
+
+**1.【P2】产物 CSS 约 600 处 `.el-*` 选择器在 antd/naive 下全部不命中**
+【文件】`dist-lib/warm-flow-designer.css`（实测 `.el-table`×180、`.el-form-item`×84、`.el-input`×72、`.el-drawer`×16…）；来源为各 `*.scoped.scss` 与 `propertySetting.global.scss`
+【问题】152KB 的单一 CSS 三栈共用，非 EP 栈载入大量死规则且观感缺失（naiveAdapter.ts:23-24 与 todo.md「③ EP 样式归位（Phase 4）」均已自认）。
+【建议】按 todo ③ 把 `.el-*` 覆盖抽到 EP 子入口样式（`/element-plus` 附带 css），主包只留 `.wf-*`/token。
+
+**2.【P2】「白底描边输入框」同一套规则复制 4 处**
+【文件】`baseInfo.scoped.scss:82-112`、`propertySetting.global.scss:42-64`、`userPickerSearch.scoped.scss:41-61`、`userPickerTree.scoped.scss:102+`（含 hover 主色边、focus `0 0 0 4px rgba(64,158,255,.12)` 光环、is-error 红环，暗黑覆盖也各自一份）
+【问题】`_common.scss` 是设计规范钦定的 mixin 归口，却没有 input mixin，导致每个组件手抄且已开始漂移。
+【建议】新增 `@mixin wf-input-flat`，四处替换。
+
+**3.【P2】`selectUser` 手抄了一份「旧版胶囊 tab」，与现行规范冲突**
+【文件】`selectUser.scoped.scss:12-24`（白底卡片 + `box-shadow` + padding 5px 的 pill 风格）vs `_common.scss:8-21` `modern-tabs` mixin（扁平下划线，规范明令「禁止蓝色实心胶囊/外层白盒/上浮阴影」）
+【问题】既是重复实现又是视觉漂移（todo.md:125 记录的「selectUser tab 7px 18px vs _common 10px 2px」同源）。
+【建议】selectUser 改 `@include modern-tabs` 并删本地拷贝（需截图核对，todo 已列）。
+
+**4.【P3】mixin 以 `@include` 进 5 个组件 → 编译产物 5 倍重复**
+【文件】`start.vue:159-162`、`end.vue:61-62`、`gateway.vue:47-48`、`skip.vue:183-184`、`between.scoped.scss:17-21` 均 include `base-settings-card/responsive-adaption`（后者 200+ 行含三档媒体查询）
+【问题】源码单点，但 CSS 产物按组件 ×5 展开，是 152K 的主要成因之一。
+【建议】把与 scoped 无关的结构类（`.base-settings-*`、`.modern-tab-*`、响应式）提为一次性的全局层。
+
+**5.【P2】约 1400 行死样式文件（库构建根本不引用）**
+【文件】`src/assets/styles/index.scss:10-17` 引链的 `element-ui.scss`(95 行)、`ruoyi.scss`(286)、`sidebar.scss`(238)、`btn.scss`(99)、`transition.scss`、`mixin.scss`、`variables.module.scss` —— 全库唯一入口 `index.scss` 无人 import（只有 `warm-flow-ui/src/main.js:29` 用）；实测 dist CSS 无 `el-message-box`/`sidebar-container`/`text-navy`/`el-upload` 等标记。另：`assets/401_images`、`404_images`、`favicon.ico` 零引用；`FlowDesigner.vue:744-746` `.container:has(.diagram-sidebar)` 空规则块。
+【建议】整链删除（git 可追溯），`_common.scss`/`tokens.scss` 留下即可。
+
+**6.【P3】非法/弃用深度选择器**
+【文件】`baseInfo.scoped.scss:77`（`::deep(...)` 双冒号写法无效，该条「内容区左对齐」规则实际不生效）；`_common.scss:176/190-204` 等大量 `::v-deep()`（Vue3 弃用写法，编译告警级）；`nodeExtList.vue:46-51` 直接手写 `.el-tag/.el-icon` class 的伪标签绕过 wf-tag（非 EP 下无样式）。
+
+---
+
+## 四、工程化问题
+
+**1.【P2】三个子入口 vite 配置 95% 重复**
+【文件】`vite.ep.config.js` / `vite.antdv.config.js` / `vite.naive.config.js`（三文件仅 `externalDeps`、`entry`、`name`、`fileName` 四行不同，其余逐字相同）
+【建议】抽 `createAdapterLibConfig(entry, name, file, uiDep)` 工厂，新适配器只加一行；这也消除注释漂移（ep 配置头注释仍只提「Element Plus 与 Ant Design Vue 均为可选」，漏 naive）。
+
+**2.【P2】`pnpm dev`（watch）只重建主包，不覆盖三个适配器子包**
+【文件】`package.json:52`（`vite build --config vite.lib.config.js --watch`）
+【问题】开发循环中改 `antdvAdapter.ts` 等不会反映到 demo（`antdv.es.js` 停在上次 build:lib），易被「改了没生效」坑。
+【建议】dev 脚本并行 watch 四配置，或文档明示适配器改动需手动 `build:antdv`。
+
+**3.【P3】`pnpm-workspace.yaml` 残留占位垃圾段**
+【文件】`pnpm-workspace.yaml:5-10`（`allowBuilds: '@logicflow/core': set this to true or false ...`）
+【问题】pnpm 交互提示的占位文案被原样提交；真正生效的是下方 `onlyBuiltDependencies`。
+【建议】删除 `allowBuilds` 段。
+
+**4.【P3】tsconfig 基线弱**：`strict: false`、include 残缺（见缺陷 23）、`allowJs` 但 vite 目录 js 不在 program；无任何 `vue-tsc --noEmit` 类型门禁脚本，类型回归只能靠 dts 构建侧信道发现。
+
+**5.【P3】库目录遗留物**：`dist/`（旧应用构建，纯库已无 build:prod，虽被 gitignore 但本地易混淆）、`html/ie.html`（ruoyi IE 提示页）、`.env.development` 的 `/dev-api`（库无 dev server，仅 mock 联调语义）——建议清理或在 README 注明用途。
+
+**6.【已知欠账对照】** `todo.md` 自认的欠账与本次发现互证：npm publish/CI 未接（todo:8-9）、EP 样式归位 Phase 4（todo:127 ↔ 本报告三-1）、样式 DRY 漂移（todo:125 ↔ 三-2/3）、between 704 行 god 组件（todo:126 ↔ 一-8 的校验链复杂度）、属性面板 schema 化（todo:142 ↔ 二-3/4 的重复）。dist-lib 依赖泄漏方面**未发现问题**（主/子包 external 实测干净）。
+
+---
+
+## 五、与 demo 的一致性
+
+**1.【未发现不匹配】** 三个 demo 的 `main.ts` 集成序列一致且与库导出/README 完全匹配（`setUiAdapter(子入口 adapter)` → `setDataProvider(createDemoProvider())` → `createApp.use(pinia).use(UI库).use(WarmFlowDesigner)`；样式统一 `@dromara/warm-flow-designer/style`）。`#node-form-extra` 插槽三家都用中性 `wf-form-item/wf-input`，跨栈正确。
+
+**2.【P3】三份 ~700 行 App.vue + demoProvider 近乎复制**：`demoProvider.ts` ep 与 antdv 逐字节相同、naive 仅注释差；App.vue 仅 UI 标签层不同。演示代码可接受，但三份会漂移（naive 版注释已丢失「nodeRatio 兜底原因」这一关键信息）。可考虑 demo 共享 `demoProvider` 包。
+
+**3.【P3】demo 冗余/过时细节**：三 demo `dependencies` 都带未使用的 `vue-router`（随库 peer 被迫引入，联动缺陷 2）；EP demo `main.ts:24` 注释「+ Element Plus 图标」已过时（现为 iconify 离线集）；EP demo `vite.config.ts` 注释仍写 `yarn build:lib`（现为 pnpm）；库 `README.md:4` 标题「v1.2.7」vs 实际 1.8.2。
+
+**4.【P2】`useFlowJson` 官方示例代码不可用**
+【文件】`src/composables/useFlowJson.ts:43`（同步进 `dist-lib/src/composables/useFlowJson.d.ts` 的 JSDoc）
+【问题】示例在模板里 `v-on="useFlowJson(designerRef).bind"` 二次调用 composable——每次渲染新建实例，其 bind 同步的是第二实例的 refs，script 里解构的 `json/dirty` 永远不更新。照抄示例的消费方必然踩坑（EP demo 自己就没这么用，而是 `flowJson.sync()` 手动同步）。
+【建议】示例改为解构同一实例的 `bind`。
+
+---
+
+## Top 10 优先整改清单
+
+| # | 级别 | 事项 | 关键位置 |
+|---|------|------|---------|
+| 1 | P1 | 修复 `FlowDesigner.vue.d.ts` 等 dts 缺失（旗舰组件类型 any），并加 d.ts 覆盖率断言 | `vite.lib.config.js:74-79`、`dist-lib/src/designer/index.d.ts:2` |
+| 2 | P1 | 卸载时恢复 `document.body.style.overflow`（落地 C8 条件化） | `FlowDesigner.vue:343/420-423` |
+| 3 | P1 | 清理 `window._markDrawerOpen/Closed` 与 `__WF_*` 全局标志族的泄漏与多实例互踩 | `useLogicFlowCanvas.ts:244-258/694-698` |
+| 4 | P2 | 非 EP 适配器 ref 方法转发（focus/filter/setCurrentKey）修 TypeError；naive 抽屉接回 `before-close` | `antdvAdapter.ts:118-140`、`naiveAdapter.ts:529`、`start.vue:129`、`UserPickerTree.vue:94` |
+| 5 | P2 | 修 `between.vue` 校验链：`slice(tabsList.length)` 恒空 + validate 竞态（warm-flow-ui 同步评估） | `between.vue:670-695` |
+| 6 | P2 | `nodeRatio.toString()` 崩溃由库兜底，撤掉 demoProvider 的补丁 | `tool.ts:59`、`demoProvider.ts:98-106` |
+| 7 | P2 | antd Select 补 `multiple` 映射；`isDrawerOpen` 去 EP DOM 依赖；适配器默认文案接 i18n 并统一 | `antdvAdapter.ts:217-247`、`useLogicFlowCanvas.ts:350-360` |
+| 8 | P2 | 发布面清理：删 `vue-router` peer、删 `file-saver`、修 `getUiAdapter` 误导文案、`propertySetting` resize 解绑、`request.ts` 拦截器 return | `package.json:72/96`、`uiAdapter.ts:83-91`、`propertySetting.vue:42-44`、`request.ts:68-70` |
+| 9 | P2 | 样式收敛第一批：删 1400 行死样式链（index.scss 引链 + 401/404 图）、白底输入抽 mixin、selectUser 旧 tab 对齐规范 | `assets/styles/*`、`selectUser.scoped.scss:12-24` |
+| 10 | P2 | 类型工程加固：库源码去 auto-import（显式 import）、tsconfig include 全 src、加 `vue-tsc --noEmit` 门禁；三个 vite 子配置抽工厂 | `vite/plugins/auto-import.js`、`tsconfig.json:24`、`vite.{ep,antdv,naive}.config.js` |
+
+补充说明：i18n 中英 catalog（187/187 key 完全对齐）、DataProvider 契约与 api 委托一致性、dist-lib 依赖泄漏、三 demo 用法与库导出匹配性——这四项经实测**未发现问题**。
diff --git a/docs/reports/2026-07-20-ui-issues-IJVBTJ-IJV7GC.md b/docs/reports/2026-07-20-ui-issues-IJVBTJ-IJV7GC.md
new file mode 100644
index 0000000000000000000000000000000000000000..35dd2273d50ff23636eb712e2d418530265392ef
--- /dev/null
+++ b/docs/reports/2026-07-20-ui-issues-IJVBTJ-IJV7GC.md
@@ -0,0 +1,71 @@
+# UI Issue 修复与回归报告（IJVBTJ / IJV7GC）
+
+> 日期：2026-07-20 ｜ 分支：`feature-ui-npm` ｜ 涉及工程：`warm-flow-ui`（webjar 基线）、`warm-flow-vue-designer`（npm 组件库）、`warm-flow-designer-demo/*`（消费示例）
+
+## 一、两个 issue 的结论速览
+
+| Issue | 内容 | warm-flow-ui | warm-flow-vue-designer | designer-demo（3 个） | 处理 |
+| --- | --- | --- | --- | --- | --- |
+| [IJVBTJ](https://gitee.com/dromara/warm-flow/issues/IJVBTJ) 暗黑主题下节点右键菜单没有适配颜色 | 经典模式右键菜单白底 + 继承浅色文字 → 白底白字不可见 | ❌ 不支持 | ❌ 不支持 | ❌（跟随库） | **已修复** |
+| [IJV7GC](https://gitee.com/dromara/warm-flow/issues/IJV7GC) 流程设计器渲染报错 `setAttribute('0') InvalidCharacterError` | 对应被关闭的 [PR #393](https://gitee.com/dromara/warm-flow/pulls/393)；旧 Chromium 内核（钉钉内嵌/部分国产浏览器）下白屏 | ❌ 不支持 | ⚠️ 部分支持（已有 `defineEmits`，缺数组防护） | ✅ 不受影响（demo 不走 form-create） | **已修复** |
+
+## 二、根因分析
+
+### IJVBTJ：暗黑主题右键菜单
+
+- 右键菜单来自 LogicFlow `Menu` 扩展（`@logicflow/extension`），DOM 类名 `.lf-menu`，默认样式只有 `background:#fff`，**不设置文字颜色**。
+- 暗黑模式下页面全局文字色为浅色（`--wf-text-primary: #e0e0e0`），菜单项继承后变成「白底浅字」，视觉上不可见（issue 截图即此现象）。
+- 排查证据：两个工程源码与构建产物 CSS 中均只有 `.lf-control`（顶部控制栏）的暗黑适配，`rg 'lf-menu'` 仅命中 LogicFlow 自带默认样式，无任何覆盖。
+- 补充：仿钉钉模式在 `initMenu()` 中已把 `nodeMenu/edgeMenu` 置空，右键菜单只在**经典模式**出现，与 issue 场景一致。
+
+### IJV7GC：`setAttribute('0')` 渲染崩溃
+
+根因链（PR #393 已定位，维护者因「依赖升级风险」关闭，建议自行二开）：
+
+1. `baseInfo.vue` 用 `proxy.$emit('update:model-value')` 但未声明 `emits` → 事件被当作 attrs 透传，Vue3 告警且传播链不规范；
+2. `el-tree-select`（EP 2.4.3）在旧内核浏览器下 `v-model` 可能回传**数组**而非字符串，数组渗入 `formPath` / `category` 字符串字段；
+3. 下游组件（`@form-create/designer` 深度 watch / 渲染管线）把数组展开为 DOM 属性 → `setAttribute('0', value)`，属性名以数字开头不符合 XML/HTML 规范 → `InvalidCharacterError` → 设计器白屏。
+
+## 三、修复内容（本次落地）
+
+原 PR #393 中的**依赖大版本升级不采纳**（vue 3.3→3.4、EP 2.4→2.8 等，风险大、维护者已明确拒绝），只落地根因侧修复 + 兜底：
+
+### warm-flow-ui（webjar 基线，只接关键修复）
+
+| 文件 | 改动 |
+| --- | --- |
+| `src/assets/styles/index.scss` | `html.dark` 块内新增 `.lf-menu` 暗黑适配（深底 `--wf-bg-white` + 浅字 `--wf-text-primary` + hover/disabled 态），与既有 `.lf-control` 适配并列 |
+| `src/components/design/common/vue/baseInfo.vue` | ① 新增 `defineEmits(['update:model-value','update:flow-name'])`，2 处 `proxy.$emit` → `emit`；② 新增 `normalizeStringFields()`：`formPath`/`category` 为数组时取 `[0]` 转字符串，在 `watch(logicJson)` 与 `getFormData()` 两处入口调用 |
+| `src/main.js` | 入口注入 `Element.prototype.setAttribute` 包装：属性名以数字开头时 `console.warn` 并跳过，作为旧内核浏览器的最后一道防线（应用壳层做全局补丁可接受；npm 库侧不做此类全局污染） |
+
+### warm-flow-vue-designer（npm 组件库）
+
+| 文件 | 改动 |
+| --- | --- |
+| `src/components/design/FlowDesigner.vue` | 全局（非 scoped）样式块新增 `.lf-menu` 亮/暗两态着色：统一走 `--wf-*` token（`html.dark` 自动翻转），亮色也显式设置文字色，不再依赖继承 |
+| `src/components/design/common/vue/baseInfo.vue` | 新增 `normalizeStringFields()` 数组防护（`defineEmits` 此前已具备），同样挂在 `watch(logicJson)` 与 `getFormData()` |
+
+### warm-flow-designer-demo
+
+- 无需改动：三个 demo 经 `workspace:*` 消费库 `dist-lib`，重建库后自动获得修复；demo 未引入 form-create，不在 IJV7GC 影响面内。
+
+## 四、回归验证（全部通过）
+
+| 项 | 命令/方式 | 结果 |
+| --- | --- | --- |
+| 组件库四构建 | `warm-flow-vue-designer: pnpm run build:lib` | ✅ 主包 + element-plus + antdv + naive 全部成功；产物 CSS 已含 `.lf-menu` token 化规则 |
+| EP demo 消费构建 | `warm-flow-ep-designer-demo: pnpm run build` | ✅ |
+| antdv4 demo 消费构建 | `warm-flow-antdv4-designer-demo: pnpm run build` | ✅ |
+| naive demo 消费构建 | `warm-flow-naive-designer-demo: pnpm run build` | ✅ |
+| webjar 基线构建 | `warm-flow-ui: yarn build:prod` | ✅ 产物 CSS 含 `html.dark .lf-menu` 系列规则、JS 含 setAttribute 兜底补丁 |
+| **视觉回归 · npm 库（EP demo :5180）** | playwright：进入经典画布 → `html.dark` → 右键节点 | ✅ 暗黑下菜单深底浅字（删除/编辑文本/复制清晰可读）；切回亮色白底深字正常 |
+| **视觉回归 · warm-flow-ui（:8083 + mock :8080）** | playwright：新建流程 → 经典模型 → 流程设计 → 暗黑右键 | ✅ 暗黑菜单深底浅字；亮色回归正常 |
+| 仿钉钉模式 | 代码路径确认 | ✅ `initMenu()` 置空 nodeMenu/edgeMenu，无右键菜单，不受影响 |
+
+> 说明：IJV7GC 的「旧 Chromium 白屏」无法在本机新内核浏览器复现（新内核下 tree-select 正常回传字符串）；已按根因链在数据入口做类型防护 + 应用壳兜底，属预防式修复。回归中亮/暗两态基础信息 → 流程设计切换均无控制台异常。
+
+## 五、残余风险
+
+1. `setAttribute` 兜底补丁是全局原型包装，只拦截「数字开头属性名」这一非法子集，行为可预期；但若未来有库依赖抛异常行为（几乎不可能），需注意。
+2. `warm-flow-ui` 的 form-create 链路（`@form-create/designer` 3.2.x + Vue 3.3.9 旧内核组合）未做依赖升级，旧浏览器上除本 issue 外的其它兼容性问题依旧可能存在——与维护者「不专门兼容过旧内核」的取向一致。
+3. `.lf-menu` 适配依赖 `--wf-*` CSS 变量：消费方若自定义主题覆盖了 `--wf-bg-white`/`--wf-text-primary`，菜单会随主题走（符合预期设计）。
diff --git a/docs/reports/2026-07-20-warm-flow-core-quality-report.md b/docs/reports/2026-07-20-warm-flow-core-quality-report.md
new file mode 100644
index 0000000000000000000000000000000000000000..629186ea5173561f828fc66fec21100a467c05c9
--- /dev/null
+++ b/docs/reports/2026-07-20-warm-flow-core-quality-report.md
@@ -0,0 +1,378 @@
+<!-- 由代码质量审查任务生成（2026-07-20，分支 feature-ui-npm，HEAD 37b17a89）。
+     纯只读静态审查产物；Top 级发现已由主流程抽查核实（getNextByCheckGateway 返回 null、
+     FlowEngine 恒 null 服务字段、AddCopyrightHeader 混入 src/main 等）。 -->
+
+# warm-flow-core 只读代码质量审查报告
+
+审查范围：`warm-flow-core/src/main`（119 个 Java 文件，无 `src/test`），未修改任何文件。所有发现均基于当前工作区代码（HEAD `37b17a89`，工作树干净）。下文路径省略前缀 `warm-flow-core/src/main/java/org/dromara/warm/flow/core/`。
+
+---
+
+## 一、正确性缺陷
+
+### 1.1【P1】`getNextByCheckGateway` 返回 null 引发 NPE 链
+
+【文件:行号】`service/impl/NodeServiceImpl.java:242-244`、`service/impl/InsServiceImpl.java:78-82`、`service/impl/TaskServiceImpl.java:199-204`、`NodeServiceImpl.java:276-279`
+
+网关节点无出线时返回 `null` 而非空集合/业务异常：
+
+```239:244:warm-flow-core/src/main/java/org/dromara/warm/flow/core/service/impl/NodeServiceImpl.java
+        if (NodeType.isGateWay(nextNode.getNodeType())) {
+            List<Skip> skipsGateway = StreamUtils.filter(flowCombine.getAllSkips()
+                , skip -> nextNode.getNodeCode().equals(skip.getNowNodeCode()));
+            if (CollUtil.isEmpty(skipsGateway)) {
+                return null;
+            }
+```
+
+三处调用方未判空：`InsServiceImpl.start` L82 `setStartInstance(nextNodes.get(0), ...)` 直接 NPE；`TaskServiceImpl.skip` L204 `pathWayData.getTargetNodes().addAll(nextNodes)` NPE；`NodeServiceImpl` 自身递归 L277-278 `newNextNodes.addAll(nodeList)` NPE。流程图配置缺陷导致的是无上下文 NPE 而非 `FlowException`。
+
+【建议】返回 `Collections.emptyList()` 或直接 `AssertUtil.isEmpty(skipsGateway, NULL_DEST_NODE)` 抛业务异常；调用方对返回值统一 `CollUtil.isNotEmpty` 防御。签名不变，向后兼容。
+
+### 1.2【P1】断言前解引用，空指针先于业务异常
+
+【文件:行号】`service/impl/TaskServiceImpl.java:245-247`
+
+```245:247:warm-flow-core/src/main/java/org/dromara/warm/flow/core/service/impl/TaskServiceImpl.java
+        Instance instance = FlowEngine.insService().getById(instanceId);
+        flowParams.variable(MapUtil.mergeAll(instance.getVariableMap(), flowParams.getVariable()));
+        AssertUtil.isNull(instance, ExceptionCons.NOT_FOUNT_INSTANCE);
+```
+
+实例不存在时 L246 先抛 NPE，L247 的 `NOT_FOUNT_INSTANCE` 永远到不了。且 L246 与 L251 **重复执行**同一 merge。同型问题：`service/impl/DefServiceImpl.java:266-268` `getById(id).copy()` 在 L268 `AssertUtil.isNull(definition, ...)` 之前解引用（copy 后对象也永不为 null，断言彻底失效）。
+
+【建议】把 `AssertUtil.isNull` 挪到首次解引用之前；删除重复 merge。纯内部顺序调整，无兼容风险。
+
+### 1.3【P2】`ListenerUtil.execute` 下标错位与提前 return
+
+【文件:行号】`utils/ListenerUtil.java:98-113`
+
+```98:104:warm-flow-core/src/main/java/org/dromara/warm/flow/core/utils/ListenerUtil.java
+            String[] listenerTypeArr = listenerTypes.split(",");
+            for (int i = 0; i < listenerTypeArr.length; i++) {
+                String listenerType = listenerTypeArr[i].trim();
+                if (listenerType.equals(type)) {
+                    if (StringUtils.isNotEmpty(listenerPaths)) {
+                        String[] listenerPathArr = listenerPaths.split(FlowCons.SPLIT_AT);
+                        String listenerPath = listenerPathArr[i].trim();
+```
+
+`listenerTypeArr[i]` 与 `listenerPathArr[i]` 共用下标，设计器数据中 types 数量多于 paths 时抛 `ArrayIndexOutOfBoundsException`，无兜底。另 L111-113：表达式监听器命中后 `return` 退出**整个方法**，同一节点配置的后续同类型监听器全部被跳过（语义上应为 `continue`）。
+
+【建议】循环前校验两数组长度并抛带 nodeCode 上下文的 `FlowException`；`return` 改 `continue`（需确认「优先执行表达式监听器」的预期语义后修正）。
+
+### 1.4【P2】条件表达式解析裸奔
+
+【文件:行号】`condition/AbstractConditionStrategy.java:56-61`、`condition/ConditionStrategyEq.java:34-39`
+
+```56:61:warm-flow-core/src/main/java/org/dromara/warm/flow/core/condition/AbstractConditionStrategy.java
+    public Boolean eval(String expression, Map<String, Object> variable) {
+        String[] split = expression.split(FlowCons.SPLIT_VERTICAL);
+        preEval(split[0].trim(), variable);
+        String variableValue = String.valueOf(variable.get(split[0].trim()));
+        return afterEval(split[1].trim(), variableValue);
+    }
+```
+
+表达式缺 `|`（如 `eq@@flag`）时 `split[1]` 抛 AIOOBE；`ConditionStrategyEq` L36：value 是数字而变量值不是数字时 `MathUtil.determineSize` 内 `new BigDecimal(variableValue)` 抛裸 `NumberFormatException`，均无表达式上下文。
+
+【建议】`eval` 中校验 `split.length == 2` 否则抛 `FlowException("非法条件表达式: " + expression)`；`determineSize` 调用点捕获转译。
+
+### 1.5【P2】静态可变共享状态（并发面）
+
+- `strategy/ConditionStrategy.java:33`、`HandlerStrategy.java:34`、`ListenerStrategy.java:31`、`VoteSignStrategy.java:33`：接口常量 `EXPRESSION_STRATEGY_LIST = new ArrayList<>()` 是公共静态可变、非线程安全集合；`ExpressionUtil.setExpression`（`utils/ExpressionUtil.java:59-61`）追加无去重——Spring 容器多次刷新（devtools/测试多 context）会重复注册，且 `getValue` L159 倒序匹配使行为随注册次数漂移。
+- `invoker/FrameInvoker.java:27` `public static FrameInvoker frameInvoker = new FrameInvoker<>();` 原始类型+公共可变静态字段；`beanFunction`/`cfgFunction` 非 volatile，启动期跨线程可见性无保证。
+- `utils/IdUtils.java:36-77`：`instance` 有 volatile+DCL，但 `instanceNative`（L41）非 volatile 且由 `setInstanceNative` 异线程写入；`nextId(workerId, datacenterId)` 的参数仅首次初始化生效，后续调用传不同值被静默忽略。
+- `enums/ChartStatus.java:51-53` `CUSTOM_COLOR` 等三个静态 HashMap 由 `init` 写、运行期读，同属启动期竞态窗口（实际风险低）。
+
+【建议】策略列表改 `CopyOnWriteArrayList` + 注册时按 `getType()` 去重；`FrameInvoker` 字段降为 private + volatile；`instanceNative` 加 volatile。均为实现细节，不破坏契约。
+
+### 1.6【P2】`FlowEngine` 服务字段恒为 null，缓存失效
+
+【文件:行号】`FlowEngine.java:41-49, 231-237`
+
+```41:43:warm-flow-core/src/main/java/org/dromara/warm/flow/core/FlowEngine.java
+    private static final DefService defService = null;
+    private static final NodeService nodeService = null;
+    private static final SkipService skipService = null;
+```
+
+9 个 `static final … = null` 字段永远为 null，`getObj(t, tClass)`（L231-237）的第一分支永假，**每次** `FlowEngine.xxxService()` 都走 `FrameInvoker.getBean` 查容器；bean 缺失时返回 null，调用点直接 NPE 且无提示。这组字段是死代码兼性能损耗。
+
+【建议】保持方法签名不变，把字段改为非 final 可写缓存（首次 getBean 后缓存），或至少在 getBean 返回 null 时抛出「未接入 starter/未注册 XxxService」的明确异常。
+
+### 1.7【P2】流程图元数据 `map.get` 后未判空
+
+【文件:行号】`service/impl/ChartServiceImpl.java:59-63, 78-93`。`nodeMap.get(node.getNodeCode()).setStatus(...)`（L59）、`skipMap.get(getSkipKey(skip)).setStatus(...)`（L60、L87）——实例 defJson 与最新路径数据不一致（定义被改）时 NPE。同型：`service/impl/NodeServiceImpl.java:149-150` `nodeMap.get(nodeCode)` 后直接 `node.getNodeType()`。
+
+【建议】get 后判空跳过或抛带 nodeCode 的 `FlowException`。
+
+### 1.8【P2】`importDef` 路径 `activityStatus` 未初始化即被解引用
+
+【文件:行号】`service/impl/InsServiceImpl.java:67`、`utils/FlowConfigUtil.java:43-79`、`dto/DefJson.java:215-229`
+
+`InsServiceImpl.start` L67 `definition.getActivityStatus().equals(ActivityStatus.SUSPENDED.getKey())` 直接拆箱比较；而 `FlowConfigUtil.structureFlow` 与 `DefJson.copyDef(DefJson)` 都不设置 `activityStatus`，ORM 实体（如 mybatis `FlowDefinition.java:116`）亦无 Java 默认值——导入的流程定义若 insert 显式写 NULL（全列 insert 覆盖 DB default 的常见情形），启动流程即 NPE。
+
+【建议】L67 改用 `ActivityStatus.isSuspended(...)`（自带判空），或 `structureFlow`/`copyDef` 补默认 `ACTIVITY`。
+
+### 1.9【P3】零散空指针/判空口径
+
+- `service/impl/TaskServiceImpl.java:390-392` 等四处 `AssertUtil.isNull(flowParams.getHandler(), HANDLER_NOT_EMPTY)`：只挡 null 不挡空串，空字符串 handler 可穿透（应使用 `AssertUtil.isEmpty`）。
+- `service/impl/TaskServiceImpl.java:262` `instance.getCreateBy().equals(...)`：createBy 为 null 时 NPE。
+- `service/impl/FormServiceImpl.java:56-57` `getById(id)` 结果未判空即 `form.getIsPublish().equals(...)`，双重 NPE 面。
+- `utils/page/Page.java:103-105` `pageOf(Integer, Integer)` 传 null 拆箱 NPE。
+
+### 1.10 资源关闭与 equals/hashCode
+
+**未发现问题**。`DefServiceImpl.importIs`（L66）、`ClassUtil.findClassesInJar`（L152）均 try-with-resources；core 实体全为接口，比较均走 `Objects.equals` 或常量在前的 `equals`，未见 equals/hashCode 定义缺陷。
+
+---
+
+## 二、JDK8 兼容红线
+
+**未发现违规**。逐包正则扫描 `List.of/Map.of/Set.of/String.isBlank/strip/Stream.toList()/Optional.isEmpty/Files.readString/var/record/switch 表达式/文本块`：全部零命中；所有流式收集均为 `Collectors.toList()`，且 `utils/StreamUtils.java:47` 有明确防回归注释：`// 注意此处不要使用 .toList() 新语法 因为返回的是不可变List 会导致序列化问题`。
+
+两条前瞻性备注（非违规，P3 记录）：
+
+- 【P3】`utils/ServiceLoaderUtil.java:122-147` 使用 `System.getSecurityManager()`/`AccessController.doPrivileged`——JDK8 合法，但 JDK17+ 标记 deprecated for removal，未来高版本 JDK 有告警/移除风险。建议后续版本降级为直接取 ContextClassLoader。
+- 【P3】`enums/ChartStatus.java:24` 与 `service/impl/ChartServiceImpl.java:34` `import java.awt.*`（`java.awt.Color`）——把桌面模块类型引入引擎核心，jlink 裁剪运行时需带 `java.desktop`。建议长期用自定义 RGB 值对象替代（需过渡期，`Color` 已出现在公共方法签名 `ChartStatus.getColorByKey` 中）。
+
+---
+
+## 三、API 设计与一致性
+
+### 3.1【P2】`MapUtil.mergeAll` 双重载语义冲突
+
+【文件:行号】`utils/MapUtil.java:66-92`。`mergeAll(Map<K,V>... maps)`（合并多个 map）与 `mergeAll(Object... values)`（把参数当 k1,v1,k2,v2 组装 map）同名共存，重载决议取决于实参静态类型，语义完全不同，极易误用；后者全仓库零调用。【建议】`Object...` 版本 `@Deprecated` 并更名（如 `ofPairs`），过渡期保留。
+
+### 3.2【P2】DTO getter 带副作用
+
+【文件:行号】`dto/FlowParams.java:266-290`。`getHandler()`/`getPermissionFlag()` 在 getter 内惰性调用 `PermissionHandler` 并**写回字段**、吞异常——序列化/日志打印 DTO 都会触发外部调用，行为不可预测。【建议】保留行为但抽成显式方法（如 `resolveHandler()`），getter 过渡期委托并在 javadoc 声明副作用；吞掉的异常至少 debug 日志。
+
+### 3.3【P2】排序字段直通 SQL 的注入面与物理列名泄漏
+
+【文件:行号】`orm/agent/WarmQuery.java:94-117, 135-161`。`orderBy = "id"/"create_time"/"update_time"` 把 snake_case 物理列名硬编码进 core 抽象；`orderByAsc(String)`/`orderBy(String)` 接受任意字符串最终拼进各 ORM 的 order by——下游若把用户输入透传即 SQL 注入。`WarmDao` 接口本身干净（无 ORM 概念泄漏），泄漏点集中在 WarmQuery 字符串列名。【建议】文档明确「orderByField 必须是白名单列」，或在 core 侧加列名合法性校验（`[a-zA-Z0-9_.]+`）。
+
+### 3.4【P2】`FlowEngine.jsonConvert` 公共可变静态字段
+
+【文件:行号】`FlowEngine.java:70` `public static JsonConvert jsonConvert;`——门面其余能力都有 getter/init 封装，唯独 JSON 转换器裸暴露，任何代码可随时改写。【建议】加 `jsonConvert()` 访问器与受控 setter，字段过渡期保留 public（兼容）但标注废弃。
+
+### 3.5【P3】utils 重复能力与命名漂移（引擎自带工具矩阵混乱）
+
+同语义多处实现（均有真实代码，行号见文件）：
+
+| 能力 | 重复实现 |
+|---|---|
+| 集合含任一字符串 | `StringUtils.containsAny(Collection,String...)` L124 与 `CollUtil.containsAny(Collection,String...)` L86（完全同签名同语义） |
+| 拼接 | `StringUtils.join` L414-450、`StreamUtils.join` L77-94、`CollUtil.strListToStr` L217（后者 `deleteCharAt` 只删 1 字符，多字符分隔符结果错误——自身还是 bug） |
+| null 默认值 | `StringUtils.nvl` L47 与 `ObjectUtil.defaultNull` L66 |
+| 字符串切分 | `StringUtils.str2List` L218、`CollUtil.strToColl` L137、`ArrayUtil.strToArrAy` L73（方法名拼写错误 "ArrAy"） |
+
+命名漂移：`UserService`（impl L72-120）同为「查列表」混用 `getPermission`/`listByAssociatedAndTypes`/`getByAssociateds`/`listByProcessedBys`/`getByProcessedBys`（且 `getPermission` 实际返回的是 processedBy 集合，名实不符）；`IWarmService.java:93` `selectCount`（DAO 术语）与 `save/remove/getById`（MP service 术语）混搭；`CooperateType.isVoteSignRejectSpel` L169 名带 Reject 实为通用 spel 前缀判断。
+
+【建议】保留旧方法（已发布契约），在 javadoc 互相 `@see` 指向唯一推荐实现；拼写错误方法新增正确名并 `@Deprecated` 旧名；后续大版本收敛。
+
+### 3.6【P3】`AssertUtil` 断言语义反直觉且不对称
+
+【文件:行号】`utils/AssertUtil.java:34-97`。方法名描述的是**抛异常的条件**（`isNull` = 为 null 就抛、`isTrue` = 为 true 就抛），与 Spring `Assert`（断言期望成立）恰好相反，对新贡献者是长期陷阱；且 `isNotEmpty(null)` 静默放过（L70-71）而 `isEmpty(null)` 抛错（L85-87），不对称。【建议】不改现有签名（大量调用+下游使用），补类级 javadoc 醒目说明语义约定，长期可新增 `throwIfNull` 风格别名。
+
+### 3.7【P3】其他
+
+- `handler/DefaultHandlerStrategy.java:27`：办理人策略实现放在 `handler` 包而其余策略在 `strategy`/`condition` 包，包归属漂移。
+- `utils/StreamUtils.java:176` `groupByKeyFilter` 声明未使用的泛型参数 `<T>`。
+- `orm/agent/WarmQuery.java:124` `desc()` javadoc 写「设置正序排列」（实为倒序），且无对称 `asc()`。
+- `FlowEngine.java:199-208` `permissionHandler()` 的 javadoc 是「获取填充类」（复制自 dataFillHandler）。
+
+---
+
+## 四、状态机与流程语义
+
+### 4.1【P1】一票否决/收尾清理：注释承诺「转历史任务」但实现只删除
+
+【文件:行号】`service/impl/TaskServiceImpl.java:921-943, 946-958, 665-668`
+
+```928:942:warm-flow-core/src/main/java/org/dromara/warm/flow/core/service/impl/TaskServiceImpl.java
+    private void oneVoteVeto(Task task, String nextNodeCode, FlowCombine flowCombine) {
+        // 一票否决（谨慎使用），如果退回，退回指向节点后还存在其他正在执行的待办任务，转历史任务，状态失效,重走流程。
+        List<Task> tasks = list(FlowEngine.newTask().setInstanceId(task.getInstanceId()));
+        // ... 省略筛选后置未完成任务 ...
+        if (CollUtil.isNotEmpty(noDoneTasks)) {
+            removeAndUser(noDoneTasks);
+        }
+    }
+```
+
+`removeAndUser`（L665-668）只做 `removeByIds` + `deleteByTaskIds`，**不生成任何 HisTask**。方法注释与 `FlowStatus.INVALID`("失效") 枚举都承诺「转历史，状态失效」，实际被否决的并行分支任务无审计痕迹。`handUndoneTask`（L946-958）注释「转历史任务，状态完成」同样只删除。这是注释与实现不符 + 历史链路缺口的双重问题。
+
+【建议】删除前按 `hisTaskService().setSkipHisList` 生成 INVALID/FINISHED 状态历史再删；若确认现行为是设计意图，必须同步修正注释与文档（影响下游对审计数据的依赖预期）。
+
+### 4.2【P2】`revoke` 与 `updateFlowInfo` 复制粘贴流水
+
+【文件:行号】`service/impl/TaskServiceImpl.java:293-307` vs `969-986`。两段几乎相同的「存历史→删待办与权限人→生成新任务权限人→setInsFinishInfo→saveBatch→updateById→saveBatch(users)」序列，且两处顺序有微妙差异（revoke 先存历史再删待办，updateFlowInfo 相反），后续维护极易语义漂移。【建议】抽私有方法统一（内部重构，不动公共 API）。
+
+### 4.3【P2】`HisTaskServiceImpl` 五处 set*His 大段重复 + 双重 setMessage
+
+【文件:行号】`service/impl/HisTaskServiceImpl.java:100-126, 129-153, 156-183, 186-212, 219-244`。五个方法重复 15+ 行相同 setter 链；其中 `setSignHisTask` L198 与 L205 `setMessage(flowParams.getMessage())` 调用两次。【建议】抽 `baseHisTask(task, flowParams)` 私有构造器；删冗余 setMessage。
+
+### 4.4【P2】`updateHandler` 监听器变量不完整（与其他动作不一致）
+
+【文件:行号】`service/impl/TaskServiceImpl.java:445, 488`。`ListenerUtil.executeStart(new ListenerVariable(r.definition, r.instance, r.nowNode, null, r.task))`——variable 传 null 且未 `.setFlowParams(flowParams)`；同方法 L488 的 executeFinish 也缺 flowParams。skip/revoke/termination/pending 全部都带。转办/加减签场景监听器拿不到流程参数，属跨动作行为不一致。【建议】补齐 `flowParams.getVariable()` 与 `.setFlowParams(flowParams)`。
+
+### 4.5【P2】重复变量合并
+
+【文件:行号】`service/impl/TaskServiceImpl.java:170 与 213`、`246 与 251`。同一请求内 `MapUtil.mergeAll(r.instance.getVariableMap(), flowParams.getVariable())` 执行两次（`getVariableMap` 每次都反序列化 JSON），纯浪费且中间语义易混淆。【建议】合并一次后复用。
+
+### 4.6【P3】超长方法与深嵌套
+
+**未发现 >150 行方法**（实测最长：`TaskServiceImpl.cooperate` L737-837 约 100 行、`skip` L166-235 约 70 行、`revoke` L238-313 约 76 行）。但：`cooperate` 集中了或签/会签/票签 4 种策略 + 表达式分支，三元嵌套（L807-822）复杂度高；`ListenerUtil.execute` L96-137 六层嵌套。`getNewVersion` 在 `DefServiceImpl.java:311-343` 与 `FormServiceImpl.java:121-145` 两份相似实现（Def 有非数字版本 fallback `"_1"`，Form 没有），属复制漂移。【建议】cooperate 拆「或签/会签/票签」策略私有方法；版本号生成收敛为一个工具。
+
+### 4.7【P3】文档与默认值矛盾
+
+`service/TaskService.java:423, 438, 453, 468` javadoc 写「ignore 转办忽略权限校验,**默认忽略**」，而 `FlowParams.ignore` 是 boolean 默认 false（不忽略），同接口 L365（transfer）又写「默认不忽略」——三处自相矛盾。另 `TaskServiceImpl.java:173` 校验 skipType 却用 `NULL_CONDITION_VALUE`("跳转条件不能为空!") 文案。【建议】统一 javadoc 为「默认不忽略」；新增 `NULL_SKIP_TYPE_PARAM` 类文案。
+
+---
+
+## 五、日志与异常规范
+
+### 5.1【P2】catch 后完全静默的吞异常清单
+
+`printStackTrace`/`System.out` 业务代码残留：**未发现**（`ExceptionUtil.java:33` 的 `e.printStackTrace(new PrintWriter(sw))` 是写入 StringWriter 的合法用法；`WarmFlow.printBanner` L161 的 System.out 属 banner 例外；`AddCopyrightHeader` 见第六类）。但静默吞异常成体系：
+
+| 位置 | 场景 | 后果 |
+|---|---|---|
+| `FlowEngine.java:258` | initBean 反射失败 `catch (Exception ignored)` | 用户配错 handler 路径静默回退，租户/权限/监听器不生效且无迹可查 |
+| `invoker/FrameInvoker.java:46-51, 63-68` | getBean/getCfg catch-all 返回 null | 容器异常被吞 |
+| `dto/FlowParams.java:270-273, 283-286` | PermissionHandler 调用失败 | 权限上下文静默缺失 |
+| `handler/DataFillHandler.java:73-76, 97-100` | 同上 | createBy/updateBy 静默不填 |
+| `utils/ExpressionUtil.java:96-99` | convertPermissions 失败 | 办理人转换静默跳过 |
+| `utils/ClassUtil.java:48, 88-89` | getClazz/clone 失败返回 null | 上层拿 null 继续走 |
+
+【建议】统一至少 `log.warn`（带类路径/key 上下文）；`ServiceLoaderUtil.java:41,63` 吞 `ServiceConfigurationError` 属可选依赖的有意设计，可保留但建议 debug 日志。
+
+### 5.2【P2】异常丢失 cause 与上下文
+
+【文件:行号】`utils/ReflectionUtil.java:50-51, 75-76, 107-108`。三处 `catch (Exception e) { throw new FlowException("扫描异常"); }`——`FlowException(String, Throwable)` 构造器（`exception/FlowException.java:55-58`）存在却不用，cause 丢失、消息无 interfacePath/implementPath。另：断言消息普遍无实体 id 上下文（如 `NOT_FOUNT_TASK` 不含 taskId），对比 `DefServiceImpl.checkFlowLegal` L348 拼接 flowName 的好实践。【建议】补 cause 与关键参数。
+
+### 5.3【P2】自定义异常体系不统一
+
+- `keygen/SnowFlakeId19.java:137`、`SnowFlakeId14.java:101`、`SnowFlakeId15.java:69` 时钟回拨抛裸 `RuntimeException`，而引擎其余全用 `FlowException`。
+- `exception/FlowException.java:32, 43`：`code`/`detailMessage` 字段在整个 core 无任何赋值调用（`FlowException(String, Integer)` 零使用）——半成品异常协议。
+
+【建议】雪花类改抛 `FlowException`（消息保留）；code 体系要么落地要么在大版本收敛。
+
+### 5.4【P3】错误文案复制粘贴错位
+
+- `service/impl/FormServiceImpl.java:95` 表单查不到报 `NOT_FOUNT_TASK`("未找到待办任务!")；L83 表单复制失败报 `NOT_FOUNT_DEF`("流程定义不存在!")——误导排查。
+- `constant/ExceptionCons.java:58` `NULL_LISTENER_STRATEGY = "办理人表达式策略不能为空!"`（应为「监听器表达式策略」，与 L56 重复文案）。
+- `handler/DataFillHandler.java:90` updateFill 日志写 "Insert operation failed"。
+- `config/WarmFlow.java:168` banner 版本 `getImplementationVersion()` 非 jar 运行（IDE/单测）时为 null，打印 `v null`。
+
+---
+
+## 六、代码坏味道
+
+### 6.1【P2】开发脚本混入发布 jar 且违反自家 license 红线
+
+【文件:行号】`utils/AddCopyrightHeader.java:1-8`
+
+```1:8:warm-flow-core/src/main/java/org/dromara/warm/flow/core/utils/AddCopyrightHeader.java
+package org.dromara.warm.flow.core.utils;
+
+import java.io.*;
+
+public class AddCopyrightHeader {
+    public static void main(String[] args) throws Exception {
+        //项目的绝对路径，也就是想修改的文件路径
+        String filePath = "D:\\IdeaProjects\\min\\RuoYi-Vue-Warm-Flow\\warm-flow";
+```
+
+带 `main()` 的一次性版权头插入脚本被打进中央仓库 jar：硬编码作者本机 Windows 路径、`System.out.println`（L82），且**它自己没有 Apache 2.0 header**——是全模块唯一违反「每个 Java 文件保留 license header」红线的文件。全仓库零引用。【建议】移出 `src/main`（挪 `docs/`/脚本目录或删除，git 可追溯）；对已发布版本无 API 兼容影响（无人会依赖它）。
+
+### 6.2【P2】零引用的 public 死代码（发布契约内，需谨慎处置）
+
+以下在**本仓库所有模块 `src/main` 零调用**（已逐一 grep 验证；因是已发布 SDK，外部可能引用，不能直接删）：
+
+- `utils/ReflectionUtil.java` 全类（3 个 public 方法）+ 仅被它使用的 `ClassUtil.findClasses` 系（L107-163）。
+- `utils/Base64.java` 全类（274 行手写 Base64，JDK8 自带 `java.util.Base64`——与 JDK 既有能力重复且零引用）。
+- `utils/HttpStatus.java`：core 内零引用（仅 `warm-flow-plugin-ui-core` 的 `HandlerSelectService` 用到 `SUCCESS` 一个常量）——HTTP 状态码放引擎核心属位置错误。
+- `enums/CooperateType.java:74, 179-194` 顺签特性：`SEQUENCE` 常量、`isSequenceSign`、`removeSequence` 定义后无任何调用点——未完成特性的存根。
+- 其他零引用工具方法：`MapUtil.mergeAll(Object...)`、`CollUtil.strToColl/listAddToNew/listAddListsToNew/strListToStr`、`StreamUtils.toIdentityMap/groupBy2Key/group2Map`、`StringUtils.nvl/toUnderScoreCase/convertToCamelCase/inStringIgnoreCase/padLeft`、`ObjectUtil.isStrTrue`、`ServiceLoaderUtil.loadList`、`ChartStatus.getColorByKey(Integer)`。
+
+【建议】统一加 `@Deprecated` + javadoc 说明替代（如 Base64 → `java.util.Base64`），大版本再移除；HttpStatus 建议下沉到 ui 插件（core 保留 @Deprecated 转发过渡）。
+
+### 6.3【P3】未使用变量/误用流做副作用
+
+- `service/impl/UserServiceImpl.java:152` `Date now = new Date();` 声明后未使用。
+- `service/impl/UserServiceImpl.java:52` `StreamUtils.toList(addTasks, task -> taskUserList.addAll(taskAddUser(task)))`——用 map+collect 做副作用遍历，返回值丢弃（应 `forEach`）。
+- `condition/ConditionStrategyGe.java:36`、`ConditionStrategyLe.java:36` `determineSize(...) > 0 || determineSize(...) == 0`：同一比较计算两次（应 `>= 0`）。
+
+### 6.4【P3】魔法值未用常量/枚举
+
+- `dto/FlowParams.java:331` `variable.put("formData", formData)`——`FlowCons.FORM_DATA` 已存在（`TaskServiceImpl` L1013 用的就是常量）。
+- `dto/DefJson.java:153` `modelValue = "CLASSICS"`（应 `ModelEnum.CLASSICS.name()`）；L240 `"0"`（应 `StringUtils.ZERO`，`DefServiceImpl` L140 用的是常量）。
+- `service/impl/TaskServiceImpl.java:783-790` 票签表达式变量名 `"skipType"/"passNum"/"rejectNum"/"todoNum"/"allNum"/...` 字面量入 map——这是对外表达式契约，应常量化防止改名破坏。
+- `utils/ListenerUtil.java:109` `"listenerVariable"` 字面量（同为表达式契约）。
+- `handler/DefaultHandlerStrategy.java:31-36` `"$"`、`"${"`、`"}"` 字面量。
+
+### 6.5【P3】@Deprecated 无替代说明
+
+【文件:行号】`entity/Node.java:126-136`。`getVersion/setVersion` 仅注 `@deprecated 下个版本废弃`，无迁移指引；且 `Node.copy()` L153、`FlowConfigUtil` L147、`DefServiceImpl` L94 内部仍在调用——「下个版本废弃」不可能兑现。【建议】javadoc 补「版本随 Definition 维护，使用 `Definition#getVersion`」类说明，并先清内部调用。
+
+### 6.6【P3】注释与实现不符（除 4.1 外）
+
+- `keygen/SnowFlakeId14.java:35-60`：注释整套从 19 位版复制——「最大机器id 结果是31」实为 7（3 bits）、「工作机器ID(0~1024)」实为 0~7、「掩码 4095」实为 31（5 bits）、「时间截向左移22位(10+12)」实为 8 位。
+- `keygen/SnowFlakeId15.java:88-89`：「保证生成的ID为15位」但 `id % 10_000_000_000_000_000L` 是对 10^16 取模（16 位上限），且远期回绕理论上产生重复 id。
+- `enums/CooperateType.java:183-188` `removeSequence` 的 javadoc 是 `isSequenceSign` 的原样复制（"判断是否是顺签"）。
+- `json/JsonConvert.java:46` 已发布 SPI 接口方法挂着 `TODO 未测试`。
+- `service/impl/TaskServiceImpl.java:167, 507` 两处 `TODO min 后续考虑并发问题...加锁`——与 `mergeVariable`（L591-598）读改写窗口一起构成**已知未处理并发缺口**，长期挂账应立项。
+- `utils/StringUtils.java:29` 空字符串常量命名 `NULLPTR`，名实相悖。
+
+---
+
+## 七、SPI/扩展点
+
+### 7.1【P2】`JsonConvert` SPI 加载失败静默为 null，NPE 遍地开花
+
+【文件:行号】`config/WarmFlow.java:154-157`、`FlowEngine.java:70`、`entity/Instance.java:125-127`
+
+```154:157:warm-flow-core/src/main/java/org/dromara/warm/flow/core/config/WarmFlow.java
+    public void spiLoad() {
+        // 通过SPI机制加载json转换策略实现类
+        FlowEngine.jsonConvert = ServiceLoaderUtil.loadFirst(JsonConvert.class);
+    }
+```
+
+未引入任何 `warm-flow-plugin-json-*` 时 `loadFirst` 返回 null 且无任何提示，之后 `Instance.getVariableMap()`（默认方法直接 `FlowEngine.jsonConvert.strToMap`）、`FlowParams.getVariableStr`、`DefServiceImpl.importJson` 等全部 NPE，错误离根因极远。【建议】`spiLoad` 后判空 `log.warn`/fail-fast：「未检测到 JsonConvert 实现，请引入 warm-flow-plugin-json 模块」。
+
+### 7.2 注册文件与实现类一致性：核对通过
+
+- `warm-flow-plugin-json-v1/.../META-INF/services/org.dromara.warm.flow.core.json.JsonConvert` 注册 5 个实现（Snack/Snack4/Jackson/FastJson/Gson），源码目录 5 个类**一一对应存在**；`json-jackson3` 注册 1 个、类存在。`ServiceLoaderUtil.loadFirst` 吞 `ServiceConfigurationError` 以兼容 optional 依赖缺失，机制成立。
+- 【P3】隐式顺序风险：一个 services 文件 5 个实现，classpath 同时存在多个 JSON 库时选中哪个取决于文件行序（Snack 优先），用户不可配置、文档未声明。建议在文档/启动日志打印实际选中的实现类。
+- 【P3】遗留构建产物：`warm-flow-orm/warm-flow-mybatis-plus/warm-flow-mybatis-plus-sb4-starter/` 仅剩 `pom.xml` + `target/`（无 `src`），target 内残留旧版 `JsonConvert` services 注册（`org.dromara.warm.flow.orm.jackson3.JsonConvertJackson3`）——本地脏产物，建议 clean，避免本地调试时被旧 SPI 干扰。
+
+### 7.3【P2】ExpressionStrategy 注册机制：静态块 + 各框架命令式注册，无去重
+
+【文件:行号】`utils/ExpressionUtil.java:38-51`（core 静态块注册 8 个条件策略 + DefaultHandlerStrategy）、`warm-flow-plugin-modes-sb/.../BeanConfig.java:155-161` 与 `modes-solon/.../BeanConfig.java:158-162`（各自追加 SpEL/SnEL 策略）。结合 1.5 的可变静态列表问题：容器刷新两次即重复注册，`getValue` 倒序优先规则下用户自定义策略可能被后来的重复系统策略遮蔽。**空实现处理**：`getValue` L161-163 对 list 中 null 元素抛 `NULL_CONDITION_STRATEGY`，但列表为空/无匹配时静默返回 null——`evalCondition` 于是返回 false，条件不满足与策略缺失不可区分。【建议】注册按 `getType()` 幂等去重；无匹配策略时抛「未找到表达式策略: 前缀」异常。
+
+### 7.4 Listener/Handler 扩展点
+
+`ListenerUtil.executeListener` L86-93 对 GlobalListener 判空后调用、`WarmServiceImpl.insertFill/updateFill` L181-196 对 DataFillHandler 判空——空实现处理正确。问题集中在 initBean 静默回退（见 5.1）与监听器路径解析健壮性（见 1.3）。
+
+---
+
+## Top 10 优先整改清单
+
+| # | 严重度 | 事项 | 关键位置 |
+|---|---|---|---|
+| 1 | P1 | `getNextByCheckGateway` 返回 null 的 NPE 链（开流程/审批/递归三处引爆点），改空集合或业务异常 | `NodeServiceImpl:243` → `InsServiceImpl:82`、`TaskServiceImpl:204`、`NodeServiceImpl:278` |
+| 2 | P1 | 断言前解引用：`revoke` 实例判空滞后（含重复 merge）、`copyDef` 判空失效 | `TaskServiceImpl:245-251`、`DefServiceImpl:266-268` |
+| 3 | P1 | 一票否决/流程收尾「转历史」承诺未实现，审计链缺口（或修实现或修语义文档） | `TaskServiceImpl:921-958, 665-668` |
+| 4 | P2 | `JsonConvert` SPI 缺失静默 null → 全局远端 NPE；补 fail-fast 提示并封装 `FlowEngine.jsonConvert` | `WarmFlow:154-157`、`FlowEngine:70` |
+| 5 | P2 | `ListenerUtil.execute` types/paths 下标错位 AIOOBE + 表达式命中 `return` 吞掉后续监听器 | `ListenerUtil:98-113` |
+| 6 | P2 | 体系性吞异常整改（initBean/FrameInvoker/FlowParams/DataFillHandler/ExpressionUtil/ClassUtil 统一 warn 日志） | `FlowEngine:258` 等 10 处 |
+| 7 | P2 | 表达式策略静态可变 ArrayList：线程安全 + 注册去重 + 无匹配策略显式报错 | `ConditionStrategy:33` 等 4 处、`ExpressionUtil:59, 155-173` |
+| 8 | P2 | `FlowEngine` 九个恒 null 服务字段：每次调用查容器、bean 缺失无提示；补缓存与明确异常 | `FlowEngine:41-49, 231-237` |
+| 9 | P2 | 条件表达式解析健壮性（`split[1]` AIOOBE、非数字变量裸 NumberFormatException，异常带表达式上下文） | `AbstractConditionStrategy:56-61`、`ConditionStrategyEq:36` |
+| 10 | P2 | `AddCopyrightHeader` 开发脚本移出 src/main（无 license header + 硬编码本机路径）；死代码工具方法批量 `@Deprecated` 规划清理 | `utils/AddCopyrightHeader`、6.2 清单 |
+
+补充说明：第 3、4、7 项涉及对外可感知行为，按仓库规则属 L2 改动，实施前建议先在 `warm-flow-test` 仓库补对应回归用例；其余项均可在不改公共签名的前提下完成。JDK8 兼容红线本次扫描零违规，资源关闭与 equals/hashCode 未发现问题。
diff --git a/docs/reports/2026-07-20-warm-flow-orm-quality-report.md b/docs/reports/2026-07-20-warm-flow-orm-quality-report.md
new file mode 100644
index 0000000000000000000000000000000000000000..7efe878497c563cba636dc373875b8f74cca5516
--- /dev/null
+++ b/docs/reports/2026-07-20-warm-flow-orm-quality-report.md
@@ -0,0 +1,312 @@
+<!-- 由代码质量审查任务生成（2026-07-20，分支 feature-ui-npm）。
+     纯只读静态审查产物；Top 级发现已由主流程抽查核实（FlowTaskMapper.xml:257 缺 flow_status=、
+     :62 node_type 绑定 nodeCode、UISort "asc".equals("ASC") 反向、MP @TableLogic(0/1) 硬编码、
+     根 pom java17.path Windows 硬路径、TenantDeleteUtil 仅存在于 mybatis-core——全部属实）。 -->
+
+# warm-flow-orm 代码质量审查报告
+
+审查范围：`warm-flow-orm/` 全部 21 个 git 跟踪的 pom + 3 套 ORM 的全部 Java 源码与 mapper XML，并对照 `warm-flow-core` 的 `WarmDao`/`Page`/`WarmQuery`/`WarmFlow` 契约与 `sql/` 四库 DDL、`plugin-modes` 的 `BeanConfig` 装配链。方法：逐文件阅读 + ripgrep 全量扫描（Java9+ API、日志坏味道、license header、注册文件一致性、XML 语句清单比对）。未修改任何文件。
+
+---
+
+## 一、矩阵一致性（最重要）
+
+### 1.1 租户 + 逻辑删除：引擎级能力实际上只有 mybatis 实现，MP/EQ 静默失效
+
+【严重度 P0】【warm-flow-orm/warm-flow-mybatis/warm-flow-mybatis-core/.../utils/TenantDeleteUtil.java:39-50、warm-flow-mybatis-core/.../dao/WarmDaoImpl.java:50-129 vs warm-flow-mybatis-plus-core/.../dao/WarmDaoImpl.java:49-143、warm-flow-easy-query-core/.../dao/WarmDaoImpl.java:117-209】
+
+mybatis 版每个 DAO 操作都会走 `TenantDeleteUtil.getEntity(entity)`，把 `FlowEngine.tenantHandler().getTenantId()` 与 `logicNotDeleteValue` 注入查询/写入条件：
+
+```39:50:warm-flow-orm/warm-flow-mybatis/warm-flow-mybatis-core/src/main/java/org/dromara/warm/flow/orm/utils/TenantDeleteUtil.java
+ public static <T extends RootEntity> T getEntity(T entity) {
+ WarmFlow flowConfig = FlowEngine.getFlowConfig();
+ if (flowConfig.isLogicDelete()) {
+ entity.setDelFlag(flowConfig.getLogicNotDeleteValue());
+ }
+
+ TenantHandler tenantHandler = FlowEngine.tenantHandler();
+ if (ObjectUtil.isNotNull(tenantHandler)) {
+ entity.setTenantId(tenantHandler.getTenantId());
+ }
+ return entity;
+ }
+```
+
+而 MP 版 `WarmDaoImpl`（如 `selectById` 直接 `getMapper().selectById(id)`，`save` 直接 `insert(entity)`）与 EQ 版（`whereById(id)`、`insertable(entity)`）**全程不接触 `FlowEngine.tenantHandler()`，也没有等价的 utils 类**；core 的 `DataFillHandler.insertFill`（warm-flow-core/.../handler/DataFillHandler.java:61-68）也只填 id/时间/办理人，不填 tenantId。结论：配置了 `warm-flow.tenant_handler_path` 的用户切到 MP/EQ 后，插入不落 tenant_id、查询不按租户过滤——**跨租户数据可见**，除非用户自行配置 MP 的 TenantLineInnerInterceptor（仓库内 0 处注册，见 1.9 同一 grep）。逻辑删除同理：EQ 的 `deleteById/deleteByIds/delete` 全是物理删除（多个 DaoImpl 内注释自认「没有启用逻辑删除，执行物理删除」，如 FlowHisTaskDaoImpl.java:81）。
+
+建议修法：把 `TenantDeleteUtil` 语义下沉为 core 内跨 ORM 的强制切面（或在 MP/EQ 的 WarmDaoImpl 每个方法显式补条件）；EQ 侧用 easy-query 拦截器实现 tenant + logic delete；无法实现前，在 README/文档明确「引擎自带租户/逻辑删除仅 mybatis 生效」，并在 MP/EQ starter 启动时对 `tenantHandlerPath`/`logicDelete` 配置打 WARN。
+
+### 1.2 逻辑删除值：MP `@TableLogic(value="0", delval="1")` 硬编码，与 WarmFlow 可配置值（默认删除值 "2"）冲突
+
+【严重度 P1】【warm-flow-orm/warm-flow-mybatis-plus/warm-flow-mybatis-plus-core/.../entity/FlowDefinition.java:76-77（8 个实体同样写法）vs warm-flow-core/.../config/WarmFlow.java:61-71】
+
+```76:77:warm-flow-orm/warm-flow-mybatis-plus/warm-flow-mybatis-plus-core/src/main/java/org/dromara/warm/flow/orm/entity/FlowDefinition.java
+ @TableLogic(value = "0", delval = "1")
+ private String delFlag;
+```
+
+而 core 默认 `logicDeleteValue = "2"`、`logicNotDeleteValue = "0"`（WarmFlow.java:66/71）。三套行为：mybatis 按配置（默认关，开了写 "2"）；MP **无视 `warm-flow.logic_delete` 开关永远逻辑删除**（@TableLogic 是实体级无条件生效），删除值恒 "1"；EQ 永远物理删除。同一引擎三种删除语义、两种删除标记值，数据层面互不兼容（换 ORM 后 del_flag=1 的行 mybatis 认为「未删除」除非配置匹配）。
+
+建议修法：统一约定 del_flag 值（建议 0/1）写进 core 默认值与四库 DDL 注释；MP 侧改为读取全局配置（`GlobalConfig.DbConfig.logicDeleteValue`）或移除注解改走引擎自带路径，保证「开关 + 值」三 ORM 一致。
+
+### 1.3 排序方向：EQ 把核心默认 "ASC" 全部当成降序执行
+
+【严重度 P1】【warm-flow-orm/warm-flow-easy-query/warm-flow-easy-query-core/.../utils/UISort.java:36-38、50 vs warm-flow-core/.../utils/page/Page.java:65、WarmQuery.java:45/137】
+
+```36:39:warm-flow-orm/warm-flow-easy-query/warm-flow-easy-query-core/src/main/java/org/dromara/warm/flow/orm/utils/UISort.java
+ String isAsc = page.getIsAsc();
+ Map<String, Boolean> queryMap = new HashMap<>();
+ queryMap.put(orderBy, "asc".equals(isAsc));
+ return new UISort(queryMap);
+```
+
+core 的规范值是大写：`Page.isAsc = "ASC"`、`WarmQuery.orderByAsc()` 设 `"ASC"`。`"asc".equals("ASC")` 为 false → EQ 对所有走 core API 的升序请求实际执行 **DESC**。MP 侧对应写法 `page.getIsAsc().equals(SqlKeyword.ASC.getSqlSegment())`（mp WarmDaoImpl.java:71-72）用大写比较，规范值正确但小写 "asc" 会反向；mybatis 直接字符串拼接大小写皆可。三 ORM 对同一 `isAsc` 值给出两种排序结果。
+
+建议修法：统一 `equalsIgnoreCase("asc")`（EQ、MP 都改），或在 core `Page/WarmQuery` setter 里规范化大小写。
+
+### 1.4 按实体查询的「有效条件字段集」三 ORM 漂移（部分条件被静默丢弃）
+
+【严重度 P1】【多处，代表性证据如下】
+
+- EQ `FlowDefinitionDaoImpl.buildWhereCondition`（easy-query-core/.../FlowDefinitionDaoImpl.java:64-79）缺 `category`、`activityStatus`、`listenerType`、`listenerPath`、`ext`（实体有这些字段，FlowDefinition.java:84-105）→ EQ 下按分类/激活状态筛选流程定义的条件被静默忽略，返回全部。
+- EQ `FlowNodeDaoImpl.buildWhereCondition`（FlowNodeDaoImpl.java:71-92）缺 `anyNodeSkip`；EQ `FlowInstanceDaoImpl.buildWhereCondition`（FlowInstanceDaoImpl.java:54-70）缺 `activityStatus`。
+- mybatis `FlowInstanceMapper.xml` 的 `select_parameter`（FlowInstanceMapper.xml:61-81）缺 `node_type` 条件（MP/EQ 都有）。
+- MP 用 `new QueryWrapper<>(entity)` 全字段生效，是三者中唯一「全量」的。
+
+同一 `service.list(entity)` 调用在三个 ORM 下 where 子句不同。
+
+建议修法：以实体字段全集为基准补齐 EQ 的 `buildWhereCondition` 与 mybatis 的 `select_parameter`，并建立「实体字段 ↔ 条件模板」核对清单（新增字段时三处同步）。
+
+### 1.5 easy-query sb3/sb4 starter 与 sb-starter 同 FQCN 类重复打包
+
+【严重度 P1】【warm-flow-orm/warm-flow-easy-query/warm-flow-easy-query-sb3-starter/src/main/java/org/dromara/warm/flow/spring/boot/config/FlowAutoConfig.java:34（sb4 同）+ sb3-starter/pom.xml:17-21】
+
+eq-sb3/sb4 各自带一份与 sb-starter **逐字节相同**的 `org.dromara.warm.flow.spring.boot.config.FlowAutoConfig`（三份文件内容一致），同时 pom 又依赖 `warm-flow-easy-query-sb-starter`（sb3-starter/pom.xml:17-21，未 exclude）→ 运行时 classpath 上同一 FQCN 出现在两个 jar 里（类加载顺序不确定、将来一旦其中一份修改即行为分叉）。对比 mybatis/mp 的 sb3/sb4 是「无源码、纯 pom 重打包」方案（warm-flow-mybatis-sb3-starter 无 src 目录），矩阵内两种互相矛盾的做法。
+
+建议修法：删除 eq-sb3/sb4 中的重复类与重复注册文件，向 mybatis/mp 的纯 pom 方案对齐。
+
+### 1.6 Solon 侧「after 钩子」三种私搭写法，存在装配顺序与重复 Bean 风险
+
+【严重度 P2】【三个 solon FlowAutoConfig + plugin-modes-solon/.../BeanConfig.java:140-156】
+
+SB 版 `BeanConfig.initFlow()` 内置 `after(warmFlow)` 钩子（plugin-modes-sb/.../BeanConfig.java:141-153）；Solon 版 `BeanConfig` **没有 after 钩子**，于是三个 ORM 各自发明：
+
+- mybatis：`@Bean WarmFlow initFlow(@Db Configuration db1Cfg, WarmFlow flowConfig)`（mybatis-solon-plugin/.../FlowAutoConfig.java:36-40）——再注册一个 WarmFlow 类型 Bean；
+- mybatis-plus：`@Bean WarmFlow after()` 里 `return FlowEngine.getFlowConfig()`（mp-solon-plugin/.../FlowAutoConfig.java:36-41）——**无任何注入参数保证 `BeanConfig.initFlow` 先执行**，若先跑则 `getFlowConfig()` 为 null（副作用 `IdUtils.setInstanceNative` 虽仍执行，但注册出 null Bean/时序不定）；
+- easy-query：`@Bean WarmFlow after(@Db EasyEntityQuery entityQuery, WarmFlow flowConfig)`（eq-solon-plugin/.../FlowAutoConfig.java:40-50），且**覆盖**了 BeanConfig 里设置的 `FrameInvoker.setBeanFunction`，判断式 `clazz.isAssignableFrom(EasyEntityQuery.class)` 方向可疑（对 `getBean(Object.class)` 也会返回 entityQuery）。
+
+另外 Solon 下 `plugin-modes-solon` 插件已 `beanMake(BeanConfig.class)`，各 ORM 插件又 `beanMake(FlowAutoConfig.class)`（其为 BeanConfig 子类）——继承的 `@Bean` 方法是否被二次注册取决于 Solon 的方法扫描实现，需实测确认（本次静态审查无法定论，标记验证项）。
+
+建议修法：在 solon 版 `BeanConfig` 补一个与 SB 对齐的 `after(WarmFlow)` 模板方法，三个 ORM 统一 override，废弃三种私搭 `@Bean WarmFlow`。
+
+### 1.7 mybatis：SB 设置 `setJdbcTypeForNull(JdbcType.NULL)`，Solon 不设置
+
+【严重度 P2】【warm-flow-mybatis-sb-starter/.../FlowAutoConfig.java:60 vs warm-flow-mybatis-solon-plugin/.../WarmFlowDaoSolonPlugin.java:39-59】
+
+SB 版 `loadXml` 里 `configuration.setJdbcTypeForNull(JdbcType.NULL)`；Solon 版只解析 XML 不设置该项。动态 insert/update 传 null 参数时（引擎 XML 大量 `<if>` 但仍有 null 经过，如批量 insert `#{item.xxx}` 不带 `<if>`），Oracle 驱动会抛「无效的列类型: 1111」——同一 ORM 在 SB 正常、Solon 报错。顺带：该行**改的是宿主应用全局 mybatis Configuration**，对宿主有副作用，建议文档声明。
+
+建议修法：Solon 事件回调中补 `e.setJdbcTypeForNull(JdbcType.NULL)`，或两侧都改为仅对 warm-flow 语句生效的方案。
+
+### 1.8 MP 分页依赖宿主注册 PaginationInnerInterceptor，warm-flow 未注册、未校验
+
+【严重度 P1】【warm-flow-mybatis-plus-core/.../WarmDaoImpl.java:66-83；全仓 `MybatisPlusInterceptor|PaginationInnerInterceptor` 0 命中】
+
+MP 版 `selectPage` 直接 `getMapper().selectPage(pagePlus, queryWrapper)`。仓库内没有任何地方注册 MP 分页拦截器，宿主应用若未自行配置，MP 的 selectPage **不截断 SQL、全量拉取**（MyBatis-Plus 已知行为），UI 的任务/定义分页列表在大表下变全表扫描且「看起来正常」。mybatis 版自带方言分页、EQ 自带 `toPageResult`，只有 MP 有此隐性前置条件。
+
+建议修法：starter 里 `@ConditionalOnMissingBean` 注册带 PaginationInnerInterceptor 的 MybatisPlusInterceptor，或启动时检测缺失并 WARN + 文档写明。
+
+### 1.9 注册文件矩阵本身核对结果
+
+【严重度 P3（记录）】SB2 `spring.factories` 与 SB3/4 `AutoConfiguration.imports` 在 mybatis/mp/eq 的 sb-starter 内均成对存在且指向同一 `FlowAutoConfig`（内容一致）；solon 三个插件 properties 分别指向 `WarmFlowDaoSolonPlugin`（mybatis、mp）与 `XPluginImpl`（eq）——**插件类命名不统一**（P3，建议 eq 更名对齐）；mybatis/mp 的 sb3/sb4 无自身注册文件、复用传递进来的 sb-starter 注册文件（可行，但与 eq 方案冲突，见 1.5）。
+
+### 1.10 其它对齐差异（合并列出）
+
+【严重度 P2】【warm-flow-mybatis-core/.../WarmDaoImpl.java:65-75 vs mp WarmDaoImpl.java:66-83、eq WarmDaoImpl.java:132-144】mybatis 版 `selectPage` 返回 `new Page<>(list, total)` **不回填 pageNum/pageSize**（返回体里恒为默认 1/10），MP/EQ 均显式回填；且 mybatis 版先 `page.setPageNum((pageNum-1)*pageSize)`（oracle 再改 pageSize）**破坏性修改调用方传入的 Page 对象**，复用该对象二次查询会错页。建议：不改入参、返回时回填原始分页参数。
+
+【严重度 P2】批量能力：mybatis `saveBatch` 单条多值 INSERT（分 mysql/oracle 方言）、MP `saveBatch` 循环单条 insert（N 条 SQL，N+1 风味）、EQ 走真 JDBC batch；`updateBatch` 三家都是循环单条。性能特征差异大，且循环中途失败无事务兜底（事务归宿主）。建议 MP 侧改用 `Db.saveBatch` 或 SqlSession batch；文档声明事务边界。
+
+【严重度 P3】EQ `FlowHisTask` 多出 `@ColumnIgnore private String createBy`（easy-query-core/.../FlowHisTask.java:123-125），mybatis/MP 版没有该字段；EQ `FlowDefinitionDaoImpl.queryByCodeList` 独有 `.useInterceptor()`（FlowDefinitionDaoImpl.java:42，全 orm 仅此一处），语义来源不明。建议对齐或注释说明。
+
+---
+
+## 二、重复代码
+
+【严重度 P2】【eq 三个 starter 的 FlowAutoConfig.java（sb/sb3/sb4 逐字节相同，各 45 行）】纯复制，见 1.5，应只保留 sb-starter 一份。
+
+【严重度 P2】【warm-flow-mybatis-sb-starter/.../FlowAutoConfig.java:55-70 与 warm-flow-mybatis-solon-plugin/.../WarmFlowDaoSolonPlugin.java:39-59】同一份 8 个 XML 的 mapperList + XMLMapperBuilder 加载逻辑复制两份（mp-solon 又一份，mp-solon-plugin/.../WarmFlowDaoSolonPlugin.java:39-59）。可下沉到 mybatis-core（或 mp-core）的一个静态工具 `WarmFlowMapperLoader.load(Configuration)`，三处调用。
+
+【严重度 P2】【warm-flow-mybatis-core/src/main/resources/warm/flow/*.xml】8 份 XML 中 `paging_end`、`order_by`、oracle ROWNUM 分页骨架、`deleteById/updateByIdLogic/deleteByIds/updateByIdsLogic` 模板完全重复 8 次（例如 FlowDefinitionMapper.xml:51-59 与 FlowUserMapper.xml:34-42 全同）。这正是 1.4/三章多处单点笔误（#{id}、#{entity.skip}、缺 `flow_status =`）的温床。建议引入代码生成或至少建立模板 + diff 校验脚本。
+
+【严重度 P3】【warm-flow-mybatis-plus-core/src/main/resources/warm/flow/*.xml（8 个文件共 62 行）】MP 的 8 份 mapper XML 全是**空壳**（只有 namespace，无任何语句），却仍被 mp-solon 插件逐个解析加载。属于从 mybatis 模块复制后掏空的遗留物。建议删除文件并同步删除 solon 插件的加载列表。
+
+【严重度 P3】【warm-flow-easy-query-core/.../FlowUserDaoImpl.java:88 与 92】`buildWhereCondition` 中 `o.createBy().eq(...)` 重复两次。删一处。
+
+【严重度 P3】【三 ORM 的 8 个实体 ×3 份复制】字段注释已开始漂移：EQ `FlowHisTask.formPath` 注释写成「审批表单是否自定义（Y是 2否）」（easy-query-core/.../FlowHisTask.java:131-132），mybatis 版 `FlowHisTask.formPath` 注释也复制错为「审批表单是否自定义」（mybatis-core/.../FlowHisTask.java:160-163）。实体无法下沉（ORM 注解不同），但注释/字段清单应以 core 接口为基准统一校对。
+
+【严重度 P3】【5 份 sb3/sb4 pom 的 maven-compiler/jar 插件配置重复】（mybatis-sb3/sb4、mp-sb3、eq-sb3/sb4）内容相同的 fork-JDK17 配置复制五份且与 mp-sb4 不一致，建议抽成父 pom 的 pluginManagement + profile。
+
+---
+
+## 三、正确性缺陷
+
+### 3.1 flow_task updateById：flowStatus 分支缺 `flow_status =` 前缀，生成非法 SQL
+
+【严重度 P1】【warm-flow-orm/warm-flow-mybatis/warm-flow-mybatis-core/src/main/resources/warm/flow/FlowTaskMapper.xml:257】
+
+```255:258:warm-flow-orm/warm-flow-mybatis/warm-flow-mybatis-core/src/main/resources/warm/flow/FlowTaskMapper.xml
+ <if test="nodeName != null and nodeName != ''">node_name = #{nodeName},</if>
+ <if test="nodeType != null">node_type = #{nodeType},</if>
+ <if test="flowStatus != null and flowStatus != ''">#{flowStatus},</if>
+ <if test="definitionId != null">definition_id = #{definitionId},</if>
+```
+
+带 flowStatus 的任务更新会生成 `SET node_code=?, ?, definition_id=?` → SQLSyntaxErrorException。`IWarmService.updateById` 是公开 API，下游可直接触发。修法：改为 `flow_status = #{flowStatus},`。
+
+### 3.2 flow_task 条件拼错参数：node_type 绑定了 nodeCode
+
+【严重度 P1】【同文件:62】
+
+```62:62:warm-flow-orm/warm-flow-mybatis/warm-flow-mybatis-core/src/main/resources/warm/flow/FlowTaskMapper.xml
+ <if test="entity.nodeType != null">and t.node_type = #{entity.nodeCode}</if>
+```
+
+按 nodeType 查任务时用 nodeCode 值比较 node_type，查询结果恒错（一般为空）。修法：`#{entity.nodeType}`。
+
+### 3.3 flow_his_task 条件参数漏 `entity.` 前缀 → BindingException
+
+【严重度 P1】【FlowHisTaskMapper.xml:74】`<if test="entity.id != null ">and t.id = #{id}</if>`——多 @Param 语句中无顶层 `id` 参数，`selectList/selectCount` 带 id 条件即抛 `Parameter 'id' not found`。修法：`#{entity.id}`。
+
+### 3.4 flow_skip 两处参数错写 → 运行时异常
+
+【严重度 P1】【FlowSkipMapper.xml:66、70-72】`and t.skip_name = #{entity.skip}`（FlowSkip 无 `skip` 属性，OGNL ReflectionException）与 `and t.skip_condition =#{skipCondition}`（无顶层参数，BindingException）。修法：`#{entity.skipName}` / `#{entity.skipCondition}`。
+
+### 3.5 flow_user 两处参数错写 → BindingException
+
+【严重度 P1】【FlowUserMapper.xml:204、330】`listByProcessedBys` 单办理人分支 `and t.processed_by = #{processedBy}`（应为 `#{entity.processedBy}`；DAO 恰好在 `processedBys.size()==1` 时走此分支，FlowUserDaoImpl.java:71-74，属可达路径）；`updateLogic` 中 `and type = #{type}`（应为 `#{entity.type}`）。
+
+### 3.6 flow_user.type 列的方言引用错乱：Oracle/SQL Server 直接报错
+
+【严重度 P1】【FlowUserMapper.xml:178-190、212-224 + sql/oracle/oracle-wram-flow-all.sql:283】
+
+`listByAssociatedAndTypes` 只对 postgresql 用 `t."type"`，其余（含 oracle、sqlserver）用反引号 `` t.`type` `` → Oracle ORA-00911、SQL Server 语法错误；`listByProcessedBys` 把 oracle 归入双引号分支，但 Oracle DDL 建列是**未加引号的 `TYPE`**（存储为大写），`t."type"`（小写带引号）→ ORA-00904 不存在的列。即：涉及 flow_user 按 type 过滤的路径在 Oracle 两种写法都错、SQL Server 反引号也错。修法：`type` 在四库都不是必须引用的保留字，统一写裸列名 `t.type`（PostgreSQL 建表用了 `"type"` 小写，裸写亦匹配）。
+
+### 3.7 SQL Server 分页完全缺失 + dataSourceType 探测值对不上
+
+【严重度 P1】【8 份 XML 的 paging_end（如 FlowDefinitionMapper.xml:51-55、180-197）+ CommonUtil.java:34-59】
+
+分页只有两个分支：oracle ROWNUM 与 `LIMIT #{pageSize} offset #{pageNum}`；SQL Server 不支持 LIMIT/OFFSET 语法（需 `OFFSET..FETCH`），而 `sql/sqlserver/sqlserver.sql` 又是官方交付的四库之一 → mybatis ORM 在 SQL Server 上分页必报错。且 `CommonUtil.setDataSourceType` 自动探测取 `getDatabaseProductName().toLowerCase()`，SQL Server 返回 "microsoft sql server"，与任何分支都不匹配、兜底 mysql。修法：XML 增加 sqlserver 分支（OFFSET..FETCH），探测值做规范化映射（contains("sql server") → "sqlserver"）。
+
+### 3.8 flow_form updateById 硬编码 `now()`，Oracle/SQL Server 方言不兼容
+
+【严重度 P2】【FlowFormMapper.xml:250-267】`<trim prefix="SET" ...>...</trim>, update_time=now()`：`now()` 在 Oracle（SYSDATE）/SQL Server（GETDATE()）非法；且当 trim 内容全空时生成 `update flow_form , update_time=now()` 非法 SQL；还与其它 7 张表「update_time 用 `#{updateTime}`」的写法不一致（form 的 updateTime 实体值被忽略）。修法：与其它 mapper 对齐，用 `<if test="updateTime != null">update_time = #{updateTime},</if>` 放入 trim。
+
+### 3.9 flow_node insert 的 permission_flag 误嵌套在 nodeName 条件内
+
+【严重度 P2】【FlowNodeMapper.xml:272-274、296-298】
+
+```272:274:warm-flow-orm/warm-flow-mybatis/warm-flow-mybatis-core/src/main/resources/warm/flow/FlowNodeMapper.xml
+ <if test="nodeName != null and nodeName != ''">node_name,
+ <if test="permissionFlag != null and permissionFlag != ''">permission_flag,</if>
+ </if>
+```
+
+nodeName 为空时 permission_flag 被静默丢弃（列/值两侧同构，不炸 SQL 但丢数据）。修法：解开嵌套，两个 `<if>` 平级。
+
+### 3.10 `${order}` 排序拼接是 SQL 注入通道（mybatis 与 MP 双双存在）
+
+【严重度 P1】【8 份 XML 的 `order_by`（如 FlowUserMapper.xml:40-42）+ mybatis WarmDaoImpl.java:71/84 + mp WarmDaoImpl.java:70-72】
+
+mybatis：`order by ${order}`，order = `page.getOrderBy() + " " + page.getIsAsc()` 原样拼接；MP：`queryWrapper.orderBy(..., page.getOrderBy())` 列名同样不转义（MP orderBy 列名注入是官方明示风险）。core 的 `IWarmService.orderBy(String)`/`WarmQuery.orderBy(String)` 是公开 API，下游把 HTTP 参数透传即形成注入。EQ 因走属性名→列名映射（UISort camelCase + EQ 校验）是唯一安全实现。修法：core 层对 orderBy 做标识符白名单校验（`[a-zA-Z0-9_.]+`）+ isAsc 枚举化，mybatis/MP 共用校验；文档警示。
+
+### 3.11 空集合 in() 生成非法 SQL
+
+【严重度 P2】【FlowTaskMapper.xml:202-211（无 size>0 守卫）、mp FlowTaskDaoImpl.java:56-61（`.in(FlowTask::getNodeCode, nodeCodes)` 无条件）】`TaskServiceImpl.java:151-152` 用 `suffixNodeCodes`（可能为空列表）调用 `getByInsIdAndNodeCodes` → mybatis 生成 `in ()` 语法错误、MP 生成 `IN ()` 同错；EQ 的 `in(空)` 由框架降级为 false 条件，行为又不一致。修法：XML 加 `<if test="nodeCodes != null and nodeCodes.size() > 0">`（同文件 getByInsAndNodeCodes 的写法），MP 加 `CollUtil.isNotEmpty` 条件。
+
+### 3.12 EQ listByTaskIdAndCooperateTypes 条件表达式写错
+
+【严重度 P2】【warm-flow-easy-query-core/.../FlowHisTaskDaoImpl.java:68】`proxy.taskId().eq(Objects.nonNull(proxy.taskId()), taskId)`——`proxy.taskId()` 永非 null，条件恒真；taskId 为 null 时生成 `task_id = NULL` 恒假。应为 `Objects.nonNull(taskId)`。
+
+### 3.13 flow_user 物理删除路径缺租户过滤
+
+【严重度 P2】【FlowUserMapper.xml:341-346 vs 348-358】`deleteByTaskIds`（物理删）没有 tenant_id 条件，而同语义的 `updateByTaskIdsLogic`（逻辑删）有 `entity.tenantId` 条件；DAO 两个分支传的是同一个 `TenantDeleteUtil.getEntity(...)`（FlowUserDaoImpl.java:48-55）。修法：物理删分支补 `<if test="entity.tenantId...">and tenant_id = #{entity.tenantId}</if>`（其余表的 deleteByIds 均有，此处独漏）。
+
+### 3.14 OGNL 数值字段与 '' 比较的隐患
+
+【严重度 P3】【FlowHisTaskMapper.xml:289】`<if test="entity.taskId != null and entity.taskId != ''">`——taskId 是 Long，OGNL 中数值与 '' 比较按 0 处理，taskId=0 时条件被跳过；同文件其它数值字段均只判 null。统一去掉 `!= ''`。
+
+事务边界、时间/ID 类型：orm 层无 `@Transactional`（事务在 plugin-ui controller 与宿主应用），`DefServiceImpl.removeDef` 等跨 DAO 多写操作依赖宿主事务——作为 SDK 属可接受设计，但建议在 README 明示；时间统一 `java.util.Date`、ID 统一 Long（雪花/MP IdWorker），未发现类型处理缺陷。
+
+---
+
+## 四、MyBatis XML 与实体一致性、四库方言
+
+除三章已列的 3.1–3.9、3.11、3.13 外：
+
+【严重度 P3】【FlowHisTaskMapper.xml:29/31、FlowTaskMapper.xml:18-19】resultMap 映射 `business_id`、`flow_name` 列，但 `flow_his_task`/`flow_task` 表（sql/mysql/warm-flow-all.sql 建表语句）没有这两列，`selectVo` 也不查——死映射，实体的 businessId/flowName 实际由 service 层组装。建议删映射或注释说明来源。
+
+【严重度 P3】【FlowDefinitionMapper.xml:309-317、FlowFormMapper.xml:269-277 + FlowDefinitionMapper.java:34】`closeFlowByCodeList` 两处 XML 语句 + 一处接口方法，core 的 `FlowDefinitionDao`/`DefService` 均未声明调用（FlowFormMapper 接口甚至没有该方法）——死代码，且硬编码 `is_publish = 9`（魔法数，对应 PublishStatus.EXPIRED）。建议删除或补全调用链。
+
+【严重度 P3】【FlowHisTaskMapper.xml:356-382 vs 440-465 vs 467-503】同文件内部不一致：`updateById` 的 SET 不含 approver；`delete` 条件含 collaborator 不含 approver；`updateLogic` 条件两者都含。建议按实体字段全集统一。
+
+【严重度 P2（评估性结论）】四库方言总体：批量 insert 仅分 mysql（多值 VALUES，PG/SQLServer 兼容）与 oracle（`union all from dual`）两支，可用；分页缺 sqlserver（见 3.7）；`flow_user.type` 引用错乱（见 3.6）；`now()`（见 3.8）。除上述外未发现其他方言问题。
+
+---
+
+## 五、JDK8 兼容
+
+**未发现。** 全目录扫描 `var`/`record`/文本块/switch 表达式/instanceof 模式/`List.of`/`Map.of`/`Optional.isEmpty`/`String.isBlank`/`strip`/`Files.readString`/Java9+ import 均 0 命中。说明：EQ DAO 中的 `.toList()`（如 easy-query-core/.../WarmDaoImpl.java:128）是 easy-query `EntityQueryable` 自身 API，非 `Stream.toList()`，不构成违规。sb3/sb4 starter 以 JDK17 编译属刻意为之（对应 SB3/4 基线）。
+
+---
+
+## 六、依赖与打包
+
+【严重度 P1】【根 pom.xml:73 + warm-flow-mybatis-sb3-starter/pom.xml:63-66（另 mybatis-sb4:68-71、mp-sb3:74-77、eq-sb3:42-45、eq-sb4:58-61）】
+
+```73:73:pom.xml
+ <java17.path>D:\software\jdk\jdk-17.0.1\bin\</java17.path>
+```
+
+5 个 sb3/sb4 starter 用 `<fork>true</fork><executable>${java17.path}\javac</executable>` 编译——硬编码 Windows 盘符路径 + 反斜杠，macOS/Linux 或任何非该路径机器上 `mvn install` 直接失败（不可移植的发布构建）。且 mp-sb4（pom.xml:79-88）没有 fork 配置，同类模块两种编译方式。修法：改用 maven-toolchains-plugin 或 `<release>17</release>`，删除机器路径。
+
+【严重度 P2】【warm-flow-mybatis-plus-sb4-starter/pom.xml:17-19 vs 根 pom.xml:96】mp-sb4 私设 `mybatis-plus.version=3.5.15`（父管理为 3.5.12，mp-sb3 又本地重复声明 3.5.12），mybatis-sb3/sb4 也各自私设 `mybatis-spring-boot3=3.0.3`/`mybatis-spring-boot4=4.0.1`——违反「版本统一在父 pom」约定，同一 ORM 各 starter 实际带出的 MP 版本不一致（3.5.12 vs 3.5.15）。修法：全部上收父 pom properties（如 `mybatis-plus4.version`）。
+
+【严重度 P2】【warm-flow-easy-query-core/pom.xml:33-37】`com.easy-query:sql-processor`（APT 注解处理器）按默认 compile scope 声明，会**传递泄漏到所有下游使用方的运行时 classpath**。修法：加 `<scope>provided</scope>` 或 `<optional>true</optional>`（proxy 类已随 jar 发布，消费者无需 APT）。
+
+【严重度 P3】【warm-flow-mybatis-plus-sb4-starter/target/classes/org/dromara/warm/flow/orm/jackson3/JsonConvertJackson3.class + META-INF/services/...JsonConvert】target 中残留**源码树已删除**的旧 JsonConvert 实现与 SPI 注册文件（现改为依赖 `warm-flow-plugin-json-jackson3`）。若发布前不 `mvn clean` 会把幽灵 SPI 打进 jar 造成 JsonConvert 双实现。修法：发布流程强制 clean；确认 1.8.9 正式产物无此文件。
+
+其余核对：lombok 均 provided ✓；各模块版本均走 `${warm-flow}`/父管理 ✓；sb-starter 同时带 spring.factories + AutoConfiguration.imports 属兼容性冗余，可接受；solon 插件对 `org.noear:solon` compile scope 符合 Solon 生态惯例。
+
+---
+
+## 七、日志 / 异常 / 坏味道
+
+【严重度 P2】【warm-flow-mybatis-core/.../utils/CommonUtil.java:40-51】探测数据库类型时 **两层 catch 全静默吞掉**（连 debug 日志都没有，throw 被注释），失败后兜底 mysql——Oracle 用户若取连接失败会静默用 LIMIT 分页然后在深处报错，难排查。修法：catch 中至少 `log.warn("探测数据库类型失败，dataSourceType 回退为 mysql", e)`。
+
+【严重度 P3】【warm-flow-mybatis-sb-starter/.../FlowAutoConfig.java:67-69、mybatis-solon .../WarmFlowDaoSolonPlugin.java:56-58、mp-solon 同】XML 加载失败 `throw new RuntimeException(e)` 裸包装、无上下文信息（哪个 mapper 失败）。建议带 mapper 路径信息的专用异常/日志。
+
+【严重度 P2】【warm-flow-easy-query-core/.../utils/UISort.java:1、FlowFormDaoImpl.java:1】两个文件**缺 Apache 2.0 license header**（仓库红线要求每个 Java 文件保留）。补齐 header 与 `@author`。
+
+【严重度 P3】【warm-flow-mybatis-plus-core/.../keygen/MybatisPlusIdGen.java:37-43】`synchronized nextId()` 且每次调用 `FrameInvoker.getBean(IdentifierGenerator.class)`——高频取号路径上「全局锁 + 容器查找」，IdWorker/IdentifierGenerator 本身线程安全，锁多余。建议缓存 bean、去掉 synchronized。
+
+【严重度 P3】【warm-flow-easy-query-core/.../WarmDaoImpl.java:61-63】用实例初始化块 `{ entityClass = getGenericClass(); }` + 反射取泛型，风格晦涩（可放构造器）；`TenantDeleteUtil` 类注释写「mybatis-plus 租户和逻辑删除工具类」但位于 mybatis 模块（TenantDeleteUtil.java:24-25，注释复制错误）。
+
+【严重度 P3】【warm-flow-easy-query-core/.../FlowFormDaoImpl.java:12-17】`@className/@description` 空模板注释，与仓库类注释规范不符。
+
+---
+
+## Top 10 优先整改清单
+
+| # | 项 | 严重度 | 位置 |
+|---|---|---|---|
+| 1 | 租户/逻辑删除仅 mybatis 生效，MP/EQ 静默失去租户隔离与逻辑删除 | P0 | 1.1（MP/EQ WarmDaoImpl 全部方法） |
+| 2 | MP `@TableLogic(0/1)` 硬编码且无视开关，与引擎默认值 2/0、EQ 物理删三方分裂 | P1 | 1.2（MP 8 个实体） |
+| 3 | `${order}`/MP orderBy 列名不校验的 SQL 注入通道（公开 API 可达） | P1 | 3.10（8 份 XML + 两个 WarmDaoImpl） |
+| 4 | flow_task `updateById` 缺 `flow_status =`、`node_type = #{entity.nodeCode}` 两处必错 SQL | P1 | 3.1/3.2（FlowTaskMapper.xml:257、62） |
+| 5 | 五处参数绑定错写（#{id}、#{entity.skip}、#{skipCondition}、#{processedBy}、#{type}）运行时异常 | P1 | 3.3–3.5 |
+| 6 | flow_user.type 方言引用在 Oracle/SQL Server 全错 + SQL Server 分页缺失 + 探测值不匹配 | P1 | 3.6/3.7（FlowUserMapper.xml、CommonUtil） |
+| 7 | EQ 排序方向反转（core 默认 "ASC" 被当 DESC）；EQ 条件字段缺失致过滤条件静默丢弃 | P1 | 1.3/1.4（UISort.java:38、各 buildWhereCondition） |
+| 8 | MP 分页依赖宿主拦截器未注册即全表返回 | P1 | 1.8（mp WarmDaoImpl.selectPage） |
+| 9 | `java17.path` Windows 硬路径 fork 编译，非 Windows 构建必失败；子 pom 私设版本漂移（MP 3.5.12/3.5.15） | P1/P2 | 6.x（根 pom.xml:73 + 5 个 starter pom） |
+| 10 | eq sb3/sb4 与 sb-starter 同 FQCN 重复类打包；MP 空 mapper XML、closeFlowByCodeList 等死代码清理 | P1/P3 | 1.5/2.x/4.x |
+
+补充说明（不确定性如实报告）：本次为纯只读静态审查，未执行编译与运行验证；「Solon 下 `BeanConfig` 与其子类 `FlowAutoConfig` 双 beanMake 是否导致继承 @Bean 方法重复注册」（1.6）依赖 Solon 版本实现细节，建议用 warm-flow-test 仓库在 Solon 3.10 下实测后再定级。
diff --git a/warm-flow-ui/src/assets/styles/index.scss b/warm-flow-ui/src/assets/styles/index.scss
index edd0647263a77da17eea2f128fe1a33d2b203c04..7d3150d6ccfeb91cbef99e4c52d76abd736c9c00 100644
--- a/warm-flow-ui/src/assets/styles/index.scss
+++ b/warm-flow-ui/src/assets/styles/index.scss
@@ -571,6 +571,26 @@ html.dark {
     }
   }
 
+  /* --- LogicFlow Menu 节点/边右键菜单暗黑适配（LF 默认白底不设文字色，暗黑下继承浅色文字导致白底白字不可见） --- */
+  .lf-menu {
+    background: var(--wf-bg-white, #1f1f1f);
+    border: 1px solid var(--wf-border-color, #333333);
+    color: var(--wf-text-primary, #e0e0e0);
+    box-shadow: 0 4px 16px rgba(0, 0, 0, 0.45);
+
+    .lf-menu-item:hover {
+      background: var(--wf-bg-color, #141414);
+    }
+
+    .lf-menu-item__disabled {
+      color: var(--wf-text-secondary, #808080);
+
+      &:hover {
+        background: transparent;
+      }
+    }
+  }
+
   /* --- 全局滚动条暗黑适配 --- */
   ::-webkit-scrollbar-thumb {
     background: #4a4a4a;
diff --git a/warm-flow-ui/src/components/design/common/vue/baseInfo.vue b/warm-flow-ui/src/components/design/common/vue/baseInfo.vue
index 849780d65ec51dac84812ae55a94b608c685b6fc..e94c74b1f1dd9301f45a8f00b98a5f6b28fcfb54 100644
--- a/warm-flow-ui/src/components/design/common/vue/baseInfo.vue
+++ b/warm-flow-ui/src/components/design/common/vue/baseInfo.vue
@@ -131,6 +131,10 @@
 import { ref, onMounted, onUnmounted, watch } from "vue";
 import {listenerList} from "@/api/flow/definition.js";
 
+// 显式声明 emits：未声明时 Vue3 会把事件当作 attrs 透传，部分浏览器下引发
+// setAttribute 无效属性名异常（gitee #IJV7GC / PR #393 根因之一）
+const emit = defineEmits(['update:model-value', 'update:flow-name']);
+
 const { proxy } = getCurrentInstance();
 
 // 响应式屏幕检测
@@ -199,6 +203,7 @@ const form = ref({
 watch(() => props.logicJson, newValue => {
   if (newValue && Object.keys(newValue).length > 0) {
     Object.assign(form.value, newValue);
+    normalizeStringFields();
     setListenerData();
     // 移动端新增时强制默认仿钉钉（覆盖logicJson中可能为空的值）
     if (isMobile.value && !props.definitionId) {
@@ -235,6 +240,19 @@ const rules = {
 // 表单引用（用于校验）
 const formRef = ref();
 
+/**
+ * formPath / category 必须是字符串：el-tree-select 在部分（旧内核）浏览器下 v-model 可能回传数组，
+ * 数组渗入后会被下游组件展开成 DOM 属性，触发 setAttribute('0') 异常白屏（gitee #IJV7GC / PR #393）
+ */
+function normalizeStringFields() {
+  if (Array.isArray(form.value.formPath)) {
+    form.value.formPath = form.value.formPath[0] || '';
+  }
+  if (Array.isArray(form.value.category)) {
+    form.value.category = form.value.category[0] || '';
+  }
+}
+
 function setListenerData() {
   // 处理监听器数据
   if (form.value.listenerType) {
@@ -277,16 +295,17 @@ function validate() {
 
 function nameChange(flowName) {
   // 可以在这里添加额外的逻辑，比如验证或格式化
-  proxy.$emit('update:flow-name', flowName); // 如果需要通知父组件
+  emit('update:flow-name', flowName); // 如果需要通知父组件
 }
 
 function modelValueChange() {
-  proxy.$emit('update:model-value'); // 如果需要通知父组件
+  emit('update:model-value'); // 如果需要通知父组件
 }
 
 function getFormData() {
   form.value.listenerType = form.value.listenerRows.map(row => row.listenerType).join(",")
   form.value.listenerPath = form.value.listenerRows.map(row => row.listenerPath).join("@@")
+  normalizeStringFields();
   return form.value;
 }
 
diff --git a/warm-flow-ui/src/main.js b/warm-flow-ui/src/main.js
index da3fd4772d1e8717872f67306649f74c66f1e8cb..e077580e9d91eafcc1bff9e96983a80bbac5b37f 100644
--- a/warm-flow-ui/src/main.js
+++ b/warm-flow-ui/src/main.js
@@ -1,3 +1,24 @@
+/**
+ * 浏览器兼容兜底：拦截无效属性名的 setAttribute 调用，防止 DOMException 白屏（gitee #IJV7GC / PR #393）。
+ * 当第三方组件把数组展开为 DOM 属性时（如 v-bind 收到数组），Vue 会尝试 setAttribute('0', value)，
+ * 属性名以数字开头不符合 XML/HTML 规范，钉钉内嵌等旧 Chromium 内核浏览器会直接抛异常导致设计器崩溃。
+ * 这里跳过该类调用并告警，作为最后一道防线（根因侧修复见 baseInfo.vue 的 emits 声明与数组防护）。
+ */
+(function patchSetAttribute() {
+  const nativeSetAttr = Element.prototype.setAttribute;
+  Element.prototype.setAttribute = function (name, value) {
+    if (typeof name === 'string' && /^\d/.test(name)) {
+      console.warn(
+        '[Warm-Flow compat] Blocked invalid setAttribute("' + name + '", ...) on <'
+        + (this.tagName || 'unknown').toLowerCase()
+        + '>. Likely an array spread into DOM attrs by a third-party component.'
+      );
+      return;
+    }
+    return nativeSetAttr.call(this, name, value);
+  };
+})();
+
 import { createApp } from 'vue'
 
 import FcDesigner from '@form-create/designer';
diff --git a/warm-flow-vue-designer/src/components/design/FlowDesigner.vue b/warm-flow-vue-designer/src/components/design/FlowDesigner.vue
index 770a8709c953458cf77a26f65c27cdde3dc91b74..6d078cf6c473bd085ae5e55a02bf183dcb1854d1 100644
--- a/warm-flow-vue-designer/src/components/design/FlowDesigner.vue
+++ b/warm-flow-vue-designer/src/components/design/FlowDesigner.vue
@@ -314,10 +314,12 @@ const tooltipPosition = ref({ x: 0, y: 0 });
 const tooltipEdge = ref({});
 
 const handleOptionClick = (item: any) => {
-  if (item.icon === "between") {
+  // item.type 为节点类型（between/serial/parallel/inclusive）；item.icon 仅为弹层展示图标名
+  const nodeType = item.type || item.icon;
+  if (nodeType === "between") {
     addBetweenNode(lf.value, item.tooltipEdge);
   } else {
-    addGatewayNode(lf.value, item.tooltipEdge, item.icon);
+    addGatewayNode(lf.value, item.tooltipEdge, nodeType);
   }
   tooltipVisible.value = false;
   // 移动端/平板端：新增节点后自适应画布，确保所有节点可见
@@ -776,6 +778,65 @@ html.dark .container {
   border: 1px solid var(--wf-border-color) !important;
 }
 
+/* ========== LogicFlow 节点/边右键菜单（Menu 扩展） ==========
+   LF 默认样式白底且不设文字色：暗黑下页面继承浅色文字 → 白底白字不可见（gitee #IJVBTJ）。
+   这里统一走 --wf-* token（html.dark 自动翻转），亮暗两态均显式着色。 */
+.lf-menu {
+  background: var(--wf-bg-white, #fff);
+  border: 1px solid var(--wf-border-light, #efefee);
+  color: var(--wf-text-primary, #303133);
+  box-shadow: var(--wf-shadow-lg, 0 4px 16px rgba(0, 0, 0, 0.1));
+}
+
+.lf-menu .lf-menu-item:hover {
+  background: var(--wf-bg-color, #f3f3f3);
+}
+
+.lf-menu .lf-menu-item__disabled {
+  color: var(--wf-text-placeholder, #aaa);
+}
+
+.lf-menu .lf-menu-item__disabled:hover {
+  background: transparent;
+}
+
+/* ========== 仿钉钉边「+」加节点按钮 / 条件徽标（SVG 组，类名由 mimic/js/skip.ts 注入） ==========
+   悬浮放大 + 主色投影，让「可点击加节点」的示能更明显；transform-box 保证以按钮自身为中心缩放。 */
+.wf-edge-plus {
+  transform-box: fill-box;
+  transform-origin: center;
+  transition: transform 0.18s cubic-bezier(0.4, 0, 0.2, 1), filter 0.18s ease;
+  filter: drop-shadow(0 2px 6px rgba(64, 158, 255, 0.35));
+}
+
+.wf-edge-plus:hover {
+  transform: scale(1.18);
+  filter: drop-shadow(0 4px 10px rgba(64, 158, 255, 0.5));
+}
+
+.wf-edge-cond {
+  transform-box: fill-box;
+  transform-origin: center;
+  transition: transform 0.18s cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+.wf-edge-cond:hover {
+  transform: scale(1.08);
+}
+
+/* 仿钉钉网关胶囊 chip（类名由 mimic/js/gatewayView.ts 注入）：柔和投影 + hover 微放大 */
+.wf-gateway-chip {
+  transform-box: fill-box;
+  transform-origin: center;
+  transition: transform 0.18s cubic-bezier(0.4, 0, 0.2, 1), filter 0.18s ease;
+  filter: drop-shadow(0 2px 6px rgba(15, 23, 42, 0.10));
+}
+
+.wf-gateway-chip:hover {
+  transform: scale(1.06);
+  filter: drop-shadow(0 4px 10px rgba(15, 23, 42, 0.16));
+}
+
 /* ========== 加载态 / 空态覆盖层 ========== */
 .wf-state-overlay {
   position: absolute;
diff --git a/warm-flow-vue-designer/src/components/design/common/vue/baseInfo.vue b/warm-flow-vue-designer/src/components/design/common/vue/baseInfo.vue
index 28d14d4f3d978c52168f2761de0e203435ecacd3..ba7b2288c950899d8fe4a33f8318442929d2e597 100644
--- a/warm-flow-vue-designer/src/components/design/common/vue/baseInfo.vue
+++ b/warm-flow-vue-designer/src/components/design/common/vue/baseInfo.vue
@@ -202,6 +202,7 @@ watch(() => props.logicJson, newValue => {
     if (!form.value.formCustom) {
       form.value.formCustom = "N";
     }
+    normalizeStringFields();
     setListenerData();
     // 移动端新增时强制默认仿钉钉（覆盖logicJson中可能为空的值）
     if (isMobile.value && !props.definitionId) {
@@ -238,6 +239,19 @@ const rules = computed(() => ({
 // 表单引用（用于校验）
 const formRef = ref();
 
+/**
+ * formPath / category 必须是字符串：tree-select 在部分（旧内核）浏览器下 v-model 可能回传数组，
+ * 数组渗入后会被下游组件展开成 DOM 属性，触发 setAttribute('0') 异常白屏（gitee #IJV7GC / PR #393）
+ */
+function normalizeStringFields() {
+  if (Array.isArray(form.value.formPath)) {
+    form.value.formPath = (form.value.formPath[0] as string) || '';
+  }
+  if (Array.isArray(form.value.category)) {
+    form.value.category = (form.value.category[0] as string) || '';
+  }
+}
+
 function setListenerData() {
   // 处理监听器数据
   if (form.value.listenerType) {
@@ -293,6 +307,7 @@ function modelValueChange() {
 function getFormData() {
   form.value.listenerType = form.value.listenerRows.map(row => row.listenerType).join(",")
   form.value.listenerPath = form.value.listenerRows.map(row => row.listenerPath).join("@@")
+  normalizeStringFields();
   return form.value;
 }
 
diff --git a/warm-flow-vue-designer/src/components/design/mimic/js/gatewayModel.ts b/warm-flow-vue-designer/src/components/design/mimic/js/gatewayModel.ts
index 2bf341241c0b63790572ae91f674c7ca1595b08b..0efc75e64bebd3ab1fe564a2661918f25e89f727 100644
--- a/warm-flow-vue-designer/src/components/design/mimic/js/gatewayModel.ts
+++ b/warm-flow-vue-designer/src/components/design/mimic/js/gatewayModel.ts
@@ -4,9 +4,10 @@ export class GatewayModel extends RectNodeModel {
 
   initNodeData(data) {
     super.initNodeData(data);
-    this.width = 70;
+    this.width = 76;
     this.height = 30;
-    this.radius = 5;
+    // 全圆角胶囊（height/2），替代原 radius=5 的方角矩形，贴近现代 chip 质感
+    this.radius = 15;
   }
   getNodeStyle() {
     return setCommonStyle(super.getNodeStyle(), this.properties, "node", "mimic");
diff --git a/warm-flow-vue-designer/src/components/design/mimic/js/gatewayView.ts b/warm-flow-vue-designer/src/components/design/mimic/js/gatewayView.ts
index e31cbacfce76f5501af2648aaf7b848ed3640f57..8d05329e67b37d97dbfac458b35c685199e71e60 100644
--- a/warm-flow-vue-designer/src/components/design/mimic/js/gatewayView.ts
+++ b/warm-flow-vue-designer/src/components/design/mimic/js/gatewayView.ts
@@ -12,13 +12,14 @@ export abstract class GatewayView extends RectNode {
 
     // 创建一个包含图标和文本的容器
     if (incomingEdges.length > 1) {
+      // 汇聚（结束）网关只有图标：水平垂直居中于胶囊（24px 保证小尺寸下依然清晰）
       return h(
           'svg',
           {
-            x: x - width / 2  + 23,
-            y: y - height / 2 + 3,
-            width: 25,
-            height: 25,
+            x: x - 12,
+            y: y - 12,
+            width: 24,
+            height: 24,
             viewBox: '0 0 1024 1024',
           },
           [
@@ -41,12 +42,14 @@ export abstract class GatewayView extends RectNode {
     return this.getSvg(x, y, width, height, text.value, style)
   }
 
-  // 自定义节点外观
+  // 自定义节点外观：语义色胶囊 chip（阴影 / hover 放大见 FlowDesigner 全局样式 .wf-gateway-chip）
   getShape(): h.JSX.Element {
     const { model } = this.props;
     const { x, y, width, height, radius } = model;
     const style = model.getNodeStyle();
-    return h('g', {style: {
+    return h('g', {
+      className: 'wf-gateway-chip',
+      style: {
         cursor: 'pointer'
       }}, [
       h('rect', {
@@ -57,6 +60,7 @@ export abstract class GatewayView extends RectNode {
         ry: radius,
         width,
         height,
+        'stroke-width': 1.2,
       }),
       this.getLabelShape(),
     ]);
diff --git a/warm-flow-vue-designer/src/components/design/mimic/js/inclusive.ts b/warm-flow-vue-designer/src/components/design/mimic/js/inclusive.ts
index a0b4cfdd697cd87cc1e9e95e4091828fad4cb285..c758fad39cc3963760b6f8780d9cc0b23d3fc6ed 100644
--- a/warm-flow-vue-designer/src/components/design/mimic/js/inclusive.ts
+++ b/warm-flow-vue-designer/src/components/design/mimic/js/inclusive.ts
@@ -9,7 +9,7 @@ class InclusiveModel extends GatewayModel {
     applyClassicDesignColor(style, this.properties, '146,84,222');
     const inDesigner = typeof window !== 'undefined' && (window as any).__WF_FLOW_DESIGN_MODE__;
     if (inDesigner && typeof style._statusRgba === 'function') {
-      style.fill = style._statusRgba(0.12);
+      style.fill = style._statusRgba(0.15);
     }
     return style;
   }
@@ -19,12 +19,12 @@ class InclusiveView extends GatewayView {
 
   getSvg(x: number, y: number, width: number, height: number, textValue: string, style: { stroke: string, fill: string }): h.JSX.Element {
     return h('g', {}, [
-      // 图标 SVG
+      // 图标 SVG：垂直居中于胶囊，左内边距 9
       h('svg', {
-        x: x - width / 2,
-        y: y - height / 2 + 3,
-        width: 25,
-        height: 25,
+        x: x - width / 2 + 8,
+        y: y - 12,
+        width: 24,
+        height: 24,
         viewBox: '0 0 1024 1024',
       }, [
         // 单个输入边时的图标
@@ -45,14 +45,15 @@ class InclusiveView extends GatewayView {
             strokeWidth: 60,
         }),
       ]),
-      // 文本元素，相对于g元素定位
+      // 文本元素：随类型语义色着色 + 半粗，与图标同基线垂直居中
       textValue ? h('text', {
-        x: x - width / 2 + 27,
-        y: y - height / 2 + 20,
-        fontSize: 13,
+        x: x - width / 2 + 35,
+        y: y + 4.5,
+        fontSize: 12.5,
         style: {
           userSelect: 'none',
-          fill: 'var(--wf-text-primary, #303133)',
+          fill: style.stroke || '#409eff',
+          fontWeight: 600,
         }
       }, textValue) : null
     ]);
diff --git a/warm-flow-vue-designer/src/components/design/mimic/js/parallel.ts b/warm-flow-vue-designer/src/components/design/mimic/js/parallel.ts
index 37706500b2c07150a487061a01c9e2d073d0ea77..67dc3518495cf70ecf088ff075b7e015bc465ba5 100644
--- a/warm-flow-vue-designer/src/components/design/mimic/js/parallel.ts
+++ b/warm-flow-vue-designer/src/components/design/mimic/js/parallel.ts
@@ -10,7 +10,7 @@ class ParallelModel extends GatewayModel {
     applyClassicDesignColor(style, this.properties, '19,194,194');
     const inDesigner = typeof window !== 'undefined' && (window as any).__WF_FLOW_DESIGN_MODE__;
     if (inDesigner && typeof style._statusRgba === 'function') {
-      style.fill = style._statusRgba(0.12);
+      style.fill = style._statusRgba(0.15);
     }
     return style;
   }
@@ -21,12 +21,12 @@ class ParallelView extends GatewayView {
   getSvg(x: number, y: number, width: number, height: number, textValue: string, style: { stroke: string, fill: string }): h.JSX.Element {
     // 创建一个包含图标和文本的容器
     return h('g', {}, [
-      // 图标 SVG
+      // 图标 SVG：垂直居中于胶囊，左内边距 9
       h('svg', {
-        x: x - width / 2,
-        y: y - height / 2 + 3,
-        width: 25,
-        height: 25,
+        x: x - width / 2 + 8,
+        y: y - 12,
+        width: 24,
+        height: 24,
         viewBox: '0 0 1024 1024',
       }, [
         h('path', {
@@ -42,14 +42,15 @@ class ParallelView extends GatewayView {
           d: 'M512 970.453333a66.56 66.56 0 0 1-47.146667-19.626666L72.96 558.933333a66.346667 66.346667 0 0 1 0-94.293333L464.853333 72.533333a68.266667 68.266667 0 0 1 94.293334 0l391.893333 392.106667a66.346667 66.346667 0 0 1 0 94.293333L559.146667 950.826667a66.56 66.56 0 0 1-47.146667 19.626666z m0-853.333333a2.986667 2.986667 0 0 0-1.92 0L118.186667 509.866667a2.56 2.56 0 0 0 0 3.626666l391.893333 392.106667a3.2 3.2 0 0 0 3.84 0l391.893333-392.106667a2.986667 2.986667 0 0 0 0-3.626666L513.92 117.76a2.986667 2.986667 0 0 0-1.92-0.64z',
         }),
       ]),
-      // 文本元素，相对于g元素定位
+      // 文本元素：随类型语义色着色 + 半粗，与图标同基线垂直居中
       textValue ? h('text', {
-        x: x - width / 2 + 27,
-        y: y - height / 2 + 20,
-        fontSize: 13,
+        x: x - width / 2 + 35,
+        y: y + 4.5,
+        fontSize: 12.5,
         style: {
           userSelect: 'none',
-          fill: 'var(--wf-text-primary, #303133)',
+          fill: style.stroke || '#409eff',
+          fontWeight: 600,
         }
       }, textValue) : null
     ]);
diff --git a/warm-flow-vue-designer/src/components/design/mimic/js/serial.ts b/warm-flow-vue-designer/src/components/design/mimic/js/serial.ts
index e9f6dcf4465604321c0f6a5b31c7ec5a19f1c01b..0b0ab79a7acb4ef90e4cdbb4149a8be333b8805f 100644
--- a/warm-flow-vue-designer/src/components/design/mimic/js/serial.ts
+++ b/warm-flow-vue-designer/src/components/design/mimic/js/serial.ts
@@ -9,7 +9,7 @@ class SerialModel extends GatewayModel {
     applyClassicDesignColor(style, this.properties, '245,158,11');
     const inDesigner = typeof window !== 'undefined' && (window as any).__WF_FLOW_DESIGN_MODE__;
     if (inDesigner && typeof style._statusRgba === 'function') {
-      style.fill = style._statusRgba(0.12);
+      style.fill = style._statusRgba(0.15);
     }
     return style;
   }
@@ -19,12 +19,12 @@ class SerialView extends GatewayView {
 
   getSvg(x: number, y: number, width: number, height: number, textValue: string, style: { stroke: string, fill: string }): h.JSX.Element {
     return h('g', {}, [
-      // 图标 SVG
+      // 图标 SVG：垂直居中于胶囊，左内边距 9
       h('svg', {
-        x: x - width / 2,
-        y: y - height / 2 + 3,
-        width: 25,
-        height: 25,
+        x: x - width / 2 + 8,
+        y: y - 12,
+        width: 24,
+        height: 24,
         viewBox: '0 0 1024 1024',
       }, [
         // 单个输入边时的图标
@@ -41,14 +41,15 @@ class SerialView extends GatewayView {
           d: 'M554.666667 516.266667l107.946666-107.946667a30.506667 30.506667 0 0 0-42.666666-42.666667L512 473.173333l-107.946667-107.946666a30.506667 30.506667 0 0 0-42.666666 42.666666L469.333333 516.266667l-108.8 107.946666a30.506667 30.506667 0 1 0 42.666667 42.666667l108.8-107.306667 106.666667 107.733334a30.506667 30.506667 0 0 0 42.666666-42.666667z',
         }),
       ]),
-      // 文本元素，相对于g元素定位
+      // 文本元素：随类型语义色着色 + 半粗，与图标同基线垂直居中
       textValue ? h('text', {
-        x: x - width / 2 + 27,
-        y: y - height / 2 + 20,
-        fontSize: 13,
+        x: x - width / 2 + 35,
+        y: y + 4.5,
+        fontSize: 12.5,
         style: {
           userSelect: 'none',
-          fill: 'var(--wf-text-primary, #303133)',
+          fill: style.stroke || '#409eff',
+          fontWeight: 600,
         }
       }, textValue) : null
     ]);
diff --git a/warm-flow-vue-designer/src/components/design/mimic/js/skip.ts b/warm-flow-vue-designer/src/components/design/mimic/js/skip.ts
index 119abbb52f3e3fba3b75a749efcbc7e4b1ef1c40..dd5fbb529e27803645deb3c7ec2c765a0085c594 100644
--- a/warm-flow-vue-designer/src/components/design/mimic/js/skip.ts
+++ b/warm-flow-vue-designer/src/components/design/mimic/js/skip.ts
@@ -70,7 +70,8 @@ class SkipView extends CurvedEdge {
       let nextEdge = model.graphModel.edges.filter(edge => edge.sourceNodeId ===  model.sourceNode.id);
       // 如果上一个节点是互斥网关，并且网关后节点大于1个，也就是说是互斥网关结束节点时
       if (['serial', 'inclusive'].includes(model.sourceNode.type as string) && nextEdge.length > 1) {
-        const midPoint = [points[0][0], points[0][1] + offsetY - 10];
+        // +4 让徽标与网关胶囊留出呼吸间距，避免描边环贴住胶囊底边
+        const midPoint = [points[0][0], points[0][1] + offsetY + 4];
         plusElements = this.getForeignObject(midPoint, condColor, model.text.value);
       } else if (!model.properties.chartStatusColor) {
         const midPoint = [points[0][0], points[0][1] + offsetY];
@@ -89,7 +90,8 @@ class SkipView extends CurvedEdge {
 
       // 判断是否由横线变为竖线，并且是互斥网关
       if (model.sourceNode && ['serial', 'inclusive'].includes(model.sourceNode.type as string) && p0[1] === p1[1] && p0[0] !== p1[0]) {
-        const midPoint = [p2[0], p1[1] + offsetY];
+        // +4 与直连分支保持同一垂直落点，且徽标不压横向连线
+        const midPoint = [p2[0], p1[1] + offsetY + 4];
         plusElements = this.getForeignObject(midPoint, condColor, model.text.value);
       }
     }
@@ -109,14 +111,18 @@ class SkipView extends CurvedEdge {
   }
 
   private getForeignObject(midPoint: number[], stroke: string, text: string) {
+    // 设计态用主蓝渐变（chroma 规范），运行态（chartStatusColor）保留纯状态色
+    const isRuntime = !!this.props.model.properties.chartStatusColor;
+    const bg = isRuntime ? stroke : 'linear-gradient(135deg, #409eff 0%, #2b7de9 100%)';
+    const shadow = isRuntime ? '0 2px 6px rgba(0, 0, 0, 0.18)' : '0 2px 6px rgba(64, 158, 255, 0.35)';
     let elements: h.JSX.Element[] = [];
     elements = [
-      // 使用 SVG 图标代替原来的图形
+      // 条件设置徽标：圆角 chip + 底色描边环 + 投影（替代原 32px 实心大方块）
       h('foreignObject', {
-        x: midPoint[0] - 16,
+        x: midPoint[0] - 18,
         y: midPoint[1] - 20,
-        width: 32,
-        height: 32,
+        width: 36,
+        height: 36,
       }, [
         h('div', {
           style: {
@@ -127,11 +133,12 @@ class SkipView extends CurvedEdge {
             height: '100%'
           },
           innerHTML: `
-<div style="width: 32px; height: 32px; transform: rotate(0deg); display: flex; align-items: center; justify-content: center;">
-  <svg t="1751615394607" class="icon" viewBox="0 0 1024 1024" version="1.1" xmlns="http://www.w3.org/2000/svg" p-id="11883">
-    <path d="M853.5 960.7h-683c-59.3 0-106-46.8-106-106v-683c0-59.3 46.8-106 106-106h682.9c59.3 0 106 46.8 106 106v682.9c0.1 59.3-49.8 106.1-105.9 106.1z" fill="${stroke}" p-id="11884"></path>
+<div style="width: 31px; height: 31px; border-radius: 10px; display: flex; align-items: center; justify-content: center;
+  background: ${bg}; border: 2px solid var(--wf-bg-page, #fff); box-sizing: border-box; box-shadow: ${shadow};">
+  <!-- viewBox 裁至图形实际边界（原素材四周留白约 30%，不裁的话 19px 里只画出 ~9px 图形） -->
+  <svg viewBox="310 262 416 416" width="17" height="17" xmlns="http://www.w3.org/2000/svg">
     <path d="M666.4 564.7c31.2 9.4 49.9 37.4 46.8 68.6-3.1 31.2-31.2 53-62.4 53s-59.3-21.8-62.4-53c-3.1-31.2 15.6-59.3 46.8-68.6v-65.5c0-9.4-6.2-15.6-15.6-15.6H401.3c-9.4 0-15.6 6.2-15.6 15.6v65.5c31.2 9.4 49.9 37.4 46.8 68.6-3.1 31.2-31.2 53-62.4 53s-59.3-21.8-62.4-53c-3.1-31.2 15.6-59.3 46.8-68.6v-81.1c0-18.7 12.5-31.2 31.2-31.2h109.1v-81.1c-31.2-9.4-49.9-37.4-46.8-68.6 3.1-31.2 31.2-53 62.4-53s59.3 21.8 62.4 53-15.6 59.3-46.8 68.6v81.1h109.1c18.7 0 31.2 12.5 31.2 31.2v81.1z m-156-218.3c18.7 0 31.2-12.5 31.2-31.2S529.1 284 510.4 284s-31.2 12.5-31.2 31.2c0.1 15.6 15.6 31.2 31.2 31.2zM370.1 655.1c18.7 0 31.2-12.5 31.2-31.2s-12.5-31.2-31.2-31.2-31.2 12.5-31.2 31.2 15.6 31.2 31.2 31.2z m280.7 0c18.7 0 31.2-12.5 31.2-31.2s-12.5-31.2-31.2-31.2-31.2 12.5-31.2 31.2 12.5 31.2 31.2 31.2z"
-    fill="#FFFFFF" p-id="11885"></path>
+    fill="#FFFFFF"></path>
   </svg>
 </div>
 `,
@@ -144,20 +151,25 @@ class SkipView extends CurvedEdge {
       // 由于我们无法直接在当前环境中测量文本，我们使用一个估算方法
       // 通常每个字符大约占用 8-10 像素宽度（取决于字体）
       const charWidth = 8; // 每个字符的估计宽度
-      const padding = 10; // 左右内边距
+      const padding = 14; // 左右内边距
       const minWidth = 40; // 最小宽度
       const textWidth = Math.max(minWidth, text.length * charWidth + padding);
 
-      // 添加背景矩形
+      // 条件文本 pill：走 --wf-* token（暗黑自动翻转）；CSS 变量须放 style 而非 presentation 属性。
+      // y 偏移与放大后的徽标（下沿 +16）保持间距，避免文字胶囊压住徽标描边环
       elements.push(
           h('rect', {
             x: midPoint[0] - textWidth / 2,
-            y: midPoint[1] + 10,
+            y: midPoint[1] + 20,
             width: textWidth,
             height: 20,
-            fill: "#fff", // 背景颜色
-            rx: 3, // 圆角
-            ry: 3
+            'stroke-width': 1,
+            rx: 10, // 圆角胶囊
+            ry: 10,
+            style: {
+              fill: 'var(--wf-bg-white, #fff)',
+              stroke: 'var(--wf-border-lighter, #ebeef5)',
+            }
           })
       );
 
@@ -165,10 +177,10 @@ class SkipView extends CurvedEdge {
       elements.push(
           h('text', {
             x: midPoint[0],
-            y: midPoint[1] + 25,
-            fontSize: 13,
-            fill: "#000",
+            y: midPoint[1] + 34,
+            fontSize: 12,
             style: {
+              fill: 'var(--wf-text-regular, #606266)',
               userSelect: 'none',
               textAnchor: 'middle' // 文本居中对齐
             }
@@ -188,31 +200,38 @@ class SkipView extends CurvedEdge {
   }
 
   private getAddElements(midPoint: number[], obj, isCondition: boolean = false) {
+    const isPlus = !obj;
     if (!obj) {
       const x = midPoint[0]
       const y = midPoint[1]
       obj = [
+        // 描边把按钮从连线上「抬起来」，配合 CSS 投影与 hover 放大（见 FlowDesigner 全局样式 .wf-edge-plus）
+        // 注意：CSS 变量在 SVG presentation 属性里无效，必须走 style（暗黑模式自动切换描边底色）
         h('circle', {
           cx: x,
           cy: y,
           r: 13,
           fill: '#409eff',
+          'stroke-width': '2',
+          style: { stroke: 'var(--wf-bg-page, #fff)' },
         }),
         h('line', {
-          x1: x - 8,
+          x1: x - 6.5,
           y1: y,
-          x2: x + 8,
+          x2: x + 6.5,
           y2: y,
           stroke: 'white',
-          'stroke-width': '2',
+          'stroke-width': '2.2',
+          'stroke-linecap': 'round',
         }),
         h('line', {
           x1: x,
-          y1: y - 8,
+          y1: y - 6.5,
           x2: x,
-          y2: y + 8,
+          y2: y + 6.5,
           stroke: 'white',
-          'stroke-width': '2',
+          'stroke-width': '2.2',
+          'stroke-linecap': 'round',
         })
       ]
     }
@@ -220,6 +239,7 @@ class SkipView extends CurvedEdge {
     plusElements.push(
         h('g', {
           ...this.getEventHandlers(isCondition), // 根据 isCondition 动态选择事件处理器
+          className: isPlus ? 'wf-edge-plus' : 'wf-edge-cond',
           style: {
             pointerEvents: 'auto',
             cursor: 'pointer'
diff --git a/warm-flow-vue-designer/src/components/design/mimic/vue/EdgeTooltip.vue b/warm-flow-vue-designer/src/components/design/mimic/vue/EdgeTooltip.vue
index 0a4d8ed60e3adcbf54c2d945b9486bd8703daab1..4d58ee82b05342dff441d4293b95e5cfa4f0e9fb 100644
--- a/warm-flow-vue-designer/src/components/design/mimic/vue/EdgeTooltip.vue
+++ b/warm-flow-vue-designer/src/components/design/mimic/vue/EdgeTooltip.vue
@@ -1,9 +1,19 @@
 <template>
-    <div :style="tooltipStyle" @mouseenter="handleTooltipEnter" @mouseleave="handleTooltipLeave">
+    <div :style="tooltipStyle" class="edge-tooltip-pop" @mouseenter="handleTooltipEnter" @mouseleave="handleTooltipLeave">
+        <div class="tooltip-caption">{{ t('edgeTooltip.title') }}</div>
         <div class="tooltip-container">
-            <div v-for="(item, index) in options" :key="index" @click="handleClick(item)" class="tooltip-item">
-                <svg-icon :icon-class="item.icon" class="tooltip-icon" />
-                <span>{{ item.label }}</span>
+            <div
+                v-for="(item, index) in options"
+                :key="index"
+                class="tooltip-item"
+                :style="{ '--item-rgb': item.rgb }"
+                @click="handleClick(item)"
+            >
+                <span class="tooltip-icon"><svg-icon :icon-class="item.icon" /></span>
+                <span class="tooltip-meta">
+                    <span class="tooltip-label">{{ item.label }}</span>
+                    <span class="tooltip-desc">{{ item.desc }}</span>
+                </span>
             </div>
         </div>
     </div>
@@ -11,12 +21,11 @@
 
 <script setup lang="ts">
 import { computed } from 'vue';
-import { useDark } from '@/composables/useDark';
+import type { CSSProperties } from 'vue';
 import { useI18n } from '@/i18n';
 
 defineOptions({ name: 'EdgeTooltip' });
 
-const { isDark, themeColors } = useDark();
 const { t } = useI18n();
 
 interface EdgeTooltipProps {
@@ -30,11 +39,13 @@ const props = withDefaults(defineProps<EdgeTooltipProps>(), {
   tooltipEdge: () => ({}),
 });
 
+// type 供 FlowDesigner 加节点逻辑使用；icon 为展示用线性图标；
+// rgb 为类型语义色（与经典模式侧栏 / 仿钉钉网关设计态语义色严格一致：审批=蓝、互斥=橙、并行=青、包含=紫）
 const options = [
-  { icon: 'between', label: t('edgeTooltip.approval') },
-  { icon: 'serial', label: t('sidebar.serial') },
-  { icon: 'parallel', label: t('sidebar.parallel') },
-  { icon: 'inclusive', label: t('sidebar.inclusive') },
+  { type: 'between', icon: 'addBetween', rgb: '64,158,255', label: t('edgeTooltip.approval'), desc: t('edgeTooltip.approvalDesc') },
+  { type: 'serial', icon: 'addSerial', rgb: '245,158,11', label: t('sidebar.serial'), desc: t('edgeTooltip.serialDesc') },
+  { type: 'parallel', icon: 'addParallel', rgb: '19,194,194', label: t('sidebar.parallel'), desc: t('edgeTooltip.parallelDesc') },
+  { type: 'inclusive', icon: 'addInclusive', rgb: '146,84,222', label: t('sidebar.inclusive'), desc: t('edgeTooltip.inclusiveDesc') },
 ]
 
 const emit = defineEmits<{
@@ -42,22 +53,13 @@ const emit = defineEmits<{
   (e: 'close-tooltip'): void;
 }>();
 
-/** 动态计算 tooltip 样式，根据暗黑模式切换颜色 */
-const tooltipStyle = computed(() => ({
+/**
+ * 仅定位走内联样式；配色/圆角/阴影全部下沉到 CSS（--wf-* token），
+ * html.dark 下自动翻转，不再依赖 JS 侧 themeColors（库形态下 postMessage 通道未必接线）。
+ */
+const tooltipStyle = computed<CSSProperties>(() => ({
   top: `${props.position.y}px`,
   left: `${props.position.x + 20}px`,
-  position: 'absolute',
-  pointerEvents: 'auto',
-  backgroundColor: themeColors.value.tooltipBg,
-  border: `1px solid ${themeColors.value.tooltipBorder}`,
-  borderRadius: '12px',
-  boxShadow: themeColors.value.tooltipShadow,
-  padding: '6px',
-  fontSize: '13px',
-  zIndex: 1000,
-  color: themeColors.value.tooltipColor,
-  display: 'flex',
-  width: 'max-content'
 }));
 
 function handleTooltipEnter() {
@@ -77,64 +79,143 @@ const handleClick = (item: any) => {
 </script>
 
 <style scoped>
+.edge-tooltip-pop {
+  position: absolute;
+  pointer-events: auto;
+  z-index: 1000;
+  width: max-content;
+  padding: 10px;
+  font-size: 13px;
+  background-color: var(--wf-tooltip-bg, #fff);
+  border: 1px solid var(--wf-tooltip-border, #ebeef5);
+  border-radius: 14px;
+  box-shadow: 0 12px 32px rgba(15, 23, 42, 0.12), 0 2px 8px rgba(15, 23, 42, 0.06);
+  color: var(--wf-tooltip-color, #303133);
+  font-family: -apple-system, BlinkMacSystemFont, "SF Pro Text", "PingFang SC", "Helvetica Neue", "Microsoft YaHei", sans-serif;
+  -webkit-font-smoothing: antialiased;
+  animation: edge-tooltip-in 0.18s cubic-bezier(0.4, 0, 0.2, 1);
+  transform-origin: top left;
+
+  /* 暗黑模式：阴影加深（底色/描边/文字色由 --wf-tooltip-* token 自动翻转） */
+  html.dark &,
+  :global(html.dark) & {
+    box-shadow: 0 12px 32px rgba(0, 0, 0, 0.5), 0 2px 8px rgba(0, 0, 0, 0.35);
+  }
+}
+
+@keyframes edge-tooltip-in {
+  from {
+    opacity: 0;
+    transform: translateY(4px) scale(0.96);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0) scale(1);
+  }
+}
+
+/* 弹层小标题：弱化的说明性文字，非二级大标题 */
+.tooltip-caption {
+  font-size: 11px;
+  font-weight: 600;
+  letter-spacing: 1px;
+  color: var(--wf-text-secondary, #909399);
+  padding: 2px 8px 8px;
+  user-select: none;
+}
+
 .tooltip-container {
     display: grid;
     grid-template-columns: repeat(2, 1fr);
-    gap: 2px;
+    gap: 4px;
     width: 100%;
 }
 
 .tooltip-item {
     display: flex;
     align-items: center;
-    gap: 8px;
-    padding: 7px 14px 7px 8px;
+    gap: 10px;
+    padding: 8px 14px 8px 8px;
     cursor: pointer;
-    border-radius: 8px;
+    border-radius: 10px;
     white-space: nowrap;
-    transition: background-color 0.18s ease;
+    transition: background-color 0.18s ease, transform 0.18s ease;
 
+    /* hover：随类型语义色轻染 + 图标翻实色，一眼区分四种节点 */
     &:hover {
-      background-color: var(--wf-primary-lighter);
+      background-color: rgba(var(--item-rgb), 0.10);
+      transform: translateY(-1px);
+
+      .tooltip-icon {
+        background: rgb(var(--item-rgb));
+        color: #fff;
+        box-shadow: 0 4px 10px rgba(var(--item-rgb), 0.35);
+      }
+
+      .tooltip-label {
+        color: rgb(var(--item-rgb));
+      }
+    }
+
+    &:active {
+      transform: translateY(0);
     }
 
-    /* 暗黑模式 hover */
+    /* 暗黑模式 hover：染色略加深保证可见 */
     html.dark &,
     :global(html.dark) & {
       &:hover {
-        background-color: rgba(64, 158, 255, 0.12);
+        background-color: rgba(var(--item-rgb), 0.16);
       }
     }
 }
 
-.tooltip-item span {
-  font-size: 13px;
-  white-space: nowrap;
-}
-
 .tooltip-icon {
   flex: 0 0 auto;
   display: flex;
   align-items: center;
   justify-content: center;
-  width: 30px;
-  height: 30px;
-  background: var(--wf-primary-light);
-  border-radius: 50%;
+  width: 34px;
+  height: 34px;
+  color: rgb(var(--item-rgb));
+  background: rgba(var(--item-rgb), 0.12);
+  border-radius: 10px;
   transition: all 0.18s ease;
 
   svg {
-    width: 17px;
-    height: 17px;
+    width: 18px;
+    height: 18px;
   }
 
-  /* 暗黑模式适配 */
+  /* 暗黑模式：底色透明度略升，避免沉进深色面板 */
   html.dark &,
   :global(html.dark) & {
-    background: rgba(64, 158, 255, 0.16);
+    background: rgba(var(--item-rgb), 0.18);
   }
 }
 
+.tooltip-meta {
+  display: flex;
+  flex-direction: column;
+  gap: 1px;
+  min-width: 0;
+}
+
+.tooltip-label {
+  font-size: 13px;
+  font-weight: 600;
+  line-height: 1.3;
+  white-space: nowrap;
+  transition: color 0.18s ease;
+}
+
+.tooltip-desc {
+  font-size: 11px;
+  line-height: 1.3;
+  color: var(--wf-text-secondary, #909399);
+  white-space: nowrap;
+}
+
 /* ========== 手机端响应式适配 ========== */
 @media (max-width: 768px) {
   .tooltip-item {
@@ -142,14 +223,18 @@ const handleClick = (item: any) => {
   }
 
   .tooltip-icon {
-    width: 28px;
-    height: 28px;
+    width: 30px;
+    height: 30px;
 
     svg {
-      width: 15px;
-      height: 15px;
+      width: 16px;
+      height: 16px;
     }
   }
+
+  .tooltip-desc {
+    display: none;
+  }
 }
 
 @media (max-width: 480px) {
diff --git a/warm-flow-vue-designer/src/i18n/index.ts b/warm-flow-vue-designer/src/i18n/index.ts
index 7fdb0ce49867943ba32d3b70bd89931cce60c20b..d5fcafd0d7515afa9647e589d3c8dbc7bff58f20 100644
--- a/warm-flow-vue-designer/src/i18n/index.ts
+++ b/warm-flow-vue-designer/src/i18n/index.ts
@@ -235,7 +235,12 @@ const zh: WfMessageTree = {
     errIsolated: '存在 {n} 个孤立节点（未连任何边）'
   },
   edgeTooltip: {
-    approval: '审批'
+    title: '添加节点',
+    approval: '审批',
+    approvalDesc: '人工审批处理',
+    serialDesc: '多分支仅走一条',
+    parallelDesc: '多分支同时执行',
+    inclusiveDesc: '按条件走多条'
   },
   baseNode: {
     initiator: '发起人',
@@ -451,7 +456,12 @@ const en: WfMessageTree = {
     errIsolated: '{n} isolated node(s) (not connected to any edge)'
   },
   edgeTooltip: {
-    approval: 'Approval'
+    title: 'Add Node',
+    approval: 'Approval',
+    approvalDesc: 'Manual approval step',
+    serialDesc: 'Only one branch runs',
+    parallelDesc: 'All branches run',
+    inclusiveDesc: 'Conditional branches'
   },
   baseNode: {
     initiator: 'Initiator',
diff --git a/warm-flow-vue-designer/src/icons/wfIcons.ts b/warm-flow-vue-designer/src/icons/wfIcons.ts
index ed46ed2982840638a05a0932de42675e9f2aab69..9d5aa6b97b00df7f237016227401ac03793fceaa 100644
--- a/warm-flow-vue-designer/src/icons/wfIcons.ts
+++ b/warm-flow-vue-designer/src/icons/wfIcons.ts
@@ -68,6 +68,27 @@ export const wfIcons: IconifyJSON = {
       height: 1024,
       body: '<path d="M85.418667 512L512.021333 85.397333 938.624 512 512.021333 938.602667z" fill="#ecf5ff"/><path d="M512 714.453333A32 32 0 0 1 480 682.666667v-138.666667H341.333333a32 32 0 1 1 0-64h138.666667V341.333333a32 32 0 0 1 64 0v138.666667H682.666667a32 32 0 0 1 0 64h-138.666667V682.666667a32 32 0 0 1-32 31.786666z" fill="#409eff"/><path d="M512 970.453333a66.56 66.56 0 0 1-47.146667-19.626666L72.96 558.933333a66.346667 66.346667 0 0 1 0-94.293333L464.853333 72.533333a68.266667 68.266667 0 0 1 94.293334 0l391.893333 392.106667a66.346667 66.346667 0 0 1 0 94.293333L559.146667 950.826667a66.56 66.56 0 0 1-47.146667 19.626666z m0-853.333333a2.986667 2.986667 0 0 0-1.92 0L118.186667 509.866667a2.56 2.56 0 0 0 0 3.626666l391.893333 392.106667a3.2 3.2 0 0 0 3.84 0l391.893333-392.106667a2.986667 2.986667 0 0 0 0-3.626666L513.92 117.76a2.986667 2.986667 0 0 0-1.92-0.64z" fill="#409eff"/>'
     },
+    /* ===== 边「+」加节点弹层专用线性图标（currentColor，可随类型语义色着色） ===== */
+    addBetween: {
+      width: 24,
+      height: 24,
+      body: '<circle cx="12" cy="8.2" r="3.4" fill="none" stroke="currentColor" stroke-width="1.7"/><path d="M5.2 19.2c0-3.3 3-5.6 6.8-5.6s6.8 2.3 6.8 5.6" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round"/>'
+    },
+    addSerial: {
+      width: 24,
+      height: 24,
+      body: '<path d="M12 2.6 21.4 12 12 21.4 2.6 12Z" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linejoin="round"/><path d="M9.4 9.4l5.2 5.2M14.6 9.4l-5.2 5.2" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round"/>'
+    },
+    addParallel: {
+      width: 24,
+      height: 24,
+      body: '<path d="M12 2.6 21.4 12 12 21.4 2.6 12Z" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linejoin="round"/><path d="M12 8.4v7.2M8.4 12h7.2" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round"/>'
+    },
+    addInclusive: {
+      width: 24,
+      height: 24,
+      body: '<path d="M12 2.6 21.4 12 12 21.4 2.6 12Z" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linejoin="round"/><circle cx="12" cy="12" r="3.6" fill="none" stroke="currentColor" stroke-width="1.7"/>'
+    },
     formDesign: {
       width: 1024,
       height: 1024,
diff --git a/warm-flow-vue-designer/src/ui/antdvAdapter.ts b/warm-flow-vue-designer/src/ui/antdvAdapter.ts
index 4c7ee9f6bb12696f631c1604eb1757ba19c8973e..e91622552d1a0fd806a2f09120d2cf4c717282e9 100644
--- a/warm-flow-vue-designer/src/ui/antdvAdapter.ts
+++ b/warm-flow-vue-designer/src/ui/antdvAdapter.ts
@@ -288,7 +288,13 @@ const AntCheckbox = vModelComp('WfAntCheckbox', ACheckbox, 'checked', (props, ra
 const AntTreeSelect = vModelComp('WfAntTreeSelect', ATreeSelect, 'value', (props, raw) => {
   if (raw.data != null) { props.treeData = raw.data; delete props.data }
   if (raw.props != null) { props.fieldNames = raw.props; delete props.props }
-  if (raw['check-strictly'] != null) { props.treeCheckStrictly = raw['check-strictly']; delete props['check-strictly'] }
+  if (raw['check-strictly'] != null) {
+    // EP 的 check-strictly（父子不联动、任意节点可选）只在勾选（多选）模式下才对应 antd 的
+    // treeCheckStrictly；单选 TreeSelect 本就任意节点可选，若误传 treeCheckStrictly 会被 antd
+    // 判定为 checkable 模式，进而告警「value should be an array」且值形态错乱。
+    if (raw.multiple != null || raw.treeCheckable != null) props.treeCheckStrictly = raw['check-strictly']
+    delete props['check-strictly']
+  }
   delete props['value-key']
   // antd TreeSelect 不接受空串作为 value，空值统一为 undefined
   if (props.value === '' || props.value == null) props.value = undefined