工程评估（全栈视角）

立场：以全栈开发工程师视角，评估本项目的工程基础设施与可维护性（区别于 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）

落地状态：T-525 已完成。当前已加入 pyproject.toml、requirements-dev.txt 和 CI ruff 检查；先只强制安全类 lint，不做全仓格式化重排，mypy 仍作为后续可选。

现状：无 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）。流程重度依赖文档的项目，快照漂移即维护成本，收尾须强制覆盖。

落地建议顺序

T-521（依赖清单）+ T-522（CI）：投入最小，马上锁住质量。
T-523（拆 gui.py）：趁 68 个 GUI 测试还新鲜。
T-524（打包）：看运营是否已在用，按需推进。
T-525（lint/type）：与拆分并行或其后。
P2 待 P0/P1 落定后再排。

每项落地遵守 docs/05-coding-rules.md 验证清单，纯逻辑改动跑 python -m unittest discover -s tests，涉及 CDP 的改动按第七节在测试商品实跑。

5.2 KiB Raw Permalink Blame History Unescape Escape