# G62 读错一行，物流 Agent 就会编出错误时间线

> 把 TMS 接入 Agent 前，先弄懂五种关键 X12 报文，以及 G62 为何随报文类型改变含义。

原文: https://fdetimes.net/zh/guides/edi-x12-guide-logistics-fde/

设想你在一家物流公司的第一周。客户想要一个 Agent，能回答“这批货在哪，晚没晚？”

IT 团队给你打开一个文件夹，里面全是文本文件。每行开头是两三个大写字母，字段之间用符号分隔。他们的运输管理系统（TMS）根本没有 REST API，只有 EDI X12。

这种情况下，难点不在模型，而在于正确读懂报文：同一个段的含义，取决于它所在的报文类型。解析器一旦读错，Agent 照样会信心十足地回答，只是答案是错的。

本文介绍最常遇到的五种报文类型、解析器里一个具体的陷阱，以及客户会拿来评判你的测试用例。

## 一批货会产生哪些报文？

对整车公路运输来说，一切从 204 开始。货主或其他相关方用这条报文向整车承运商发出运输委托。其中，B2 携带货物基本信息，S5 对应每个停靠点，N1 是相关各方，L11 是参考号。

承运商用 990 回复：接受或拒绝这批货。卡车上路后，承运商发送 214，向货主、收货人和代理报告货物状态。开头的 B10 段携带货物参考号等标识，AT7 是核心：它包含状态代码、原因、状态时间和预约信息。

海运用 315 报告货物事件。这里要读 N9 获取参考号，Q2 获取船舶和航行日期，R4 获取港口，SG 获取状态。

997 是功能确认，用于回复一条报文或一组报文：接收方确认已收到，并说明报文被接受、带错误接受还是被拒绝。

| 报文类型 | 谁发送，为什么 | 优先读取的段 | AI 系统用它做什么 |
|---|---|---|---|
| 204 | 货主向承运商发出运输委托 | B2、S5、N1、L11、G62（回复截止时间） | 计划：停靠点、相关方、回复截止时间 |
| 990 | 承运商接受或拒绝 | 与正确版本的 204 匹配 | 这批货是有车可派，还是要重新分配 |
| 214 | 承运商报告公路货物状态 | B10、AT7 | 用于预测延误的事件时间线 |
| 315 | 报告海运货物事件 | N9、Q2、R4、SG | 船舶、港口、货物状态 |
| 997 | 接收方做技术确认 | AK5、AK9 | 连接是否健康，不是业务数据 |

## G62 陷阱：一个随报文类型改变含义的段

TrueCommerce 的 214 指南里有一条简短规则：不得用 G62 报告货物状态的日期和时间，这个时间位于 AT7。而在 204 中，头部的 G62 携带的是回复委托的截止时间。

假设一位赶工的工程师为所有报文写了同一个“查找日期时间”的函数，靠扫描 G62 实现。在 204 上，这个函数会取到回复截止时间，并把它记成一个货物事件。

在 214 上，它会跳过真正存放时间的 AT7。于是 Agent 会根据根本不是事件的时间戳，说出“货物晚到 6 小时”。

**要点:** 在 EDI 中，只看段名无法确定含义，还必须知道它所在的报文类型。

所以解析器必须先按报文类型分流，再读取各段。下面的 Python 示例刻意没有硬编码每个字段的位置。字段位置来自每个合作方的实施指南，不能靠猜。

```python
def parse_segments(raw, seg_term="~", elem_sep="*"):
    # 分隔符按合作方文档设置，绝不假定默认值
    return [s.strip().split(elem_sep) for s in raw.split(seg_term) if s.strip()]

def first(segs, tag):
    return next((s for s in segs if s[0] == tag), None)

# tx_type：从 ST 段名之后的第一个元素读取，例如 first(segs, "ST")[1] == "214"
# field_map：根据实施指南建立的对照表；pick(seg, name) 返回记录位置上的元素
def to_records(tx_type, segs, field_map):
    if tx_type == "214":
        return {
            "shipment_ref": field_map.pick(first(segs, "B10"), "shipment_ref"),
            # 事件时间只取自 AT7，绝不取自 G62
            "events": [field_map.pick(s, "status") for s in segs if s[0] == "AT7"],
        }
    if tx_type == "204":
        return {
            "stops": [s for s in segs if s[0] == "S5"],
            # 204 头部的 G62 = 回复委托的截止时间
            "respond_by": field_map.pick(first(segs, "G62"), "datetime"),
        }
    if tx_type == "997":
        return {"ack": True}  # 只记录，绝不回复
    raise ValueError(f"不支持的报文类型 {tx_type}")
```

