OPC/cmautobuy
2
0
Fork 0
Code Issues 114 Pull Requests Actions Packages Projects Releases Wiki Activity

Admin：兼容顺运宝列表尾页持续超时 #302

New Issue
Open
opened 2026-08-24 21:55:58 +08:00 by ila · 2 comments
ila commented 2026-08-24 21:55:58 +08:00
Owner
Copy Link
Copy Source

基本信息

  • 类型：缺陷
  • 父级大工单：#14
  • 所属 MVP / 版本：#15 / 顺运宝同步稳定性
  • 阶段：同步列表完整性
  • 依赖：#300
  • 状态：已完成，待用户验收

要解决什么

生产部署 #300 后，同页 3 次、每次 60 秒的有限重试已经生效，但顺运宝 /am/stock/list 仍连续在最后一个不足 20 条的尾页等待响应头超时：

  • 761 张：第 39 页，尾页 1 条；
  • 894 张：第 45 页，尾页 14 条；
  • 484 张：第 25 页，尾页 4 条。

最新失败运行持续 276 秒，错误已经包含“连续 3 次请求失败”，可排除未部署新版和会话失效。顺运宝主页当前可访问，问题集中在列表高 offset/尾页请求。继续单纯增加超时或重试次数只会延长失败时间。

复现步骤：

  1. 在生产 Admin 的顺运宝数据页选择包含数百张货运单的日期。
  2. 点击同步。
  3. 前面的完整页正常返回，最后一个不足 page_size=20 的尾页连续 3 次超过 60 秒。
  4. 同步失败且不推进游标；之前日期已经成功 upsert 的数据保留。

做什么 / 不做什么

做什么

  • 使用生产现有顺运宝会话执行不写数据的尾页对照探测，比较标准尾页、向前重叠的完整窗口及 length=100 请求。
  • 根据探测结果为最后一个不足一页的尾段选择最小兼容策略。
  • 合并重叠窗口时按货运单 ID 去重，最终仍要求唯一 ID 数量等于同步前总数。
  • 保留分页前后 listTotal、页响应条数和唯一 ID 完整性检查；任何不一致仍停止且不推进游标。
  • 为只读重试增加不含 Cookie、请求体和个人数据的诊断日志，记录接口、页码/offset、尝试次数、耗时和错误分类。
  • 补充尾页、重复 ID、总数漂移、连续超时、取消和普通整页的自动化测试。
  • 更新顺运宝接口基线与任务归档。

不做什么

  • 不放宽完整性门禁，不把缺页同步标为成功。
  • 不并行拉取列表，不自动重试登录和顺运宝真实写请求。
  • 不增加数据库迁移，不修改 Client 接口。
  • 不无限提高超时或重试次数。
  • 不在探测和日志中输出 Cookie、账号密码或原始响应业务数据。

怎么做

  1. 固定当前生产版本和失败记录，确认 page_size=20、失败页均为尾部不足一页。
  2. 在独立临时诊断程序中复用项目的 syb.Client、生产配置和现有会话，只调用 ListPage：
    • 标准尾页；
    • start=max(total-pageSize,0) 的重叠完整窗口；
    • 顺运宝若支持，再验证 length=100。
      只记录状态、条数和耗时，不输出 Cookie、请求体或货运单内容。
  3. 若重叠窗口稳定返回，则在 admin/service/syb.go 的单日分页计划中把非整除尾页改为向前重叠取满一页，并按 ID 合并；若服务端实际忽略非对齐 start，则以探测通过的 length=100 顺序分页方案替代。实施前把最终选择和证据回填本工单。
  4. 保留 ListTotal 前后复核及唯一 ID 精确计数。重叠区出现重复是预期；除此之外缺失、额外 ID 或总数变化仍返回快照漂移错误。
  5. 在 admin/syb/client.go 为只读请求注入可选诊断回调或使用标准日志记录每次失败尝试的安全元数据；不得记录请求体与凭据。若 service 层更适合记录日期/页码，则由 service 记录调用边界耗时。
  6. 更新 admin/syb/client_test.go、admin/service/syb_test.go 和 docs/admin/08-顺运宝接口.md。

预计修改文件：

  • admin/service/syb.go
  • admin/service/syb_test.go
  • admin/syb/client.go
  • admin/syb/client_test.go
  • docs/admin/08-顺运宝接口.md
  • docs/task/<工单号>-admin顺运宝尾页超时兼容.md

数据库：不变。
Admin/Client 接口：不变。

