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