Admin：顺运宝只读分页超时增加当前页有限重试 #300

New Issue

2026-08-24T17:37:24+08:00

ila commented

2026-08-24 17:37:24 +08:00

基本信息

类型：缺陷
父级大工单：#14
所属 MVP / 版本：#15 / Admin 四模块可用闭环
阶段：顺运宝同步稳定性

要解决什么

生产同步日期范围 2026-08-23～2026-08-24 时连续三次在 2026-08-23 第 45 页失败：前 44 页已获取 880/894 张，第 45 页 POST /am/stock/list 连续 30 秒未返回响应头并触发 Client.Timeout。三次失败位置完全一致，最新同步记录的 stock/detail/created/updated 均为 0，游标未推进。

当前顺运宝客户端单请求总超时固定 30 秒；listTotal、list、detail/listByStock 发生网络超时、响应读取失败或临时 5xx 时不做页级重试。历史日期因此立即失败，操作员再次点击会从当天第 1 页重新请求，重复给远端制造负载。

做什么 / 不做什么

做：把顺运宝 HTTP 单请求总超时从 30 秒提高到 60 秒。
做：只对 listTotal、list、detail/listByStock 这三类只读货运查询增加最多 3 次的当前请求重试，重试间隔为 1 秒、2 秒，并支持 context 取消。
做：网络连接/超时、响应体读取失败和 HTTP 5xx 才允许重试；错误信息保留接口路径和最终失败原因，并标明已尝试次数。
做：重试仍复用同一个 Cookie Jar、请求参数和当前页/当前明细批次；外层页码、分页前后总数、页长、唯一 ID、明细一一对应及游标门禁保持不变。
做：更新顺运宝接口基线，明确只读重试与真实写入绝不重试的边界。
不做：不重试登录、验证码、会话业务失败、401/403、非 5xx HTTP 状态、非法 JSON、业务信封失败、分页/明细格式或完整性错误。
不做：不自动重试删除入库码、新增明细和写入快递单号等真实写请求。
不做：不修改 MySQL schema、Admin/Client 接口、页面结构、同步游标规则、店铺准入规则或 page_size。
不做：本工单不部署生产；实现完成后另建部署工单。

怎么做

在 admin/syb/client.go 中给可重试的传输/临时服务错误增加内部类型判断；非法 JSON 与业务错误继续作为不可重试错误。
增加只读请求封装，最多 3 次调用现有统一 do，使用 1 秒、2 秒退避；等待期间监听调用方 context。
ListTotal、日期/单号 listPage、DetailListByStock 改用只读封装。登录、会话检查和三个真实写入方法继续直接调用 do。
单请求总超时提高到 60 秒；不新增网页配置项，避免采购员误配。
在 admin/syb/client_test.go 覆盖相同第 45 页超时/5xx后成功、三次耗尽、context 取消、401/业务/格式错误不重试，以及真实写请求仍只发送一次。
更新 docs/admin/08-顺运宝接口.md 的分页和写入边界。

预计修改：

admin/syb/client.go
admin/syb/client_test.go
docs/admin/08-顺运宝接口.md

不涉及数据库迁移和 Client。

验收标准

/am/stock/list 第 45 页首次或第二次发生超时/5xx时，只重试同一页，请求参数不变化；成功后继续同步。
listTotal 与 detail/listByStock 使用相同的只读重试边界。
单次请求超时为 60 秒，单个只读请求最多 3 次，退避支持 context 取消。
401/403、业务失败、非法 JSON、分页条数/唯一 ID/明细完整性错误不重试。
登录、验证码、会话校验和真实顺运宝写请求不自动重试；写入结果未知门禁保持不变。
重试耗尽后的错误包含接口、尝试次数和最后一次具体原因，仍不推进同步游标。
现有逐日分页、容量、店铺、明细完整性和游标测试保持通过。
Go 1.23.0 下 go test ./...、go build ./...、go vet ./... 全部通过。
不修改数据库结构、Admin/Client 接口、页面、凭据或生产业务数据。

怎么验证

从 admin/ 执行：

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

测试全部使用 httptest，禁止调用真实顺运宝站点。

风险和回退

