跳到主要内容

HMI 接口

现场 Darra.PLC.HMI(WinForms + WebView2)加载 HMI 页面。Service 侧 HmiWebServer 固定监听 18823(HTTP + WebSocket),端口硬编码,界面不可改。本页是 HMI 登录、活动报警、L1-L2 短期 Historian 与配方部署这组已发布接口。

Historian 只做短时趋势,不是 MES / OEE / SPC,也不是 OPC UA Part 11 Historical Access。HMI 标准页是 main / alarm / trend / recipe / users / settings。登录走 JWT,不要自建凭证页。

确认活动报警​

HmiAlarmPanelEndpoint.Acknowledge · 可执行

按报警编号批量确认当前活动报警。客户端走 POST /api/hmi/alarms/ack;活动列表同时经 WebSocket alarm.acknowledged 推送。

签名​

POST /api/hmi/alarms/ack
Body: { "ids": [1, 2, 3] }

参数​

idsint[]
  • 输入
  • 必填
要确认的报警编号。已确认项不重复处理。

返回值​

returnjson
{ ok: true, acked: 3, failed: [] }。failed 列出未能确认的编号。

行为​

  • 只确认当前活动报警,不改历史归档。
  • 单源是 Service AlarmManager,HMI 不自建报警缓存。
  • HTTP 200 只表示本次确认请求已处理,不表示现场已消警。

错误与限制​

  • 未识别编号进入 failed,不伪造成功。

示例​

确认两条活动报警。

POST /api/hmi/alarms/ack
Content-Type: application/json

{ "ids": [12, 15] }

读取活动报警​

HmiAlarmPanelEndpoint.ListAlarms · 可执行

读取当前活动报警。HMI 报警页按严重度降序、同级再按时间降序排列。

签名​

GET /api/hmi/alarms

参数​

无参数。

返回值​

returnjson
{ ok: true, count: N, alarms: [ { id, severity, code, message, source, timestamp, state }, ... ] }

行为​

  • 没有活动报警时返回空列表;空列表不是故障。
  • 实时新增走 WebSocket alarm.added,本接口是请求时刻快照。
  • 不返回 MES 工单或质量 SPC。

错误与限制​

  • 未声明额外错误码。

示例​

GET /api/hmi/alarms

查询历史数据​

HmiHistorianController.Query · 可执行

按变量、时间范围、聚合方式和间隔查询 L1-L2 短期历史点。路径 /api/runtime/historian/query。

签名​

GET /api/runtime/historian/query?tag=X&from=ISO&to=ISO&agg=avg&interval=1s

参数​

tagstring
  • 输入
  • 必填
采集键名。
fromstring
  • 输入
  • 必填
起始时间,ISO 8601 或 epoch 毫秒。
tostring
  • 输入
  • 必填
结束时间,ISO 8601 或 epoch 毫秒;必须大于 from。
aggstring
  • 输入
  • 可选
  • 默认 avg
  • 约束 avg、min、max、sum、first、last。
聚合方式。
intervalstring
  • 输入
  • 可选
  • 默认 1s
  • 约束 1s、1m、1h。
聚合间隔。

返回值​

returnjson
{ ok: true, tag, agg, interval, from, to, count, points: [{ ts, v }, ...] }。HTTP 200 不等于 Historian 已连接现场总线。

行为​

  • 单次时间窗不超过 7 天,单次最多 5000 点(与 HMI historian.js 对齐)。
  • 已启动但该 tag 无数据时诚实返回空 points,不投影健康态。
  • 拒绝 OEE / SPC / 工单 / OPC UA HA / Parquet / Excel / PDF 查询路径。

错误与限制​

  • 400 bad_request:缺 tag、from/to 无法解析、to ≤ from、agg 或 interval 非法。
  • 400 window_too_large:时间窗超过 7 天。
  • 503 historian_not_running:Historian 未启动。空归档不是健康态。
  • 503 historian_query_failed:查询失败,禁止 200 空点装成功。

示例​

查过去 1 小时平均温度。

GET /api/runtime/historian/query?tag=DB1.Temp&from=2026-09-04T00:00:00Z&to=2026-09-04T01:00:00Z&agg=avg&interval=1s

读取历史变量​

HmiHistorianController.Tags · 可执行

列出当前 Historian 已有历史数据的变量名。HistorianService.ListKeys() 真取,不返回 mock 列表。

签名​

GET /api/runtime/historian/tags

参数​

无参数。

返回值​

