feat(subscription): add membership access preflight

docs/04-architecture.md

@@ -25,6 +25,7 @@ GUI（PySide6 QTabWidget，当前显示 6 Tab）
   ├── cdp        CDP 客户端（连接、找/开 tab、执行 JS、拖拽）
   ├── editor     登录检测 / 检测商品状态 / 采集旧标题旧封面 / 改标题 / 换封面 / 点更新
   ├── product_status  商品状态代码、显示和分组规则
+  ├── subscription  cmhub 账号订阅状态查询、响应归一化与客户端预检状态
   ├── ai         文本生成（提示词+旧标题→新标题）/ 图像生成（提示词+旧封面→新封面）/ 商品原图理解（商品套图AI帮写）
   ├── image_studio          商品套图项目/资产/job数据服务（兼容旧AI工场终选）
   ├── product_suite         套图设置归一化、数量计算、完整提示词与job规划
@@ -78,6 +79,7 @@ imported  →  collected  →  generated  →  applied
 - `cdp`：连接调试端口、找/开 tab、执行 JS、拖拽、注入文件。
 - `editor`：登录检测、读取商品状态、**采集**（读旧标题、下载旧封面）、改标题、换封面、点更新。
 - `product_status`：商品状态代码 `normal/unlisted/reviewing/unknown` 的归一化、中文显示、EDS 提示分类和下游任务分组；①②③只能复用该模块，不各自判断。
+- `subscription`：使用 cmhub API Key 查询 `GET /api/v1/cmshopee/subscription/status`，把远端权益结果归一化为有效、宽限、未订阅、到期、撤销、账号不可用、Key 无效、暂时不可用或旧服务兼容状态；不保存、展示或记录 API Key，服务端始终是最终授权方。
 - `ai`：`gen_title(prompt, old_title)`、`gen_cover(prompt, old_cover_path)`、`analyze_product_images(instruction, context, image_paths)`；前两者分别负责②标题/生图，后者只供商品套图中的「AI帮写」调用 cmhub 图片理解接口，读取1至8张按 `source_order` 排序的本地商品原图并返回可编辑卖点与白名单计费元数据。
 - `cmhub_models`：格式化 cmhub 模型别名，并维护仅进程内有效的短期模型目录缓存；缓存键使用规整网关地址和别名，不含 API Key，不写入配置、SQLite、日志或导出文件。
 
@@ -86,6 +88,7 @@ imported  →  collected  →  generated  →  applied
 - 应用配置（模型选择、生成参数、目录、Chrome 路径）→ `data/config.json`。
 - AI 模型清单（direct 内部兼容模式 url/模型/密钥/类型/连接超时）→ `data/config/ai_models.json`（API Key 本地明文保存，必须 gitignore，UI 打码显示；普通设置页不再暴露 direct 切换入口）。
 - cmhub 网关 Key → `data/config/cmhub.json`，schema `{ "api_key": "..." }`；`config.json` 只保存 Base URL、别名和超时，不保存 Key。
+- 订阅状态 → 仅进程内 `SubscriptionStatus`；顶部 GUI 只展示服务端返回的账号显示名、套餐名和有效期，不写入 SQLite、诊断日志或导出。`404` 表示服务端尚未启用订阅接口，客户端保持旧行为；网络异常不被误判为会员到期。
 - cmhub 模型目录与 AI帮写/正式套图预估价格 → 仅内存短期缓存；预估值只供用户确认，实际扣点仍以网关响应 metadata 为准。
 - 业务数据（账号、任务、各阶段结果）→ SQLite `data/cmshopee.db`。
 - 图片（采集的旧封面、AI 生成的新封面）→ `data/images/`（路径记在 DB）。

docs/routes.md

@@ -25,6 +25,14 @@
 
 创建六个业务Tab之前先请求版本接口。服务端明确要求强制升级时，不创建 `MainWindow`，而是显示「必须升级」模态进度窗口：用户点击「立即升级」后可看到下载、校验、准备新版和重启阶段，以及百分比和字节数；运行中可「取消并退出」，失败后可重试。校验完成后软件启动安装目录外的独立更新器并退出，更新器替换程序后自动重启新版。版本接口完全不可达或非法时仍失败放行；一旦已明确强制，元数据缺失或后续失败都不允许进入旧版主界面。
 
