Build and Deploy Front / deploy (push) Successful in 6m56s

Details

官网换 GradientWaves/TextType 并做性能减负；模块指南拆开发/运营；含营销指南、轨迹单与 H5 价格等改动。

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

2026-10-21 18:07:41 +08:00

4.8 KiB

Raw Blame History

轨迹中心开发指引

面向开发。运营日常见同页「运营」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 联调清单

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

8. 关键代码位置

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

4.8 KiB Raw Blame History Unescape Escape