图像API文档
概述
本文档详细记录了邮轮穿舱件管理系统后台的图像上传、下载、处理等相关接口。系统采用FastAPI框架构建，通过CVCore图像识别服务进行图像处理，支持图像与工件的绑定管理。
系统架构
flowchart TD
subgraph 前端层
A[Web客户端]
B[微信小程序]
end
subgraph API路由层
C[image_router.py]
D[wechat/image.py]
end
subgraph 服务层
E[image_service.py]
end
subgraph 数据访问层
F[Image模型]
G[ImageMapping模型]
end
subgraph 外部服务
H[CVCore图像服务]
I[OSS存储服务]
end
A --> C
B --> D
C --> E
D --> E
E --> F
E --> G
E --> H
H --> I
核心组件分析
1. 数据模型
Image模型
- 文件位置: app/models/image.py
- 功能: 存储图片基本信息
- 字段说明:
id: 图片ID（主键）key: 图片在OSS中的唯一标识created_by/updated_by: 创建/更新用户IDcreated_at/updated_at: 创建/更新时间
ImageMapping模型
- 文件位置: app/models/image_mapping.py
- 功能: 管理图片与工件的绑定关系
- 字段说明:
workpiece_id: 工件IDimage_id: 图片ID- 审计字段（创建/更新信息）
2. 服务层架构
classDiagram
class ImageService {
+service_upload_new_image(image: UploadFile) dict
+service_delete_image_entity_by_id(image_id: int)
+service_get_image_entity_by_key_or_image_id() Image
+service_get_unbind_images() List[int]
+service_get_images_by_workpiece_id(workpiece_id: int) List[Image]
+service_get_tuple_lists() List[ImageMapping]
+service_get_image_entity() List[Image]
+service_bind_image_to_workpiece(image_id: int, workpiece_id: int) dict
+service_unbind_image_to_workpiece(image_id: int, workpiece_id: int) dict
+service_search_image_sdk_with_key(key: str) dict
+service_search_image_sdk_with_id(image_id: int) dict
}
class CVCoreService {
+upload_image_to_cvcore(image: bytes) Dict
+get_image_from_cvcore(key: str) bytes
+sdk_add_image(image: ImageInSchema) Dict
+sdk_delete_image(product_id: str, pic_name: str) Dict
+sdk_search_image(key: str) Dict
}
ImageService --> CVCoreService : 依赖
API接口详解
主图像管理接口（image_router.py）
1. 图片上传接口
- 端点:
POST /image/create - 功能: 上传新图片到系统
- 参数:
image: UploadFile - 返回: 包含图片ID的字典
- 流程:
- 接收上传的图片文件
- 调用CVCore服务上传到OSS
- 在数据库中创建图片记录
- 返回图片ID
# 核心代码片段
async def api_create_new_image(image: UploadFile = File(...)):
raw_bytes = await image.read()
resp = await upload_image_to_cvcore(raw_bytes)
file_key = resp["file_key"]
image_orm = await Image.create(key=file_key)
return {"image_id": image_orm.id}
参考文件: app/routers/image_router.py
2. 图片删除接口
- 端点:
DELETE /image/delete - 功能: 删除系统中的图片实体
- 参数:
image_id: int - 返回: 操作结果消息
参考文件: app/routers/image_router.py
3. 图片绑定管理接口
绑定图片到工件
- 端点:
POST /image/enable/bind - 功能: 将图片绑定到指定工件
- 参数:
ImageWorkpieceTuple(包含image_id和workpiece_id) - 流程:
- 验证图片和工件存在性
- 调用CVCore SDK添加图片到识别系统
- 创建绑定关系记录
sequenceDiagram
participant Client
participant ImageRouter
participant ImageService
participant CVCore
participant Database
Client->>ImageRouter: POST /image/enable/bind
ImageRouter->>ImageService: service_bind_image_to_workpiece()
ImageService->>Database: 验证图片存在性
ImageService->>Database: 验证绑定关系
ImageService->>CVCore: sdk_add_image()
CVCore-->>ImageService: 添加结果
ImageService->>Database: 创建ImageMapping
ImageService-->>ImageRouter: 绑定结果
ImageRouter-->>Client: 成功响应
参考文件: app/routers/image_router.py
解绑图片从工件
- 端点:
POST /image/disable/bind - 功能: 将图片从工件解绑
- 参数:
ImageWorkpieceTuple - 流程:
- 验证绑定关系存在性
- 调用CVCore SDK从识别系统删除图片
- 删除绑定关系记录
参考文件: app/routers/image_router.py
4. 图片查询接口
获取未绑定图片
- 端点:
GET /image/status/list/unbinds - 功能: 获取系统中未绑定到任何工件的图片
- 返回: 未绑定图片ID列表
参考文件: app/routers/image_router.py
获取所有绑定关系
- 端点:
GET /image/status/list/binds - 功能: 获取所有图片与工件的绑定关系
- 返回: ImageMapping对象列表
参考文件: app/routers/image_router.py
获取所有图片实体
- 端点:
GET /image/status/list/imageEntity - 功能: 获取系统中所有图片实体
- 返回: Image对象列表
参考文件: app/routers/image_router.py
5. 图片搜索接口
根据Key搜索图片
- 端点:
GET /image/searchByKey - 功能: 根据图片Key搜索图片
- 参数:
key: str - 返回: 搜索结果
参考文件: app/routers/image_router.py
根据ID搜索图片
- 端点:
GET /image/searchById - 功能: 根据图片ID搜索图片
- 参数:
image_id: int - 返回: 搜索结果
参考文件: app/routers/image_router.py
微信小程序图像接口（wechat/image.py）
根据工件ID获取图片
- 端点:
GET /image/workpiece/{workpiece_id}/images - 功能: 微信小程序根据工件ID获取绑定的图片
- 参数:
workpiece_id: int(路径参数) - 返回: 图片实体列表
@miniapp_image_router.get("/workpiece/{workpiece_id}/images")
async def api_get_image_by_workpiece_id(workpiece_id: int):
image_entity_list = await service_get_images_by_workpiece_id(workpiece_id)
return image_entity_list
参考文件: app/routers/wechat/image.py
核心服务实现
图像服务（image_service.py）
flowchart TD
subgraph 图像上传流程
A[接收上传文件] --> B[读取字节数据]
B --> C[调用CVCore上传]
C --> D[获取文件Key]
D --> E[创建Image记录]
E --> F[返回图片ID]
end
subgraph 绑定流程
G[验证图片存在性] --> H[检查重复绑定]
H --> I[生成产品信息]
I --> J[调用SDK添加图片]
J --> K[创建绑定关系]
K --> L[返回绑定结果]
end
subgraph 解绑流程
M[验证绑定关系] --> N[生成删除参数]
N --> O[调用SDK删除图片]
O --> P[删除绑定关系]
P --> Q[返回解绑结果]
end
主要服务方法:
service_upload_new_image(): 处理图片上传逻辑service_bind_image_to_workpiece(): 处理图片绑定逻辑service_unbind_image_to_workpiece(): 处理图片解绑逻辑service_search_image_sdk_with_key(): 基于Key的图片搜索
参考文件: app/service/image_service.py
CVCore集成服务（cvcore.py）
classDiagram
class ImageInSchema {
+pic_name: str
+product_id: str
+oss_name: str
}
class CVCoreClient {
+upload_image_to_cvcore(image: bytes) Dict
+get_image_from_cvcore(key: str) bytes
+sdk_add_image(image: ImageInSchema) Dict
+sdk_delete_image(product_id: str, pic_name: str) Dict
+sdk_search_image(key: str) Dict
}
ImageInSchema <-- CVCoreClient : 使用
核心功能:
- 图片上传到OSS存储
- 图片从OSS下载
- 与图像识别系统的集成
- 图片搜索功能
参考文件: app/lib/cvcore.py
数据流分析
图片上传数据流
sequenceDiagram
participant User
participant Frontend
participant Backend
participant CVCore
participant OSS
participant Database
User->>Frontend: 选择图片文件
Frontend->>Backend: POST /image/create
Backend->>CVCore: upload_image_to_cvcore()
CVCore->>OSS: 上传图片文件
OSS-->>CVCore: 返回文件Key
CVCore-->>Backend: 上传结果
Backend->>Database: 创建Image记录
Database-->>Backend: 记录ID
Backend-->>Frontend: 图片ID
Frontend-->>User: 上传成功
图片绑定数据流
sequenceDiagram
participant User
participant Frontend
participant Backend
participant CVCore
participant Database
User->>Frontend: 选择绑定关系
Frontend->>Backend: POST /image/enable/bind
Backend->>Database: 验证图片和工件
Database-->>Backend: 验证结果
Backend->>CVCore: sdk_add_image()
CVCore-->>Backend: 添加结果
Backend->>Database: 创建ImageMapping
Database-->>Backend: 绑定ID
Backend-->>Frontend: 绑定成功
Frontend-->>User: 操作完成
错误处理机制
常见错误类型
- 图片不存在错误 (HTTP 404)
- 重复绑定错误 (HTTP 400)
- CVCore服务错误 (HTTP 500)
- 文件上传错误 (HTTP 500)
错误处理策略
- 使用FastAPI的HTTPException进行统一错误处理
- 详细的日志记录便于问题排查
- 访问日志记录所有操作
安全考虑
- JWT认证: 所有接口都需要有效的JWT令牌
- 访问控制: 记录用户操作日志
- 输入验证: 验证图片ID和工件ID的有效性
- 重复操作防护: 防止重复绑定操作
性能优化建议
- 图片处理: 考虑添加图片压缩和格式转换
- 缓存策略: 对频繁访问的图片添加缓存
- 批量操作: 支持批量上传和绑定操作
- 异步处理: 使用异步IO提高并发性能
索引
本图像管理系统提供了完整的图片生命周期管理功能，包括上传、存储、绑定、搜索等核心功能。系统采用分层架构设计，通过CVCore服务集成图像识别能力，支持Web端和微信小程序两种客户端访问。接口设计合理，错误处理完善，具有良好的可扩展性和维护性。
核心参考文件:
- app/routers/image_router.py - 主图像管理API
- app/routers/wechat/image.py - 微信小程序图像API
- app/service/image_service.py - 图像业务逻辑
- app/models/image.py - 图片数据模型
- app/models/image_mapping.py - 绑定关系模型
- app/lib/cvcore.py - CVCore集成服务