OPC/goauto
2
0
Fork 0
Code Issues 192 Pull Requests Actions Packages Projects Releases Wiki Activity

SYB 只读分页请求超时后有限重试 #79

New Issue
Closed
opened 2026-08-24 17:23:40 +08:00 by ila · 2 comments
ila commented 2026-08-24 17:23:40 +08:00
Owner
Copy Link
Copy Source

需求来源

  • 提出时间：2026-08-24
  • 现象：同步 2026-08-24 时，/am/stock/list 前 22 页成功，第 23 页等待响应头超过 30 秒，整次同步失败：已获取 440/442 张。
  • 用户确认：按分析建议建立工单并实施。

原因

  • SYB 客户端当前总超时为 30 秒。
  • loadDailyList 对每页只请求一次；任一只读分页请求出现暂时网络故障即结束整次同步。
  • 错误没有 401/403、未登录、登录过期或 code=-2 证据，因此不能清理会话或重新登录。
  • 前 22 页均成功，现有证据只能说明第 23 页临时未在超时前返回响应头；不能武断认定为登录失效或确定的接口限流。

范围与方案

  • 修改服务端 SYB 客户端及测试，不改 Web、Android、数据库和 API 契约。
  • 仅对语义只读的 SYB 请求使用有限重试：货运单总数、货运单列表、货运单明细。
  • 仅当错误属于请求超时/网络故障、响应读取失败、SYB 5xx 或异常响应格式时重试；明确未登录、4xx、业务失败和本地数据校验失败不重试。
  • 共执行最多 3 次（首次 + 2 次重试），等待 1 秒、2 秒；等待必须响应 context 取消。
  • 将单次 HTTP 总超时从 30 秒调整为 60 秒，减少 SYB 偶发慢响应误判。
  • 每次重试重新构造请求体，不复用已经消费的 Body。
  • 保留完整性校验：重试全部失败仍停止同步并记录原有“已获取/总数/页码”上下文。
  • 不自动重试登录、验证码、任何写入或回填请求；不把网络错误判断为会话失效。
  • 不通过调大分页绕过问题；分页大小仍保持 20，后续只有真实证据证明更大分页稳定时才另行调整。

依赖与影响

  • 依赖现有 SYB 同步、会话错误分类和同步记录机制。
  • 可独立于 #78 的 Web 人工入口验收；修改单元只有 Server。
  • 无数据库迁移，无 UI/原型要求，无 Android 影响。

验收标准

  • /am/stock/list 第一次或第二次发生可重试错误、后续恢复时，同步继续且不会遗漏该页。
  • listTotal 和 listByStock 使用相同的只读重试边界。
  • 可重试错误连续三次后返回最后一次错误，分页上下文仍包含日期、页码和已获取数量。
  • 401/403、明确会话失效、业务失败和响应内容完整性错误不重试。
  • context 取消时立即停止等待和重试。
  • 网络故障不清除有效 SYB 会话。
  • 既有 SYB 客户端、导入和完整性测试通过。

验证计划

  • 单元测试覆盖：网络/5xx 后恢复、达到上限、会话错误不重试、context 取消。
  • 运行 go test ./app/goauto/sybclient ./app/goauto/sybimport。
  • 运行服务端定向验证或构建。
  • 不对真实 SYB 发起请求；真实同步由用户验收。

风险

  • 最坏失败时长增加，但同步为后台任务且外层仍受 30 分钟总时限约束。
  • 只读接口虽然使用 POST，但没有写入语义；重试范围必须显式列举，禁止推广到通用 POST。
  • 重试不能掩盖分页漂移，现有页数、唯一 ID、前后总数与明细完整性校验全部保留。

文档影响

需 Wiki-first 更新《SYB ERP Interface Contract》和《Business Rules and Glossary》，记录只读重试边界、次数、退避和不重试范围。

