---
name: module-management-index-重构-面板自治
overview: 重构 fms-vue 模块管理页：将 index.vue（1600 行）中散落的面板数据回写回调与业务逻辑下放到各面板组件，index 只持有 drafts/originals 两份数据，通过 v-model 与面板双向绑定，保存时统一 diff。目标是将 index.vue 精简到 500 行以内。
todos:
  - id: diff-foundation
    content: 改造 utils/dataChanges.js：diffRows 增加剔除 _ / v_ 前缀字段，抽出 stripInternalKeys 供 diffRows 与 hasUnsavedChanges 共用
    status: completed
  - id: model-table-form-panels
    content: 模式 A/C 改造表格类与表单类面板：ModuleFieldsPanel、ModuleQueryConfigPanel、ModuleBasicPanel、ModuleAutoCodePanel 改 defineModel，去掉 local 副本、watch 同步与虚拟字段剥离
    status: completed
    dependencies:
      - diff-foundation
  - id: model-designers
    content: 用 [subagent:code-explorer] 与 [skill:lsp-code-analysis] 定位并改造 FormDesignEditor、TableDesignEditor 及壳组件 ModuleListConfigPanel、ModuleEditPanel 为 defineModel，useStructureEditing 只换写入口
    status: completed
    dependencies:
      - model-table-form-panels
  - id: index-rewire
    content: 重接 index.vue：全部面板改 v-model 双向绑定，删除 4 个 proxy 回调，新增分组引用清理、自动编码只读、i18n reconcile 三个跨面板 watch
    status: completed
    dependencies:
      - model-designers
  - id: sync-fields-down
    content: 将 buildSyncPlan、applySyncPlan、syncFields 迁入 ModuleFieldsPanel，同步按钮移至字段面板工具栏，index 相应删除调用与按钮
    status: completed
    dependencies:
      - index-rewire
  - id: extract-module-tree
    content: 新建 useModuleTree.js 抽出模块树的加载、新增、删除、拖拽排序与右键菜单逻辑，index.vue 改为解构接入
    status: completed
    dependencies:
      - sync-fields-down
  - id: verify-regression
    content: 编译校验与关键流程回归：新建模块保存、字段同步、分组增删、自动编码、i18n、模块拖拽排序、切换模块脏检查
    status: completed
    dependencies:
      - extract-module-tree
---

## 用户要求

对 `fms-vue/src/views/module/module-management/index.vue`（1600 行）进行职责解耦重构：

- **index.vue 只保留两个核心状态**：`drafts`（草稿数组对象）与 `originals`（基线数组对象），保存时执行一次 diff 即可。
- **各面板自治**：字段、列表、编辑、查询、自动编码、多语言、基础信息各自的编辑逻辑与数据写入，下沉到各自组件内部，通过 `v-model` 双向绑定自己那份数据，不再由父级中转。

## 产品概述

模块管理页面（左侧模块树 + 右侧分节配置面板）的内部架构重构，属纯前端逻辑层改造，页面功能与视觉表现保持不变，仅"同步字段"按钮从顶部通栏移入字段定义面板工具栏。

## 核心特性

- **数据所有权下沉**：7 个配置面板通过 `defineModel` 直接读写 `drafts` 中属于自己的那一份数据，父级不再提供 proxy 回调。
- **保存时统一 diff**：index.vue 保留 `drafts` / `originals` 两份快照，`handleSave` 时按主表 `diffRow`、子表 `diffRows`、i18n `buildI18nChangeRequest` 生成差异请求。
- **跨面板联动改为响应式**：分组删除清理引用、自动编码字段置只读、受管 i18n 键补齐，由事件回调改为父级 `watch` 幂等联动。
- **字段同步内聚**：`syncFields` / `buildSyncPlan` / `applySyncPlan` 整体移入 `ModuleFieldsPanel`，同步按钮随行迁至字段面板工具栏。
- **树逻辑外移**：模块树的加载、新增、删除、拖拽排序、右键菜单（约 250 行）抽为 `useModuleTree.js`。

## 预期效果

`index.vue` 由 1600 行降至 500 行以内，仅剩编排职责（树 + 草稿加载 + 保存编排 + 3 个跨面板 watch + 模板接线）；面板组件各自内聚、可独立测试。

## 技术栈

沿用项目现有技术栈，不引入新依赖：

- Vue 3 `<script setup>` + `defineModel`（Vue 3.4+ 稳定 API，项目中 `ModuleI18nPanel.vue` 已在使用）
- Vite + `@/components/ui` 自建组件库（`FmsTable` / `Form` / `Modal` 等）
- 数据层：通用 API `loadDataApi` / `saveObjectApi` / `nextIdApi` / `describeApi`
- 差异计算：`@/utils/dataChanges`（`diffRow` / `diffRows` / `allocateTemporaryIds` / `remapForeignKeys`）

