cmautobuy/docs/task/11-保存当前设备并登记-client.md

11 保存当前设备并登记 Client

• 类型：Client 功能
• 父级大工单：#1
• 所属 MVP：#2
• 依赖：#6、#8、#10、#12
• 状态：已实现，待验收
• 日期：2026-08-06
• Gitea 工单：#11

目标

设置页保存当前 Windows Client 信息时，先把稳定设备号和设备名写入本地 SQLite，再在后台调用 Admin 的幂等登记接口。远端失败不能回滚本地数据，也不能阻塞界面或领取任务。

最终实现

• 使用 admin.client_id 和 admin.client_name 保存当前 Client 信息。
• 仅在数据库没有有效设备号时生成一次，以后保存保持设备号不变。
• 设备名允许为空，最多 50 个字符；两个设置项在同一事务内保存。
• 调用 PUT /api/v1/client/registration 登记 Client；可选的已勾选 Android 设备会随请求提交。
• HTTP 使用 Python 标准库实现，没有增加第三方依赖；请求不读取系统代理，避免本机或局域网 Admin 被代理软件拦截。
• 保存和 HTTP 登记在 QThread Worker 中执行。保存期间禁用按钮，页面分别显示本地保存和 Admin 登记结果。
• 页面或应用关闭后断开界面信号并忽略迟到结果，避免访问已销毁控件。
• MockAdminGateway 支持幂等登记和失败模拟，方便后续功能开发与测试。

主要文件

• client/src/current_client_service.py
• client/src/http_admin_gateway.py
• client/src/admin_gateway.py
• client/src/mock_admin_gateway.py
• client/src/settings_repository.py
• client/src/settings_ui.py
• client/src/settings_ui_event.py
• client/test/test_current_client_service.py
• client/test/test_http_admin_gateway.py
• client/test/test_settings_ui_event.py

验证结果

• Python 语法检查：通过。
• git diff --check：通过。
• Client 全量单元测试：48 项通过。
• 使用离屏 Qt 验证保存成功、Admin 失败、重试、慢请求不阻塞和关闭后迟到结果：通过。
• 使用临时 Admin 进程和隔离 SQLite 做真实端到端登记：通过；同一 Client 重复登记后记录数仍为 1。

测试环境会提示 PyQt5 字体目录缺失和 sip API 过时警告，但不影响测试结果；这两项是现有运行环境问题，不属于本工单。

待人工验收

1. 启动实际 Admin 和 Client。
2. 进入“参数设置”，填写设备名并点击“保存当前设备”。
3. 确认页面显示“本地已保存，已登记到 Admin”。
4. 重启 Client，确认设备号和设备名能够恢复。
5. 再次保存，确认设备号不变，Admin 中没有新增重复 Client。
6. 停止 Admin 后再次保存，确认本地信息仍保存，页面明确提示 Admin 登记失败。

提交

• fab5778 feat: 保存并登记当前 Client (#11)