feat(t224): add incremental freight sync

docs/api.md

@@ -172,7 +172,17 @@ Connector 是 loopback 内部服务，不复用 ADMIN/BUYER 凭证。除 `/healt
 ### Connector `POST /v1/freight/query`
 
 ```json
-{"order_number":"完整单号"}
+{"mode":"ORDER_NUMBER","order_number":"完整单号"}
+```
+
+或按 Asia/Shanghai 自然日闭区间查询，单次最多 7 天：
+
+```json
+{
+  "mode":"CREATED_RANGE",
+  "created_from":"2026-07-22",
+  "created_to":"2026-07-28"
+}
 ```
 
 成功返回最小化规范结构：
@@ -219,11 +229,15 @@ T-224 增加：
 ```json
 {
   "mode":"CREATED_RANGE",
-  "created_from":"2026-07-27T16:00:00Z",
-  "created_to":"2026-07-28T16:00:00Z"
+  "created_from":"2026-07-22",
+  "created_to":"2026-07-28"
 }
 ```
 
+手动范围最多 7 个自然日；也可以只提交
+`{"mode":"CREATED_RANGE","sync_to_now":true}`。后者在没有水位时从当天开始，有水位时
+从成功水位前回看 10 分钟对应的自然日开始，后端再按最多 7 天切窗。
+
 响应 `202`，返回 sync id/status。订单号不进入 URL、事件 message 或访问日志；数据库
 只保存规范值及用于审计/检索的受控字段，不保存 Connector 密钥。
 
@@ -232,11 +246,16 @@ T-224 增加：
 返回 `PENDING/RUNNING/SUCCEEDED/FAILED`、查询模式、匿名查询摘要、开始/结束时间、
 订单/商品计数和稳定错误码。失败不返回 ERP 原始 body 或个人信息。
 
+### `GET /api/v1/freight-sync-watermark`
+
+返回当前 ADMIN creator 的顺运宝最近成功日期同步水位；尚未成功同步时返回
+`{"watermark":null}`。只有完整批次落库成功才在同一事务推进水位；失败、空响应以外
+的协议错误和较旧范围成功均不会覆盖较新的水位。
+
 ### `GET /api/v1/freight-orders`
 
-T-222 首版返回当前 ADMIN creator 最近更新的货运单并支持 `limit`（1..100）。
-T-224 增加 `q`、`sync_status`、`created_from/to` 和 `cursor`；`q` 只匹配受控来源
-单号、店铺或内部 UUID，不匹配电话/地址。响应不包含收件人字段或 Connector 原文。
+返回当前 ADMIN creator 最近更新的货运单并支持 `limit`（1..100）。响应不包含
+收件人字段或 Connector 原文；列表筛选和 cursor 后置，不属于本次日期同步闭环。
 
 ### `GET /api/v1/freight-orders/{id}`