跳到主要内容

工件管理接口文档

文档概述​

1.1 文档目的​

本文档详细描述了邮轮穿舱件管理系统中工件管理模块的完整接口规范、前端组件架构和业务逻辑流程。基于对系统代码的深入分析，提供全面的技术文档。

1.2 适用对象​

  • 前端开发人员
  • 后端开发人员
  • 系统测试人员
  • 项目管理人员

1.3 系统背景​

邮轮穿舱件管理系统是专门用于管理邮轮防火穿舱件的后台管理系统，工件管理模块负责处理防火板、穿舱件等核心工件的全生命周期管理。

2. 系统架构分析​

2.1 前端架构概览​

flowchart TD
    subgraph Frontend Architecture
        A[WorkpieceView.vue] --> B[WorkpieceEdit.vue]
        A --> C[HTTP Service]
        B --> C
        C --> D[Backend API]
    end
    
    subgraph Component Hierarchy
        E[App.vue] --> F[Router]
        F --> G[WorkpieceView]
        F --> H[WorkpieceEdit]
    end

架构说明：

  • 采用Vue.js + Vuetify技术栈构建的单页面应用
  • 基于组件化的架构设计，实现高内聚低耦合
  • 使用Vue Router进行页面路由管理
  • 通过Axios HTTP客户端与后端API通信

2.2 组件依赖关系​

graph TD
    A[WorkpieceView] --> B[WorkpieceEdit]
    A --> C[HTTP Service]
    B --> C
    C --> D[Axios]
    D --> E[Backend API]
    A --> F[Vuetify Components]
    B --> F

依赖分析：

  • WorkpieceView和WorkpieceEdit组件共享HTTP服务层
  • 所有API调用通过统一的Axios实例处理
  • 组件间通过Vue Router进行导航和数据传递

3. 接口规范​

3.1 基础信息​

  • 基础URL: 由环境变量VUE_APP_API配置
  • 认证方式: JWT Bearer Token
  • 数据格式: JSON
  • 字符编码: UTF-8

3.2 通用响应格式​

成功响应​

{
  "data": {},
  "message": "操作成功"
}

错误响应​

{
  "detail": "错误描述信息"
}

4. 工件管理接口详情​

4.1 工件基础操作接口​

4.1.1 获取所有工件​

  • 接口路径: /workpiece/all
  • 请求方法: GET
  • 功能描述: 获取系统中所有工件的基本信息列表
  • 权限要求: 需要JWT认证

响应数据结构：

interface BaseWorkpiece {
  workpiece_id: number;
  workpiece_status: number; // 0:未生效, 1:已生效, 2:维护中
  created_at: string;
  updated_at: string;
  created_by: number;
  updated_by: number;
  maintainance_reference: number;
  inspect_reference: number;
}

4.1.2 创建新工件​

  • 接口路径: /workpiece
  • 请求方法: POST
  • 功能描述: 创建新的基础工件记录
  • 请求体: 空
  • 响应: 返回新创建的工件基本信息

4.1.3 删除工件​

  • 接口路径: /workpiece/{workpiece_id}
  • 请求方法: DELETE
  • 功能描述: 删除指定的工件记录
  • 请求参数:
    • confirm_name: 确认名称（用于已实例化工件）

4.2 工件详细信息接口​

4.2.1 获取工件详细信息​

  • 接口路径: /workpiece-info/{workpiece_id}
  • 请求方法: GET
  • 功能描述: 获取工件的完整详细信息

响应数据结构：

interface WorkpieceInfo {
  wp_id: string;
  wp_firestop_code: string;    // 防火板代号
  wp_matrial: string;          // 材料
  wp_size: string;             // 规格
  wp_fire_rating: string;      // 防火等级
  wp_watertightness: string;   // 水密等级
  wp_main_vertical_zone: string; // 主竖区
  wp_installation_location: string; // 安装位置
  wp_z_coordinate: string;     // Z坐标
  wp_frame_station: string;    // 肋位
  wp_longitudinal_stiffener: string; // 纵桁
  wp_sap1: string;             // SAP1
  wp_sap2: string;             // SAP2
  wp_standard_drawing_catalogue: string; // 图册章节
  wp_extra: string;            // 额外信息
}

4.2.2 创建工件信息​

  • 接口路径: /workpiece-info/
  • 请求方法: POST
  • 功能描述: 为工件创建详细信息（实例化工件）
  • 请求体: WorkpieceInfo对象

4.2.3 更新工件信息​

  • 接口路径: /workpiece-info/{workpiece_id}
  • 请求方法: PUT
  • 功能描述: 更新工件的详细信息
  • 请求体: WorkpieceInfo对象

4.2.4 删除工件信息​

  • 接口路径: /workpiece-info/{workpiece_id}
  • 请求方法: DELETE
  • 功能描述: 删除工件的详细信息

5. 前端组件分析​

5.1 WorkpieceView组件架构​