returnjson
{ ok: true, count: N, tags: ["Tag1", "Tag2", ...] }

行为​

  • 仅在 Historian 已启动时返回 200。未启动不得 ok:true + 空 tags。
  • 已启动且尚无键时返回空列表,表示无采集键,不是健康证明。

错误与限制​

  • 503 historian_not_running:未启动。
  • 503 historian_empty_archive:ListKeys 失败。

示例​

GET /api/runtime/historian/tags

HMI 用户登录​

HmiAuthController.Login · 可执行

使用用户名和密码创建 HMI 浏览器会话。凭据走 Service RbacService(%ProgramData%/DarraPLC/auth,Argon2id/PBKDF2),与 IDE 用户库同一套。JWT 只放 Authorization: Bearer,不解析 Cookie。

签名​

POST /api/runtime/auth/login
Body: { "username": "...", "password": "...", "remember": true }

参数​

usernamestring
  • 输入
  • 必填
用户名。
passwordstring
  • 输入
  • 必填
密码。
rememberbool
  • 输入
  • 可选
  • 默认 false
true 时 access 有效期按 30 天 refresh;false 时 access 15 分钟。

返回值​

returnjson
{ token, exp, role, sessionId }。role 为 admin / engineer / operator / maintenance。

行为​

  • HS256 JWT,payload {sub, role, sid, exp, iat}。
  • remember 会话每 5 分钟回查 RBAC;账户禁用或改角色最迟下一请求生效。
  • 认证失败不区分用户是否存在。
  • 本接口是 HMI 浏览器会话。IDE 登录走 WebView2,禁止自建 /login 凭证页。

错误与限制​

  • 400 missing_fields:缺用户名或密码。
  • 401 invalid_credentials:用户不存在、禁用、密码错或锁定。
  • 405 method_not_allowed:非 POST。

示例​

POST /api/runtime/auth/login
Content-Type: application/json

{ "username": "operator", "password": "...", "remember": false }

HMI 用户登出​

HmiAuthController.Logout · 可执行

结束当前 HMI 会话并撤销 JWT。

签名​

POST /api/runtime/auth/logout
Authorization: Bearer <token>

参数​

无参数。

返回值​

returnjson
{ ok: true }

行为​

  • 重复登出保持幂等。
  • 只撤销本会话,不改 RBAC 用户库。

错误与限制​

  • 405 method_not_allowed:非 POST。

示例​

POST /api/runtime/auth/logout
Authorization: Bearer <token>

读取配方列表​

RecipeWebEndpoint.ListRecipes · 可执行

读取控制项目中的全部配方。权威路径是复数 /api/hmi/recipes,不是已退役的 /api/runtime/recipe 内存 stub。

签名​

GET /api/hmi/recipes

参数​

无参数。

返回值​

returnjson
[ { id, name, description, groupId, version, createdAt, updatedAt }, ... ]。空数组表示未配置配方,不是故障。

行为​

  • 返回当前版本与更新时间。
  • HTTP 200 不等于配方已写入 .dplc。
  • 配方是设备控制参数,不是 MES 工单或物料清单。

错误与限制​

  • 未声明额外错误码。

示例​

GET /api/hmi/recipes

加载配方​

RecipeWebEndpoint.DeployRecipe · 可执行

把指定配方提交到扫描边界。只有 State=Committed 才算已应用。HTTP 200 且 Success 但非 Committed 不得装已部署。

签名​

POST /api/hmi/recipes/{id}/deploy
Body: { "targetVariables": { "DB1.Setpoint": "12.5" } }

参数​

idstring
  • 输入
  • 必填
配方 ID。
targetVariablesobject
  • 输入
  • 必填
  • 约束 至少一个目标变量。
目标变量映射。空对象拒绝部署。

返回值​

returnjson
Committed 返回 200,含 TransactionId。仍在扫描队列返回 202 Pending,调用方用 GET /api/hmi/recipes/deployments/{transactionId} 续查,绝不重提。

行为​

  • 部署在下一扫描边界原子提交。
  • 查询同一 transactionId 不重复提交。
  • 设计时调用会失败,不得假装已应用。

错误与限制​

  • 400:请求 JSON 无效或 targetVariables 为空。
  • 404:配方不存在或事务未知。
  • 202:已入队未提交。
  • 502 / 503:执行异常或入队被拒。

示例​

部署配方到设定值,若 202 则续查。

POST /api/hmi/recipes/line-a/deploy
Content-Type: application/json

{ "targetVariables": { "DB1.Speed": "1500" } }