风险：最坏情况下一个持续超时的只读请求最多等待约 183 秒；页面已使用后台同步记录，不阻塞浏览器请求。
风险：今天重试期间列表可能变化；现有分页后总数、唯一 ID 和明细完整性检查继续负责拦截，不因重试放宽。
风险：把重试误加到写接口会造成重复真实写入；测试必须统计写请求只有一次。
回退：恢复只读方法直接调用 do 并把超时改回 30 秒即可；无 schema 和数据回退。

## 基本信息 - 类型：缺陷 - 父级大工单：#14 - 所属 MVP / 版本：#15 / Admin 四模块可用闭环 - 阶段：顺运宝同步稳定性 ## 要解决什么生产同步日期范围 2026-08-23～2026-08-24 时连续三次在 2026-08-23 第 45 页失败：前 44 页已获取 880/894 张，第 45 页 `POST /am/stock/list` 连续 30 秒未返回响应头并触发 `Client.Timeout`。三次失败位置完全一致，最新同步记录的 stock/detail/created/updated 均为 0，游标未推进。当前顺运宝客户端单请求总超时固定 30 秒；`listTotal`、`list`、`detail/listByStock` 发生网络超时、响应读取失败或临时 5xx 时不做页级重试。历史日期因此立即失败，操作员再次点击会从当天第 1 页重新请求，重复给远端制造负载。 ## 做什么 / 不做什么 - 做：把顺运宝 HTTP 单请求总超时从 30 秒提高到 60 秒。 - 做：只对 `listTotal`、`list`、`detail/listByStock` 这三类只读货运查询增加最多 3 次的当前请求重试，重试间隔为 1 秒、2 秒，并支持 context 取消。 - 做：网络连接/超时、响应体读取失败和 HTTP 5xx 才允许重试；错误信息保留接口路径和最终失败原因，并标明已尝试次数。 - 做：重试仍复用同一个 Cookie Jar、请求参数和当前页/当前明细批次；外层页码、分页前后总数、页长、唯一 ID、明细一一对应及游标门禁保持不变。 - 做：更新顺运宝接口基线，明确只读重试与真实写入绝不重试的边界。 - 不做：不重试登录、验证码、会话业务失败、401/403、非 5xx HTTP 状态、非法 JSON、业务信封失败、分页/明细格式或完整性错误。 - 不做：不自动重试删除入库码、新增明细和写入快递单号等真实写请求。 - 不做：不修改 MySQL schema、Admin/Client 接口、页面结构、同步游标规则、店铺准入规则或 `page_size`。 - 不做：本工单不部署生产；实现完成后另建部署工单。 ## 怎么做 1. 在 `admin/syb/client.go` 中给可重试的传输/临时服务错误增加内部类型判断；非法 JSON 与业务错误继续作为不可重试错误。 2. 增加只读请求封装，最多 3 次调用现有统一 `do`，使用 1 秒、2 秒退避；等待期间监听调用方 context。 3. `ListTotal`、日期/单号 `listPage`、`DetailListByStock` 改用只读封装。登录、会话检查和三个真实写入方法继续直接调用 `do`。 4. 单请求总超时提高到 60 秒；不新增网页配置项，避免采购员误配。 5. 在 `admin/syb/client_test.go` 覆盖相同第 45 页超时/5xx后成功、三次耗尽、context 取消、401/业务/格式错误不重试，以及真实写请求仍只发送一次。 6. 更新 `docs/admin/08-顺运宝接口.md` 的分页和写入边界。预计修改： - `admin/syb/client.go` - `admin/syb/client_test.go` - `docs/admin/08-顺运宝接口.md` 不涉及数据库迁移和 Client。 ## 验收标准 - [x] `/am/stock/list` 第 45 页首次或第二次发生超时/5xx时，只重试同一页，请求参数不变化；成功后继续同步。 - [x] `listTotal` 与 `detail/listByStock` 使用相同的只读重试边界。 - [x] 单次请求超时为 60 秒，单个只读请求最多 3 次，退避支持 context 取消。 - [x] 401/403、业务失败、非法 JSON、分页条数/唯一 ID/明细完整性错误不重试。 - [x] 登录、验证码、会话校验和真实顺运宝写请求不自动重试；写入结果未知门禁保持不变。 - [x] 重试耗尽后的错误包含接口、尝试次数和最后一次具体原因，仍不推进同步游标。 - [x] 现有逐日分页、容量、店铺、明细完整性和游标测试保持通过。 - [x] Go 1.23.0 下 `go test ./...`、`go build ./...`、`go vet ./...` 全部通过。 - [x] 不修改数据库结构、Admin/Client 接口、页面、凭据或生产业务数据。 ## 怎么验证从 `admin/` 执行： ```powershell $env:GOTOOLCHAIN="go1.23.0" go test ./syb ./service -count=1 go test ./... -count=1 go build ./... go vet ./... Remove-Item Env:GOTOOLCHAIN ``` 测试全部使用 `httptest`，禁止调用真实顺运宝站点。 ## 风险和回退 - 风险：最坏情况下一个持续超时的只读请求最多等待约 183 秒；页面已使用后台同步记录，不阻塞浏览器请求。 - 风险：今天重试期间列表可能变化；现有分页后总数、唯一 ID 和明细完整性检查继续负责拦截，不因重试放宽。 - 风险：把重试误加到写接口会造成重复真实写入；测试必须统计写请求只有一次。 - 回退：恢复只读方法直接调用 `do` 并把超时改回 30 秒即可；无 schema 和数据回退。

