接口索引

1. 桌面扫码登录

桌面端只访问 SF6；SF6 服务端代理 SSO。创建请求需提供稳定 UUID 格式的 device_id 和设备名称 device_name。

POST /api/desktop/auth/qr
Content-Type: application/json
{"device_id":"550e8400-e29b-41d4-a716-446655440000","device_name":"一车间工作站"}

成功：{"code":0,"data":{"challenge_id":"sf6_...","expires_in":120,"poll_interval":2,"qr_image_data_url":"data:image/png;base64,...","qr_image_url":"https://sf6.xahrf.cn/api/desktop/auth/qr/image?challenge_id=sf6_..."}}

二维码图片为原始 image/png 响应，缓存为 no-store；挑战不存在、过期或已结束返回 404，SSO 图片服务异常返回 502。

GET /api/desktop/auth/qr/image?challenge_id=sf6_...

POST /api/desktop/auth/qr/poll
Content-Type: application/json
{"challenge_id":"sf6_...","device_id":"550e8400-e29b-41d4-a716-446655440000"}

POST /api/desktop/auth/qr/cancel
Content-Type: application/json
{"challenge_id":"sf6_...","device_id":"550e8400-e29b-41d4-a716-446655440000"}

轮询响应状态为 pending、success、expired、cancelled 或 failed。成功时 data 包含 session（SF6 access/refresh token）、employee、device；pending 可带剩余 expires_in。每次轮询建议按 poll_interval 间隔执行。

{"code":0,"data":{"status":"success","session":{"access_token":"...","refresh_token":"...","token_type":"Bearer","expires_in":7200,"refresh_expires_in":7776000},"employee":{"employee_id":"2","sso_user_id":"...","name":"张三","username":"zhangsan","department_id":"...","department_name":"生产部"},"device":{"device_id":"550e8400-e29b-41d4-a716-446655440000","device_name":"一车间工作站"}}}

错误响应为 {"code":"错误码","message":"原因"}。常见 HTTP 状态：400 参数错误、403 设备不匹配/客户端未授权、409 挑战正在完成、429 请求过频、502 SSO 暂不可用、503 SF6 客户端未配置。

2. 会话接口

employee_sso_login 是兼容入口：将 DLME OIDC access token 与设备 UUID 以 JSON POST 提交；优先使用上面的 SF6 扫码流程。旧 employee_login 已停用，固定返回 HTTP 410。

POST https://sf6.xahrf.cn/api.php?action=employee_sso_login
{"access_token":"DLME OIDC access token","device_id":"550e8400-e29b-41d4-a716-446655440000"}

成功：{"success":true,"message":"登录成功","data":{"access_token":"...","refresh_token":"...","expires_in":7200,"refresh_expires_in":7776000,"user":{"id":2,"username":"zhangsan","real_name":"张三","role":"employee","group_name":"生产部"}}}

POST https://sf6.xahrf.cn/api.php?action=refresh_token
{"refresh_token":"当前 refresh token","device_id":"550e8400-e29b-41d4-a716-446655440000"}

POST https://sf6.xahrf.cn/api.php?action=logout
{"refresh_token":"当前 refresh token","device_id":"550e8400-e29b-41d4-a716-446655440000"}

刷新成功返回新的 access_token、refresh_token、expires_in 和 refresh_expires_in；旧 refresh token 立即失效。退出仅撤销匹配设备的会话。令牌错误返回 401，设备不匹配返回 401，停用账号返回 403。

3. 任务和计划项

以下业务接口需 Bearer Access Token。任务只返回已分配给当前员工且状态为 running 的任务；任务项接口返回该员工的待处理、锁定和已完成项。生产任务固定关联当前表盘模板版本，并通过 dial_template 返回快照元数据或 null。

GET https://sf6.xahrf.cn/api.php?action=tasks
GET https://sf6.xahrf.cn/api.php?action=grab_tasks
GET https://sf6.xahrf.cn/api.php?action=my_task_items
GET https://sf6.xahrf.cn/api.php?action=get_task_users&task_id=123
Authorization: Bearer <access_token>

• tasks 返回 {success, has_task, data[]}。每项包括 id、task_name、planned_quantity、distribution_mode、status、gauge_range_info{gauge_name,min_range,max_range}、dial_template。平均分配任务另含 completed_count、my_assigned_count；抢单任务另含 pending_count、my_locked_count。
• grab_tasks 返回有待领取计划项的抢单任务：task_id、task_name、dial_template、meter_range、planned_quantity、distribution_mode、pending_count、my_locked_count。
• my_task_items 每项包括 id、task_id、item_number、task_name、dial_template、meter_range、distribution_mode、status、assigned_user_id、completed_at、dial_upload_id。
• get_task_users 仅允许已分配到该任务的员工查询，返回 data 用户 ID 数组；未分配返回 403。

dial_template 对象字段：template_id、brand、brand_name、product_name、version、sha256、image_url、style_profile_id、calibration、updated_at。

POST https://sf6.xahrf.cn/api.php?action=grab_task_item
Authorization: Bearer <access_token>
Content-Type: application/x-www-form-urlencoded
 task_id=123

成功：{"success":true,"message":"抢单成功","data":{"item_id":456,"item_number":1}}

