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- 聚合方式。
intervalstring- 聚合间隔。
返回值
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- 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" } }