cmsp/docs/04-local-development-and-verification.md

generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Local-Development-and-Verification wiki_url: https://git.ilapage.cn/chengma/cmsp/wiki/Local-Development-and-Verification.- wiki_revision: 023ef74aa74316cd47ee50757d356634ddd37c41 synchronized_at: 2026-09-30T01:39:57Z

本地开发与验证

erpgo 视频上传验证（2026-09-30）

运行 go test ./...、go test -race ./...、go vet ./...、npm --prefix frontend run build 和 Wails 构建。模拟 HTTP 和临时 SQLite 覆盖 multipart video、X-API-Key、幂等键、结果查询、成功落库及 unknown 不重发；真实店铺写入与 Shopee 页面生效需单独验收。

全店铺同步验证（2026-09-29，#26）

internal/erpgo/sync_test.go 使用模拟HTTP与临时SQLite验证最新店铺列表、串行店铺/分页、每店完整提交、同店ID去重、分页及本地事务失败继续、全局错误/取消停止、空店铺/列表失败、跨店ID冲突，以及诊断、下载/上传状态和已上传视频记录保留。app_sync_test.go 验证单店请求及Go侧重叠同步拒绝。

验证命令：go test ./...、go test -race ./...、go vet ./...；Windows 使用 Wails 构建生成绑定及前端资源。模拟测试及构建不等于真实全店铺联调或 Windows WebView2/Narrator/高对比度/DPI验收；本次没有对真实全部店铺落库，没有淘宝访问或外部写操作。默认真实联调测试仍只处理首个店铺的临时数据库，不自动扩大为全部店铺。

每页500条边界验证（2026-09-29）

internal/store/product_test.go 使用501条虚构匹配记录和1条不匹配记录，验证20/50/100/200/500五档有效、无效值回退20、500条末页1条、随后空页、分页不重叠与总数一致。前端使用已安装Naive UI分页控件的showSizePicker/pageSizes/onUpdate:pageSize契约；changePageSize 保留筛选、清空勾选并回到第一页。默认/重置为20。

执行 go test ./...、go vet ./...、前端构建及 wails build -o cmsp25.exe。构建及数据库测试不代替Windows实际下拉、键盘、Narrator、高对比度/显示缩放或每页500条的真机响应体验验收。

缺少视频与未下载组合筛选验证（2026-09-29）

internal/store/product_test.go 的组合筛选测试使用虚构数据和临时 SQLite，覆盖 pending/failed 包含、running/done 排除、全部及单状态、视频诊断/店铺/在售/上传交集、过滤后 COUNT 与分页一致、旧空条件兼容、参数化查询以及查询前后状态不变。未下载只依赖 SQLite 状态，不以文件是否存在判定。

前端默认和重置都是在售中 + 缺少视频 + 未下载（含失败）；下载状态控件位于类型与上传之间，使用标准下拉和现有自动换行布局。点击搜索应用，切换全部可恢复查看已下载记录。验证 go test ./...、go vet ./...、前端构建及 wails build -o cmsp24.exe。构建和 SQLite 测试不代替 Windows WebView2、Narrator、高对比度、不同显示缩放及键盘的真机验收。

商品原链接验证（2026-09-29）

internal/taobao/imagesearch_test.go 验证 auctionURL 参数保留、缺失字段兼容、非法链接候选跳过及全部非法时明确报错；detail_test.go 验证淘宝/天猫域名、商品 ID 匹配、拒绝恶意域名/重复 ID/错误编码/用户信息/其他端口及片段、原链接导航、缓存复用和受限后停止。app_video_test.go 的 SQLite 停止场景包含天猫原链接，验证商品、视频、上传及剩余队列状态保留。常规测试不访问淘宝。

从根目录执行 go test ./...、go test -race ./...、go vet ./...；Windows 构建可用 & "$env:USERPROFILE\go\bin\wails.exe" build -o cmsp23.exe。不要与正在更新前端嵌入资源的构建同时运行 Go 测试。真实联调须先确认专属浏览器归属、登录检查通过且没有进行中的下载任务；只读 SQLite，响应只分析必要字段名/链接结构，不落盘原始响应与凭据。遇到请求或访问异常即停止，不为验证重复请求。

淘宝风控停止门验证（2026-09-29）

从仓库根目录先完成前端资源构建，再执行嵌入这些资源的 Go 测试，避免两者同时更新/读取 frontend/dist：

