# 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 兼容性单独评估。