验收标准

  • 已完成不写业务数据的生产尾页对照探测，工单记录请求形状、耗时和结果，不包含凭据或业务明细。
  • 非整除尾页不再依赖已证明连续超时的标准尾页请求形状。
  • 761、894、484 等总数可在测试中分别得到 761、894、484 个唯一 ID。
  • 重叠窗口只去除相同货运单 ID，不吞掉不同货运单。
  • 分页前后总数变化、唯一 ID 缺失或额外、响应条数异常时仍失败且不推进游标。
  • 普通整页分页行为保持不变。
  • 只读网络/读响应/5xx 仍为最多 3 次；登录、会话、业务/格式错误和真实写请求仍不自动重试。
  • 日志能定位失败的日期、页码、offset、attempt 和耗时，不包含 Cookie、密码、请求体或业务明细。
  • Go 1.23.0 下 go test ./... -count=1、go build ./...、go vet ./... 全部通过。
  • 完成工单实施记录与本地归档，提交均引用本工单。

怎么验证

从 admin/ 执行：

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

重点自动化用例：

  • 总数小于、等于、大于一页；
  • 总数 761、894、484 的非整除尾页；
  • 重叠窗口重复 ID 合并；
  • 尾页返回缺失、额外 ID；
  • 分页前后总数漂移；
  • 请求 3 次超时及 context 取消；
  • 登录/写请求仍只发送一次。

生产只读探测只调用列表查询，不执行同步写库；实现完成后生产真实同步需另行部署并由用户验收。

风险和回退

  • 风险：顺运宝可能同时使用 start 与 pageIndex，非对齐重叠窗口需要生产只读探测确认；提高 length 可能增加单次响应大小。
  • 控制：先探测后选择；所有结果仍经过总数和唯一 ID 完整性门禁；保持顺序拉取。
  • 回退：回退本工单代码提交即可恢复 #300 的固定 20 条分页和同页 3 次重试；无数据库迁移。

生产只读探测与最终实现决策（2026-08-24）

探测复用生产现有会话，只调用 listTotal/list，没有执行同步落库或顺运宝写请求；输出仅含日期、总数、start、pageIndex、length、返回条数、唯一 ID 数和耗时。

关键结果

  • 生产配置：page_size=20。
  • 2026-08-24 探测时总数已增长到 650：
    • 标准尾页 start=640,pageIndex=33,length=20：35 秒仍未返回，主动取消；
    • 重叠窗口 start=630,pageIndex=33,length=20：约 19.5 秒返回 20/20 个唯一 ID；
    • start=600,length=100：约 41.1 秒返回尾部 50 个唯一 ID；
    • start=550,length=100：约 22.1 秒返回 100/100 个唯一 ID。
  • 2026-08-20 总数 761：
    • start=741,length=20：50 秒未返回；
    • start=661,length=100：55 秒未返回；
    • start=261,length=500：58 秒未返回；
    • start=0,length=500：约 4.3 秒返回 500/500；
    • start=0,length=761：约 21.0 秒返回 761/761 个唯一 ID。
  • 2026-08-23 总数 894：
    • 在前面连续高负载探测后，start=0,length=894 曾连续 3 次、每次 60 秒超时；
    • 稍后同一请求约 22.3 秒返回 894/894 个唯一 ID，说明顺运宝还存在临时负载/限流窗口，但低 offset 整日请求本身受支持。

结论

问题不是单纯“尾页不足 20 条”，而是顺运宝高 offset/连续查询在部分数据和负载窗口下不稳定。只向前重叠 20、100 或 500 条不能覆盖所有日期；把全程页大小改为 100 也不是稳定解法。

最终方案

  1. 每个单日总数大于 0 时，正常路径先请求 start=0,pageIndex=1,length=expectedTotal，一次取得当天列表，显著减少请求次数并避开高 offset。
  2. 单日整批请求仍使用 #300 的最多 3 次、单次 60 秒只读重试；业务、格式、会话和 context 取消错误不回退。
  3. 仅当整批请求以“可重试网络/读响应/5xx 已耗尽 3 次”的明确错误结束时，回退原有 page_size 顺序分页，兼容极大响应或上游临时拒绝整批请求。
  4. 无论走整批还是回退分页，都必须重新查询 listTotal，并要求响应条数、唯一 ID 数和前后总数完全一致；失败仍不推进游标。
  5. 为每次只读失败/恢复记录安全元数据：日期范围、path、start、pageIndex、length、attempt、耗时和分类；不记录 Cookie、请求体、账号、订单号或业务响应。
  6. 数据库、Admin/Client 接口、60 秒超时、最多 3 次和真实写请求单次门禁均不变。

该方案与建单时“按探测结果二选一”的差异：探测证明固定重叠窗口和统一 100 条分页都不足以覆盖历史日期，因此改为低 offset 的单日整批正常路径，并保留旧分页作为明确网络重试耗尽后的兼容回退。

