feat(mini-user): logistics sign photos, dial, ETA and courier callbacks (v3.4.13)

Extend Courier adapter for XFX sign photos and route callbacks; mini-user logistics UI with timeline, phone dial, and estimated arrival.

Co-authored-by: Cursor <cursoragent@cursor.com>

杜康好客-v3.4.13-体验优化开发文档.md

@@ -8,9 +8,9 @@
 | 模块 | 内容 |
 |------|------|
 | admin-web | 推广码 attributionCount；核销记录用户信息；技术支持工单优先级；**大图上传前压缩** |
-| mini-user | 门店电话脱敏+拨打埋点；门头/套餐展示；商品去分享+首图 preview；提货确认弹框；版本更新提示；**订单详情配送中物流摘要+详情页时间线**；**头像超 10MB 压缩** |
+| mini-user | 门店电话脱敏+拨打埋点；门头/套餐展示；商品去分享+首图 preview；提货确认弹框；版本更新提示；**物流增强（签收照/拨号/时间线/ETA）**；**头像超 10MB 压缩** |
 | h5-partner / h5-shop / h5-user | 登录 phone/code 前端校验；**OSS 图片超 10MB 自动 canvas 压缩后上传** |
-| 后端 | 工单 priority 字段；client-config minClientVersion；合伙人微信登录暂停拦截 |
+| 后端 | 工单 priority；client-config minClientVersion；合伙人微信暂停禁登；**Courier 适配器（100108/100301/路由回调）** |
 
 ## 2. ST 映射
 
@@ -34,7 +34,7 @@
 | ST1785901775231811 | 门店套餐遮挡 | ✅ 折叠/行数限制 |
 | ST1785901711627824 | SHOP login 校验 | ✅ 前端空字段拦截 |
 | ST1785901314893145 | 门头照裁剪 | ✅ aspectFit + preview |
-| ST1785939375449985 | 订单物流追踪页 | ✅ 配送中摘要 + 物流详情页时间线（小飞侠路由） |
+| ST1785939375449985 | 订单物流追踪页 | ✅ 签收照 + 拨号 + 时间线 + ETA + 路由回调 |
 | — | 上传图片超 10MB 先压缩 | ✅ `@dukang/shared-ui/compressImage` + 各端 upload |
 
 ## 3. 后端 API / 配置
@@ -44,16 +44,57 @@
 | GET | `/common/client-config` | 新增 `minClientVersion`（env `MINI_USER_MIN_VERSION`） |
 | — | `CommonSupportTicket.priority` | `LOW \| NORMAL \| HIGH \| URGENT`，默认 NORMAL |
 | — | `loginPartnerWechat` | 非 ACTIVE 账号抛出「合伙人账号已停用」 |
-| GET | `/trade/orders/:id/track` | 物流路由；小飞侠（`XFX`/`XIAOFEIXIA`）走小飞侠 TRACK_ROUTE，其他承运商返回 manualQueryUrl |
+| GET | `/trade/orders/:id/track` | 聚合：`nodes`（旧→新）、`signPhotoUrls`、`estimatedArrival`；经 `CourierService` 适配小飞侠 cmd 100102/100108/100301 |
+| POST | `/callbacks/courier/xfx/track` | 小飞侠路由变化回调（适配器入口） |
+| POST | `/callbacks/courier/logistics/track` | 跨城物流回调占位（记录日志，后续接入） |
+| POST | `/callbacks/delivery/track` | 兼容旧路径，等同 `xfx` |
 
 ### 4. mini-user 物流（ST1785939375449985）
 
 | 页面 | 行为 |
 |------|------|
-| 订单详情 | 状态为**配送中**（`SHIPPING`/`SHIPPED`）时，状态下方展示最新一条路由信息；右侧「物流详情」进入详情页 |
-| 物流详情 | 物流信息 + 完整动态时间线（**最新在上**）；无顶部配送状态区块；自定义导航栏无顶空白 |
-| 接口 | `GET /trade/orders/:id` + `GET /trade/orders/:id/track`；`shouldLoadOrderTrack`：有运单号或小飞侠 provider 时拉路由 |
-| 公共模块 | `apps/mini-user/src/lib/order-logistics.ts` |
+| 订单详情 | **配送中**展示最新路由摘要 + 「物流详情」；物流未到时展示 **预估送达**（100301） |
+| 物流详情 | 物流信息；**签收照片**（有则展示，`previewImage` 放大）；**物流动态**旧→新、节点全红点亮、最新在底部 |
+| 电话拨号 | 物流文案中手机号可点击 `makePhoneCall` |
+| 接口 | `GET /trade/orders/:id/track`（`OrderTrackDto`）；C 端禁止直连小飞侠 |
+| 公共模块 | `order-logistics.ts` + `LogisticsRichText` 组件 |
+
+#### 4.1 对外回调 URL（提供给小飞侠）
+
+**生产**
+
+```
+POST https://api.dukanghaoke.com/api/v1/callbacks/courier/xfx/track
+Content-Type: application/json
+```
+
+**测试**
+
+```
+POST https://api-test.dukanghaoke.com/api/v1/callbacks/courier/xfx/track
+```
+
+请求体：
+
+| 字段 | 说明 |
+|------|------|
+| outNumber | 商户单号 |
+| number | 运单号 |
+| status | 1下单 2取件 3中转 4派件 5签收 7取消 |
+| statusName | 中文状态 |
+| trackInfo | 路由描述 |
+| createTime | 路由时间 |
+
+成功响应：`{"code":"100000","message":"success"}`
+
+#### 4.2 Courier 适配器（`integrations/courier`）
+
+| cmd | 能力 | Provider 方法 |
+|-----|------|---------------|
+| 100102 | 路由查询 | `getTrack` |
+| 100108 | 签收照片 | `getSignPhotos` → OSS → `signPhotoUrls` |
+| 100301 | 预估送达 | `checkDeliveryCoverage` → `estimatedArrival` |
+| 回调 | 路由推送 | `parseTrackCallback` + `mapTrackStatus` |
 
 ## 5. 数据表
 
@@ -70,6 +111,7 @@
 - [ ] 技术支持可创建/筛选/编辑优先级
 - [ ] 合伙人/门店登录空字段前端提示；暂停合伙人微信登录被拒
 - [ ] mini-user：电话脱敏、拨打埋点、提货确认、无分享按钮、首图 preview、门头/套餐正常
-- [ ] mini-user：低版本弹窗、UpdateManager；配送中展示最新物流 + 物流详情页（最新在上、无顶空白）
+- [ ] mini-user：配送中物流摘要 + 签收照预览 + 电话拨号 + 时间线旧→新全点亮 + 预估送达
+- [ ] 小飞侠路由回调 `POST /callbacks/courier/xfx/track` 可推进订单状态且幂等
 - [ ] 各端上传 >10MB 图片自动压缩后可上传；仍超限有明确报错
 - [ ] `pnpm lint` 无新增错误