2026-07-02 15:48:22 +08:00
|
|
|
|
# 工程评估（全栈视角）
|
|
|
|
|
|
|
|
|
|
|
|
> 立场：以全栈开发工程师视角，评估本项目的**工程基础设施与可维护性**（区别于 `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）
|
|
|
|
|
|
|
2026-07-07 15:11:40 +08:00
|
|
|
|
> 落地状态：T-525 已完成。当前已加入 `pyproject.toml`、`requirements-dev.txt` 和 CI ruff 检查；先只强制安全类 lint，不做全仓格式化重排，mypy 仍作为后续可选。
|
|
|
|
|
|
|
2026-07-02 15:48:22 +08:00
|
|
|
|
- **现状**：无 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 的改动按第七节在测试商品实跑。
|
