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。