From ccb4d52d9f3df2da6828566f821ac74d724e5d5a Mon Sep 17 00:00:00 2001 From: chengma Date: Fri, 26 Jun 2026 15:55:28 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E7=BB=9F=E4=B8=80=20V1=20=E6=9B=B4?= =?UTF-8?q?=E6=96=B0=E7=A1=AE=E8=AE=A4=E7=AD=96=E7=95=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 8 ++--- CLAUDE.md | 4 +-- docs/00-ai-start-here.md | 55 ++++++++++++++++++++-------------- docs/01-vision.md | 10 +++---- docs/02-requirements.md | 32 ++++++++++---------- docs/03-tech-stack.md | 4 +-- docs/04-architecture.md | 26 ++++++++-------- docs/05-coding-rules.md | 16 +++++----- docs/06-tasks.md | 8 ++--- docs/README.md | 2 +- docs/api.md | 4 +-- docs/current-state.md | 14 ++++----- docs/routes.md | 19 ++++++------ docs/ui/README.md | 6 ++-- docs/ui/overview-pipeline.svg | 8 ++--- docs/ui/tab2-ai-generate.svg | 2 +- docs/ui/tab3-update-shopee.svg | 2 +- progress.md | 11 +++++++ 18 files changed, 127 insertions(+), 104 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 1c3c626..4e97638 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,15 +18,15 @@ cmshopee 是一个 **Windows 本地桌面自动化工具**：管理多个 Shopee 1. 本文 `AGENTS.md`：仓库定位与规则。 2. [`docs/00-ai-start-here.md`](docs/00-ai-start-here.md)：编程入口与流程。 -3. [`docs/04-architecture.md`](docs/04-architecture.md)：尤其**第四节 CDP 已验证事实**。 +3. [`docs/04-architecture.md`](docs/04-architecture.md)：尤其**第七节 CDP 已验证事实**。 4. [`docs/05-coding-rules.md`](docs/05-coding-rules.md)：硬性编码规则。 5. [`docs/06-tasks.md`](docs/06-tasks.md) + [`docs/current-state.md`](docs/current-state.md)：领取任务、了解现状。 6. 与当前任务相关的具体文档。 ## 工作规则 -- 复用已有 `cdp.py`，遵守架构第四节的选择器、就绪判断、上传/拖拽方式，不另起一套 CDP 交互。 -- 只做当前任务范围内的事；V2（批量、多账号并行）只记录不实现。 +- 复用已有 `cdp.py`，遵守架构第七节的选择器、就绪判断、上传/拖拽方式，不另起一套 CDP 交互。 +- 只做当前任务范围内的事；V2（多账号并行、dry-run、运行日志）只记录不实现。 - CDP 选择器 / 流程 / 配置 schema 变化，必须同步更新 `docs/04-architecture.md` 与相关任务。 - 改完后更新任务状态、追加 `progress.md`、覆盖 `docs/current-state.md`。 @@ -34,7 +34,7 @@ cmshopee 是一个 **Windows 本地桌面自动化工具**：管理多个 Shopee - 绝不把真实账号、密码、Cookie、token 写进代码、文档或日志；密码加密存、不自动登录。 - `config.json`、`cmshopee.db`、`chrome_user_data_dir/`（含密码/登录态）绝不提交版本库。 -- 「更新」提交线上、删除满 9 张封面等不可逆动作，必须显式确认/开关，并先在测试商品验证。 +- 「更新」提交线上、删除满 9 张封面等不可逆动作，必须有显式确认；③ 点击「开始更新」后必须弹窗确认，用户确认后才批量更新当前筛选结果。 - 不绕过 Shopee 的验证码、风控、限流或权限校验。 ## 验证 diff --git a/CLAUDE.md b/CLAUDE.md index 973d1f5..1f0b72a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -7,7 +7,7 @@ Claude Code 处理本仓库任务时： 1. 先读取 [`AGENTS.md`](AGENTS.md)。 -2. 再按 `AGENTS.md` 进入 [`docs/00-ai-start-here.md`](docs/00-ai-start-here.md) 和相关文档（重点 `docs/04-architecture.md` 第四节 CDP 已验证事实）。 +2. 再按 `AGENTS.md` 进入 [`docs/00-ai-start-here.md`](docs/00-ai-start-here.md) 和相关文档（重点 `docs/04-architecture.md` 第七节 CDP 已验证事实）。 3. 不在本文重复维护任务流程、编码规则或文档清单，避免和 `AGENTS.md` 漂移。 -安全红线（详见 `AGENTS.md`）：不写真实凭证、密码加密存不自动登录；不提交 `config.json`、`cmshopee.db`、`chrome_user_data_dir/`；不可逆操作需显式确认；不绕过 Shopee 风控。 +安全红线（详见 `AGENTS.md`）：不写真实凭证、密码加密存不自动登录；不提交 `config.json`、`cmshopee.db`、`chrome_user_data_dir/`；不可逆操作需显式确认，③ 开始更新前需弹窗确认；不绕过 Shopee 风控。 diff --git a/docs/00-ai-start-here.md b/docs/00-ai-start-here.md index ddd04d7..6a9fa97 100644 --- a/docs/00-ai-start-here.md +++ b/docs/00-ai-start-here.md @@ -9,18 +9,18 @@ cmshopee 是一个 Windows 本地桌面自动化工具（Tkinter，5 Tab）， 5 Tab 流水线（工作流优先顺序）： **① 导入采集 → ② AI生成 → ③ 更新shopee → ④ 账号管理 → ⑤ 设置** -目标闭环：④ 配账号并登录 → ① 导入 Excel（按“别名”列关联账号）、采集旧标题/旧封面并回写 → ② 用提示词 AI 生成新标题/新封面（无人工确认）→ ③ 对已生成任务改标题+换封面并直接点「更新」提交（无开关）→ 结果实时存 SQLite、批量回写原 Excel。 +目标闭环：④ 配账号并登录 → ① 导入 Excel（按“别名”列关联账号）、采集旧标题/旧封面并回写 → ② 用提示词 AI 生成新标题/新封面（不设逐条确认阶段）→ ③ 对已生成任务点击「开始更新」，弹窗确认后批量改标题+换封面并点「更新」提交 → 结果实时存 SQLite、批量回写原 Excel。 -存储：应用设置 `config.json`（含 AI Key）+ 业务数据 SQLite `cmshopee.db` + Excel 用 openpyxl + 图片存本地 `images/`。AI 服务商待定。 +存储：应用设置 `config.json` + AI 模型清单 `config/ai_models.json`（含加密 AI Key）+ 业务数据 SQLite `cmshopee.db` + Excel 用 openpyxl + 图片存本地 `images/`。AI 服务商待定。 ## 必读顺序 每次开始写代码前，按这个顺序建立上下文： 1. [`01-vision.md`](01-vision.md)：为什么做、为谁做、什么不做。 -2. [`02-requirements.md`](02-requirements.md)：MVP 要什么、怎么算达成。 +2. [`02-requirements.md`](02-requirements.md)：V1 要什么、怎么算达成。 3. [`03-tech-stack.md`](03-tech-stack.md)：既定技术选型（Python + 自研 CDP + Tkinter 待确认）。 -4. [`04-architecture.md`](04-architecture.md)：模块职责、账号数据模型、**第四节 CDP 已验证事实（重点）**。 +4. [`04-architecture.md`](04-architecture.md)：模块职责、账号数据模型、**第七节 CDP 已验证事实（重点）**。 5. [`05-coding-rules.md`](05-coding-rules.md)：写代码前必须遵守的规则。 6. [`06-tasks.md`](06-tasks.md)：领取本轮唯一任务。 7. [`../progress.md`](../progress.md)：历史执行记录、验证结果、阻塞点和关键决策。 @@ -30,14 +30,16 @@ cmshopee 是一个 Windows 本地桌面自动化工具（Tkinter，5 Tab）， ## 当前阶段 -当前项目处于：**单账号流程已验证，正扩展多账号管理 + GUI**。 +当前项目处于：**V0 单账号流程已验证，正在实现 V1 多账号 + Excel + AI + 5 Tab GUI 流水线**。 优先路径： -1. Phase 0：把已验证流程模块化（`editor.py`），定义账号配置。 -2. Phase 1：账号绑定 user-data-dir、Chrome 启动、登录保活、加载商品页。 -3. Phase 2：GUI 跑通单账号改标题 + 换封面闭环。 -4. Phase 3：批量与多账号并行（V2）。 +1. Phase 0：把已验证流程模块化（`editor.py`），建立 `config.json` 与 SQLite。 +2. Phase 1：账号绑定 user-data-dir、Chrome 启动、登录保活。 +3. Phase 2：导入 Excel、采集旧标题/旧封面并回写。 +4. Phase 3：AI 生成新标题/新封面。 +5. Phase 4：③ 批量确认后更新 Shopee 并回写结果。 +6. Phase 5：设置、加密密钥方案、收尾。 ## 领取任务规则 @@ -52,28 +54,35 @@ cmshopee 是一个 Windows 本地桌面自动化工具（Tkinter，5 Tab）， 如果代码实际状态和任务看板冲突，先说明冲突，不要擅自跳步。 -## MVP 边界 +## 版本边界 -MVP 只做： +**V0 已验证原型**： -- 账号配置（增删改 1..N 个 Shopee 账号）。 -- 每账号绑定 `chrome_user_data_dir/` 独立配置目录。 -- 一键启动 Chrome 供首次人工登录、登录态持久化。 -- 用某账号打开指定商品详情页，改标题、换封面。 -- 显式确认后点击「更新」提交（默认不提交）。 +- 单账号已登录 Chrome，通过 CDP 打开商品页、改标题、换封面。 +- 原型脚本默认不提交线上，`UPDATE=1` 才点击「更新」。 +- 作为 `editor.py` 的已验证参照，不再代表当前完整产品范围。 -MVP 不做： +**V1 当前 coding 目标**： + +- 5 Tab 流水线：① 导入采集 → ② AI生成 → ③ 更新shopee → ④ 账号管理 → ⑤ 设置。 +- 多账号管理，但执行更新仍串行；账号以独立 user-data-dir 隔离。 +- Excel 导入/回写 + SQLite 实时落库 + 本地图片目录。 +- AI 生成标题/封面，不设逐条确认阶段。 +- ③ 点击「开始更新」后弹窗确认当前筛选范围和任务数量；用户确认后才批量提交线上。 + +**V1 不做**： - 自动登录 / 自动填账号密码。 - 绕过验证码、风控、限流。 -- 批量、多账号并行、爬取、数据库（属 V2 及之后）。 +- 多账号并行、dry-run、完整运行日志（属 V2 及之后）。 +- 商品数据批量爬取。 ## 事实来源 项目事实只信： -- [`04-architecture.md`](04-architecture.md) 第四节：CDP 交互已验证结论（选择器、就绪判断、上传/拖拽方式）。 -- [`04-architecture.md`](04-architecture.md) 4.1/4.2/4.3：`config.json`、SQLite schema、Excel 模板。 +- [`04-architecture.md`](04-architecture.md) 第七节：CDP 交互已验证结论（选择器、就绪判断、上传/拖拽方式）。 +- [`04-architecture.md`](04-architecture.md) 5.1/5.1b/5.2/5.3：`config.json`、`config/ai_models.json`、SQLite schema、Excel 模板。 - 真实页面探查结果（用 `prototypes/inspect_images.py` / `prototypes/cookies.py` 实地确认）。 - 已验证脚本 `cdp.py`、`prototypes/demo.py`、`prototypes/set_title.py`、`prototypes/set_cover.py` 中跑通的逻辑。 @@ -93,14 +102,14 @@ MVP 不做： 做 CDP / 浏览器操作： -- 先看 `04-architecture.md` 第四节已验证事实。 +- 先看 `04-architecture.md` 第七节已验证事实。 - 再看 `api.md` 的 `cdp` / `editor` 模块合约。 - 复用 `cdp.py`，不重写一套。 做账号配置 / Chrome 启动： -- 先看 `04-architecture.md` 3.1 数据模型与 `api.md` 的 `config` / `chrome` 合约。 -- Chrome 启动参数严格按第四节“Chrome 启动参数”一条。 +- 先看 `04-architecture.md` 第五节数据模型与 `api.md` 的 `config` / `chrome` 合约。 +- Chrome 启动参数严格按第七节“Chrome 启动参数”一条。 ## 验证命令 diff --git a/docs/01-vision.md b/docs/01-vision.md index b931e66..574f28a 100644 --- a/docs/01-vision.md +++ b/docs/01-vision.md @@ -20,8 +20,8 @@ cmshopee 要解决：**运营要在多个 Shopee 卖家账号下，逐个商品 - **核心流程优先**：先把「单账号改标题 + 换封面」做稳，再扩展多账号和批量。 - **真实环境优先**：操作真实的已登录 Chrome，不伪造登录、不绕过风控。 -- **小步交付**：每一步都能运行、能验证、能回退；默认不提交线上，显式开关才落库。 -- **少即是稳**：MVP 不追求全自动，只追求最小可靠闭环；首次登录由人工完成。 +- **小步交付**：每一步都能运行、能验证、能回退；提交线上前必须由用户在批量确认弹窗中确认。 +- **少即是稳**：V1 不追求无人值守全自动，只追求本地批量流水线可靠；首次登录由人工完成。 - **凭证安全**：登录态保存在各账号独立的 Chrome user-data-dir 里，不导出、不外传、不写进代码或文档。 ## 四、核心价值主张 @@ -31,14 +31,14 @@ cmshopee 要解决：**运营要在多个 Shopee 卖家账号下，逐个商品 | 多账号集中管理 | 一处配置多个 Shopee 账号，各自绑定独立浏览器配置目录，互不串号 | | 免反复登录 | 每个账号的登录态持久化在自己的 user-data-dir，启动即带登录 Cookie | | 自动改标题/换封面 | CDP 驱动浏览器自动改标题、上传新图并拖拽设为封面 | -| 可控可回退 | 默认只改不提交，显式确认/开关才点「更新」，演示与试错零风险 | +| 可控可追溯 | ③ 点击「开始更新」后弹窗确认，确认后才批量提交；执行结果实时落库并回写 Excel | ## 五、不做什么（非目标） - 不做 Shopee 账号的**自动登录 / 自动填账号密码**（首次登录人工完成）。 - 不**绕过验证码、风控、限流或平台权限校验**。 - 不做商品数据的**批量爬取 / 导出**。 -- 不做云端服务、数据库、多人协作后台（MVP 为本地单机工具）。 +- 不做云端服务、外部数据库、多人协作后台（V1 为本地单机工具，业务数据使用本地 SQLite）。 - 不接管标题/封面以外的商品字段编辑。 -> MVP 的具体功能范围与验收标准，见 [需求](02-requirements.md)。 +> V1 的具体功能范围与验收标准，见 [需求](02-requirements.md)。 diff --git a/docs/02-requirements.md b/docs/02-requirements.md index b2ef3a3..6991f6a 100644 --- a/docs/02-requirements.md +++ b/docs/02-requirements.md @@ -19,7 +19,7 @@ ## 三、功能清单 -### 第一版 MVP（最小闭环） +### V0 已验证原型（单账号最小闭环） | 功能 | 用户能做什么 | 优先级 | | --- | --- | --- | @@ -30,9 +30,9 @@ | 加载商品页 | 选定账号，用其已登录 Chrome 打开指定商品详情页 | P0 | | 改标题 | 对该商品按规则修改标题（如去掉结尾若干字 / 指定新标题） | P0 | | 换封面 | 上传一张本地图片，自动设为商品封面（满 9 张时先删原封面再传） | P0 | -| 提交更新 | 在显式确认后点击「更新」，把改动提交到线上（默认不提交） | P0 | +| 提交更新 | 在显式确认后点击「更新」，把改动提交到线上；原型脚本默认不提交 | P0 | -### 第二版（多账号 + Excel + AI，5 Tab 流水线） +### V1 当前目标（多账号 + Excel + AI，5 Tab 流水线） 5 个 Tab，顺序：① 导入采集 → ② AI生成 → ③ 更新shopee → ④ 账号管理 → ⑤ 设置。 @@ -44,8 +44,8 @@ | 采集旧数据（①） | 程序只读打开商品页，抓取旧标题、下载旧封面到本地，回写 Excel 旧字段 | P0 | | AI 生成（②） | 输入标题/封面提示词，AI 据提示词+旧标题生成新标题、据提示词+旧封面生成新封面 | P0 | | 提示词管理（②） | 标题提示词「保存」到 `title_prompt.txt` 并启动回显；封面提示词多模板（下拉 + 新建/保存/另存为/重命名/删除）+ 插入 `{新标题}` + 预览（变量替换） | P0 | -| 查看对照（②） | 双击任务弹窗查看新旧封面（纯查看，无人工确认）；可选对单行重生成 | P0 | -| 更新 shopee（③） | 按批次/店铺/状态筛选；对筛选出的已生成任务打开编辑页换标题+封面，并直接点「更新」提交线上（无开关）；可按状态=失败重试 | P0 | +| 查看对照（②） | 双击任务弹窗查看新旧封面（纯查看，无逐条审核阶段）；可选对单行重生成 | P0 | +| 更新 shopee（③） | 按批次/店铺/状态筛选；点击「开始更新」后弹窗确认，确认后对当前筛选出的已生成任务打开编辑页换标题+封面，并逐条点「更新」提交线上；可按状态=失败重试 | P0 | | 结果存储与回写 | 各阶段结果实时存 SQLite；该文件全部完成后把旧/新数据+状态批量回写原 Excel | P0 | | 设置（⑤） | AI 模型管理（下拉+新增/删除/详情/测试连接，至少各一个文本+图像模型）；标题/图片大模型角色选择；分辨率(512/1k/2k/4k，返回超时随分辨率自动)；并发/重试/jpg质量；图片目录/Chrome 路径/端口 | P0 | | 首次引导保护 | 未配账号/未登录时，① ③ 执行按钮禁用并提示去④ | P0 | @@ -58,16 +58,16 @@ | 运行日志 / dry-run | 操作留痕、可先空跑预览 | V2 | | 标题规则模板 | 预设多种改标题规则（前缀、替换、截断等） | V3 | -## 四、核心用户故事（MVP） +## 四、核心用户故事（V1） 1. 作为运营，我打开工具后能看到已配置的账号列表，并能新增一个账号。 2. 我为某账号点击「启动并登录」，工具用它专属的配置目录打开 Chrome，我手动登录一次 Shopee 卖家中心。 3. 之后我选中该账号、填入商品 ID，工具自动打开该商品详情页（带登录态）。 4. 工具自动把标题改成目标值，并上传我指定的图片、把它拖到第一位设为封面。 -5. 我核对无误后点击「更新」（或让工具在确认后点击），改动提交线上；不确认则刷新即还原。 +5. 我在 ③ 按批次/店铺/状态筛选已生成任务，点击「开始更新」后看到批量确认弹窗；确认后工具逐条提交线上，取消则不执行。 6. 当账号尚未登录、商品页加载失败或封面已满 9 张时，工具给出明确提示并安全处理。 -## 五、验收标准（MVP） +## 五、验收标准（V1） - **账号配置**：新增/编辑/删除账号后，配置持久化到本地文件，重启工具仍在。 - **绑定配置目录**：每个账号对应唯一的 `chrome_user_data_dir/<账号标识>` 目录；不同账号互不共用、不串号。 @@ -75,8 +75,8 @@ - **加载商品页**：选定账号执行时，能用该账号登录态打开目标商品详情页，标题框与图片管理器渲染就绪。 - **改标题**：写入后标题框 `value` 与 `modelvalue` 均等于目标值（确认页面模型已更新）。 - **换封面**：上传成功后图片张数 +1（满 9 张时先删第一张再传）；目标图被拖到第一位成为封面。 -- **提交更新**：默认不点「更新」；开启提交时，按钮可点才点击，禁用态则不点并提示原因。 -- **安全**：任意失败路径不崩溃、不误删、不在无确认下提交线上。 +- **提交更新**：③ 点击「开始更新」后必须弹窗确认本次筛选范围和任务数量；用户确认后才逐条点「更新」，按钮禁用则不点并记录失败原因。 +- **安全**：任意失败路径不崩溃、不误删、不在缺少批量确认的情况下提交线上。 ## 六、范围边界与决策 @@ -87,10 +87,10 @@ | 是否需要账号 | 是；管理多个 Shopee 卖家账号，但登录由人工首次完成 | | 存储 | 应用设置用 `config.json`；账号/任务/结果用 SQLite；Excel 读写用 openpyxl | | 账号↔任务绑定 | 以 Excel“别名”列为权威（非文件名）；匹配不到的略过并最后弹窗汇总 | -| 是否提交更新 | ③ 执行时总是点「更新」提交线上（无人工确认、无开关） | +| 是否提交更新 | ③ 点击「开始更新」后弹窗确认；确认后对当前筛选结果逐条点「更新」提交线上；无常驻提交开关、无逐条人工审核 | | 执行方式 | 多账号串行、逐任务执行，单条失败继续 | | 旧标题/旧封面 | 程序在「采集」阶段改前抓取的快照（输出列），运营不填 | -| 新标题/新封面 | AI 生成（输出列），直接用于更新（无人工确认）；本地留档+回写 Excel 供追溯 | +| 新标题/新封面 | AI 生成（输出列），直接用于 ③；不设逐条确认阶段，本地留档+回写 Excel 供追溯 | | AI 服务 | 文本+图像生成，服务商/模型待定；Key 加密存于配置；见 [技术栈](03-tech-stack.md) | | 本地图片 | 旧封面下载、新封面生成存本地图片目录，路径记 DB | | 结果落库时机 | 各阶段处理完立即写 SQLite；该 Excel 全部完成后批量回写原文件 | @@ -102,11 +102,11 @@ - **账号 / 凭证风险**：登录态存在各账号 user-data-dir，等同账号凭证；目录不得提交版本库、不得外传。 - **密码存储风险**：Tab2 的密码加密存于 SQLite，仅供人工参考，**绝不自动登录/自动填**；`cmshopee.db`、`config.json` 必须 gitignore；加密密钥不得与密文同存（见 [任务 T-403](06-tasks.md)）。 - **别名匹配风险**：别名以 Excel 列为准；不匹配的行略过并最后弹窗，执行起始在日志逐条打印「文件→匹配账号」留痕，防误改。 -- **AI 主图风险（高，已知并接受）**：本设计**无人工确认、无提交开关**，AI 生成的标题/封面经 ③ 执行即直接上线；主图若失真/夸大/侵权可能违反 Shopee 规则甚至下架。唯一缓解：新图本地留档 + 回写 Excel 供事后追溯；强烈建议先在测试商品验证再批量。 +- **AI 主图风险（高，已知并接受）**：本设计不设逐条人工审核和常驻提交开关；AI 生成的标题/封面经 ③ 批量确认后会提交线上。主图若失真/夸大/侵权可能违反 Shopee 规则甚至下架。缓解：开始更新前弹窗确认筛选范围和任务数量，新图本地留档 + 回写 Excel 供事后追溯；强烈建议先在测试商品验证再批量。 - **AI 成本与依赖**：接入文本+图像 AI = 新外部依赖 + API 费用 + Key 管理；服务商/模型/合规待 [技术栈](03-tech-stack.md) 确认。 -- **AI Key 安全**：Key 加密存于 `config.json`，不写日志、不提交版本库。 +- **AI Key 安全**：Key 加密存于 `config/ai_models.json`，不写日志、不提交版本库。 - **第三方平台风险**：Shopee 页面结构、class 名、接口随时可能变；限流、风控、封号风险存在，禁止高频批量。 -- **自动化边界风险**：③ 执行会自动改标题、上传图片、拖拽并**直接点更新提交线上**（无确认、无开关）；点「开始更新」前需自行确保任务来源与 AI 产出可接受。 +- **自动化边界风险**：③ 确认后会自动改标题、上传图片、拖拽并点「更新」提交线上；点「开始更新」并确认前需自行确保筛选范围、任务来源与 AI 产出可接受。 - **合规风险**：仅在自有/授权账号上操作；遵守 Shopee 卖家条款；不绕过任何平台限制。 - **GUI 选型待确认**：默认 Tkinter（零依赖），是否改用 PySide/Web 由维护者确认，见 [技术栈](03-tech-stack.md)。 -- **多账号并行待确认**：MVP 单账号单端口；并行的端口分配与资源占用在 V2 评估。 +- **多账号并行待确认**：V1 多账号串行；并行的端口分配与资源占用在 V2 评估。 diff --git a/docs/03-tech-stack.md b/docs/03-tech-stack.md index bce847b..96686c7 100644 --- a/docs/03-tech-stack.md +++ b/docs/03-tech-stack.md @@ -27,13 +27,13 @@ ## 二、决策记录与演进 - **CDP 自研而非 playwright**：当前手写 `cdp.py`，因为它零重依赖、完全可控，并已在开发环境绕开了代理（`*_proxy` 指向本地 :1080）和 Chrome 的 Origin 403 两个坑。未来若交互复杂度大幅上升，再评估 playwright。 -- **GUI 选 Tkinter**：MVP 是单机配置 + 触发操作的轻量界面，Tkinter 零依赖即可。若后续需要表格、拖拽、复杂布局，再评估 PySide6。**该选型在动代码前需维护者确认。** +- **GUI 选 Tkinter**：V1 是单机配置 + 触发操作的轻量界面，Tkinter 零依赖即可。若后续需要表格、拖拽、复杂布局，再评估 PySide6。**该选型在动代码前需维护者确认。** - **存储拆两层**：应用设置进 `config.json`，账号/任务/结果进 SQLite。判据：少量人改无需查询 → 配置文件；成行增长要查询/导出 → DB。同一事实只存一处，不重复。取代早期的 `accounts.json` 方案。 - **Excel 用 openpyxl**：运营用真实 .xlsx；stdlib 无法读写 xlsx，引入一个轻依赖比改用 CSV 更贴合用户习惯。 - **多账号隔离用独立 user-data-dir，不用 Chrome profile**：profile 共享同一 user-data-dir/进程/调试端口，无法每账号独立 CDP 与并行；独立 user-data-dir 才契合自动化。详见 [架构 3.0](04-architecture.md)。 - **快捷方式生成用 PowerShell（无额外依赖）**：用 `WScript.Shell.CreateShortcut` 生成 `.lnk`，不引入 `pywin32` 等依赖。 - **AI 服务商待定**：需选支持文本生成 + 图像 image-to-image 的服务；选型要权衡能力、合规（电商主图）、计费、Key 管理。**未确认前不在代码里写死某家 SDK**，先在 `ai.py` 留稳定接口（`gen_title`/`gen_cover`）。 -- **AI 产出无人工确认**：生成的新标题/新封面经 ③ 执行即直接上线（无确认、无提交开关）；本地留档 + 回写 Excel 供追溯。 +- **AI 产出无逐条审核**：生成的新标题/新封面经 ③ 批量确认后提交线上；无常驻提交开关，本地留档 + 回写 Excel 供追溯。 - **不引入数据库（指外部 DB）**：用 stdlib SQLite 足够；不引入 Postgres/MySQL 等。 - **生产在 Windows 直跑**：开发期我们用过 WSL→Windows 的 `netsh portproxy`（9333→9222）连 CDP；但 GUI 与 Chrome 都在 Windows 时，直接连 `127.0.0.1:9222`，无需 portproxy。 diff --git a/docs/04-architecture.md b/docs/04-architecture.md index 073e63b..b66bf22 100644 --- a/docs/04-architecture.md +++ b/docs/04-architecture.md @@ -51,8 +51,8 @@ imported → collected → generated → applied - **imported**：openpyxl 解析输入列入库。 - **collected**：只读打开商品页，读旧标题、下载旧封面到本地，写 `old_title/old_cover_path`，回写 Excel 旧字段。 -- **generated**：AI 用提示词+旧标题生成新标题；用提示词+旧封面生成新封面（image-to-image），新图存本地。**无人工确认环节**，生成完即可被 ③ 执行（新图留档本地 + 回写 Excel 供事后追溯）。 -- **applied**：打开编辑页换标题+封面，**总是点「更新」提交线上**（无开关），回写结果。 +- **generated**：AI 用提示词+旧标题生成新标题；用提示词+旧封面生成新封面（image-to-image），新图存本地。**不设逐条人工审核阶段**，生成完即可进入 ③（新图留档本地 + 回写 Excel 供事后追溯）。 +- **applied**：③ 点击「开始更新」后弹窗确认当前筛选范围和任务数量；确认后打开编辑页换标题+封面，逐条点「更新」提交线上，回写结果。 任意阶段失败 → `stage` 不前进、记 `error`、`result/skipped`，不影响其他任务。 @@ -62,7 +62,7 @@ imported → collected → generated → applied **核心模块** -- `appconfig`：读写 `config.json`（Chrome 路径、`chrome_user_data_dir` 根、图片目录、AI 配置、端口、DB 路径、默认是否提交）。 +- `appconfig`：读写 `config.json`（Chrome 路径、`chrome_user_data_dir` 根、图片目录、AI 配置、端口、DB 路径）。 - `db`：SQLite 读写账号、任务、各阶段结果；建表/迁移。 - `excel`：openpyxl 读输入列、把输出列回写原 Excel（处理文件锁）。 - `config`：账号 ↔ user-data-dir 绑定；slug；目录创建。 @@ -195,8 +195,8 @@ CREATE TABLE tasks ( - `alias` 是账号↔任务**唯一关联键**；找不到账号 → stage=skipped，error=别名未匹配，最后弹窗汇总。 - `account_name` 仅展示/参考；匹配以 `alias` 为准。 - `old_title/old_cover_path`：程序**采集阶段抓取**的快照（输出）。 -- `new_title/new_cover_path`：**AI 生成**结果（输出），图片落本地，**无人工确认**，生成即可应用。 -- `committed`：③ 执行时**总是点「更新」提交**；该字段记录提交是否成功。 +- `new_title/new_cover_path`：**AI 生成**结果（输出），图片落本地；不设逐条确认阶段，生成即可进入 ③。 +- `committed`：③ 用户确认批量更新弹窗后逐条点「更新」提交；该字段记录提交是否成功。 - 各字段**每阶段处理完立即写回 SQLite**（实时落库）；阶段结束后批量回写 Excel。 ### 5.3 Excel 模板 @@ -244,7 +244,7 @@ images//_new. # AI 生成的新封面 - 每条/每张完成**立即 `set_generated` 写库**（实时落库，停止或崩溃不丢已生成的）。 - **「停止」**：取消未开始的任务，正在跑的少量完成或中断；停止后可再次「开始生成」对剩余继续。 - 进度：`标题 x/n · 封面 x/n · 失败 n`。 -- 生成后 stage=generated；**无人工确认**。双击任务弹窗查看新旧封面（纯查看），可选对某行 `重生成`；新标题直接用 AI 输出（不可编辑）。 +- 生成后 stage=generated；**不设逐条人工审核阶段**。双击任务弹窗查看新旧封面（纯查看），可选对某行 `重生成`；新标题直接用 AI 输出（不可编辑）。 - 并发数、重试、分辨率、jpg 质量、模型/Key 均来自 ⑤ 设置（`config.json` 的 `ai` 段）。 提示词管理： @@ -255,7 +255,9 @@ images//_new. # AI 生成的新封面 ### 6.3 应用更新（③ Tab） -- 对**已生成（generated）任务**：`open_product` → `change_title(new_title)`（如有）→ `replace_cover(new_cover_path)`（如有）→ **总是 `click_update` 提交**。 +- ③ 顶部筛选确定本次作用范围；点击「开始更新」后弹窗展示筛选条件、任务数量和“将提交线上”的风险提示。 +- 用户点「是/确认」才开始批量更新；点「否/取消」不执行、不改库。 +- 对确认后的**已生成（generated）任务**：`open_product` → `change_title(new_title)`（如有）→ `replace_cover(new_cover_path)`（如有）→ `click_update` 提交。 - 串行、单条失败继续；每条立即写 SQLite；全部完成回写 Excel（新字段+状态）+ 弹窗汇总。 ### 6.4 登录检测 @@ -277,18 +279,18 @@ images//_new. # AI 生成的新封面 | 上传成功 | 张数 +1 且新图 src 为 `susercontent` | | 封面=第一位 | `Input.dispatchMouseEvent` 拖到第一位，落点 `第一张.left - 0.30*宽` | | 满 9 张 | 上限 9；换封面先删第一张（`.shopee-image-manager__icon--delete`，确认框待实测）| -| 更新按钮 | `button.eds-button` 中 `更新`；③ 执行即点提交；禁用态（校验未过）记为失败 | +| 更新按钮 | `button.eds-button` 中 `更新`；③ 批量确认后逐条点提交；禁用态（校验未过）记为失败 | | 登录检测 | 重定向到登录页或缺 `SPC_ST` → 未登录 | -高风险动作（删满 9 张封面、点更新提交、AI 图直接上线）先在测试商品验证。注意：本设计**无人工确认、无提交开关**，③ 一旦执行即把 AI 标题/封面提交线上，新图本地留档+回写 Excel 是唯一事后追溯手段。 +高风险动作（删满 9 张封面、点更新提交、AI 图上线）先在测试商品验证。注意：本设计无逐条人工审核阶段、无常驻提交开关；③ 点击「开始更新」后必须弹窗确认，确认后才把当前筛选结果中的 AI 标题/封面提交线上。新图本地留档+回写 Excel 是事后追溯手段。 ## 八、推荐开发顺序 1. **地基**：`editor.py`（含采集）、`appconfig.py`+`config.json`、`db.py`、`.gitignore`。 2. **账号与启动**（④）：`config` 建目录、`chrome` 启动器/快捷方式、登录保活与检测、账号 CRUD。 3. **导入采集**（①）：`excel` 导入、采集旧标题/旧封面、回写。 -4. **AI 生成**（②）：`ai` 模块、提示词、对照预览与确认。 -5. **更新 shopee**（③）：对已生成任务换标题+封面、直接提交、回写。 +4. **AI 生成**（②）：`ai` 模块、提示词、对照预览。 +5. **更新 shopee**（③）：对已生成任务弹窗批量确认后换标题+封面、提交、回写。 6. **设置**（⑤）+ 首次未配账号引导保护。 ## 九、项目结构建议 @@ -317,5 +319,5 @@ cmshopee/ - 存储边界：应用设置→config.json，账号/任务/结果→SQLite，图片→本地目录并记路径于 DB，登录态→user-data-dir；同一事实只存一处。 - 别名是账号↔任务唯一关联键。 - 密码与 AI Key 加密存、不外传、不写日志；不自动登录。 -- AI 生成内容直接用于 ③ 更新（无人工确认）；新图本地留档 + 回写 Excel 以备追溯。 +- AI 生成内容直接进入 ③ 更新候选；③ 批量确认后提交，新图本地留档 + 回写 Excel 以备追溯。 - 高风险模块先单独验证，再接入流水线。 diff --git a/docs/05-coding-rules.md b/docs/05-coding-rules.md index 4780e9b..b497651 100644 --- a/docs/05-coding-rules.md +++ b/docs/05-coding-rules.md @@ -7,7 +7,7 @@ 1. **不臆造**：选择器、字段、文件、接口不确定就查证或先用 `prototypes/inspect_images.py` 探查页面，不要猜 class 名。 2. **守范围**：只做当前任务要求的事，不顺手加批量/并行等后续功能。 -3. **照架构**：复用 `cdp.py`，遵守 `04-architecture.md` 第四节“已验证结论”，不另起一套 CDP 交互。 +3. **照架构**：复用 `cdp.py`，遵守 `04-architecture.md` 第七节“已验证结论”，不另起一套 CDP 交互。 4. **小步改**：一次只解决一个问题，不夹带无关重构。 5. **可验证**：改完必须能 `py_compile`，关键路径能在测试商品上跑通，对得上验收标准。 @@ -20,16 +20,16 @@ ## 2. 事实来源纪律 -- CDP 交互只信 `04-architecture.md` 第四节的“已验证结论”和真实页面探查结果。 +- CDP 交互只信 `04-architecture.md` 第七节的“已验证结论”和真实页面探查结果。 - 不从旧脚本注释或记忆里推断仍然有效的选择器；Shopee 页面可能已变，必要时重新探查。 - 不虚构 Shopee 接口、字段、按钮文案。 - 选择器 / 流程变化必须同步更新 `04-architecture.md` 和相关任务。 ## 3. 范围纪律 -- MVP 只做 `02-requirements.md` 中列为 P0 的功能（账号配置、绑定目录、启动登录、加载页、改标题、换封面、可选更新）。 -- V2 / V3 功能（批量、多账号并行、日志、规则模板）只记录，不实现。 -- 需求明确排除的非目标（自动登录、绕风控、爬取、数据库）不得实现。 +- V1 只做 `02-requirements.md` 中列为 P0 的当前目标功能（5 Tab、账号管理、Excel 导入采集、AI 生成、批量确认后更新 Shopee、结果回写）。 +- V2 / V3 功能（多账号并行、dry-run、完整运行日志、规则模板）只记录，不实现。 +- 需求明确排除的非目标（自动登录、绕风控、商品数据批量爬取、外部数据库）不得实现。 ## 4. 架构纪律 @@ -68,7 +68,7 @@ python prototypes/demo.py # 单账号闭环验证（不提交） - 绝不明文存密码；DB 里密码必须加密，且加密密钥不与密文同存。 - 绝不把 `config.json`、`cmshopee.db`、`chrome_user_data_dir/` 提交版本库。 - 绝不自动登录 / 自动填账号密码；登录由人工完成，程序只检测登录态。 -- 绝不在没有显式确认/开关的情况下点击「更新」提交线上。 +- 绝不在缺少 ③ 批量确认弹窗确认的情况下点击「更新」提交线上。 - 绝不擅自删除用户文件或重置 user-data-dir。 - 绝不为通过验证而降低验收标准（如不验证 `modelvalue` 就当改成功）。 @@ -76,8 +76,8 @@ python prototypes/demo.py # 单账号闭环验证（不提交） - 登录凭证只存在于各账号 user-data-dir；不导出、不外传、不写入配置或日志。 - 涉及 Shopee 时，遵守 `04-architecture.md` 写明的页面规则与限流边界；不高频批量、不绕风控/验证码。 -- 高风险动作（删满 9 张的封面、点击更新）必须有显式确认或开关，并先在测试商品验证。 -- 自动化默认支持“只改不提交”（dry-run 思路）；提交、删除等不可逆动作要可控、可回退（刷新还原）。 +- 高风险动作（删满 9 张的封面、点击更新）必须有显式确认，并先在测试商品验证。 +- V1 无常驻提交开关；③ 的批量确认弹窗是提交线上前的确认边界。dry-run 属 V2。 ## 9. 拿不准就问 diff --git a/docs/06-tasks.md b/docs/06-tasks.md index 3db0a32..2edc18e 100644 --- a/docs/06-tasks.md +++ b/docs/06-tasks.md @@ -22,7 +22,7 @@ | ID | 任务 | 依赖 | 验收要点 | 状态 | | --- | --- | --- | --- | --- | | T-001 | `editor.py`：改标题/换封面/点更新/登录检测/**采集(读旧标题+旧封面下载)**/apply_task，复用 `cdp.py` | - | 函数可调用，在测试商品跑通；与 `prototypes/demo.py` 行为一致 | TODO | -| T-002 | `appconfig.py` + `config.json`（含 image_dir、ai 段、端口等默认值） | - | 读写正常；不存在则写默认；AI Key 加密占位 | TODO | +| T-002 | `appconfig.py` + `config.json`（含 image_dir、ai 选择/参数段、端口等默认值；不含 AI Key） | - | 读写正常；不存在则写默认；AI Key 留给 `config/ai_models.json`/T-501 | TODO | | T-003 | `db.py` + SQLite 建表（accounts/tasks，含各阶段字段） | - | `init_db` 幂等；账号/任务/各 set_* 可用；schema 同架构 5.2 | TODO | | T-004 | `.gitignore`：排除 `config.json`、`cmshopee.db`、`chrome_user_data_dir/`、`images/` | T-002, T-003 | 凭证/业务/图片不被提交 | TODO | @@ -61,8 +61,8 @@ | ID | 任务 | 依赖 | 验收要点 | 状态 | | --- | --- | --- | --- | --- | -| T-401 | Tab③ 列出已生成任务 + 按批次/店铺/状态筛选 | T-303 | 顶部批次/店铺/状态筛选；「开始更新」仅作用于当前筛选结果；状态=失败可重试；无提交开关；警示“执行即提交线上” | TODO | -| T-402 | 串行执行 apply：换标题+换封面+**总是点更新提交**，单条失败继续，立即写库 | T-401, T-001 | 逐条 set_applied；恒提交；失败继续；未登录引导保护 | TODO | +| T-401 | Tab③ 列出已生成任务 + 按批次/店铺/状态筛选 + 开始更新确认弹窗 | T-303 | 顶部批次/店铺/状态筛选；「开始更新」仅作用于当前筛选结果；弹窗显示筛选条件/任务数/线上提交风险；取消不执行；状态=失败可重试；无常驻提交开关 | TODO | +| T-402 | 串行执行 apply：批量确认后换标题+换封面+点更新提交，单条失败继续，立即写库 | T-401, T-001 | 确认后逐条 set_applied；失败继续；未登录引导保护；未确认时不调用 apply | TODO | | T-403 | 回写结果到原 Excel（新标题/新封面/更新状态）+ 结束弹窗汇总 | T-402, T-204 | 回写原文件（锁处理）；弹窗 成功/失败/略过 | TODO | ## Phase 5 · 设置与收尾 @@ -81,7 +81,7 @@ - M2：账号管理可用、能登录与检测（Phase 1）。 - M3：导入 + 采集 + 回写旧数据（Phase 2）。 - M4：AI 生成新标题/新封面（Phase 3）。 -- M5：对已生成任务更新 Shopee（直接提交）+ 回写结果（Phase 4）。 +- M5：对已生成任务弹窗批量确认后更新 Shopee + 回写结果（Phase 4）。 ## 待办池（Backlog） diff --git a/docs/README.md b/docs/README.md index 8051dcd..ae3448a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,7 +4,7 @@ ## 一句话定位 -cmshopee 是一个给**电商运营**使用的 Windows 桌面自动化工具，用于**管理多个 Shopee 卖家账号、并用 CDP 驱动 Chrome 批量修改商品标题、替换商品封面图**。第一版先跑通「配置账号 → 绑定独立 Chrome 配置目录（保留登录态）→ 用某账号打开指定商品详情页 → 改标题 + 换封面（可选提交更新）」闭环。 +cmshopee 是一个给**电商运营**使用的 Windows 桌面自动化工具，用于**管理多个 Shopee 卖家账号、并用 CDP 驱动 Chrome 批量修改商品标题、替换商品封面图**。V0 已验证单账号「改标题 + 换封面」闭环；当前 V1 目标是 5 Tab 流水线：导入采集 → AI 生成 → 点击「开始更新」并确认后批量提交 → 回写结果。 ## 文档导航 diff --git a/docs/api.md b/docs/api.md index 54ed54c..89478ea 100644 --- a/docs/api.md +++ b/docs/api.md @@ -116,7 +116,7 @@ collect(account, task) -> dict # -> {old_title, old_cover_path} change_title(cdp, new_title) -> dict # {ok, value, modelvalue}，要求三者相等 replace_cover(cdp, image_win_path) -> dict # 上传→等CDN→拖第一位；满9张先删第一张 click_update(cdp) -> dict # {clicked, reason}；禁用则记失败 -apply_task(account, task) -> dict # 对已生成任务：换标题+换封面+点「更新」提交（恒提交） +apply_task(account, task) -> dict # 对已生成任务：换标题+换封面+点「更新」提交（调用前必须已做批量确认） # -> {committed, error} ``` @@ -142,7 +142,7 @@ generate_batch(tasks, prompts, ai_cfg, on_progress, should_stop) -> None - 并发数/重试/分辨率/jpg 质量来自 `appconfig.ai_config()`；Key 加密存、不入日志。 - 标题快、图片慢：分两段、各用各自并发数；失败按 `retry` 重试，仍失败记 error 不阻塞其余。 - 调用有成本与失败可能：超时、限流、内容安全拒绝都要返回明确错误。 -- 生成结果**直接用于 ③ 更新**（无人工确认）；本地留档 + 回写 Excel 供追溯。 +- 生成结果**直接进入 ③ 更新候选**；③ 点击「开始更新」后弹窗批量确认，确认后提交线上。本地留档 + 回写 Excel 供追溯。 ## prompts 模块（`prompts.py`，待建） diff --git a/docs/current-state.md b/docs/current-state.md index 76cf777..1b069fa 100644 --- a/docs/current-state.md +++ b/docs/current-state.md @@ -5,8 +5,8 @@ ## 当前快照 -- 日期：2026-06-25 -- 阶段：单账号 CDP 流程已验证；多账号管理 + 5 Tab GUI + Excel/AI 流水线为既定设计，尚未开始编码。 +- 日期：2026-06-26 +- 阶段：V0 单账号 CDP 流程已验证；V1 多账号管理 + 5 Tab GUI + Excel/AI 流水线为既定设计，尚未开始编码。 - 技术栈：Python 3.10+，自研 CDP（websocket-client + requests），SQLite（sqlite3）+ `config.json` + openpyxl + AI（服务商待定），GUI Tkinter 5 Tab（待最终确认）。 - 生产代码：尚无 `appconfig/db/excel/config/chrome/editor/gui`；现有为验证脚本 + `cdp.py`。 - 测试：以 `py_compile` + 在测试商品上手动跑 `prototypes/demo.py` 为主，无自动化测试。 @@ -15,11 +15,11 @@ ## 既定设计要点（文档已定） - GUI：**5 Tab 流水线**，顺序 ① 导入采集 → ② AI生成 → ③ 更新shopee → ④ 账号管理 → ⑤ 设置。 -- 流水线阶段：imported → collected（采集旧标题/旧封面+下载+回写）→ generated（AI 提示词生成新标题/新封面）→ applied（改 Shopee 并直接提交）。**无 confirmed、无提交开关。** -- 存储：`config.json`（应用设置含 AI Key）+ SQLite `cmshopee.db`（账号/任务/各阶段结果）+ openpyxl（Excel）+ 本地 `images/`（旧/新封面）。 +- 流水线阶段：imported → collected（采集旧标题/旧封面+下载+回写）→ generated（AI 提示词生成新标题/新封面）→ applied（③ 弹窗批量确认后改 Shopee 并提交）。**无 confirmed、无常驻提交开关。** +- 存储：`config.json`（应用设置）+ `config/ai_models.json`（AI 模型清单与加密 Key）+ SQLite `cmshopee.db`（账号/任务/各阶段结果）+ openpyxl（Excel）+ 本地 `images/`（旧/新封面）。 - 多账号隔离：每账号独立 user-data-dir（非 profile）。 - 账号↔任务绑定：以 Excel“别名”列为权威；未匹配略过，结束弹窗汇总。 -- 执行：多账号串行、单条失败继续；③ 执行即点「更新」提交线上（无确认、无开关）。 +- 执行：多账号串行、单条失败继续；③ 点击「开始更新」后弹窗确认当前筛选范围和任务数量，确认后逐条点「更新」提交线上。 - AI：服务商待定；生成内容直接用于更新，本地留档+回写 Excel 供追溯。 - 登录：人工登录 + 程序检测，不自动登录；首次未配账号/未登录时 ① ③ 禁用并引导去④。 @@ -40,7 +40,7 @@ - 找到/新建商品详情页 tab，等编辑器就绪。 - 改标题：原生 setter + 派发事件，`value` 与 `modelvalue` 双等于新值。 - 换封面：`setFileInputFiles` 上传（`.shopee-image-manager__upload input[type=file]`）→ 等 CDN 链接 → `Input.dispatchMouseEvent` 拖到第一位（落点 `first.left - 0.30*w`）。 -- 「更新」按钮：可点才点，禁用态识别；默认不提交。 +- 「更新」按钮：可点才点，禁用态识别；③ 未批量确认前不提交。 ## 任务看板状态 @@ -74,7 +74,7 @@ set UPDATE=1 && python prototypes/demo.py 1. 读仓库级 `AGENTS.md` / `CLAUDE.md`（如有）。 2. 读 `docs/00-ai-start-here.md`。 -3. 读 `docs/05-coding-rules.md` 与 `docs/04-architecture.md` 第四节。 +3. 读 `docs/05-coding-rules.md` 与 `docs/04-architecture.md` 第七节。 4. 在 `docs/06-tasks.md` 取第一个 `TODO` 且依赖 `DONE` 的任务。 5. 将该任务状态改为 `DOING`。 diff --git a/docs/routes.md b/docs/routes.md index f0858eb..fb752f4 100644 --- a/docs/routes.md +++ b/docs/routes.md @@ -12,11 +12,11 @@ | --- | --- | --- | | ① 导入采集 | 导入多个 Excel；任务列表；**采集**商品当前的旧标题/旧封面（只读），封面图下载本地；回写 Excel 旧字段 | 只读，低 | | ② AI生成 | 左侧标题/封面**提示词**；右侧按批次/店铺筛选任务列表；AI 生成新标题/新封面；双击看新旧封面 | 不触线上，中 | -| ③ 更新shopee | 对**已生成**任务打开编辑页换标题+封面并**直接点「更新」提交**；结果回写 Excel | **写线上，高** | +| ③ 更新shopee | 对**已生成**任务点击「开始更新」后弹窗确认；确认后打开编辑页换标题+封面并逐条点「更新」提交；结果回写 Excel | **写线上，高** | | ④ 账号管理 | Shopee 账号（账号名/别名/数据目录/端口/密码加密/登录状态）；启动登录、检测登录、生成快捷方式 | 中 | | ⑤ 设置 | AI 模型/API Key、本地图片目录、Chrome 路径、默认端口等 | — | -任务的**阶段状态**贯穿各 Tab：`imported → collected → generated → applied`（或 `failed/skipped`）。**无人工确认、无提交开关**。各 Tab 聚焦各自阶段的列与按钮，但操作同一批任务（同一 batch）。 +任务的**阶段状态**贯穿各 Tab：`imported → collected → generated → applied`（或 `failed/skipped`）。② 不设逐条人工确认阶段；③ 无常驻提交开关，但点击「开始更新」后必须弹窗确认当前筛选范围和任务数量。各 Tab 聚焦各自阶段的列与按钮，但操作同一批任务（同一 batch）。 ## 首次使用引导保护 @@ -74,14 +74,14 @@ - 底部**单个「开始生成」+「停止」**：开始生成 = **先按 `title_concurrency` 并发生成标题，接着按 `image_concurrency` 并发生成封面**；进度实时显示 标题/封面/失败 计数。 - 生成参数（标题/图片并发数、失败重试、分辨率、jpg 质量、模型/Key）在 **⑤ 设置**，不在本 Tab 重复。 - 每条/每张完成即写库；「停止」取消未开始项，可再次「开始生成」对剩余继续。 -- **无人工确认环节**；新标题直接用 AI 输出（不可编辑）；可选对单行 `重生成`。生成完即可进入 ③。 +- **无逐条人工审核环节**；新标题直接用 AI 输出（不可编辑）；可选对单行 `重生成`。生成完即可进入 ③，③ 开始更新前会做批量确认。 ## ③ 更新shopee ``` ┌ 更新shopee ───────────────────────────────────────────────────┐ │ 批次[本次▼] 店铺[全部▼] 状态[已生成▼] [筛选] │ -│ ⚠ 「开始更新」对【当前筛选结果】执行，即改标题+换封面并直接提交 │ +│ ⚠ 点击「开始更新」后确认【当前筛选结果】，确认后改标题+换封面并提交 │ │ ┌───────────────────────────────────────────────────────────┐ │ │ │ 店铺 商品ID 新标题 新封面 阶段 结果 │ │ │ └───────────────────────────────────────────────────────────┘ │ @@ -92,7 +92,8 @@ - 顶部**按批次 / 店铺 / 状态筛选**（与 ①②一致）；「开始更新」作用于**当前筛选结果**，是一道范围控制。 - 店铺筛选：建议**逐店铺更新**（每店铺需先启动其 Chrome 并登录）。 - 状态筛选：`已生成` 只跑未更新的；`失败` 用于**失败重试**；`已更新成功/略过` 仅查看。 -- 对筛选出的**已生成（generated）任务**执行：打开编辑页换标题+换封面 → **总是点「更新」提交**（无开关）。 +- 点击「开始更新」后弹窗展示本次筛选条件、任务数量和“将提交线上”的风险提示；用户点「是/确认」才开始，点「否/取消」不执行。 +- 对确认后的**已生成（generated）任务**执行：打开编辑页换标题+换封面 → 点「更新」提交。 - 串行、单条失败继续；每条立即写回 SQLite（committed/状态/error）。 - 全部完成 → 把新标题/新封面/更新状态批量回写原 Excel；弹窗汇总。 @@ -122,13 +123,13 @@ │ ① 导入采集：导入 Excel → 采集旧标题/旧封面 → 回写旧字段 │ -② AI生成：提示词 → 生成新标题/新封面（无确认） +② AI生成：提示词 → 生成新标题/新封面（无逐条审核） │ -③ 更新shopee：对已生成任务换标题+封面 → 直接点「更新」提交 → 回写结果 +③ 更新shopee：对已生成任务点击开始更新 → 弹窗确认 → 换标题+封面 → 点「更新」提交 → 回写结果 ``` - 未配账号/未登录：① ③ 的执行按钮禁用并提示去 ④。 -- 已生成的任务即可进 ③；③ 执行即提交线上（无确认、无开关）。 +- 已生成的任务即可进 ③；③ 用户确认批量弹窗后提交线上，无常驻提交开关。 - 任意步骤失败：记入该任务、日志标明，不影响其他任务。 ## 组件建议（Tkinter） @@ -138,7 +139,7 @@ | `MainNotebook` | 根窗口 | 5 个 Tab | | `CollectTab` | ① | 导入、任务表、采集、回写 | | `GenerateTab` | ② | 左提示词 + 右筛选/任务列表、双击看新旧封面、开始生成 | -| `ApplyTab` | ③ | 已生成任务、换标题+封面+直接提交、回写 | +| `ApplyTab` | ③ | 已生成任务、开始更新确认、换标题+封面+提交、回写 | | `AccountsTab` | ④ | 账号增删改、启动登录 | | `SettingsTab` | ⑤ | AI/目录/Chrome 配置 | diff --git a/docs/ui/README.md b/docs/ui/README.md index bd4f782..2af3da2 100644 --- a/docs/ui/README.md +++ b/docs/ui/README.md @@ -4,10 +4,10 @@ cmshopee 5 Tab 桌面应用的界面效果图。SVG 可用浏览器直接打开 | 文件 | 内容 | | --- | --- | -| [overview-pipeline.svg](overview-pipeline.svg) | 5 Tab 流水线总览（stage：imported→collected→generated→confirmed→applied） | +| [overview-pipeline.svg](overview-pipeline.svg) | 5 Tab 流水线总览（stage：imported→collected→generated→applied） | | [tab1-import-collect.svg](tab1-import-collect.svg) | ① 导入采集：导入 Excel、任务列表、采集旧标题/旧封面、回写、日志 | -| [tab2-ai-generate.svg](tab2-ai-generate.svg) | ② AI生成：提示词、生成、新旧对照预览、确认/重生成 | -| [tab3-update-shopee.svg](tab3-update-shopee.svg) | ③ 更新shopee：已确认任务、批次提交开关、执行结果、汇总 | +| [tab2-ai-generate.svg](tab2-ai-generate.svg) | ② AI生成：提示词、生成、新旧对照预览、重生成 | +| [tab3-update-shopee.svg](tab3-update-shopee.svg) | ③ 更新shopee：已生成任务、开始更新确认、执行结果、汇总 | | [tab4-accounts.svg](tab4-accounts.svg) | ④ 账号管理：账号列表、启动登录、检测登录、账号编辑弹窗 | | [tab5-settings.svg](tab5-settings.svg) | ⑤ 设置：AI 模型/Key、路径、端口 | diff --git a/docs/ui/overview-pipeline.svg b/docs/ui/overview-pipeline.svg index 9ce05b5..730c1dd 100644 --- a/docs/ui/overview-pipeline.svg +++ b/docs/ui/overview-pipeline.svg @@ -18,12 +18,12 @@ cmshopee · 5 Tab 流水线总览 工作流优先顺序 · 对象是 Excel 里的每一行任务 · 状态字段 stage 贯穿全程 - + imported collected generated - applied（直接提交） + applied（确认后提交） @@ -49,7 +49,7 @@ 旧标题→新标题 旧封面→新封面 双击看新旧封面 - → generated（无确认） + → generated（无逐条审核） @@ -57,7 +57,7 @@ 已生成任务 打开编辑页 换标题 + 换封面 - 直接点更新提交 + 开始更新确认后提交 串行 · 失败继续 实时写库 + 回写Excel → applied diff --git a/docs/ui/tab2-ai-generate.svg b/docs/ui/tab2-ai-generate.svg index a7949df..c4df32e 100644 --- a/docs/ui/tab2-ai-generate.svg +++ b/docs/ui/tab2-ai-generate.svg @@ -90,7 +90,7 @@ …百搭耳環飾品生成中… 处理中 - 新标题直接用 AI 输出（不可编辑）· 可对单行右键「重生成」· 无人工确认 + 新标题直接用 AI 输出（不可编辑）· 可对单行右键「重生成」· 无逐条审核 diff --git a/docs/ui/tab3-update-shopee.svg b/docs/ui/tab3-update-shopee.svg index 3e9107b..d87a1fc 100644 --- a/docs/ui/tab3-update-shopee.svg +++ b/docs/ui/tab3-update-shopee.svg @@ -28,7 +28,7 @@ - ⚠ 「开始更新」对【当前筛选结果】执行：改标题+换封面并直接提交线上（无确认、无开关） + ⚠ 点击「开始更新」后确认【当前筛选结果】：确认后改标题+换封面并提交线上 diff --git a/progress.md b/progress.md index 45d31e7..69fa144 100644 --- a/progress.md +++ b/progress.md @@ -158,4 +158,15 @@ - 注意：`prototypes/demo.py` 依赖根目录 `cdp.py`，需从项目根运行或设 PYTHONPATH。 - 下一步：Phase 0 起步（T-001/T-002/T-003）。 +## 【2026-06-26】修正 · V1 提交策略 + 入口引用 + 版本边界 + +- 状态：DONE（仅文档） +- 变更：更新 `AGENTS.md`、`CLAUDE.md`、`docs/00-ai-start-here.md`、`docs/01-vision.md`、`docs/02-requirements.md`、`docs/03-tech-stack.md`、`docs/04-architecture.md`、`docs/05-coding-rules.md`、`docs/06-tasks.md`、`docs/routes.md`、`docs/current-state.md`、`docs/README.md`、`docs/api.md` 与 UI 线框说明。 +- 决策： + - ③ 更新 shopee 的提交策略统一为：点击「开始更新」后弹窗确认当前筛选范围和任务数量，用户确认后才批量更新并逐条点「更新」提交线上；取消则不执行、不改库。 + - V1 不设逐条人工审核阶段，也无常驻提交开关；批量确认弹窗是提交线上前的确认边界。 + - V0 = 已验证单账号原型；V1 = 当前 5 Tab + Excel + AI + SQLite 流水线；V2 = 多账号并行 / dry-run / 完整运行日志等后续能力。 + - CDP 已验证事实统一引用 `docs/04-architecture.md` 第七节。 +- 下一步：继续处理剩余全栈落地缺口，如 SQLite/Excel schema、GUI 线程模型、AI 接入任务依赖。 +