快速上手指南（5 分钟跑通全流程）

按照以下步骤依次操作，即可完成从设备上线到用户扫码下单的完整链路：

• 第 1 步 — 添加设备：进入 设备管理，点击 添加设备，填写设备 SN 码、备注名称和 Windows 打印机名称（需与系统"设备和打印机"中的名称完全一致）
• 第 2 步 — 配置 AI 服务：进入 账户管理 → API 配置，填写 AI 服务提供商、服务地址、API Key 等信息（详见下方"AI 工作流配置"）
• 第 3 步 — 创建风格：进入 AI 风格库，点击 新建风格，上传封面图、填写工作流 ID 并启用
• 第 4 步 — H5 模板：进入 H5 模板，创建 H5 模板、添加图片位，将第 3 步创建的风格绑定到图片位
• 第 5 步 — UI 设置：进入 UI 设置，配置 H5 页面外观、大屏 Logo、待机屏标题、咨询二维码等
• 第 6 步 — 绑定并上线：回到 设备管理，编辑设备 → 绑定 H5 模板、UI 模板和定价方案 → 保存后设备即上线
• 第 7 步 — 扫码测试：在设备待机屏扫描二维码，进入 H5 页面完成选风格 → 上传照片 → 支付 → 打印 → 裁切全流程

AI工作流配置 账户 → API配置

• 服务提供商：填写 comfyui、generic 或其他标识
• 服务地址 (base_url)：AI服务的根地址，如 http://192.168.1.10:8188
• API Key：若服务需要鉴权则填写，否则留空
• 工作流接口 (workflow_endpoint)：处理接口路径，如 /api/ai/generate
• 配置完成后，在 AI风格库 的风格详情中填写 工作流ID（工作流文件名或模型ID）并启用该风格

请求格式（POST）：
{"order_id":"...","workflow_id":"...","input_image_url":"...","callback_url":"..."}

同步返回： {"output_url":"http://..."}（立即完成）

异步返回： {"job_id":"..."}（系统每5秒轮询状态）

回调通知： 服务完成后 POST 到 callback_url，body: {"status":"completed","output_url":"..."}

H5扫码流程

• 设备待机屏展示二维码 → 用户扫码打开H5页面
• 第1步：选择风格 → 第2步：上传照片（含确认下单）→ 第3步：查看制作进度
• 设备端自动接收打印任务 → AI处理 → 打印 → 裁切

设备远程控制 WS 实时双向通道

• 在 设备管理 中勾选一或多台设备，顶部工具栏的 关机 / 重启 / 推送更新 / 重置 Token 按钮将触发并行下发：所有目标设备通过 WebSocket 同时收到指令
• 操作完成后会弹出 批量命令结果面板，按设备列出五种状态：
  • EXECUTED：WS 已下发且设备已确认执行（含 RTT 毫秒数）
  • DELIVERED：已下发但未在 5 秒超时窗口内收到确认（设备可能卡顿，建议检查日志）
  • ACCEPTED：设备离线，幂等命令（reload-config / refresh-showcase / push_update）已排队，设备上线后自动补发
  • SKIPPED：设备离线且为非幂等命令（如 restart/shutdown/reset_token），仅记录，不自动补发；设备上线后需人工再次触发
  • NOT_FOUND：设备码未在 devices 表中注册
• 历史记录在 设备管理 → 单设备行 → 远控 按钮打开的控制台对话框中查看，支持实时事件流（设备 → 服务端反向推送）
• 首页顶部的 远控通道运维 widget 每 10 秒刷新：汇总在线连接数 / 平均 RTT / 近 15 分钟内按严重度（info/warn/error/critical）分组的事件数
• 批量单次上限 50 台设备；默认超时 5 秒可通过 API 最大调到 30 秒

设备反向事件上报 device → server WS

设备屏（kiosk）通过同一条 WS 通道主动推送运行状态到服务端，无需后端轮询。当前已接入的触发点：

• connectivity/reconnected：WS 断线重连成功（downtime > 30s 升级 warn，否则 info）
• hardware/printer-status、hardware/cutter-status：设备端周期探测发现打印机/裁切机在线状态翻转时推送
• task/{stage}-failed：任务阶段失败，print/cut 阶段为 critical，download/render 为 error，payload 含 orderId / failCode / failReason 等

