docs: 规划正式代码包结构
将正式代码目标结构统一为 app/ 包和根目录 main.py，区分 app/ 正式代码与 prototypes/ 原型参照。 新增 T-000 作为首个实现任务：创建 app 包、迁移 cdp.py、补 app/__main__.py 与 main.py、修正 prototypes/demo.py 导入。 更新模块合约、技术栈、编码规则和 current-state：后续模块路径改为 app/editor.py、app/appconfig.py、app/db.py 等，启动方式为 python main.py 或 python -m app。
This commit is contained in:
chengma
@@ -9,7 +9,7 @@
|
||||
| --- | --- | --- | --- |
|
||||
| 语言 | Python 3.10+ | 已定 | 已有脚本均为 Python；标准库够用 |
|
||||
| 运行平台 | Windows（生产）；WSL 可用于开发 | 已定 | Chrome 与各 user-data-dir 在 Windows；GUI 与 Chrome 同机，CDP 走 `localhost` |
|
||||
| 浏览器自动化 | 自研 CDP 客户端 `cdp.py` | 已定 | 基于 websocket-client + requests 手写；不引入 playwright/selenium，规避代理与 Origin 坑 |
|
||||
| 浏览器自动化 | 自研 CDP 客户端 `app/cdp.py` | 已定 | 基于 websocket-client + requests 手写；不引入 playwright/selenium，规避代理与 Origin 坑 |
|
||||
| WebSocket | `websocket-client`（import `websocket`） | 已定 | 讲 CDP 协议；用 `suppress_origin=True` 绕过 403 |
|
||||
| HTTP | `requests` | 已定 | 读 `/json` 拿 tab 列表；`trust_env=False` 忽略代理 |
|
||||
| 浏览器 | Google Chrome（已安装） | 已定 | 带 `--remote-debugging-port` 启动 |
|
||||
@@ -22,17 +22,17 @@
|
||||
| AI 图像生成 | 选 `default_image_model`（category=image，image-to-image） | 选型在配置 | 提示词+旧封面→新封面；分辨率 512/1k/2k/4k，返回超时随分辨率 |
|
||||
| 并发 | 标准库 `concurrent.futures.ThreadPoolExecutor` | 已定 | 标题/图片分别按并发数并行；可停止、可重试 |
|
||||
| 图片处理 | `requests`（下载）+ `Pillow`（按分辨率/jpg质量存盘） | 部分待定 | 下载旧封面；新封面按 resolution 生成、jpg_quality 存盘 |
|
||||
| 测试 | `python -m py_compile` + `unittest` + 手动 CDP/AI 验证 | 已定（分层） | 配置/DB/Excel/prompts 用单测；CDP/Shopee 与真实 AI 属集成验证或 mock |
|
||||
| 测试 | `python -m compileall app main.py` + `unittest` + 手动 CDP/AI 验证 | 已定（分层） | 配置/DB/Excel/prompts 用单测；CDP/Shopee 与真实 AI 属集成验证或 mock |
|
||||
|
||||
## 二、决策记录与演进
|
||||
|
||||
- **CDP 自研而非 playwright**：当前手写 `cdp.py`，因为它零重依赖、完全可控，并已在开发环境绕开了代理（`*_proxy` 指向本地 :1080）和 Chrome 的 Origin 403 两个坑。未来若交互复杂度大幅上升，再评估 playwright。
|
||||
- **CDP 自研而非 playwright**：当前已验证根目录 `cdp.py`，正式代码迁入 `app/cdp.py`；它零重依赖、完全可控，并已在开发环境绕开了代理（`*_proxy` 指向本地 :1080）和 Chrome 的 Origin 403 两个坑。未来若交互复杂度大幅上升，再评估 playwright。
|
||||
- **GUI 选 PySide6**：V1 是 5 Tab 运营工作台，包含任务表格、筛选、图片预览、后台采集/生成/更新、进度与停止。当前环境已安装 PySide6，且 Tkinter 不可用；Qt 的 `QThread`/signal-slot 比 Tkinter 手动 queue/after 更适合长任务回传 UI。
|
||||
- **存储拆两层**：应用设置进 `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 服务商待定**：需选支持文本生成 + 图像 image-to-image 的服务；选型要权衡能力、合规（电商主图）、计费、Key 管理。**未确认前不在代码里写死某家 SDK**，先在 `app/ai.py` 留稳定接口（`gen_title`/`gen_cover`）。
|
||||
- **AI 产出无逐条审核**：生成的新标题/新封面经 ③ 批量确认后提交线上；无常驻提交开关，本地留档 + 回写 Excel 供追溯。
|
||||
- **不引入数据库（指外部 DB）**：用 stdlib SQLite 足够；不引入 Postgres/MySQL 等。
|
||||
- **生产在 Windows 直跑**：开发期我们用过 WSL→Windows 的 `netsh portproxy`（9333→9222）连 CDP；但 GUI 与 Chrome 都在 Windows 时，直接连 `127.0.0.1:9222`，无需 portproxy。
|
||||
@@ -43,7 +43,8 @@
|
||||
| --- | --- |
|
||||
| 安装依赖 | `pip install websocket-client requests openpyxl pillow PySide6` |
|
||||
| 检查 PySide6 | `python -c "import PySide6; print(PySide6.__version__)"` |
|
||||
| 语法检查 | `python -m py_compile *.py` |
|
||||
| 语法检查 | `python -m compileall app main.py` |
|
||||
| 启动 GUI | `python main.py` / `python -m app` |
|
||||
| 单元测试（T-006 后） | `python -m unittest discover -s tests` |
|
||||
| 跑单账号演示 | `python prototypes/demo.py`（分步）/ `set AUTO=1 && python prototypes/demo.py`（自动） |
|
||||
| 提交更新（真改线上） | `set UPDATE=1 && python prototypes/demo.py` |
|
||||
@@ -66,14 +67,14 @@ set AUTO=1 && python prototypes/demo.py
|
||||
|
||||
- 新增第三方依赖前，先在本文说明用途、替代方案和维护成本。
|
||||
- GUI 框架固定为 PySide6，不允许混入 Tkinter/PyQt/Web 形成两套 UI。
|
||||
- 不引入第二套浏览器自动化方案（不要 cdp.py 之外再混入 selenium/playwright）。
|
||||
- 不引入第二套浏览器自动化方案（不要 `app/cdp.py` 之外再混入 selenium/playwright）。
|
||||
- 不确定的技术选型先更新本文，再进入代码。
|
||||
|
||||
## 五、测试分层
|
||||
|
||||
| 层级 | 覆盖对象 | 验证方式 |
|
||||
| --- | --- | --- |
|
||||
| 语法 | 所有 `.py` | `python -m py_compile *.py`，后续可扩展 `compileall` |
|
||||
| 语法 | 正式代码包与入口 | `python -m compileall app main.py` |
|
||||
| 单元 | `appconfig/db/excel/prompts/config/chrome` 的纯逻辑 | T-006 建立 `tests/` 后运行 `python -m unittest discover -s tests`，使用临时目录/临时 SQLite/样例 Excel |
|
||||
| GUI 轻测 | PySide6 主窗口可创建、Tab 数量、worker signal 基本行为 | 可用 unittest 构造 `QApplication`，不连真实 Shopee |
|
||||
| 集成 | CDP/editor 操作 Shopee 测试商品 | 手动跑 `prototypes/demo.py` 或后续专用集成脚本 |
|
||||
|
||||
Reference in New Issue
Block a user