classDiagram
    class WorkpieceView {
        +data(): Object
        +computed: filteredActiveWorkpieces
        +mounted(): void
        +methods: loadWorkpieces()
        +methods: createWorkpiece()
        +methods: editWorkpiece()
        +methods: viewWorkpiece()
        +methods: deleteWorkpiece()
    }
    
    class WorkpieceEdit {
        +data(): Object
        +computed: isInitializing
        +methods: initializeWorkpiece()
        +methods: saveWorkpiece()
        +methods: deleteWorkpiece()
    }
    
    WorkpieceView --> WorkpieceEdit : navigates to

5.1.1 组件功能特性​

数据管理：

  • 分离管理已生效和未生效工件
  • 实时数据筛选和排序功能
  • 分页显示支持

用户交互：

  • 双击查看工件详情
  • 一键创建新工件
  • 批量操作支持
  • 实时搜索筛选

状态管理：

stateDiagram-v2
    [*] --> Loading
    Loading --> Loaded : 数据加载成功
    Loading --> Error : 数据加载失败
    Loaded --> Filtering : 用户筛选
    Filtered --> Viewing : 查看详情
    Viewing --> Editing : 编辑操作
    Editing --> Saving : 保存修改
    Saving --> Loaded : 保存成功
    Saving --> Error : 保存失败

5.2 WorkpieceEdit组件架构​

5.2.1 表单验证规则​

// 防火板代号验证
firestopCodeRules: [
  v => !!v || '防火板代号不能为空',
  v => (v && v.length >= 2) || '防火板代号至少2个字符'
],

// 材料验证  
materialRules: [
  v => !!v || '材料不能为空'
]

5.2.2 业务逻辑流程​

sequenceDiagram
    participant User
    participant WorkpieceEdit
    participant HTTP
    participant Backend
    
    User->>WorkpieceEdit: 进入编辑页面
    WorkpieceEdit->>HTTP: GET /workpiece-info/{id}
    HTTP->>Backend: 请求工件信息
    Backend-->>HTTP: 返回工件数据
    HTTP-->>WorkpieceEdit: 更新表单数据
    
    User->>WorkpieceEdit: 修改表单数据
    User->>WorkpieceEdit: 点击保存
    WorkpieceEdit->>HTTP: PUT /workpiece-info/{id}
    HTTP->>Backend: 更新工件信息
    Backend-->>HTTP: 更新成功
    HTTP-->>WorkpieceEdit: 显示成功消息
    WorkpieceEdit->>User: 返回列表页面

6. 数据流分析​

6.1 工件状态管理​

graph TD
    A[创建基础工件] --> B[未生效状态]
    B --> C[填写详细信息]
    C --> D[已生效状态]
    D --> E[维护中状态]
    D --> F[已停用状态]
    E --> D[维护完成]
    F --> G[删除工件]

状态说明：

  • 未生效状态 (0): 仅创建基础记录，等待详细信息填写
  • 已生效状态 (1): 详细信息已填写，可正常使用
  • 维护中状态 (2): 正在进行维护操作
  • 已停用状态 (-1): 已停用，不可使用

6.2 数据验证流程​

flowchart TD
    A[用户输入] --> B[前端验证]
    B --> C{验证通过?}
    C -->|是| D[发送API请求]
    C -->|否| E[显示错误信息]
    D --> F[后端验证]
    F --> G{验证通过?}
    G -->|是| H[保存数据]
    G -->|否| I[返回错误响应]
    H --> J[操作成功]
    I --> E

7. 错误处理机制​

7.1 前端错误处理​

  • 网络请求超时处理
  • API响应错误码解析
  • 用户操作错误提示
  • 表单验证错误显示

7.2 后端错误码映射​

  • 400: 请求参数错误
  • 401: 未授权访问
  • 404: 资源不存在
  • 500: 服务器内部错误

8. 性能优化建议​

8.1 前端优化​

  • 实现数据懒加载
  • 添加请求防抖机制
  • 优化组件渲染性能
  • 使用虚拟滚动处理大数据量

8.2 后端优化​

  • 添加查询缓存机制
  • 优化数据库索引
  • 实现分页查询优化
  • 添加API响应压缩

9. 安全考虑​

9.1 认证安全​

  • JWT令牌有效期管理
  • 接口权限验证
  • 敏感操作二次确认

9.2 数据安全​

  • 输入数据验证和清理
  • SQL注入防护
  • XSS攻击防护

10. 参考文件​

源代码文件引用：​

核心代码片段引用：​

索引​

本文档全面分析了邮轮穿舱件管理系统中工件管理模块的接口规范、前端架构和业务逻辑。系统采用现代化的前后端分离架构，通过RESTful API实现数据交互，具备完整的CRUD操作功能和健全的错误处理机制。

关键特性：

  • 完整的工件生命周期管理
  • 实时数据筛选和搜索功能
  • 健全的表单验证机制
  • 友好的用户交互体验
  • 完善的安全防护措施

该系统为邮轮穿舱件管理提供了高效、可靠的技术解决方案，具有良好的可扩展性和维护性。