docs(tasks): add first-run activation onboarding
This commit is contained in:
chengma
@@ -0,0 +1,90 @@
|
||||
---
|
||||
id: T-701
|
||||
title: 新用户首次启动激活与使用引导
|
||||
phase: 8
|
||||
deps: [T-700]
|
||||
status: TODO
|
||||
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 激活入口、默认地址和激活后的工作流引导。
|
||||
Reference in New Issue
Block a user