所有事件在首页 远控通道运维 widget 的 CRITICAL 柱与下方列表中聚合显示，critical 级事件会闪烁提示。

设备故障一键复位 设备管理 → 编辑设备 → 故障急救

裁切机卡纸、打印机故障等现场异常，会让一批订单卡在"裁切中 / 打印中"无法继续。无需逐单处理或远程登录，在设备编辑器即可一键清场：

• 进入 设备管理 → 编辑某台设备 → 故障急救 块，点击 设备故障一键复位（红色危险按钮）。
• 系统先预查该设备当前"裁切中 / 打印中"的卡单：无卡单则提示"无需复位"，不进任何破坏性操作。
• 有卡单时弹出二次确认，列出将取消的总数及拆分（模式二 X 张 / H5 Y 张）。此操作不可撤销，确认后才执行。
• 执行内容：批量取消该设备卡单（走与单单取消相同的状态机）、刷新大屏回待机；其中模式二单会推一条 failed 通知到合作方（让对方自行退款 / 退积分），H5 单标记为待退款。
• 完成后弹汇总反馈：取消 N 单 / 推送 M 个合作方通知 / 标记 K 单待退款。

取消范围仅限"裁切中 / 打印中"，不会误伤刚下单、尚未开始制作的订单。被取消的 H5 单会在 收入明细 列表显示橙色"待退款"标记，运营据此去支付平台后台手动退款（基础版不自动调退款接口）。

客户端开机启动延时 编辑 startup-delay.txt

真机开机后客户端（大屏 Chrome）延时多久再启动，由设备本地一个纯文本文件控制——运维直接改文件即可，无需进 Windows 任务计划程序：

• 编辑设备上的 D:\gusenprint\startup-delay.txt，内容就是秒数（如 90），保存后重启设备生效。
• 文件缺失或内容非法（空 / 非数字 / 负数等）时自动回退默认 90 秒，不会报错或卡住开机。
• 有效范围 0–600 秒，超过 600 按 600 封顶（防误填导致开机长时间黑屏）。
• 该文件请保存为 UTF-8（无 BOM）；记事本"另存为"时编码选 UTF-8 即可。

收入导出

• 在 收入明细 页面设置筛选条件后点击 导出，CSV文件自动下载
• 导出范围受当前筛选条件约束（时间范围、设备、支付状态等）

常见问题

• 风格无法启用：需要先填写工作流 ID（任意非空字符串均可让系统通过验证）
• H5 风格列表为空：检查设备绑定的 H5 模板是否配置了图片位，图片位是否绑定了已启用的风格
• 删除报错：支持强制删除，删除时会自动解除所有绑定关系
• 重置密码：在 账户管理 → 安全设置 中修改密码
• 打印机名称不匹配：设备管理中填写的打印机名称必须与 Windows「设备和打印机」里显示的名称完全一致（含空格和大小写）
• AI 渲染超时：检查 AI 服务地址是否可达、工作流 ID 是否正确；可在运行日志中查看详细错误信息
• 裁切失败 / 巡边点未识别：确认 Mark 定位标记已开启、纸张位置正确、刀压参数合适；可在设备调试面板中测试裁切
• 订单状态一直"处理中"：进入 首页 → 运行日志 查看该订单各阶段状态；常见原因为 AI 服务无响应或打印队列阻塞
• 设备显示离线：确认设备客户端已启动、网络通畅；可在设备管理中点击 重置 Token 后重新注册
• 二维码扫不出来：检查 UI 设置中是否配置了正确的 H5 入口地址；动态二维码模式需服务端正常运行
• 设备卡纸 / 故障后一批单卡在"制作中"：进入 设备管理 → 编辑该设备 → 故障急救，点 设备故障一键复位 批量清卡单（仅清"裁切中 / 打印中"）；模式二自动通知合作方、H5 单标记待退款
• 收入列表出现"待退款"橙标：是被一键复位取消的 H5 单，需到支付平台后台手动退款（基础版不自动退款）
• 开机后大屏起得太慢 / 太快：编辑该设备的 D:\gusenprint\startup-delay.txt 改秒数（默认 90，范围 0–600），重启设备生效