## 需求来源 - 提出时间：2026-08-24 - 现象：同步 2026-08-24 时，`/am/stock/list` 前 22 页成功，第 23 页等待响应头超过 30 秒，整次同步失败：已获取 440/442 张。 - 用户确认：按分析建议建立工单并实施。 ## 原因 - SYB 客户端当前总超时为 30 秒。 - `loadDailyList` 对每页只请求一次；任一只读分页请求出现暂时网络故障即结束整次同步。 - 错误没有 401/403、未登录、登录过期或 code=-2 证据，因此不能清理会话或重新登录。 - 前 22 页均成功，现有证据只能说明第 23 页临时未在超时前返回响应头；不能武断认定为登录失效或确定的接口限流。 ## 范围与方案 - 修改服务端 SYB 客户端及测试，不改 Web、Android、数据库和 API 契约。 - 仅对语义只读的 SYB 请求使用有限重试：货运单总数、货运单列表、货运单明细。 - 仅当错误属于请求超时/网络故障、响应读取失败、SYB 5xx 或异常响应格式时重试；明确未登录、4xx、业务失败和本地数据校验失败不重试。 - 共执行最多 3 次（首次 + 2 次重试），等待 1 秒、2 秒；等待必须响应 context 取消。 - 将单次 HTTP 总超时从 30 秒调整为 60 秒，减少 SYB 偶发慢响应误判。 - 每次重试重新构造请求体，不复用已经消费的 Body。 - 保留完整性校验：重试全部失败仍停止同步并记录原有“已获取/总数/页码”上下文。 - 不自动重试登录、验证码、任何写入或回填请求；不把网络错误判断为会话失效。 - 不通过调大分页绕过问题；分页大小仍保持 20，后续只有真实证据证明更大分页稳定时才另行调整。 ## 依赖与影响 - 依赖现有 SYB 同步、会话错误分类和同步记录机制。 - 可独立于 #78 的 Web 人工入口验收；修改单元只有 Server。 - 无数据库迁移，无 UI/原型要求，无 Android 影响。 ## 验收标准 - [ ] `/am/stock/list` 第一次或第二次发生可重试错误、后续恢复时，同步继续且不会遗漏该页。 - [ ] `listTotal` 和 `listByStock` 使用相同的只读重试边界。 - [ ] 可重试错误连续三次后返回最后一次错误，分页上下文仍包含日期、页码和已获取数量。 - [ ] 401/403、明确会话失效、业务失败和响应内容完整性错误不重试。 - [ ] context 取消时立即停止等待和重试。 - [ ] 网络故障不清除有效 SYB 会话。 - [ ] 既有 SYB 客户端、导入和完整性测试通过。 ## 验证计划 - 单元测试覆盖：网络/5xx 后恢复、达到上限、会话错误不重试、context 取消。 - 运行 `go test ./app/goauto/sybclient ./app/goauto/sybimport`。 - 运行服务端定向验证或构建。 - 不对真实 SYB 发起请求；真实同步由用户验收。 ## 风险 - 最坏失败时长增加，但同步为后台任务且外层仍受 30 分钟总时限约束。 - 只读接口虽然使用 POST，但没有写入语义；重试范围必须显式列举，禁止推广到通用 POST。 - 重试不能掩盖分页漂移，现有页数、唯一 ID、前后总数与明细完整性校验全部保留。 ## 文档影响 需 Wiki-first 更新《SYB ERP Interface Contract》和《Business Rules and Glossary》，记录只读重试边界、次数、退避和不重试范围。
ila commented 2026-08-24 17:32:18 +08:00
Author
Owner
Copy Link
Copy Source

实施完成，等待人工验收

实现结果

  • SYB 单次 HTTP 总超时由 30 秒提高到 60 秒。
  • listTotal、list、detail/listByStock 三个语义只读接口遇到瞬时网络/超时、响应读取失败、HTTP 5xx 或响应信封异常时，最多执行 3 次，退避 1 秒、2 秒。
  • context 取消会立即停止；三次仍失败返回最后错误，外层日期、页码和“已获取/总数”上下文保持不变。
  • 401/403、会话失效、业务失败、数据完整性错误和本地校验失败不重试。
  • 登录、验证码、单件码写入和任何回填请求仍只发送一次。
  • 分页大小与既有完整性校验没有改变。

