chengma/cmroubao
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Page: T-237
Pages
00-ai-start-here 01-vision 02-requirements 03-tech-stack 04-architecture 05-coding-rules 06-tasks 07-user-stories 08-interaction-checklist Design Home Integrations-shunyunbao-contract PPT T-001 T-002 T-003 T-004 T-101 T-102 T-103 T-104 T-201 T-202 T-203 T-204 T-205 T-206 T-207 T-208 T-209 T-210 T-211 T-212 T-213 T-214 T-215 T-216 T-217 T-218 T-219 T-220 T-221 T-222 T-223 T-224 T-225 T-226 T-227 T-228 T-229 T-230 T-231 T-232 T-233 T-234 T-235 T-236 T-237 T-238 T-239 T-240 T-241 T-242 T-243 T-244 T-245 T-246 T-247 T-248 T-249 T-250 T-251 T-252 T-253 T-254 T-255 T-256 T-257 T-258 T-259 T-260 T-261 T-262 T-263 T-264 T-265 T-266 T-267 T-268 T-269 T-270 T-271 T-272 T-273 T-274 T-275 T-276 T-277 T-278 T-279 T-280 T-281 Task-Template Tasks agent-context api clean-state-checklist current-state routes
Clone
1
T-237
ila edited this page 2026-08-07 16:36:50 +08:00
Table of Contents

同步来源：docs/tasks/T-237.md · commit afc651f75a3a

id: T-237 title: 完整单号货运同步导入 phase: 2 deps:

  • T-236 status: DONE created: 2026-07-29 context_ref: cf83fb5 work_branch: null write_paths:
  • docs/tasks/T-237.md
  • docs/api.md
  • docs/current-state.md
  • backend-api/cmd/api/**
  • backend-api/internal/config/**
  • backend-api/internal/usecase/freight_*
  • backend-api/internal/transport/httpapi/**
  • backend-api/internal/transport/webui/**

问题 / 背景

Admin 按完整订单号导入 ERP 货运时，当前请求只完成登录预检和同步记录创建，随后以 goroutine 后台查询 ERP。页面立即显示 RUNNING，采购人员需要反复刷新，且后台 90 秒 context 超时后又 使用同一个已取消 context 写失败状态，存在同步记录长期停留在 RUNNING 的风险。

单号导入只处理一个确定订单，内部系统更需要即时、明确的成功或失败结果。创建日期范围可能 包含分页和多个详情请求，不适合受相同页面等待时间约束。

方案

  1. 仅将 ORDER_NUMBER 改为同步执行：认证预检、创建同步记录、查询订单/详情、规范化和事务 落库都在同一请求的 55 秒总预算内完成。CREATED_RANGE 和“同步至现在”继续异步。
  2. 同步记录仍完整经历 PENDING -> RUNNING -> SUCCEEDED/FAILED。成功响应前必须已提交货运头 和全部商品明细；Admin 随后跳转 /freight，立即从 SQLite 列表看到导入数据。
  3. 55 秒超时、浏览器取消、ERP/协议错误或存储失败均使用独立的短时 cleanup context 收敛为 FAILED，禁止遗留 RUNNING。超时使用稳定错误码 FREIGHT_SYNC_TIMEOUT。
  4. 同一 API 进程同时只允许一个完整单号同步导入；占用时快速返回稳定 FREIGHT_SYNC_BUSY，不让后续请求排队消耗 55 秒。
  5. 保持 Idempotency-Key：相同键和请求重放返回已有最终结果，不重复查询或写入；不同 payload 继续冲突。首次成功 API 返回 201，成功重放返回 200，不再以 202 表示后台受理。
  6. HTTP Server WriteTimeout 从 30 秒提高到 70 秒，为 55 秒业务预算、TLS 和响应写入留余量； ERP 单次 HTTP timeout 仍为 30 秒。

验收要点

  • 完整单号 POST 只在货运头和明细事务提交后返回成功，返回时 run 为 SUCCEEDED。
  • Admin 成功后跳转 /freight，列表立即显示本次货运单；页面不再要求刷新 RUNNING。
  • 完整单号从请求进入到执行结束最多 55 秒；超时可靠保存 FAILED/FREIGHT_SYNC_TIMEOUT。
  • ERP、协议、存储和请求取消也可靠保存终态，不复用已取消 context 进行失败收尾。
  • 同进程并发完整单号导入快速返回 FREIGHT_SYNC_BUSY；幂等成功重放不重复执行。
  • 日期范围导入继续返回 202/PENDING 并在后台执行。
  • HTTP WriteTimeout 为 70 秒，覆盖同步业务预算。
  • 标准 Go 测试、race、vet 和三个入口构建通过。

边界

  • 不修改 ERP 登录、OCR、验证码重试、字段 allowlist、货运 schema 或采购任务生成规则。
  • 不将创建日期范围导入改为同步，也不在浏览器轮询或引入消息队列。
  • 不在自动测试中访问真实 ERP；超时和并发使用可控 fake 验证。

执行记录

  • 2026-07-29：创建任务。确认同步化范围仅为完整单号；55 秒是整个单号请求预算，服务端写 超时提高至 70 秒。终态收尾、并发拒绝和幂等重放与同步响应一起实现。
  • 2026-07-29：完整单号改为请求内同步执行，成功 API 返回 201/SUCCEEDED、重放返回 200，Admin 跳转可立即读取的货运列表；日期同步保留 202 后台模式。增加 55 秒预算、 70 秒 WriteTimeout、单进程并发门、超时/取消独立失败收尾，以及 success/timeout/busy/ session/not-found 的稳定 Web/API 映射。标准 Go 测试、race、vet 及三个入口构建均通过。