ila referenced this issue

2026-08-24 17:37:35 +08:00

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

ila referenced this issue

2026-08-24 17:37:35 +08:00

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

ila referenced this issue from a commit

2026-08-24 17:42:49 +08:00

fix: 增加顺运宝只读分页有限重试 (#300)

ila commented

2026-08-24 17:43:02 +08:00

实施完成，待用户验收

实现提交：439639c

完成内容：

顺运宝 HTTP 单请求总超时由 30 秒提高到 60 秒。
listTotal、list、detail/listByStock 对网络/响应读取/HTTP 5xx 最多尝试 3 次，退避 1 秒、2 秒。
第 45 页失败时保持 start=880、pageIndex=45、length=20，只重试当前页。
context 取消会立即停止退避。
401/403、业务失败、非法 JSON、分页格式/完整性错误不重试。
登录、会话校验和档口入库码真实写请求继续直接调用单次请求；5xx 和响应损坏测试确认写请求仍只有 1 次。
更新顺运宝接口基线；无数据库迁移、Admin/Client 接口或页面变更。

验证结果：

GOTOOLCHAIN=go1.23.0 go test ./syb ./service -count=1：通过。
GOTOOLCHAIN=go1.23.0 go test ./... -count=1：通过。
GOTOOLCHAIN=go1.23.0 go build ./...：通过。
GOTOOLCHAIN=go1.23.0 go vet ./...：通过。
git diff --check：通过。

未验证：没有调用真实顺运宝站点复现第 45 页，尚未部署生产；需另建部署工单后验证真实超时恢复。

## 实施完成，待用户验收实现提交：`439639c` 完成内容： - 顺运宝 HTTP 单请求总超时由 30 秒提高到 60 秒。 - `listTotal`、`list`、`detail/listByStock` 对网络/响应读取/HTTP 5xx 最多尝试 3 次，退避 1 秒、2 秒。 - 第 45 页失败时保持 `start=880`、`pageIndex=45`、`length=20`，只重试当前页。 - context 取消会立即停止退避。 - 401/403、业务失败、非法 JSON、分页格式/完整性错误不重试。 - 登录、会话校验和档口入库码真实写请求继续直接调用单次请求；5xx 和响应损坏测试确认写请求仍只有 1 次。 - 更新顺运宝接口基线；无数据库迁移、Admin/Client 接口或页面变更。验证结果： - `GOTOOLCHAIN=go1.23.0 go test ./syb ./service -count=1`：通过。 - `GOTOOLCHAIN=go1.23.0 go test ./... -count=1`：通过。 - `GOTOOLCHAIN=go1.23.0 go build ./...`：通过。 - `GOTOOLCHAIN=go1.23.0 go vet ./...`：通过。 - `git diff --check`：通过。未验证：没有调用真实顺运宝站点复现第 45 页，尚未部署生产；需另建部署工单后验证真实超时恢复。

ila referenced this issue from a commit

2026-08-24 17:43:42 +08:00

docs: 归档任务 #300

ila commented

2026-08-24 17:43:46 +08:00