414 lines
9.4 KiB
Markdown
414 lines
9.4 KiB
Markdown
# OCR 功能实现总结
|
||
|
||
## 实现完成情况
|
||
|
||
✅ **已完成全部功能需求**
|
||
|
||
---
|
||
|
||
## 新增文件清单
|
||
|
||
### 1. DTO 类 (数据模型)
|
||
|
||
#### 📄 OcrProbability.java
|
||
```
|
||
路径: com-marriage-client/src/main/java/com/jinrui/marriage/client/dto/OcrProbability.java
|
||
说明: 表示OCR识别结果的概率信息
|
||
属性:
|
||
- average: Double (平均概率)
|
||
- min: Double (最小概率)
|
||
```
|
||
|
||
#### 📄 OcrLocation.java
|
||
```
|
||
路径: com-marriage-client/src/main/java/com/jinrui/marriage/client/dto/OcrLocation.java
|
||
说明: 表示OCR识别结果的位置信息
|
||
属性:
|
||
- width: Integer (宽度)
|
||
- height: Integer (高度)
|
||
- top: Integer (顶部距离)
|
||
- left: Integer (左侧距离)
|
||
```
|
||
|
||
#### 📄 OcrFieldData.java
|
||
```
|
||
路径: com-marriage-client/src/main/java/com/jinrui/marriage/client/dto/OcrFieldData.java
|
||
说明: 表示单个识别字段的完整数据
|
||
属性:
|
||
- word: String (识别的文本内容)
|
||
- probability: OcrProbability (识别概率)
|
||
- location: OcrLocation (位置信息)
|
||
```
|
||
|
||
### 2. Controller 修改
|
||
|
||
#### 📝 OcrController.java
|
||
```
|
||
修改内容:
|
||
1. 新增imports: OcrFieldData, OcrProbability, OcrLocation
|
||
2. 修改 /parse 端点返回值:
|
||
- 新增 parsed_detailed 字段（返回完整的字段数据）
|
||
- 保持 parsed 字段（向后兼容，仅包含文本）
|
||
3. 新增 parseMarriageFieldsFromRawDetailed() 方法
|
||
- 从百度API原始响应中提取详细字段数据
|
||
- 支持所有结婚证字段
|
||
4. 新增 extractFieldData() 方法
|
||
- 从JSON中提取完整字段数据（word + probability + location）
|
||
5. 新增 convertToSimpleParsed() 方法
|
||
- 将详细数据转换为简化格式（向后兼容）
|
||
```
|
||
|
||
### 3. 示例和文档
|
||
|
||
#### 📄 OcrResponseExample.java
|
||
```
|
||
路径: com-marriage-client/src/main/java/com/jinrui/marriage/client/example/OcrResponseExample.java
|
||
说明: 演示新API的使用方式，包含6个实用示例
|
||
示例:
|
||
1. 检查识别结果的可信度
|
||
2. 获取识别结果在图片中的位置
|
||
3. 按置信度筛选结果
|
||
4. 获取完整的字段详细信息
|
||
5. 使用简化版本（向后兼容）
|
||
6. 导出为JSON格式
|
||
```
|
||
|
||
#### 📄 OcrFieldDataTest.java
|
||
```
|
||
路径: com-marriage-client/src/test/java/com/jinrui/marriage/client/test/OcrFieldDataTest.java
|
||
说明: 单元测试文件
|
||
测试用例:
|
||
- DTO创建和初始化
|
||
- JSON序列化/反序列化
|
||
- 阈值判断
|
||
- 边界值测试
|
||
- null值处理
|
||
```
|
||
|
||
#### 📄 OCR_UPDATE.md
|
||
```
|
||
路径: 项目根目录
|
||
说明: OCR功能更新文档
|
||
内容:
|
||
- 功能描述
|
||
- DTO类说明
|
||
- API返回格式详解
|
||
- 向后兼容性说明
|
||
- 识别字段列表
|
||
- 使用示例
|
||
- 技术实现细节
|
||
- 注意事项
|
||
```
|
||
|
||
#### 📄 OCR_API_DOCUMENT.md
|
||
```
|
||
路径: 项目根目录
|
||
说明: 详细的API接口文档（与Swagger兼容）
|
||
内容:
|
||
- 接口概述
|
||
- 上传接口说明
|
||
- 解析接口说明
|
||
- 响应数据详细说明
|
||
- 错误处理指南
|
||
- 使用场景示例
|
||
- 集成建议
|
||
```
|
||
|
||
---
|
||
|
||
## 核心功能说明
|
||
|
||
### 功能1: 返回识别概率信息
|
||
|
||
**百度API原始格式:**
|
||
```json
|
||
{
|
||
"word": "王连杰",
|
||
"probability": {
|
||
"average": 20.68798065,
|
||
"min": 0.9106679559
|
||
}
|
||
}
|
||
```
|
||
|
||
**在API响应中:**
|
||
```json
|
||
{
|
||
"parsed_detailed": {
|
||
"husbandName": {
|
||
"word": "王连杰",
|
||
"probability": {
|
||
"average": 20.68798065,
|
||
"min": 0.9106679559
|
||
},
|
||
...
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**使用方式:**
|
||
```javascript
|
||
const confidence = response.data.parsed_detailed.husbandName.probability.average;
|
||
if (confidence < 60) {
|
||
// 提示用户进行人工审核
|
||
}
|
||
```
|
||
|
||
### 功能2: 返回位置信息
|
||
|
||
**百度API原始格式:**
|
||
```json
|
||
{
|
||
"location": {
|
||
"width": 109,
|
||
"height": 47,
|
||
"top": 933,
|
||
"left": 253
|
||
}
|
||
}
|
||
```
|
||
|
||
**在API响应中:**
|
||
```json
|
||
{
|
||
"parsed_detailed": {
|
||
"husbandName": {
|
||
"word": "王连杰",
|
||
"location": {
|
||
"width": 109,
|
||
"height": 47,
|
||
"top": 933,
|
||
"left": 253
|
||
},
|
||
...
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**使用方式 (前端标注):**
|
||
```javascript
|
||
const loc = response.data.parsed_detailed.husbandName.location;
|
||
// 在图片上绘制识别框
|
||
drawRectangle(loc.left, loc.top, loc.width, loc.height);
|
||
```
|
||
|
||
### 功能3: 向后兼容性
|
||
|
||
**旧格式仍然保持:**
|
||
```json
|
||
{
|
||
"parsed": {
|
||
"husbandName": "王连杰",
|
||
"wifeName": "张丹",
|
||
"marriageNo": "320321201700004108",
|
||
"registerDate": "2017-04-01"
|
||
}
|
||
}
|
||
```
|
||
|
||
**现有客户端代码无需修改，仍可继续使用:**
|
||
```javascript
|
||
const husbandName = response.data.parsed.husbandName;
|
||
```
|
||
|
||
---
|
||
|
||
## 支持的识别字段
|
||
|
||
| 字段键 | 说明 | 备注 |
|
||
|-------|------|------|
|
||
| husbandName | 男方姓名 | ✅ |
|
||
| husbandId | 男方身份证号 | ✅ |
|
||
| husbandBirthDate | 男方出生日期 | 自动转换格式 |
|
||
| husbandNationality | 男方国籍 | ✅ |
|
||
| husbandGender | 男方性别 | ✅ |
|
||
| wifeName | 女方姓名 | ✅ |
|
||
| wifeId | 女方身份证号 | ✅ |
|
||
| wifeBirthDate | 女方出生日期 | 自动转换格式 |
|
||
| wifeNationality | 女方国籍 | ✅ |
|
||
| wifeGender | 女方性别 | ✅ |
|
||
| marriageNo | 结婚证字号 | 仅保留数字 |
|
||
| certificateHolder | 持证人 | ✅ |
|
||
| registerDate | 登记日期 | 自动转换格式 |
|
||
| remark | 备注 | 可选 |
|
||
|
||
---
|
||
|
||
## API 响应结构
|
||
|
||
```
|
||
┌─ data (响应数据体)
|
||
├─ raw String 百度OCR原始响应
|
||
├─ words Array 识别的所有文本
|
||
├─ parsed Object 简化格式（向后兼容）
|
||
│ ├─ husbandName String
|
||
│ ├─ wifeName String
|
||
│ ├─ marriageNo String
|
||
│ └─ registerDate String
|
||
└─ parsed_detailed Object 详细格式（新增）
|
||
├─ husbandName OcrFieldData
|
||
│ ├─ word String
|
||
│ ├─ probability OcrProbability
|
||
│ │ ├─ average Double
|
||
│ │ └─ min Double
|
||
│ └─ location OcrLocation
|
||
│ ├─ width Integer
|
||
│ ├─ height Integer
|
||
│ ├─ top Integer
|
||
│ └─ left Integer
|
||
└─ wifeName OcrFieldData
|
||
└─ ... (结构相同)
|
||
```
|
||
|
||
---
|
||
|
||
## 技术亮点
|
||
|
||
1. **完全向后兼容**
|
||
- 旧版客户端无需修改代码
|
||
- 同时提供新旧两种格式
|
||
|
||
2. **灵活的数据结构**
|
||
- probability 和 location 为可选字段
|
||
- 支持 null 值处理
|
||
|
||
3. **规范的命名**
|
||
- 类名使用 Ocr 前缀
|
||
- 字段名与百度API保持一致
|
||
|
||
4. **完整的文档**
|
||
- API文档
|
||
- 实现文档
|
||
- 代码示例
|
||
- 单元测试
|
||
|
||
---
|
||
|
||
## 部署和编译
|
||
|
||
### 编译项目
|
||
```bash
|
||
cd /Users/bugjiewang/StudioProjects/fucai-server
|
||
mvn clean compile -DskipTests -pl com-marriage-client
|
||
```
|
||
|
||
### 单元测试
|
||
```bash
|
||
mvn test -pl com-marriage-client -Dtest=OcrFieldDataTest
|
||
```
|
||
|
||
### 打包应用
|
||
```bash
|
||
mvn clean package -DskipTests
|
||
```
|
||
|
||
---
|
||
|
||
## 使用建议
|
||
|
||
### 客户端集成步骤
|
||
|
||
1. **调用上传接口**
|
||
```javascript
|
||
const formData = new FormData();
|
||
formData.append('file', imageFile);
|
||
const uploadResp = await fetch('/marriage/ocr/upload', {
|
||
method: 'POST',
|
||
body: formData
|
||
});
|
||
const uploadId = uploadResp.data.uploadId;
|
||
```
|
||
|
||
2. **调用解析接口**
|
||
```javascript
|
||
const parseResp = await fetch('/marriage/ocr/parse', {
|
||
method: 'POST',
|
||
headers: { 'Content-Type': 'application/json' },
|
||
body: JSON.stringify({
|
||
mobile: userMobile,
|
||
smsCode: verificationCode,
|
||
uploadId: uploadId
|
||
})
|
||
});
|
||
```
|
||
|
||
3. **处理响应**
|
||
```javascript
|
||
const data = parseResp.data;
|
||
|
||
// 方式1: 使用简化格式（向后兼容）
|
||
const simplifiedData = data.parsed;
|
||
|
||
// 方式2: 使用详细格式（包含概率和位置）
|
||
const detailedData = data.parsed_detailed;
|
||
|
||
// 方式3: 检查识别质量
|
||
for (const [key, fieldData] of Object.entries(detailedData)) {
|
||
if (fieldData.probability.average < 60) {
|
||
console.warn(`${key} 识别度较低: ${fieldData.probability.average}%`);
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. ⚠️ **概率值意义**
|
||
- 0-100 之间的浮点数
|
||
- 越高表示识别准确度越高
|
||
- 建议 >= 60% 为可接受
|
||
|
||
2. ⚠️ **位置信息**
|
||
- 坐标以图片左上角为原点
|
||
- 单位为像素
|
||
- 用于前端标注或图片裁剪
|
||
|
||
3. ⚠️ **字段转换**
|
||
- 日期自动转换为 YYYY-MM-DD 格式
|
||
- 证号仅保留数字部分
|
||
- 其他字段保持原样
|
||
|
||
4. ⚠️ **安全性**
|
||
- 敏感信息（如身份证号）建议端到端加密
|
||
- 服务端应对数据进行脱敏处理
|
||
- 仅在必要时返回完整信息
|
||
|
||
---
|
||
|
||
## 文档索引
|
||
|
||
| 文档 | 用途 | 读者 |
|
||
|------|------|------|
|
||
| OCR_UPDATE.md | 功能更新说明 | 开发者、产品经理 |
|
||
| OCR_API_DOCUMENT.md | 接口调用文档 | 前端开发者 |
|
||
| OcrResponseExample.java | 代码示例 | 开发者 |
|
||
| OcrFieldDataTest.java | 单元测试 | QA、开发者 |
|
||
|
||
---
|
||
|
||
## 总结
|
||
|
||
✅ **本次更新成功将百度API的 probability 和 location 字段集成到OCR识别结果中**
|
||
|
||
- 新增3个DTO类，规范封装数据
|
||
- 修改OcrController，提供两种格式的返回值
|
||
- 新增3个方法，支持详细数据提取和格式转换
|
||
- 提供完整的文档、示例和单元测试
|
||
- 完全向后兼容，无需修改现有客户端代码
|
||
|
||
**实现特点:**
|
||
1. 高度可用 - 支持probability和location的完整信息
|
||
2. 高度兼容 - 保持原有的parsed简化格式
|
||
3. 高度规范 - 遵循阿里巴巴JAVA开发规范
|
||
4. 高度可靠 - 包含完整的文档、示例和测试
|
||
|
||
**建议:**
|
||
- 立即在QA环境测试
|
||
- 收集反馈并优化阈值
|
||
- 逐步推进到生产环境
|
||
- 监控识别准确率变化
|
||
|