验证

  • go test ./app/goauto/sybclient ./app/goauto/sybimport：通过。
  • go test ./app/goauto/...：通过。
  • go test ./...：通过。
  • python dev_scripts/harness.py sync --verify：通过。
  • 测试覆盖真实故障形状“等待响应头超时后第三次恢复”、5xx 恢复、达到上限、明确错误不重试和 context 取消。
  • 未访问真实 SYB；需重启 API 服务后由用户人工同步验收。

文档与提交

  • Wiki《SYB ERP Interface Contract》revision：7a3513c2d59a4c0557b90fabc4aa46313e377fe5。
  • Wiki《Business Rules and Glossary》revision：45bbde203b18cee7031aed8129f72a6e8f883033。
  • 任务归档：Task-79-SYB-只读分页请求超时后有限重试，revision 91e1ed1e047ea0014116d900e92c9d04f5f5d0e3。
  • 提交：af3dd5563b08bef2cdde7542631d4137674fb577，已推送 main。

工单保持开启，状态为待验收。

## 实施完成，等待人工验收 ### 实现结果 - SYB 单次 HTTP 总超时由 30 秒提高到 60 秒。 - `listTotal`、`list`、`detail/listByStock` 三个语义只读接口遇到瞬时网络/超时、响应读取失败、HTTP 5xx 或响应信封异常时，最多执行 3 次，退避 1 秒、2 秒。 - context 取消会立即停止；三次仍失败返回最后错误，外层日期、页码和“已获取/总数”上下文保持不变。 - 401/403、会话失效、业务失败、数据完整性错误和本地校验失败不重试。 - 登录、验证码、单件码写入和任何回填请求仍只发送一次。 - 分页大小与既有完整性校验没有改变。 ### 验证 - `go test ./app/goauto/sybclient ./app/goauto/sybimport`：通过。 - `go test ./app/goauto/...`：通过。 - `go test ./...`：通过。 - `python dev_scripts/harness.py sync --verify`：通过。 - 测试覆盖真实故障形状“等待响应头超时后第三次恢复”、5xx 恢复、达到上限、明确错误不重试和 context 取消。 - 未访问真实 SYB；需重启 API 服务后由用户人工同步验收。 ### 文档与提交 - Wiki《SYB ERP Interface Contract》revision：`7a3513c2d59a4c0557b90fabc4aa46313e377fe5`。 - Wiki《Business Rules and Glossary》revision：`45bbde203b18cee7031aed8129f72a6e8f883033`。 - 任务归档：[Task-79-SYB-只读分页请求超时后有限重试](https://git.ilapage.cn/OPC/goauto/wiki/Task-79-SYB-%E5%8F%AA%E8%AF%BB%E5%88%86%E9%A1%B5%E8%AF%B7%E6%B1%82%E8%B6%85%E6%97%B6%E5%90%8E%E6%9C%89%E9%99%90%E9%87%8D%E8%AF%95.-)，revision `91e1ed1e047ea0014116d900e92c9d04f5f5d0e3`。 - 提交：`af3dd5563b08bef2cdde7542631d4137674fb577`，已推送 `main`。 工单保持开启，状态为待验收。
ila commented 2026-08-28 15:07:32 +08:00
Author
Owner
Copy Link
Copy Source

用户于 2026-08-28 明确确认本工单验收通过。按项目流程记录验收结论并关闭工单；本次仅更新工单状态，无新增长期文档事实，不重复同步 Wiki。

用户于 2026-08-28 明确确认本工单验收通过。按项目流程记录验收结论并关闭工单；本次仅更新工单状态，无新增长期文档事实，不重复同步 Wiki。
ila closed this issue 2026-08-28 15:07:34 +08:00
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/goauto#79