15 KiB
15 KiB
Excel 导入模板功能设计文档：单条模板 / 批量模板
1. 设计目标
当前项目已经具备“模板管理”能力，但需要进一步明确模板类型，避免把单条变量模板和从 Excel 导入的一整套变量混在一起。
新的设计目标是把模板管理拆成两类：
单条模板管理：每次新增变量时，复制/套用一条变量模板。
批量模板管理：导入 Excel，读取 MES_基本变量原始数据，保存为一整套批量模板。
其中：
单条模板保留现在的使用方式，用于新增或编辑单条变量时快速填充字段。批量模板用于把外部 Excel 中的MES_基本变量原始数据整批复制到当前设备模块。- 批量模板只读取导入 Excel 的
MES_基本变量原始数据Sheet。 - 批量模板不读取、不解析、不使用
设备类型对应表。 - 批量模板不会根据外部 Excel 修改当前网页中的设备模块、工位、设备 IP、DB。
2. 模板管理分类
模板管理分为两个 Tab 或两个区域：
单条模板管理 | 批量模板管理
| 类型 | 数据来源 | 使用方式 | 结果 |
|---|---|---|---|
| 单条模板管理 | 用户手动维护的一条变量字段模板 | 新增变量时选择并套用 | 新增 1 条变量 |
| 批量模板管理 | 外部 Excel 的 MES_基本变量原始数据 |
选择批量模板并使用 | 一次新增多条变量 |
第一版不做设备模板、不做工位模板、不从 Excel 反向生成设备配置。
3. 单条模板管理
单条模板管理保留当前功能。
3.1 功能定位
单条模板用于减少单条变量录入时的重复填写。
例如用户新增变量时，可以选择：
Bool 信号模板Int 数值模板Real 浮点模板String 字符串模板
然后自动填充：
TagTypeIDTagLong变量类型是否启用是否监控- 其它常用字段
3.2 单条模板使用规则
新增变量时：
- 用户点击
新增变量。 - 系统打开变量编辑弹窗。
- 用户选择一个单条模板。
- 点击
使用模板。 - 模板字段填入当前变量表单。
- 用户继续补充
TagID / TagName / 变量地址 / 测量项目等字段。 - 保存后只新增一条共享变量。
3.3 单条模板保存内容
单条模板保存的是一条变量的部分字段，不需要保存完整 38 字段。
建议结构：
{
"id": "tpl-bool-signal",
"templateName": "Bool 信号模板",
"description": "常用 Bool 开关量信号",
"fields": {
"TagTypeID": "11",
"TagLong": "1",
"变量类型": "Bool",
"是否启用": "1",
"是否监控": "1"
}
}
4. 批量模板管理
批量模板管理是本次新增的重点。
4.1 功能定位
批量模板用于把外部 Excel 中的一整套基本变量原始数据保存成可复用模板。
用户后续可以选择这个批量模板，并一次性追加到当前设备模块的共享变量数据中。
效果类似之前版本：
直接复制 Excel 中的 MES_基本变量原始数据
4.2 批量模板来源
批量模板只来自外部 Excel 的：
MES_基本变量原始数据
即使导入 Excel 中存在：
设备类型对应表
系统也不读取、不解析、不使用。
4.3 批量模板使用结果
用户使用批量模板后：
- 批量模板中的所有变量追加到当前选中的设备模块。
- 当前设备模块右侧
MES_基本变量原始数据展开预览立即刷新。 - 如果当前设备模块有多个配置行，右侧按多个工位展开显示。
- 导出 Excel 时，新追加的变量会出现在
MES_基本变量原始数据中。
5. Excel 导入规则
5.1 Sheet 读取规则
导入 Excel 时只查找并读取：
MES_基本变量原始数据
如果没有该 Sheet，提示：
未找到 MES_基本变量原始数据 Sheet，无法导入批量模板。
不会读取：
设备类型对应表
也不会读取其它 Sheet。
5.2 表头规则
第一行作为表头。
字段以当前系统中的 MES_HEADERS 为准。
处理规则：
| 情况 | 处理方式 |
|---|---|
| Excel 存在系统支持字段 | 读取该字段 |
| Excel 存在未知字段 | 忽略 |
| Excel 缺少系统字段 | 补为空 |
| Excel 空行 | 忽略 |
至少应存在：
TagIDTagName
建议必须填写：
TagTypeIDTagLong
5.3 字段保留规则
批量模板保存导入 Excel 中识别出的多条基本变量原始数据。
保存时字段仍按 38 列标准字段管理：
TagID
TagName
工位号
数据来源
IP
TagTypeID
TagLong
DbName
...
IsWebSocket
但导出和右侧预览时，以下字段仍以当前网页设备模块配置为准：
工位号数据来源IPDbName
也就是说，外部 Excel 中这些字段可以被导入保存，但不会覆盖当前网页的设备模块配置。
5.4 TagID 规则
外部 Excel 中可能存在两种格式：
TAG_0000001
ST04_TAG_0000001
批量模板保存时建议统一保存为基础格式：
TAG_0000001
规则：
如果 TagID 中包含 TAG_，则从 TAG_ 开始截取。
示例：
| 导入值 | 模板保存值 |
|---|---|
TAG_0000001 |
TAG_0000001 |
ST04_TAG_0000001 |
TAG_0000001 |
ST11_TAG_0000023 |
TAG_0000023 |
使用批量模板追加到设备模块后，页面预览和 Excel 导出再按当前工位展开：
ST04_TAG_0000001
ST05_TAG_0000001
6. 批量模板使用规则
6.1 使用入口
在模板管理中进入：
批量模板管理
选择一个批量模板后点击：
使用批量模板
6.2 使用前提
必须先选择左侧设备模块。
如果未选择设备模块，提示：
请先选择设备模块，再使用批量模板。
6.3 追加方式
使用批量模板时，不覆盖当前设备模块已有变量，而是追加。
示例：
当前设备模块已有变量：3 条
批量模板变量：23 条
使用后当前设备模块变量：26 条
6.4 TagID 冲突处理
如果批量模板中的 TagID 与当前设备模块已有变量重复，推荐第一版自动重排。
示例：
当前已有：
TAG_0000001
TAG_0000002
批量模板中有：
TAG_0000001
TAG_0000002
TAG_0000003
追加后生成：
TAG_0000003
TAG_0000004
TAG_0000005
这样可以避免同一设备模块中基础 TagID 重复。
6.5 展开预览
批量模板追加后，右侧表格按当前设备模块配置行展开。
例如：
当前设备模块配置行：ST04、ST05
批量模板变量：23 条
右侧展开显示：46 行
7. 数据结构建议
7.1 总配置结构
建议 OPFS/localStorage 中保存：
{
"version": 3,
"updatedAt": "2026-06-02T10:00:00.000Z",
"devices": [],
"variableTemplates": [],
"batchVariableTemplates": []
}
7.2 单条模板结构
{
"id": "tpl-bool-signal",
"templateName": "Bool 信号模板",
"description": "常用 Bool 开关量信号",
"fields": {
"TagTypeID": "11",
"TagLong": "1",
"变量类型": "Bool"
}
}
7.3 批量模板结构
{
"id": "batch-tpl-001",
"templateName": "放油标准批量模板",
"description": "从外部 Excel 导入",
"sourceFileName": "SignalTable_CZ.xlsx",
"createdAt": "2026-06-02T10:00:00.000Z",
"variables": [
{
"TagID": "TAG_0000001",
"TagName": "PLC_PC_工件到位",
"TagTypeID": "11",
"TagLong": "1",
"变量类型": "Bool",
"变量地址": "0",
"变量其它": ".0"
}
]
}
8. 页面交互设计
8.1 模板管理弹窗
模板管理弹窗分为两个 Tab：
单条模板管理 | 批量模板管理
8.2 单条模板管理
保留当前能力：
- 新增单条模板
- 编辑单条模板
- 删除单条模板
- 在新增变量弹窗中使用单条模板
- 从当前变量保存为单条模板
8.3 批量模板管理
新增能力：
导入 Excel预览批量模板使用批量模板删除批量模板
批量模板列表展示：
- 模板名称
- 来源文件
- 变量数量
- 创建时间
8.4 导入 Excel 确认弹窗
导入 Excel 后先展示确认信息：
来源文件：SignalTable_CZ.xlsx
读取 Sheet：MES_基本变量原始数据
有效变量数：23
忽略空行：0
忽略未知列：2
模板名称：[放油标准批量模板]
模板说明：[从外部 Excel 导入]
[取消] [保存为批量模板]
9. 测试方案
9.1 单条模板测试
- 打开新增变量弹窗。
- 选择一个单条模板。
- 点击
使用模板。 - 确认只填充当前变量表单。
- 保存后只新增一条变量。
9.2 批量模板导入测试
- 打开模板管理。
- 进入
批量模板管理。 - 点击
导入 Excel。 - 选择包含
MES_基本变量原始数据的 Excel。 - 确认系统只读取该 Sheet。
- 保存后生成一个批量模板。
9.3 非目标 Sheet 测试
- 导入包含
设备类型对应表的 Excel。 - 确认系统不读取、不解析、不使用该 Sheet。
- 当前设备模块配置不发生变化。
9.4 批量模板使用测试
- 选择左侧一个设备模块。
- 在批量模板管理中选择一个模板。
- 点击
使用批量模板。 - 当前设备模块一次性新增多条变量。
- 右侧
MES_基本变量原始数据展开预览立即刷新。
9.5 Excel 导出测试
- 使用批量模板批量新增变量。
- 点击
生成 Excel。 - 导出的
MES_基本变量原始数据包含新增变量。 - 导出的
工位号 / 数据来源 / IP / DbName使用当前网页设备模块配置。 - 导出的 Excel 仍只包含两个 Sheet。
9.6 异常测试
需要验证：
- Excel 没有
MES_基本变量原始数据时提示错误。 - Excel 表头缺少
TagID或TagName时提示错误。 - Excel 空行被忽略。
- Excel 未知列被忽略。
- 批量模板保存后刷新页面仍存在。
10. 页面草图
10.1 模板管理
┌──────────────────────────────────────────────────────────────────────────────┐
│ 模板管理 │
├──────────────────────────────────────────────────────────────────────────────┤
│ [单条模板管理] [批量模板管理] │
├──────────────────────────────┬───────────────────────────────────────────────┤
│ 批量模板列表 │ 批量模板预览 │
│ [导入 Excel] │ 模板名称：放油标准批量模板 │
│ ┌──────────────────────────┐ │ 来源文件：SignalTable_CZ.xlsx │
│ │ 放油标准批量模板 23 条 │ │ 变量数量：23 │
│ │ 称重批量模板 12 条 │ │ │
│ └──────────────────────────┘ │ ┌───────────────────────────────────────────┐ │
│ │ │ TagID TagName TagTypeID │ │
│ │ │ TAG_0000001 PLC_PC_工件到位 11 │ │
│ │ │ TAG_0000002 PLC_PC_读取完成 11 │ │
│ │ └───────────────────────────────────────────┘ │
├──────────────────────────────┴───────────────────────────────────────────────┤
│ [删除模板] [使用批量模板] [关闭] │
└──────────────────────────────────────────────────────────────────────────────┘
10.2 导入确认
┌──────────────────────────────────────────────────────┐
│ 导入 Excel 为批量模板 │
├──────────────────────────────────────────────────────┤
│ 来源文件：SignalTable_CZ.xlsx │
│ 读取 Sheet：MES_基本变量原始数据 │
│ 有效变量数：23 │
│ 忽略空行：0 │
│ 忽略未知列：2 │
│ │
│ 模板名称：[放油标准批量模板 ] │
│ 模板说明：[从外部 Excel 导入 ] │
├──────────────────────────────────────────────────────┤
│ [取消] [保存为批量模板] │
└──────────────────────────────────────────────────────┘
11. 后续迭代方向
后续可以继续增强：
- 支持导入 Excel 后直接追加到当前设备模块，不先保存为批量模板。
- 支持批量模板内变量字段编辑。
- 支持批量模板导出为 JSON。
- 支持从当前设备模块变量保存为批量模板。
- 支持批量模板使用时选择 TagID 策略：自动重排、保留原值、覆盖重复。
- 支持导入前筛选变量，例如按
变量类型、TagName、是否启用筛选。