6.7 KiB

Raw Blame History

身份证识别接口 - 快速测试指南

📌 实现总结

✅ 已完成 - 身份证识别接口 /marriage/ocr/parseIdCard 已成功添加到 OcrController

🚀 快速测试步骤

前提条件

已配置百度OCR API Key和Secret Key
应用已启动，监听在 8080 端口
已获取验证码和手机号

测试流程

1️⃣ 上传身份证图片

curl -X POST \
  -F "file=@/path/to/idcard_front.jpg" \
  http://localhost:8080/marriage/ocr/upload

保存返回的 uploadId

2️⃣ 调用身份证识别接口

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "mobile": "18888888888",
    "smsCode": "123456",
    "uploadId": "xxx"
  }' \
  http://localhost:8080/marriage/ocr/parseIdCard

📋 完整的请求/响应示例

请求

{
  "mobile": "18888888888",
  "smsCode": "123456",
  "uploadId": "a1b2c3d4e5f6g7h8"
}

成功响应（识别成功）

{
  "code": 200,
  "msg": "success",
  "data": {
    "raw": "{...百度API原始响应JSON...}",
    "words": ["王连杰", "男", "汉族", "1995年04月01日", "江苏省南京市建邺区...", "320321199504011218"],
    "parsed": {
      "name": "王连杰",
      "gender": "男",
      "nationality": "汉族",
      "birthday": "1995-04-01",
      "address": "江苏省南京市建邺区...",
      "id_number": "320321199504011218"
    },
    "parsed_detailed": {
      "name": {
        "word": "王连杰",
        "probability": {
          "average": 20.68798065,
          "min": 0.9106679559
        },
        "location": {
          "width": 109,
          "height": 47,
          "top": 933,
          "left": 253
        }
      },
      "gender": {
        "word": "男",
        "probability": {
          "average": 24.97878838,
          "min": 0.9302400351
        },
        "location": {
          "width": 39,
          "height": 40,
          "top": 973,
          "left": 792
        }
      },
      "nationality": {
        "word": "汉族",
        "probability": {
          "average": 17.19703484,
          "min": 0.7144192457
        },
        "location": {
          "width": 79,
          "height": 43,
          "top": 1011,
          "left": 249
        }
      },
      "birthday": {
        "word": "1995-04-01",
        "probability": {
          "average": 20.66628647,
          "min": 0.7240950465
        },
        "location": {
          "width": 250,
          "height": 55,
          "top": 1044,
          "left": 857
        }
      },
      "address": {
        "word": "江苏省南京市建邺区...",
        "probability": {
          "average": 18.5,
          "min": 0.75
        },
        "location": {
          "width": 300,
          "height": 60,
          "top": 1100,
          "left": 300
        }
      },
      "id_number": {
        "word": "320321199504011218",
        "probability": {
          "average": 13.2870388,
          "min": 0.5172381401
        },
        "location": {
          "width": 341,
          "height": 68,
          "top": 1081,
          "left": 343
        }
      }
    }
  }
}

失败响应示例

缺少关键字段:

{
  "code": 400,
  "msg": "请上传完整清晰的身份证正面",
  "data": null
}

验证码错误:

{
  "code": 400,
  "msg": "验证码错误，请重新输入！",
  "data": null
}

文件过期:

{
  "code": 400,
  "msg": "上传文件不存在或已过期，请重新上传！",
  "data": null
}

🔍 响应字段说明

parsed 字段（简化格式）

用于快速获取识别结果，仅包含文本内容：

name - 姓名
gender - 性别
nationality - 民族
birthday - 出生日期（已格式化为 YYYY-MM-DD）
address - 住址
id_number - 身份证号

parsed_detailed 字段（详细格式）

用于获取完整的识别信息，每个字段包含：

word - 识别的文本内容
probability - 识别概率
- average - 平均概率 (0-100)
- min - 最小概率
location - 在图片中的位置
- width - 宽度（像素）
- height - 高度（像素）
- top - 距顶部（像素）
- left - 距左侧（像素）

💡 使用建议

1. 检查识别质量

// 检查识别概率
if (data.parsed_detailed.name.probability.average < 60) {
  console.warn('姓名识别质量较低，建议人工审核');
}

2. 提取特定字段

// 简单方式
const name = data.parsed.name;

// 详细方式
const nameData = data.parsed_detailed.name;
const nameWord = nameData.word;
const nameConfidence = nameData.probability.average;

3. 验证关键信息

// 验证身份证号长度
if (data.parsed.id_number.length !== 18) {
  console.error('身份证号长度不正确');
}

// 验证日期格式
const dateRegex = /^\d{4}-\d{2}-\d{2}$/;
if (!dateRegex.test(data.parsed.birthday)) {
  console.error('出生日期格式不正确');
}

🔧 常见问题

Q: 如何区分结婚证识别和身份证识别？

结婚证识别：POST /marriage/ocr/parse
身份证识别：POST /marriage/ocr/parseIdCard

Q: 上传接口可以共用吗？

A: 是的，使用相同的上传接口：POST /marriage/ocr/upload

Q: 识别概率很低怎么办？

上传更清晰的身份证照片
确保光线充足
避免倾斜和反光
考虑人工审核

Q: location 信<><E4BFA1><EFBFBD>有什么用？

在前端标注识别位置
裁剪识别结果进行二次处理
验证识别的准确性

Q: 支持身份证反面吗？

A: 当前实现仅支持身份证正面（id_card_side: "front"）。如需支持反面，可参考代码逻辑进行扩展。

📊 API对比

功能	结婚证识别	身份证识别
接口URL	`/marriage/ocr/parse`	`/marriage/ocr/parseIdCard`
上传接口	`/marriage/ocr/upload`	`/marriage/ocr/upload`
百度API	marriage_certificate	idcard
支持反面	是（可扩展）	否（仅正面）
probability	✅	✅
location	✅	✅
向后兼容	✅	✅

🧪 使用 Postman 测试

1. 新建 POST 请求

URL: http://localhost:8080/marriage/ocr/parseIdCard

2. 设置 Headers

Key	Value
Content-Type	application/json

3. 设置 Body (raw JSON)

{
  "mobile": "18888888888",
  "smsCode": "123456",
  "uploadId": "a1b2c3d4e5f6g7h8"
}

4. 点击 Send

📖 相关文档

实现完成日期: 2025-11-26
版本: v1.0.0
状态: ✅ 生产就绪

6.7 KiB Raw Blame History Unescape Escape