图像模型文档

概述

本文档详细介绍了邮轮穿舱件管理系统后台中的图像存储和管理相关数据模型。系统采用分层架构设计，包含数据模型层、服务层和API路由层，实现了完整的图像上传、存储、检索和管理功能。

系统架构

整体架构图

flowchart TD
    subgraph 前端层
        A[Web界面]
        B[移动端应用]
    end
    
    subgraph API路由层
        C[ImageRouter]
        D[其他业务路由]
    end
    
    subgraph 服务层
        E[ImageService]
        F[ImageMappingService]
    end
    
    subgraph 数据模型层
        G[Image模型]
        H[ImageMapping模型]
    end
    
    subgraph 外部服务
        I[CVCore图像识别]
        J[OSS存储]
    end
    
    A --> C
    B --> C
    C --> E
    C --> F
    E --> G
    F --> H
    E --> I
    F --> I
    G --> J

组件关系图

classDiagram
    class ImageRouter {
        +APIRouter image_router
        +api_create_new_image()
        +api_delete_image_entity()
        +api_bind_image_to_wp()
        +api_unbind_image_to_wp()
        +api_get_unbind_images()
    }
    
    class ImageService {
        +service_upload_new_image()
        +service_delete_image_entity_by_id()
        +service_bind_image_to_workpiece()
        +service_unbind_image_to_workpiece()
        +service_get_unbind_images()
    }
    
    class ImageMappingService {
        +service_create_image_mapping()
        +service_get_image_mappings_by_workpiece()
        +service_delete_image_mapping()
    }
    
    class Image {
        +IntField id
        +CharField key
        +IntField created_by
        +DatetimeField created_at
    }
    
    class ImageMapping {
        +IntField workpiece_id
        +IntField image_id
        +IntField created_by
        +DatetimeField created_at
    }
    
    class CVCore {
        +upload_image_to_cvcore()
        +sdk_add_image()
        +sdk_delete_image()
        +sdk_search_image()
    }
    
    ImageRouter --> ImageService : 调用
    ImageRouter --> ImageMappingService : 调用
    ImageService --> Image : 操作
    ImageService --> ImageMapping : 操作
    ImageService --> CVCore : 集成
    ImageMappingService --> ImageMapping : 操作

数据模型设计

Image模型

Image模型用于存储图像的基本元数据信息，是系统的核心数据实体。

erDiagram
    IMAGE {
        int id PK "图片ID"
        string key "图片OSS Key"
        int created_by "创建人"
        int updated_by "更新人"
        datetime created_at "创建时间"
        datetime updated_at "更新时间"
    }

字段说明：

id: 图片唯一标识符，主键
key: 图片在OSS存储系统中的键值
created_by: 创建人用户ID
updated_by: 最后更新人用户ID
created_at: 创建时间戳
updated_at: 最后更新时间戳

参考源文件：

image.py

ImageMapping模型

ImageMapping模型用于建立图片与工件之间的多对多映射关系。

