cmshoppe/docs/02-requirements.md

需求

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

一、业务现状

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

二、用户角色

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

三、功能清单

第一版 MVP（最小闭环）

功能	用户能做什么	优先级
账号配置	在 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

第二版（多账号 + Excel + AI，5 Tab 流水线）

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

功能	用户能做什么	优先级
账号管理（④）	增删改账号：账号名/别名/地区/数据目录/端口/密码（加密仅参考）/备注；登录状态；启动登录、检测登录	P0
导入（①）	导入多个 Excel，按模板解析输入列（账号名/别名/商品id）为任务列表	P0
导入校验汇总（①）	导入后展示文件数、解析行数（原始数据量）、有效/无效行、匹配账号行数（按账号细分）、未匹配行数；跑采集前先纠错	P0
采集旧数据（①）	程序只读打开商品页，抓取旧标题、下载旧封面到本地，回写 Excel 旧字段	P0
AI 生成（②）	输入标题/封面提示词，AI 据提示词+旧标题生成新标题、据提示词+旧封面生成新封面	P0
提示词管理（②）	标题提示词「保存」到 title_prompt.txt 并启动回显；封面提示词多模板（下拉 + 新建/保存/另存为/重命名/删除）+ 插入 {新标题} + 预览（变量替换）	P0
查看对照（②）	双击任务弹窗查看新旧封面（纯查看，无人工确认）；可选对单行重生成	P0
更新 shopee（③）	按批次/店铺/状态筛选；对筛选出的已生成任务打开编辑页换标题+封面，并直接点「更新」提交线上（无开关）；可按状态=失败重试	P0
结果存储与回写	各阶段结果实时存 SQLite；该文件全部完成后把旧/新数据+状态批量回写原 Excel	P0
设置（⑤）	AI 模型管理（下拉+新增/删除/详情/测试连接，至少各一个文本+图像模型）；标题/图片大模型角色选择；分辨率(512/1k/2k/4k，返回超时随分辨率自动)；并发/重试/jpg质量；图片目录/Chrome 路径/端口	P0
首次引导保护	未配账号/未登录时，① ③ 执行按钮禁用并提示去④	P0

后续迭代

功能	描述	阶段
多账号并行	多个账号各自端口同时运行	V2
运行日志 / dry-run	操作留痕、可先空跑预览	V2
标题规则模板	预设多种改标题规则（前缀、替换、截断等）	V3

四、核心用户故事（MVP）

1. 作为运营，我打开工具后能看到已配置的账号列表，并能新增一个账号。
2. 我为某账号点击「启动并登录」，工具用它专属的配置目录打开 Chrome，我手动登录一次 Shopee 卖家中心。
3. 之后我选中该账号、填入商品 ID，工具自动打开该商品详情页（带登录态）。
4. 工具自动把标题改成目标值，并上传我指定的图片、把它拖到第一位设为封面。
5. 我核对无误后点击「更新」（或让工具在确认后点击），改动提交线上；不确认则刷新即还原。
6. 当账号尚未登录、商品页加载失败或封面已满 9 张时，工具给出明确提示并安全处理。

五、验收标准（MVP）

• 账号配置：新增/编辑/删除账号后，配置持久化到本地文件，重启工具仍在。
• 绑定配置目录：每个账号对应唯一的 chrome_user_data_dir/<账号标识> 目录；不同账号互不共用、不串号。
• 启动并登录：点击后 Chrome 用对应 user-data-dir 启动并开启调试端口；人工登录一次后，再次启动无需重新登录。
• 加载商品页：选定账号执行时，能用该账号登录态打开目标商品详情页，标题框与图片管理器渲染就绪。
• 改标题：写入后标题框 value 与 modelvalue 均等于目标值（确认页面模型已更新）。
• 换封面：上传成功后图片张数 +1（满 9 张时先删第一张再传）；目标图被拖到第一位成为封面。
• 提交更新：默认不点「更新」；开启提交时，按钮可点才点击，禁用态则不点并提示原因。
• 安全：任意失败路径不崩溃、不误删、不在无确认下提交线上。

六、范围边界与决策

问题	决策
第一版平台	Windows 桌面（Chrome 与各 user-data-dir 同机）
多账号隔离方式	每账号独立 user-data-dir（非 Chrome profile）；理由见 架构 3.0
是否需要账号	是；管理多个 Shopee 卖家账号，但登录由人工首次完成
存储	应用设置用 config.json；账号/任务/结果用 SQLite；Excel 读写用 openpyxl
账号↔任务绑定	以 Excel“别名”列为权威（非文件名）；匹配不到的略过并最后弹窗汇总
是否提交更新	③ 执行时总是点「更新」提交线上（无人工确认、无开关）
执行方式	多账号串行、逐任务执行，单条失败继续
旧标题/旧封面	程序在「采集」阶段改前抓取的快照（输出列），运营不填
新标题/新封面	AI 生成（输出列），直接用于更新（无人工确认）；本地留档+回写 Excel 供追溯
AI 服务	文本+图像生成，服务商/模型待定；Key 加密存于配置；见 技术栈
本地图片	旧封面下载、新封面生成存本地图片目录，路径记 DB
结果落库时机	各阶段处理完立即写 SQLite；该 Excel 全部完成后批量回写原文件
原文件被占用	回写时若原 Excel 被锁定，提示关闭重试或另存副本（SQLite 为事实来源）
暂不支持	自动登录、多账号并行（V2）、爬取

七、待确认 / 风险点

• 账号 / 凭证风险：登录态存在各账号 user-data-dir，等同账号凭证；目录不得提交版本库、不得外传。
• 密码存储风险：Tab2 的密码加密存于 SQLite，仅供人工参考，绝不自动登录/自动填；cmshopee.db、config.json 必须 gitignore；加密密钥不得与密文同存（见 任务 T-403）。
• 别名匹配风险：别名以 Excel 列为准；不匹配的行略过并最后弹窗，执行起始在日志逐条打印「文件→匹配账号」留痕，防误改。
• AI 主图风险（高，已知并接受）：本设计无人工确认、无提交开关，AI 生成的标题/封面经 ③ 执行即直接上线；主图若失真/夸大/侵权可能违反 Shopee 规则甚至下架。唯一缓解：新图本地留档 + 回写 Excel 供事后追溯；强烈建议先在测试商品验证再批量。
• AI 成本与依赖：接入文本+图像 AI = 新外部依赖 + API 费用 + Key 管理；服务商/模型/合规待 技术栈 确认。
• AI Key 安全：Key 加密存于 config.json，不写日志、不提交版本库。
• 第三方平台风险：Shopee 页面结构、class 名、接口随时可能变；限流、风控、封号风险存在，禁止高频批量。
• 自动化边界风险：③ 执行会自动改标题、上传图片、拖拽并直接点更新提交线上（无确认、无开关）；点「开始更新」前需自行确保任务来源与 AI 产出可接受。
• 合规风险：仅在自有/授权账号上操作；遵守 Shopee 卖家条款；不绕过任何平台限制。
• GUI 选型待确认：默认 Tkinter（零依赖），是否改用 PySide/Web 由维护者确认，见 技术栈。
• 多账号并行待确认：MVP 单账号单端口；并行的端口分配与资源占用在 V2 评估。