diff --git a/docs/task/60-修复顺运宝分页总数误判.md b/docs/task/60-修复顺运宝分页总数误判.md new file mode 100644 index 0000000..81b7164 --- /dev/null +++ b/docs/task/60-修复顺运宝分页总数误判.md @@ -0,0 +1,60 @@ +# 60 Admin:修复顺运宝分页总数误判导致同步停止 + +- 类型:缺陷 +- 父级大工单:#14 +- 所属 MVP / 版本:#15 / MVP +- 状态:已完成 +- 日期:2026-08-09 +- Gitea 工单:http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/60 + +## 背景与目标 + +#58 把顺运宝 `list.data.total` 当成日期范围总数,逐页与 `listTotal.data` 比较。 +真实 HAR 证明前者是当前页条数:范围总数为 3846 时,第一页返回 20 行且 +`list.data.total = 20`。因此任意一天超过默认页长 20 条都会被错误报告为总数 +变化并停止。本任务修正字段语义,同时保留防止 offset 分页静默漏单的保护。 + +## 最终方案 + +- `ListPage` 将 `data.total` 明确解释为当前页条数,并要求它等于实际 `list` + 数组长度。 +- 同步服务根据预检总数计算每页预期条数:普通页必须完整,最后一页必须等于 + 剩余条数。 +- 每天所有列表页获取完毕后再次调用 `listTotal`;前后总数不同则停止且不推进 + 游标。 +- 继续要求全部页唯一货运单 ID 数等于预检总数,并保留重复 ID、明细完整性、 + 31 天范围和 10000 条熔断保护。 +- 测试假服务端改为按照真实 HAR 返回当前页条数。方案与建单内容一致。 + +## 改了哪些 + +- `admin/syb/client.go`:纠正 `list.data.total` 语义并校验页内数量。 +- `admin/service/syb.go`:增加每页预期数量和分页前后 `listTotal` 核对。 +- `admin/syb/client_test.go`:补充 `total` 与列表长度不一致的客户端测试。 +- `admin/service/syb_test.go`:修正假响应,覆盖多页、短页、总数变化、重复 ID 和 + 明细缺失。 +- `docs/admin/08-顺运宝接口.md`:记录 HAR 证据和新的完整性校验规则。 + +## 验收结果 + +| 验收标准 | 结果 | +|---|---| +| 多页响应中 `data.total` 为当前页条数时可以完整同步 | 通过 | +| 页内报告条数与实际数组长度不一致时失败且不推进游标 | 通过 | +| 普通页或最后一页数量不符合预期时失败且不推进游标 | 通过 | +| 分页前后 `listTotal` 变化时失败且不推进游标 | 通过 | +| 唯一 ID 不足、重复 ID 和明细不完整保护继续有效 | 通过 | +| 31 天限制和默认 10000 条熔断保持有效 | 通过 | +| HAR 字段语义已写入接口基线 | 通过 | + +## 测试 + +- 执行的命令:在 `admin/` 目录执行 + `$env:GOTOOLCHAIN="go1.23.0"; go build ./...; go test ./... -count=1; go vet ./...; Remove-Item Env:GOTOOLCHAIN` +- 结果:构建通过;全部 Go 测试通过;`go vet` 通过;`git diff --check` 通过。 +- **没验证到的部分**:未使用真实顺运宝账号重跑 2026-08-07 的 874 张货运单; + 自动化测试使用本地 `httptest`,其中 501 张货运单按 20 条分页并成功完成。 + +## 相关提交 + +- `919522f` 修复顺运宝分页总数误判