QiuSWandClaude Opus 5
ea7371a25f
从线上 Wiki 回读 15 个核心页面并写入镜像头（页面名、地址、revision、 同步时间）。`python dev_scripts/harness.py sync --verify` 通过， 新项目 Wiki 初始化门禁完成。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LbdtsD3ohhSMy3KPoCgARq
123 lines
6.8 KiB
Markdown
123 lines
6.8 KiB
Markdown
<!-- gitea-wiki-mirror:start -->
|
||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||
wiki_page: Architecture-and-Code-Map
|
||
wiki_url: https://git.ilapage.cn/chengma/cmsp/wiki/Architecture-and-Code-Map.-
|
||
wiki_revision: 5250b3f1f2cec82390869a70a8da4c4b54b1a959
|
||
synchronized_at: 2026-09-02T03:57:22Z
|
||
<!-- gitea-wiki-mirror:end -->
|
||
|
||
# 架构与代码地图
|
||
|
||
## 当前实现状态
|
||
|
||
**截至 2026-09-02，本仓库还没有产品代码。** 本页的目录结构和执行路径是已确认的目标设计，不是既有实现。阅读时必须区分：
|
||
|
||
- **当前事实**：仓库只有 DevHarness 骨架、文档镜像和一份设计规范 `Wails专属Chrome登录与淘宝以图搜流程.md`；业务能力目前只存在于仓库外的两份 Python 参考实现。
|
||
- **目标规范**：本页描述的 Go 目录、执行路径和边界。
|
||
|
||
Go 骨架建立后，本页必须改写为对当前代码的描述，并在工单记录变更。不允许用目标描述宣称现有能力。
|
||
|
||
## 项目定位
|
||
|
||
cmsp 是运行在使用者本机的单机桌面程序，没有服务端，没有多用户，没有权限模型。它是三个外部系统之间的搬运工：
|
||
|
||
```text
|
||
货憨憨 ERP --拉取--> cmsp（本机 SQLite） --上传--> 货憨憨 ERP --同步--> Shopee
|
||
|
|
||
+--以图搜、抓视频--> 淘宝（专属 Chrome）
|
||
```
|
||
|
||
程序不直接访问 Shopee。所有写入 Shopee 的内容都经由货憨憨 ERP。
|
||
|
||
## 代码地图
|
||
|
||
目标目录结构：
|
||
|
||
```text
|
||
cmsp/
|
||
├─ main.go Wails 应用入口
|
||
├─ app.go 暴露给前端的方法，只做参数校验和转发
|
||
├─ internal/
|
||
│ ├─ config/ 参数设置的读取、校验与持久化
|
||
│ ├─ store/ SQLite 打开、迁移与仓储；商品、任务、视频、认证状态
|
||
│ ├─ huohanhan/ 货憨憨 ERP 客户端
|
||
│ │ ├─ auth.go 登录、验证码 OCR、认证状态复用与失效重登
|
||
│ │ ├─ client.go 统一请求、401 重试
|
||
│ │ ├─ product.go 商品查询与分页
|
||
│ │ └─ upload.go 素材上传与商品视频批量更新
|
||
│ ├─ taobao/ 淘宝流程，结构见设计规范
|
||
│ │ ├─ chrome_manager.go 专属 Chrome 的端口扫描、启动、归属校验、复用与关闭
|
||
│ │ ├─ cdp_client.go CDP 连接、导航与在页面上下文执行 JavaScript
|
||
│ │ ├─ login_service.go Cookie 检查与服务端深度登录检查
|
||
│ │ ├─ image_service.go 主图读取与缩放
|
||
│ │ ├─ sign_service.go pcSign 与 MTOP sign 生成
|
||
│ │ ├─ image_search.go 调用 MTOP 以图搜接口并解析商品
|
||
│ │ ├─ detail_video.go 商品详情页视频地址提取与去重
|
||
│ │ └─ models.go 登录状态与商品结构体
|
||
│ ├─ downloader/ 视频下载队列、并发控制、重试与 ffprobe 校验
|
||
│ └─ task/ 任务编排、状态机、进度事件、断点续传
|
||
└─ frontend/
|
||
└─ src/
|
||
├─ views/ProductsView 商品数据页：表格、多选、同步/下载/上传按钮、进度与日志
|
||
└─ views/SettingsView 参数设置页：货憨憨账号、Chrome 路径与用户数据目录、下载目录、并发数
|
||
```
|
||
|
||
界面为两个标签页：**商品数据**与**参数设置**。
|
||
|
||
前端不直接实现业务判断。登录是否有效、任务能否开始、按钮是否可用，都由 Go 侧返回的状态决定。
|
||
|
||
## 两条主要执行路径
|
||
|
||
### 路径一：货憨憨商品同步与视频上传
|
||
|
||
```text
|
||
使用者点击「同步数据」
|
||
→ app.go 校验参数
|
||
→ internal/huohanhan/auth 取得有效认证（复用 SQLite 中的 token，失效则重新登录）
|
||
→ internal/huohanhan/product 分页拉取指定 Shopee 店铺商品
|
||
→ internal/store 写入或更新商品行
|
||
→ 事件推送进度，前端刷新表格
|
||
|
||
使用者勾选商品点击「上传视频」
|
||
→ internal/task 逐个取出本地视频文件
|
||
→ internal/huohanhan/upload 上传素材取得线上地址
|
||
→ internal/huohanhan/upload 批量更新商品视频
|
||
→ internal/store 更新上传状态
|
||
→ 事件推送进度
|
||
```
|
||
|
||
上传链路的接口细节尚未确认，见[需求总览](09-product-requirements-overview.md)的未决项。
|
||
|
||
### 路径二：淘宝以图搜与视频下载
|
||
|
||
```text
|
||
使用者勾选商品点击「下载视频」
|
||
→ internal/taobao/chrome_manager 准备或复用专属 Chrome
|
||
→ internal/taobao/login_service 执行服务端深度登录检查
|
||
├─ 无效 → 返回 E_LOGIN_REQUIRED，中断整批，提示重新登录
|
||
└─ 有效 ↓
|
||
→ 对每个商品：
|
||
internal/taobao/image_service 读取主图并缩放
|
||
internal/taobao/sign_service 生成 pcSign 与 MTOP sign
|
||
internal/taobao/image_search 在淘宝页面上下文请求 MTOP，解析同款商品
|
||
internal/taobao/detail_video 逐个打开同款详情页，提取并去重视频地址
|
||
internal/downloader 下载 MP4，ffprobe 校验，写入本地目录
|
||
internal/store 逐条落库，商品间随机等待
|
||
→ 事件推送进度
|
||
```
|
||
|
||
每个商品开始前重新执行深度登录检查。登录失效是全局停止条件，不是单个商品的失败。
|
||
|
||
详细的登录检查、签名和接口约定见仓库内 `Wails专属Chrome登录与淘宝以图搜流程.md`，该文件是路径二的目标规范。
|
||
|
||
## 不可破坏的边界
|
||
|
||
- **淘宝登录必须由使用者手动完成。** 程序只负责打开登录页和检查结果，不自动填写密码、不绕过验证码、不绕过安全验证。
|
||
- **淘宝登录态只存在于专属 Chrome Profile。** 程序不读取、不复制、不落盘、不上传 Cookie；只从当前会话读取 `_m_h5_tk` 用于计算签名，且不缓存、不长期复用、不写入日志。
|
||
- **同一个 Chrome Profile 不得同时启动两个实例。** 启动前必须校验 PID 存在、进程命令属于本程序专属 Profile、CDP 端口可访问且存在 `page` 类型目标。
|
||
- **登录失效是全局停止门。** 必须中断整批任务并保留断点，不得记为单商品失败后继续，也不得自动反复请求 MTOP 接口。
|
||
- **货憨憨的写操作必须显式确认。** 上传素材、批量修改商品、删除素材都属于写操作，调用方必须明确表达意图，不得作为查询流程的副作用发生。
|
||
- **凭据不进入仓库。** 账号、密码、token、Cookie、Chrome Profile 内容不得出现在代码、日志、工单、Wiki 和提交中。
|
||
- **SQLite 是任务状态的唯一事实来源。** 不允许再用 JSON 文件维护第二份任务状态。
|
||
- **前端不做安全判断。** 按钮禁用只是提示，真正的校验必须在 Go 侧执行。
|