邮轮穿舱件管理系统 - 工件管理模块文档

概述

本文档详细记录了邮轮穿舱件管理系统中工件管理模块的完整架构和实现细节。该系统采用分层架构设计，实现了工件全生命周期的管理，包括工件基本信息管理、状态跟踪、详细信息管理等核心功能。

系统架构

整体架构图

flowchart TD
    subgraph 前端层
        A[Web界面]
        B[移动端应用]
    end
    
    subgraph API网关层
        C[工件管理路由]
        D[工件信息路由]
    end
    
    subgraph 业务逻辑层
        E[工件服务]
        F[工件信息服务]
    end
    
    subgraph 数据访问层
        G[PostgreSQL<br/>工件表]
        H[MongoDB<br/>工件信息表]
    end
    
    A --> C
    B --> C
    C --> E
    D --> F
    E --> G
    F --> H

技术栈

• 后端框架: FastAPI
• 数据库: PostgreSQL + MongoDB混合存储
• ORM: Tortoise-ORM (PostgreSQL) + Beanie (MongoDB)
• 认证: JWT Token认证
• 日志: 结构化日志记录

数据模型设计

工件核心模型 (PostgreSQL)

erDiagram
    WORKPIECE {
        int workpiece_id PK "工件ID"
        int workpiece_status "工件状态"
        int inspect_reference "视检参考工单ID"
        int maintainance_reference "维护参考工单ID"
        int created_by "创建人"
        int updated_by "更新人"
        datetime created_at "创建时间"
        datetime updated_at "更新时间"
    }

参考文件: workpiece.py

工件详细信息模型 (MongoDB)

erDiagram
    WORKPIECE_INFO {
        string wp_id PK "工件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 "Z坐标"
        string wp_frame_station "肋位"
        string wp_longitudinal_stiffener "纵桁"
        string wp_sap1 "SAP1"
        string wp_sap2 "SAP2"
        string wp_standard_drawing_catalogue "图册章节"
        string wp_extra "额外信息"
    }

参考文件: mg_workpiece_info.py

数据流架构

工件生命周期数据流

flowchart LR
    A[工件创建] --> B[基本信息存储<br/>PostgreSQL]
    B --> C[详细信息补充<br/>MongoDB]
    C --> D[状态跟踪更新]
    D --> E[工单关联]
    E --> F[维护记录]
    F --> G[历史归档]
    
    H[用户操作] --> I[访问日志记录]
    I --> J[审计追踪]

业务逻辑实现

工件服务层

核心服务方法

# 工件创建服务
async def service_create_workpiece(
    inspect_reference: int = 0, 
    maintainance_reference: int = 0, 
    created_by: int = -1
) -> Workpiece:
    """
    创建工件实体，包含基本状态信息和工单关联
    """

参考文件: workpiece_service.py

状态管理服务

# 工件状态更新服务
async def service_update_workpiece_status(
    workpiece_id: int, 
    updated_status: int, 
    updated_by: int = -1
) -> Optional[Workpiece]:
    """
    更新工件状态，支持状态跟踪和工作流管理
    """

参考文件: workpiece_service.py

工件信息服务层

详细信息管理

sequenceDiagram
    participant Client as 客户端
    participant Router as 工件信息路由
    participant Service as 工件信息服务
    participant MongoDB as MongoDB
    
    Client->>Router: POST /workpiece-info/
    Router->>Service: service_create_workpiece_info()
    Service->>MongoDB: 检查wp_id唯一性
    MongoDB-->>Service: 验证结果
    Service->>MongoDB: 插入新文档
    MongoDB-->>Service: 插入结果
    Service-->>Router: 返回工件信息
    Router-->>Client: 创建成功响应

参考文件: workpiece_info_service.py

搜索功能实现

# 防火板代号搜索服务
async def service_search_workpiece_infos_by_code(firestop_code: str) -> List[WorkpieceInfo]:
    """
    基于防火板代号的模糊搜索，支持部分匹配
    """

参考文件: workpiece_info_service.py

API接口设计

工件管理API

路由结构

flowchart TD
    A[POST /workpiece] --> A1[创建工件]
    B[GET /workpiece/all] --> B1[获取所有工件]
    C[DELETE /workpiece/{wp_id}] --> C1[删除工件]
    D[PUT /workpiece/{wp_id}/status] --> D1[更新工件状态]
    
    E[POST /workpiece-info/] --> E1[创建工件信息]
    F[GET /workpiece-info/{wp_id}] --> F1[获取工件信息]
    G[GET /workpiece-info/] --> G1[分页获取列表]
    H[PUT /workpiece-info/{wp_id}] --> H1[更新工件信息]
    I[DELETE /workpiece-info/{wp_id}] --> I1[删除工件信息]
    J[GET /workpiece-info/search/by-code] --> J1[搜索工件信息]

