Admin：修复顺运宝分页总数误判导致同步停止 #60

New Issue

2026-08-09T18:58:03+08:00

ila commented

2026-08-09 18:58:03 +08:00

基本信息

类型：缺陷
父级大工单：#14
所属 MVP / 版本：#15 Admin 四模块可用闭环
阶段：顺运宝货运单与采购任务
依赖：#58、#59
状态：已完成

要解决什么

#58 将顺运宝 /am/stock/list 响应的 data.total 当成筛选范围总数，并逐页与 /am/stock/listTotal 的预检总数比较。

真实 HAR 已确认：

/am/stock/listTotal 的 data 是筛选范围总数；
/am/stock/list 第一页返回 20 行时，data.total = 20，表示当前页返回条数；
当某天总数为 874 时，现有代码错误比较 874 != 20，报告“分页期间从 874 变为 20”并停止同步。

因此每天超过一页（默认 20 条）都会确定性失败，并非顺运宝数据真的漂移。

做什么 / 不做什么

做：
- 按当前页数量解释和校验 list.data.total。
- 普通页必须为完整页，最后一页必须等于预期剩余条数。
- 每天分页完成后再次调用 listTotal，与分页前预检总数比较。
- 保留唯一货运单 ID 数必须等于预检总数、重复 ID 失败、明细完整性失败和不推进游标规则。
- 修正 httptest 假服务端，使其按 HAR 返回当前页数量。
- 更新顺运宝接口基线和任务测试。
不做：
- 不放宽 31 天、10000 条上限。
- 不改变顺运宝请求参数、每页 20 条或明细每批 100 个 ID。
- 不修改同步记录表、Client 四接口、采购和下单逻辑。
- 自动化测试不请求真实顺运宝。

怎么做

admin/syb/client.go 将 ListPage 返回值明确为当前页报告条数，并要求它与实际 list 长度一致。
admin/service/syb.go 删除“页内 total 等于当日总数”的错误比较；按预检总数计算每页预期条数，拒绝短页、超长页。
每个日期列表翻页完成后重新调用 ListTotal，前后总数不同则失败；随后继续核对唯一 ID 总数。
修改 admin/syb/client_test.go、admin/service/syb_test.go 的假响应及回归用例，覆盖 874/20 同类多页场景、短页、前后总数变化、重复 ID。
更新 docs/admin/08-顺运宝接口.md，纠正字段语义和完整性策略。

验收标准

当日总数大于 20、每页 data.total 为当前页条数时可以完整翻页，不再误报总数从 N 变为 20。
list.data.total 与实际 list 长度不一致时失败且不推进游标。
非最后一页短页、最后一页数量不符时失败且不推进游标。
分页前后 listTotal 变化时失败且不推进游标。
分页后的唯一货运单 ID 数不等于预检总数时失败且不推进游标。
重复 ID、明细不完整、31 天限制和 10000 条熔断保护保持有效。
HAR 字段语义写入 Admin 顺运宝接口基线。
Go 1.23.0 go build ./...、go test ./... -count=1、go vet ./... 通过。

怎么验证

从 admin/ 执行：

$env:GOTOOLCHAIN="go1.23.0"
go build ./...
go test ./... -count=1
go vet ./...
Remove-Item Env:GOTOOLCHAIN

测试使用 httptest，不连接真实顺运宝接口。

风险和回退

若把最后一页数量规则写错，可能造成误报；测试覆盖整页、尾页和空页边界。
分页前后总数一致仍无法证明服务端数据集合完全不变，但结合唯一 ID、重复 ID 和明细覆盖校验，可防住当前 offset 分页的主要漏单方式。
回退本提交会恢复“每天超过 20 条必然失败”的旧行为，不涉及数据库回退。

