--- id: T-701 title: 新用户首次启动激活与使用引导 phase: 8 deps: [T-700] status: DONE created: 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。