一句话说明：面向日本线业务，打单前自动把日文收件人姓名转写成代理可用的英文名（罗马字），写入转单接口的
consigneeNameEng。转写失败时直接拦截打单，不会用其它翻译顶替，也不会把日文原样发出去。
寄往日本的运单，日本代理店要求面单上的收件人姓名必须是拉丁字母。
在此之前系统走的是通用机器翻译，日文姓名里的汉字和假名常常被原样透传给代理（例如 あさの りん 传过去还是 あさの りん），代理端反馈错误率超过 50%，需要人工逐票改正，严重影响时效。
现在改为使用 AI 做罗马字转写（transliteration），并且针对日本线的实际写法做了专门处理：
| 场景 | 原来的机器翻译 | 现在 |
|---|---|---|
| 常规日文姓名 | 假名/汉字原样透传 | 山田 太郎 → Yamada Taro |
| 姓名顺序 | 不保证 | 强制姓在前、名在后（原文是「名 姓」时会自动重排） |
| 外国人的片假名名字 | 按日文读音硬拼 | 还原护照写法：ブランドン → Brandon（不是 Burandon） |
| 中国籍收件人 | 按日文音读 | 用汉语拼音：张 三 → Zhang San（不是 Chou San） |
| 旧字体、异体字 | 常出错 | 髙橋 弘子 → Takahashi Hiroko |
| 姓名之间没有空格 | 切不开 | 藤原量 → Fujiwara Ryo |
| 长音 | 规则一刀切会错 | 佐藤 → Sato，但 井上 保留为 Inoue、松浦 保留为 Matsuura |
| 公司名、带敬称 | — | 株式会社エンリッチ → Enrich Co., Ltd.、西谷さん → Nishitani-san |
效果已用 18850 条真实收件人姓名跑过全量验证并经客户确认：零失败、零空值，同一个姓名每次输出完全一致。
本功能使用贵司自己的 AI 服务账号，用量费用由贵司承担（实测成本极低，全量 18850 条约 1 元人民币量级）。
需要提供：
⚠️ API Key 属于敏感凭据，请通过客服私下提供，不要贴在公开的工单、群聊里。若曾经泄露过，请到 DeepSeek 后台重新生成一把再提供。
把 Key 交给客服后，由我方运维在系统后台为贵司机构完成开通。可配置项如下（通常保持默认即可，有特殊需要再跟客服提）：
| 配置项 | 默认值 | 说明 |
|---|---|---|
| AI 服务密钥 | 无默认，必须配置 | 即上面 2.1 的 API Key，按机构隔离，各机构互不影响 |
| 使用的模型 | deepseek-v4-flash |
客户已确认效果的模型 |
| 单次转写超时 | 5 秒 | 可调范围 1–30 秒 |
| 失败重试次数 | 2 次 | 可调范围 0–3 次；仅对限流、服务端异常这类临时故障重试 |
| 结果缓存天数 | 3 天 | 同一个收件人姓名在此期间内不再重复调用 AI |
⚠️ 未开通就使用会拦截打单。 如果没有配置密钥就配了下面的脚本，打单时会提示「本机构未配置收件人姓名转写的 DeepSeek API Key，请联系客服配置后再打单」。
建议先在一个转单 API 上配置脚本试跑，确认面单上的英文名符合日本代理要求后，再推广到其它日本线渠道。
转单 API → 执行脚本 → 打单前（取号前执行）。
// 日文收件人姓名 → 英文名（罗马字），结果写入转单接口的 consigneeNameEng
// 转写失败时把错误信息作为脚本返回值，系统据此拦截打单
(function () {
try {
var name = $waybill.getShouJianRenXingMing();
if (name == null || String(name).trim() == "") {
return "";
}
$apiEntity.put("consigneeNameEng",
$jsService.getBean("japaneseNameRomanizeService").romanize(String(name).trim()));
return "";
} catch (e) {
return "收件人姓名转写失败，已拦截打单：" + e.message;
}
})()
第一，return 的空字符串／错误信息就是拦不拦单的开关。
打单前脚本靠返回值决定要不要拦单：返回空字符串放行，返回非空文字则中断打单，并把这段文字显示给操作人员。所以转写失败时必须 return 一段错误信息，不能只在脚本里记个日志。
第二，整段都要包在 try 里。
包括取收件人姓名、取服务这两句。系统会把脚本内部抛出的错误吞掉、只记一条运单日志就继续打单，所以必须由脚本自己捕获再返回错误信息，拦截才会生效。
第三，外层的 (function () { ... })() 不能拆掉。
脚本引擎不允许在最外层直接写 return，拆掉外层函数会立刻变成语法错误；而这个语法错误又会被上一条说的机制吞掉——结果就是打单照常发出、姓名根本没被转写，而且没有任何提示。包成这种立即执行函数还有个好处：里面的变量不会残留到同一批次执行的其它脚本里。
⚠️ 如果贵司的转单接口取的不是
consigneeNameEng这个字段，请把脚本里的字段名换成实际使用的那个，其余不变。
consigneeNameEng 并存入缓存；半角空格、全角空格、多余空格的差异不影响缓存复用——
岡田 美沙子与岡田 美沙子视为同一个人。
以下任一情况发生时，这一票会被拦下、不会推给代理，打单人员会看到「收件人姓名转写失败，已拦截打单：……」的提示：
| 情况 | 提示里会看到 | 怎么处理 |
|---|---|---|
| 未配置密钥 | 本机构未配置收件人姓名转写的 DeepSeek API Key，请联系客服配置后再打单 | 联系客服开通 |
| 账户没钱 | DeepSeek 账户余额不足，请充值后重试 | 到 DeepSeek 后台充值 |
| 密钥无效／被停用 | DeepSeek API Key 无效或无权限 | 重新生成密钥后交客服更新 |
| 超时、网络异常、AI 服务故障 | DeepSeek 调用失败，已重试 N 次…… | 稍后重试；持续出现请联系客服 |
| AI 返回的内容不可用于面单 | 姓名转写结果含非法字符…… / 结果为空 | 少见；请把该运单号反馈客服 |
这是客户明确要求的行为：宁可拦下这一票让人工介入，也不能把没转写好的姓名发给日本代理——姓名错误会引发清关问题并造成经济损失。因此系统不会在失败时回退到普通机器翻译，也不会把日文原文当英文名发出去。
只允许英文字母、空格，以及句点 .、逗号 ,、连字符 -、撇号 ' 这四个符号（用于 Enrich Co., Ltd.、Nishitani-san 这类真实写法），并且必须至少含一个字母。出现数字、括号、日文字符等一律判为不可用并拦截。
转写是同步进行的，也就是说打单会等它出结果：
⚠️ 打单会比以前慢一些，这是本功能的固有代价。 姓名必须在推单给代理之前拿到正确结果，所以只能同步等待、等不到就拦截。若贵司对打单速度敏感，可与客服沟通调整超时与重试次数——但调得过小会让本来能成功的票被误拦，请谨慎。
Q：以前配过的翻译脚本还要留着吗？
不要。请把转单 API 打单前脚本里旧的姓名翻译逻辑整段替换成第三节的脚本，两套同时存在会互相覆盖。
Q：同一个收件人第二次打单，结果会不一样吗？
不会。缓存有效期内直接复用上一次的结果；即使缓存过期重新调用，同一个姓名的输出也是一致的（已用 18850 条样本验证）。
Q：能不能只对日本件启用？
可以。脚本配置在转单 API 上，只在日本线使用的那些转单 API 上配置即可，其它渠道不受影响。
Q：收件人姓名本来就是英文的，会被改坏吗？
不会。已有的拉丁字母会被保留，只做大小写和空格的规范化。
Q：能不能不拦截、失败就用原文发出去？
不能，这是客户方明确要求的设计。若确有此需求，请通过客服提出，由业务侧评估。