<!-- gitea-wiki-mirror:start -->
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Project-Profile
wiki_url: https://git.ilapage.cn/chengma/cmsp/wiki/Project-Profile.-
wiki_revision: 7a6c27d8b2986bc87bc3eabf45fdf3813a9c7764
synchronized_at: 2026-10-07T08:26:23Z
<!-- gitea-wiki-mirror:end -->

# 项目档案

## erpgo 视频上传现状（2026-09-30）

cmsp 的商品查询和指定商品视频上传统一通过 erpgo。旧 huohanhan 配置在本机文件中保留兼容，但不用于请求。真实店铺写入须由使用者指定商品并在上传确认框确认。


## erpgo 查询依赖与配置（2026-09-28）

cmsp 仍为单交付桌面应用，没有自身常驻服务。店铺刷新与商品同步依赖已有 erpgo 服务，由其统一使用服务端配置的货憨憨账号查询。指定商品视频上传也通过 erpgo；cmsp 不再直连货憨憨。

| 本机配置 | 用途与边界 |
|---|---|
| erpgo.base_url | erpgo 服务根地址，包含 http:// 或 https://，不能带用户信息、查询参数或片段 |
| erpgo.api_key | 查询凭据，仅保存在本机 config.yaml；界面默认掩码，不进日志、工单、Wiki 或提交 |
| huohanhan.* | 仅兼容旧 config.yaml；界面不显示，也不用于请求 |

有效 Key 可访问 erpgo 配置账号全部 Shopee 店铺，没有独立只读权限体系。旧配置缺少 erpgo 字段仍可读取；未配置查询凭据时保留本地缓存和上传设置，查询明确失败，不回退另一账号。config.yaml 不提交、不打包或共享。

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

## 基本信息

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

## 项目治理模式

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

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

## 内部系统实施授权（2026-09-28）

本项目为内部系统，不设置独立方案、原型或高风险实施人工确认门禁。用户明确要求实施且目标与预期行为明确时，Agent 完成必要分析后直接推进，不因 API、配置、凭据存取、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 | 计划中，见[本地开发与验证](04-local-development-and-verification.md) | 内部分发 Windows 单文件可执行程序，不公开发布 | 根目录 `AGENTS.md` | 查询消费 erpgo 契约；查询及视频写入均消费 erpgo，淘宝流程仍在本机 |

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

## 建设基线评估

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

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

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

## 技术栈与运行环境

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

## 迁移来源

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

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

## 阅读入口

- 新人从 [Home](README.md) 开始。
- 目录职责与执行路径见[架构与代码地图](02-architecture-and-code-map.md)。
- 术语与业务规则见[业务规则与术语](03-business-rules-and-glossary.md)。
- 需求状态见[需求总览](09-product-requirements-overview.md)。

## 常用命令

所有命令从仓库根目录 `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 项目骨架建立后补入[本地开发与验证](04-local-development-and-verification.md)，本页不重复维护。

## 目录边界

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

Go 与前端目录在项目骨架建立后补入[架构与代码地图](02-architecture-and-code-map.md)。

## 环境、配置与凭据

| 凭据或配置 | 用途 | 提供方式 |
|---|---|---|
| erpgo API Key | 商品查询与指定商品视频上传 | 在「参数设置」页填写，仅保存在本机 config.yaml，界面掩码显示；不得写入仓库、日志、工单或 Wiki |
| 历史货憨憨配置与认证数据 | 兼容旧本机文件与数据库 | 不再参与运行时请求，不自动删除；日志必须脱敏 |
| 淘宝登录态 | 以图搜与访问商品详情 | 只保存在专属 Chrome Profile 目录，程序不读取、不落盘、不上传 |
| Chrome 可执行文件路径、用户数据目录 | 启动专属浏览器 | 「参数设置」页配置，属于路径不属于凭据 |
| 历史 OCR 服务地址 | 兼容旧配置 | 不再参与运行时请求 |
| Gitea token | 文档同步 | 只从进程环境或 MCP 安全配置读取，**不得写入仓库** |

淘宝与 1688 共用的专属 Chrome Profile 默认位于 `config.yaml` 所在目录下的 `运行数据/浏览器/淘宝1688`；开发模式在项目根目录，打包版在 exe 旁，不落入可清理的 `build/bin`。改变旧目录后需分别手动重新登录，原 Profile 不自动迁移或删除。该目录不得提交、打包或共享。

## 项目专用验收要求

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