+## 会员订阅接入
+
+- 强制升级检查完成、主窗口显示后，后台用 `data/config/cmhub.json` 的 API Key 请求 `GET /api/v1/cmshopee/subscription/status`；不会阻塞 Qt 主线程或把 Key 放入 URL、状态栏、日志和错误提示。
+- 状态接口已启用时，未配置 Key、Key 无效、账号禁用、未订阅、到期、撤销或暂时无法确认会员状态，主窗口只保留「设置」Tab，并在顶部显示中文原因；用户可打开设置重填 Key、按服务端返回的 `manage_url` 用默认浏览器前往线上会员中心，或退出。已接受的异步任务、本地数据和导出不删除。
+- 订阅有效时，应用顶部标题区域右侧显示“账号名 · 套餐名 · 有效至日期”；宽限期显示宽限截止日。不得把长会员文本拼进 Windows 原生窗口标题，也不得展示 API Key。
+- 当前服务端未部署订阅接口时，`404` 视为旧服务兼容：顶部显示“会员服务尚未启用”，六个工作流继续按旧行为运行，不弹阻断窗口。网络或格式错误显示“暂时无法确认会员状态”，不能误报为 Key 无效或会员到期。
+- ② AI生成、⑥商品套图和「AI帮写」的每次新提交均读取同一订阅预检状态；客户端预检只改善体验，cmhub 产品接口仍必须服务端最终裁决。已提交的异步任务继续查询、下载和查看。自定义网关直连同样做客户端软校验，不能作为不可绕过的授权保护。
+
 ## 全局 Tab 栏可用性
 
 当前 6 个主 Tab 是高频导航入口，不能使用 Qt 默认的紧凑宽度。`MainWindow` 必须为 `QTabWidget/QTabBar` 设置基础样式：
@@ -110,6 +118,7 @@
 - 筛选行提供「打开图片文件夹」按钮，用于只读打开本地图片目录：选中某行时打开该商品所在账号图片文件夹（优先打开已有新/旧封面文件的真实父目录，缺失时回退到规范账号目录）；未选行且选择具体批次时打开该批次图片文件夹；未选行且为全部批次时打开图片根目录。目录不存在只中文提示，不自动创建目录，不修改任务状态。
 - 右下：任务列表（店铺名、商品id、旧标题、新标题、标题状态、图片状态）+ AI生成运行日志；标题/图片状态由 `new_title`、`new_cover_path`、`stage/status` 和失败步骤推导，帮助用户区分“标题未生成 / 图片未生成 / 标题成功但图片失败”。商品ID列按原等分宽度约 50% 显示；标题状态和图片状态列在 T-554 基础上再缩到约 33%，缩出的宽度平均给旧标题和新标题。已生成、未提交线上、非运行中的任务可双击「新标题」列本地微调，写回 `tasks.new_title`，清空 `last_error` 并回到可更新；双击其他列弹窗展示旧封面、新封面和历史候选图。
 - 底部**单个「开始生成」+「停止」**，并增加「生成内容」下拉：默认只生成标题，可选只生成封面或生成标题和封面；只生成封面不调用生文，有新标题时优先使用，没有时用已采集旧标题作为封面prompt参考，新旧标题都为空才不纳入。开始前先从真实候选重新分组商品状态，弹出与①共用的纵向范围确认框：默认「生成架上商品」（即仅检测结果为正常的商品），「生成全部商品」为警示橙色描边，还会处理未上架、审核中、状态未知商品，可能额外消耗点数；未上架、审核中、状态未知默认不入队、不请求 AI、不消耗点数，用户明确选择全部范围才可入队。商品状态功能上线前的历史空状态会启动时迁移为默认正常；上线后仍为空的记录按未知处理。范围确认不跨轮记忆，取消或候选在确认期间变化均不启动生成；无异常候选时该警示选项禁用。标题/图片两条进度条右侧分别显示同宽用时标签（`生标题用时 N 秒` / `生图用时 N 秒`），运行中每秒递增，完成/停止后冻结；原图片进度条右侧的失败数和 cmhub 余额不再占用该位置。cmhub 模式会把用户设置的图片并发内部限制到最大 5，并用同样最大 5 的独立下载线程池拉取 `image_url`，不新增用户可见下载并发配置；运行日志显示用户设置并发和实际并发。下拉状态持久化到 `config.json` 的 `ai.generate_mode`，并继续写回旧兼容 `ai.generate_cover`。
