8.6 KiB
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: 9757a12d42f1f824ea906f5729d8ced09f0ccf0e synchronized_at: 2026-09-28T09:47:38Z
架构与代码地图
当前查询调用链（2026-09-28）
本节描述已实现的店铺/商品查询路径，优先于本页历史目标设计中的直连查询描述。视频上传与淘宝流程沿用原实现。
参数设置 → internal/config（erpgo 服务地址、API Key）
RefreshShops → internal/erpgo.Client.ListShops
→ GET /api/v1/integrations/huohanhan/shops
→ internal/store.ReplaceShops（同一事务替换本地店铺缓存）
DownloadProductData → internal/erpgo.Client.DownloadAllProducts
→ GET /api/v1/integrations/huohanhan/products（指定店铺，串行分页）
→ 完整校验并按内部商品 id 去重
→ internal/store.SyncProducts（商品和诊断同一事务）
→ 前端刷新本地商品列表
主要入口是 app.go 的 RefreshShops、DownloadProductData；internal/erpgo/client.go 负责白名单转换、稳定错误码及分页完整性；internal/store/product.go 的 SyncProducts 使用与诊断仓储共用的事务辅助函数，不改变 SQLite 表结构。
查询只读取货憨憨现有数据，不触发 Shopee 同步；不自动回退直连。任何请求/校验失败不返回可落库的部分数据；数据库失败回滚商品与诊断。下载、上传、视频记录和断点状态保留，不依据列表删除商品。internal/huohanhan 仍用于现有视频上传，原客户端代码保留用于回归与回退。
当前实现状态
历史设计基线截至 2026-09-02；当前查询实现见上方 2026-09-28 专节。 本页的目录结构和执行路径是已确认的目标设计，不是既有实现。阅读时必须区分：
- 当前事实：仓库有 DevHarness 骨架、文档镜像，以及 Go 骨架（Wails 入口 + config / store / logx 三个包，见下方代码地图）。淘宝与货憨憨的业务能力尚未实现，目前只存在于仓库外的两份 Python 参考实现。
- 目标规范：本页描述的 Go 目录、执行路径和边界。
Go 骨架建立后，本页必须改写为对当前代码的描述，并在工单记录变更。不允许用目标描述宣称现有能力。
项目定位
cmsp 是运行在使用者本机的单机桌面程序，没有服务端，没有多用户，没有权限模型。它是三个外部系统之间的搬运工：
货憨憨 ERP --查询--> erpgo --拉取--> cmsp（本机 SQLite） --上传--> 货憨憨 ERP --同步--> Shopee
|
+--以图搜、抓视频--> 淘宝（专属 Chrome）
程序不直接访问 Shopee。所有写入 Shopee 的内容都经由货憨憨 ERP。
代码地图
目标目录结构：
cmsp/
├─ main.go Wails 应用入口
├─ app.go 暴露给前端的方法，只做参数校验和转发
├─ internal/
│ ├─ config/ 参数设置的读取、校验与持久化
│ ├─ store/ SQLite 打开、迁移与仓储；商品、任务、视频、认证状态
│ ├─ erpgo/ 店铺/商品只读查询、字段转换与分页校验
│ ├─ 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/erpgo 使用 X-API-Key 调用查询接口
→ 串行分页并完整校验指定 Shopee 店铺在售商品
→ internal/store.SyncProducts 同一事务保存商品和诊断
→ 事件推送进度，前端刷新表格
使用者勾选商品点击「上传视频」
→ 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 侧执行。