cmshoppe/docs/02-requirements.md

# 需求

> 本文只描述**要什么**与**怎么算达成**，用产品 / 用户语言表达，**不涉及技术实现**。
> 技术方案、数据结构、CDP 细节见 [架构设计](04-architecture.md)。

## 一、业务现状

| 项 | 状态 |
| --- | --- |
| 用户 | 电商运营，手动在多个 Shopee 卖家账号下逐个改标题、换封面，效率低 |
| 数据 | 商品数据在 Shopee 卖家中心；本工具不落库，只在浏览器页面上操作 |
| 现有系统 | 已用 CDP 验证单账号流程（改标题、上传图、拖拽换封面、可选更新），见 `current-state.md` |
| 约束 | 依赖真实 Chrome 与已登录态；受 Shopee 页面结构、限流、风控影响；首次登录需人工 |

## 二、用户角色

- **运营操作员**：配置账号、为账号登录、对选定商品执行改标题/换封面。
- **未登录账号**：已在配置中但其 user-data-dir 尚未登录 Shopee；执行任务前必须先人工登录。

## 三、功能清单

### V0 已验证原型（单账号最小闭环）

| 功能 | 用户能做什么 | 优先级 |
| --- | --- | --- |
| 账号配置 | 在 GUI 里新增/编辑/删除 1 个或多个 Shopee 账号（名称、地区、备注） | P0 |
| 绑定配置目录 | 为每个账号在项目 `chrome_user_data_dir/<账号标识>` 下创建并绑定独立 user-data-dir | P0 |
| 启动并登录 | 一键用某账号的 user-data-dir 启动 Chrome（带调试参数），首次人工登录 Shopee 后登录态持久化 | P0 |
| 生成快捷方式 | 可选：为每账号生成桌面快捷方式，目标带该账号 user-data-dir，供手动打开对应账号 Chrome | P1 |
| 加载商品页 | 选定账号，用其已登录 Chrome 打开指定商品详情页 | P0 |
| 改标题 | 对该商品按规则修改标题（如去掉结尾若干字 / 指定新标题） | P0 |
| 换封面 | 上传一张本地图片，自动设为商品封面（满 9 张时必须先确认本地旧封面备份存在，再删原封面并上传） | P0 |
| 提交更新 | 在显式确认后点击「更新」，把改动提交到线上；原型脚本默认不提交 | P0 |

### V1 当前目标（多账号 + Excel + AI，5 Tab 流水线）

5 个 Tab，顺序：① 导入采集 → ② AI生成 → ③ 更新蝦皮 → ④ 账号管理 → ⑤ 设置。

| 功能 | 用户能做什么 | 优先级 |
| --- | --- | --- |
| 账号管理（④） | 增删改账号：账号名/别名/地区/数据目录/端口/密码（本地明文仅参考，UI 打码）/备注；登录状态；启动登录、检测登录。检测登录必须把 `accounts.shopee.tw/seller/login` 这类 Shopee accounts 登录页明确判为未登录 | P0 |
| 导入（①） | 导入多个 Excel，按模板解析输入列（账号名/别名/商品id）为任务列表 | P0 |
| 导入校验汇总（①） | 导入后展示文件数、解析行数（原始数据量）、有效/无效行、匹配账号行数（按账号细分）、未匹配行数；跑采集前先纠错 | P0 |
| 采集旧数据（①） | 程序只读打开商品页，抓取旧标题、下载旧封面到本地，回写 Excel 旧字段 | P0 |
| AI 生成（②） | 输入标题/封面提示词，按②本轮「生成内容」下拉选择只生成标题、只生成封面或生成标题和封面；只生成封面要求任务已有新标题，避免用户无意产生图片模型成本；②任务表格拆分显示「标题状态 / 图片状态」，商品ID列缩窄约 50%，状态列再缩到当前约 33%，多出的宽度平均给旧标题和新标题；标题/图片两条进度条右侧分别显示生标题/生图实时用时秒数；点击「开始生成」时清空②界面旧日志，只显示本轮生成日志，历史 run_logs 仍保留 | P0 |
| 提示词管理（②） | 标题提示词「保存」到 `data/title_prompt.txt` 并启动回显；封面提示词多模板（下拉 + 新建/保存/另存为/重命名/删除）+ 插入 `{新标题}` + 预览（变量替换） | P0 |
| 查看对照（②） | 双击任务弹窗查看旧封面、新封面和历史候选图；可在弹窗内对当前行「重置图片」，退出后用状态筛选「待生成」批量补生成封面；不在弹窗内启动单条生图 | P0 |
| 更新蝦皮（③） | 按批次/店铺/状态筛选；③左下角「更新内容」下拉选择只更新标题、只更新封面或更新标题和封面；点击「开始更新」前先校验所选内容已生成，缺失则中文弹窗阻断且不打开 Chrome；确认后对当前筛选出的已生成任务按每批最大条数分批更新蝦皮商品并点「更新」提交线上；普通正式更新不再受测试商品 ID 限制，可批量更新真实商品；可按状态=失败重试 | P0 |
| 检查本轮更新 / 运行日志 / 多账号并行（③/⑤） | ③ 提供「检查本轮更新」按钮，不打开 Shopee、不提交、不改任务状态，只显示当前筛选范围、店铺分布、预计分批、更新内容和会更新字段；点击「检查本轮更新」或「开始更新」时清空③界面旧日志，只显示本轮检查/更新日志；真实更新写运行日志；可在⑤开启多账号并行，同账号内仍串行 | V2 已接入，检查按钮已接入 |
| 结果存储与回写 | 各阶段结果实时存 SQLite；该文件全部完成后把旧/新数据+状态批量回写原 Excel | P0 |
| 设置（⑤） | AI 模型管理（下拉+新增/删除/详情/测试连接，至少各一个文本+图像模型）；标题/图片大模型角色选择；分辨率(512/1k/2k/4k，普通默认 cmhub 模式下只控制生图尺寸，返回超时只读展示实际口径：标题 600 秒 / 图片 900 秒；direct 兼容路径仍按分辨率映射)；并发/重试/jpg质量，其中 cmhub 生图请求与图片下载实际并发最大 5，超过后内部限流且运行日志展示实际并发；图片目录/Chrome 路径/端口；设置页采用居中内容区、适度左右留白和响应式三列表单，长字段跨列显示；点击「保存设置」成功后弹轻量提示框 | P0 |
| 首次引导保护 | 未配账号、对应账号 Chrome 未启动或未登录时，① ③ 执行按钮禁用/执行前拦截并提示去④；③ 不自动打开缺失账号 Chrome，必须中止本轮更新 | P0 |

