保存当前设备并登记 Client #11

New Issue

2026-08-06T17:06:03+08:00

ila commented

2026-08-06 17:06:03 +08:00

基本信息

类型：需求
父级大工单：#1
所属 MVP / 版本：#2 / MVP
阶段：3. Admin Mock/Gateway 闭环
依赖：#6、#8、#10、#12
当前状态：验收通过

要解决什么

设置页“当前设备”保存按钮需要完成两件职责清晰的动作：

检查并持久化本机设备号和设备名；
本地保存成功后，在后台调用独立登记接口，把当前 Client 幂等登记或更新到 Admin。

不再通过 claim 或心跳完成设置页登记。登记接口由 Admin 工单 #12 实现；claim 只在“获取任务”流程调用。

已确认接口

PUT /api/v1/client/registration
X-Client-Id: <稳定设备号>
X-Request-Id: <uuid>
Content-Type: application/json
Authorization: Bearer <token>

请求沿用领取能力结构：

{
  "client": {"name": "办公室-01"},
  "supported_types": ["collect", "purchase"],
  "device": {
    "address": "192.168.0.173:5555",
    "platform": "android",
    "pdd_package": "com.xunmeng.pinduoduo"
  },
  "capabilities": {
    "purchase_mode": "dry_run",
    "schema_versions": [1]
  }
}

成功统一返回 200：

{
  "registered": true,
  "client_id": "CLIENT-123456",
  "registered_at": "2026-08-06T09:00:00Z"
}

正式细节以 #12 和双方权威契约为准。

本地保存规则

“当前设备”指运行 Client 的 Windows 电脑，不是 Android 设备；
SQLite 的 admin.client_id 是设备号权威来源；
不存在时生成一次并持久化，存在时保持不变；
不把界面中的“待生成”当成数据库状态；
设备名最多 50 字，可为空；本地保存到 admin.client_name；
不向 Admin 发送生成设备号所用的原始硬件参数；
本地保存成功后立即更新页面，再启动远端登记；
Admin 登记失败不得回滚本地保存；
页面必须区分“本地保存成功”和“Admin 登记失败”。

实现方案

增加当前 Client 设置读写服务，集中处理设备号生成和设置键。
扩展 AdminGateway 和 MockAdminGateway，增加 register_client。
#12 完成后实现 HttpAdminGateway.register_client。
使用 QObject + moveToThread Worker 执行 HTTP，禁止阻塞主线程。
保存期间禁用重复点击；完成或失败后恢复。
窗口关闭时断开信号并忽略迟到结果。
使用 Mock 测试本地保存、远端成功、远端失败、超时和重复登记。
本任务只做显式登记，不做定时心跳，不领取任务。

暂定修改范围

client/src/settings_ui_event.py
client/src/settings_repository.py
client/src/admin_gateway.py
client/src/mock_admin_gateway.py
client/src/http_admin_gateway.py
可能新增当前 Client 设置/登记应用服务
client/requirements.txt（启用固定版本 HTTP 依赖前单独确认）
client/test/ 对应测试

不做什么

不从设置保存入口调用 claim；
不领取、保存或执行 PDD 任务；
不增加定时心跳、租约或 Admin 状态查询；
不在 Qt 主线程执行 HTTP；
不重新生成已经存在的设备号；
不因 Admin 失败删除或回滚本地设备信息；
不记录 token、原始硬件参数或完整敏感请求头；
不接入 Android 自动化或真实下单。

验收标准

无设备号时生成并保存到 admin.client_id；
已有设备号时保持不变；
设备号和设备名能从 SQLite 恢复；
名称长度和请求字段在本地校验；
本地保存成功后后台调用正式登记接口；
相同设备号重复保存不会创建重复 Client；
登记接口不会领取或改变任务；
Admin 失败不影响本地保存结果；
用户能区分本地保存状态和 Admin 登记状态；
HTTP 不阻塞 Qt 主线程；
窗口关闭后的迟到结果��会访问已销毁控件；
Mock、HTTP 契约、Repository、事件和离屏 Qt 测试通过；
全量 unittest、语法检查和 git diff --check 通过。

