错误码映射转换工具

将不同供应商的短信错误码统一映射到云信标准错误码体系。

快速开始

基本使用流程

# 步骤 1: 准备云信标准错误码规则文件（已内置）
# 规则文件位置: references/yxe_error_codes.csv

# 步骤 2: 运行映射工具
python3 scripts/error_code_mapper.py <供应商错误码文件> [输出文件路径]

# 示例
python3 scripts/error_code_mapper.py ./supplier_codes.csv ./mapped_result.xlsx
python3 scripts/error_code_mapper.py ./vendor_errors.xlsx

详细功能说明

1. 支持的输入格式

CSV 文件: 包含错误码和错误原因的表格
XLSX 文件: Excel 格式的错误码文档

输入文件要求:

必须包含错误码列（列名可能为：错误码、code、error_code、errCode 等）
必须包含错误原因列（列名可能为：错误原因、描述、description、msg、message 等）
支持自动识别常见列名

2. 映射逻辑

工具使用 语义相似度匹配 将供应商错误码映射到云信标准：

关键词匹配: 提取错误原因中的关键词进行匹配
语义相似度: 使用文本相似度算法找到最匹配的云信错误码
规则优先级: 内置映射规则优先于自动匹配

映射规则示例:

供应商原始原因	匹配关键词	映射到云信错误码
黑名单/BLACK/投诉拉黑	黑名单、投诉、BLACK	YXE:002 黑名单
敏感词/内容审核不通过	敏感词、审核、屏蔽	YXE:003 敏感词
频率超限/发送过快	频率、超限、过快、限流	YXE:004 频率超限
携号转网/运营商变更	携号、转网、变更	YXE:005 携号转网
模板不匹配/格式错误	模板、格式、不匹配	YXE:007 模板不匹配
手机号错误/格式非法	手机号、格式、非法	YXE:010 手机号码错误
关机/停机/空号	关机、停机、空号	YXE:014/YXE:015/YXE:016
网络超时/连接失败	网络、超时、连接	YXE:009 网络问题
成功/已送达/DELIVRD	成功、送达、DELIVRD	DELIVRD 成功

3. 输出格式

输出为 XLSX 文件，包含以下列：

列名	说明
供应商原始错误码	输入文件中的错误码
供应商原始错误原因	输入文件中的错误描述
云信规约错误码	映射后的云信标准错误码
云信规约错误原因	云信标准错误描述
匹配置信度	语义匹配的相似度分数 (0-1)
映射方式	匹配方式（关键词/语义/规则）

使用示例

示例 1: 映射 CSV 文件

输入文件 (supplier_codes.csv):

error_code,error_msg
E001,用户手机号在黑名单中
E002,内容包含敏感词汇
E003,发送频率超过限制
E004,网络连接超时
E005,短信发送成功

运行命令:

python3 scripts/error_code_mapper.py supplier_codes.csv result.xlsx

输出结果:

供应商原始错误码 | 供应商原始错误原因 | 云信规约错误码 | 云信规约错误原因 | 匹配置信度 | 映射方式
E001 | 用户手机号在黑名单中 | YXE:002 | 黑名单 | 0.95 | 关键词
E002 | 内容包含敏感词汇 | YXE:003 | 敏感词 | 0.92 | 关键词
E003 | 发送频率超过限制 | YXE:004 | 频率超限 | 0.90 | 关键词
E004 | 网络连接超时 | YXE:009 | 网络问题 | 0.88 | 语义
E005 | 短信发送成功 | DELIVRD | 成功 | 1.00 | 规则

示例 2: 映射 XLSX 文件

python3 scripts/error_code_mapper.py ./vendor_data.xlsx ./output.xlsx

示例 3: 批量处理多个文件

# 处理目录中的所有 CSV/XLSX 文件
for file in ./suppliers/*.csv; do
    python3 scripts/error_code_mapper.py "$file" "./output/$(basename $file .csv).xlsx"
done

自定义映射规则

添加自定义规则

编辑 references/custom_rules.json 文件：

{
  "custom_mappings": [
    {
      "supplier_code": "VENDOR_001",
      "supplier_reason": "自定义错误描述",
      "yxe_code": "YXE:001",
      "yxe_reason": "发送失败"
    }
  ],
  "keyword_rules": [
    {
      "keywords": ["自定义关键词1", "自定义关键词2"],
      "yxe_code": "YXE:001",
      "yxe_reason": "发送失败"
    }
  ]
}

脚本说明

error_code_mapper.py

主要功能：

解析 CSV/XLSX 输入文件
自动识别错误码和错误原因列
使用语义匹配算法映射到云信标准
生成带置信度的映射结果

参数说明:

python3 scripts/error_code_mapper.py <input_file> [output_file] [--rules custom_rules.json]

参数:
  input_file    输入文件路径 (CSV 或 XLSX)
  output_file   输出文件路径 (默认: mapped_result.xlsx)
  --rules       自定义规则文件路径 (可选)

注意事项

输入文件编码: CSV 文件建议使用 UTF-8 编码
列名识别: 工具会自动识别常见列名，如果识别失败会提示手动指定
匹配置信度: 置信度低于 0.6 的映射结果需要人工复核
未匹配项: 无法匹配的错误码会标记为 "UNKNOWN"，需要手动处理

依赖说明

脚本依赖以下 Python 库：

pandas: 数据处理
openpyxl: Excel 文件读写
difflib: 文本相似度计算
re: 正则表达式

安装依赖:

pip install pandas openpyxl

error-code-mapper