实施结果

  • 实现提交：68ff67a652ef059ea17e4d3e54aa0004951e4e52
  • 归档提交：5f544a1deb91fd4a333aafb1185d9e2465d17ede
  • 归档文件：docs/task/302-admin顺运宝列表尾页持续超时兼容.md
  • 数据库迁移：无。
  • Admin/Client HTTP 接口变化：无。
  • Go 1.23.0 全量 test、build、vet：通过。
  • 生产只读探测临时程序和服务器临时目录已清理；探测未执行业务写入。
  • 已通过 #303 部署到生产，生产稳定链接与实际进程均指向 5f544a1；真实同步结果仍待用户验收。
## 基本信息 - 类型：缺陷 - 父级大工单：#14 - 所属 MVP / 版本：#15 / 顺运宝同步稳定性 - 阶段：同步列表完整性 - 依赖：#300 - 状态：已完成，待用户验收 ## 要解决什么 生产部署 #300 后，同页 3 次、每次 60 秒的有限重试已经生效，但顺运宝 `/am/stock/list` 仍连续在最后一个不足 20 条的尾页等待响应头超时： - 761 张：第 39 页，尾页 1 条； - 894 张：第 45 页，尾页 14 条； - 484 张：第 25 页，尾页 4 条。 最新失败运行持续 276 秒，错误已经包含“连续 3 次请求失败”，可排除未部署新版和会话失效。顺运宝主页当前可访问，问题集中在列表高 offset/尾页请求。继续单纯增加超时或重试次数只会延长失败时间。 复现步骤： 1. 在生产 Admin 的顺运宝数据页选择包含数百张货运单的日期。 2. 点击同步。 3. 前面的完整页正常返回，最后一个不足 `page_size=20` 的尾页连续 3 次超过 60 秒。 4. 同步失败且不推进游标；之前日期已经成功 upsert 的数据保留。 ## 做什么 / 不做什么 ### 做什么 - 使用生产现有顺运宝会话执行不写数据的尾页对照探测，比较标准尾页、向前重叠的完整窗口及 `length=100` 请求。 - 根据探测结果为最后一个不足一页的尾段选择最小兼容策略。 - 合并重叠窗口时按货运单 ID 去重，最终仍要求唯一 ID 数量等于同步前总数。 - 保留分页前后 `listTotal`、页响应条数和唯一 ID 完整性检查；任何不一致仍停止且不推进游标。 - 为只读重试增加不含 Cookie、请求体和个人数据的诊断日志，记录接口、页码/offset、尝试次数、耗时和错误分类。 - 补充尾页、重复 ID、总数漂移、连续超时、取消和普通整页的自动化测试。 - 更新顺运宝接口基线与任务归档。 ### 不做什么 - 不放宽完整性门禁，不把缺页同步标为成功。 - 不并行拉取列表，不自动重试登录和顺运宝真实写请求。 - 不增加数据库迁移，不修改 Client 接口。 - 不无限提高超时或重试次数。 - 不在探测和日志中输出 Cookie、账号密码或原始响应业务数据。 ## 怎么做 1. 固定当前生产版本和失败记录，确认 `page_size=20`、失败页均为尾部不足一页。 2. 在独立临时诊断程序中复用项目的 `syb.Client`、生产配置和现有会话，只调用 `ListPage`： - 标准尾页； - `start=max(total-pageSize,0)` 的重叠完整窗口； - 顺运宝若支持，再验证 `length=100`。 只记录状态、条数和耗时，不输出 Cookie、请求体或货运单内容。 3. 若重叠窗口稳定返回，则在 `admin/service/syb.go` 的单日分页计划中把非整除尾页改为向前重叠取满一页，并按 ID 合并；若服务端实际忽略非对齐 start，则以探测通过的 `length=100` 顺序分页方案替代。实施前把最终选择和证据回填本工单。 4. 保留 `ListTotal` 前后复核及唯一 ID 精确计数。重叠区出现重复是预期；除此之外缺失、额外 ID 或总数变化仍返回快照漂移错误。 5. 在 `admin/syb/client.go` 为只读请求注入可选诊断回调或使用标准日志记录每次失败尝试的安全元数据；不得记录请求体与凭据。若 service 层更适合记录日期/页码，则由 service 记录调用边界耗时。 6. 更新 `admin/syb/client_test.go`、`admin/service/syb_test.go` 和 `docs/admin/08-顺运宝接口.md`。 预计修改文件： - `admin/service/syb.go` - `admin/service/syb_test.go` - `admin/syb/client.go` - `admin/syb/client_test.go` - `docs/admin/08-顺运宝接口.md` - `docs/task/<工单号>-admin顺运宝尾页超时兼容.md` 数据库：不变。 Admin/Client 接口：不变。 ## 验收标准 - [x] 已完成不写业务数据的生产尾页对照探测，工单记录请求形状、耗时和结果，不包含凭据或业务明细。 - [x] 非整除尾页不再依赖已证明连续超时的标准尾页请求形状。 - [x] 761、894、484 等总数可在测试中分别得到 761、894、484 个唯一 ID。 - [x] 重叠窗口只去除相同货运单 ID，不吞掉不同货运单。 - [x] 分页前后总数变化、唯一 ID 缺失或额外、响应条数异常时仍失败且不推进游标。 - [x] 普通整页分页行为保持不变。 - [x] 只读网络/读响应/5xx 仍为最多 3 次；登录、会话、业务/格式错误和真实写请求仍不自动重试。 - [x] 日志能定位失败的日期、页码、offset、attempt 和耗时，不包含 Cookie、密码、请求体或业务明细。 - [x] Go 1.23.0 下 `go test ./... -count=1`、`go build ./...`、`go vet ./...` 全部通过。 - [x] 完成工单实施记录与本地归档，提交均引用本工单。 ## 怎么验证 从 `admin/` 执行： ```powershell $env:GOTOOLCHAIN = "go1.23.0" go test ./... -count=1 go build ./... go vet ./... Remove-Item Env:GOTOOLCHAIN ``` 重点自动化用例： - 总数小于、等于、大于一页； - 总数 761、894、484 的非整除尾页； - 重叠窗口重复 ID 合并； - 尾页返回缺失、额外 ID； - 分页前后总数漂移； - 请求 3 次超时及 context 取消； - 登录/写请求仍只发送一次。 生产只读探测只调用列表查询，不执行同步写库；实现完成后生产真实同步需另行部署并由用户验收。 ## 风险和回退 - 风险：顺运宝可能同时使用 `start` 与 `pageIndex`，非对齐重叠窗口需要生产只读探测确认；提高 `length` 可能增加单次响应大小。 - 控制：先探测后选择；所有结果仍经过总数和唯一 ID 完整性门禁；保持顺序拉取。 - 回退：回退本工单代码提交即可恢复 #300 的固定 20 条分页和同页 3 次重试；无数据库迁移。 ## 生产只读探测与最终实现决策（2026-08-24） 探测复用生产现有会话，只调用 `listTotal/list`，没有执行同步落库或顺运宝写请求；输出仅含日期、总数、start、pageIndex、length、返回条数、唯一 ID 数和耗时。 ### 关键结果 - 生产配置：`page_size=20`。 - 2026-08-24 探测时总数已增长到 650： - 标准尾页 `start=640,pageIndex=33,length=20`：35 秒仍未返回，主动取消； - 重叠窗口 `start=630,pageIndex=33,length=20`：约 19.5 秒返回 20/20 个唯一 ID； - `start=600,length=100`：约 41.1 秒返回尾部 50 个唯一 ID； - `start=550,length=100`：约 22.1 秒返回 100/100 个唯一 ID。 - 2026-08-20 总数 761： - `start=741,length=20`：50 秒未返回； - `start=661,length=100`：55 秒未返回； - `start=261,length=500`：58 秒未返回； - `start=0,length=500`：约 4.3 秒返回 500/500； - `start=0,length=761`：约 21.0 秒返回 761/761 个唯一 ID。 - 2026-08-23 总数 894： - 在前面连续高负载探测后，`start=0,length=894` 曾连续 3 次、每次 60 秒超时； - 稍后同一请求约 22.3 秒返回 894/894 个唯一 ID，说明顺运宝还存在临时负载/限流窗口，但低 offset 整日请求本身受支持。 ### 结论 问题不是单纯“尾页不足 20 条”，而是顺运宝高 offset/连续查询在部分数据和负载窗口下不稳定。只向前重叠 20、100 或 500 条不能覆盖所有日期；把全程页大小改为 100 也不是稳定解法。 ### 最终方案 1. 每个单日总数大于 0 时，正常路径先请求 `start=0,pageIndex=1,length=expectedTotal`，一次取得当天列表，显著减少请求次数并避开高 offset。 2. 单日整批请求仍使用 #300 的最多 3 次、单次 60 秒只读重试；业务、格式、会话和 context 取消错误不回退。 3. 仅当整批请求以“可重试网络/读响应/5xx 已耗尽 3 次”的明确错误结束时，回退原有 `page_size` 顺序分页，兼容极大响应或上游临时拒绝整批请求。 4. 无论走整批还是回退分页，都必须重新查询 `listTotal`，并要求响应条数、唯一 ID 数和前后总数完全一致；失败仍不推进游标。 5. 为每次只读失败/恢复记录安全元数据：日期范围、path、start、pageIndex、length、attempt、耗时和分类；不记录 Cookie、请求体、账号、订单号或业务响应。 6. 数据库、Admin/Client 接口、60 秒超时、最多 3 次和真实写请求单次门禁均不变。 该方案与建单时“按探测结果二选一”的差异：探测证明固定重叠窗口和统一 100 条分页都不足以覆盖历史日期，因此改为低 offset 的单日整批正常路径，并保留旧分页作为明确网络重试耗尽后的兼容回退。 ## 实施结果 - 实现提交：`68ff67a652ef059ea17e4d3e54aa0004951e4e52` - 归档提交：`5f544a1deb91fd4a333aafb1185d9e2465d17ede` - 归档文件：`docs/task/302-admin顺运宝列表尾页持续超时兼容.md` - 数据库迁移：无。 - Admin/Client HTTP 接口变化：无。 - Go 1.23.0 全量 test、build、vet：通过。 - 生产只读探测临时程序和服务器临时目录已清理；探测未执行业务写入。 - 已通过 #303 部署到生产，生产稳定链接与实际进程均指向 `5f544a1`；真实同步结果仍待用户验收。
ila referenced this issue from a commit 2026-08-24 22:31:29 +08:00
docs: 归档任务 #302
ila commented 2026-08-24 22:31:55 +08:00
Author
Owner
Copy Link
Copy Source

