feat: 实现 OCR 模块和车辆上牌管理功能

- 新增 yudao-module-ocr 模块
  - OCR API 模块:定义 Feign 接口和 DTO
  - OCR Server 模块:实现行驶证识别功能
  - 集成百度 OCR SDK
  - 支持多厂商扩展(百度/腾讯/阿里云)

- 新增车辆上牌管理功能
  - 数据库表:asset_vehicle_registration
  - 完整的 CRUD 接口
  - 行驶证识别接口(集成 OCR)
  - 车辆匹配功能(根据 VIN)
  - 确认上牌功能(更新车辆信息)

- 技术实现
  - 遵循 BPM/System 模块的 RPC API 模式
  - 使用 Feign 实现服务间调用
  - Base64 编码传输图片数据
  - 统一返回格式 CommonResult<T>

- 文档
  - OCR 模块使用文档
  - OCR 部署指南
  - 车辆上牌管理总结
  - API 集成规划和总结
This commit is contained in:
kkfluous
2026-03-12 20:33:21 +08:00
parent 0706b51acd
commit 78a6cde22d
50 changed files with 3886 additions and 0 deletions

View File

@@ -0,0 +1,188 @@
# OCR 模块部署指南
## 部署步骤
### 1. 添加到主 POM
已完成 ✅ - `yudao-module-ocr` 已添加到 `oneos-backend/pom.xml` 的 modules 中。
### 2. 配置 Nacos
在 Nacos 配置中心创建配置文件:`ocr-server-dev.yaml`
```yaml
server:
port: 48090
# OCR 配置
ocr:
default-provider: baidu
baidu:
app-id: ${OCR_BAIDU_APP_ID}
api-key: ${OCR_BAIDU_API_KEY}
secret-key: ${OCR_BAIDU_SECRET_KEY}
```
### 3. 配置环境变量
在部署环境中设置以下环境变量:
```bash
export OCR_BAIDU_APP_ID=your-app-id
export OCR_BAIDU_API_KEY=your-api-key
export OCR_BAIDU_SECRET_KEY=your-secret-key
```
或在 Nacos 的 `common-dev.yaml` 中配置。
### 4. 启动服务
```bash
cd oneos-backend/yudao-module-ocr/yudao-module-ocr-server
java -jar target/yudao-module-ocr-server.jar
```
或使用 Maven
```bash
cd oneos-backend
mvn spring-boot:run -pl yudao-module-ocr/yudao-module-ocr-server
```
### 5. 验证服务
访问 Swagger 文档:
```
http://localhost:48090/doc.html
```
查看 OCR 识别接口是否正常。
## 权限配置
在系统管理中添加权限:
- 权限标识:`ocr:vehicle-license:recognize`
- 权限名称:行驶证识别
- 所属菜单OCR 识别管理
## 集成到其他模块
### 1. 添加依赖
在需要使用 OCR 的模块(如 `yudao-module-asset-server`)的 `pom.xml` 中添加:
```xml
<!-- OCR 模块 API -->
<dependency>
<groupId>cn.iocoder.cloud</groupId>
<artifactId>yudao-module-ocr-api</artifactId>
<version>${revision}</version>
</dependency>
```
### 2. 使用 Feign 调用
创建 Feign 客户端(如果需要跨服务调用):
```java
@FeignClient(name = "ocr-server", contextId = "ocrApi")
public interface OcrApi {
@PostMapping("/admin-api/ocr/vehicle-license")
CommonResult<VehicleLicenseRespVO> recognizeVehicleLicense(
@RequestParam("file") MultipartFile file,
@RequestParam(value = "provider", required = false) String provider
);
}
```
### 3. 直接注入使用(同一服务内)
```java
@Service
public class VehicleService {
@Resource
private OcrService ocrService;
public void processVehicleLicense(byte[] imageData) {
VehicleLicenseResult result = ocrService.recognizeVehicleLicense(imageData);
// 处理识别结果
}
}
```
## 监控和日志
### 日志配置
`logback-spring.xml` 中添加:
```xml
<logger name="cn.iocoder.yudao.module.ocr" level="INFO"/>
<logger name="com.baidu.aip" level="WARN"/>
```
### 监控指标
建议监控以下指标:
- OCR 识别成功率
- OCR 识别耗时
- OCR API 调用次数
- 错误率和错误类型
## 故障排查
### 1. 识别失败
检查:
- 百度 OCR 凭证是否正确
- 图片格式是否支持JPG、PNG、BMP
- 图片大小是否超过 4MB
- 网络连接是否正常
### 2. 服务启动失败
检查:
- Nacos 配置是否正确
- 依赖是否完整
- 端口是否被占用
### 3. 性能问题
优化建议:
- 添加识别结果缓存
- 实现请求限流
- 考虑使用异步识别
## 成本优化
### 1. 百度 OCR 计费
- 行驶证识别0.015 元/次
- 每月前 1000 次免费
### 2. 优化建议
- 实现结果缓存,避免重复识别
- 前端压缩图片,减少传输时间
- 批量识别时使用队列异步处理
## 安全建议
1. **API 密钥管理**:使用配置中心加密存储
2. **接口鉴权**:确保只有授权用户可以调用
3. **图片校验**:验证上传图片的合法性
4. **日志脱敏**:不要在日志中记录敏感信息
5. **限流保护**:防止恶意调用消耗配额
## 后续扩展
1. 添加驾驶证识别
2. 添加身份证识别
3. 集成腾讯、阿里云 OCR
4. 实现识别结果的人工校验功能
5. 添加识别历史记录查询