front/src/views/track/trackGuide/guide.md

轨迹中心新手指引

本文面向第一次接触 轨迹中心（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 轨迹拉取详解。

3.3 轨迹推送（概要）

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

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 轨迹拉取 与 4.5 轨迹推送 → 按第 5 章实操 → 结合 推送记录、未映射轨迹与网关 requestId 排查。