npm --prefix frontend run build
go test ./...
go test -race ./...
go vet ./...
& "$env:USERPROFILE\go\bin\wails.exe" build -o cmsp22.exe

-race 需要本机支持 CGO 的 C 编译器。app_video_test.go 使用临时 SQLite 和模拟页面，覆盖同批多商品只深度检查一次、后续当前页面守卫不导航且在图搜前停止，以及深度检查、图搜、详情及疑似风控停止后的状态保留。internal/taobao/access_test.go 覆盖批次首次检查、新批次重新深度检查、后续登录/风控重定向、Cookie 缺失、页面读取/JSON 失败，以及明确提示、同批去重/复用、候选上限与可取消等待；internal/task/task_test.go 覆盖停批不计失败及保留当前位置。测试不打开真实专属 Profile、不向淘宝发请求、不写真实店铺。

新默认配置为 search_top_n=5、wait_seconds_min=10、wait_seconds_max=20，旧明确配置保持兼容。本次本机旧组合 20/2/4 已按用户授权改为新参数，仅修改这三个数值，未改变其他字段和凭据。平台恢复时间、真实风控触发率及 Windows WebView2 实际提示须由用户恢复访问后观察，模拟测试不能证明平台解除限制。

erpgo 查询配置与验证（2026-09-28）

内部使用者从「参数设置 → erpgo 商品查询与视频上传」填写服务根地址和 API Key，再点击「保存设置」。Key 默认遮蔽，可主动查看；保存失败保留输入。旧 huohanhan 配置只为兼容本机文件保留，界面不再显示，也不用于请求。

本机 YAML 字段示例（不含真实凭据）：

erpgo:
  base_url: "https://erpgo.example.com"
  api_key: ""

地址填写服务根路径，客户端追加 /api/v1/integrations/huohanhan；Key 仅通过 X-API-Key 请求头发送，不使用 URL 参数。修改本机配置后重启，或在设置页保存以立即生效。旧配置可读取；未配置时只能查看缓存，刷新查询会提示补齐设置。

从仓库根目录验证：

go test ./...
go vet ./...
go build -o "$env:TEMP\cmsp-check.exe" .
npm --prefix frontend run build
& "$env:USERPROFILE\goin\wails.exe" build
python dev_scripts/harness.py check --strict

Wails CLI 路径以实际安装为准；当前代码已在 Windows 使用 v2.16.0 构建验证，CLI 生成 frontend/wailsjs/go 绑定。构建不等于真机界面全部通过验证。

经授权后执行真实只读联调，配置只从本机文件读取：

$env:CMSP_ERPGo_LIVE_CONFIG = Join-Path (Get-Location) 'config.yaml'
go test . -run TestERPGoLiveReadOnlySync -v -count=1 -timeout 10m
Remove-Item Env:CMSP_ERPGo_LIVE_CONFIG

该测试读取店铺及首个店铺全部在售商品，只写临时 SQLite，验证商品/诊断落库与状态保留及数据库重开；不修改现有数据库，不上传或修改真实店铺。默认 go test 不执行该联调。浏览器模拟只能证明设置控件和错误展示，不能代替 Windows WebView2、Narrator、高对比度或真实上传验收。

当前可执行范围

产品代码尚未建立。 目前本仓库只能执行文档结构检查与 Harness 自测。下面标注「计划」的命令在 Go 骨架建立前无法运行，建立后必须回到本页把它们改成经过实际运行验证的命令，并删除「计划」标注。

环境要求

依赖	版本	用途	当前是否必需
Python	3.10 及以上	运行 dev_scripts/harness.py 文档工具	是
Git	任意近期版本	版本管理	是
Go	1.22 及以上	编译后端	计划
Node.js	20 及以上	编译前端	计划
Wails CLI	v2 最新稳定版	构建桌面应用	计划
Google Chrome	近期稳定版	专属浏览器，登录淘宝并提供 CDP	计划
ffprobe	任意近期版本	校验下载的 MP4 是否完整	计划

运行环境为 Windows 10 及以上。不支持 macOS 与 Linux。

Windows PowerShell 与 UTF-8

• 优先使用当前已配置的 PowerShell；可选择时使用 PowerShell 7 pwsh.exe。
• 不要为了设置编码额外再启动一层 PowerShell。
• 文档与源码统一使用 UTF-8。命令支持时显式指定编码，例如 Get-Content -Encoding utf8。
• 只有确实出现乱码时才调整当前进程的输出编码，不要默认设置。
• 不使用 -ExecutionPolicy Bypass。确有可信 .ps1 被执行策略阻止且没有更小替代方案时，才对该次进程使用并在工单记录原因。

