fucai-server/IDCARD_QUICK_TEST.md

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

## 📌 实现总结

✅ **已完成** - 身份证识别接口 `/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  
**状态**: ✅ 生产就绪