CN_Tool_client/docs/superpowers/specs/2026-04-22-mmsmapping-layout-and-config-design.md

# MMS Mapping 页面重构设计

## 1. 背景

当前 `frontend/src/views/tools/mmsmapping/` 页面已具备基础联调能力，但页面结构与本次使用方式不一致：

- 左侧仍保留大段 `request JSON` 编辑区
- 结果展示位于右侧，不符合“左下统一看输出”的操作习惯
- `request.indexSelection` 仍依赖手工编辑 JSON，不利于基于 `DefaultCfg.txt` 做可重复调试
- 页面尚未把解析返回的辅助信息与最终映射配置联动起来

本次重构目标是让页面围绕 `getIcdMmsJson` 的两步联调流程工作：

1. 先选择 ICD 文件并解析，获取候选辅助信息
2. 基于候选辅助信息和 `DefaultCfg.txt` 生成一份可编辑配置
3. 用户可反复修改该配置，并多次生成新的 `mappingJson`

## 2. 目标

### 2.1 页面目标

- 左上只保留 ICD 文件选择和 `解析 ICD` 按钮
- 左下统一展示接口返回中的 `mappingJson` 和 `problems`
- 右侧作为系统配置区，承载基础请求字段、模板配置表格和辅助信息
- 页面不再要求用户直接编辑 `request JSON`

### 2.2 业务目标

- `解析 ICD` 与 `生成映射` 分离为两个动作
- `解析 ICD` 后生成一份“基于候选结果的可编辑配置草稿”
- 用户在不重新解析的前提下，可以多次修改草稿并重复生成 `mappingJson`
- 当后端返回 `NEED_INDEX_SELECTION` 时，页面保留当前配置，便于继续调整

## 3. 非目标

- 不改后端接口契约
- 不扩展 `mappingJson` 之外的新结果展示结构
- 不直接编辑后端原始 `indexCandidates`
- 不把 `icdDocument` 树保留在主界面中单独展示

## 4. 已知接口约束

基于 `API-getIcdMmsJson.md`，本次页面需要遵守以下接口规则：

- 接口路径为 `/api/mms-mapping/get-icd-mms-json`
- 请求仍为 `multipart/form-data`
- 请求由 `icdFile` 文件 Part 和 `request` JSON Part 组成
- `request` 的基础字段为：
  - `version`
  - `author`
  - `saveToDisk`
  - `prettyJson`
  - `outputDir`
  - `indexSelection`
- 第一次解析时可不传有效 `indexSelection`，接口会返回 `NEED_INDEX_SELECTION`
- 第二次生成时，`indexSelection` 必须沿用解析返回的合法候选值
- `mappingJson` 为字符串字段，需要前端格式化展示
- `problems` 用于承载配置问题、校验问题或运行异常信息

## 5. 页面布局设计

页面采用双列布局，左侧再拆成上下两块。

### 5.1 左上：文件入口区

仅保留以下元素：

- 已选择 ICD 文件名
- `选择 ICD`
- `解析 ICD`
- 当前解析状态标签

该区域不再展示可编辑 JSON 文本，也不承载系统配置字段。

### 5.2 左下：统一结果区

仅展示：

- `mappingJson`
- `problems`

展示规则：

- 返回存在 `mappingJson` 时，默认激活 `mappingJson` 页签
- 仅存在 `problems` 时，默认激活 `problems` 页签
- 每次发起解析或生成请求后，左下刷新为最近一次接口返回结果
- 左下不单独展示 `icdDocument` 树和候选结构

### 5.3 右侧：系统配置区

右侧固定为配置与生成工作区，包含三部分：

1. 基础请求字段表单
2. 基于 `DefaultCfg.txt` 生成的模板配置表格
3. 解析返回的辅助信息展示及 `生成映射` 操作区

## 6. 右侧配置区设计

### 6.1 基础请求字段

基础字段全部保留并可配置：

- `version`
- `author`
- `saveToDisk`
- `prettyJson`
- `outputDir`

使用表单形式维护，不再暴露底层 JSON 文本。

这些字段参与两类请求：

