docs: 归档任务 #60

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` 修复顺运宝分页总数误判