From 599f2a171c939ed0f5cfe0a26d02b1d0c067a44d Mon Sep 17 00:00:00 2001 From: chengma Date: Thu, 2 Jul 2026 15:48:22 +0800 Subject: [PATCH] docs: add engineering review tasks --- docs/06-tasks.md | 13 ++++++++ docs/README.md | 1 + docs/engineering-review.md | 67 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 81 insertions(+) create mode 100644 docs/engineering-review.md diff --git a/docs/06-tasks.md b/docs/06-tasks.md index 739cdcb..2fa9cc5 100644 --- a/docs/06-tasks.md +++ b/docs/06-tasks.md @@ -105,6 +105,16 @@ | T-519 | ②AI生成长任务进度条 + 用户可读滚动日志 | T-303, T-505, T-518 | 问题：批量生成几十/上百个标题或图片超时重试时，仅底部文字 `进度：标题x/y · 封面x/y · 失败z` 和技术型结构化日志不足以让用户判断剩余量、是否卡住、慢在哪一步。方案：②底部操作区增加标题/图片两条独立 `QProgressBar`，分两行显示 `标题 x/y`、`图片 x/y`，标题阶段结束后保持 100%，图片进度按本轮总任务口径显示并在旁边保留失败数；现有「AI生成运行日志」改为用户可读自动滚动日志，显示本轮开始、标题/图片开始与成功、商品ID/店铺、图片超时/重试、失败原因、停止请求和完成汇总。日志不得显示 API Key、密码、Cookie、token、完整请求体、base64 图片或超长 prompt；保留 DB `run_logs/run_log_events` 脱敏记录。只改②生成 UI、`GenerateWorker`/AI 生成事件文案和 GUI/AI 单测，不改 AI HTTP 协议、DB schema、Excel、Shopee/CDP 流程 | DONE | | T-520 | ②AI生成封面可选生成开关 | T-519, T-501b | 问题：图片生成成本明显高于标题生成，当前②「开始生成」默认标题和图片都生成，用户只想改标题时也会调用图片模型，成本不可控；⑤「允许更新封面」只控制③线上提交阶段，不能替代②生成阶段的成本选择。方案：②AI生成页增加「生成封面图片（成本较高）」复选框，状态持久化到 `config.json` 的 `ai.generate_cover`，默认 `false`；点击「开始生成」时读取该开关：关闭时只并发生成标题，标题成功后立即 `db.set_generated(task_id, new_title, NULL)`，任务进入 `generated` 并可在③只更新标题，不调用 `gen_cover()`、不渲染封面提示词、不创建新封面文件，图片进度和运行日志明确显示本轮未生成图片；开启时保持现有标题后图片两段流程。③的 `allow_cover_update` 仍只控制线上更新阶段，若任务无 `new_cover_path`，③跳过封面更新且不因未开启「允许更新封面」阻断。只改 `config.json` 的 AI 段、②生成 UI、`GenerateWorker`/`ai.generate_batch()` 编排和 `appconfig/ai/gui` 单测；不改 DB schema、AI HTTP 协议、Excel、Shopee/CDP 更新流程 | DONE | +## Phase 6 · 工程基础设施（`docs/engineering-review.md`） + +| ID | 任务 | 依赖 | 验收要点 | 状态 | +| --- | --- | --- | --- | --- | +| T-521 | 依赖清单（锁版本 requirements） | T-006 | 依据 `docs/engineering-review.md` P0。新增锁版本的 `requirements.txt`（或 `pyproject.toml`）声明 PySide6/openpyxl/websocket-client/requests 及版本，与 `docs/03-tech-stack.md` 依赖纪律对齐；README/文档补安装说明；不引入新运行时依赖、不改业务代码 | TODO | +| T-522 | CI：自动跑语法 + 单元/ GUI 测试 | T-006, T-521 | 依据 `docs/engineering-review.md` P1。加 GitHub Actions，在 push/PR 上按 `requirements.txt` 安装依赖并跑 `python -m compileall app main.py` + `python -m unittest discover -s tests`（含 PySide6 环境下的 GUI 测试，`QT_QPA_PLATFORM=offscreen`）；不连真实 Shopee/AI；失败即红灯，把"改完必跑测试"变强制门禁 | TODO | +| T-523 | 拆分 `app/gui.py` 为 `app/gui/` 包 | T-511, T-514, T-515, T-516, T-517 | 依据 `docs/engineering-review.md` P0。把 6317 行 God-file 拆为包：`models.py`（3 个 TableModel）、`tabs/`（①~⑤各一文件）、`workers.py`（Generate/Apply/Collect/WriteBack/AccountLoginCheck/AIModelTest 从 gui 挪出，与 `app/workers.py` 基类归拢）、`widgets.py`（色板常量、空状态卡、批次总览等 helper）、`main_window.py`。纯结构重构、对外行为与公开符号不变（保留 `from app import gui` 及 `MainWindow`/各 Tab/Worker 的导入路径或提供兼容再导出），保留 PySide6 缺失优雅降级；68 个 GUI 测试全绿、不删减断言 | TODO | +| T-524 | PyInstaller 打包为免安装 exe | T-521 | 依据 `docs/engineering-review.md` P1。新增 PyInstaller spec/脚本，产出 Windows 免安装 `.exe`；打包排除并绝不内置 `config.json`/`config/ai_models.json`/`cmshopee.db*`/`chrome_user_data_dir/`/`images/`/`logs/` 等本地数据与密钥；首次运行按现有默认值在本地生成配置；文档补打包与分发步骤 | TODO | +| T-525 | 引入 ruff（lint + format）+ 可选 pre-commit | T-006 | 依据 `docs/engineering-review.md` P1。加 `ruff` 配置（lint + format），先以现状为基线不做大规模风格重排，只开启安全规则（未用 import/变量、明显错误）；可选 `.pre-commit-config.yaml`；不改业务逻辑；CI（T-522）可串入 ruff 检查。数据模型渐进上 mypy 作为后续可选 | TODO | + ## 里程碑 - M1：editor（含采集）模块化、config.json + SQLite + AI 模型清单后端 + 测试基座就绪（Phase 0）。 @@ -121,3 +131,6 @@ - AI 生成图的合规/质量自检。 - （已提升为 T-518）② 左栏提示词区组件密度优化：封面模板低频动作（另存为/重命名/删除）收敛进②本页「模板操作」菜单/小按钮；第一版不移入⑤，不改提示词数据结构。 - 界面深色主题：为 `docs/ui-color-design.md` 语义色板另出深色等义映射（当前只服务浅色）。 +- DB 版本化迁移：引入 `PRAGMA user_version` + 有序迁移列表，替代当前 ad-hoc `ALTER TABLE ADD COLUMN`（`docs/engineering-review.md` P2）。 +- CDP/editor 自动回归：录制 DOM 快照 / mock-CDP 夹具做选择器形状回归，针对 T-404 高频故障源（`docs/engineering-review.md` P2）。 +- 宽异常审计：确认 `app/` 中 88 处 `except Exception` 均落诊断日志、无静默吞异常（`docs/engineering-review.md` P2）。 diff --git a/docs/README.md b/docs/README.md index 9ebbf59..59ce2e9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -24,6 +24,7 @@ cmshopee 是一个给**电商运营**使用的 Windows PySide6 桌面自动化 - [常见问题排查](troubleshooting.md)：本地配置、启动报错、敏感文件修复等排障记录。 - [产品与 UI 评估](ux-review.md)：以 PM + UI 设计视角评估 5 Tab 模块 / 组件合理性，含优化方案与优先级清单。 - [界面配色设计](ui-color-design.md)：语义色板与组件配色映射规范，指导给状态 / 按钮 / 校验 / 登录状态上色。 +- [工程评估](engineering-review.md)：全栈视角评估工程基础设施与可维护性（依赖清单 / CI / 打包 / gui.py 拆分 / lint），含 P0-P2 与优先级。 ## 任务 / 进度 / 当前状态 diff --git a/docs/engineering-review.md b/docs/engineering-review.md new file mode 100644 index 0000000..be07457 --- /dev/null +++ b/docs/engineering-review.md @@ -0,0 +1,67 @@ +# 工程评估（全栈视角） + +> 立场：以全栈开发工程师视角，评估本项目的**工程基础设施与可维护性**（区别于 `docs/ux-review.md` 的产品/UI 视角、`docs/ui-color-design.md` 的视觉视角）。 +> 基线：2026-07-02 代码现状（`app/` 11.4k 行、`tests/` 6.4k 行）+ `docs/04-architecture.md` / `docs/03-tech-stack.md` / `docs/05-coding-rules.md`。 +> 性质：评估与建议，不改代码。P0/P1 已转 `docs/06-tasks.md` Phase 6 的 T-521~T-525；P2 记入本文与 Backlog。 + +## 总判断 + +功能层面已相当扎实：模块职责清晰、`0` 处 TODO/FIXME、`0` 处裸 `except`、PySide6 缺失时优雅降级（`QMainWindow = object` 兜底 + `else` 桩）、测试:代码 ≈ 6.4k:11.4k、诊断日志分层（T-207/T-505）、密钥脱敏纪律、DB 已有轻量迁移（`ALTER TABLE ADD COLUMN` + 列存在性判断）。 + +**问题集中在工程基础设施和可维护性**——这些是随项目长大迟早要还的债，现在还便宜。 + +## 🔴 P0 + +### 1. `app/gui.py` 巨型 God-file（→ T-523） + +- **现状**：`app/gui.py` 6317 行、17 个类，占全代码库 55%。更关键的是 6 个业务 Worker（`GenerateWorker`/`ApplyWorker`/`CollectWorker`/`WriteBackWorker`/`AccountLoginCheckWorker`/`AIModelTestWorker`，约 1500 行）把编排逻辑埋在 GUI 文件里，Qt 信号与业务逻辑耦合。 +- **影响**：所有 UI 改动都挤进同一文件——难导航、易冲突、无法按模块隔离测试；worker 里的业务逻辑难以脱离 Qt 单测。 +- **方案**：拆成 `app/gui/` 包——`models.py`（3 个 TableModel）、`tabs/`（5 个 Tab 各一文件）、`workers.py`（具体 worker 从 gui 挪出，与 `app/workers.py` 基类归拢）、`widgets.py`（色板常量、空状态卡、批次总览等 helper）、`main_window.py`。纯结构重构、行为不变，有 68 个 GUI 测试兜底。 +- **工作量**：中～大；风险可控（测试网密）。 + +### 2. 没有依赖清单（→ T-521） + +- **现状**：无 `requirements.txt` / `pyproject.toml`。PySide6、openpyxl、websocket-client、requests 全靠约定，版本未锁。 +- **影响**：换机器/新人上手靠猜；版本漂移风险已有征兆（`ai_models category` 启动报错、PySide6 假定 6.5.3）。 +- **方案**：加锁版本的 `requirements.txt`（或 `pyproject.toml`），与 `docs/03-tech-stack.md` 依赖纪律对齐。 +- **工作量**：小；收益极高。 + +## 🟠 P1 + +### 3. 没有打包/分发方案（→ T-524） + +- **现状**：定位是"给运营用的 Windows 桌面工具"，但无 PyInstaller spec，运营需自装 Python+pip+PySide6。 +- **影响**：门槛与"桌面工具"定位矛盾，是落地的最后一公里。 +- **方案**：PyInstaller 打包脚本，产出免安装 `.exe`；spec 里排除 `config.json`/`cmshopee.db`/`images/` 等本地数据。 +- **工作量**：中。 + +### 4. 没有 CI（→ T-522） + +- **现状**：测试写得好但无自动执行；GUI 测试依赖 PySide6，最易被漏跑。 +- **影响**：回归靠人自觉；AGENTS "改完必跑测试" 无强制门禁。 +- **方案**：GitHub Actions，在 push/PR 跑 `compileall` + `unittest discover`（含安装 PySide6 后的 GUI 测试）。 +- **工作量**：小。 + +### 5. 没有 lint/format/type 配置（→ T-525） + +- **现状**：无 ruff/black/mypy/pre-commit；类型注解部分覆盖。 +- **影响**：大代码库 + AI agent 持续改，缺一致性门禁会慢慢腐化（未用 import、风格漂移）。 +- **方案**：引入 ruff（lint+format 一把梭）+ 可选 pre-commit hook；数据模型可渐进上 mypy。 +- **工作量**：小～中。 + +## 🟡 P2（记录，暂不建任务） + +- **DB 迁移 ad-hoc**：`ALTER TABLE ADD COLUMN + 列存在性判断`能用，但无 `PRAGMA user_version` 版本化、无有序迁移列表。schema 已在长（`deleted_at`、`run_logs`…），建议趁早加极简版本化迁移 runner。 +- **CDP/editor 只有手动集成测试**：最脆的一层无自动回归，而 T-404 历史说明真实 bug 几乎都出在这里（确认框、上传转圈、重复图、稳定等待）。可探索录制 DOM 快照 / mock-CDP 夹具做选择器形状回归。难、ROI 中等，但针对最高频故障源。 +- **88 处 `except Exception` 待审计**：虽无裸 except，但广捕获多；有诊断层前提下应确认每个宽捕获都落日志、无静默吞异常。 +- **文档快照漂移**：`docs/current-state.md` 的"下一个可领取任务"曾滞后（写 T-505 但 T-505~517 已 DONE）。流程重度依赖文档的项目，快照漂移即维护成本，收尾须强制覆盖。 + +## 落地建议顺序 + +1. **T-521（依赖清单）+ T-522（CI）**：投入最小，马上锁住质量。 +2. **T-523（拆 gui.py）**：趁 68 个 GUI 测试还新鲜。 +3. **T-524（打包）**：看运营是否已在用，按需推进。 +4. **T-525（lint/type）**：与拆分并行或其后。 +5. P2 待 P0/P1 落定后再排。 + +> 每项落地遵守 `docs/05-coding-rules.md` 验证清单，纯逻辑改动跑 `python -m unittest discover -s tests`，涉及 CDP 的改动按第七节在测试商品实跑。