249 lines
6.3 KiB
Markdown
249 lines
6.3 KiB
Markdown
# 身份证识别接口实现完成
|
||
|
||
## ✅ 实现状态
|
||
|
||
身份证识别接口已成功添加到 `OcrController.java` 中，完全参考结婚证识别接口的逻辑。
|
||
|
||
## 📋 实现内容
|
||
|
||
### 1. 新增配置
|
||
|
||
在 OcrController 中添加了身份证API配置：
|
||
|
||
```java
|
||
@Value("${baidu.ocr.idCardUrl:https://aip.baidubce.com/rest/2.0/ocr/v1/idcard}")
|
||
private String idCardUrl;
|
||
```
|
||
|
||
### 2. 新增识别接口
|
||
|
||
**接口方法**: `/marriage/ocr/parseIdCard`
|
||
|
||
```java
|
||
@PostMapping("/parseIdCard")
|
||
public ResultObject parseIdCard(@RequestBody OcrParseDTO dto)
|
||
```
|
||
|
||
**功能**: 识别身份证正面
|
||
|
||
**流程**:
|
||
1. 验证手机号、验证码、上传ID
|
||
2. 从Redis中获取上传的图片Base64数据
|
||
3. 调用百度身份证识别API
|
||
4. 解析识别结果，提取字段数据（包含probability和location）
|
||
5. 返回详细和简化两种格式
|
||
|
||
### 3. 支持的识别字段
|
||
|
||
- **name** - 姓名
|
||
- **gender** - 性别
|
||
- **nationality** - 民族
|
||
- **birthday** - 出生日期
|
||
- **address** - 住址
|
||
- **id_number** - 身份证号
|
||
|
||
### 4. 核心辅助方法
|
||
|
||
#### parseIdCardFieldsFromRawDetailed()
|
||
从百度API原始响应解析身份证字段数据，提取所<EFBFBD><EFBFBD><EFBFBD>字段的word、probability和location信息。
|
||
|
||
#### extractFieldDataFromIdCardNode()
|
||
从JSON节点提取单个身份证字段的完整数据（word、probability、location）。
|
||
|
||
#### extractAndAddIdCardField()
|
||
提取并添加身份证字段到结果Map中。
|
||
|
||
#### parseIdCardFieldsSimple()
|
||
简单的字段解析（fallback方法）。
|
||
|
||
## 🚀 API 使用方法
|
||
|
||
### 第一步：上传身份证图片
|
||
|
||
```bash
|
||
curl -X POST \
|
||
-F "file=@idcard_front.jpg" \
|
||
http://localhost:8080/marriage/ocr/upload
|
||
```
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "success",
|
||
"data": {
|
||
"uploadId": "xxx"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 第二步：识别身份证正面
|
||
|
||
```bash
|
||
curl -X POST \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"mobile": "18888888888",
|
||
"smsCode": "123456",
|
||
"uploadId": "xxx"
|
||
}' \
|
||
http://localhost:8080/marriage/ocr/parseIdCard
|
||
```
|
||
|
||
## 📊 响应格式示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "success",
|
||
"data": {
|
||
"raw": "{百度API原始JSON响应}",
|
||
"words": ["王连杰", "男", "汉族", "1995年04月01日", ...],
|
||
"parsed": {
|
||
"name": "王连杰",
|
||
"gender": "男",
|
||
"nationality": "汉族",
|
||
"birthday": "1995-04-01",
|
||
"address": "江苏省南京市...",
|
||
"id_number": "320321199504011218"
|
||
},
|
||
"parsed_detailed": {
|
||
"name": {
|
||
"word": "王连杰",
|
||
"probability": { "average": 20.69, "min": 0.91 },
|
||
"location": { "width": 109, "height": 47, "top": 933, "left": 253 }
|
||
},
|
||
"gender": {
|
||
"word": "男",
|
||
"probability": { "average": 25.0, "min": 0.95 },
|
||
"location": { "width": 50, "height": 40, "top": 980, "left": 300 }
|
||
},
|
||
...其他字段...
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## ✨ 关键特性
|
||
|
||
### ✅ 完全参考parse接口逻辑
|
||
- 相同的验证流程
|
||
- 相同的Redis缓存机制
|
||
- 相同的API调用方式
|
||
- 相同的数据解析逻辑
|
||
|
||
### ✅ 复用upload接口
|
||
- 使用相同的上传接口
|
||
- 图片存储到Redis中
|
||
- 10分钟有效期
|
||
|
||
### ✅ 支持probability和location
|
||
- 返回识别概率信息（average和min）
|
||
- 返回识别位置信息（width、height、top、left）
|
||
- parsed和parsed_detailed两种格式
|
||
|
||
### ✅ 验证关键字段
|
||
- 必须包含name和id_number
|
||
- 缺少关键字段时返回错误提示
|
||
|
||
## 📝 配置要求
|
||
|
||
需要在 `application.properties` 或 `application.yml` 中配置百度OCR API参数：
|
||
|
||
```properties
|
||
baidu.ocr.apiKey=your_api_key
|
||
baidu.ocr.secretKey=your_secret_key
|
||
baidu.ocr.idCardUrl=https://aip.baidubce.com/rest/2.0/ocr/v1/idcard
|
||
```
|
||
|
||
## 🔍 流程对比
|
||
|
||
### 结婚证识别 (/parse)
|
||
```
|
||
upload() → parseIdCard()
|
||
├─ 验证手机号、验证码、uploadId
|
||
├─ 从Redis获取图片
|
||
├─ 调用百度API
|
||
├─ parseMarriageFieldsFromRawDetailed() - 提取字段
|
||
└─ 返回结果
|
||
```
|
||
|
||
### 身份证识别 (/parseIdCard)
|
||
```
|
||
upload() → parseIdCard()
|
||
├─ 验证手机号、验证码、uploadId
|
||
├─ 从Redis获取图片
|
||
├─ 调用百度API
|
||
├─ parseIdCardFieldsFromRawDetailed() - 提取字段
|
||
└─ 返回结果
|
||
```
|
||
|
||
## 🛠️ 技术细节
|
||
|
||
### 百度API请求参数
|
||
```java
|
||
params.put("image", imageBase64); // 图片Base64
|
||
params.put("id_card_side", "front"); // 正面
|
||
params.put("probability", "true"); // 返回概率信息
|
||
params.put("location", "true"); // 返回位置信息
|
||
```
|
||
|
||
### 字段解析流程
|
||
1. 获取API返回的 `words_result` 数组
|
||
2. 取第一个元素（通常是完整的结果对象）
|
||
3. 逐个提取各字段（姓名、性别、民族等）
|
||
4. 构建OcrFieldData对象（包含word、probability、location）
|
||
5. 同时转换为简化格式（仅包含word）
|
||
|
||
### 错误处理
|
||
- 验证码错误时返回 `验证码错误，请重新输入！`
|
||
- 文件不存在时返回 `上传文件不存在或已过期，请重新上传！`
|
||
- 缺少关键字段时返回 `请上传完整清晰的身份证正面`
|
||
- API调用失败时返回 `识别失败，请稍后再试！`
|
||
|
||
## 📚 文件位置
|
||
|
||
- **源文件**: `/Users/bugjiewang/StudioProjects/fucai-server/com-marriage-client/src/main/java/com/jinrui/marriage/client/controller/OcrController.java`
|
||
|
||
**新增的方法**:
|
||
- `parseIdCard()` - 主要接口方法
|
||
- `parseIdCardFieldsFromRawDetailed()` - 详细字段解析
|
||
- `extractFieldDataFromIdCardNode()` - 单个字段提取
|
||
- `extractAndAddIdCardField()` - 字段辅助添加
|
||
- `parseIdCardFieldsSimple()` - 简化字段解析（fallback）
|
||
|
||
## ✅ 编译验证
|
||
|
||
代码已成功编译，仅有以下警告（非关键）：
|
||
- 字段未使用警告
|
||
- 泛型参数警告
|
||
- 条件始终真/假警告
|
||
- main()方法签名警告
|
||
|
||
所有功能已完整实现，可正常使用。
|
||
|
||
## 🔗 相关接口
|
||
|
||
### 上传接口
|
||
- **URL**: `/marriage/ocr/upload`
|
||
- **方法**: POST
|
||
- **参数**: file（MultipartFile）
|
||
- **返回**: uploadId
|
||
|
||
### 结婚证识别接口
|
||
- **URL**: `/marriage/ocr/parse`
|
||
- **方法**: POST
|
||
- **参数**: mobile, smsCode, uploadId
|
||
- **返回**: 结婚证识别结果
|
||
|
||
### 身份证识别接口（新增）
|
||
- **URL**: `/marriage/ocr/parseIdCard`
|
||
- **方法**: POST
|
||
- **参数**: mobile, smsCode, uploadId
|
||
- **返回**: 身份证识别结果
|
||
|
||
---
|
||
|
||
实现完成！✨
|
||
|