ClientApps/CN_Tool_client

Fork 0

Files

yexb 9a388627a0 docs: refine mmsmapping config defaults

2026-04-22 01:48:45 +08:00

12 KiB

Raw Permalink Blame History

MMS Mapping 页面重构设计

1. 背景

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

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

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

先选择 ICD 文件并解析，获取候选辅助信息
基于候选辅助信息和 DefaultCfg.txt 生成一份可编辑配置
用户可反复修改该配置，并多次生成新的 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 右侧：系统配置区

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

精简请求字段表单
基于 DefaultCfg.txt 自动生成的默认模板配置表格
解析返回的辅助信息展示及 生成映射 操作区

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，而是在解析完成后生成一份“配置草稿”。

草稿由三部分合并得到：

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

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

7. 模板与候选匹配规则

7.1 匹配原则

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

7.2 自动匹配建议

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

优先按 groupDesc 匹配
若不唯一，则结合以下信息辅助判断：
- 模板 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 人工流程验证

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

12.3 风险专项验证

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

13. 风险与注意事项

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

14. 结论

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

先解析
再配置
可多次生成

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

12 KiB Raw Permalink Blame History Unescape Escape