2.8 KiB
2.8 KiB
60 Admin：修复顺运宝分页总数误判导致同步停止
- 类型：缺陷
- 父级大工单：#14
- 所属 MVP / 版本：#15 / MVP
- 状态：已完成
- 日期：2026-08-09
- Gitea 工单：#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修复顺运宝分页总数误判