zzh
f1d219ae48
Add product/channel billing condition editors, place-order additional services, billing simulator, forecast-to-inbound fee delta and margin warnings, insurance-aware claim tips, OMS preset dict seeds, and related AI skills/system pages. Co-authored-by: Cursor <cursoragent@cursor.com>
152 lines
5.0 KiB
Markdown
152 lines
5.0 KiB
Markdown
---
|
||
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 可提示缺项。
|