Table of Contents

项目档案

基本信息
项目治理模式
DevHarness 来源与基线
子项目与交付单元
建设基线评估
技术栈与运行环境
迁移来源
阅读入口
常用命令
目录边界
环境、配置与凭据
项目专用验收要求

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.

项目档案

本页记录不经常变化、所有维护者都需要知道的信息。它是项目档案的事实来源；仓库内 docs/00-project-profile.md 是只读镜像。

基本信息

项目	内容
项目名称	cmsp
一句话目标	给内部同事一个桌面工具，把货憨憨 ERP 里的 Shopee 商品自动配上从淘宝同款抓取的介绍视频
主要使用者	公司内部运营同事；维护者为项目负责人与 Claude/Codex Agent
Gitea 地址	https://git.ilapage.cn
仓库	`chengma/cmsp`
默认分支	`main`
主要维护者	`ila`
文档适用范围	默认分支当前版本；具体镜像 revision 见每个本地文件头

项目治理模式

项目	当前值
当前治理模式	轻量
选择理由	内部工具、单人开发、不对外交付、无常驻服务、不处理真实个人数据
升级规则	单个任务真实风险高于轻量模式时只升级该任务，不抬高日常门禁
必须升级的任务	货憨憨批量写操作、账号凭据处理、SQLite 结构迁移、并发下载与上传、删除本地视频或线上素材

轻量模式只裁剪工单、原型、测试和文档流程，不取消凭据保护、不可逆操作授权和真实测试证据要求。

DevHarness 来源与基线

项目	内容
DevHarness 来源仓库	`D:/OPC/dev_harness`（对应 `https://git.ilapage.cn/OPC/dev_harness`）
当前基线提交	`40b99387adc184274c43fda5f7efb3746642e27a`
最后接入或升级日期	2026-09-02（接入 `c13f6ad`，同日升级至 `40b9938`，见工单 #1）
项目适配说明	完整保留 Harness 规则与 `dev_scripts/` 工具。治理模式选择轻量。本项目无常驻服务，不创建 `Deployment-and-Operations` 页面；`Deployment-Template` 仅作为模板保留。

子项目与交付单元

子项目 / 交付单元	职责	技术栈	构建与测试	版本与发布方式	规则入口	共享边界
cmsp 桌面应用	商品同步、淘宝以图搜与视频下载、视频上传货憨憨的 GUI 与任务引擎	Go + Wails v2 + Vue 3 + Naive UI + SQLite	计划中，见本地开发与验证	内部分发 Windows 单文件可执行程序，不公开发布	根目录 `AGENTS.md`	无跨仓库契约；依赖货憨憨 ERP 与淘宝的外部接口

当前是单交付单元，不拆分子仓库。

建设基线评估

评估日期 2026-09-02。结论：从零开发业务功能，复用成熟框架与组件，并以一个开源项目作为工程结构参考，不做上游合并。

候选	许可证	结论	原因
Kafka-King	Apache-2.0	作为结构参考采用，不作为上游基线	Wails v2 + Vue3 + Naive UI，侧边导航、配置页、表格多选批量操作与本项目同构，体量适中可读完；但业务领域完全不同，无法二次开发
Tiny RDM	GPL-3.0	仅参考设置页组织与进度事件封装写法，不复制代码	许可证为 GPL-3.0，直接复制代码会带来分发约束；且工程复杂度远高于内部工具需要
flybird-m3u8downloader	见上游仓库	仅参考下载任务队列设计思路	规模小、领域接近，但功能覆盖不足以作为基线

不存在功能与架构高度匹配的完整开源产品，因此从零实现业务功能。参考写法不等于复制代码；如果后续确实需要引入某个项目的源码片段，必须先在工单确认其许可证与保留范围，并在本节登记。

技术栈与运行环境

