---
name: oms-receiver-address-parse
description: >-
  Parses and roughly validates international logistics recipient addresses for OMS
  place-order (PC/H5). Use when working on 收件地址, AI解析, parse-address,
  receiver fields, 地址完整性, or /order/receiver/parse-address prompts/UX.
---

# OMS 国际物流收件地址解析

面向**跨境/国际物流下单**：把客户粘贴的整段地址拆成 OMS `receiver.*` 字段，并做**粗校验**（能否预报/打单），不是地图级精校、也不是国内快递四级地址库。

实现入口：

- 后端：`POST /order/receiver/parse-address`（`OrderService.ReceiverAddressParse.cs`）
- PC：`src/views/order/placeOrder/index.vue`（左粘贴 / 右表单）
- H5：`H5PlaceOrderSheet.vue`（收件步「AI解析」弹窗）
- API：`postOrderReceiverParseAddress`（`src/api/order/index.ts`）

改 prompt / 校验规则时，以本 skill 为准，前后端口径保持一致。

## 目标（只做这些）

1. **拆字段**：姓名、电话、国家、邮编、省/州、城市、街道行
2. **粗完整**：下单必填是否齐；建议项是否缺
3. **粗风险**：明显缺国家/邮编/街道、国家二字码说不清、电话不像号码 → `warnings`
4. **不编造**：原文没有的省市区邮编一律留空

## 不要做这些

- 不调用地图/邮政 API 做地址真实性验证
- 不强制「可投递 / 门牌存在 / 邮编与城市严格匹配」
- 不把国内四级联选（省市区街道）当成必须结构
- 不把税号/EORI/VAT 当成解析主目标（可有则填，无则忽略）

## OMS 字段映射

| JSON / API | 表单含义 | 说明 |
|------------|----------|------|
| `recipientsName` | 收件人名称 | 必填 |
| `phone` | 手机 | 必填；优先手机号 |
| `telePhone` | 电话 | 固话 |
| `email` | 邮箱 | 选填 |
| `companyName` | 公司 | 选填 |
| `countryCode` | 国家 | **ISO 二字码大写**（US/GB/DE…）必填 |
| `province` | 省/州 | 建议有（US State、CN 省、AU State） |
| `city` | 城市 | 建议有 |
| `streetNumber` | 门牌号 | 可选；能拆再拆 |
| `streetAddress1` | 地址1 | **必填**主街道行 |
| `streetAddress2/3` | 地址2/3 | 溢出或 Apt/Suite |
| `zipCode` | 邮编 | 必填（粗：非空且像邮编即可） |

## 完整度口径（粗校验）

### 必填（`missingRequired` / `isComplete=false`）

- 收件人名称
- 收件人手机
- 国家（二字码）
- 邮编
- 地址1

与 PC/H5 下单提交校验对齐。

### 建议（`missingRecommended`，不挡 `isComplete`）

- 省/州
- 城市  

多数渠道打单会用到；缺了给提示，不拦死。

### warnings（短中文）

适合写：

- 无法判断国家
- 电话疑似不完整
- 邮编格式可疑（如美国非 5/9 位、英国完全不像外邮编）
- 街道与姓名粘在一起拆不清

不要写：

- 「该地址在谷歌地图不存在」
- 「邮编与城市不匹配」（无权威数据时禁止臆断）

## 解析规则（中/英）

1. **国家**：中文名/英文名 → ISO2。常见：中国 CN、美国 US、英国 **GB**（勿用 UK 作主码）、香港 HK、台湾 TW、澳门 MO、德国 DE、法国 FR、日本 JP、澳大利亚 AU、加拿大 CA、新加坡 SG。
2. **中国地址**：省→`province`，市→`city`，区县+路号→`streetAddress1`；勿把省市区塞进姓名。
3. **英文地址**：`State`→`province`，`City`→`city`，street line→`streetAddress*`，ZIP/Postcode→`zipCode`。
4. **电话**：带国家码的 `+1`/`+44` 等保留；手机进 `phone`，固话进 `telePhone`。
5. **过长街道**：主行放 `streetAddress1`，其余 `2/3`；单独门牌可放 `streetNumber`。
6. **不确定就空**：宁可空 + warning，不要猜邮编/城市。

## LLM 输出契约

只输出 JSON（可被后端 `ExtractJsonObject` 抽取）：

```json
{
  "recipientsName": "",
  "companyName": "",
  "phone": "",
  "telePhone": "",
  "email": "",
  "countryCode": "",
  "province": "",
  "city": "",
  "streetNumber": "",
  "streetAddress1": "",
  "streetAddress2": "",
  "streetAddress3": "",
  "zipCode": "",
  "warnings": []
}
```

后端会再跑 `EvaluateCompleteness`，前端展示绿/橙/红提示。

## 改代码时注意

1. 改 system prompt → 同步本 skill + `OrderService.ReceiverAddressParse.cs`
2. 改必填集合 → 同步 PC `isSingleRecipientComplete` / H5 `validateStep(1)` / 后端 `EvaluateCompleteness`
3. UX：解析只**覆盖非空解析结果**；有选填内容时展开「更多」
4. 无 AI 提供商时接口应明确报错，勿静默假成功

## 自测样例

**英：**

```text
John Smith, +1 310-555-0199, 1001 Sunset Blvd, Los Angeles, CA 90001, USA
```

期望：US / CA / Los Angeles / 90001 / street 含 Sunset / phone 有值。

**中（跨境少见但仍要能拆）：**

```text
张三 13800138000 广东省深圳市南山区科技园南路 88 号 518000
```

期望：CN / 广东 / 深圳 / 邮编 518000 / 地址1 含南山区或路名。

**故意残缺：**

```text
Tom, Some Street, USA
```

期望：缺 phone/zip → `isComplete=false`，warnings 可提示缺项。