这种写法迫使你先回答“这是什么报文”，再回答“这是什么字段”。客户为海运业务加入 315 时，只需新增一个读取 N9、Q2、R4 和 SG 的分支，不必改动 214 的逻辑。

## 997 表示“已收到”，不表示“同意”

第二个错误通常出现得更晚，在系统运行几周之后。在 997 中，AK5 报告每个事务集的结果（如有错误也会列出），AK9 报告整个功能组的结果和事务集数量。当所有结果都显示为接受时，很容易以为每批货都没问题。

实际上，997 或 999 只说明报文通过了技术校验。一条 204 可能先收到表示接受的 997，随后又收到表示拒绝的 990。业务结果必须单独跟踪，依据是 990 或对账报告。

还有一点：990 对应的是某个特定版本的 204。如果客户把一个委托修改了两次，系统必须把接受回复匹配到正确的委托。被拒绝的委托必须退回调度重新分配，不能悄悄停在“已发送”状态。

反方向也需要一条硬规则。X12 标准规定，997 本身不得再被确认，以免陷入“确认的确认”的无限循环。如果你的 AI 管道会生成报文，就写一个测试，证明它永远不会用 997 回复 997。

## 对接客户 EDI 的四个步骤

到现场的第一步，是向每个合作方要实施指南，而不是要数据库权限。建立一张对照表：报文类型、段、字段、业务含义。拿着这张表和调度员过一遍，因为他们知道哪些状态代码真正在用。

第二步，按上文的方式构建按报文类型分流的解析器，并把原始报文和标准化记录一起存储。Agent 答错时，你需要追溯到产生这个答案的那一行 AT7 或 SG。

第三步，维护两张独立的状态表：一张记录 997（连接是否健康），一张记录 204/990/214（货物情况如何）。AI 系统只读第二张，第一张用于运维告警。

最后一步是测试套件。Stacksync 的 990 测试指南要求测试被拒绝的委托，并确认它退回调度重新分配。这是应该最先写的测试：如果它不通过，被拒绝的货物就会闲置，没人再派一辆车。

## 让客户失去信任的错误

常见错误都很眼熟：在 214 中从 G62 取事件时间，把表示接受的 997 当成委托已被接受，把 990 匹配到旧版本的 204，漏掉拒绝的情况，以及让管道用 997 回复 997。修复这些错误都不需要 AI 知识，需要的是仔细读文档、尽早写测试。

职业方面，阅读物流行业的前线部署工程师（FDE）或解决方案工程师招聘启事时，留意“EDI”“X12”和“TMS”这几个词。看到它们，就在面试中直接问：这个岗位有多少时间花在系统集成上。

简历上不要只写“有 EDI 经验”。要具体：你对接过 204/990/214 流程，把 997 与业务结果分开对账，并为被拒绝的委托编写了测试套件。

延误预测 Agent 的质量，取决于喂给它的时间线。面对物流客户，这一切从事件时间取自 AT7、而不是 G62 开始。

**本周动手试试:**

- 手写一条小的 214 和一条小的 204，都包含 G62，然后写一个测试，检查解析器只从 AT7 获取事件时间
- 为一个被 990 拒绝的委托写测试，检查这批货是否回到调度队列
- 向客户 IT 团队索取每个合作方的 EDI 实施指南，在写第一行代码之前建好“段 → 数据字段”对照表

## 信源

- [Product: X12 EDI (TrueCommerce: X12 214 Transportation Carrier Shipment Status Message)](https://help.truecommerce.com/en/articles/10208514-x12-214-transportation-carrier-shipment-status-message)

- [EDI 214 Transportation Carrier Shipment Status Message (Stedi X12 004010)](https://www.stedi.com/edi/x12-004010/214)

- [EDI 204 Motor Carrier Load Tender (Stedi X12 004050)](https://www.stedi.com/edi/x12-004050/204)

- [EDI 990 Response to a Load Tender (Stedi X12 004050)](https://www.stedi.com/edi/x12-004050/990)

- [Stacksync: XPO Logistics Freight Inc, EDI 990](https://www.stacksync.com/edi/xpo-logistics-freight-inc/990)

- [EDI 997 Functional Acknowledgment (Stedi X12 004010)](https://www.stedi.com/edi/x12-004010/997)

- [EDI 315 Status Details (Ocean) (Stedi X12 003060)](https://www.stedi.com/edi/x12-003060/315)
