546 lines
19 KiB
Markdown
546 lines
19 KiB
Markdown
# SignalTable_CZ Excel 生成器设计文档 v6
|
||
|
||
## 1. 项目目标
|
||
|
||
本项目基于 `C:\work\Project\Excel` 的 Vue 前端项目，建设一个用于维护并生成标准 `SignalTable_CZ.xlsx` 的网页工具。
|
||
|
||
最终目标是：当项目需要生成 SCADA 可读取的信号表 Excel 时，用户打开网页，维护设备模块、工位和变量配置，然后点击 `生成 Excel`，得到标准 Excel 文件。
|
||
|
||
当前 v6 设计重点是把原来的：
|
||
|
||
```text
|
||
一个设备 = 一个工位
|
||
```
|
||
|
||
调整为：
|
||
|
||
```text
|
||
一个设备模块 = 多个工位
|
||
同一个设备模块内多个工位共用同一套 MES_基本变量原始数据
|
||
```
|
||
|
||
本次只更新 `.md` 设计文档，不进行 Vue 代码修改。
|
||
|
||
## 2. Excel 输出范围
|
||
|
||
最终生成的 Excel 只包含两个 Sheet：
|
||
|
||
1. `MES_基本变量原始数据`
|
||
2. `设备类型对应表`
|
||
|
||
不生成以下 Sheet：
|
||
|
||
- `工厂接口配置`
|
||
- `变量类型代码说明`
|
||
- `配置_信号`
|
||
|
||
Sheet 名称必须完全一致，不能改名、不能多空格、不能使用英文替代。
|
||
|
||
## 3. 设计变更说明
|
||
|
||
### 3.1 旧设计废弃点
|
||
|
||
v6 开始废弃以下旧设计：
|
||
|
||
- 不再认为左侧设备列表中的一行就是一个工位。
|
||
- 不再让 `devices[]` 直接对应 `设备类型对应表` 的每一行。
|
||
- 不再让一个设备模块只能生成一行 `设备类型对应表`。
|
||
- 不再让一个设备模块只能维护一个工位。
|
||
|
||
### 3.2 新设计核心
|
||
|
||
v6 中左侧设备列表展示的是设备模块。
|
||
|
||
一个设备模块内部可以维护多个工位，工位只维护自身工位参数：
|
||
|
||
- 工位名称
|
||
- 数据来源
|
||
- DB
|
||
- 是否启用
|
||
|
||
同一个设备模块只维护一份共享 `MES_基本变量原始数据`。设备模块下所有工位导出时都使用这同一套变量，再按各自工位参数展开。
|
||
|
||
导出 Excel 时，当前选中的设备模块会导出其内部所有工位。
|
||
|
||
## 4. 设备模块与工位关系
|
||
|
||
### 4.1 设备模块
|
||
|
||
设备模块用于描述一组共用设备信息的工位集合。
|
||
|
||
设备模块字段：
|
||
|
||
| 字段 | 说明 | 是否必填 |
|
||
| --- | --- | --- |
|
||
| 设备名称 | 设备模块显示名称，例如“放油设备” | 是 |
|
||
| 设备型号 | PLC 或设备型号，例如 `S1500` | 是 |
|
||
| 设备IP | PLC 或设备通信 IP | 是 |
|
||
| 是否启用 | 控制该设备模块是否启用 | 是 |
|
||
|
||
设备模块示例：
|
||
|
||
```json
|
||
{
|
||
"id": "dev-001",
|
||
"deviceName": "放油设备",
|
||
"deviceModel": "S1500",
|
||
"deviceIp": "192.168.1.60",
|
||
"enabled": 1,
|
||
"stations": [],
|
||
"variables": []
|
||
}
|
||
```
|
||
|
||
### 4.2 工位
|
||
|
||
工位属于设备模块，一个设备模块可以包含多个工位。
|
||
|
||
工位字段：
|
||
|
||
| 字段 | 说明 | 是否必填 |
|
||
| --- | --- | --- |
|
||
| 工位名称 | SCADA 工位号，例如 `ST04` | 是 |
|
||
| 数据来源 | 默认等于设备名称，写入 `设备类型对应表.数据来源` | 是 |
|
||
| DB | 写入 `设备类型对应表.DB` 和变量 `DbName` | 是 |
|
||
| 是否启用 | 写入 `设备类型对应表.是否启用` | 是 |
|
||
| 基本变量原始数据 | 不保存在工位中，由设备模块统一维护 | 否 |
|
||
|
||
工位示例：
|
||
|
||
```json
|
||
{
|
||
"id": "station-001",
|
||
"deviceName": "放油前",
|
||
"stationName": "ST04",
|
||
"dataSource": "放油前",
|
||
"deviceModel": "S1500",
|
||
"deviceIp": "192.168.1.60",
|
||
"db": "DB10000",
|
||
"enabled": 1,
|
||
"variables": []
|
||
}
|
||
```
|
||
|
||
## 5. 多工位数据结构
|
||
|
||
推荐数据结构：
|
||
|
||
```json
|
||
{
|
||
"devices": [
|
||
{
|
||
"id": "dev-001",
|
||
"deviceName": "放油设备",
|
||
"deviceModel": "S1500",
|
||
"deviceIp": "192.168.1.60",
|
||
"enabled": 1,
|
||
"stations": [
|
||
{
|
||
"id": "station-001",
|
||
"deviceName": "放油前",
|
||
"stationName": "ST04",
|
||
"dataSource": "放油前",
|
||
"deviceModel": "S1500",
|
||
"deviceIp": "192.168.1.60",
|
||
"db": "DB10000",
|
||
"enabled": 1
|
||
},
|
||
{
|
||
"id": "station-002",
|
||
"deviceName": "放油后",
|
||
"stationName": "ST05",
|
||
"dataSource": "放油后",
|
||
"deviceModel": "S1500",
|
||
"deviceIp": "192.168.1.60",
|
||
"db": "DB10001",
|
||
"enabled": 1
|
||
}
|
||
],
|
||
"variables": []
|
||
}
|
||
],
|
||
"variables": []
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
- `devices[]` 保存设备模块。
|
||
- `devices[].stations[]` 保存该设备模块下的工位。
|
||
- `devices[].variables[]` 保存该设备模块共享的 38 字段变量。
|
||
- 顶层 `variables[]` 仅作为全局默认变量模板来源。
|
||
- 新增设备模块时，从全局默认变量模板复制一份到该设备模块。
|
||
- 新增工位时不复制变量，只新增工位参数。
|
||
- 同一设备模块下所有工位共用 `devices[].variables[]`。
|
||
|
||
## 6. 页面整体设计
|
||
|
||
页面继续采用左右分栏结构。
|
||
|
||
左侧：
|
||
|
||
- 设备模块列表
|
||
- 设备模块新增
|
||
- 设备模块编辑
|
||
- 设备模块删除
|
||
- 查询设备模块
|
||
- 展开/收起设备列表
|
||
|
||
右侧：
|
||
|
||
- 当前设备模块的工位切换区
|
||
- 当前设备模块共享的 `MES_基本变量原始数据`
|
||
|
||
页面行为：
|
||
|
||
- 点击左侧设备模块，右侧显示该设备模块下的工位。
|
||
- 点击右侧某个工位，变量表用该工位参数预览同一套共享变量。
|
||
- 右侧只做工位切换和变量预览，不提供工位新增、编辑、删除。
|
||
- 修改变量表中的任意变量，会影响当前设备模块下所有工位的导出结果。
|
||
- ST04、ST05 在页面上看到的是同一套变量，只是 `工位号 / 数据来源 / IP / DbName / TagID` 按当前选中工位预览。
|
||
- 未选择设备模块时，右侧显示空状态。
|
||
- 选择设备模块但没有工位时，右侧提示先新增工位。
|
||
|
||
## 7. 设备模块整表编辑
|
||
|
||
设备模块新增/编辑弹窗采用整表编辑模式，不再单独摆放 `设备名称 / 设备型号 / 设备IP / 是否启用` 表单。
|
||
|
||
弹窗主体是一张配置表，每一行都是一条完整配置，并会在导出 Excel 时生成 `设备类型对应表` 的一行。
|
||
|
||
表格字段：
|
||
|
||
```text
|
||
设备名称
|
||
工位名称
|
||
设备型号
|
||
设备IP
|
||
DB
|
||
是否启用
|
||
操作
|
||
```
|
||
|
||
### 7.1 新增配置行
|
||
|
||
点击弹窗左上角 `+` 后，立即新增一条完整配置行。
|
||
|
||
默认生成规则：
|
||
|
||
- `设备名称` 默认取当前第一行设备名称，若没有则为空。
|
||
- `工位名称` 自动递增，例如 `ST06`。
|
||
- `设备型号` 默认取当前第一行设备型号，若没有则为 `S1500`。
|
||
- `设备IP` 默认取当前第一行设备IP。
|
||
- `DB` 自动递增，例如 `DB10002`。
|
||
- `是否启用` 默认为 `1`。
|
||
|
||
校验规则：
|
||
|
||
- `设备名称` 不能为空。
|
||
- `工位名称` 不能为空。
|
||
- `设备型号` 不能为空。
|
||
- `设备IP` 不能为空。
|
||
- `DB` 不能为空。
|
||
|
||
### 7.2 编辑配置行
|
||
|
||
所有字段都在表格单元格中直接编辑。
|
||
|
||
保存后：
|
||
|
||
- 设备模块左侧列表使用第一行配置作为显示信息。
|
||
- 导出 Excel 时以每行最新配置为准。
|
||
- 导出 Excel 时以最新网页设置为准。
|
||
|
||
### 7.3 删除配置行
|
||
|
||
删除配置行时：
|
||
|
||
- 删除该行配置。
|
||
- 不删除设备模块共享变量。
|
||
- 导出 Excel 不再包含该行。
|
||
|
||
## 8. 右侧基本变量详情设计
|
||
|
||
右侧变量表展示当前设备模块共享的 `MES_基本变量原始数据`。
|
||
|
||
如果当前选中了某个工位，变量表中的工位相关字段按该工位做预览；但保存变量时仍保存到设备模块共享变量中。
|
||
|
||
变量表必须完整保留 38 个字段：
|
||
|
||
```text
|
||
TagID
|
||
TagName
|
||
工位号
|
||
数据来源
|
||
IP
|
||
TagTypeID
|
||
TagLong
|
||
DbName
|
||
变量类型
|
||
变量地址
|
||
变量其它
|
||
演示偏移
|
||
列位置
|
||
测量位置
|
||
测量项目
|
||
测量单位
|
||
变量类型代码
|
||
变量类型名称
|
||
机体类型
|
||
线体类型
|
||
TagAdr
|
||
TagAdrDemo
|
||
是否启用
|
||
监控组
|
||
监控时间间隔
|
||
OpcServer_OPNAME
|
||
变量特点
|
||
是否监控
|
||
变量排序
|
||
工序能力
|
||
监控属性代码
|
||
测量位置短
|
||
上限值
|
||
下限值
|
||
理论值
|
||
IsGoodBad
|
||
IsSaveToSql
|
||
IsWebSocket
|
||
```
|
||
|
||
变量操作：
|
||
|
||
- 新增变量
|
||
- 编辑变量
|
||
- 删除变量
|
||
- 复制变量
|
||
|
||
导出前强制覆盖字段：
|
||
|
||
```text
|
||
工位号 = 当前工位.工位名称
|
||
数据来源 = 当前工位.数据来源
|
||
IP = 当前设备模块.设备IP
|
||
DbName = 当前工位.DB
|
||
```
|
||
|
||
`TagID` 导出规则：
|
||
|
||
```text
|
||
TAG_0000001 -> ST04_TAG_0000001
|
||
```
|
||
|
||
如果 `TagID` 已经以当前工位名开头，则不重复添加。
|
||
|
||
## 9. Excel 生成规则 v6
|
||
|
||
点击 `生成 Excel` 时，只导出当前选中的设备模块。
|
||
|
||
### 9.1 设备类型对应表
|
||
|
||
导出列固定为：
|
||
|
||
```text
|
||
设备IP
|
||
设备类型
|
||
DB
|
||
是否启用
|
||
工位号
|
||
数据来源
|
||
```
|
||
|
||
导出来源：
|
||
|
||
| Excel 列 | 来源 |
|
||
| --- | --- |
|
||
| 设备IP | 当前配置行.设备IP |
|
||
| 设备类型 | 当前配置行.设备型号 |
|
||
| DB | 当前配置行.DB |
|
||
| 是否启用 | 当前配置行.是否启用 |
|
||
| 工位号 | 当前配置行.工位名称 |
|
||
| 数据来源 | 当前配置行.设备名称 |
|
||
|
||
如果当前设备模块下有 ST04、ST05 两条配置，则 `设备类型对应表` 生成两行数据。
|
||
|
||
### 9.2 MES_基本变量原始数据
|
||
|
||
`MES_基本变量原始数据` 由当前设备模块共享变量按所有工位展开生成。
|
||
|
||
示例：
|
||
|
||
```text
|
||
当前设备模块：放油设备
|
||
工位：ST04、ST05
|
||
设备模块共享变量：23 条
|
||
导出结果：表头 1 行 + ST04 变量 23 行 + ST05 变量 23 行
|
||
```
|
||
|
||
每条变量导出时：
|
||
|
||
- 保持 38 列顺序不变。
|
||
- 对每个工位复制一遍设备模块共享变量。
|
||
- 使用当前配置行字段覆盖 `工位号 / 数据来源 / DbName / IP`。
|
||
- 按工位生成 `TagID`。
|
||
|
||
### 9.3 导出范围
|
||
|
||
导出规则：
|
||
|
||
- 只导出当前选中的设备模块。
|
||
- 导出当前设备模块下全部工位。
|
||
- 不导出未选中的其他设备模块。
|
||
- 禁用工位也导出，但 `是否启用 = 0`。
|
||
- 禁用设备模块是否允许导出，第一版允许导出，导出内容仍以工位启用状态为准。
|
||
|
||
## 10. 校验规则
|
||
|
||
### 10.1 设备模块校验
|
||
|
||
生成 Excel 前校验当前设备模块：
|
||
|
||
- 必须选择一个设备模块。
|
||
- 设备名称不能为空。
|
||
- 设备型号不能为空。
|
||
- 设备IP不能为空。
|
||
- 当前设备模块下至少存在一个工位。
|
||
|
||
### 10.2 工位校验
|
||
|
||
当前设备模块下所有工位需要校验：
|
||
|
||
- 工位名称不能为空。
|
||
- 数据来源不能为空。
|
||
- DB 不能为空。
|
||
- 同一设备模块下工位名称不能重复。
|
||
- 同一设备模块下 DB 建议不能重复。
|
||
|
||
### 10.3 变量校验
|
||
|
||
当前设备模块共享变量需要校验：
|
||
|
||
- 至少有一条变量。
|
||
- 至少有一条启用变量。
|
||
- `TagID` 不能为空。
|
||
- `TagName` 不能为空。
|
||
- 变量表导出必须保持 38 列。
|
||
- Sheet 名称必须为 `MES_基本变量原始数据`。
|
||
|
||
### 10.4 Excel 校验
|
||
|
||
导出的 Excel 必须满足：
|
||
|
||
- 只包含两个 Sheet。
|
||
- Sheet 名称完全一致。
|
||
- `设备类型对应表` 行数等于当前设备模块下工位数 + 表头。
|
||
- `MES_基本变量原始数据` 行数等于当前设备模块工位数 × 共享变量数 + 表头。
|
||
|
||
## 11. OPFS 持久化规则
|
||
|
||
OPFS 或 localStorage 中保存完整配置：
|
||
|
||
```json
|
||
{
|
||
"version": 2,
|
||
"updatedAt": "2026-06-01T10:00:00.000Z",
|
||
"devices": []
|
||
}
|
||
```
|
||
|
||
兼容迁移规则：
|
||
|
||
- 旧数据中如果是 `一个设备 = 一个工位`，迁移时把旧设备转换为一个设备模块，并在其下创建一个工位。
|
||
- 旧设备的 `stationName / db / dataSource` 移入新工位。
|
||
- 旧设备的 `variables` 移入新设备模块，作为该设备模块共享变量。
|
||
- 旧设备的 `deviceName / deviceModel / deviceIp / enabled` 保留在设备模块。
|
||
- 顶层 `variables[]` 继续作为新增设备模块的默认变量模板来源。
|
||
|
||
## 12. 多工位测试用例
|
||
|
||
| 编号 | 测试项 | 操作 | 预期结果 |
|
||
| --- | --- | --- | --- |
|
||
| T01 | 新建设备模块 | 点击新增设备，填写设备名称、设备型号、设备IP、是否启用 | 左侧出现一个设备模块 |
|
||
| T02 | 新增工位 | 在设备模块中新增 ST04、ST05 两个工位 | 设备模块下出现两个工位 |
|
||
| T03 | 共享变量维护 | 修改当前设备模块共享变量的 `TagName` | ST04、ST05 导出时都使用修改后的变量 |
|
||
| T04 | 删除工位 | 删除 ST04 | 当前设备模块下不再显示 ST04 |
|
||
| T05 | 禁用工位 | 将 ST05 设置为禁用 | 导出中 ST05 的 `是否启用 = 0` |
|
||
| T06 | 导出设备表 | 选择当前设备模块并导出 Excel | `设备类型对应表` 包含 ST04、ST05 两行 |
|
||
| T07 | 导出变量表 | 当前设备模块有 ST04、ST05，共享变量 23 条 | `MES_基本变量原始数据` 包含 ST04 展开 23 行和 ST05 展开 23 行 |
|
||
| T08 | 导出范围 | 选择另一个设备模块导出 | Excel 不包含上一个设备模块的工位 |
|
||
| T09 | 工位重复校验 | 同一设备模块下创建两个 ST04 | 阻止导出并提示工位名称重复 |
|
||
| T10 | 空工位校验 | 工位名称或 DB 为空 | 阻止导出并提示对应字段不能为空 |
|
||
|
||
## 13. 页面草图 v6
|
||
|
||
### 13.1 主页面
|
||
|
||
```text
|
||
┌────────────────────────────────────────────────────────────────────────────────────┐
|
||
│ SignalTable_CZ Excel 生成器 [校验] [生成 Excel] [导入配置] [导出配置] │
|
||
├──────────────────────────────┬─────────────────────────────────────────────────────┤
|
||
│ 左侧：设备模块 │ 右侧：当前设备模块的工位与变量 │
|
||
│ [新增设备] [编辑设备] [删除] │ │
|
||
│ [查询设备模块 ] │ 当前设备：放油设备 / S1500 / 192.168.1.60 │
|
||
│ │ │
|
||
│ ┌──────────────────────────┐ │ 工位列表： │
|
||
│ │ ▶ 放油设备 S1500 启用 │ │ ┌────────┬────────┬─────────┬──────┐ │
|
||
│ │ 注油设备 S1500 启用 │ │ │ ST04 │ 放油前 │ DB10000 │ 启用 │ │
|
||
│ │ 清洗设备 S1500 禁用 │ │ │ ST05 │ 放油后 │ DB10001 │ 启用 │ │
|
||
│ └──────────────────────────┘ │ └────────┴────────┴─────────┴──────┘ │
|
||
│ │ [<] 当前工位 ST04 / 放油前 / DB10000 [>] │
|
||
│ 共 3 个设备模块 │ │
|
||
│ │ 共享变量清单，当前预览工位：ST04 / 放油前 / DB10000 │
|
||
│ │ ┌───────────────────────────────────────────────┐ │
|
||
│ │ │ TagID TagName 类型 地址 │ │
|
||
│ │ │ ST04_TAG_000001 工件到位 Bool 0.0 │ │
|
||
│ │ │ ST04_TAG_000002 读取完成 Bool 0.1 │ │
|
||
│ │ │ ... │ │
|
||
│ │ └───────────────────────────────────────────────┘ │
|
||
└──────────────────────────────┴─────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 13.2 新增/编辑设备模块弹窗
|
||
|
||
```text
|
||
┌─────────────────────────────────────┐
|
||
│ 新增设备模块 │
|
||
├─────────────────────────────────────┤
|
||
│ + │
|
||
│ 设备名称： [放油设备 ] │
|
||
│ 设备型号： [S1500 ] │
|
||
│ 设备IP： [192.168.1.60 ] │
|
||
│ 是否启用： ○ 启用 ○ 禁用 │
|
||
├─────────────────────────────────────┤
|
||
│ 工位管理 │
|
||
│ 点击 + 增加完整工位 │
|
||
│ ┌────────┬────────┬─────────┬────┐ │
|
||
│ │ ST04 │ 放油前 │ DB10000 │ 启 │ │
|
||
│ │ ST05 │ 放油后 │ DB10001 │ 启 │ │
|
||
│ └────────┴────────┴─────────┴────┘ │
|
||
├─────────────────────────────────────┤
|
||
│ [取消] [保存] │
|
||
└─────────────────────────────────────┘
|
||
```
|
||
|
||
### 13.3 空状态
|
||
|
||
```text
|
||
┌──────────────────────────────┬─────────────────────────────────────────────────────┐
|
||
│ 左侧：设备模块 │ │
|
||
│ ┌──────────────────────────┐ │ 请选择左侧设备模块 │
|
||
│ │ 放油设备 S1500 启用 │ │ │
|
||
│ │ 注油设备 S1500 启用 │ │ 选择后可维护该设备下的工位 │
|
||
│ └──────────────────────────┘ │ 和 MES_基本变量原始数据 │
|
||
└──────────────────────────────┴─────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 13.4 无工位状态
|
||
|
||
```text
|
||
┌──────────────────────────────┬─────────────────────────────────────────────────────┐
|
||
│ 左侧：设备模块 │ 当前设备：放油设备 / S1500 / 192.168.1.60 │
|
||
│ ┌──────────────────────────┐ │ │
|
||
│ │ ▶ 放油设备 S1500 启用 │ │ 当前设备模块还没有工位 │
|
||
│ └──────────────────────────┘ │ │
|
||
│ │ 请在设备模块编辑中点击 + 新增工位 │
|
||
└──────────────────────────────┴─────────────────────────────────────────────────────┘
|
||
```
|