304 lines
18 KiB
Markdown
304 lines
18 KiB
Markdown
# `/system/module-management` 代码重构计划（还债专项）
|
||
|
||
> 本文是**纯代码重构**计划：不改任何行为、UI 文案、API 调用和保存协议。
|
||
> 与 `docs/module-management-refactor-plan.md`（功能改造历史记录）无关，请勿混淆。
|
||
> 执行前请先通读本文第 1、2 节和第 8 节（禁改清单）。
|
||
|
||
## 1. 背景与问题
|
||
|
||
模块管理功能已基本完成，但代码存在三类结构性债务：
|
||
|
||
1. **巨型文件**：`ModuleFormEditPanel.vue` 3709 行、`ModuleTableEditPanel.vue` 2962 行、
|
||
`index.vue` 1522 行，全模块约 1.2 万行。
|
||
2. **三处复制的"同源"逻辑**：分组树推导在面板与结构树组件间整段复制（注释自述
|
||
"与面板 bandMeta 同源"）；两个编辑面板共享约 20 个同名函数。靠人肉同步，改一处漏
|
||
一处就是 bug。
|
||
3. **index.vue 职责过重**：树管理、草稿加载、保存编排、删除级联、i18n 协调、确认弹窗
|
||
全部平铺在一个 `<script setup>` 里，`saveModule` 单函数约 120 行。
|
||
|
||
目标：在不改变任何外部行为的前提下消除上述债务，让后续功能开发有清晰的落点。
|
||
|
||
## 2. 当前代码范围（行数为 2026-08 时点，执行时以符号名为准）
|
||
|
||
```text
|
||
src/views/system/module-management/
|
||
index.vue 1522 容器：树 + 草稿 + 保存编排
|
||
common.js 6
|
||
components/
|
||
ModuleFormEditPanel.vue 3709 主表表单设计器
|
||
ModuleTableEditPanel.vue 2962 子表表格设计器
|
||
ModuleBasicPanel.vue / ModuleFieldsPanel.vue / ModuleListConfigPanel.vue
|
||
ModuleQueryConfigPanel.vue / ModuleAutoCodePanel.vue / ModulePowersPanel.vue
|
||
ModuleI18nPanel.vue / MenuDetailPanel.vue / I18nQuickSetModal.vue / IconSelect.vue
|
||
structure-tree/
|
||
ModuleStructureTree.vue 963 专用结构编辑树（拖拽/右键/重命名）
|
||
StructureTreeNode.vue 584 树节点（递归渲染）
|
||
tests/unit/
|
||
module-table-edit-panel-dnd.spec.js 443 拖拽语义测试（重构的安全网）
|
||
tree-external-drag.spec.js
|
||
utils.spec.js
|
||
```
|
||
|
||
现有 utils/composables 层（新代码遵循同样习惯）：
|
||
`@/utils/tree.js`（buildTree/sortTree）、`@/utils/dataChanges.js`（diffRows/tableChange/
|
||
allocateTemporaryIds/remapForeignKeys）、`@/utils/i18n.js`、`@/utils/tempId.js`、
|
||
`@/composables/useHotkeys.js`。
|
||
|
||
## 3. 同源复制清单（重构的核心对象）
|
||
|
||
### 3.1 分组树推导：`ModuleTableEditPanel.vue` ⟷ `structure-tree/ModuleStructureTree.vue`
|
||
|
||
以下符号在两个文件中各有一份、语义一致（面板版 bandMeta 额外计算 maxLevel）：
|
||
|
||
| 符号 | 作用 |
|
||
| --- | --- |
|
||
| `sortGroupNodesByXh` | 按 b_xh 排序分组节点（注意两处都注释了 toSorted 必须回写原数组） |
|
||
| `buildGroupTree` | 分组扁平数组 → 树 |
|
||
| `groupTree` / `groupNodeMap` | 树 computed / gid→节点 Map |
|
||
| `groupColumnsMap` | gid→直属列 Map + 未分组列数组 |
|
||
| `bandMeta` | 层级/ownCount/span/children 元信息（面板版含 maxLevel） |
|
||
| `isDescendantOf` / `isDescendantGroup` | 判断分组祖先-子孙关系（防拖入自身子树成环） |
|
||
| `FIELD_TYPE_LABELS` + `fieldNameMap` / `fieldMap` / `fieldName` / `controlTypeLabel` / `groupIdOfRow` | 字段查询与标签 |
|
||
|
||
### 3.2 两个编辑面板的共享函数：`ModuleFormEditPanel.vue` ⟷ `ModuleTableEditPanel.vue`
|
||
|
||
同名（或仅改名）且核心语义一致的符号：
|
||
|
||
`onEditModeChange`、`emitUpdate`、`onRowOrderChange`、`renumberRows`、
|
||
`groupIdOfRow`/`groupIdOf`、`fieldNameMap`、`fieldMap`、`fieldOf`、`fieldName`、
|
||
`controlTypeLabel`、`FIELD_TYPE_LABELS`、`libraryFields`、`isFieldAdded`、`nextGroupXh`、
|
||
`selectedRow`、`selectRow`、`createEditRow`、`insertField`、`selectField`、
|
||
`copyRowProps`、`pastePropsToSelected`、`toggleInspector`/`toggleRowFlag`、
|
||
`syncToList`、`syncToQuery`、`scrollToRowCell`/`scrollToRowCard`
|
||
|
||
**注意：同名不等于同体。** 例如 `createEditRow` 在表格面板写 `b_width`/`b_height`，
|
||
在表单面板写 `b_colspan` 等；`insertField` 的落点参数也不完全相同。抽取前必须逐对
|
||
diff 函数体，按第 5.2 节的三条规则归类，禁止强行合并。
|
||
|
||
## 4. 总体约束（每个阶段都适用）
|
||
|
||
1. **纯重构**：不改行为、不改 UI 结构与文案、不改 props/emits 契约（子面板对父级的
|
||
接口保持不变）、不改 API 调用与保存请求结构、不引入任何新依赖（包括拖拽库）。
|
||
2. **现有测试是安全网**：`tests/unit/module-table-edit-panel-dnd.spec.js` 及其它测试
|
||
必须全程绿；除 import 路径外不允许修改测试断言。若某步导致断言失败，说明该步
|
||
改变了行为，应回退重做。
|
||
3. **每阶段一个独立 commit**，commit message 注明阶段号。开始前若工作区有未提交
|
||
改动，先提交或暂存，保证基线干净。
|
||
4. **保持注释纪律**：项目注释是"为什么"型中文注释；搬运代码时注释随行；删除复制
|
||
体后，同步删除"与面板 bandMeta 同源"这类描述复制关系的注释（已不成立）。
|
||
5. **不重写响应式模型**：`localEdit` 本地副本 + watch props、`localGroups` 绕过回流
|
||
等模式虽然别扭但经过调试，本次只搬运不重新设计。
|
||
6. 每阶段结束运行：`pnpm test && pnpm lint`（最终再跑一次 `pnpm check`）。
|
||
|
||
## 5. 阶段任务
|
||
|
||
### 阶段一：抽取分组树推导 composable（风险最低、收益最大，先做）
|
||
|
||
新建 `src/views/system/module-management/composables/useGroupTree.js`：
|
||
|
||
```text
|
||
useGroupTree(groupsRef, rowsRef)
|
||
入参：groups 的 ref/computed（面板传 props 派生，结构树传 localGroups），
|
||
rows 的 ref/computed（编辑行数组）
|
||
返回：groupTree、groupNodeMap、groupColumnsMap、bandMeta（统一含 maxLevel）、
|
||
isDescendantGroup(ancestorGid, gid)、groupIdOfRow(row)
|
||
纯函数另行导出：buildGroupTree(groups)、sortGroupNodesByXh(nodes)
|
||
```
|
||
|
||
改造点：
|
||
|
||
- `ModuleTableEditPanel.vue`：删除本地 `sortGroupNodesByXh`/`buildGroupTree`/
|
||
`groupTree`/`groupNodeMap`/`groupColumnsMap`/`bandMeta`/`isDescendantOf`，改用
|
||
composable。`bandMeta` 统一含 `maxLevel` 后，`bandRows` 等消费处照常解构。
|
||
- `structure-tree/ModuleStructureTree.vue`：同样替换；其 `bandMeta` 消费处不使用
|
||
maxLevel，多余字段无害。
|
||
- **保持 watch 注册顺序**：`ModuleTableEditPanel.vue` 中 `watch(() => props.editConfig, …,
|
||
{ immediate: true })` 必须位于 bandMeta 等 computed 定义之后（原文件有 TDZ 注释，
|
||
搬运时不得把 watch 上移）。
|
||
|
||
验收：`pnpm test` 全绿；两个文件合计减少约 250 行；拖拽/右键/分组增删改手工冒烟
|
||
（见第 7 节清单）无变化。
|
||
|
||
### 阶段二：抽取字段查询与共享纯函数
|
||
|
||
1. 新建 `src/views/system/module-management/composables/useFieldLookup.js`：
|
||
|
||
```text
|
||
useFieldLookup(fieldsRef)
|
||
返回：fieldNameMap、fieldMap、fieldOf(row)、fieldName(row)、controlTypeLabel(row)
|
||
常量：FIELD_TYPE_LABELS
|
||
```
|
||
|
||
2. 新建 `src/views/system/module-management/editPanelShared.js`（纯函数，无 Vue 依赖）：
|
||
|
||
```text
|
||
renumberRows(rows) // (i+1)*10 重排
|
||
buildClipboardProps(row, fieldNameOf) // 复制列属性的键集合（两面板 diff 后统一）
|
||
applyClipboardProps(row, props)
|
||
buildVisibilityMap(rows) // syncToList/syncToQuery 共用的可见性 Map
|
||
```
|
||
|
||
3. 两个面板中 3.2 节列出的每个函数：先逐对 diff 函数体，再归三类处理——
|
||
- **完全相同** → 移入共享文件，原位改为导入；
|
||
- **语义相同、细节不同**（如 `createEditRow` 的默认值差异）→ 抽参数化工厂
|
||
（如 `createEditRowFactory(defaults)`），两面板各自传参；
|
||
- **本质不同** → 保留各自实现，不强行合并，在 PR 说明中列出。
|
||
4. `syncToList`/`syncToQuery` 结构高度一致（仅目标数组与写回字段不同）：用
|
||
`buildVisibilityMap` 共享取数部分，emit 与提示文案留在各自面板。
|
||
|
||
验收：`pnpm test` 全绿；两面板各减约 150–250 行；数据视图"同步到列表/查询配置"
|
||
行为与提示文案不变。
|
||
|
||
### 阶段三：拆分 index.vue
|
||
|
||
目标：index.vue 只保留模板、状态接线和面板编排（预期 ≤ 700 行）。抽出的
|
||
composables 放 `src/views/system/module-management/composables/`：
|
||
|
||
```text
|
||
useModuleTree.js 树状态与操作：moduleTreeData/Loading、moduleKeyword/ExpandedKeys、
|
||
unsavedModuleIds、loadModuleTree、markCategoryNonLeaf、moduleTypeIconMap、
|
||
filterTree/filteredModuleTree、collectAllKeys、expandAncestors、
|
||
findModuleNode、insertModuleNode、removeModuleNode、
|
||
hasSavedModuleDescendant、collectUnsavedModuleIds、
|
||
buildBreadcrumb/moduleBreadcrumb、addModule、deleteModule
|
||
useModuleConfig.js 草稿加载与脏检查：configLoading、originals/drafts、loadedModuleId、
|
||
loadModuleConfig、hasModuleChanges、reloadModule、
|
||
watch(moduleSelectedId) 及 skipModuleLoad 约定、onModuleSelect
|
||
useModuleSave.js 保存编排：saveModule、validateAutoCode、subTables 常量、
|
||
临时 id 分配与外键重映射、i18n reconcile 调用
|
||
useConfirm.js 两套确认弹窗：通用 showConfirm/onConfirmOk/confirmState 与
|
||
切换保护 switchConfirm/onSwitch*
|
||
```
|
||
|
||
要求：
|
||
|
||
- composable 返回 index.vue 模板所需的最小集合；跨 composable 共享的状态
|
||
（如 `selectedModule`）由 index.vue 组装后传入，避免 composable 互相 import。
|
||
- `saveModule` 依赖 `basicPanelRef`/`autoCodePanelRef`/`i18nPanelRef` 与
|
||
`finalI18nItems`，以参数（refs + getter）注入 `useModuleSave`，不移动模板。
|
||
- `onFieldsUpdate`/`applyDisabledFieldDefaults`/`onAutoCodeUpdate` 属于草稿派生
|
||
联动，随 `useModuleConfig` 或留在 index.vue 均可，以"内聚"为准并在 commit 说明。
|
||
|
||
验收：`pnpm test` 全绿；保存（含跨表外键重映射）、重载、切换未保存保护、删除模块
|
||
（含 i18n 孤儿键清理）手工冒烟无变化。
|
||
|
||
### 阶段四：编辑器目录化拆分（本计划的维护性核心，目标单文件 ≤ 700 行）
|
||
|
||
两个编辑面板各 3000+ 行、script/template/style 混在一个文件，是维护痛点的主要
|
||
来源。本阶段按"职责切分、只搬运不重写"把两个编辑器重组为目录：
|
||
|
||
```text
|
||
components/table-edit/
|
||
TableEditPanel.vue 壳：视图切换（设计/数据）、编辑方式切换（主表/子表）、布局编排 ≤ 300
|
||
FieldLibrary.vue 字段库：搜索 + 字段列表 + 拖出源（application/fms-field） ≤ 250
|
||
TablePreview.vue 多级表头预览表：band 行渲染、mock 行、预览拖拽落点指示 ≤ 500
|
||
TableInspector.vue 属性面板：列属性 / 分组带属性 / 空态三态 ≤ 400
|
||
useTablePreviewDrag.js 预览表拖拽：onPreviewDragStart/Over/Drop、落点指示状态 ≤ 180
|
||
useColumnResize.js 列宽拖拽：pointer capture 三件套 + 40–600 边界 ≤ 100
|
||
components/form-edit/
|
||
FormEditPanel.vue 壳：视图切换、编辑方式切换、布局编排 ≤ 300
|
||
FormCanvas.vue 画布：分组区块 + 字段卡片 + 24 栅格行 + 插入线 ≤ 700
|
||
FormInspector.vue 属性面板：栅格 / textarea 高度 / 状态开关等 ≤ 450
|
||
useFormDrag.js 拖拽：跟手卡片、insert line 计算、落点提交（updateDragIntent 等） ≤ 600
|
||
useFormGrid.js 栅格分配纯逻辑：collectLineIndexes/rebalanceInsert/distributeLine ≤ 200
|
||
components/edit-panels/
|
||
EditDataView.vue 两编辑器共享的数据视图：工具栏 + FmsTable + 行拖拽排序 ≤ 150
|
||
```
|
||
|
||
切分规则：
|
||
|
||
1. **壳组件保留对外契约**：`TableEditPanel.vue` / `FormEditPanel.vue` 对 index.vue 的
|
||
props/emits 完全不变，index.vue 只改 import 路径。
|
||
2. **状态归属**：`localEdit`、`localGroups`、选中态（selectedNodeKey/selectedRow）
|
||
留在壳组件，子组件通过 props/事件交互；`useXxx` composable 接收壳的 refs、返回
|
||
handlers 与状态，不自带数据源。
|
||
3. **样式随组件迁移**（scoped），BEM 类名前缀（`mm-fdesign-` / `mm-tdesign-`）保持
|
||
不变，避免测试选择器与深层样式选择器失效；全局样式（如 `.mst-drag-badge`）留在
|
||
原文件并保留注释说明。
|
||
4. `FieldLibrary` 两编辑器都需要但文案/点击行为有差异：优先做成参数化共享组件放在
|
||
`edit-panels/` 下；若 diff 后发现耦合过深，允许 form-edit 下保留一份薄的私有实现，
|
||
在交付说明中说明选择。
|
||
5. 原 `components/ModuleTableEditPanel.vue` / `ModuleFormEditPanel.vue` 删除，由
|
||
壳组件顶替（路径变化后同步更新 index.vue import 与测试中的 import 路径，仅此
|
||
一处允许改测试文件，断言不动）。
|
||
6. `structure-tree/` 已是独立目录，本阶段不动。
|
||
|
||
停损：`FormCanvas` + `useFormDrag` 是全计划最大风险点（表单画布模板与拖拽状态机
|
||
交织最深）。若拆 FormEditPanel 时出现难定位的行为差异，允许降级交付：完成
|
||
table-edit/ 目录重组 + form-edit 仅抽 `useFormGrid.js`（纯逻辑无 UI 搬迁，风险低），
|
||
其余记录到交付说明留待下轮。
|
||
|
||
验收：`pnpm test` 全绿（dnd spec 通过 StubDraggable 定位 `.mst-node`，不受影响）；
|
||
所有新文件 ≤ 700 行（参考目标）；设计/数据视图切换、属性面板编辑、列宽拖拽、
|
||
字段库点击/拖出手工冒烟无变化。
|
||
|
||
### 阶段五：收尾与小修
|
||
|
||
1. 硬编码颜色收敛到 token：`ModuleTableEditPanel.vue` 中 `#d95757`（危险红）、
|
||
`#fafbfc`（列头底色）、`#e7f6ed`/`#146c41`（已加入勾选）等，替换为
|
||
`--fms-*` 变量（项目已有 `--fms-danger` 类 token，先查 `src/styles/` 再定值；
|
||
没有合适 token 则新增，不硬编码第二次）。
|
||
2. `index.vue` 的 `deleteModule` 中 i18n 孤儿键清理 SQL 拼接（`b_key LIKE
|
||
'module.${code}.%'` 等）抽为 `@/utils/i18n.js` 的
|
||
`buildModuleI18nCleanupFilter(moduleType, moduleCode)`，并把"前缀匹配安全性依赖
|
||
`.` 与 `_` 不互撞"这一约定写成函数注释。调用处行为不变。
|
||
3. 检查全模块不再有"`module-management` 内重复定义 `FIELD_TYPE_LABELS`"等残留
|
||
（grep 确认单一定义点）。
|
||
|
||
### 阶段六：补测试
|
||
|
||
1. `tests/unit/module-form-edit-panel.spec.js`：参照
|
||
`module-table-edit-panel-dnd.spec.js` 的手法（StubDraggable、
|
||
`document.elementFromPoint` mock、defineProperty 注入坐标）覆盖 FormEditPanel 的
|
||
核心纯逻辑：栅格 rebalance（`collectLineIndexes`/`rebalanceInsert`/`distributeLine`）、
|
||
行内移动 `moveSelectedRow`、复制/粘贴属性。
|
||
2. 为 `composables/useGroupTree.js` 写直接单测：band 的 span/ownCount/层级计算、
|
||
参差深度、空分组占位、`isDescendantGroup` 防环。
|
||
3. 若阶段三已把保存编排中的纯计算（subTables diff 收集、外键重映射输入输出）
|
||
拆为可测函数，为其补 spec；否则跳过不强求。
|
||
|
||
验收：新增测试与既有测试全部通过；`pnpm check`（lint + fmt:check + build）通过。
|
||
|
||
## 6. 建议的执行顺序与停损点
|
||
|
||
- 顺序即阶段编号：一 → 二 → 三 → 四 → 五 → 六，每阶段独立 commit。
|
||
- 阶段四风险最高（模板与拖拽状态机大搬家），其内部自带停损规则（见阶段四末尾）；
|
||
最低交付线为 table-edit/ 重组 + useFormGrid 抽取。阶段一~三、五不允许跳过。
|
||
- 任何阶段若发现测试失败且 30 分钟内无法定位根因，回退该阶段 commit 并在交付
|
||
说明中记录现象。
|
||
|
||
## 7. 手工冒烟清单（每阶段结束过一遍，重点阶段一、三、四）
|
||
|
||
```text
|
||
模块树：搜索展开/收起、右键新增三种模块、未保存节点置灰不可作父级、删除级联
|
||
草稿：修改后切换模块弹三选一（保存并切换/放弃/取消）、重载确认、Ctrl/Cmd+S
|
||
表格设计器：拖列换位/入组/出组、拖分组嵌套与排序、拖入自身子树被禁止、
|
||
右键增删改分组、分组内联重命名、列宽拖拽与步进、Ctrl+C/X/V、Delete、
|
||
未分组悬浮落点（无未分组列时）、字段库点击加入/定位
|
||
表单设计器：字段拖入任意位置、插入线、栅格自动分配（12→6/6）、跨组移动、
|
||
textarea 高度、删除与恢复、同步到列表/查询
|
||
保存：新增字段+新增分组后保存一次成功（验证临时 id 分配与 b_field_id/b_group_id 重映射）
|
||
```
|
||
|
||
## 8. 明确不要做的事情
|
||
|
||
- 不改 `props/emits` 契约、不改保存请求结构、不改 API 参数。
|
||
- 不重写 `localEdit`/`localGroups` 的响应式数据流，不把双快照（originals/drafts）
|
||
模式换成其它脏检查方案。
|
||
- 不引入 TS、不引入新依赖、不做大规模重命名（`b_` 前缀数据库字段命名保持）。
|
||
- 不把 `ModuleFormEditPanel` 与 `ModuleTableEditPanel` 合并为一个编辑器组件
|
||
（允许共享叶子组件如 `EditDataView`/`FieldLibrary`，但两个编辑器本体各自独立）。
|
||
- 不删除任何"为什么"型注释；不修改既有测试的断言。
|
||
- 不顺手修 UI 细节/交互问题（发现则记录到交付说明，另开任务）。
|
||
|
||
## 9. 可直接交给其他 AI 的执行指令
|
||
|
||
在 `fms-vue` 项目中按照 `docs/module-management-code-refactor-plan.md` 执行代码重构。
|
||
先完整阅读该计划、`src/views/system/module-management/` 下的 index.vue、两个编辑面板、
|
||
structure-tree/ 两个组件以及 `tests/unit/module-table-edit-panel-dnd.spec.js`，再按
|
||
阶段一至阶段六逐步执行：每阶段一个 commit，阶段内先 diff 再抽取（同名函数不等于
|
||
同体），全程保持行为不变。每阶段结束运行 `pnpm test && pnpm lint` 并按第 7 节清单
|
||
手工冒烟；最终运行 `pnpm check`。交付时说明：各阶段修改的文件与行数变化、抽取的
|
||
共享符号清单、哪些同名函数被判定为"本质不同"而未合并、测试与构建结果、以及执行
|
||
过程中发现但未处理的问题。
|