+- 点击「开始生成」还会先读取主窗口已验证的会员状态。未订阅、到期、Key 无效或状态暂时无法确认时不创建 `GenerateWorker`，引导到⑤设置或线上会员中心；旧服务订阅接口尚未启用时保持原有生成行为。
 - 生成参数（标题/图片并发数、失败重试、分辨率、jpg 质量、cmhub 网关/Key/别名）在 **设置**；②只暴露本轮生成标题/封面/图文的内容模式。设置不新增“下载并发”控件；cmhub 图片下载并发由程序按实际生图并发自动计算，最大 5。
 - 只生成标题时标题成功即写库并进入 `generated`，保留已有封面；只生成封面时通过组件级写库只保存 `new_cover_path`，不覆盖已有标题，也不把旧标题写入空的 `new_title`；生成标题和封面时按缺失组件增量补齐。“有新封面、无新标题”时标题状态为待生成、图片状态为已生成，后续补标题不重复生图。三种模式都写 `run_type=generate` 的 `run_logs/run_log_events` 和用户可读滚动日志；日志开头明确显示本轮生成内容。点击「开始生成」时先清空②界面可见日志并写入本轮开始摘要，运行中只追加本轮日志；不删除历史 `run_logs/run_log_events` 或本地 `data/logs/`。进入页面默认可显示“本轮日志会在开始运行后显示”，历史日志不自动混入当前运行界面。「停止」取消未开始项，可再次「开始生成」对剩余继续。即使用户通过商品状态筛选查看异常商品，也必须在范围确认框主动选择「生成全部商品」才会入队；默认「生成架上商品」不会因筛选而放宽。
 - 「重置生成结果」支持选中任务或当前筛选结果，运行中禁用；确认框提供「重置标题 / 重置封面 / 重置全部」，只改本地 DB，默认不删除本地新封面文件。若范围内包含已提交线上记录，必须提示本地重置不回滚蝦皮，重生成后再更新会再次提交线上。
@@ -223,6 +232,7 @@
 - AI帮写提交图片理解前先显示「开始AI帮写」确认框：按 `source_order` 说明会理解当前商品前1至8张可用原图并生成商品卖点与要求。模型目录只走后台读取或进程内短期缓存；仅当前图片理解别名有唯一无条件价格时显示「预计扣点：X 点」，否则明确实际以网关返回为准。确认框默认、Esc 和关闭均取消，不提交图片；开始后可取消本地等待，但已提交网关的请求仍可能产生扣点。预估不写入业务数据，完成后仍只显示接口返回的实际扣点和余额。
 - 常规「生成套图」保留“已有成功历史”优先确认，选择继续后才后台读取或复用同一模型目录缓存，并显示正式生成确认。确认严格按最终 planned `specs` 展示各分类实际张数、总张数和比例；逐图主图开启时明确白底图只用第一张原图，其他分类按每张原图生成；关闭时所有分类使用第1张主图及同一批冻结参考图。仅唯一无条件的生图价格显示预计单张和总扣点，总价只按 `len(specs)` 计算；价格未知时不显示数字。默认、Esc、关闭、切换任务、取消读取或计划变化均不创建生图 job；单图失败重试和恢复未完成任务不增加这一层批量确认。
 - 商品套图只管理本地图片资产，不自动上传或修改蝦皮；③线上更新边界不受影响。旧 `ImageStudioTab` 留作代码兼容但不再作为主窗口入口。
+- 「AI帮写」和「生成套图」在新提交前共用主窗口会员预检；默认网关或自定义网关直连都一样。继续查询已提交默认网关任务、下载、预览、历史查看和导出不属于新提交，不因会员状态变化中断。
 
 ## 流程导航
 
@@ -246,7 +256,7 @@
 
 | 组件 | 归属 | 说明 |
 | --- | --- | --- |
