docs: 归档任务 #11

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)`