Table of Contents

架构与代码地图

当前实现状态
项目定位
代码地图
两条主要执行路径

路径一：货憨憨商品同步与视频上传
路径二：淘宝以图搜与视频下载

不可破坏的边界

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

架构与代码地图

当前实现状态

截至 2026-09-02，本仓库还没有产品代码。 本页的目录结构和执行路径是已确认的目标设计，不是既有实现。阅读时必须区分：

当前事实：仓库有 DevHarness 骨架、文档镜像，以及 Go 骨架（Wails 入口 + config / store / logx 三个包，见下方代码地图）。淘宝与货憨憨的业务能力尚未实现，目前只存在于仓库外的两份 Python 参考实现。
目标规范：本页描述的 Go 目录、执行路径和边界。

Go 骨架建立后，本页必须改写为对当前代码的描述，并在工单记录变更。不允许用目标描述宣称现有能力。

项目定位

cmsp 是运行在使用者本机的单机桌面程序，没有服务端，没有多用户，没有权限模型。它是三个外部系统之间的搬运工：

货憨憨 ERP  --拉取-->  cmsp（本机 SQLite）  --上传-->  货憨憨 ERP  --同步-->  Shopee
                          |
                          +--以图搜、抓视频-->  淘宝（专属 Chrome）

程序不直接访问 Shopee。所有写入 Shopee 的内容都经由货憨憨 ERP。

代码地图

目标目录结构：

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 侧返回的状态决定。

两条主要执行路径

路径一：货憨憨商品同步与视频上传

使用者点击「同步数据」
  → app.go 校验参数
  → internal/huohanhan/auth 取得有效认证（复用 SQLite 中的 token，失效则重新登录）
  → internal/huohanhan/product 分页拉取指定 Shopee 店铺商品
  → internal/store 写入或更新商品行
  → 事件推送进度，前端刷新表格

使用者勾选商品点击「上传视频」
  → internal/task 逐个取出本地视频文件
  → internal/huohanhan/upload 上传素材取得线上地址
  → internal/huohanhan/upload 批量更新商品视频
  → internal/store 更新上传状态
  → 事件推送进度

上传链路的接口细节尚未确认，见需求总览的未决项。

路径二：淘宝以图搜与视频下载

使用者勾选商品点击「下载视频」
  → 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 已于 2026-09-02 由负责人删除，其中的稳定结论已并入上述业务规则页，不要再引用那个文件名。

不可破坏的边界

淘宝登录必须由使用者手动完成。 程序只负责打开登录页和检查结果，不自动填写密码、不绕过验证码、不绕过安全验证。
淘宝登录态只存在于专属 Chrome Profile。 程序不读取、不复制、不落盘、不上传 Cookie；只从当前会话读取 _m_h5_tk 用于计算签名，且不缓存、不长期复用、不写入日志。
同一个 Chrome Profile 不得同时启动两个实例。 启动前必须校验 PID 存在、进程命令属于本程序专属 Profile、CDP 端口可访问且存在 page 类型目标。
登录失效是全局停止门。 必须中断整批任务并保留断点，不得记为单商品失败后继续，也不得自动反复请求 MTOP 接口。
货憨憨的写操作必须显式确认。 上传素材、批量修改商品、删除素材都属于写操作，调用方必须明确表达意图，不得作为查询流程的副作用发生。
凭据不进入仓库。 账号、密码、token、Cookie、Chrome Profile 内容不得出现在代码、日志、工单、Wiki 和提交中。
SQLite 是任务状态的唯一事实来源。 不允许再用 JSON 文件维护第二份任务状态。
前端不做安全判断。 按钮禁用只是提示，真正的校验必须在 Go 侧执行。