记录 ffprobe 同目录交付与启动预检

2026-10-06 14:15:04 +08:00
parent c0ba75becd
commit 71370ea41b
1 changed files with 216 additions and 1 deletions
@@ -1 +1,216 @@
-test
+# 本地开发与验证
+
+## 跨电脑运行的 ffprobe（2026-10-06）
+
+下载与上传前的视频完整性校验需要 `ffprobe.exe`。将打包后的 `cmsp.exe` 与 `ffprobe.exe` 复制到目标电脑的**同一目录**，无需在目标电脑配置 PATH。程序优先使用同目录文件；开发环境未放同目录文件时才查找 PATH。启动时若缺失或无法运行，界面与运行日志会提示；批量取视频在开始前也会检查，避免逐商品下载后才失败。`build.bat` 只生成 cmsp.exe，不会自动复制 ffprobe.exe；交付时须一并复制，不要复制本机配置、数据库或浏览器 Profile。
+
+## 批量上传并发与选择范围（2026-10-05）
+
+`upload.concurrency` 在本机 `config.yaml` 中配置，默认 1、允许 1—4；`config.example.yaml` 给出示例，参数设置页可修改并保存。旧配置缺字段保持串行；该值与仅控制 CDN 文件下载的 `download.concurrency` 独立。`app_upload.go` 对不同商品有界并行，单商品幂等键、未决操作只查原键、批次互斥及 `succeeded` 才写本地完成状态的规则不变。模拟 HTTP/临时 SQLite 的 `TestUploadBatchRespectsConfiguredConcurrency` 覆盖默认串行和并发 3，配置测试覆盖旧文件默认、保存读回与非法值；真实批量写入及 ERPGo 限流需单独验收。
+
+商品列表搜索、重置、翻页后不沿用隐藏勾选；后台刷新只保留当前页可见 ID。复现“当前筛选 13 条却带入旧选 48 条”时，以列表显示、已选数、确认弹窗及最终调用的同一组 ID 为验收依据。
+
+## 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 保留筛选、清空勾选并回到第一页。普通搜索/重置和翻页也清空旧勾选，后台刷新只保留当前页可见 ID；批量预览与执行使用同一快照。默认/重置为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`：
+
+```powershell
+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 字段示例（不含真实凭据）：
+
+```yaml
+erpgo:
+  base_url: "https://erpgo.example.com"
+  api_key: ""
+```
+
+地址填写服务根路径，客户端追加 /api/v1/integrations/huohanhan；Key 仅通过 X-API-Key 请求头发送，不使用 URL 参数。修改本机配置后重启，或在设置页保存以立即生效。旧配置可读取；未配置时只能查看缓存，刷新查询会提示补齐设置。
+
+从仓库根目录验证：
+
+```powershell
+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 绑定。构建不等于真机界面全部通过验证。
+
+经授权后执行真实只读联调，配置只从本机文件读取：
+
+```powershell
+$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 条件或重复执行无关搜索。
+
+```powershell
+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（`$`）等内容。起始标记后必须立即换行，结束标记必须单独占一行：
+
+```powershell
+@'
+print("hello")
+'@ | python -
+```
+
+`foreach`、`if` 等语句块不能裸放在管道左侧；需要管道输出时使用 `$()`、`@()` 或先赋值。普通命令输出无需包装：
+
+```powershell
+@(foreach ($number in 1..3) { $number }) |
+    Measure-Object
+```
+
+不要把含 `*` 的搜索路径直接作为 `rg` 路径参数。优先传入真实目录，并用 `-g/--glob` 让 ripgrep 筛选路径：
+
+```powershell
+rg -n -g '*.md' 'PowerShell' docs
+```
+
+只有确实需要把实体路径列表交给其他命令时，才使用 `Get-ChildItem` 展开并传递 `.FullName`；不要把 `Get-ChildItem -Filter` 设为所有 `rg` 搜索的固定前置。
+
+## 第一次运行
+
+```powershell
+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 尚未初始化或镜像未同步，按[开发工作流](01-workflow.md)的初始化门禁处理。
+
+### 计划：构建与运行桌面应用
+
+Go 骨架建立后补充，形式如下（尚未验证，不要直接复制使用）：
+
+```powershell
+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 结构变更、并发或删除数据时，必须先确认再执行，不能靠试错获得风险反馈。