250 lines
9.3 KiB
Markdown
250 lines
9.3 KiB
Markdown
# B 端需求拆解与实现说明
|
||
|
||
## 1. 需求翻译
|
||
|
||
系统包含两个流程：
|
||
|
||
1. 容积测量：A 端发起一次配置请求，B 端将严格 8 字段的配置 JSON 提交到该请求，A 端下载参数并调用 `start_volume_measurement`。
|
||
2. 辨识：B 端发布“函数 2 参数”；A 端采集稳定压力 JSON 和辨识 CSV 并上传；B 端打印稳定压力、下载新 CSV、绘图并人工返回 0/1。
|
||
|
||
辨识结果约定：
|
||
|
||
- `1`：参数通过，A 端结束本次辨识。
|
||
- `0`：参数未通过，B 端必须同时提交一套新的函数 2 参数，A 端下载后重新辨识。
|
||
|
||
## 2. 已实现内容
|
||
|
||
### Server 中转接口
|
||
|
||
- `getPendingVolumeConfigRequest`：返回指定设备当前等待 B 端响应的容积请求。
|
||
- `submitVolumeConfigFile`：将 B 端上传的容积配置绑定到对应请求。
|
||
- `publishIdentificationConfig`：按设备发布函数 2 的 CSV 配置。
|
||
- `getIdentificationConfig`：A 端按设备读取函数 2 配置。
|
||
- `setIdentificationFeedback`：B 端按设备与运行 ID 返回 0/1。
|
||
- `getPendingPanelFile`：按设备返回下一条待处理 CSV/JSON 消息。
|
||
- `ackPanelFile`：确认处理完成并删除 server 暂存文件。
|
||
- 参数发布和评审写入要求 `B_ADMIN_TOKEN`。
|
||
|
||
server 使用 `fileRecords` 保存上传文件索引，使用 `identificationFeedback`
|
||
保存当前设备待消费的辨识反馈。
|
||
|
||
### B 端本地程序
|
||
|
||
- `b-admin.js`：响应设备容积请求并上传配置 JSON，同时发布和读取函数 2 参数。
|
||
- `poll-panel-inbox.js`：获取 server 中待处理的数组 JSON 与辨识 CSV 消息。
|
||
- `plot-json.js`：将数字数组、数值对象数组或多个数值数组绘制为折线图。
|
||
- 新 CSV 到达后自动下载并生成上下组合时序图。
|
||
- 人工输入 0/1；输入 0 时读取新函数 2 JSON 并提交。
|
||
- 只有下载、绘图、评审提交全部成功后，文件才标记为已处理。
|
||
|
||
## 3. 参数契约
|
||
|
||
函数 1，对应 `start_volume_measurement`：
|
||
|
||
```json
|
||
{
|
||
"q_in_val": 91,
|
||
"dt": 0.1,
|
||
"xa_full": 1000,
|
||
"p_max": 200,
|
||
"fit_low": 50,
|
||
"fit_high": 200,
|
||
"T_delta": 30,
|
||
"num_runs": 6
|
||
}
|
||
```
|
||
|
||
函数 2，对应 `start_identification`：
|
||
|
||
```json
|
||
{
|
||
"q_in_val": 91,
|
||
"dt": 0.1,
|
||
"n_order": 8,
|
||
"t_c": 2.5,
|
||
"levels": [10, 20, 30, 40, 50, 60, 70, 80],
|
||
"dead_area": 0,
|
||
"xa_full": 1000,
|
||
"V_val": 1,
|
||
"repeat": 2
|
||
}
|
||
```
|
||
|
||
示例数值仅用于联调，正式值需要算法或产品确认。
|
||
|
||
## 4. A 端调用契约
|
||
|
||
函数 1 使用一次性请求，不监听或扫描文件路径：
|
||
|
||
```json
|
||
{ "type": "createVolumeConfigRequest", "deviceId": "设备 ID" }
|
||
{ "type": "getVolumeConfigRequest", "deviceId": "设备 ID", "requestId": "请求 ID" }
|
||
{ "type": "ackVolumeConfigRequest", "deviceId": "设备 ID", "requestId": "请求 ID" }
|
||
```
|
||
|
||
B 端只能在请求有效期内提交容积配置；A 端确认接收后，server 删除请求和临时文件。
|
||
|
||
读取函数 2 参数：
|
||
|
||
```json
|
||
{ "type": "getIdentificationConfig", "deviceId": "设备 ID" }
|
||
```
|
||
|
||
查询某个辨识 CSV 的结果：
|
||
|
||
```json
|
||
{
|
||
"type": "getIdentificationFeedback",
|
||
"deviceId": "设备 ID",
|
||
"runId": "CSV 文件名"
|
||
}
|
||
```
|
||
|
||
未评审时返回 `ready: false`；评审后返回 `ready: true` 和 `result: 0|1`。
|
||
当结果为 0 时，A 端重新调用 `getIdentificationConfig` 获取已经更新的 CSV。
|
||
|
||
## 5. Server 部署
|
||
|
||
1. 配置 server 环境变量 `B_ADMIN_TOKEN`、`HOST`、`PORT` 和可选的 `DATA_DIR`。
|
||
2. ControlPanel 与 ReinLoop 使用相同的 server URL 和设备 ID。
|
||
3. Panel 不扫描文件目录，仅按设备 ID 消费 server 消息队列。
|
||
4. CSV 处理完成后由 server 自动删除暂存文件。
|
||
|
||
## 6. B 端运行
|
||
|
||
PowerShell 环境变量：
|
||
|
||
```powershell
|
||
$env:REINLOOP_API_URL="http://服务器地址:3000/api"
|
||
$env:B_ADMIN_TOKEN="与 server 相同的管理令牌"
|
||
$env:REINLOOP_DEVICE_ID="设备 ID"
|
||
$env:POLL_INTERVAL_MS="1000"
|
||
```
|
||
|
||
响应 A 端当前待处理的函数 1 参数请求：
|
||
|
||
```powershell
|
||
node .\b-admin.js publish-volume .\volume-config.example.json
|
||
```
|
||
|
||
发布函数 2 参数：
|
||
|
||
```powershell
|
||
node .\b-admin.js publish-identification .\identification-config.example.json
|
||
```
|
||
|
||
读取当前函数 2 参数：
|
||
|
||
```powershell
|
||
node .\b-admin.js get-identification
|
||
```
|
||
|
||
启动监听与评审：
|
||
|
||
```powershell
|
||
npm start
|
||
```
|
||
|
||
### Electron 图形界面
|
||
|
||
首次使用安装依赖：
|
||
|
||
```powershell
|
||
cd ControlPanel
|
||
npm install
|
||
```
|
||
|
||
启动桌面应用：
|
||
|
||
```powershell
|
||
npm run gui
|
||
```
|
||
|
||
图形界面提供以下功能：
|
||
|
||
- 选择本地辨识 CSV，调用现有绘图模块生成并预览上下组合时序图。
|
||
- 打开并预览已有 PNG/JPG 绘图结果。
|
||
- 导入或直接编辑容积测量、系统辨识 JSON 配置。
|
||
- 读取当前系统辨识配置并发布新配置。
|
||
- 响应 ReinLoop 已发起的容积请求；没有待处理请求时拒绝上传。
|
||
- 容积配置发布前强制校验 8 个字段、数值类型以及 `num_runs` 整数类型。
|
||
|
||
Server API URL 和 Admin Token 可以在界面顶部输入，也可以在启动应用前设置
|
||
`REINLOOP_API_URL`、`B_ADMIN_TOKEN` 环境变量。Token 仅由 Electron 主进程用于请求，
|
||
不会保存到浏览器存储或配置文件。
|
||
|
||
### 打包 Windows EXE
|
||
|
||
在 `ControlPanel` 目录执行：
|
||
|
||
```powershell
|
||
npm install
|
||
npm run pack:win
|
||
```
|
||
|
||
构建结果输出到仓库根目录的 `Build` 文件夹：
|
||
|
||
- 安装版 EXE：运行后可选择安装目录，并创建桌面和开始菜单快捷方式。
|
||
- 便携版 EXE：无需安装，可直接运行。
|
||
- `win-unpacked`：未压缩的应用目录，适合排查打包后的运行问题。
|
||
|
||
应用包含原生 `canvas` 绘图模块，打包配置会自动将它从 ASAR 中解包。不要手动删除
|
||
`win-unpacked/resources/app.asar.unpacked`。未配置代码签名证书时，Windows 首次运行可能
|
||
显示 SmartScreen 提示；正式对外分发时应配置可信的 Windows 代码签名证书。
|
||
|
||
## 7. 仍需产品/A 端确认
|
||
|
||
- A 端数组 JSON 的最终结构尚未定义；当前兼容数字数组、数值对象数组和对象内多个数值数组。
|
||
- B→A 配置、A→B CSV、A→B 数组 JSON 都保存在 server 的 `DATA_DIR` 下。
|
||
- 两套参数示例中的正式默认值、单位和合法范围尚未定义。
|
||
- A 端上传稳定压力 JSON 与辨识 CSV 到 `<设备 ID>/ind_data`。
|
||
- A 端按 CSV 文件名登记 `runId`，B 端以相同 `runId` 提交反馈。
|
||
- 当前图像是否通过由 B 端人工判断；产品未提供自动判断算法或阈值。
|
||
|
||
## 8. 公司、产线、许可证与模型管理
|
||
|
||
Electron 工作台现已使用“公司 + 产线”选择代替手工设备 ID。Server 返回的
|
||
`deviceId` 固定为 `<company_code>/<production_line_code>`，配置发布、模型目录、
|
||
绘图收件箱和辨识反馈均使用同一个值。
|
||
|
||
应用启动时首先显示连接门禁页，只提供 Server API URL 和 Admin Token。点击
|
||
“连接并校验”后，主进程调用需要管理权限的 `listOrganizations` 接口同时检查
|
||
网络、API 地址和 Token；只有请求成功才显示公司、产线以及后续业务标签页。
|
||
连接失败时业务区保持隐藏并显示 Server 返回的错误。本次应用会话不提供更改连接
|
||
入口，需要切换 Server 或 Token 时重新启动应用。
|
||
|
||
公司与产线菜单会显示 `● 在线`、`○ 离线` 或 `◇ 状态未知`，并在连接成功后
|
||
每 10 秒静默刷新。在线状态来自 `listOrganizations` 中每条产线的 `online` 字段，
|
||
可选的 `lastSeenAt` 用于 Server 判断心跳是否超时；旧 Server 未返回该字段时显示
|
||
“状态未知”，不会误报在线。
|
||
|
||
组织管理页支持：
|
||
|
||
- 添加公司，编码只允许小写字母、数字、下划线和连字符。
|
||
- 在公司下添加产线；同一公司的产线编码必须唯一。
|
||
- 刷新组织后，顶部公司和产线菜单同步更新。
|
||
|
||
许可证页支持：
|
||
|
||
- 根据当前公司和产线签发许可证。
|
||
- 每次签发由操作者选择外部 RSA 私钥和本地保存位置；Panel 不保存或上传私钥。
|
||
- 许可证采用与 ReinLoop 相同的 RSA-PSS SHA-256 格式，并包含公司、产线和组合设备 ID。
|
||
- 本地文件写入成功后才登记 Server；登记失败会删除本次本地文件，避免半完成状态。
|
||
- 查看已签发许可证详情和撤销许可证。
|
||
|
||
模型管理页按当前产线列出 `<deviceId>/model_config`，支持上传、下载和删除。
|
||
|
||
绘图页收到辨识 CSV 后提供“通过/未通过”操作。选择未通过时必须先导入并成功
|
||
发布一份新的系统辨识配置，随后才提交数字 `0`；通过则提交数字 `1`。CSV 在结论
|
||
提交成功前不会从 Server 收件箱删除，应用中途退出后仍可重新获取。行程 JSON 在
|
||
绘图成功后直接确认。
|
||
|
||
Panel 当前依赖以下新增 Server type：
|
||
|
||
`listOrganizations`、`createCompany`、`createProductionLine`、`createLicense`、
|
||
`listLicenses`、`getLicense`、`revokeLicense`。既有模型和反馈接口继续使用。
|
||
|
||
## 9. 已知依赖风险
|
||
|
||
依赖审计仍报告第三方构建依赖存在安全告警。未执行可能引入破坏性升级的
|
||
`npm audit fix --force`，发布前应结合 Electron Builder 兼容性单独评估。 |