注意：领取响应不包含表盘模板或图片链接。领取前可从 grab_tasks 响应中读取该任务的 dial_template.image_url；领取后可调用：
GET https://sf6.xahrf.cn/api.php?action=my_task_items
Authorization: Bearer <access_token>

在对应计划项中读取 dial_template.image_url（如任务没有关联启用模板，则 dial_template 为 null）。

POST https://sf6.xahrf.cn/api.php?action=release_task_item
Authorization: Bearer <access_token>
Content-Type: application/x-www-form-urlencoded
item_id=456

成功：{"success":true,"message":"已释放计划数"}

领取只适用于抢单模式任务；同一员工有未完成锁定项时不能再领取。grab_task_item 仅返回 item_id 和 item_number，不会返回模板链接。领取前从 grab_tasks[].dial_template.image_url 获取；领取后调用 my_task_items，从对应计划项的 dial_template.image_url 获取。图片链接需携带 Bearer Token 下载。

4. 上传生产记录

以 multipart/form-data POST。计划项必须处于 locked 且分配给当前员工；成功后记录创建并将计划项标为 completed。用户和量程均由会话及任务自动确定，不需要客户端提交精度或额定/报警参数。

字段	必需	说明
task_item_id	是	本人锁定的计划项 ID
task_id	否	可选校验项，须与计划项所属任务相同
meter_number	是	表计编号
dial_image	否	表盘图片；jpg/jpeg/png/webp/bmp
template_status	否	生成状态，默认“未生成”
extra_json	否	额外 JSON 字符串

POST https://sf6.xahrf.cn/api.php?action=upload_dial
Authorization: Bearer <access_token>
-F "task_item_id=456" -F "meter_number=M20261024001" -F "dial_image=@dial.png"

成功：{"success":true,"message":"表盘数据上传成功","data":{"id":789,"image_path":"uploads/dial_images/...png"}}

400 参数或任务不匹配；403 计划项不属于当前员工或未锁定；404 任务不存在；500 上传或保存失败。

5. 表盘模板

目录和图片需要有效 SF6 Bearer Token，不额外检查客户端模板权限。分组编码由系统生成；先取启用分组，再按 brand 查询组内启用模板。空结果以空数组返回。接口支持 ETag；收到 304 时复用缓存。

GET https://sf6.xahrf.cn/api.php?action=dial_template_groups
Authorization: Bearer <access_token>

{"success":true,"message":"","data":{"groups":[{"brand":"grp_...","brand_name":"平高","updated_at":"2026-10-24T11:00:00+08:00"}]}}

GET https://sf6.xahrf.cn/api.php?action=dial_templates&brand=grp_...
Authorization: Bearer <access_token>

{"success":true,"message":"","data":{"templates":[{"template_id":"dt_0123456789abcdef01234567","brand":"grp_...","brand_name":"平高","product_name":"压力表产品","version":1,"sha256":"...","image_url":"https://sf6.xahrf.cn/api/desktop/dial-templates/dt_0123456789abcdef01234567/image?version=1","style_profile_id":"manual_default","calibration":{"coordinate_system":"image_pixels","origin":"top_left","image_width":1600,"image_height":1600,"guides":[],"parameters":[]},"updated_at":"2026-10-24T11:00:00+08:00"}]}}

brand 可省略以兼容读取所有启用组模板。图片为单独 HTTPS 下载；请求同样需 Bearer Token，响应 image/png，带 SHA-256 ETag 和私有缓存。模板被删除、停用或分组停用时返回 404。

表盘模板上传 API 已移除。模板的新建、编辑和删除请使用 SF6 网页管理界面；客户端 API 仅提供启用分组/模板的读取及受 Bearer Token 保护的图片下载。分组管理同样仅通过网页完成。

6. 软件版本和量程

GET https://sf6.xahrf.cn/api.php?action=latest_version
GET https://sf6.xahrf.cn/api.php?action=meter_ranges

二者目前无需认证。latest_version 返回当前软件版本对象或 null，字段按数据库记录为 id、version_name、version_code、force_update、file_path、description、is_current、created_at。meter_ranges 返回数组项，包含量程记录字段 id、meter_type_id、range_name、min_range、max_range、unit、created_at，以及关联的 type_name、type_code。

{"success":true,"data":{"id":1,"version_name":"Ver 1.0.0","version_code":100,"force_update":0,"file_path":"uploads/software/app.zip","description":"更新说明","is_current":1,"created_at":"2026-10-24 10:00:00"}}

{"success":true,"data":[{"id":1,"meter_type_id":1,"range_name":"0–2.5 MPa","min_range":"0.000","max_range":"2.500","unit":"MPa","created_at":"2026-10-24 10:00:00","type_name":"压力表","type_code":"YLB"}]}

通用错误与兼容说明

• 常规接口错误格式：{"success":false,"message":"..."}，部分错误带稳定的 error 字段。
• 常见 HTTP 状态：400 请求无效、401 令牌无效/过期、403 无权访问、404 action/资源不存在、405 方法不支持、409 版本或状态冲突、429 限流、500 内部错误、503 依赖服务暂不可用。
• 已移除的精度字段及额定值、报警值、闭锁值、超压值不属于当前 API；客户端不应发送或依赖这些字段。
• 所有 JSON 请求使用 UTF-8；上传文件接口使用 multipart/form-data。二维码之外的 POST 参数也可用普通表单提交。