cmshoppe/docs/tasks/T-701.md

id, title, phase, deps, status, created

id	title	phase	deps	status	created
T-701	新用户首次启动激活与使用引导	8	T-700	DONE	2026-07-23

问题 / 背景

当前强制订阅模式下，全新安装且尚未配置默认网关 API Key 的用户启动程序后，只会看到除“设置”外的业务 Tab 被禁用、界面自动切到设置页、状态栏提示“请先在设置配置 cmhub API Key”。普通用户需要自行理解 Base URL、API Key、cmhub 和订阅状态，也不知道去哪里获取 Key；配置成功后，程序也没有继续说明添加店铺、登录、导入商品和开始采集的顺序。

该流程可供开发人员测试，但不能支撑零基础新用户独立完成首次使用。首次启动应先解释“需要绑定会员账号”，只向普通用户索取必要的会员 API Key，并在验证成功后给出清晰的下一步。

方案

1. 内置默认网关公开地址

• 打包版和源码版为默认网关提供统一的内置 Base URL，首版使用 https://cm.833729.com；干净安装不再要求普通用户手工输入该地址。
• 默认值只用于配置缺失或空值，不覆盖已有用户保存的非空默认网关地址，也不修改自定义网关模型配置。
• 线上会员中心入口使用独立的、产品确认过的 HTTPS 常量，首版指向 https://cm.833729.com；不得根据 API 路径猜测或拼接会员中心地址。
• 设置页继续保留 Base URL 作为兼容和运维入口，但首次激活窗口不展示 Base URL、模型别名、超时等技术配置。

2. 首次激活窗口

• 启动升级检查和数据目录准备完成后，主窗口按现有异步流程检查订阅；检测到默认网关 API Key 缺失时，显示中文模态窗口“激活蝦皮圈优化助手”。
• 窗口只展示：
  • 简短说明：“首次使用需要绑定会员账号”；
  • 一个密码模式输入框“会员 API Key”，支持粘贴和显示/隐藏；
  • 本地保存提示，明确 Key 在输入框和设置页中打码显示，但按项目现状以本机明文配置保存；
  • “验证并开始使用”“前往会员中心获取 API Key”“退出程序”三个操作。
• “前往会员中心获取 API Key”使用系统默认浏览器打开经过固定 HTTPS 校验的官方地址，窗口保持打开；打开失败显示中文提示。
• 关闭标题栏等同“退出程序”，不得落入只有禁用 Tab、又没有行动指引的半完成界面。
• 验证期间禁用重复提交并显示“正在验证会员账号”；网络请求继续在 worker 中执行，不阻塞 GUI。

3. Key 验证、保存与错误恢复

• 激活窗口使用用户当前输入的 Key 直接请求既有 GET /api/v1/cmshopee/subscription/status，不得为了验证先把未经确认的 Key 写入磁盘。
• active 或 grace 验证成功后才保存 Key，复用现有订阅状态应用逻辑，恢复业务 Tab，并在原生窗口标题显示账号、套餐和有效期。
• Key 已通过身份验证但套餐为 required、expired、revoked 或账号不可用时，可以保存该 Key 供续费后重新检测，但继续保持门禁，并在激活窗口提供对应中文原因和会员中心入口。
• key_invalid 时不保存输入值，保持输入框可修改并明确提示“会员 API Key 无效”；网络失败或非法响应时不清空用户输入，允许重试，不得误报为套餐到期。
• Key、Authorization 请求头和完整原始响应不得进入日志、异常正文、状态栏、SQLite、测试快照或导出文件。
• 已有有效 Key 的存量用户不显示首次激活窗口，继续走 T-686/T-700 的启动检查、到期提示和重新检测流程。

4. 激活后的首次使用清单

• 首次激活成功后显示一次中文引导，按实际工作流列出：
  1. 添加蝦皮店铺账号；
  2. 启动 Chrome 并人工完成登录；
  3. 导入商品 Excel；
  4. 开始采集、AI 生成和更新蝦皮。
• 主操作“开始配置店铺”直接进入“账号管理”Tab；“稍后”不阻断使用，并在下次启动继续提示，直到用户明确完成引导或选择“不再提示”。
• 引导不得自动创建账号、自动登录、填写密码、启动批量任务或绕过 Shopee 验证码。

