T-685 阶段一设备登记与会话观测

问题 / 背景

商业授权方案的当前权威实施顺序要求先验证“哪个桌面安装实例正在为哪个 cmhub 账号使用”，再启用套餐强制。当前桌面端只保存普通 cmhub API Key；所有请求没有设备会话，无法统计设备稳定性、旧版本占比、复制配置或换机风险。

阶段一是观测与兼容阶段：已有 API Key 继续承担 cmhub 身份和点数计费；设备会话只提供设备上下文。设备登记、会话刷新或心跳失败不得中断当前生文、生图、商品套图、轮询和下载，也不得要求用户输入卡密或账号密码。

cmhub 需先提供并冻结以下产品接口契约后才可实施：

POST /api/v1/client/devices/register
POST /api/v1/client/devices/heartbeat
X-Device-Session 的有效期、刷新条件、错误码和产品接口接受范围

方案

1. 本机设备状态

新增桌面端设备身份与安全存储模块。首次运行生成高熵随机 install_id，以 product_code + install_id 派生版本化设备摘要 v1:<hash>；不上报、记录或展示原始 install_id。
使用 Windows DPAPI 按当前 Windows 用户保护 install_id、device_session_token 和会话过期时间。敏感状态存入独立受保护文件，不混入 config.json、cmhub.json、SQLite 普通字段、任务快照或日志。
不读取或上传原始 MachineGuid、MAC、磁盘序列号。MachineGuid 风控摘要属于服务端后续可选能力，不是本任务的桌面端认证依据。
DPAPI 只支持 Windows；测试环境通过可 mock 的适配层验证。无法读取或写入受保护状态时按“未登记旧客户端”继续运行，写入脱敏诊断并采用退避重试，不生成临时不稳定 device_id。

2. 注册、会话与心跳

应用启动后异步执行设备登记，不阻塞数据目录检查、强制升级、Chrome 检测、数据库初始化或主窗口显示。
登记请求沿用当前 Bearer cmhub API Key 身份，提交 product_code、版本化设备摘要、device_id_version、client_version、平台；不得提交用户 ID、原始机器标识、API Key 到请求体或 URL。
成功后安全保存短期 device_session_token 与过期信息；会话临期、应用启动和每日首次使用时后台刷新。心跳/刷新需节流，同一安装实例 24 小时内不得为普通生成高频重复写 last_seen。
当有有效会话时，cmshopee 产品相关 cmhub 请求统一附加 X-Device-Session 与 X-Client-Version；没有会话或服务端尚未开放设备接口时保留现有请求方式并标记 legacy_client 观测路径。
请求头组装必须集中在 cmhub 客户端边界，覆盖标题、封面 submit/poll、AI帮写、商品套图 submit/poll/继续查询、模型目录和余额查询；图片 CDN 下载不携带设备会话。不得通过散落的各 worker 手工拼接。

3. 用户体验、诊断与安全

阶段一不新增卡密激活弹窗、不阻断按钮、不显示“无授权”错误；必要时仅在状态栏以低干扰中文提示“正在登记本机设备”或“设备登记稍后重试”。
不在设置页、运行日志、SQLite、诊断日志、异常回包或 URL 中展示设备摘要、会话令牌、旧 API Key、DPAPI 密文或本地文件路径。
把可聚合事件写入脱敏诊断：登记成功/失败分类、会话刷新、使用旧兼容路径；不记录原始响应。阶段一不新增本地设备管理、解绑、套餐、卡密、网页支付或权益展示 UI。

验收要点

首次启动生成稳定的版本化设备摘要并以 DPAPI 保存本机状态；同一 Windows 用户重启后摘要稳定，复制数据目录到另一用户/设备不能直接读取敏感状态。
登记、会话刷新与每日心跳均在后台执行；成功请求包含所需产品字段，正常 cmhub 调用带 X-Device-Session 和 X-Client-Version。
设备服务不可用、网络抖动、会话过期、DPAPI 失败和旧 cmhub 服务返回未知接口时，现有托管生成、已有异步任务轮询/下载与本地功能不中断。
标题、封面、AI帮写、商品套图、模型目录和余额的产品请求不会遗漏有效设备会话；图片 CDN 下载不携带该头。
所有设备相关日志、状态和错误均为中文且不含会话令牌、API Key、原始设备标识或 DPAPI 密文。
当前 direct 自定义网关路径在阶段一保持现状，不被误改为授权强制；正式 BYOK 代理与 direct 移除留给后续任务。

测试与文档

新增 tests/test_device_identity.py、tests/test_device_session.py：DPAPI 适配 mock、稳定身份、无法解密降级、登记幂等、会话刷新/心跳节流、无服务兼容和日志脱敏。
扩展 tests/test_ai.py、tests/test_image_studio_generation.py、tests/test_gui.py：统一请求头覆盖、图片下载排除、启动非阻塞与用户可见中文状态。
更新 docs/04-architecture.md、docs/routes.md 的设备会话边界、受保护本地状态、阶段一兼容策略与接口契约；同步 Obsidian 方案的接口实测结果。

验证

py -3.10 -m unittest tests.test_device_identity tests.test_device_session tests.test_ai tests.test_image_studio_generation tests.test_gui
py -3.10 -m unittest discover -s tests
py -3.10 -m ruff check app tests main.py
py -3.10 -m compileall app main.py
git diff --check

边界（不改什么）

不实现卡密、激活、套餐、权益、设备席位、解绑、续费、支付、离线权益令牌或服务端授权强制。
不把 DeviceSession 当作用户身份或计费身份；Bearer API Key 和既有点数账本保持原职责。
不修改 cmhub 通用 API 的全局鉴权，不阻断未升级客户端，不要求用户重新填写 API Key。
不改变 direct 自定义网关、BYOK 代理、图片异步协议、Chrome/CDP、采集或更新蝦皮逻辑。

关联

Obsidian《卡密设备绑定与套餐授权方案》§6.3、§6.9：阶段一设备观测及最终身份边界。
T-544：既有启动升级检查；设备登记不得阻塞该流程。
T-678/T-679：现有自定义网关与商品套图来源；阶段一只观测，不提前改变其执行路径。

执行记录

待 cmhub 设备接口契约冻结后实施。

6.4 KiB Raw Blame History