From 988444407a1f98c2076787d05d45a87e0f6ff84d Mon Sep 17 00:00:00 2001 From: chengma Date: Thu, 6 Aug 2026 17:58:13 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=BD=92=E6=A1=A3=E4=BB=BB=E5=8A=A1=20?= =?UTF-8?q?#11?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/task/11-保存当前设备并登记-client.md | 60 +++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 docs/task/11-保存当前设备并登记-client.md diff --git a/docs/task/11-保存当前设备并登记-client.md b/docs/task/11-保存当前设备并登记-client.md new file mode 100644 index 0000000..5070f22 --- /dev/null +++ b/docs/task/11-保存当前设备并登记-client.md @@ -0,0 +1,60 @@ +# 11 保存当前设备并登记 Client + +- 类型：Client 功能 +- 父级大工单：#1 +- 所属 MVP：#2 +- 依赖：#6、#8、#10、#12 +- 状态：已实现，待验收 +- 日期：2026-08-06 +- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/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)`