核心API端点

方法	路径	功能	认证要求
POST	/workpiece	创建工件	JWT Token
GET	/workpiece/all	获取所有工件	JWT Token
DELETE	/workpiece/{wp_id}	删除工件	JWT Token
PUT	/workpiece/{wp_id}/status	更新状态	JWT Token

参考文件: workpiece_router.py

工件信息API端点

方法	路径	功能	数据验证
POST	/workpiece-info/	创建工件信息	WorkpieceInfoSchemaIn
GET	/workpiece-info/{wp_id}	获取详细信息	WorkpieceInfoSchemaOut
PUT	/workpiece-info/{wp_id}	更新信息	WorkpieceInfoSchemaUpdate
GET	/workpiece-info/search/by-code	搜索工件	防火板代号参数

参考文件: workpiece_info_router.py

数据验证模式

输入验证模式

classDiagram
    class WorkpieceInfoSchemaIn {
        +wp_id: str
        +wp_firestop_code: str
        +wp_matrial: str
        +wp_size: str
        +wp_fire_rating: str
        +wp_watertightness: str
        +wp_main_vertical_zone: str
        +wp_installation_location: str
        +wp_z_coordinate: str
        +wp_frame_station: str
        +wp_longitudinal_stiffener: str
        +wp_sap1: str
        +wp_sap2: str
        +wp_standard_drawing_catalogue: str
        +wp_extra: Optional[str]
    }

参考文件: workpiece_info_schema.py

输出验证模式

classDiagram
    class WorkpieceInfoSchemaOut {
        +wp_id: str
        +wp_firestop_code: str
        +wp_matrial: str
        +wp_size: str
        +wp_fire_rating: str
        +wp_watertightness: str
        +wp_main_vertical_zone: str
        +wp_installation_location: str
        +wp_z_coordinate: str
        +wp_frame_station: str
        +wp_longitudinal_stiffener: str
        +wp_sap1: str
        +wp_sap2: str
        +wp_standard_drawing_catalogue: str
        +wp_extra: str
    }

参考文件: workpiece_info_schema.py

错误处理机制

异常处理层次

flowchart TD
    A[业务逻辑异常] --> B[服务层捕获]
    B --> C[路由层处理]
    C --> D[统一错误响应]
    
    E[数据库异常] --> F[完整性约束检查]
    F --> G[唯一性验证]
    G --> H[适当的HTTP状态码]

具体错误处理

错误类型	HTTP状态码	处理方式
工件不存在	404 Not Found	返回详细错误信息
重复工件ID	400 Bad Request	数据验证拒绝
数据库错误	500 Internal Server Error	日志记录并返回通用错误
认证失败	401 Unauthorized	JWT Token验证

安全与审计

访问控制

sequenceDiagram
    participant User as 用户
    participant Auth as 认证中间件
    participant Router as 路由层
    participant Service as 服务层
    
    User->>Auth: 请求携带JWT Token
    Auth->>Auth: 验证Token有效性
    Auth->>Router: 认证通过
    Router->>Service: 执行业务逻辑
    Service->>Service: 记录访问日志

审计日志

每个API调用都会自动记录访问日志，包含：

• 操作类型和描述
• 相关用户ID
• 时间戳
• 关联的工件和工单信息

性能优化考虑

数据库优化策略

1. 索引优化: MongoDB中为wp_id和wp_firestop_code建立索引
2. 查询分页: 支持skip/limit参数控制返回数据量
3. 连接池: 数据库连接复用
4. 缓存策略: 热点数据缓存考虑

搜索优化

• 使用MongoDB的regex查询实现模糊搜索
• 支持大小写不敏感的搜索选项
• 搜索结果分页返回，避免大数据量传输

部署与迁移

数据库迁移

# 空数据库初始化
aerich init-db

# 模型更新迁移
aerich migrate
aerich upgrade

容器化部署

系统支持Docker容器化部署，包含完整的依赖管理和环境配置。

索引

邮轮穿舱件管理系统的工件管理模块采用了现代化的微服务架构设计，具有以下特点：

1. 分层清晰: 明确的数据层、服务层、API层分离
2. 混合存储: PostgreSQL用于事务性数据，MongoDB用于文档型数据
3. 完整生命周期: 支持工件的创建、状态跟踪、信息管理、搜索和删除
4. 安全可靠: JWT认证和完整的审计日志
5. 扩展性强: 模块化设计便于功能扩展

该系统为邮轮穿舱件的全生命周期管理提供了完整的技术解决方案。

参考文件汇总:

• workpiece.py
• mg_workpiece_info.py
• workpiece_service.py
• workpiece_info_service.py
• workpiece_router.py
• workpiece_info_router.py
• workpiece_info_schema.py