## 基本信息 - 类型：缺陷 - 父级大工单：#14 - 所属 MVP / 版本：#15 Admin 四模块可用闭环 - 阶段：顺运宝货运单与采购任务 - 依赖：#58、#59 - 状态：已完成 ## 要解决什么 #58 将顺运宝 `/am/stock/list` 响应的 `data.total` 当成筛选范围总数，并逐页与 `/am/stock/listTotal` 的预检总数比较。真实 HAR 已确认： - `/am/stock/listTotal` 的 `data` 是筛选范围总数； - `/am/stock/list` 第一页返回 20 行时，`data.total = 20`，表示当前页返回条数； - 当某天总数为 874 时，现有代码错误比较 `874 != 20`，报告“分页期间从 874 变为 20”并停止同步。因此每天超过一页（默认 20 条）都会确定性失败，并非顺运宝数据真的漂移。 ## 做什么 / 不做什么 - 做： - 按当前页数量解释和校验 `list.data.total`。 - 普通页必须为完整页，最后一页必须等于预期剩余条数。 - 每天分页完成后再次调用 `listTotal`，与分页前预检总数比较。 - 保留唯一货运单 ID 数必须等于预检总数、重复 ID 失败、明细完整性失败和不推进游标规则。 - 修正 `httptest` 假服务端，使其按 HAR 返回当前页数量。 - 更新顺运宝接口基线和任务测试。 - 不做： - 不放宽 31 天、10000 条上限。 - 不改变顺运宝请求参数、每页 20 条或明细每批 100 个 ID。 - 不修改同步记录表、Client 四接口、采购和下单逻辑。 - 自动化测试不请求真实顺运宝。 ## 怎么做 1. `admin/syb/client.go` 将 `ListPage` 返回值明确为当前页报告条数，并要求它与实际 `list` 长度一致。 2. `admin/service/syb.go` 删除“页内 total 等于当日总数”的错误比较；按预检总数计算每页预期条数，拒绝短页、超长页。 3. 每个日期列表翻页完成后重新调用 `ListTotal`，前后总数不同则失败；随后继续核对唯一 ID 总数。 4. 修改 `admin/syb/client_test.go`、`admin/service/syb_test.go` 的假响应及回归用例，覆盖 874/20 同类多页场景、短页、前后总数变化、重复 ID。 5. 更新 `docs/admin/08-顺运宝接口.md`，纠正字段语义和完整性策略。 ## 验收标准 - [x] 当日总数大于 20、每页 `data.total` 为当前页条数时可以完整翻页，不再误报总数从 N 变为 20。 - [x] `list.data.total` 与实际 `list` 长度不一致时失败且不推进游标。 - [x] 非最后一页短页、最后一页数量不符时失败且不推进游标。 - [x] 分页前后 `listTotal` 变化时失败且不推进游标。 - [x] 分页后的唯一货运单 ID 数不等于预检总数时失败且不推进游标。 - [x] 重复 ID、明细不完整、31 天限制和 10000 条熔断保护保持有效。 - [x] HAR 字段语义写入 Admin 顺运宝接口基线。 - [x] Go 1.23.0 `go build ./...`、`go test ./... -count=1`、`go vet ./...` 通过。 ## 怎么验证从 `admin/` 执行： ```powershell $env:GOTOOLCHAIN="go1.23.0" go build ./... go test ./... -count=1 go vet ./... Remove-Item Env:GOTOOLCHAIN ``` 测试使用 `httptest`，不连接真实顺运宝接口。 ## 风险和回退 - 若把最后一页数量规则写错，可能造成误报；测试覆盖整页、尾页和空页边界。 - 分页前后总数一致仍无法证明服务端数据集合完全不变，但结合唯一 ID、重复 ID 和明细覆盖校验，可防住当前 offset 分页的主要漏单方式。 - 回退本提交会恢复“每天超过 20 条必然失败”的旧行为，不涉及数据库回退。

ila referenced this issue

2026-08-09 18:58:20 +08:00

[Epic] Admin 采集采购管理端 #14

ila referenced this issue

2026-08-09 18:58:20 +08:00

[MVP] Admin 四模块可用闭环 #15

ila commented

2026-08-09 18:58:21 +08:00

已开始实施。将只修改 Admin 顺运宝分页解析、同步编排、测试和接口文档；保留工作区现有 Client、.gitignore 和脚本改动，自动化不访问真实顺运宝。

已开始实施。将只修改 Admin 顺运宝分页解析、同步编排、测试和接口文档；保留工作区现有 Client、`.gitignore` 和脚本改动，自动化不访问真实顺运宝。

ila commented

2026-08-09 19:01:47 +08:00

实施完成，等待用户验收

实现提交：919522f
归档提交：59d70b2
归档：docs/task/60-修复顺运宝分页总数误判.md

最终校验：

go build ./...：通过
go test ./... -count=1：通过
go vet ./...：通过
git diff --check：通过

回归覆盖：假服务端按 HAR 返回“当前页 total”，501 张货运单以 20 条分页可成功同步；页内数量不一致、短页、分页前后总数变化、重复 ID、唯一 ID 不足及明细缺失继续失败且不推进游标。

未验证：没有连接真实顺运宝账号重跑 2026-08-07 的 874 张货运单。工单保持打开，待用户验收后关闭并同步 #14/#15。

## 实施完成，等待用户验收 - 实现提交：`919522f` - 归档提交：`59d70b2` - 归档：`docs/task/60-修复顺运宝分页总数误判.md` 最终校验： - `go build ./...`：通过 - `go test ./... -count=1`：通过 - `go vet ./...`：通过 - `git diff --check`：通过回归覆盖：假服务端按 HAR 返回“当前页 total”，501 张货运单以 20 条分页可成功同步；页内数量不一致、短页、分页前后总数变化、重复 ID、唯一 ID 不足及明细缺失继续失败且不推进游标。未验证：没有连接真实顺运宝账号重跑 2026-08-07 的 874 张货运单。工单保持打开，待用户验收后关闭并同步 #14/#15。

ila commented

2026-08-09 21:16:44 +08:00

用户已于 2026-08-09 明确通过全部 Admin 待验收工单。本工单验收通过，现关闭，并同步父级 #15、#14 的任务清单。

ila closed this issue

2026-08-09 21:16:47 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: chengma/cmautobuy#60