-| `MainWindow(QMainWindow)` | 根窗口 | 持有 `QTabWidget`、状态栏、全局消息 |
+| `MainWindow(QMainWindow)` | 根窗口 | 持有 `QTabWidget`、状态栏、顶部会员状态、订阅受限恢复入口和全局消息 |
 | `CollectTab(QWidget)` | ① | 导入、任务表、采集、回写 |
 | `GenerateTab(QWidget)` | ② | 左提示词管理 + 右筛选/任务列表；双击看新旧封面；先确认商品状态生成范围，再按本轮「生成内容」下拉接入 `GenerateWorker` |
 | `ApplyTab(QWidget)` | ③ | 已生成任务筛选 +「更新内容」下拉 + 商品状态优先/内容完整性预检剔除 +「检查本轮更新」+ 分批开始更新确认 + 检查/真实更新运行日志 + 结果回写与结束汇总 |
@@ -257,6 +267,7 @@
 | `BaseWorker(QObject)` | 后台 | 定义 `progress/log/row_updated/failed/finished/cancelled` signals |
 | `ApplyWorker(BaseWorker)` | ③ | 账号就绪预检、检查本轮更新、按每批最大条数分批、按账号并行或串行调用 `editor.apply_task(...)`、逐条 `set_applied()`，失败继续，写运行日志；执行层再次拒绝非正常商品状态 |
 | `AIModelTestWorker(BaseWorker)` | 设置 | 后台调用 `appconfig.test_ai_model()` 测试模型连接 |
+| `SubscriptionCheckWorker(BaseWorker)` | 根窗口 | 后台查询 cmhub 账号订阅状态；结果只通过 signal 回主线程更新会员标签和工作流可用性 |
 | `WriteBackWorker(BaseWorker)` | ①③ | ①回写旧字段；③回写新标题/新封面/更新状态 |
 | `ImageStudioPullImagesWorker / ImageStudioDownloadOriginalWorker / ProductSuiteImportImagesWorker / ProductSuiteGenerateWorker / ProductSuiteAiWriteWorker / CMHubModelCatalogWorker` | 商品套图 | 后台执行只读拉主图、远程原图下载、本地图片校验复制、默认网关异步或自定义网关同步套图生成、AI帮写和只读模型目录；拉图和本轮下载支持安全边界协作停止，worker 不直接操作 QWidget |
 

docs/tasks/T-686.md

@@ -3,7 +3,7 @@ id: T-686
 title: 会员订阅状态接入与启动访问门禁
 phase: 8
 deps: []
-status: TODO
+status: DONE
 created: 2026-07-21
 ---
 
@@ -59,7 +59,10 @@ cmhub 需提供 `GET /api/v1/cmshopee/subscription/status`。2026-07-21 无凭
 ## 验证
 
 ```bash
-py -3.10 -m unittest tests.test_subscription tests.test_ai tests.test_image_studio_generation tests.test_gui
+py -3.10 -m unittest discover -s tests -p test_subscription.py
+py -3.10 -m unittest discover -s tests -p test_ai.py
+py -3.10 -m unittest discover -s tests -p test_image_studio_generation.py
+py -3.10 -m unittest discover -s tests -p test_gui.py
 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
@@ -82,3 +85,5 @@ git diff --check
 ## 执行记录
 
 - 2026-07-21：任务创建；cmhub 订阅状态接口尚未上线，需在实现中保持 `404` 旧服务兼容。
+- 2026-07-21：新增 `app/subscription.py` 和 `SubscriptionCheckWorker`，复用 cmhub 共享 HTTP 会话查询订阅状态；主窗口在显示后异步检查，顶部显示账号/套餐/有效期，受限状态只保留设置恢复入口。② AI生成、⑥商品套图和 AI帮写的新提交接入同一预检，旧服务 `404` 放行既有工作流。
+- 2026-07-21：验证通过：`py -3.10 -m compileall app main.py`、`py -3.10 -m ruff check app tests main.py`、订阅/应用配置/AI/套图/GUI 定向测试，以及 `py -3.10 -m unittest discover -s tests`（664 项）。无凭据请求线上订阅状态接口返回 `404`，已由单测和运行时兼容分支覆盖；服务端上线后需使用测试 API Key 做一次真实有效/到期/未订阅联调，不属于本仓库可完成的接口发布工作。