fix(#79): retry transient SYB read failures

2026-08-24 17:31:34 +08:00
parent 5c9b75fc53
commit af3dd5563b
4 changed files with 208 additions and 13 deletions
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Business-Rules-and-Glossary
 wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Business-Rules-and-Glossary.-
-wiki_revision: 3d2a64c6638229ff95a8ac5a5680bb41f0dcb91d
-synchronized_at: 2026-08-24T09:01:14Z
+wiki_revision: 45bbde203b18cee7031aed8129f72a6e8f883033
+synchronized_at: 2026-08-24T09:26:57Z
 <!-- gitea-wiki-mirror:end -->

 # 业务规则与术语
@@ -190,6 +190,7 @@ synchronized_at: 2026-08-24T09:01:14Z
 - 定时同步与保留的手动导入 API 共用同一个导入服务和 `syb_sync_run` 记录；定时任务的操作人显示为“系统定时同步”。
 - 同一时刻只允许一个 SYB 同步任务运行。上一次仍在运行时，本次定时触发直接跳过，不排队、不并发，也不立即重试；等待下一小时再次触发。
 - 定时任务失败时明确记录失败原因，不自动重试。服务重启后由既有启动恢复逻辑处理遗留的运行中记录。
+- 单次同步内部的 SYB 只读请求（货运单总数、列表和明细）遇到暂时网络故障、5xx 或异常响应时最多执行 3 次，分别退避 1 秒、2 秒，单次 HTTP 总超时 60 秒；这不等于失败任务自动重试。明确未登录、业务失败、数据完整性错误以及任何写操作均不自动重试。
 - SYB 商品页不再提供“导入”和“同步记录”快捷按钮，也不查询、展示或轮询同步状态；后台同步成功、失败或中断均不在商品页弹出消息，商品数据由用户主动查询或刷新获取。
 - 独立“SYB 同步记录”页面是同步结果的唯一 Web 展示位置，保留运行状态、进度、数量、失败原因和店铺统计；go-admin 定时任务中的 `GoAutoSYBHourlySync` 提供“执行记录”入口。管理员可在同步记录页人工发起覆盖昨天和今天的同步，采购员只读；人工与定时同步共用导入服务、执行记录和互斥，不排队、不并发，也不立即重试。

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: SYB-ERP-Interface-Contract
 wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/SYB-ERP-Interface-Contract.-
-wiki_revision: f92d8e766d3307ac80abfd85f664fb0ab87ec4c2
-synchronized_at: 2026-08-20T03:53:19Z
+wiki_revision: 7a3513c2d59a4c0557b90fabc4aa46313e377fe5
+synchronized_at: 2026-08-24T09:28:34Z
 <!-- gitea-wiki-mirror:end -->

 # 12 顺云宝（SYB）ERP 接口契约
@@ -212,6 +212,14 @@ Admin 默认 `max_matches = 10000`，可以在配置中调整；上限针对整
 预检总数。历史日期出现前后总数变化、短页、重复 ID 或唯一 ID 不足时立即失败，
 不推进游标。

+
+`[必须]` `listTotal`、`list` 和 `detail/listByStock` 属于语义只读查询，虽然
+使用 POST，也只允许在超时、网络故障、响应读取失败、HTTP 5xx 或响应信封格式异常时
+有限重试：单次 HTTP 总超时 60 秒，最多执行 3 次，重试前分别等待 1 秒、2 秒，等待须
+响应 context 取消。HTTP 401/403、明确会话失效、业务失败、接口数据完整性错误和本地
+校验失败不得重试；登录、验证码、单件码写入和任何回填请求也不得使用该机制。重试
+耗尽后返回最后一次错误，外层继续保留日期、页码和已获取数量上下文并将同步标为失败。
+
 今天的货运单会在同步期间持续新增。只有 UTC+8 下的今天发生上述快照漂移时，
 允许只重试今天的列表分页，最多 3 次；已经完成的历史日期不得重复拉取，每次尝试
 也必须使用独立 ID 集合。第三次仍不稳定时，可以对最后一次取得的合法唯一 ID