## 实现思路

### 探索验证结论（决定方案可行性的 4 个事实）

1. **改造是封闭的**：`ModuleBasicPanel` / `ModuleFieldsPanel` / `ModuleListConfigPanel` / `ModuleEditPanel` / `ModuleQueryConfigPanel` / `ModuleAutoCodePanel` / `ModuleI18nPanel` / `TableDesignEditor` / `FormDesignEditor` 的全部引用点都在 `module-management/index.vue` 内，无外部调用者。改组件签名不会破坏其他页面。
2. **`cloneData` 是 JSON 深拷贝**，故 `drafts` 与 `originals` 完全独立，组件就地修改 `drafts` 的行对象不会污染基线，保存时 diff 依然准确。
3. **`useStructureEditing`（33KB 内核）无需任何改动**：它采用依赖注入，`localRows` / `localGroups` 副本 + `watch(getRows)` 同步 + `applyRows` / `applyGroups` 两个写入口均由宿主提供。改造只需把 getter 指向 model、把两个写入口改为写 model，其 `if (val === localRows.value) return` 防环逻辑天然继续生效，零循环风险。
4. **表格渲染不能依赖深度侦听**：`ModuleQueryConfigPanel` 注释明确 "stk-table 对同一引用数组的 push 不敏感，必须换新引用才会渲染新行"。故约定 **行内字段就地 patch + 提交时换新数组引用**。

### 架构设计

```mermaid
flowchart TB
  subgraph IDX["index.vue（编排层 ~500 行）"]
    direction TB
    TREE["useModuleTree.js<br/>树加载/新增/删除/拖拽排序/右键菜单"]
    ST["状态：originals + drafts"]
    LOAD["loadModuleConfig"]
    SAVE["handleSave<br/>validate → diffRow/diffRows<br/>→ 分配真实ID → 跨表重映射 → reload"]
    W1["watch: i18n reconcile（防抖300ms）"]
    W2["watch: 分组删除 → 清理引用"]
    W3["watch: 自动编码字段 → 置只读"]
  end

  B["ModuleBasicPanel"] <-->|"v-model"| ST
  F["ModuleFieldsPanel<br/>含 syncFields"] <-->|"v-model × 6"| ST
  L["ModuleListConfigPanel"] <-->|"v-model × 2"| ST
  E["ModuleEditPanel"] <-->|"v-model × 4"| ST
  Q["ModuleQueryConfigPanel"] <-->|"v-model"| ST
  A["ModuleAutoCodePanel"] <-->|"v-model"| ST
  I["ModuleI18nPanel"] <-->|"v-model:rows"| ST

  L --> TDE["TableDesignEditor"]
  E --> TDE
  E --> FDE["FormDesignEditor"]
  TDE --> USE["useStructureEditing<br/>（内核不改，仅换写入口）"]
  FDE --> USE

  ST --> SAVE
```

### 三种改造模式

**模式 A · 表格类面板**（`ModuleFieldsPanel` / `ModuleQueryConfigPanel`）

删除 local 副本与 `watch(props)` 同步，直接以 model 作为 `FmsTable` 数据源；行内编辑就地 patch，提交时换新数组引用触发渲染。

**模式 B · 设计器**（`TableDesignEditor` / `FormDesignEditor`）

保留 `useStructureEditing` 的 local 副本机制，仅替换注入的 getter 与两个写入口。这是本次改动中风险最低、收益最高的一处。

**模式 C · 表单类面板**（`ModuleBasicPanel` / `ModuleAutoCodePanel`）

`defineModel` 拿到对象引用后直接改属性即可（无需 emit，因为 `drafts.module` 与 `originals.module` 已是两份深拷贝）。

### 关键决策与权衡

| 决策 | 选择 | 理由 |
| --- | --- | --- |
| 是否抽 `useModuleTree` | **抽** | 250 行树逻辑与配置编辑零耦合；作为独立最后阶段，可单独验证与回退 |
| 同步字段按钮位置 | **移入 `ModuleFieldsPanel` 工具栏** | 符合"谁的数据谁负责"；若留顶部通栏需额外暴露 ref，反而增加耦合 |
| 步骤 1 是否拆分 | **拆成 1a 表格类 / 1b 设计器与表单类** | `FormDesignEditor` 96KB 为最大改动块，拆分降低单次回归风险 |
| 分组删除清理引用 | **改父级 `watch` 差集推断** | 原 `applyGroups(groups, removedIds)` 携带的 removedIds 不再上抛；watch 版幂等且同时覆盖 `listConfig` / `editConfig`，比原回调更不易漏 |
| 自动编码只读联动 | **改父级 `watch`** | 逻辑幂等；需回归验证 `syncFields` 批量改 `editConfig` 时的行为 |
| i18n reconcile | **保留在 index**（不下放） | 其依赖横跨 module/fields/groups；且保存前需同步执行一次，`v-show` 隐藏时防抖未完成会漏。保留纯函数 `applyManagedI18n()` 由 index 直接调用 |


