399 lines
12 KiB
Markdown
399 lines
12 KiB
Markdown
# 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`
|
||
- 前端页面只对用户开放 `version`、`author` 和 `indexSelection` 相关配置
|
||
- `saveToDisk`、`prettyJson`、`outputDir` 仍按接口契约参与请求，但采用页面内部默认值，不在右侧配置区开放编辑
|
||
- 第一次解析时可不传有效 `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`
|
||
|
||
使用表单形式维护，不再暴露底层 JSON 文本。
|
||
|
||
以下字段不在右侧开放配置，而是由页面内部写死默认值：
|
||
|
||
- `saveToDisk = false`
|
||
- `prettyJson = true`
|
||
- `outputDir = ''`
|
||
|
||
上述字段仍参与两类请求：
|
||
|
||
- 解析 ICD 请求
|
||
- 生成映射请求
|
||
|
||
区别在于解析请求强制使用空的 `indexSelection`。
|
||
|
||
### 6.2 默认模板表格骨架
|
||
|
||
右侧表格的骨架由 `DefaultCfg.txt` 提供。
|
||
页面在解析完成后，基于 `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` 时：
|
||
|
||
- 使用当前前端可配置字段
|
||
- 同时附带页面内部默认值：
|
||
- `saveToDisk = false`
|
||
- `prettyJson = true`
|
||
- `outputDir = ''`
|
||
- 强制令 `request.indexSelection = []`
|
||
- 调用 `getIcdMmsJson`
|
||
|
||
解析成功后：
|
||
|
||
- 保存本次 `indexCandidates`
|
||
- 基于 `DefaultCfg.txt` 自动生成新的默认模板草稿
|
||
- 右侧展示辅助信息与模板配置表格
|
||
|
||
### 8.3 生成映射
|
||
|
||
点击 `生成映射` 时：
|
||
|
||
- 取右侧当前最新草稿
|
||
- 做本地校验
|
||
- 组装最终 `request.indexSelection`
|
||
- 同时附带页面内部默认值：
|
||
- `saveToDisk = false`
|
||
- `prettyJson = true`
|
||
- `outputDir = ''`
|
||
- 再次调用 `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`
|
||
|
||
职责：
|
||
|
||
- 精简请求字段表单
|
||
- 基于 `DefaultCfg.txt` 自动生成的默认模板配置表格
|
||
- 辅助信息展示
|
||
- `生成映射`
|
||
|
||
### 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`，但用户操作对象变为“基于候选生成的可编辑草稿”，从而兼顾接口约束、调试效率和页面可用性。
|