PowerShell 语法与外部命令

• Windows 环境默认使用当前 PowerShell 语法，不套用 Bash 的 heredoc、变量、路径、引号或反斜杠转义规则。只有明确调用 Bash、WSL 或 Git Bash，并确认路径与编码边界时，才使用 Bash 专用语法。
• 不需要变量展开的正则和字符串优先用单引号；单引号字符串内部的单引号写成两个单引号。需要变量展开时才使用双引号。
• 正则同时包含单双引号或转义复杂时，优先赋值给变量、使用 rg -e，或拆成语义等价的简单查询；不得为了避开转义改变 AND/OR 条件或重复执行无关搜索。

rg -n 'error|warning' docs
$pattern = 'can''t match "value"'
rg -n -e $pattern docs

PowerShell 不支持 Bash heredoc。需要把多行 Python 送入标准输入时，使用单引号 here-string，避免 PowerShell 展开 Python 中的 dollar sign（$）等内容。起始标记后必须立即换行，结束标记必须单独占一行：

@'
print("hello")
'@ | python -

foreach、if 等语句块不能裸放在管道左侧；需要管道输出时使用 $()、@() 或先赋值。普通命令输出无需包装：

@(foreach ($number in 1..3) { $number }) |
    Measure-Object

不要把含 * 的搜索路径直接作为 rg 路径参数。优先传入真实目录，并用 -g/--glob 让 ripgrep 筛选路径：

rg -n -g '*.md' 'PowerShell' docs

只有确实需要把实体路径列表交给其他命令时，才使用 Get-ChildItem 展开并传递 .FullName；不要把 Get-ChildItem -Filter 设为所有 rg 搜索的固定前置。

第一次运行

cd D:\chengma\cmsp
git status --short --branch
python dev_scripts/harness.py check --strict
python -m unittest discover -s tests -v

预期结果：

• git status 显示当前分支，且没有意料之外的改动。
• check --strict 输出检查通过，没有缺失文件或缺失章节。
• 单元测试全部通过。

如果 check --strict 报告镜像 revision 无效，说明 Wiki 尚未初始化或镜像未同步，按开发工作流的初始化门禁处理。

计划：构建与运行桌面应用

Go 骨架建立后补充，形式如下（尚未验证，不要直接复制使用）：

wails dev     # 开发模式，热重载
wails build   # 产出 Windows 可执行文件
go test ./... # 后端单元测试

常用调试方式

文档与流程

目的	命令	说明
检查文档结构	python dev_scripts/harness.py check --strict	检查必需文件与固定章节
快速核对 Wiki 镜像	python dev_scripts/harness.py sync --check	只比对 revision，不下载正文
完整核对镜像正文	python dev_scripts/harness.py sync --deep-check	怀疑镜像损坏时使用
导出镜像	python dev_scripts/harness.py sync	只能 Wiki → docs/，没有反向同步

计划：淘宝链路调试

Go 实现完成后适用：

• 专属 Chrome 是否就绪：访问 http://127.0.0.1:<端口>/json/version，能返回 JSON 即调试端口正常。
• 是否存在可用页面：访问 http://127.0.0.1:<端口>/json/list，检查是否有 type 为 page 的目标。
• 登录是否有效：在界面点击「检查登录状态」，看返回的缺失 Cookie 名称、页面标题与阻断词。
• 图搜是否成功：查看任务日志中的 HTTP 状态码与业务返回码，不要打印完整响应正文。

调试时禁止打印完整 Cookie、_m_h5_tk 完整值、账号密码和完整签名原文。

完成修改前

按顺序完成，缺一项就不算完成：

1. git status --short --branch 确认只包含本次任务相关文件。
2. 运行与改动范围相称的测试，并记录真实结果；没有跑到的部分明确写出未验证。
3. 判断是否有长期文档影响。有则先改 Gitea Wiki，读取确认，再 python dev_scripts/harness.py sync 导出镜像并检查差异；没有则记录原因。
4. python dev_scripts/harness.py check --strict 通过。
5. 提交只包含本次任务文件；有工单时提交信息带工单号，例如 feat: 商品列表分页 (#12)。
6. 有工单的任务在工单追加最终证据评论，状态置为「待验收」，等待人工验收。

涉及货憨憨写操作、账号凭据、SQLite 结构变更、并发或删除数据时，必须先确认再执行，不能靠试错获得风险反馈。