- 解析 ICD 请求
- 生成映射请求

区别在于解析请求强制使用空的 `indexSelection`。

### 6.2 模板表格骨架

右侧表格的骨架由 `DefaultCfg.txt` 提供。

优先使用 `ReportList` 生成分组，每个分组至少展示：

- `desc`
- `Select`
- `DataSetList`
- `LnInstList`

每个模板分组下，以 `LnInstList` 为行生成可编辑配置行，用于最终组装：

- `bindings[].label`
- `bindings[].reportName`
- `bindings[].dataSetName`
- `bindings[].lnInst`

### 6.3 解析返回的辅助信息

右侧必须展示解析接口返回的辅助信息，至少包括：

- `groupKey`
- `groupDesc`
- `templateLabels`
- `reports[].reportName`
- `reports[].dataSetName`
- `reports[].availableLnInstValues`

这些内容的目的不是直接提交，而是作为模板匹配和用户确认的依据。

### 6.4 可编辑草稿

页面不直接编辑后端原始 `indexCandidates`，而是在解析完成后生成一份“配置草稿”。

草稿由三部分合并得到：

1. `DefaultCfg.txt` 模板骨架
2. 本次解析返回的 `indexCandidates`
3. 页面上当前用户编辑态

用户后续反复编辑的是草稿，提交时再把草稿转换为最终 `request.indexSelection`。

## 7. 模板与候选匹配规则

### 7.1 匹配原则

`DefaultCfg.txt` 负责定义“页面配置骨架”，但不能单独作为最终提交源。
真正提交给后端的分组和值，仍必须基于本次解析返回的合法候选结果。

### 7.2 自动匹配建议

解析完成后，页面尝试将模板分组与候选分组自动匹配：

1. 优先按 `groupDesc` 匹配
2. 若不唯一，则结合以下信息辅助判断：
   - 模板 `LnInstList` 与候选 `templateLabels` 的交集
   - 模板 `DataSetList` 与候选 `reports[].dataSetName` 的交集

### 7.3 待确认规则

若自动匹配结果不唯一或无法判断，则不强行绑定，直接标记为“待确认”。
此时用户需手动选择当前模板分组对应的候选组。

### 7.4 行级编辑规则

每个模板行至少允许用户设置：

- `reportName`
- `dataSetName`
- `lnInst`

候选值优先来自当前已绑定候选组中的合法项，避免用户录入非法值。

## 8. 交互流程设计

### 8.1 选择文件

用户选择 ICD 文件后，页面更新当前文件状态。

若文件发生变化，页面清空：

- 解析缓存
- 配置草稿
- 左下结果

### 8.2 解析 ICD

点击 `解析 ICD` 时：

- 使用当前基础请求字段
- 强制令 `request.indexSelection = []`
- 调用 `getIcdMmsJson`

解析成功后：

- 保存本次 `indexCandidates`
- 生成新的配置草稿
- 右侧展示辅助信息与模板配置表格

### 8.3 生成映射

点击 `生成映射` 时：

- 取右侧当前最新草稿
- 做本地校验
- 组装最终 `request.indexSelection`
- 再次调用 `getIcdMmsJson`

### 8.4 多次生成

在不重新选择文件且不重新点击 `解析 ICD` 的前提下：

- 用户可以反复修改右侧草稿
- 每次点击 `生成映射` 都重新组装新的 `indexSelection`
- 左下结果始终更新为最近一次返回的 `mappingJson` / `problems`

### 8.5 重新解析

仅在以下情况需要重新解析：

- 更换 ICD 文件
- 用户主动点击 `解析 ICD`

重新解析后，旧候选和旧草稿均失效，以新解析结果为准。

## 9. 状态与错误处理

### 9.1 业务状态

- `SUCCESS`：左下优先展示 `mappingJson`
- `NEED_INDEX_SELECTION`：视为继续修正配置，不视为页面异常
- `FAILED`：左下展示 `problems`，并同步提示错误消息

### 9.2 页面保留策略

当生成请求返回 `NEED_INDEX_SELECTION` 或 `FAILED` 时：