项目	内容
语言与框架	Go 1.22+、Wails v2、Vue 3、Naive UI
本地状态存储	SQLite（商品、任务、视频、下载与上传状态、货憨憨认证状态）
外部依赖程序	Google Chrome（专属 Profile，用于淘宝登录与 CDP）、`ffprobe`（视频完整性校验）
外部服务	货憨憨 ERP HTTP 接口；淘宝 MTOP 以图搜接口；验证码识别为外部 HTTP OCR 服务
支持环境	Windows 10 及以上；不支持 macOS 与 Linux
开发命令行	PowerShell 7 `pwsh`；不套用 Bash 语法，见本地开发与验证
常驻服务	无。本项目是单机桌面程序，不部署服务端

迁移来源

本项目的业务能力由两份已验证的 Python 实现迁移为 Go。两份来源都在仓库外，只作参考，不纳入本仓库版本管理。

来源	位置	覆盖范围	迁移状态
淘宝流程	`D:\chengma\电商视频自动下载工具\已验证淘宝流程\正式脚本`	专属 Chrome 管理、CDP、登录守卫、MTOP 图搜、详情视频提取、下载与 ffprobe 校验	未开始
货憨憨接口	`D:\chengma\hhh_api`	登录与验证码 OCR、认证状态管理、商品查询、图片上传、批量修改	未开始
淘宝流程 Go 版设计规范	已于 2026-09-02 由负责人删除	专属 Chrome、登录检查、以图搜的目标行为与错误码	结论已并入业务规则与术语

阅读入口

新人从 Home 开始。
目录职责与执行路径见架构与代码地图。
术语与业务规则见业务规则与术语。
需求状态见需求总览。

常用命令

所有命令从仓库根目录 D:\chengma\cmsp 执行。

用途	命令
查看工作区	`git status --short --branch`
检查文档结构	`python dev_scripts/harness.py check --strict`
运行 Harness 自测	`python -m unittest discover -s tests -v`
快速检查 Wiki 镜像	`python dev_scripts/harness.py sync --check`
导出 Wiki 镜像	`python dev_scripts/harness.py sync`

产品构建与测试命令在 Go 项目骨架建立后补入本地开发与验证，本页不重复维护。

目录边界

目录	职责	谁可以改
`docs/`	Gitea Wiki 只读镜像	只能由 `harness.py sync` 生成
`docs/task/`	人工明确要求的专项快照	默认为空
`dev_scripts/`	DevHarness 自身工具	升级 DevHarness 时整体替换；业务脚本不得混放
`tests/`	DevHarness 结构自测	业务测试不放这里
`.gitea/issue_template/`	工单模板	跟随 DevHarness

Go 与前端目录在项目骨架建立后补入架构与代码地图。

环境、配置与凭据

凭据或配置	用途	提供方式
货憨憨账号与密码	登录 ERP 拉取商品、上传视频	由使用者在程序「参数设置」页填写，保存在本机配置文件；不得写入仓库、日志、工单或 Wiki
货憨憨认证 token 与 cookies	复用登录态	运行时保存在本机 SQLite；日志必须脱敏
淘宝登录态	以图搜与访问商品详情	只保存在专属 Chrome Profile 目录，程序不读取、不落盘、不上传
Chrome 可执行文件路径、用户数据目录	启动专属浏览器	「参数设置」页配置，属于路径不属于凭据
OCR 服务地址	识别货憨憨登录验证码	配置项，默认值记录在代码常量中
Gitea token	文档同步	只从进程环境或 MCP 安全配置读取，不得写入仓库

专属 Chrome Profile 目录默认为 %LOCALAPPDATA%\电商视频自动下载工具\淘宝浏览器\默认账号，沿用已验证 Python 流程的路径，避免使用者重新登录。该目录不得提交、打包或共享。

项目专用验收要求

任何提交不得包含账号、密码、token、Cookie 或 Chrome Profile 内容。
涉及货憨憨写操作（上传视频、批量修改商品）的改动必须建工单，并在真实店铺上验证前先说明影响范围。
淘宝登录失效必须中断整批任务，不得降级为单个商品失败后继续，也不得自动重复请求 MTOP 接口。
未真实运行验证的行为必须在工单中写明未验证，不得以「实现完成」代替测试结果。