5. 文档与自动验证

• 更新 docs/04-architecture.md、docs/routes.md 和必要的打包文档，明确默认网关内置值、首次激活状态机、Key 保存时机及存量用户兼容边界。
• 扩展应用配置、订阅和 GUI 测试，使用临时数据目录和模拟接口覆盖首次启动、验证中、成功、无套餐、过期、Key 无效、网络失败、浏览器打开失败、退出和存量用户不弹窗。
• 所有自动测试不得请求真实订阅接口、写入真实 data/ 或包含可用 API Key。

验收要点

• 干净数据目录首次启动时，普通用户无需填写 Base URL，只看到“会员 API Key”激活窗口和明确操作。
• 未配置 Key 时不能进入业务 Tab；关闭激活窗口会正常退出，不停留在无说明的受限主界面。
• 点击“前往会员中心获取 API Key”只打开预设的官方 HTTPS 地址，不拼接接口路径。
• 验证过程不阻塞 GUI、不重复提交；有效或宽限状态保存 Key、启用工作区并显示账号、套餐和有效期。
• 无套餐、过期、撤销和账号不可用保持门禁并给出中文恢复路径；Key 无效和网络失败不写入错误凭据、不泄露敏感信息。
• 已有非空默认网关地址和有效 Key 的存量用户配置不被覆盖，也不出现首次激活窗口。
• 首次激活成功后出现四步使用清单，“开始配置店铺”进入账号管理；不执行自动登录或自动业务操作。
• 验证通过：
  • py -3.10 -m unittest discover -s tests -p test_appconfig.py
  • py -3.10 -m unittest discover -s tests -p test_subscription.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
  • git diff --check

边界（不改什么）

• 不实现客户端注册、登录、支付、订单、退款或套餐购买页面；会员业务仍在官方线上用户端完成。
• 不修改 cmhub 订阅接口路径、响应 schema、套餐规则或服务端最终授权。
• 不实现卡密、设备绑定、设备数量限制、自动续费或客户端本地硬授权。
• 不移除设置页的高级网关配置，不覆盖存量 Base URL、Key 或自定义模型。
• 不修改 AI 生成、商品套图、Chrome/CDP、采集、封面上传、拖拽排序或更新蝦皮逻辑。

执行记录

• 2026-07-23：根据零基础新用户首次启动体验评审创建任务。当前实现只自动切到设置并显示状态栏提示，缺少会员 API Key 激活入口、默认地址和激活后的工作流引导。
• 2026-07-23：内置默认网关和官方会员中心公开地址 https://cm.833729.com；配置缺失或空 Base URL 时使用默认值，已有非空地址保持不变。新增非敏感 onboarding.first_use_guide_state，空值不触发引导，避免存量用户被误判为新用户。
• 2026-07-23：新增 MembershipActivationDialog。缺少 Key 时只显示会员 API Key、显示/隐藏、本地明文保存说明、验证、会员中心和退出；关闭窗口等同退出。验证使用 worker 内存覆盖值，不提前落盘；Key 无效、网络失败或非法响应保留输入且不保存，服务端未拒绝凭据后才写入 data/config/cmhub.json。
• 2026-07-23：有效、宽限和旧服务兼容状态恢复业务 Tab；有效 Key 但未订阅、过期、撤销或账号不可用时保存 Key 供续费后重查，但激活窗口和业务门禁保持。首次激活成功后显示“添加店铺 → 人工登录 → 导入 Excel → 采集/生成/更新”清单，支持开始配置、稍后提醒和不再提示。
• 2026-07-23：同步 docs/04-architecture.md、docs/routes.md、docs/packaging.md；新增配置、订阅、激活窗口、凭据落盘边界、官方会员中心、首次引导和存量配置兼容测试。临时 Qt 截图验证窗口约 520×318，控件无几何重叠；本机测试环境缺少 Qt 字体目录，因此截图不用于中文字形验收。
• 2026-07-23：验证通过：py -3.10 -m unittest discover -s tests（699 项）、py -3.10 -m ruff check app tests main.py、py -3.10 -m compileall app main.py、git diff --check。自动测试只使用临时目录和模拟订阅结果，未请求真实接口、未写入真实 data/、未使用真实 API Key。