erDiagram
    IMAGE_MAPPING {
        int workpiece_id "工件ID"
        int image_id "图片ID"
        int created_by "创建人"
        int updated_by "更新人"
        datetime created_at "创建时间"
        datetime updated_at "更新时间"
    }
    
    IMAGE ||--o{ IMAGE_MAPPING : "被映射"
    WORKPIECE ||--o{ IMAGE_MAPPING : "映射图片"

字段说明：

workpiece_id: 关联的工件ID
image_id: 关联的图片ID
created_by: 创建人用户ID
updated_by: 最后更新人用户ID
created_at: 创建时间戳
updated_at: 最后更新时间戳

参考源文件：

image_mapping.py

服务层设计

ImageService服务

ImageService提供图像实体的核心业务逻辑操作。

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(key: str, image_id: int) Image
        +service_get_unbind_images() List[int]
        +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
    }

主要方法说明：

图像上传流程

sequenceDiagram
    participant Client
    participant ImageRouter
    participant ImageService
    participant CVCore
    participant ImageModel
    
    Client->>ImageRouter: POST /image/create
    ImageRouter->>ImageService: service_upload_new_image()
    ImageService->>CVCore: upload_image_to_cvcore()
    CVCore-->>ImageService: 返回file_key
    ImageService->>ImageModel: create(key=file_key)
    ImageModel-->>ImageService: 返回image_id
    ImageService-->>ImageRouter: 返回image_id
    ImageRouter-->>Client: 成功响应

图像绑定流程

sequenceDiagram
    participant Client
    participant ImageRouter
    participant ImageService
    participant CVCore
    participant ImageModel
    participant ImageMappingModel
    
    Client->>ImageRouter: POST /image/enable/bind
    ImageRouter->>ImageService: service_bind_image_to_workpiece()
    ImageService->>ImageModel: 验证image_id存在
    ImageService->>ImageMappingModel: 检查是否已绑定
    ImageService->>CVCore: sdk_add_image()
    CVCore-->>ImageService: 绑定成功
    ImageService->>ImageMappingModel: create映射关系
    ImageMappingModel-->>ImageService: 返回tuple_id
    ImageService-->>ImageRouter: 返回成功
    ImageRouter-->>Client: 绑定成功

参考源文件：

image_service.py

ImageMappingService服务

ImageMappingService专门处理图片映射关系的业务逻辑。

classDiagram
    class ImageMappingService {
        +service_create_image_mapping(workpiece_id: int, image_id: int) ImageMapping
        +service_get_image_mapping_by_id(mapping_id: int) Optional[ImageMapping]
        +service_get_all_image_mappings(skip: int, limit: int) List[ImageMapping]
        +service_get_image_mappings_by_workpiece(workpiece_id: int) List[ImageMapping]
        +service_get_image_mappings_by_image(image_id: int) List[ImageMapping]
        +service_delete_image_mapping(mapping_id: int) bool
        +service_delete_image_mapping_by_workpiece_and_image(workpiece_id: int, image_id: int) bool
    }

参考源文件：

image_mapping_service.py

API路由设计

ImageRouter路由

ImageRouter提供RESTful API接口，对外暴露图像管理功能。

flowchart TD
    A[客户端请求] --> B{路由选择}
    
    B -->|创建图片| C[POST /image/create]
    B -->|删除图片| D[DELETE /image/delete]
    B -->|获取OSS键| E[GET /image/keyById]
    B -->|绑定图片| F[POST /image/enable/bind]
    B -->|解绑图片| G[POST /image/disable/bind]
    B -->|未绑定列表| H[GET /image/status/list/unbinds]
    B -->|绑定元组| I[GET /image/status/list/binds]
    B -->|图片实体| J[GET /image/status/list/imageEntity]
    B -->|Key搜索| K[GET /image/searchByKey]
    B -->|ID搜索| L[GET /image/searchById]
    
    C --> M[返回image_id]
    D --> N[返回成功消息]
    E --> O[返回OSS键]
    F --> P[返回绑定结果]
    G --> Q[返回解绑结果]
    H --> R[返回未绑定ID列表]
    I --> S[返回绑定元组列表]
    J --> T[返回图片实体列表]
    K --> U[返回搜索结果]
    L --> V[返回搜索结果]

主要接口说明：

创建图片: POST /image/create - 上传新图片到系统
删除图片: DELETE /image/delete - 删除指定图片实体
绑定图片: POST /image/enable/bind - 将图片绑定到工件
解绑图片: POST /image/disable/bind - 解除图片与工件的绑定关系

参考源文件：

image_router.py

外部服务集成

CVCore图像识别服务

系统通过CVCore模块与外部图像识别服务集成。

classDiagram
    class CVCore {
        +ImageInSchema data_model
        +upload_image_to_cvcore(image: bytes) Dict
        +sdk_add_image(image: ImageInSchema) Dict
        +sdk_delete_image(product_id: str, pic_name: str) Dict
        +sdk_search_image(key: str) Dict
    }
    
    class ImageInSchema {
        +str pic_name
        +str product_id
        +str oss_name
    }

主要功能：

图像上传到OSS存储
图像识别模型训练
图像搜索和匹配
图像删除管理

参考源文件：

cvcore.py

数据流分析

图像上传数据流

flowchart LR
    A[客户端上传图片] --> B[ImageRouter接收]
    B --> C[ImageService处理]
    C --> D[CVCore上传OSS]
    D --> E[返回OSS Key]
    E --> F[创建Image记录]
    F --> G[返回image_id]

图像绑定数据流

flowchart TD
    A[绑定请求] --> B[验证图片存在]
    B --> C[检查是否已绑定]
    C --> D{是否已绑定}
    D -->|是| E[返回错误]
    D -->|否| F[调用CVCore SDK]
    F --> G[创建映射关系]
    G --> H[返回成功]

错误处理机制

系统采用分层的错误处理策略：

数据验证错误: 参数验证失败时返回400状态码
业务逻辑错误: 如重复绑定、资源不存在等返回相应错误信息
系统错误: 外部服务异常等返回500状态码

性能考虑

数据库优化: 使用索引优化查询性能
缓存策略: 高频查询数据可考虑缓存
异步处理: 图像上传和处理采用异步方式
分页查询: 大数据量查询支持分页

索引

图像模型系统采用清晰的分层架构，通过Image和ImageMapping两个核心数据模型，结合服务层和API路由层，实现了完整的图像存储和管理功能。系统具有良好的扩展性和维护性，能够满足邮轮穿舱件管理系统的图像处理需求。

关键特性：

完整的图像生命周期管理
灵活的图片-工件映射关系
与外部图像识别服务的深度集成
完善的错误处理和日志记录
RESTful API设计，便于前端集成

参考源文件汇总：

概述​

系统架构​

整体架构图​

组件关系图​

数据模型设计​

Image模型​

ImageMapping模型​

服务层设计​

ImageService服务​

ImageMappingService服务​

API路由设计​

ImageRouter路由​

外部服务集成​

CVCore图像识别服务​

数据流分析​

图像上传数据流​

图像绑定数据流​

错误处理机制​

性能考虑​

索引​

概述

系统架构

整体架构图

组件关系图

数据模型设计

Image模型

ImageMapping模型

服务层设计

ImageService服务

ImageMappingService服务

API路由设计

ImageRouter路由

外部服务集成

CVCore图像识别服务

数据流分析

图像上传数据流

图像绑定数据流

错误处理机制

性能考虑

索引