固件写入工具设计

相关仓库：firmware-tool https://github.com/ffffxxxjjj/firmware-tool ；sign https://github.com/ffffxxxjjj/sign ；gateway https://github.com/ffffxxxjjj/gateway 。固件分发全流程见 sign 仓 docs/固件分发全流程.md；服务端端点见 sign 仓 docs/sign-server-api.md。

1. 定位与边界

• 给现场实施人员用，图形界面向导式操作，不是开发时的出包加命令行直写。
• 用在出发前准备区，一台接一台批量准备设备；客户现场只剩安装、上电、验在线。
• 工具不管签名钥匙（1 初始 + 2 备用是全局的，跟着固件走）；不管 OTA 打包（那是管理后台的事）。
• 无离线写：必须联网，无网拒绝开始，不做后期补录。
• 工具不产生密钥对：密钥对由后台生成、绑定序列号，工具只接收后台分发的私钥与序列号（旧的“现场产生、人工登记”流程已作废）。

2. 单台设备流程

1. 准备：出发前从管理后台批量领号，工具里导入号段；准备包（在线从下载页下载，或选本地文件）。
2. 联网检查：必须联网，无网拒绝开始。
3. 操作员登录：工具用操作员账号（用户名密码）登录管理后台（POST /operator/login，操作员会话 Cookie，HttpOnly，12 小时）。
4. 取密钥：工具向后台上报设备序列号、型号等，后台分发密钥对并绑定到该序列号（POST /devices/issue，只走操作员会话；公钥私钥都存后台，记操作时间、操作人等审计）；重发须 reissue=true，返回存量密钥不轮换。
5. 连接设备：DAPLink 一根线（SWD 烧写 + 虚拟串口对话）。
6. 写固件：SWD 写初始固件，烧完校验。
7. 写私钥与序列号：工具经串口发给固件，固件写进一次性可编程存储区，读回确认（PROV BEGIN → PROV SERIAL <序列号> → PROV KEY <64 位十六进制私钥> → PROV COMMIT → OK PROVISIONED；固件回复永不输出私钥）。
8. 读出显示：工具读回序列号，界面显示，操作人员人工记录台账，点“已记录”继续（台账作核对用；系统记录以后的台分发记录为准）。
9. 完成：一台完成，换下一台。任一步失败停下，不放行。

注：第 4 步（取密钥）与第 7 步（写私钥与序列号）顺序固定：先取到密钥，再写进设备；没有分发成功的台不写。

3. 界面

• 步骤向导：准备 → 登录 → 取密钥 → 连接 → 写入 → 确认 → 完成；当前步高亮，已完成打勾，失败步标红停住。
• 设备队列：批量准备时排队，一台完成提示换下一台；每台记录序列号、型号、版本、结果、时间。
• 日志区：每步操作和结果实时显示，失败写明原因。
• 关键显示：序列号读出后显示，供人工记录；“已记录”确认按钮。
• 联网状态：无网时开始按钮禁用，并明示原因。

4. 服务端（管理后台，接口以实现为准）

• 设备列表（登记表）：管理后台页面，字段：序列号、型号、公钥（列表不出现私钥）、上线状态、固件版本、当前版本、最新版本、登记时间、登记方式。
• 批量领号：POST /devices/allocate（管理员会话；数量 1–1000，否则 400；序列号 GW{YYYYMMDD}{序号:04}，按天计数、不重复，标记已领出防重领）。
• 操作员登录：POST /operator/login（用户名密码；失败一律 401 通用文案）；建操作员 POST /operators（管理员会话）；禁用 POST /operators/{用户名}/disable（管理员会话，幂等，禁用后会话失效；本版无恢复接口）。
• 分发设备密钥：POST /devices/issue（只走操作员会话；序列号须在已领出批次里，否则 400；已分发不带 reissue=true 拒绝；没分发过带 reissue=true 拒绝；已用写入工具上报登记过的序列号（无后台存钥）再分发拒绝；返回序列号、型号、公钥、私钥、分发时间、分发人）。
• 写入工具上报登记：POST /devices（只走机器凭证签名，不走会话；序列号、公钥、型号、固件版本；序列号须在已领出批次里且未登记，否则 400）。这是另一条登记路径（工具上报已备好密钥的设备），不是分发流程的必经步：分发流程的台由分发即登记，不重复调本接口；已用本接口登记过的序列号不能再分发（无后台存钥可交付）。
• 查询：GET /devices、GET /devices/{序列号}（管理员会话；列表含当前版本与最新版本）。
• 公开下载首页：免登录页面，供下载初始固件和写入工具安装包。初始固件只含公开钥匙、无私钥，可公开。

5. 设备端配合（已定）

• 固件 provisioning 命令（经串口，DAPLink 自带虚拟串口）：PROV BEGIN／PROV SERIAL／PROV KEY／PROV COMMIT／PROV ABORT／PROV STATUS；协议、状态机、提交检查顺序、字段规则、错误码见 gateway 仓 docs/provisioning.md（固件只接收后台分发的私钥与序列号，不再自产密钥）。
• 命令格式：纯 ASCII，全大写，一行一条，\n 结尾（\r\n 也行）；单行最长 128 字节；回复一行，含结尾 \n。
• 信任区与签名钥匙（1 初始 + 2 备用）跟着固件走，不用工具处理。

6. 约束与失败处理

• 必须联网：启动和分发前检查网络，无网拒绝开始，不做离线写。
• 任一步失败停下：该设备不放行，不进入下一台；失败原因写进日志和记录。
• 分发成功且写进确认才算完成一台：分发没成功、写进没确认前不算完。
• 公钥格式校验：64 位十六进制，否则拒绝（与分发接口同一规则）。
• 序列号防重：领号时标记已领出，分发时核对在已领出批次里；重复分发按重发规则；重复登记拒绝。
• 私钥只出现在工具内存与串口发送行里，不写日志、不进台账、不回显。

7. 待接事项

• 界面与向导、串口对话、SWD 烧写接线（工具骨架已建，接线待做）。
• SWD 烧写用 probe-rs + DAPLink（CMSIS-DAP），不用另装烧录软件；串口对话用 DAPLink 自带虚拟串口 + serialport 库（跨平台）。烧写时串口必须关闭（DAPLink 占用冲突），流程顺序先烧写、后开串口正好避开。
• 操作员会话在工具内的存取方式（登录后 Cookie 存取，掉线重登）。