# 轨迹中心新手指引

> 本文面向第一次接触 **轨迹中心（Track Center）** 的运营、客服与开发同学，帮助你理解「轨迹如何从服务商拉取、标准化入库、再推送给业务方」的完整链路，以及各菜单模块分别做什么。

---

## 1. 系统是什么？

**轨迹中心**是一套 **物流轨迹采集、标准化、存储与推送** 的中台服务（后端项目 `TrackCenter`）。它的核心目标是：

- 按 **应用（AppKey）** 隔离不同业务方的轨迹数据；
- 维护 **轨迹状态 / 轨迹内容 / 轨迹标记** 等主数据，把各服务商的原始描述映射为统一模型；
- 通过 **轨迹拉取配置** 向服务商拉取轨迹，经映射后写入订单；
- 通过 **轨迹推送配置** 把标准化后的轨迹推送给 OMS、客户系统或第三方回调；
- 提供 **轨迹订单** 查询、手工补录、刷新与推送能力；
- 基于规则做 **运输 / 妥投 / 退回** 等 KPI 预警。

你可以把它理解为：**轨迹主数据 + 拉取映射 + 推送映射 + 订单轨迹仓 + 预警引擎** 的组合。

---

## 2. 核心概念速查

| 概念 | 说明 | 在系统中的位置 |
|------|------|----------------|
| **应用（AppKey）** | 业务方身份，轨迹配置与订单均按 AppKey 隔离 | 各配置页、轨迹订单列表 |
| **轨迹订单** | 承载客户单号、尾程单号、最新轨迹摘要等的订单实体 | 菜单：轨迹订单 |
| **轨迹明细** | 单条轨迹事件（时间、时区、地点、内容、状态等），存于 ES | 轨迹订单详情 → 轨迹 Tab |
| **轨迹状态** | 轨迹节点编码（如已揽收、运输中、签收），用于状态机与预警 | 菜单：轨迹状态 |
| **轨迹内容** | 对外展示的轨迹文案（中/英），可关联状态与标记 | 菜单：轨迹内容 |
| **轨迹标记** | 轨迹标签（如异常、退回），用于筛选与预警因子 | 菜单：轨迹标记 |
| **轨迹拉取** | 某 App + 服务商 + 订单类型下的拉取规则与内容映射 | 菜单：轨迹拉取 |
| **轨迹推送** | 向业务方推送轨迹时的映射与优先级 | 菜单：轨迹推送 |
| **预警分区** | KPI 统计用的地理/业务分区 | 菜单：预警分区 |
| **预警配置** | 运输超时、妥投、退回等预警规则 | 菜单：预警配置 |
| **预警订单** | 已触发的预警明细与处理 | 菜单：预警订单 |

### 轨迹来源（TrackSourceEnum）

| 值 | 含义 |
|----|------|
| 1 | 外部服务商（拉取或接口回写） |
| 2 | 内部系统 |
| 3 | 人工补录 |

### 订单类型（TrackOrderType）

| 值 | 含义 |
|----|------|
| 1 | 小包 |
| 2 | 大包 |
| 4 | 主单 |

小包、大包、主单可存在 **关联关系**；拉取/更新轨迹后，系统可按关联关系 **向下游订单同步** 轨迹（见 CAP `TrackUpsert` 处理逻辑）。

---

## 3. 端到端业务流程

### 3.1 参与方

```
业务系统 / OMS / WMS
        │
        ▼
   轨迹中心（TrackCenter）
        │
        ├── 订单创建 / 订阅（ProviderService）
        ├── 定时或手工拉取（接口转发 → 服务商）
        ├── 入参映射 → 轨迹内容/状态匹配 → 写入 ES
        ├── 推送映射 → 回调业务方
        └── 预警引擎（运输/妥投/退回）
        │
        ▼
   外部轨迹服务商 API
```

### 3.2 轨迹拉取（概要）

