feat(t237): import freight orders synchronously

docs/api.md

@@ -242,7 +242,7 @@ ERP 配置来源：
 
 ### `POST /api/v1/freight-syncs`
 
-ADMIN 创建异步同步记录，必须带 `Idempotency-Key`：
+ADMIN 创建货运同步记录，必须带 `Idempotency-Key`：
 
 ```json
 {"mode":"ORDER_NUMBER","order_number":"完整单号"}
@@ -262,8 +262,17 @@ T-224 增加：
 `{"mode":"CREATED_RANGE","sync_to_now":true}`。后者在没有水位时从当天开始，有水位时
 从成功水位前回看 10 分钟对应的自然日开始，后端再按最多 7 天切窗。
 
-响应 `202`，返回 sync id/status。订单号不进入 URL、事件 message 或访问日志；数据库
-只保存规范值及用于审计/检索的受控字段，不保存 ERP 凭证、Cookie 或 JWT。
+`ORDER_NUMBER` 在同一请求内执行认证、ERP 查询、规范化和事务落库，总预算 55 秒。首次成功
+返回 `201` 和最终 `SUCCEEDED` run，成功幂等重放返回 `200`，两者均设置
+`Location: /api/v1/freight-orders`。同时只能执行一个完整单号同步，其他请求快速返回
+`409 FREIGHT_SYNC_BUSY`；超时返回 `504 FREIGHT_SYNC_TIMEOUT`，并使用独立 cleanup context
+把已创建 run 保存为 `FAILED`。Admin Web 成功后跳转 `/freight?notice=import-succeeded`，
+此时列表已能读取货运头和全部商品明细。
+
+`CREATED_RANGE` 和 `sync_to_now` 保持异步，响应 `202` 和 `PENDING` run，随后在后台执行。
+订单号不进入 URL、事件 message 或访问日志；数据库只保存规范值及用于审计/检索的受控字段，
+不保存 ERP 凭证、Cookie 或 JWT。HTTP Server `WriteTimeout` 为 70 秒，ERP 单次请求 timeout
+仍为 30 秒。
 
 ### `GET /api/v1/freight-syncs/{sync_id}`
 
@@ -286,8 +295,9 @@ T-224 增加：
 T-222 返回货运头、全部当前商品明细和 revision/hash 状态。T-223 再增加采购需求和
 已生成 task 引用。不存在和跨 creator 统一 404；响应 `Cache-Control: no-store`。
 
-T-227 的后台 worker 使用当前 Go 内存会话，按 `listTotal -> list 分页 -> listByStock`
-查询。每次先校验会话；列表最多 100 条、每页 20 条，详情每批最多 100 个外部 stock ID。
+T-227 的 Go source 使用当前内存会话，按 `listTotal -> list 分页 -> listByStock` 查询；
+完整单号由请求同步调用，日期范围由后台 worker 调用。每次先校验会话；列表最多 100 条、
+每页 20 条，详情每批最多 100 个外部 stock ID。
 未配置、未登录、找不到货运单、响应协议错误和暂时不可用分别落为
 `ERP_NOT_CONFIGURED`、`ERP_SESSION_REQUIRED`、`ERP_FREIGHT_NOT_FOUND`、
 `ERP_RESPONSE_INVALID` 和 `ERP_UNAVAILABLE`，不返回 ERP 原始错误 body。

docs/current-state.md

@@ -5,7 +5,7 @@
 ## 当前快照
 
 - 日期：2026-07-29
-- 阶段：T-237 已规划完整单号 55 秒同步导入，待实现
+- 阶段：T-237 已完成完整单号 55 秒同步导入
 - Git：当前分支为 `main`；T-001 至 T-004、T-101 至 T-104、T-201 至 T-219
   均按文档提交、实现提交的顺序纳入历史
 - 生产代码：`android-buyer/` 已接入 Roubao Android 源码
@@ -16,8 +16,9 @@
   task-scoped 参考图和 `authctl`
 - ERP 货运：Go 后端以受锁内存 ERP 会话直连按完整单号或创建日期同步；v12 保存
   同步记录、货运头和全部明细，canonical hash 控制 revision，Admin 已有 `/freight`、
-  `/freight/import`、`/freight/{id}` 与对应 JSON API。T-237 计划将完整单号改为 55 秒
-  同步响应并可靠写终态，日期范围仍后台异步。
+  `/freight/import`、`/freight/{id}` 与对应 JSON API。T-237 已将完整单号改为 55 秒
+  同步响应，成功后直接进入可见货运列表；超时/取消使用独立 cleanup context 写
+  `FAILED`，日期范围仍后台异步。HTTP `WriteTimeout` 为 70 秒。
 - ERP Go 迁移：T-225 已用脱敏 fixture 固定 `internal/platform/shunyunbao` 的 header、
   单号/日期查询、分页、详情批量和字段 allowlist，并使货运用例依赖来源中立错误。T-226
   已增加受锁保护的 Go 内存 Cookie jar、验证码 ticket、登录和用户校验，以及 ADMIN 的
@@ -39,7 +40,7 @@
 - Android Studio：未安装；`winget` 静默安装卡住后已终止，不阻塞命令行构建
 - 测试：T-219 Android Debug/Release 单元测试与构建和根 `init.ps1` 通过；
   Debug APK `1.4.16 (21)` 已覆盖安装到 PKG110
-- 后端测试：T-226 至 T-229 已运行 `go test ./...`、`go test -race ./...`、`go vet ./...`
+- 后端测试：T-226 至 T-237 已运行 `go test ./...`、`go test -race ./...`、`go vet ./...`
   和三个 Go 入口构建；T-227 增加 Go source 的伪 ERP 会话预检、完整单号、日期分页去重、
   详情 allowlist 和稳定错误码覆盖；根 `init.ps1` 的 Android 测试/Debug APK 与 Go 标准
   验证也通过，均未访问真实 ERP；

docs/tasks/T-237.md

@@ -4,7 +4,7 @@ title: 完整单号货运同步导入
 phase: 2
 deps:
   - T-236
-status: PLANNED
+status: DONE
 created: 2026-07-29
 context_ref: cf83fb5
 work_branch: null
@@ -45,14 +45,14 @@ Admin 按完整订单号导入 ERP 货运时，当前请求只完成登录预检
 
 ## 验收要点
 
-- [ ] 完整单号 POST 只在货运头和明细事务提交后返回成功，返回时 run 为 `SUCCEEDED`。
-- [ ] Admin 成功后跳转 `/freight`，列表立即显示本次货运单；页面不再要求刷新 `RUNNING`。
-- [ ] 完整单号从请求进入到执行结束最多 55 秒；超时可靠保存 `FAILED/FREIGHT_SYNC_TIMEOUT`。
-- [ ] ERP、协议、存储和请求取消也可靠保存终态，不复用已取消 context 进行失败收尾。
-- [ ] 同进程并发完整单号导入快速返回 `FREIGHT_SYNC_BUSY`；幂等成功重放不重复执行。
-- [ ] 日期范围导入继续返回 `202/PENDING` 并在后台执行。
-- [ ] HTTP `WriteTimeout` 为 70 秒，覆盖同步业务预算。
-- [ ] 标准 Go 测试、race、vet 和三个入口构建通过。
+- [x] 完整单号 POST 只在货运头和明细事务提交后返回成功，返回时 run 为 `SUCCEEDED`。
+- [x] Admin 成功后跳转 `/freight`，列表立即显示本次货运单；页面不再要求刷新 `RUNNING`。
+- [x] 完整单号从请求进入到执行结束最多 55 秒；超时可靠保存 `FAILED/FREIGHT_SYNC_TIMEOUT`。
+- [x] ERP、协议、存储和请求取消也可靠保存终态，不复用已取消 context 进行失败收尾。
+- [x] 同进程并发完整单号导入快速返回 `FREIGHT_SYNC_BUSY`；幂等成功重放不重复执行。
+- [x] 日期范围导入继续返回 `202/PENDING` 并在后台执行。
+- [x] HTTP `WriteTimeout` 为 70 秒，覆盖同步业务预算。
+- [x] 标准 Go 测试、race、vet 和三个入口构建通过。
 
 ## 边界
 
@@ -64,3 +64,7 @@ Admin 按完整订单号导入 ERP 货运时，当前请求只完成登录预检
 
 - 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 及三个入口构建均通过。