### 后续迭代

| 功能 | 描述 | 阶段 |
| --- | --- | --- |
| 标题规则模板 | 预设多种改标题规则（前缀、替换、截断等） | V3 |

## 四、核心用户故事（V1）

1. 作为运营，我打开工具后能看到已配置的账号列表，并能新增一个账号。
2. 我为某账号点击「启动并登录」，工具用它专属的配置目录打开 Chrome，我手动登录一次 Shopee 卖家中心。
3. 之后我选中该账号、填入商品 ID，工具自动打开该商品详情页（带登录态）。
4. 工具自动把标题改成目标值，并上传我指定的图片、把它拖到第一位设为封面。
5. 我在 ③ 按批次/店铺/状态筛选已生成任务，点击「开始更新」后看到批量确认弹窗；若本轮需要的账号 Chrome 未启动或未登录，工具先列出账号并中止；确认且账号均就绪后工具逐条提交线上，取消则不执行。
6. 当账号尚未登录、商品页加载失败、商品 ID 已失效或封面已满 9 张时，工具给出明确提示并安全处理；若 Shopee 只弹出短暂错误 toast，工具应自动捕获并展示该错误文案。

## 五、验收标准（V1）

- **账号配置**：新增/编辑/删除账号后，配置持久化到本地文件，重启工具仍在。
- **绑定配置目录**：每个账号对应唯一的 `chrome_user_data_dir/<账号标识>` 目录；不同账号互不共用、不串号。
- **启动并登录**：点击后 Chrome 用对应 user-data-dir 启动并开启调试端口；人工登录一次后，再次启动无需重新登录。
- **加载商品页**：选定账号执行时，能用该账号登录态打开目标商品详情页，标题框与图片管理器渲染就绪；若商品 ID 失效、无权限或店铺不匹配导致详情页无法就绪，工具能显示 Shopee toast 错误文案并写入运行日志，而不是只报等待超时；若该失败发生在程序自动新建的商品 tab 内，失败后应自动关闭该 tab，复用用户原本打开的 tab 不关闭；①列表仅在明确捕获商品失效类 toast 时显示“商品失效”，其他加载失败仍显示“失败”。
- **改标题**：写入后标题框 `value` 与 `modelvalue` 均等于目标值（确认页面模型已更新）。
- **换封面**：上传成功后图片张数 +1（满 9 张时先确认旧封面本地备份存在，再删第一张并上传；备份缺失则拒绝删除）；目标图被拖到第一位成为封面。
- **提交更新**：③ 点击「开始更新」后必须弹窗确认本次筛选范围和任务数量；真实提交前必须检查本轮需要的账号 Chrome 已启动且已登录，缺失则弹窗列出账号并中止本轮、不自动打开 Chrome；用户确认且账号就绪后才逐条点「更新」，按钮禁用则不点并记录失败原因。
- **安全**：任意失败路径不崩溃、不误删、不在缺少批量确认的情况下提交线上。

## 六、范围边界与决策