- 左下结果区刷新为新结果
- 右侧当前草稿不清空
- 用户可以继续修改后再次生成

### 9.3 模板解析异常

`DefaultCfg.txt` 含尾逗号等非严格 JSON 片段，前端模板读取需要容错处理。

若模板解析失败：

- 右侧配置区展示明确错误
- 禁用 `生成映射`
- 不影响重新解析动作

### 9.4 本地校验

生成前至少校验：

- 分组已绑定到候选组
- 每个待提交行已填写 `reportName`
- 每个待提交行已填写 `dataSetName`
- 每个待提交行已填写 `lnInst`

## 10. 组件与模块拆分

### 10.1 页面入口

`frontend/src/views/tools/mmsmapping/index.vue`

职责：

- 编排左右布局
- 管理请求与响应状态
- 管理解析缓存、草稿状态和结果区状态

### 10.2 左上文件区组件

保留并收缩当前请求组件职责，建议继续使用：

- `frontend/src/views/tools/mmsmapping/components/MappingRequestPanel.vue`

调整后仅负责：

- 文件选择
- `解析 ICD`
- 解析状态展示

### 10.3 左下结果区组件

继续使用：

- `frontend/src/views/tools/mmsmapping/components/MappingResultPanel.vue`

职责聚焦为：

- `mappingJson` 展示
- `problems` 展示

### 10.4 右侧配置组件

新增：

- `frontend/src/views/tools/mmsmapping/components/MappingConfigPanel.vue`

职责：

- 基础请求字段表单
- 模板配置表格
- 辅助信息展示
- `生成映射`

### 10.5 配置转换工具

建议新增一个页面级工具文件，负责：

- 容错解析 `DefaultCfg.txt`
- 生成草稿结构
- 模板与候选匹配
- 草稿转 `request.indexSelection`

## 11. 预计修改点

预计改动集中在以下范围：

- `frontend/src/views/tools/mmsmapping/index.vue`
- `frontend/src/views/tools/mmsmapping/components/MappingRequestPanel.vue`
- `frontend/src/views/tools/mmsmapping/components/MappingResultPanel.vue`
- 新增 `frontend/src/views/tools/mmsmapping/components/MappingConfigPanel.vue`
- 新增页面级模板解析与转换工具文件
- 必要时补充 `frontend/src/api/tools/mmsmapping/interface/index.ts` 中的前端草稿类型

## 12. 验证方案

### 12.1 静态验证

- `cd frontend && npm run lint`
- `cd frontend && npm run type-check`

### 12.2 人工流程验证

1. 选择 ICD 文件后，左上只显示文件入口和 `解析 ICD`
2. 点击 `解析 ICD` 后，右侧出现基础字段、模板表格和辅助信息
3. 在不重新解析的情况下，多次修改右侧草稿并点击 `生成映射`
4. 左下每次都刷新为最近一次 `mappingJson` / `problems`
5. 当返回 `NEED_INDEX_SELECTION` 时，右侧草稿仍保留
6. 更换 ICD 文件后，旧候选、旧草稿和旧结果全部清空

### 12.3 风险专项验证

- `DefaultCfg.txt` 容错解析是否稳定
- 自动匹配不唯一时是否正确进入“待确认”
- 多次生成时是否始终按最新草稿提交
- 左下结果区是否始终只绑定 `mappingJson` 和 `problems`

## 13. 风险与注意事项

- `DefaultCfg.txt` 与接口候选结构不是一一直接映射，匹配策略必须保守，不能静默误绑
- 候选辅助信息较多，右侧滚动区域需要合理拆分，避免整页滚动体验过重
- 若前端继续把复杂转换逻辑堆在 `index.vue` 中，后续维护成本会迅速上升，必须提前拆出配置组件和工具文件

## 14. 结论

本设计采用“左侧入口与结果、右侧配置与生成”的结构，将原本的手工 JSON 联调页重构为面向两步流程的配置页面：

- 先解析
- 再配置
- 可多次生成

页面最终提交的仍是标准 `request.indexSelection`，但用户操作对象变为“基于候选生成的可编辑草稿”，从而兼顾接口约束、调试效率和页面可用性。