## 实现要点（防回归）

### 1. 地基：`diffRows` 必须补剔除逻辑（否则字段面板的 `__form/__list/__query` 会进保存请求）

`diffRow`（主表）已有剔除 `_` / `v_` 前缀的逻辑，`diffRows`（子表）缺失，需对齐。改造后 `ModuleFieldsPanel` 不再逐行剥离虚拟字段，因此这一步是前置依赖。

### 2. `stk-table` 渲染约定（最容易踩的坑）

所有表格面板提交时必须换新数组引用，不能只就地改行对象：

```js
function commit() {
  rows.value = [...rows.value] // 新数组引用，行对象引用保持不变
}
```

### 3. `ModuleAutoCodePanel` 改为惰性建行（顺带修掉一个既有缺陷）

现状 `watch(immediate)` 在面板挂载时即 `createDraft()` 造一行，导致用户从未配置自动编码也会 diff 出一条无意义 insert。改为：仅当用户实际编辑时才建行，`rows.value[0]` 不存在时以 `computed` 返回 null 渲染空态。

### 4. 保存编排链路不可下放

`beforeSave`（跨面板 `validate` + 依赖校验 + i18n 键物化）→ `buildSaveData`（diff）→ `prepareSaveReqs`（`allocateTemporaryIds` + `remapForeignKeys` 跨表重映射）→ `afterSave`（重载回灌真实 ID）必须留在 index。临时负数 ID → 真实雪花 ID 的重映射依赖 `drafts` 与待提交请求共享同一批行对象引用，**改造后此特性必须保持**（`defineModel` 共享引用天然满足）。

### 5. 中间态说明

步骤 1a / 1b 改完组件契约后、步骤 2 完成 index 接线前，页面处于不可用中间态。因此 1a、1b 须连续执行，不可中途停手。

## 目录结构

```
fms-vue/src/
├── utils/
│   └── dataChanges.js                    # [MODIFY] diffRows 增加剔除 _ / v_ 前缀字段（与 diffRow 对齐）；
│                                         #          新增 stripInternalKeys 供 diffRows 与 index 的 hasUnsavedChanges 共用
└── views/module/module-management/
    ├── index.vue                         # [MODIFY 主体] 1600 行 → ~500 行。
    │                                     #   删除：4 个 proxy 回调（onModuleUpdate / onFieldsUpdate /
    │                                     #         onAutoCodeUpdate / onGroupsUpdate）、syncFields 三件套、树逻辑、moduleRowOf
    │                                     #   保留：originals / drafts、loadModuleConfig、保存编排四步、脏检查、快捷键、模板与样式
    │                                     #   新增：3 个跨面板 watch、useModuleTree 接入、全部面板 v-model 接线
    ├── useModuleTree.js                  # [NEW ~250 行] 模块树逻辑：loadModuleTree / addModule / deleteModule /
    │                                     #   onModuleDrop / buildModuleContextMenu / onModuleContextMenuClick /
    │                                     #   findNodePosition / renumberSiblings / hasSavedModuleDescendant /
    │                                     #   collectUnsavedModuleIds / markCategoryNonLeaf / moduleRowOf /
    │                                     #   unsavedModuleIds 集合。导出响应式状态与方法供 index 解构
    ├── ModuleBasicPanel.vue              # [MODIFY] :data + @update → defineModel 默认 model（模式 C）；
    │                                     #   setField / onCodeInput / onModuleTypeChange 直接改属性，不再 emit
    ├── ModuleFieldsPanel.vue             # [MODIFY 职责最重] defineModel × 6（fields / editConfig / listConfig /
    │                                     #   queryConfig / i18n / module）；模式 A 去掉 local 副本与虚拟字段剥离；
    │                                     #   承接从 index 迁入的 buildSyncPlan / applySyncPlan / syncFields，
    │                                     #   并在面板工具栏新增「同步字段」按钮
    ├── ModuleListConfigPanel.vue         # [MODIFY] 壳组件：defineModel × 2（listConfig / groups）；
    │                                     #   向下 TableDesignEditor 透传 v-model
    ├── ModuleEditPanel.vue               # [MODIFY] 壳组件：defineModel × 4（editConfig / listConfig / groups / editMode）；
    │                                     #   向 FormDesignEditor / TableDesignEditor 透传 v-model
    ├── ModuleQueryConfigPanel.vue        # [MODIFY] defineModel（模式 A）；去掉 localQuery 副本与 watch 同步
    ├── ModuleAutoCodePanel.vue           # [MODIFY] defineModel（模式 C）；改为惰性建行，未配置时不产生脏行
    ├── ModuleI18nPanel.vue               # [不改] 已使用 defineModel('rows')，作为本次改造的契约样板
    ├── utils.js                          # [不改] i18n 纯函数（reconcileI18nRows / buildI18nChangeRequest 等）
    ├── components/fieldDefaults.js       # [不改] 行默认值工厂
    └── components/design-editor/
        ├── TableDesignEditor.vue         # [MODIFY] rows / groups / editMode 改 defineModel（模式 B）；
        │                                 #   applyRows / applyGroups 从 emit 改为写 model
        ├── FormDesignEditor.vue          # [MODIFY 96KB 最大块] 同上；需用 LSP 定位全部 emit('update') /
        │                                 #   emit('updateGroups') / emit('updateListConfig') 调用点集中替换
        └── common/useStructureEditing.js # [不改] 依赖注入式内核，写入口由宿主提供，本次仅换调用侧
```

