图像服务文档

概述

邮轮穿舱件管理系统后台的图像服务模块负责处理图像上传、存储、搜索和与工件的绑定关系管理。该模块通过集成CVCore图像识别系统，实现了完整的图像处理流水线。

系统架构

核心组件关系图

flowchart TD
    subgraph 前端层
        A[前端界面]
    end
    
    subgraph API路由层
        B[Image Router]
    end
    
    subgraph 业务逻辑层
        C[Image Service]
        D[Image Mapping Service]
    end
    
    subgraph 数据访问层
        E[Image Model]
        F[ImageMapping Model]
    end
    
    subgraph 外部服务
        G[CVCore SDK]
        H[OSS存储]
    end
    
    A --> B
    B --> C
    B --> D
    C --> E
    C --> G
    D --> F
    G --> H

类继承关系图

classDiagram
    class Image {
        +IntField id
        +CharField key
        +IntField created_by
        +IntField updated_by
        +DatetimeField created_at
        +DatetimeField updated_at
    }
    
    class ImageMapping {
        +IntField workpiece_id
        +IntField image_id
        +IntField created_by
        +IntField updated_by
        +DatetimeField created_at
        +DatetimeField updated_at
    }
    
    class ImageInSchema {
        +str pic_name
        +str product_id
        +str oss_name
    }
    
    ImageMapping --> Image : 关联

核心功能模块

1. 图像实体管理

图像模型定义

app/models/image.py

图像实体存储图像的基本信息，包括OSS键值、创建时间等元数据。

class Image(Model):
    id = fields.IntField(description="图片ID", null=False, pk=True)
    key = fields.CharField(description="图片OSS Key", null=False, max_length=255)
    created_by = fields.IntField(description="创建人", null=True, default=-1)
    updated_by = fields.IntField(description="更新人", null=True, default=-1)
    created_at = fields.DatetimeField(description="创建时间", null=False, auto_now_add=True)
    updated_at = fields.DatetimeField(description="更新时间", null=False, auto_now=True)

图像上传流程

sequenceDiagram
    participant Client as 客户端
    participant Router as Image Router
    participant Service as Image Service
    participant CVCore as CVCore SDK
    participant DB as 数据库
    
    Client->>Router: POST /image/create
    Router->>Service: service_upload_new_image()
    Service->>CVCore: upload_image_to_cvcore()
    CVCore-->>Service: 返回file_key
    Service->>DB: Image.create(key=file_key)
    DB-->>Service: 返回image_orm
    Service-->>Router: 返回image_id
    Router-->>Client: 上传成功响应

2. 图像-工件映射管理

映射模型定义

app/models/image_mapping.py

图像映射实体维护图像与工件之间的多对多关系。

class ImageMapping(Model):
    workpiece_id = fields.IntField(description="工件ID AKA Product ID", null=False)
    image_id = fields.IntField(description="图片ID AKA Image ID", null=False)
    created_by = fields.IntField(description="创建人", null=True, default=-1)
    updated_by = fields.IntField(description="更新人", null=True, default=-1)
    created_at = fields.DatetimeField(description="创建时间", null=False, auto_now_add=True)
    updated_at = fields.DatetimeField(description="更新时间", null=False, auto_now=True)

绑定/解绑流程图

flowchart TD
    A[开始绑定] --> B{检查图片是否存在}
    B -->|不存在| C[返回404错误]
    B -->|存在| D{检查是否已绑定}
    D -->|已绑定| E[返回400错误]
    D -->|未绑定| F[调用CVCore SDK]
    F --> G{SDK调用成功}
    G -->|失败| H[返回500错误]
    G -->|成功| I[创建映射关系]
    I --> J[返回成功响应]

3. CVCore集成服务

SDK接口定义

app/lib/cvcore.py

CVCore SDK提供图像识别系统的核心功能集成。

class ImageInSchema(BaseModel):
    pic_name: str = Field(default="", description="图像名称")
    product_id: str = Field(default="", description="产品ID")
    oss_name: str = Field(default="", description="OSS名称")

主要SDK功能

图像上传 - upload_image_to_cvcore()
图像添加 - sdk_add_image()
图像删除 - sdk_delete_image()
图像搜索 - sdk_search_image()

4. 图像搜索功能

搜索流程图

