QiuSWandClaude Opus 5
5c5c6825b0
- 原型确认记录填入线上链接、版本 v4、确认日期与覆盖范围 - 新增「已确认的界面决定」：侧栏形式与宽度、登录状态唯一显示位置、 两行工具栏、四个搜索条件到 getPage 参数的映射、店铺来源、 运行日志独立窗口、路径选择框类型、表格列 - R6 状态改为「原型已确认，未实现」 - 负责人于 2026-09-02 删除了 Wails专属Chrome登录与淘宝以图搜流程.md， 三处 Wiki 引用改指向业务规则与术语页，并留一句说明避免后人再引用 - 架构页「当前事实」更新为已有 Go 骨架 - README 补充目录说明与当前状态 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LbdtsD3ohhSMy3KPoCgARq
125 lines
7.1 KiB
Markdown
125 lines
7.1 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: 94d20f4ed447c66e00b06c993afc8736fae04d15
|
||
synchronized_at: 2026-09-02T07:59:04Z
|
||
<!-- gitea-wiki-mirror:end -->
|
||
|
||
# 架构与代码地图
|
||
|
||
## 当前实现状态
|
||
|
||
**截至 2026-09-02，本仓库还没有产品代码。** 本页的目录结构和执行路径是已确认的目标设计，不是既有实现。阅读时必须区分：
|
||
|
||
- **当前事实**：仓库有 DevHarness 骨架、文档镜像，以及 Go 骨架（Wails 入口 + config / store / logx 三个包，见下方代码地图）。淘宝与货憨憨的业务能力尚未实现，目前只存在于仓库外的两份 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 逐条落库，商品间随机等待
|
||
→ 事件推送进度
|
||
```
|
||
|
||
每个商品开始前重新执行深度登录检查。登录失效是全局停止条件，不是单个商品的失败。
|
||
|
||
详细的登录检查、签名和接口约定见[业务规则与术语](03-business-rules-and-glossary.md)的「淘宝登录」与「淘宝以图搜」两节。
|
||
|
||
原先仓库内的 `Wails专属Chrome登录与淘宝以图搜流程.md` 已于 2026-09-02 由负责人删除，其中的稳定结论已并入上述业务规则页，不要再引用那个文件名。
|
||
|
||
## 不可破坏的边界
|
||
|
||
- **淘宝登录必须由使用者手动完成。** 程序只负责打开登录页和检查结果，不自动填写密码、不绕过验证码、不绕过安全验证。
|
||
- **淘宝登录态只存在于专属 Chrome Profile。** 程序不读取、不复制、不落盘、不上传 Cookie；只从当前会话读取 `_m_h5_tk` 用于计算签名，且不缓存、不长期复用、不写入日志。
|
||
- **同一个 Chrome Profile 不得同时启动两个实例。** 启动前必须校验 PID 存在、进程命令属于本程序专属 Profile、CDP 端口可访问且存在 `page` 类型目标。
|
||
- **登录失效是全局停止门。** 必须中断整批任务并保留断点，不得记为单商品失败后继续，也不得自动反复请求 MTOP 接口。
|
||
- **货憨憨的写操作必须显式确认。** 上传素材、批量修改商品、删除素材都属于写操作，调用方必须明确表达意图，不得作为查询流程的副作用发生。
|
||
- **凭据不进入仓库。** 账号、密码、token、Cookie、Chrome Profile 内容不得出现在代码、日志、工单、Wiki 和提交中。
|
||
- **SQLite 是任务状态的唯一事实来源。** 不允许再用 JSON 文件维护第二份任务状态。
|
||
- **前端不做安全判断。** 按钮禁用只是提示，真正的校验必须在 Go 侧执行。
|