怎么验证

实现前先等待 #12 的 Admin 测试和真实 curl 联调通过；Client 完成后使用同一契约用例验证 Mock 与 HTTP Gateway。

## 基本信息 - 类型：需求 - 父级大工单：#1 - 所属 MVP / 版本：#2 / MVP - 阶段：3. Admin Mock/Gateway 闭环 - 依赖：#6、#8、#10、#12 - 当前状态：验收通过 ## 要解决什么设置页“当前设备”保存按钮需要完成两件职责清晰的动作： 1. 检查并持久化本机设备号和设备名； 2. 本地保存成功后，在后台调用独立登记接口，把当前 Client 幂等登记或更新到 Admin。不再通过 `claim` 或心跳完成设置页登记。登记接口由 Admin 工单 #12 实现；`claim` 只在“获取任务”流程调用。 ## 已确认接口 ```http PUT /api/v1/client/registration X-Client-Id: <稳定设备号> X-Request-Id: <uuid> Content-Type: application/json Authorization: Bearer <token> ``` 请求沿用领取能力结构： ```json { "client": {"name": "办公室-01"}, "supported_types": ["collect", "purchase"], "device": { "address": "192.168.0.173:5555", "platform": "android", "pdd_package": "com.xunmeng.pinduoduo" }, "capabilities": { "purchase_mode": "dry_run", "schema_versions": [1] } } ``` 成功统一返回 `200`： ```json { "registered": true, "client_id": "CLIENT-123456", "registered_at": "2026-08-06T09:00:00Z" } ``` 正式细节以 #12 和双方权威契约为准。 ## 本地保存规则 - “当前设备”指运行 Client 的 Windows 电脑，不是 Android 设备； - SQLite 的 `admin.client_id` 是设备号权威来源； - 不存在时生成一次并持久化，存在时保持不变； - 不把界面中的“待生成”当成数据库状态； - 设备名最多 50 字，可为空；本地保存到 `admin.client_name`； - 不向 Admin 发送生成设备号所用的原始硬件参数； - 本地保存成功后立即更新页面，再启动远端登记； - Admin 登记失败不得回滚本地保存； - 页面必须区分“本地保存成功”和“Admin 登记失败”。 ## 实现方案 1. 增加当前 Client 设置读写服务，集中处理设备号生成和设置键。 2. 扩展 `AdminGateway` 和 `MockAdminGateway`，增加 `register_client`。 3. #12 完成后实现 `HttpAdminGateway.register_client`。 4. 使用 `QObject + moveToThread` Worker 执行 HTTP，禁止阻塞主线程。 5. 保存期间禁用重复点击；完成或失败后恢复。 6. 窗口关闭时断开信号并忽略迟到结果。 7. 使用 Mock 测试本地保存、远端成功、远端失败、超时和重复登记。 8. 本任务只做显式登记，不做定时心跳，不领取任务。 ## 暂定修改范围 - `client/src/settings_ui_event.py` - `client/src/settings_repository.py` - `client/src/admin_gateway.py` - `client/src/mock_admin_gateway.py` - `client/src/http_admin_gateway.py` - 可能新增当前 Client 设置/登记应用服务 - `client/requirements.txt`（启用固定版本 HTTP 依赖前单独确认） - `client/test/` 对应测试 ## 不做什么 - 不从设置保存入口调用 `claim`； - 不领取、保存或执行 PDD 任务； - 不增加定时心跳、租约或 Admin 状态查询； - 不在 Qt 主线程执行 HTTP； - 不重新生成已经存在的设备号； - 不因 Admin 失败删除或回滚本地设备信息； - 不记录 token、原始硬件参数或完整敏感请求头； - 不接入 Android 自动化或真实下单。 ## 验收标准 - [x] 无设备号时生成并保存到 `admin.client_id`； - [x] 已有设备号时保持不变； - [x] 设备号和设备名能从 SQLite 恢复； - [x] 名称长度和请求字段在本地校验； - [x] 本地保存成功后后台调用正式登记接口； - [x] 相同设备号重复保存不会创建重复 Client； - [x] 登记接口不会领取或改变任务； - [x] Admin 失败不影响本地保存结果； - [x] 用户能区分本地保存状态和 Admin 登记状态； - [x] HTTP 不阻塞 Qt 主线程； - [x] 窗口关闭后的迟到结果��会访问已销毁控件； - [x] Mock、HTTP 契约、Repository、事件和离屏 Qt 测试通过； - [x] 全量 unittest、语法检查和 `git diff --check` 通过。 ## 怎么验证实现前先等待 #12 的 Admin 测试和真实 curl 联调通过；Client 完成后使用同一契约用例验证 Mock 与 HTTP Gateway。