sequenceDiagram
    participant Client as 客户端
    participant Router as Image Router
    participant Service as Image Service
    participant CVCore as CVCore SDK
    
    Client->>Router: GET /image/searchByKey
    Router->>Service: service_search_image_sdk_with_key()
    Service->>CVCore: sdk_search_image(key)
    CVCore-->>Service: 返回搜索结果
    Service-->>Router: 处理结果数据
    Router-->>Client: 返回相似图像列表

API接口文档

图像管理接口

方法	路径	功能描述	参数
POST	`/image/create`	上传新图片	`image: UploadFile`
DELETE	`/image/delete`	删除图片实体	`image_id: int`
GET	`/image/keyById`	获取图片OSS键	`id: int`

绑定管理接口

方法	路径	功能描述	参数
POST	`/image/enable/bind`	绑定图片到工件	`image_id, workpiece_id`
POST	`/image/disable/bind`	解绑图片到工件	`image_id, workpiece_id`

状态查询接口

方法	路径	功能描述
GET	`/image/status/list/unbinds`	获取未绑定图片
GET	`/image/status/list/binds`	获取所有绑定关系
GET	`/image/status/list/imageEntity`	获取所有图片实体

数据流分析

图像上传数据流

flowchart LR
    A[原始图像] --> B[字节数据]
    B --> C[CVCore上传]
    C --> D[OSS存储]
    D --> E[返回file_key]
    E --> F[数据库记录]
    F --> G[系统索引]

图像搜索数据流

flowchart TD
    A[搜索请求] --> B[解析搜索条件]
    B --> C{搜索类型}
    C -->|按Key| D[直接调用CVCore]
    C -->|按ID| E[查询数据库获取Key]
    E --> F[调用CVCore搜索]
    D --> G[返回相似度结果]
    F --> G
    G --> H[格式化响应数据]

性能优化策略

1. 存储优化

使用OSS对象存储进行图像文件管理
数据库仅存储元数据和索引信息
支持图像压缩和格式转换

2. 搜索优化

集成CVCore图像识别引擎
支持基于内容的图像检索
缓存热门搜索结果

3. 并发处理

异步文件上传处理
批量绑定/解绑操作支持
连接池和数据库连接复用

错误处理机制

常见错误类型

上传失败 - 网络问题或存储空间不足
绑定冲突 - 图片已绑定到其他工件
资源不存在 - 图片或工件ID无效
权限不足 - JWT令牌验证失败

错误处理流程

stateDiagram-v2
    [*] --> 正常操作
    正常操作 --> 错误检测: 异常发生
    错误检测 --> 日志记录: 记录错误详情
    日志记录 --> 错误分类: 根据类型分类
    错误分类 --> 客户端错误: 4xx错误
    错误分类 --> 服务端错误: 5xx错误
    客户端错误 --> 用户提示: 返回具体错误信息
    服务端错误 --> 系统告警: 触发监控告警
    用户提示 --> [*]
    系统告警 --> [*]

安全考虑

1. 身份验证

JWT令牌验证所有API请求
访问日志记录用户操作
权限控制基于角色和资源

2. 数据安全

图像文件存储在安全的OSS中
数据库连接使用加密传输
敏感操作需要额外授权

3. 输入验证

文件类型和大小限制
SQL注入防护
路径遍历攻击防护

部署和配置

环境要求

Python 3.8+
FastAPI框架
Tortoise-ORM
CVCore服务端点

配置文件

系统配置通过settings.cvc_target_url指定CVCore服务地址，确保图像服务能够正确连接到图像识别系统。

索引

图像服务模块为邮轮穿舱件管理系统提供了完整的图像处理能力，包括上传、存储、搜索和与工件的关联管理。通过集成专业的CVCore图像识别系统，实现了高效的图像检索和相似度匹配功能，为系统的智能化管理提供了重要支撑。

参考文件:

概述​

系统架构​

核心组件关系图​

类继承关系图​

核心功能模块​

1. 图像实体管理​

图像模型定义​

图像上传流程​

2. 图像-工件映射管理​

映射模型定义​

绑定/解绑流程图​

3. CVCore集成服务​

SDK接口定义​

主要SDK功能​

4. 图像搜索功能​

搜索流程图​

API接口文档​

图像管理接口​

绑定管理接口​

状态查询接口​

数据流分析​

图像上传数据流​

图像搜索数据流​

性能优化策略​

1. 存储优化​

2. 搜索优化​

3. 并发处理​

错误处理机制​

常见错误类型​

错误处理流程​

安全考虑​

1. 身份验证​

2. 数据安全​

3. 输入验证​

部署和配置​

环境要求​

配置文件​

索引​

概述