图片管理接口文档

概述

本文档详细介绍了邮轮穿舱件管理系统的图片管理接口规范。该系统提供完整的图片上传、下载、绑定、解绑和管理功能，支持图像与工件的关联管理，为系统提供丰富的图像数据支持。

系统架构

前端架构图

flowchart TD
    subgraph Frontend
        A[ImageView.vue] --> B[ImageAdmin.vue]
        A --> C[HTTP Service]
        B --> C
        C --> D[Backend API]
    end
    
    subgraph Backend
        D --> E[Image Management]
        D --> F[Workpiece Management]
        E --> G[Image Storage]
        F --> H[Workpiece Database]
    end

组件依赖关系

flowchart TD
    subgraph ImageManagement
        A[ImageView] --> B[ImageAdmin]
        A --> C[HTTP Service]
        B --> C
        C --> D[Axios]
        D --> E[Authentication]
    end
    
    subgraph ExternalDependencies
        F[Vuetify UI]
        G[Vue Router]
        H[Vuex Store]
    end
    
    A --> F
    A --> G
    A --> H
    B --> F

核心接口规范

1. 图像上传接口

接口: POST /image/create

描述: 上传新的图像文件到系统

请求格式: multipart/form-data

请求参数:

• image (File): 图像文件

响应示例:

{
  "image_id": 123,
  "key": "image_20240115_103000.jpg",
  "created_at": "2024-01-15T10:30:00Z"
}

前端实现参考:

• ImageView.vue
• ImageAdmin.vue

2. 图像下载接口

接口: GET /image-infrastructure/download

描述: 根据图像key下载图像数据

查询参数:

• key (string): 图像唯一标识符

响应格式: Base64编码的图像数据

前端实现参考:

• ImageView.vue

3. 图像绑定接口

接口: POST /image/enable/bind

描述: 将图像绑定到指定工件

请求体:

{
  "image_id": 123,
  "workpiece_id": 456
}

前端实现参考:

• ImageView.vue

4. 图像解绑接口

接口: POST /image/disable/bind

描述: 解除图像与工件的绑定关系

请求体:

{
  "image_id": 123,
  "workpiece_id": 456
}

前端实现参考:

• ImageView.vue

5. 图像删除接口

接口: DELETE /image/delete

描述: 删除指定的图像

查询参数:

• image_id (integer): 图像ID

前端实现参考:

• ImageView.vue

6. 图像列表查询接口

接口: GET /image/status/list/imageEntity

描述: 获取所有图像实体的列表

响应示例:

