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 集成规划和总结
2026-03-12 20:33:21 +08:00
parent 0706b51acd
commit 78a6cde22d
50 changed files with 3886 additions and 0 deletions
--- a/yudao-module-asset/VEHICLE_REGISTRATION_SUMMARY.md
+++ b/yudao-module-asset/VEHICLE_REGISTRATION_SUMMARY.md
@@ -0,0 +1,211 @@
+# 车辆上牌管理功能实施总结
+
+## 实施完成情况
+
+### ✅ Phase 2 已完成
+
+#### 2.1 数据库设计
+- ✅ 创建 `asset_vehicle_registration` 表
+- ✅ 添加菜单和权限 SQL
+- ✅ 文件位置：`yudao-module-asset/sql/mysql/vehicle_registration.sql`
+
+#### 2.2 后端实现
+
+**DO 层**
+- ✅ `VehicleRegistrationDO.java` - 车辆上牌记录实体
+
+**Mapper 层**
+- ✅ `VehicleRegistrationMapper.java` - 数据访问层
+
+**VO 层**
+- ✅ `VehicleRegistrationBaseVO.java` - 基础 VO
+- ✅ `VehicleRegistrationSaveReqVO.java` - 创建/更新请求 VO
+- ✅ `VehicleRegistrationPageReqVO.java` - 分页查询请求 VO
+- ✅ `VehicleRegistrationRespVO.java` - 响应 VO
+- ✅ `VehicleLicenseRecognizeRespVO.java` - 识别响应 VO
+
+**Convert 层**
+- ✅ `VehicleRegistrationConvert.java` - 对象转换器
+
+**Service 层**
+- ✅ `VehicleRegistrationService.java` - 服务接口
+- ✅ `VehicleRegistrationServiceImpl.java` - 服务实现
+  - 识别行驶证（待集成 OCR）
+  - 创建上牌记录
+  - 更新上牌记录
+  - 删除上牌记录
+  - 查询上牌记录
+  - 确认上牌（更新车辆信息）
+
+**Controller 层**
+- ✅ `VehicleRegistrationController.java` - REST API
+  - `POST /asset/vehicle-registration/recognize-license` - 识别行驶证
+  - `POST /asset/vehicle-registration/create` - 创建记录
+  - `PUT /asset/vehicle-registration/update` - 更新记录
+  - `DELETE /asset/vehicle-registration/delete` - 删除记录
+  - `GET /asset/vehicle-registration/get` - 获取单条
+  - `GET /asset/vehicle-registration/page` - 分页查询
+  - `POST /asset/vehicle-registration/confirm` - 确认上牌
+
+#### 2.3 依赖配置
+- ✅ 在 `asset-server/pom.xml` 中添加 OCR 模块依赖
+
+#### 2.4 编译验证
+- ✅ Maven 编译成功
+
+## 项目结构
+
+```
+yudao-module-asset/
+├── sql/mysql/
+│   └── vehicle_registration.sql                    # 数据库脚本
+└── yudao-module-asset-server/
+    └── src/main/java/cn/iocoder/yudao/module/asset/
+        ├── controller/admin/vehicleregistration/
+        │   ├── VehicleRegistrationController.java  # REST API
+        │   └── vo/
+        │       ├── VehicleRegistrationBaseVO.java
+        │       ├── VehicleRegistrationSaveReqVO.java
+        │       ├── VehicleRegistrationPageReqVO.java
+        │       ├── VehicleRegistrationRespVO.java
+        │       └── VehicleLicenseRecognizeRespVO.java
+        ├── service/vehicleregistration/
+        │   ├── VehicleRegistrationService.java     # 服务接口
+        │   └── VehicleRegistrationServiceImpl.java # 服务实现
+        ├── convert/vehicleregistration/
+        │   └── VehicleRegistrationConvert.java     # 对象转换
+        ├── dal/
+        │   ├── dataobject/vehicleregistration/
+        │   │   └── VehicleRegistrationDO.java      # 实体类
+        │   └── mysql/vehicleregistration/
+        │       └── VehicleRegistrationMapper.java  # Mapper
+        └── pom.xml                                 # 添加 OCR 依赖
+```
+
+## 核心功能
+
+### 1. 行驶证识别
+- 接口：`POST /asset/vehicle-registration/recognize-license`
+- 功能：上传行驶证照片，OCR 识别车辆信息
+- 状态：**待集成 OCR 服务**（需要通过 Feign 或 HTTP 调用 OCR 模块）
+
+### 2. 上牌记录管理
+- 创建上牌记录
+- 更新上牌记录
+- 删除上牌记录
+- 分页查询上牌记录
+
+### 3. 确认上牌
+- 接口：`POST /asset/vehicle-registration/confirm`
+- 功能：确认上牌记录后，自动更新车辆基础信息表
+- 更新字段：
+  - 车牌号 (plateNo)
+  - VIN (vin)
+  - 发动机号 (engineNo)
+  - 注册日期 (registerDate)
+  - 强制报废期 (scrapDate)
+  - 检验有效期 (inspectExpire)
+  - 车型ID (vehicleModelId)
+
+## 技术亮点
+
+1. **分离设计**：车辆信息拆分为多个表（base/location/business/status），上牌管理只更新基础信息表
+2. **状态管理**：上牌记录有三种状态（待确认/已确认/已作废）
+3. **事务保证**：确认上牌时，同时更新上牌记录和车辆信息，保证数据一致性
+4. **权限控制**：所有接口都有权限验证
+
+## 待完成工作
+
+### 🔲 Phase 2.5: OCR 服务集成
+
+**方案 A：Feign 调用（推荐）**
+1. 创建 Feign 客户端
+```java
+@FeignClient(name = "ocr-server", contextId = "ocrApi")
+public interface OcrApi {
+    @PostMapping("/admin-api/ocr/vehicle-license")
+    CommonResult<VehicleLicenseRespVO> recognizeVehicleLicense(
+        @RequestParam("file") MultipartFile file);
+}
+```
+
+2. 在 VehicleRegistrationServiceImpl 中注入并调用
+```java
+@Resource
+private OcrApi ocrApi;
+
+public VehicleLicenseRecognizeRespVO recognizeVehicleLicense(byte[] imageData) {
+    // 调用 OCR 服务
+    CommonResult<VehicleLicenseRespVO> result = ocrApi.recognizeVehicleLicense(...);
+    // 处理结果
+}
+```
+
+**方案 B：HTTP 调用**
+使用 RestTemplate 或 WebClient 调用 OCR 服务
+
+### 🔲 Phase 2.6: 测试
+1. 单元测试
+2. 集成测试
+3. 端到端测试
+
+### 🔲 Phase 2.7: 部署
+1. 执行数据库脚本
+2. 配置权限
+3. 启动服务
+4. 验证功能
+
+## API 接口列表
+
+| 接口 | 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|------|
+| 识别行驶证 | POST | /asset/vehicle-registration/recognize-license | asset:vehicle-registration:recognize | 上传照片识别 |
+| 创建记录 | POST | /asset/vehicle-registration/create | asset:vehicle-registration:create | 创建上牌记录 |
+| 更新记录 | PUT | /asset/vehicle-registration/update | asset:vehicle-registration:update | 更新上牌记录 |
+| 删除记录 | DELETE | /asset/vehicle-registration/delete | asset:vehicle-registration:delete | 删除上牌记录 |
+| 获取单条 | GET | /asset/vehicle-registration/get | asset:vehicle-registration:query | 根据ID查询 |
+| 分页查询 | GET | /asset/vehicle-registration/page | asset:vehicle-registration:query | 分页查询 |
+| 确认上牌 | POST | /asset/vehicle-registration/confirm | asset:vehicle-registration:update | 确认并更新车辆 |
+
+## 数据库表结构
+
+### asset_vehicle_registration
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | BIGINT | 主键ID |
+| vehicle_id | BIGINT | 车辆ID |
+| vin | VARCHAR(50) | 车辆识别代号 |
+| plate_no | VARCHAR(20) | 车牌号 |
+| plate_date | DATE | 上牌日期 |
+| operator | VARCHAR(50) | 操作员 |
+| recognized_brand | VARCHAR(100) | OCR识别的品牌型号 |
+| vehicle_model_id | BIGINT | 匹配的车型ID |
+| photo_url | VARCHAR(500) | 行驶证照片URL |
+| ocr_provider | VARCHAR(50) | OCR厂商 |
+| status | TINYINT | 状态（0-待确认 1-已确认 2-已作废） |
+| ... | ... | 其他字段 |
+
+## 下一步建议
+
+1. **优先级 1：集成 OCR 服务**
+   - 实现 Feign 客户端
+   - 完成识别功能
+   - 测试端到端流程
+
+2. **优先级 2：完善业务逻辑**
+   - 添加车型匹配算法
+   - 实现照片上传到文件服务
+   - 添加识别结果缓存
+
+3. **优先级 3：前端对接**
+   - 提供 API 文档
+   - 协助前端集成
+   - 联调测试
+
+---
+
+**实施日期**：2026-03-12
+**实施人员**：AI Assistant
+**版本**：v1.0.0
+**状态**：Phase 2 完成，待集成 OCR 服务