#302 已完成，等待用户验收。

  • 生产只读探测确认：标准/重叠高 offset 请求并不稳定；start=0,length=当天总数 已分别完整返回 761 和 894 个唯一 ID。
  • 最终实现：单日优先低-offset整批读取；仅明确耗尽三次网络/读响应/5xx 重试时回退原分页。
  • 总数前后复核、响应条数、唯一 ID、今天快照漂移和游标门禁均保留。
  • 只读失败/恢复日志只包含合法日期范围、path、offset、页码、length、attempt、耗时和分类，不包含 Cookie、请求体、订单号或响应数据。
  • Go 1.23.0：go test ./... -count=1、go build ./...、go vet ./... 全部通过。
  • 实现提交：68ff67a652ef059ea17e4d3e54aa0004951e4e52
  • 归档提交：5f544a1deb91fd4a333aafb1185d9e2465d17ede
  • 归档：docs/task/302-admin顺运宝列表尾页持续超时兼容.md

未验证：尚未部署生产并执行真实同步；超过 894 张的真实单日整批响应、生产分页回退恢复、真实 MySQL _test 集成用例。

#302 已完成，等待用户验收。 - 生产只读探测确认：标准/重叠高 offset 请求并不稳定；`start=0,length=当天总数` 已分别完整返回 761 和 894 个唯一 ID。 - 最终实现：单日优先低-offset整批读取；仅明确耗尽三次网络/读响应/5xx 重试时回退原分页。 - 总数前后复核、响应条数、唯一 ID、今天快照漂移和游标门禁均保留。 - 只读失败/恢复日志只包含合法日期范围、path、offset、页码、length、attempt、耗时和分类，不包含 Cookie、请求体、订单号或响应数据。 - Go 1.23.0：`go test ./... -count=1`、`go build ./...`、`go vet ./...` 全部通过。 - 实现提交：`68ff67a652ef059ea17e4d3e54aa0004951e4e52` - 归档提交：`5f544a1deb91fd4a333aafb1185d9e2465d17ede` - 归档：`docs/task/302-admin顺运宝列表尾页持续超时兼容.md` 未验证：尚未部署生产并执行真实同步；超过 894 张的真实单日整批响应、生产分页回退恢复、真实 MySQL `_test` 集成用例。
ila commented 2026-08-25 08:47:34 +08:00
Author
Owner
Copy Link
Copy Source

#302 已通过 #303 部署到生产：稳定链接和实际进程均指向 5f544a1，systemd、Nginx、本机/公网 HTTP、schema v30 和后台活动检查全部通过。部署过程没有主动触发真实顺运宝同步；请由用户在页面执行目标日期范围同步完成业务验收。

#302 已通过 #303 部署到生产：稳定链接和实际进程均指向 `5f544a1`，systemd、Nginx、本机/公网 HTTP、schema v30 和后台活动检查全部通过。部署过程没有主动触发真实顺运宝同步；请由用户在页面执行目标日期范围同步完成业务验收。
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
admin ila
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: OPC/cmautobuy#302