[
  {
    "id": 1,
    "key": "image1.jpg",
    "name": "工件正面图",
    "description": "工件的正面拍摄图像",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
]

前端实现参考:

• ImageView.vue

7. 绑定关系查询接口

接口: GET /image/status/list/binds

描述: 获取所有已绑定的图像映射关系

响应示例:

[
  {
    "image_id": 1,
    "workpiece_id": 123
  }
]

前端实现参考:

• ImageView.vue

8. 未绑定图像查询接口

接口: GET /image/status/list/unbinds

描述: 获取所有未绑定的图像ID列表

响应示例:

[1, 2, 3]

前端实现参考:

• ImageView.vue

数据模型

图像实体模型 (ImageEntity)

classDiagram
    class ImageEntity {
        +id: integer
        +key: string
        +name: string
        +description: string
        +workpiece_id: integer?
        +created_at: datetime
        +updated_at: datetime
        +getImageUrl(): string
        +isBound(): boolean
    }

属性说明:

• id: 图像唯一标识符
• key: 图像存储键值
• name: 图像名称（可选）
• description: 图像描述（可选）
• workpiece_id: 关联的工件ID，null表示未绑定
• created_at: 创建时间
• updated_at: 更新时间

绑定关系模型 (ImageBind)

classDiagram
    class ImageBind {
        +image_id: integer
        +workpiece_id: integer
        +created_at: datetime
    }
    
    ImageEntity "1" --> "0..1" ImageBind : has

前端组件架构

ImageView.vue 组件结构

classDiagram
    class ImageView {
        +images: Array~ImageEntity~
        +filteredImages: Array~ImageEntity~
        +availableWorkpieces: Array~Workpiece~
        +searchQuery: string
        +statusFilter: string
        +viewMode: string
        +loadImages(): Promise~void~
        +filterImages(): void
        +uploadImages(): Promise~void~
        +bindImage(image): void
        +unbindImage(image): Promise~void~
        +deleteImage(image): Promise~void~
    }
    
    class ImageEntity {
        +id: integer
        +key: string
        +name: string
        +url: string
        +workpiece_id: integer?
    }
    
    ImageView "1" --> "*" ImageEntity : manages

组件方法调用流程

sequenceDiagram
    participant User
    participant ImageView
    participant HTTPService
    participant BackendAPI
    
    User->>ImageView: 页面加载
    ImageView->>HTTPService: loadImages()
    HTTPService->>BackendAPI: GET /image/status/list/imageEntity
    BackendAPI-->>HTTPService: 图像列表
    HTTPService-->>ImageView: 图像数据
    ImageView->>ImageView: 渲染图像网格
    
    User->>ImageView: 点击上传按钮
    ImageView->>HTTPService: uploadImages()
    HTTPService->>BackendAPI: POST /image/create
    BackendAPI-->>HTTPService: 上传结果
    HTTPService-->>ImageView: 上传成功

状态管理

图像状态流程图

stateDiagram-v2
    [*] --> Unbound
    Unbound --> Bound : bindImage()
    Bound --> Unbound : unbindImage()
    Unbound --> [*] : deleteImage()
    Bound --> [*] : deleteImage()

筛选状态管理

flowchart TD
    A[全部图像] --> B{筛选条件}
    B -->|已绑定| C[显示已绑定图像]
    B -->|未绑定| D[显示未绑定图像]
    B -->|全部| E[显示所有图像]
    C --> F[列表/网格视图]
    D --> F
    E --> F

错误处理机制

错误处理流程图

flowchart TD
    A[API调用] --> B{调用成功?}
    B -->|是| C[更新界面状态]
    B -->|否| D[错误处理]
    D --> E[显示错误消息]
    D --> F[使用备用数据]
    E --> G[用户重试]
    F --> C

错误类型处理

错误类型	处理方式	用户提示
网络错误	重试机制 + 备用数据	"网络连接失败，请检查网络"
认证错误	跳转到登录页	"请重新登录"
权限错误	显示无权限页面	"您没有访问权限"
数据错误	数据验证 + 默认值	"数据加载失败，使用默认数据"

性能优化建议

1. 图像懒加载

// 实现图像懒加载
const lazyLoadImages = () => {
  const images = document.querySelectorAll('img[data-src]')
  const observer = new IntersectionObserver((entries) => {
    entries.forEach(entry => {
      if (entry.isIntersecting) {
        const img = entry.target
        img.src = img.dataset.src
        observer.unobserve(img)
      }
    })
  })
  images.forEach(img => observer.observe(img))
}

2. 图像缓存策略

• 使用浏览器缓存存储已下载的图像
• 实现图像预览的本地缓存
• 设置合适的缓存过期时间

3. 分页加载优化

// 分页加载实现
const loadImagesWithPagination = async (page, pageSize) => {
  const start = (page - 1) * pageSize
  const end = start + pageSize
  return images.slice(start, end)
}

安全考虑

1. 文件上传安全

• 验证文件类型和大小
• 扫描恶意代码
• 限制上传频率

2. 数据访问安全

• 验证用户权限
• 实施CSRF保护
• 使用HTTPS传输

参考文件

核心实现文件

• ImageView.vue - 主要的图像管理界面
• ImageAdmin.vue - 图像上传管理组件
• http/index.js - HTTP服务配置

相关文档

• API_Doc_ticket.md - 工单API文档（包含图像引用）

索引

图片管理接口为邮轮穿舱件管理系统提供了完整的图像生命周期管理功能，包括上传、下载、绑定、解绑和删除等操作。系统采用模块化设计，具有良好的可扩展性和维护性。前端组件通过统一的HTTP服务与后端API交互，实现了用户友好的图像管理界面。

关键特性包括：

• 支持多种图像格式上传
• 实时图像预览和绑定状态管理
• 灵活的筛选和搜索功能
• 完善的错误处理和用户反馈
• 优化的性能和安全考虑

该系统为邮轮穿舱件的图像资料管理提供了可靠的技术支持，能够满足复杂的工业应用场景需求。