ila referenced this issue

2026-08-06 17:06:15 +08:00

[Epic] Client 拼多多任务采集与采购客户端 #1

ila referenced this issue

2026-08-06 17:06:15 +08:00

[MVP] Client 可运行任务闭环 #2

ila commented

2026-08-06 17:06:19 +08:00

工单已创建，当前仅记录已确认流程和待确认契约，不开始编码。等待 Admin 心跳接口文档后先更新本工单，再实施。

ila referenced this issue

2026-08-06 17:17:03 +08:00

Admin：新增幂等 Client 登记接口 #12

ila changed title from ~~保存当前设备并通过心跳登记 Client~~ to 保存当前设备并登记 Client

2026-08-06 17:17:33 +08:00

ila commented

2026-08-06 17:17:49 +08:00

方案已按用户确认更新：不再使用心跳或 claim 完成设置页登记；改为依赖 #12 的独立幂等登记接口。

ila commented

2026-08-06 17:21:52 +08:00

依赖契约已由 #12 固化并提交：PUT /api/v1/client/registration，文档提交 02073ea。Client 实现继续等待 #12 Admin 接口和真实联调通过。

依赖契约已由 #12 固化并提交：`PUT /api/v1/client/registration`，文档提交 `02073ea`。Client 实现继续等待 #12 Admin 接口和真实联调通过。

ila referenced this issue

2026-08-06 17:21:54 +08:00

定义 Admin Gateway 并实现 Mock 契约 #10

ila commented

2026-08-06 17:42:48 +08:00

依赖 #12 已验收关闭；现开始实施 #11。将按已确认方案完成本地设置持久化、Gateway 登记契约、HTTP 实现、Qt Worker 线程与离屏测试。

ila commented

2026-08-06 17:58:34 +08:00

实施完成，等待验收

已完成本地设备号/设备名的原子保存；设备号只在缺失时生成。
已接入 PUT /api/v1/client/registration，通过 Qt Worker 后台登记；Admin 失败不回滚本地数据。
已实现 Mock 和标准库 HTTP Gateway；本机/LAN Admin 请求主动绕过系统代理，避免代理软件误拦截。
已覆盖 Repository、服务、Mock、HTTP 契约、事件、慢请求和窗口关闭场景。
Client 全量测试 48 项通过，Python 语法检查和 git diff --check 通过。
已用临时 Admin + 隔离 SQLite 完成真实端到端验证：重复登记记录数保持 1。

代码提交：fab5778

归档提交：9884444

本地归档：docs/task/11-保存当前设备并登记-client.md

工单保持打开，等待用户人工验收。

## 实施完成，等待验收 - 已完成本地设备号/设备名的原子保存；设备号只在缺失时生成。 - 已接入 `PUT /api/v1/client/registration`，通过 Qt Worker 后台登记；Admin 失败不回滚本地数据。 - 已实现 Mock 和标准库 HTTP Gateway；本机/LAN Admin 请求主动绕过系统代理，避免代理软件误拦截。 - 已覆盖 Repository、服务、Mock、HTTP 契约、事件、慢请求和窗口关闭场景。 - Client 全量测试 48 项通过，Python 语法检查和 `git diff --check` 通过。 - 已用临时 Admin + 隔离 SQLite 完成真实端到端验证：重复登记记录数保持 1。代码提交：`fab5778` 归档提交：`9884444` 本地归档：`docs/task/11-保存当前设备并登记-client.md` 工单保持打开，等待用户人工验收。

ila commented

2026-08-06 18:00:10 +08:00