配置分三层：**拉取主配置** → **内容映射** → **拉取优先级**。触发后由 `TrackRefreshEventHandler` 解析服务商报文并匹配内容映射，命中则发布 `TrackUpsert` 写入 ES；未命中则写入「未映射」原始轨迹。详见 [4.4 轨迹拉取详解](#44-轨迹拉取详解)。

### 3.3 轨迹推送（概要）

按 **AppKey + 客户（Customer）** 唯一维护推送主配置与 **推送内容映射**（含 Sort 顺序）。轨迹新增/修改后由 `TrackPushEventHandler` 组装报文并经接口转发回调业务方，结果写入 ES 推送记录。详见 [4.5 轨迹推送详解](#45-轨迹推送详解)。

### 3.4 人工补录

在 **轨迹订单** 详情中可新增/编辑轨迹明细（来源为「人工」），适用于服务商无节点、客服补录等场景。补录后同样走标准化与可选推送、预警逻辑。

---

## 4. 各菜单功能说明

| 菜单路径 | 主要功能 | 典型操作 |
|----------|----------|----------|
| **新手指引** `/track/guide` | 本文档，系统说明与配置顺序 | 首次接入必读 |
| **轨迹订单** `/track/order` | 订单列表、轨迹时间轴、补录、刷新、推送 | 按单号查询 → 打开详情 → 刷新/推送 |
| **预警订单** `/track/warningOrder` | 运输/妥投/退回预警单处理 | 筛选 → 查看详情 → 关闭/跟进 |
| **轨迹状态** `/track/state` | 维护状态编码与中英文名称 | 新增状态 → 与内容、预警规则关联 |
| **轨迹标记** `/track/flag` | 维护轨迹标签 | 配置异常类等标记 |
| **轨迹内容** `/track/content` | 维护标准轨迹文案，关联状态 | 配置展示文案、英文文案 |
| **轨迹拉取** `/track/pull` | 拉取主配置、内容映射、优先级 | 选服务商 → 建拉取配置 → 映射内容 |
| **轨迹推送** `/track/push` | 推送主配置、内容映射 | 配置推送字段与优先级 |
| **预警配置** `/track/kpiEarlyWarningConfig` | 运输、妥投、退回预警规则 | 按产品+国家配置时效与规则 |

### 4.1 轨迹订单详情 Tab

| Tab | 作用 |
|-----|------|
| **详情** | 订单主信息与轨迹列表 |
| **推送记录** | 历史推送报文与结果 |
| **日志** | 订单操作日志 |
| **拉取配置** | 当前订单关联的拉取配置快照 |
| **订单轨迹 / 外部轨迹** | 内外部轨迹时间轴展示 |

### 4.2 轨迹拉取 / 推送页面布局

| 页面 | 左侧 | 中间 / 主区 | 右侧 / 子表 |
|------|------|-------------|-------------|
| **轨迹拉取** `/track/pull` | 服务商列表 | 拉取主配置列表 | 内容映射、拉取优先级 |
| **轨迹推送** `/track/push` | 客户列表 | 推送主配置 | 推送内容映射（可排序） |

### 4.3 预警配置类型

| 类型 | 说明 |
|------|------|
| **运输预警** | 从起始状态到目标状态的超时未更新 |
| **妥投预警** | 签收相关 KPI |
| **退回预警** | 退回类轨迹异常 |

---

## 4.4 轨迹拉取详解

后端路由前缀：`/Track/PullConfig`（`TrackPullService`）。数据表：`t_track_pull_config`、`t_track_pull_content_config`、`t_track_pull_priority_config`。

### 4.4.1 三层配置模型

```
AppKey + ServiceProviderCode（唯一）
    ├── 拉取主配置（TrackPullConfigEntity）
    ├── 内容映射 N 条（TrackPullContentConfigEntity）→ 关联「轨迹内容」主数据
    └── 拉取优先级 N 条（TrackPullPriorityEntity）→ 决定用哪种单号、多久拉一次
```

**唯一性约束**：同一 `AppKey + ServiceProviderCode` 只能有一条拉取主配置（新增/修改时后端校验，重复会报「配置已经存在」）。

**新增主配置时的默认行为**：保存成功后，系统**自动插入一条兜底优先级**（不可删除）：

| 字段 | 默认值 | 含义 |
|------|--------|------|
| Customer | `*`（全部客户） | 未单独配置客户时使用 |
| OrderNoType | 跟踪单号 | 用尾程/跟踪单号向服务商查询 |
| Priority | 999 | 数值越大优先级越低，兜底排最后 |
| PullInterval | 720 分钟（12 小时） | 定时拉取间隔 |

### 4.4.2 拉取主配置字段

| 字段 | 说明 | 业务用途 |
|------|------|----------|
| AppKey | 应用标识 | 与订单、接口转发上下文隔离 |
| ServiceProviderCode | 服务商编码 | 与订单上的服务商、定时任务分组一致 |
| StartTrackCode | 开始轨迹 code | 订单到达该轨迹节点后，才进入正常拉取周期（配合订单拉取状态扫描） |
| EndTrackCode | 结束轨迹 code | 订单到达该节点后进入结束态；配合 **SilenceAfterEnd** 停止拉取 |
| SilenceBeforeStart | 开始前静默（小时） | 未达 StartTrackCode 前的等待；订单拉取状态为 `SilenceBeforeStart`，由定时任务扫描启动 |
| SilenceAfterEnd | 结束后静默（小时） | 签收等结束后仍可能短暂拉取，之后停止 |
| TrackExtraNames | 扩展字段名（逗号分隔） | 从服务商单条轨迹 JSON 中按路径提取字段，合并为 `Extra` 存入 ES |

前端编辑项中还包含 **报文解析** 相关字段（`EditTrackPullConfigInput`，写入配置供消费端使用）：

| 字段 | 说明 |
|------|------|
| ParseMethod | 1=取映射后标准返参，2=取服务商原始返参 |
| OrderPath | 订单节点在响应 JSON 中的路径 |
| OrderNoName | 单号字段名（用于反查主单） |
| TrackDetailsPath | 轨迹明细数组/对象路径 |
| TrackStatusName / TrackContentName / TrackContentCodeName | 状态、内容、代码字段名 |
| TrackPlaceName | 发生地字段名 |
| TrackIsoTimeName / TrackTimeName / TrackTimeZoneName | ISO 时间、本地时间、时区字段名 |
| OrderType / Customer | 订单类型、客户（与优先级配合） |

> 实际解析时，`TrackRefreshEventHandler` 主要使用全局 `InterfaceRelayParamsConfigOptions` 中的路径配置；请与运维确认应用配置与页面配置一致。

### 4.4.3 内容映射（拉取内容配置）

每条映射把 **服务商原始轨迹** 对应到一条 **轨迹内容**（`TrackContentId`），从而得到标准 `TrackCode`、状态、中英文文案。

| 字段 | 说明 |
|------|------|
| TrackContentId | 关联「轨迹内容」主数据，决定入库后的标准轨迹 code |
| TrackStatusValue | 服务商状态值，**多个用英文逗号分隔**；与报文中状态字段精确匹配 |
| TrackKeyword | 正向关键词，逗号分隔；轨迹描述 **包含** 任一关键词即候选 |
| TrackKeywordReverse | 反向关键词；若描述 **包含** 反向词，则 **否决** 该条映射 |
| TrackPlaceValue | 发生地兜底枚举：返回值、目的港、起运港、目的国、起运国、目的城市、起运城市 |
| TrackTimePlaceValue | 时区发生地兜底（与地点枚举类似） |

**保存校验（避免重复映射）**：

- 同一拉取配置下，**TrackContentId** 不可重复；
- **TrackStatusValue** 中任一值不可与其它行的状态集合冲突；
- **TrackKeyword** 中任一关键词不可与其它行冲突。

**运行时匹配顺序**（`TrackRefreshEventHandler.HandleTrackAsync`）：

1. **轨迹状态**：用 `TrackStatusName` 从报文取值，与某行的 `TrackStatusValues` 列表匹配（`Contains`）；
2. **轨迹内容关键词**：若状态未命中，则遍历各映射的 `TrackKeywords`，描述包含关键词则命中；
3. **反向关键词**：命中后若描述含 `TrackKeywordReverse` 中任一词，则视为未命中；
4. 仍未命中：写入 ES 为 **未映射轨迹**（`TrackContentId = -1`，保留原始内容与报文 hash，默认 `IsExternal = false`）。

**去重**：同一订单下，相同原始报文 hash（`OriginTrackDataHash`）已存在则跳过，避免重复消费。

### 4.4.4 拉取优先级

按 **客户 + 订单号类型** 细分拉取策略（表 `t_track_pull_priority_config`）。

**订单号类型（TrackOrderNoType）**：

| 值 | 含义 |
|----|------|
| 1 | 客户单号 |
| 2 | 跟踪单号 |
| 4 | 其他单号 |

| 字段 | 说明 |
|------|------|
| Customer | 客户简称；`*` 表示全部客户（系统兜底行） |
| OrderNoType | 调用服务商 API 时使用的单号类型 |
| Priority | 数值越小越优先（与注释「最优先级、最匹配」一致） |
| PullInterval | 拉取频率，**单位：分钟**；保存时若小于 60，后端强制改为 60 |

**唯一性**：同一拉取配置下 `Customer + OrderNoType` 不可重复。

**删除限制**：`Customer = *` 的兜底行 **禁止删除**，否则会报「兜底配置禁止被删除」。

### 4.4.5 拉取触发与执行链路

#### 手工刷新

`POST /ProviderService/Track/Refresh`

1. 单号去重、去空；
2. 按 AppKey + 单号查询可刷新的订单（需已配置拉取、订单存在）；
3. 按 `ServiceProviderCode + AppKey + OrderType` 分组；
4. 每组调用 `BatchForwardThenPushToQueueAsync`（拉取标准接口编码来自应用配置 `GetTrackInterfaceCode`）；
5. 无可用订单时抛出：**「一个能更新的都没有」**。

#### 定时拉取

`POST /TimerTask/Refresh`（`TrackPullTask`，Hangfire）

1. 关联查询所有 **拉取主配置 + 优先级行**；
2. 为每条优先级配置创建后台任务 `RefreshForConfigAsync`；
3. Redis 锁 key：`TrackPullKey(config)`，TTL = `PullInterval * 60` 秒，防止同一策略并发重复拉取；
4. 分页查询待拉取订单，按订单类型分组批量转发；
5. 队列名由 `TrackAppOptions.TrackPullTaskLevel` 决定。

#### 消费拉取结果

队列订阅：`TrackRefreshSubscribe` → `TrackRefreshEventHandler`

1. 转发失败（`IsSuccess = false`）直接记日志返回；
2. 从 `Attach` 反序列化 `TrackRefreshAttach`（服务商、AppKey、OrderType）；
3. Redis 读取 `AppKey:ServiceProviderCode` 下的拉取配置 + 内容映射列表（`TrackPullCacheService`，编辑后自动刷新缓存）；
4. 按 `OrderPath` 解析订单列表，再按 `TrackDetailsPath` 遍历轨迹节点；
5. 用平台单号反查主单（`GetTrackOrderByProviderAndOrderNo`），找不到则告警跳过；
6. 匹配成功 → 发布 `TrackUpsertForRefreshSubscribe`；匹配失败 → 仅写未映射 ES 记录。

### 4.4.6 拉取相关 API

| 接口 | 说明 |
|------|------|
| `POST /Track/PullConfig/GetPage` | 主配置分页（可按 AppKey、服务商名关键字） |
| `GET /Track/PullConfig/GetDetail` | 主配置详情 |
| `POST /Track/PullConfig/Edit` | 主配置增删改（Options：新增/修改/删除） |
| `POST /Track/PullConfig/GetContentPage` | 内容映射分页 |
| `GET /Track/PullConfig/GetContentDetail` | 内容映射详情 |
| `POST /Track/PullConfig/EditContent` | 内容映射增删改 |
| `POST /Track/PullConfig/GetPriorityPage` | 优先级分页 |
| `GET /Track/PullConfig/GetPriorityDetail` | 优先级详情 |
| `POST /Track/PullConfig/EditPriority` | 优先级增删改 |
| `POST /ProviderService/Track/Refresh` | 手工刷新 |

---

## 4.5 轨迹推送详解

后端路由前缀：`/Track/PushConfig`（`TrackPushService`）。数据表：`t_track_push_config`、`t_track_push_content_config`。推送记录存 **Elasticsearch**（`TrackPushRecordIndex`）。

### 4.5.1 两层配置模型

```
AppKey + Customer（唯一）
    ├── 推送主配置（TrackPushConfigEntity）
    └── 推送内容映射 N 条（TrackPushContentConfigEntity），按 OrderNoType + Sort 排序
```

**唯一性约束**：同一 **Customer** 只能有一条推送主配置（按客户维度，与 AppKey 组合使用）。

**缓存**：`TrackPushCacheService` 以 `AppKey:Customer` 为 key 缓存内容映射列表（TTL 约 3 天；无数据时 5 秒），主配置或内容变更后自动 `SetPushContentConfigsAsync` 刷新。

### 4.5.2 推送主配置字段

| 字段 | 说明 |
|------|------|
| AppKey | 应用标识 |
| Customer | 客户（外部主体 ID），推送策略按客户隔离 |
| ServiceProviderCode | 服务商编码；推送前校验，为空会报「未关联服务商，无法推送」 |
| IsAutoPush | 是否自动推送；为 false 时系统推送会被拦截，需手工推送 |
| IsCanUpdate | 是否允许推送「修改」类轨迹 |
| IsCanDelete | 是否允许推送「删除」类轨迹（当前删除分支未实现推送） |
| IsAllPush | 全量推送：为 true 时会把历史已推轨迹一并组装进报文 |
| IsAllPushWithLatest | 全量模式下，同 code + 同比较字段时替换旧条，保证最新一条 |
| DateTimeFormatType | 时间格式：0 默认、1 时间戳、2 时间+时区 |
| DateTimeFormat | 时间模板；保存时后端会返回「格式化样例」供核对 |
| TimezoneFormat | 时区模板；若填时区则必须同时填时间格式 |

**时间格式校验**（`CheckDateTimeFormat`）：

- 类型为 **时间戳**：输出 Unix 时间样例；
- 类型为 **时间+时区**：可仅时间、或时间+时区组合；填了时区未填时间会报错；
- 默认：`yyyy-MM-ddTHH:mm:ss.fffK`。

### 4.5.3 推送内容映射

每条映射描述：**当订单出现某标准轨迹 code 时，推送给业务方的字段取值**。

| 字段 | 说明 |
|------|------|
| OrderNoType | 订单类型：小包 / 大包 / 主单（与拉取 OrderType 一致） |
| TrackContentId | 关联轨迹内容主数据 |
| Sort | 推送顺序，**数值越小越靠前**；新增时自动 `Max(Sort)+1` |
| TrackContentCodeValue | 推送给对方的轨迹 code 参数值 |
| TrackContentValue | 中文描述参数值 |
| TrackEnContentValue | 英文描述参数值 |
| TrackStatusValue | 状态参数值 |
| SwapTrackContentId | 可交换的轨迹内容 ID；用于顺序校验时的「等价节点」 |
| ExtraConfig | JSON：把订单表字段或轨迹 Extra 映射到推送体 `extra`（如 `t_order.xxx`） |

**唯一性**（同一推送配置 + 同一 OrderNoType 下不可重复）：

- TrackContentId
- TrackContentCodeValue
- TrackStatusValue
- TrackContentValue
- TrackEnContentValue

**排序**：`POST /Track/PushConfig/SortContent` 可拖拽调整 Sort；删除某条后，同 OrderNoType 下更大 Sort 的记录会自动减 1。

**配置变更与预警**：修改/删除推送内容映射后，会异步触发 `ReturnWarningHandler.PushConfigChangedHandleAsync` 重新计算退回类预警。

### 4.5.4 推送触发方式

#### 自动推送（系统）

轨迹入库/更新后，`TrackUpsertEventHandler` 在满足条件时发布 `TrackPushSubscribe`（`TrackPushEvent`）。

`TrackPushEventHandler` 处理逻辑要点：

1. 按 AppKey + Customer 加载推送配置，无配置则直接 return；
2. 按 **OrderNoType** 分组，每组内按 **Sort 升序** 得到推送顺序链表；
3. **新增（OptionType.新增）且 OperationMan 为空** → 走系统推送 `BuiltSystemPushItemsAsync`：
   - 异常单（`QuestionType = Error`）**不自动推**，只能人工；
   - 必须在映射中找到当前 `TrackCode` 对应行；
   - `IsAutoPush` 必须为 true；
   - **顺序校验**：订单上 `LatestPushTrackCode` 须与本次推送构成「上一条 + 1」或命中 **SwapTrackContentId** 交换节点，否则报「推送顺序异常」；
4. **修改（OptionType.修改）** → `DoUpdateAsync`，需 `IsCanUpdate`，调用更新类标准接口编码（`TrackUpdateInterfaceCode`）。

#### 手工推送

`POST /ProviderService/Track/Push`

- 按 AppKey、OrderType、OrderNos 查订单；
- 从 ES 取指定 `TrackCode` 的轨迹；支持 `CompareFields` + `CompareValue` 按扩展字段过滤；
- 每个订单取 **CreateTime 最新** 的一条；
- 发布 `TrackManualPushSubscribe`，带 `OperationMan`（当前用户名）。

手工推送 **不校验** 是否已推过、**不强制** 顺序（但仍受 `IsAllPush` 等配置影响）。

#### 推送报文组装

`BuiltPushItem` 生成的业务字段（写入对方回调 Body）：

| 字段 | 来源 |
|------|------|
| date | 按 DateTimeFormatType 格式化 TrackTime + TimeZone |
| timeZone | 轨迹发生时区 |
| location | 轨迹发生地 |
| description / descriptionCn | 映射中的英/中文参数值 |
| code / status | 映射中的 code、状态参数值 |
| extra | 轨迹 Extra + ExtraConfig 解析订单字段合并 |

`IsAllPush = true` 时：读取最近一次成功推送记录，合并历史节点，再追加当前节点；`IsAllPushWithLatest` 控制同 code 是否去重替换。

### 4.5.5 推送完成与记录

- 批量调用 `BatchForwardThenPushToQueueAsync`（`PushTrackInterfaceCode`），回调队列 `TrackPushCompletedSubscribe`；
- 成功/失败通过 `BroadcastingService` 发 RabbitMQ：`TrackPush.{AppKey}`；
- 订单详情 **推送记录** Tab：`GET /ProviderService/Track/GetTrackPushRecords`；
- 高级查询：`POST /ProviderService/Track/QueryTrackPushRecords`（支持成败、中英文内容、轨迹时间、推送时间范围）；
- 获取可推轨迹 code 列表：`GET /ProviderService/Track/GetTrackPushContentList?appKey=&customer=`。

### 4.5.6 推送相关 API

| 接口 | 说明 |
|------|------|
| `POST /Track/PushConfig/GetPage` | 主配置分页 |
| `GET /Track/PushConfig/GetDetail` | 主配置详情 |
| `POST /Track/PushConfig/Edit` | 主配置增删改，返回时间格式样例文案 |
| `POST /Track/PushConfig/GetContentPage` | 内容映射分页 |
| `GET /Track/PushConfig/GetContentDetail` | 内容映射详情 |
| `POST /Track/PushConfig/EditContent` | 内容映射增删改 |
| `POST /Track/PushConfig/SortContent` | 调整 Sort 顺序 |
| `POST /ProviderService/Track/Push` | 手工推送 |
| `GET /ProviderService/Track/GetTrackPushContentList` | 可推送轨迹 code 列表 |
| `GET /ProviderService/Track/GetTrackPushRecords` | 单订单推送记录 |
| `POST /ProviderService/Track/QueryTrackPushRecords` | 批量查询推送记录 |

### 4.5.7 拉取 vs 推送 对照

| 维度 | 轨迹拉取 | 轨迹推送 |
|------|----------|----------|
| 配置主键 | AppKey + **服务商** | AppKey + **客户** |
| 子配置维度 | 内容映射 + **优先级（客户+单号类型+频率）** | 内容映射（**订单类型+Sort 顺序**） |
| 核心目标 | 服务商报文 → 标准轨迹内容 | 标准轨迹 → 业务方回调字段 |
| 顺序含义 | 内容映射为 **匹配规则**，无全局顺序 | Sort 为 **业务推送节点顺序** |
| 定时任务 | `TrackPullTask` 按 PullInterval | 无（由轨迹变更事件驱动） |
| 典型失败 | 未映射、单号找不到主单 | 顺序错误、未开自动推送、异常单 |

---

## 5. 新手推荐配置路径

按以下顺序操作，可最快跑通「拉取 → 入库 → 推送」：

### 第一步：维护主数据

1. **轨迹状态**：创建业务需要的状态编码（与 OMS 状态机对齐）。
2. **轨迹标记**（可选）：配置异常、退回等标记。
3. **轨迹内容**：为每个展示节点配置中英文文案，并关联对应 **轨迹状态**。

### 第二步：确认拉取接口可用

1. 与开发确认轨迹服务商的 **拉取接口** 已在网关侧配置完成（含鉴权、签名、入参/出参映射）。
2. 记录拉取配置所需的 **标准接口编码**、**服务商接口编码**，并确认对应配置已 **发布生效**。
3. 确保当前 **AppKey** 已具备调用该拉取接口的权限。

### 第三步：配置轨迹拉取

1. 进入 **轨迹拉取**，选择服务商，新建主配置（AppKey + 服务商唯一）。
2. 填写 **StartTrackCode / EndTrackCode**、静默小时数、扩展字段名（若需要）。
3. 为常见服务商状态/描述添加 **内容映射**（先状态精确匹配，再关键词；注意反向词）。
4. 按客户补充 **拉取优先级**（单号类型 + PullInterval）；保留系统自带的 `*` 兜底行。
5. 确认网关拉取接口可用后，在轨迹订单试 **刷新轨迹**。

### 第四步：配置轨迹推送（若需回传业务方）

1. 进入 **轨迹推送**，按 **客户** 新建主配置（每客户一条）。
2. 开启 **IsAutoPush**，配置时间格式并保存（核对返回的样例字符串）。
3. 按 **小包/大包/主单** 分别维护推送内容映射，设置 **Sort** 顺序（与业务节点顺序一致）。
4. 需要一次推全流程时开启 **IsAllPush**；仅需最新节点时配合 **IsAllPushWithLatest**。
5. 在业务侧准备好接收回调；用 **手工推送** 或观察 **推送记录** 验证。

### 第五步：验证

1. 在 **轨迹订单** 中按单号查询，或等待订单订阅入库。
2. 使用 **刷新轨迹** 触发拉取，在详情中查看新轨迹节点。
3. 查看 **推送记录** 确认业务方是否收到。
4. 若配置了预警，在 **预警订单** 中观察是否按规则触发。

---

## 6. 网关接口编码（拉取 / 推送）

定时任务与手工刷新/推送通过 **接口转发** 调用，编码来自应用配置（非轨迹表字段）：

| 场景 | 配置项（示例名） | 订阅队列 |
|------|------------------|----------|
| 拉取轨迹 | `GetTrackInterfaceCode` | `TrackRefreshSubscribe` |
| 推送新增 | `PushTrackInterfaceCode` | `TrackPushCompletedSubscribe` |
| 推送修改 | `TrackUpdateInterfaceCode` | `TrackPushCompletedSubscribe` |

拉取/推送内容映射变更后会刷新 **Redis 缓存**；网关侧接口映射须 **发布生效** 后才会改变 HTTP 行为。

---

## 7. 主要后端 API（TrackCenter）

供联调与排查参考（前缀以部署环境为准，如 `/TrackCenter`）：

| 路由 | 说明 |
|------|------|
| `POST /Track/Order/GetTrackOrderList` | 轨迹订单分页列表 |
| `POST /Track/Order/UpdateOrderStatus` | 更新订单完成状态等 |
| `POST /Track/Status/*` | 轨迹状态 CRUD |
| `POST /Track/Content/*` | 轨迹内容 CRUD |
| `POST /Track/Flag/*` | 轨迹标记 CRUD |
| `POST /Track/PullConfig/*` | 拉取配置与内容映射 |
| `POST /Track/PushConfig/*` | 推送配置与内容映射 |
| `POST /ProviderService/Track/Refresh` | 手工刷新轨迹 |
| `POST /ProviderService/Track/Push` | 手工推送轨迹 |
| `POST /Warning/*` | 预警查询与处理 |
| `POST /ForewarningService/*` | 预警分区与规则 |

---

## 8. 常见问题

### Q1：刷新轨迹提示「一个能更新的都没有」？

- 检查订单是否存在、AppKey 是否匹配；
- 检查是否已配置对应服务商的 **轨迹拉取**；
- 检查拉取配置中的 **接口编码** 是否正确，网关侧映射是否已 **发布生效**。

### Q2：拉取到了轨迹但订单摘要未变？

- 在详情查看是否为 **未映射轨迹**（有原始内容、无标准 TrackCode）；
- 检查 **TrackStatusValue** 是否与服务商返回值一致（区分大小写逻辑见代码：状态为 Contains 匹配）；
- 关键词是否被 **反向关键词** 否决；
- 内容映射是否与它行 **TrackContentId / 状态 / 关键词** 冲突导致保存失败。

### Q3：业务方收不到推送？

- 确认该客户 **IsAutoPush** 已开启，且订单非 **异常单**（异常单只能手工推）；
- 检查 **LatestPushTrackCode** 与本次 TrackCode 是否满足 Sort 顺序（或 Swap 节点）；
- 映射中是否存在当前 TrackCode 与 OrderNoType；
- 在 **推送记录** 查看拦截原因（Rabbit 广播失败消息）或网关 requestId；
- 核对 **ServiceProviderCode** 是否已在推送主配置中填写。

### Q4：预警未触发或误报？

- 核对 **预警分区** 是否覆盖该订单国家/渠道；
- 检查 **预警配置** 中起始/结束状态、时间阈值与因子（标记、内容）；
- 确认轨迹时间与 **时区** 配置是否正确。

### Q5：小包/大包/主单轨迹不一致？

- 存在订单 **关联关系** 时，系统可能将轨迹同步到关联单；
- 拉取配置按 **订单类型** 区分，需分别配置。

---

## 9. 延伸阅读

| 文档 | 内容 |
|------|------|
| `docs/中后台前端页面设计规范.md` | 前端页面开发规范 |

---

**建议学习顺序**：先看第 3 章流程 → 精读 [4.4 轨迹拉取](#44-轨迹拉取详解) 与 [4.5 轨迹推送](#45-轨迹推送详解) → 按第 5 章实操 → 结合 **推送记录**、未映射轨迹与网关 requestId 排查。