# 轨迹中心开发指引

> 面向 **开发**。运营日常见同页「运营」Tab。  
> **OMS 与 TrackCenter 是两个系统**：OMS 通过 HTTP/`Oms:TrackService` 调用轨迹中心；拉取/推送主逻辑在 TrackCenter（`tracks-master`）。

---

## 1. 架构

```
OMS 订单事件
  → Outbox（TrackUpsert / LifecycleAppend）
  → HTTP TrackCenter ProviderService
       ├── Order/UpsertSmallBag   （建/更新轨迹订单）
       └── Track/Upsert            （追加生命周期节点）
  →（TrackCenter 内）拉取服务商 / 标准化 / 推送业务方 / 预警
```

配置：`Oms:TrackService`（`BaseUrl`、`AppKey`、`AppSecret`）。

---

## 2. OMS 侧：何时 Upsert / Append

实现主要在 `OrderService.ParcelBilling.cs` 及 Messaging Handler。

| 触发 | OMS 方法 / 事件 | 说明 |
|------|-----------------|------|
| 预报排货成功 | `PublishForecastTrackAsync` | `AppendInitialTrackOnSuccess=true`（初始节点） |
| 入库排货成功 | `EnqueueSmallBagTrackUpsertAsync` | 默认不强制初始节点 |
| TrackNo 变化 | `Enqueue…WhenTrackNoChanged` / 同步 Upsert | 常带初始节点 |
| 入库扫描 | `OrderLifecycleTrackAppendIntegrationEvent` | 入库生命周期码 |
| 出库扫描 | 同上 | 出库生命周期码 |
| 手工/调试/批量 | 对应 Order API | 按入参 |

**要点：**

- 创单 HTTP **不直接**发轨迹；须预报（或入库）排货出 `ChannelCode`。  
- 异步预报任务无 HttpContext：payload 须带创单捕获的 **Authorization**，否则轨迹网关 401。  
- TrackNo 为空时可用 ClientNo 占位，真正 TrackNo 到达后再 Upsert。

### Upsert 关键字段

| 字段 | 含义 |
|------|------|
| Client | 客户编码 |
| OrderNo | **ServiceNo**（运单号） |
| TrackNo | 跟踪号（可占位） |
| CountryCode 等 | 收件信息 |
| ApiCode | 拉单路由：下游供应商码 → 产品/渠道 rules 快照 SupplierCode → live 等 |
| Channel / Product / OtherNo | 渠道、产品、客户单号 |

OMS 扩展字段（不一定进 Upsert Body）：`Authorization`、`AppendInitialTrackOnSuccess`。

---

## 3. TrackCenter：主数据与配置模型

| 概念 | 说明 |
|------|------|
| AppKey | 业务方隔离 |
| 轨迹状态 / 内容 / 标记 | 标准化主数据 |
| 拉取配置 | AppKey + **服务商** 唯一；内容映射 + 优先级 |
| 推送配置 | AppKey + **客户** 唯一；内容映射按 Sort |
| 预警 | 运输 / 妥投 / 退回 |

订单类型：小包 / 大包 / 主单；可关联同步。

---

## 4. 轨迹拉取（TrackCenter）

路由前缀约 `/Track/PullConfig`（`TrackPullService`）。

```
拉取主配置
  ├── 内容映射 N（状态值 / 关键词 / 反向词 → TrackContent）
  └── 优先级 N（客户 + 单号类型 + PullInterval 分钟，最小常被钳到 60）
```

新建主配置通常自动插入 `Customer=*` 兜底优先级（禁止删）。

**匹配顺序：** 状态值 Contains → 正向关键词 → 反向词否决 → 未映射（保留原文 hash 去重）。

**触发：**

- 手工：`POST /ProviderService/Track/Refresh`（无能更新订单 →「一个能更新的都没有」）  
- 定时：`TrackPullTask` + Redis 锁（TTL≈PullInterval）  
- 消费：`TrackRefreshEventHandler` → 命中则 `TrackUpsert`，否则写未映射  

报文解析路径依赖应用配置 `InterfaceRelayParamsConfigOptions` 与页面字段对齐。

---

## 5. 轨迹推送（TrackCenter）

路由前缀约 `/Track/PushConfig`（`TrackPushService`）。

```
推送主配置（IsAutoPush / IsCanUpdate / IsAllPush / 时间格式…）
  └── 内容映射（OrderNoType + Sort；推送给对方的 code/文案/状态）
```

**系统推送：** `TrackUpsertEventHandler` → `TrackPushEventHandler`  
- 异常单一般不自动推  
- Sort 顺序校验（可用 SwapTrackContentId）  
- `IsAutoPush` 必须为 true  

**手工推送：** `POST /ProviderService/Track/Push`（不强制顺序）。  
推送记录在 ES；完成回调队列 `TrackPushCompletedSubscribe`。

---

## 6. 预警

配置：运输超时、妥投、退回；依赖分区与状态/标记因子。  
推送内容变更可能触发退回类预警重算（`ReturnWarningHandler`）。

---

## 7. OMS ↔ Track 联调清单

1. `Oms:TrackService` 可达且鉴权正确  
2. 预报/入库已排出 `ChannelCode` / `ApiCode`  
3. 异步任务 Authorization 未丢  
4. TrackCenter 侧该服务商拉取映射已配  
5. 需要回传时客户推送 `IsAutoPush` + Sort 顺序  

---

## 8. 关键代码位置

| 侧 | 位置 |
|----|------|
| OMS 发轨迹 | `OrderService.ParcelBilling.cs`（Publish/Enqueue）、`Messaging/*Track*` |
| TrackCenter 拉取/推送 | `TrackPullService` / `TrackPushService`、`TrackRefreshEventHandler` / `TrackPushEventHandler` |
| 前端菜单 | `/track/*`（OMS 前端代理到轨迹中心 API 以部署为准） |