| 问题 | 决策 |
| --- | --- |
| 第一版平台 | Windows 桌面（Chrome 与各 user-data-dir 同机） |
| 多账号隔离方式 | 每账号独立 user-data-dir（非 Chrome profile）；理由见 [架构 3.0](04-architecture.md) |
| 是否需要账号 | 是；管理多个 Shopee 卖家账号，但登录由人工首次完成 |
| 存储 | 应用设置用 `config.json`；账号/任务/结果用 SQLite；Excel 读写用 openpyxl |
| 账号↔任务绑定 | 以 Excel“别名”列为权威（非文件名）；匹配不到的略过并最后弹窗汇总 |
| 是否提交更新 | ③ 点击「开始更新」后弹窗确认；确认后对当前筛选结果逐条点「更新」提交线上；无常驻提交开关、无逐条人工审核 |
| 执行方式 | 默认多账号串行；⑤ 可开启多账号并行，不同账号可同时跑、同账号内仍串行；③ 按当前筛选结果全部更新，普通正式更新不再以测试商品 ID 阻断，超过每批最大条数时自动分批；单条失败继续 |
| 更新前账号就绪 | ③ 真实更新前检查当前筛选结果需要的账号；Chrome 未启动、CDP 端口不可达或未登录时整体中止并提示去④，不静默自动启动账号浏览器 |
| 旧标题/旧封面 | 程序在「采集」阶段改前抓取的快照（输出列），运营不填 |
| 新标题/新封面 | AI 生成（输出列），直接用于 ③；不设逐条确认阶段，本地留档+回写 Excel 供追溯 |
| AI 服务 | 文本+图像生成；普通产品默认 cmhub 网关，Key 本地明文存于 `data/config/cmhub.json`；direct 兼容清单存于 `data/config/ai_models.json`；首次保存/变更时提示，UI 打码、不入日志；见 [技术栈](03-tech-stack.md) |
| 本地图片 | 旧封面下载、新封面生成存本地图片目录，路径记 DB |
| 结果落库时机 | 各阶段处理完立即写 SQLite；该 Excel 全部完成后批量回写原文件 |
| 原文件被占用 | 回写时若原 Excel 被锁定，提示关闭重试或另存副本（SQLite 为事实来源） |
| 暂不支持 | 自动登录、爬取 |

## 七、待确认 / 风险点

- **账号 / 凭证风险**：登录态存在各账号 user-data-dir，等同账号凭证；目录不得提交版本库、不得外传。
- **本地敏感文件风险**：Tab④ 的密码本地明文存于 SQLite，仅供人工参考，**绝不自动登录/自动填**；AI Key 本地明文存于 `data/config/cmhub.json` 或 direct 兼容的 `data/config/ai_models.json`；首次保存/变更密码或 API Key 时必须提示“本地明文保存”；`data/` 整体必须 gitignore，旧布局 `config.json`、`config/ai_models.json`、`cmshopee.db`、`chrome_user_data_dir/`、`images/` 也继续 gitignore 以支持迁移；UI 打码、日志/导出脱敏（见 [任务 T-503](06-tasks.md)）。
- **别名匹配风险**：别名以 Excel 列为准；不匹配的行略过并最后弹窗，执行起始在日志逐条打印「文件→匹配账号」留痕，防误改。
- **AI 主图风险（高，已知并接受）**：本设计不设逐条人工审核和常驻提交开关；AI 生成的标题/封面经 ③ 批量确认后会提交线上。主图若失真/夸大/侵权可能违反 Shopee 规则甚至下架。缓解：开始更新前弹窗确认筛选范围和任务数量，新图本地留档 + 回写 Excel 供事后追溯；强烈建议先在测试商品验证再批量。
- **AI 成本与依赖**：接入文本+图像 AI = 新外部依赖 + API 费用 + Key 管理；服务商/模型/合规待 [技术栈](03-tech-stack.md) 确认。
- **AI Key 安全**：Key 本地明文存于 `data/config/cmhub.json` 或 direct 兼容的 `data/config/ai_models.json`，保存/变更时提示，UI 打码，不写日志，不提交版本库。
- **第三方平台风险**：Shopee 页面结构、class 名、接口随时可能变；限流、风控、封号风险存在，禁止高频批量。
- **自动化边界风险**：③ 确认后会自动改标题、上传图片、拖拽并点「更新」提交线上；点「开始更新」并确认前需自行确保筛选范围、任务来源与 AI 产出可接受。
- **检查边界**：③「检查本轮更新」只检查当前筛选任务并写运行日志，不打开 Shopee、不点击更新、不改任务状态；点击「开始更新」并确认后才可能真实提交。
- **多账号并行风险**：⑤ 开启多账号并行后，不同账号可同时执行更新；同一账号内仍串行。执行前检查本轮账号调试端口，端口冲突时阻断真实更新。
- **合规风险**：仅在自有/授权账号上操作；遵守 Shopee 卖家条款；不绕过任何平台限制。
- **GUI 选型**：V1 固定为 PySide6；后台任务通过 QThread/signal 回传进度，见 [技术栈](03-tech-stack.md) 与 [架构](04-architecture.md)。
- **多账号并行默认关闭**：默认仍串行；只在⑤明确开启后并行，建议先用「检查本轮更新」确认账号、店铺和任务范围。