321 lines
6.7 KiB
Markdown
321 lines
6.7 KiB
Markdown
# 身份证识别接口 - 快速测试指南
|
||
|
||
## 📌 实现总结
|
||
|
||
✅ **已完成** - 身份证识别接口 `/marriage/ocr/parseIdCard` 已成功添加到 OcrController
|
||
|
||
## 🚀 快速测试步骤
|
||
|
||
### 前提条件
|
||
- 已配置百度OCR API Key和Secret Key
|
||
- 应用已启动，监听在 8080 端口
|
||
- 已获取验证码和手机号
|
||
|
||
### 测试流程
|
||
|
||
#### 1️⃣ 上传身份证图片
|
||
|
||
```bash
|
||
curl -X POST \
|
||
-F "file=@/path/to/idcard_front.jpg" \
|
||
http://localhost:8080/marriage/ocr/upload
|
||
```
|
||
|
||
**保存返回的 uploadId**
|
||
|
||
#### 2️⃣ 调用身份证识别接口
|
||
|
||
```bash
|
||
curl -X POST \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"mobile": "18888888888",
|
||
"smsCode": "123456",
|
||
"uploadId": "xxx"
|
||
}' \
|
||
http://localhost:8080/marriage/ocr/parseIdCard
|
||
```
|
||
|
||
## 📋 完整的请求/响应示例
|
||
|
||
### 请求
|
||
|
||
```json
|
||
{
|
||
"mobile": "18888888888",
|
||
"smsCode": "123456",
|
||
"uploadId": "a1b2c3d4e5f6g7h8"
|
||
}
|
||
```
|
||
|
||
### 成功响应（识别成功）
|
||
|
||
```json
|
||
{
|
||
"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
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 失败响应示例
|
||
|
||
**缺少关键字段**:
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"msg": "请上传完整清晰的身份证正面",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**验证码错误**:
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"msg": "验证码错误，请重新输入！",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**文件过期**:
|
||
```json
|
||
{
|
||
"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. 检查识别质量
|
||
|
||
```javascript
|
||
// 检查识别概率
|
||
if (data.parsed_detailed.name.probability.average < 60) {
|
||
console.warn('姓名识别质量较低，建议人工审核');
|
||
}
|
||
```
|
||
|
||
### 2. 提取特定字段
|
||
|
||
```javascript
|
||
// 简单方式
|
||
const name = data.parsed.name;
|
||
|
||
// 详细方式
|
||
const nameData = data.parsed_detailed.name;
|
||
const nameWord = nameData.word;
|
||
const nameConfidence = nameData.probability.average;
|
||
```
|
||
|
||
### 3. 验证关键信息
|
||
|
||
```javascript
|
||
// 验证身份证号长度
|
||
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: 如何区分结婚证识别和身份证识别？
|
||
|
||
A:
|
||
- 结婚证识别：POST `/marriage/ocr/parse`
|
||
- 身份证识别：POST `/marriage/ocr/parseIdCard`
|
||
|
||
### Q: 上传接口可以共用吗？
|
||
|
||
A: 是的，使用相同的上传接口：POST `/marriage/ocr/upload`
|
||
|
||
### Q: 识别概率很低怎么办？
|
||
|
||
A:
|
||
1. 上传更清晰的身份证照片
|
||
2. 确保光线充足
|
||
3. 避免倾斜和反光
|
||
4. 考虑人工审核
|
||
|
||
### Q: location 信<><E4BFA1><EFBFBD>有什么用？
|
||
|
||
A:
|
||
- 在前端标注识别位置
|
||
- 裁剪识别结果进行二次处理
|
||
- 验证识别的准确性
|
||
|
||
### 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)
|
||
|
||
```json
|
||
{
|
||
"mobile": "18888888888",
|
||
"smsCode": "123456",
|
||
"uploadId": "a1b2c3d4e5f6g7h8"
|
||
}
|
||
```
|
||
|
||
### 4. 点击 Send
|
||
|
||
## 📖 相关文档
|
||
|
||
- [OCR功能完整文档](OCR_API_DOCUMENT.md)
|
||
- [身份证识别实现详情](IDCARD_IMPLEMENTATION.md)
|
||
- [快速参考指南](OCR_QUICK_REFERENCE.md)
|
||
|
||
---
|
||
|
||
**实现完成日期**: 2025-11-26
|
||
**版本**: v1.0.0
|
||
**状态**: ✅ 生产就绪
|
||
|