<!-- 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 侧执行。