ReinLoopTest/ControlPanel/B端实现说明.md

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：

{
  "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：

{
  "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 使用一次性请求，不监听或扫描文件路径：

{ "type": "createVolumeConfigRequest", "deviceId": "设备 ID" }
{ "type": "getVolumeConfigRequest", "deviceId": "设备 ID", "requestId": "请求 ID" }
{ "type": "ackVolumeConfigRequest", "deviceId": "设备 ID", "requestId": "请求 ID" }

B 端只能在请求有效期内提交容积配置；A 端确认接收后，server 删除请求和临时文件。

读取函数 2 参数：

{ "type": "getIdentificationConfig", "deviceId": "设备 ID" }

查询某个辨识 CSV 的结果：

{
  "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 环境变量：

$env:REINLOOP_API_URL="http://服务器地址:3000/api"
$env:B_ADMIN_TOKEN="与 server 相同的管理令牌"
$env:REINLOOP_DEVICE_ID="设备 ID"
$env:POLL_INTERVAL_MS="1000"

响应 A 端当前待处理的函数 1 参数请求：

node .\b-admin.js publish-volume .\volume-config.example.json

发布函数 2 参数：

node .\b-admin.js publish-identification .\identification-config.example.json

读取当前函数 2 参数：

node .\b-admin.js get-identification

启动监听与评审：

npm start

Electron 图形界面

首次使用安装依赖：

cd ControlPanel
npm install

启动桌面应用：

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 目录执行：

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、listControlFiles、 getControlFileDownload、deleteControlFile。既有模型和反馈接口继续使用。

控制数据接口约定：listControlFiles 按 deviceId 分页返回控制结束后上传到 <deviceId>/data_record/ 的文件元数据；getControlFileDownload 按 fileID 返回带时效的 下载 URL；deleteControlFile 按 fileID 删除文件和元数据。三者均应要求 B 端管理令牌，且 服务端必须验证文件归属控制数据目录，避免使用该接口操作其他业务文件。

9. 已知依赖风险

依赖审计仍报告第三方构建依赖存在安全告警。未执行可能引入破坏性升级的 npm audit fix --force，发布前应结合 Electron Builder 兼容性单独评估。