## 关键代码结构

### 1. `useStructureEditing` 宿主注入契约改造（模式 B 的核心，33KB 内核零改动）

```js
// TableDesignEditor.vue / FormDesignEditor.vue —— 改造后
const rows = defineModel('rows', { type: Array, default: () => [] })
const groups = defineModel('groups', { type: Array, default: () => [] })
const editMode = defineModel('editMode', { type: String, default: 'form' })

const editing = useStructureEditing({
  moduleId: () => props.moduleId,
  getRows: () => rows.value,          // 原：() => props.rows
  getGroups: () => groups.value,      // 原：() => props.groups
  createRow: props.createRow,
  applyRows: (next) => { rows.value = next },        // 原：(r) => emit('update', r)
  applyGroups: (next) => { groups.value = next },    // 原：(g, ids) => emit('updateGroups', g, ids)
  requestRename: (gid) => structureTreeRef.value?.startRename(gid),
  fieldNameOf: (row) => fieldName(row),
  getField: (fieldId) => fieldMap.value.get(fieldId),
})
```

### 2. index.vue 三个跨面板 watch 的签名（幂等，替代原 proxy 回调）

```js
// 分组删除 → 清理列表/编辑配置中的 b_group_id 引用
watch(() => drafts.value?.groups, (next, prev) => { /* 差集推断 removedIds，置 null */ })

// 自动编码字段 → 在表单中置只读；换字段时还原旧字段
watch(
  () => (Number(drafts.value?.autoCode?.[0]?.b_canuse) === 1
    ? String(drafts.value.autoCode[0].b_field_id ?? '') : ''),
  (nextId, prevId) => { /* 遍历 editConfig 幂等置位 */ },
)

// 受管 i18n 键补齐（保留在 index，防抖 300ms；保存前由 beforeSave 同步直调 applyManagedI18n 兜底）
watch(managedI18nItems, () => { /* 防抖后 reconcile */ })
```

## 执行约束

- 每次提交后页面须可运行：步骤 1a、1b 连续执行不可中断；步骤 2 / 3 / 4 各自完成后独立可验证。
- 不改动 `useStructureEditing.js`、`utils.js`、`fieldDefaults.js`、`tree.js` 及 `table/` `form/` 下的受控展示子组件。
- 复用既有 `Message` 提示风格与 `_` / `v_` 前缀字段约定，不新增全局约定。

## Agent Extensions

### SubAgent

- **code-explorer**
- 用途：在 `FormDesignEditor.vue`（96KB / 约 2500 行）中精确定位全部 `emit('update')` / `emit('updateGroups')` / `emit('updateListConfig')` / `emit('update:editMode')` 调用点及其所在函数，避免肉眼遗漏导致写入口漏改
- 预期产出：完整的调用点清单（行号 + 所属函数 + 上下文），据此集中替换为 model 写入

### Skill

- **lsp-code-analysis**
- 用途：改造前后对各面板的 props / emits 做符号级引用导航（find references / call hierarchy），确认无遗漏调用点，并复核 `useStructureEditing` 的 `applyRows` / `applyGroups` 注入点
- 预期产出：引用点完整性校验报告，确保契约变更后无悬挂引用