meswork/Excelbuilder
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: update Excel template management and export handling

Browse Source
This commit is contained in:
meswork
2026-06-03 08:46:56 +08:00
parent 9cfb8d16f0
commit 57f804818e
8 changed files with 1092 additions and 124 deletions
Download Patch File Download Diff File Expand all files Collapse all files

541
docs/excel-import-template-feature-design.md Normal file
View File

@@ -0,0 +1,541 @@
# 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`、`是否启用` 筛选。