@qilitt-mickey/vue3-temp-skill 1.0.12 → 1.1.2

package/references/data-compare.md

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