From 45ab5c9e841cfbbc18c1777d63180cf82e67b944 Mon Sep 17 00:00:00 2001
From: yexb <553699424@qq.com>
Date: Wed, 22 Apr 2026 01:41:30 +0800
Subject: [PATCH] docs: add mmsmapping redesign spec

---
 ...-22-mmsmapping-layout-and-config-design.md | 384 ++++++++++++++++++
 1 file changed, 384 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-04-22-mmsmapping-layout-and-config-design.md

diff --git a/docs/superpowers/specs/2026-04-22-mmsmapping-layout-and-config-design.md b/docs/superpowers/specs/2026-04-22-mmsmapping-layout-and-config-design.md
new file mode 100644
index 0000000..db0a885
--- /dev/null
+++ b/docs/superpowers/specs/2026-04-22-mmsmapping-layout-and-config-design.md
@@ -0,0 +1,384 @@
+# 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`，但用户操作对象变为“基于候选生成的可编辑草稿”，从而兼顾接口约束、调试效率和页面可用性。