邮轮穿舱件管理系统后台 - 服务层文档

文档概述

本文档详细分析邮轮穿舱件管理系统后台的业务逻辑层实现，涵盖所有service组件的功能、接口和依赖关系。通过深入分析代码结构，提供全面的架构视图和实现细节。

服务层架构概览

邮轮穿舱件管理系统采用分层架构设计，服务层作为业务逻辑的核心层，负责处理所有业务规则、数据验证和业务操作。服务层位于数据访问层（模型层）和表示层（路由层）之间，实现关注点分离。

服务组件依赖关系图

flowchart TD
    subgraph 核心服务层
        A[用户服务]
        B[角色权限服务]
        C[工单服务]
        D[工件服务]
        E[工件信息服务]
        F[图片服务]
        G[图片映射服务]
        H[访问日志服务]
    end
    
    subgraph 数据访问层
        I[用户模型]
        J[角色模型]
        K[工单模型]
        L[工件模型]
        M[工件信息模型]
        N[图片模型]
        O[图片映射模型]
        P[访问日志模型]
    end
    
    subgraph 工具库层
        Q[密码工具]
        R[图片处理工具]
        S[日志工具]
    end
    
    A --> I
    B --> J
    C --> K
    D --> L
    E --> M
    F --> N
    G --> O
    H --> P
    
    A --> Q
    F --> R
    A --> S
    B --> S
    C --> S
    D --> S
    E --> S
    F --> S
    G --> S
    H --> S

服务组件详细分析

1. 用户服务 (User Service)

文件引用: user_service.py

功能概述

用户服务负责管理系统的用户账户，包括用户注册、认证、信息管理和状态控制。

核心接口

# 密码管理工具函数
def service_util_hash_password(password: str) -> str
def service_util_verify_password(password: str, hashed_password: str) -> bool

# 用户CRUD操作
async def service_create_user(user_data: UserSchemaIn, created_by: int = -1) -> UserSchemaOut
async def service_get_user_by_id(user_id: int) -> Optional[UserSchemaOut]
async def service_get_user_by_username(username: str) -> Optional[UserSchemaOut]
async def service_get_user_by_openid(openid: str) -> Optional[UserSchemaOut]
async def service_get_all_users(skip: int = 0, limit: int = 100) -> List[UserSchemaOut]
async def service_update_user(user_id: int, user_data: UserUpdateSchema, updated_by: int = -1) -> Optional[UserSchemaOut]
async def service_delete_user(user_id: int) -> bool

# 用户认证和状态管理
async def service_authenticate_user(login_data: UserLoginSchema) -> Optional[UserSchemaOut]
async def service_change_user_status(user_id: int, status: UserStatus, updated_by: int = -1) -> Optional[UserSchemaOut]

依赖关系

• 数据模型: User 模型
• 数据模式: UserSchemaIn, UserSchemaOut, UserUpdateSchema, UserLoginSchema
• 工具库: bcrypt 密码哈希库
• 日志系统: app.core.loggers.logger

业务逻辑流程图

flowchart TD
    A[用户请求] --> B{操作类型}
    B -->|创建用户| C[验证用户名唯一性]
    B -->|用户登录| D[多方式用户查找]
    B -->|更新用户| E[验证更新数据]
    
    C --> F[检查邮箱唯一性]
    F --> G[密码哈希处理]
    G --> H[创建用户记录]
    
    D --> I[用户名/邮箱/手机号查找]
    I --> J[密码验证]
    J --> K[用户状态检查]
    
    E --> L[字段级验证]
    L --> M[唯一性检查]
    M --> N[数据更新]
    
    H --> O[返回用户信息]
    K --> O
    N --> O

2. 角色权限服务 (Role Service)

文件引用: role_service.py

功能概述

角色权限服务管理用户的权限分配和验证，支持细粒度的权限控制。

核心接口

async def service_get_user_scopes(user_id: int) -> List[str]
async def service_grant_user_a_scope(user_id: int, scope_name: str)
async def service_revoke_user_a_scope(user_id: int, scope_name: str)

依赖关系

• 数据模型: Role 模型
• 异常处理: tortoise.exceptions.DoesNotExist, IntegrityError
• HTTP异常: fastapi.HTTPException
• 日志系统: app.core.loggers.logger

权限管理流程图

sequenceDiagram
    participant Client
    participant Router
    participant RoleService
    participant RoleModel
    participant Logger
    
    Client->>Router: 权限请求
    Router->>RoleService: service_get_user_scopes(user_id)
    RoleService->>RoleModel: filter(user_id=user_id).first()
    RoleModel-->>RoleService: Role对象
    RoleService->>RoleService: scope_list.split(",")
    RoleService->>Logger: 记录操作日志
    RoleService-->>Router: 权限列表
    Router-->>Client: 响应结果

3. 工单服务 (Ticket Service)

文件引用: ticket_service.py

功能概述

工单服务管理系统的工单生命周期，包括创建、查询、更新和删除操作。

核心接口

async def service_get_all_ticket_entitys() -> List[TicketOutSchema]
async def service_create_ticket(ticket_schema: TicketInSchema) -> Ticket
async def service_update_ticket(ticket_id: int, ticket_schema: TicketInSchema) -> Ticket
async def service_get_ticket_by_id(ticket_id: int) -> TicketOutSchema
async def service_delete_ticket(ticket_id: int) -> None
async def service_get_all_tickets() -> List[TicketOutSchema]

依赖关系

• 数据模型: Ticket 模型
• 数据模式: TicketInSchema, TicketOutSchema
• 异常处理: tortoise.exceptions.DoesNotExist, IntegrityError
• HTTP异常: fastapi.HTTPException

4. 工件服务 (Workpiece Service)

文件引用: workpiece_service.py

功能概述

工件服务管理邮轮穿舱件的核心业务对象，支持工件的全生命周期管理。

核心接口

async def service_create_workpiece(inspect_reference: int = 0, maintainance_reference: int = 0, created_by: int = -1) -> Workpiece
async def service_get_workpiece_by_id(workpiece_id: int) -> Optional[Workpiece]
async def service_get_all_workpieces(skip: int = 0, limit: int = 100) -> List[Workpiece]
async def service_update_workpiece(workpiece_id: int, inspect_reference: Optional[int] = None, maintainance_reference: Optional[int] = None, updated_by: int = -1) -> Optional[Workpiece]
async def service_delete_workpiece(workpiece_id: int) -> bool
async def service_get_workpieces_by_inspect_reference(inspect_reference: int) -> List[Workpiece]
async def service_get_workpieces_by_maintainance_reference(maintainance_reference: int) -> List[Workpiece]
async def service_update_workpiece_status(workpiece_id: int, updated_status: int, updated_by: int = -1) -> Optional[Workpiece]

依赖关系

• 数据模型: Workpiece 模型
• 异常处理: tortoise.exceptions.DoesNotExist, IntegrityError
• HTTP异常: fastapi.HTTPException
• 日志系统: app.core.loggers.logger

5. 工件信息服务 (Workpiece Info Service)

文件引用: workpiece_info_service.py

功能概述

工件信息服务使用MongoDB存储工件的详细信息，支持复杂的查询和扩展属性。

核心接口

async def service_create_workpiece_info(workpiece_info_data: WorkpieceInfoSchemaIn) -> WorkpieceInfo
async def service_get_workpiece_info_by_wp_id(wp_id: str) -> Optional[WorkpieceInfo]
async def service_get_all_workpiece_infos(skip: int = 0, limit: int = 100) -> List[WorkpieceInfo]
async def service_update_workpiece_info(wp_id: str, update_data: WorkpieceInfoSchemaUpdate) -> Optional[WorkpieceInfo]
async def service_delete_workpiece_info(wp_id: str) -> bool
async def service_search_workpiece_infos_by_code(firestop_code: str) -> List[WorkpieceInfo]
async def service_get_workpiece_info_by_id(workpiece_info_id: str) -> Optional[WorkpieceInfo]

依赖关系

• 数据模型: WorkpieceInfo MongoDB模型
• 数据模式: WorkpieceInfoSchemaIn, WorkpieceInfoSchemaOut, WorkpieceInfoSchemaUpdate
• 数据库: MongoDB通过 bson.ObjectId
• HTTP异常: fastapi.HTTPException

6. 图片服务 (Image Service)

文件引用: image_service.py

功能概述

图片服务管理系统的图片上传、存储、搜索和与工件的绑定关系。

核心接口

async def service_delete_image_entity_by_id(image_id: int)
async def service_get_image_entity_by_key_or_image_id(key: str = None, image_id: int = None)
async def service_upload_new_image(image: UploadFile = File(...)) -> dict
async def service_get_unbind_images() -> List[int]
async def service_get_images_by_workpiece_id(workpiece_id: int) -> List[Image]
async def service_bind_image_to_workpiece(image_id: int, workpiece_id: int) -> dict
async def service_unbind_image_to_workpiece(image_id: int, workpiece_id: int)
async def service_search_image_sdk_with_key(key: str) -> dict
async def service_search_image_sdk_with_id(image_id: int) -> dict

依赖关系

• 数据模型: Image, ImageMapping, Workpiece
• 图片处理: app.lib.cvcore 计算机视觉核心库
• 文件上传: fastapi.UploadFile, File
• 工具函数: app.core.util.gen_pic_name, gen_product_id

图片处理流程图

flowchart LR
    A[图片上传] --> B[CV Core处理]
    B --> C[生成文件Key]
    C --> D[保存图片实体]
    D --> E{绑定操作}
    E -->|绑定| F[生成产品ID]
    E -->|搜索| G[图片搜索]
    F --> H[SDK绑定调用]
    H --> I[创建映射关系]
    G --> J[返回搜索结果]

7. 图片映射服务 (Image Mapping Service)

文件引用: image_mapping_service.py

功能概述

图片映射服务管理图片与工件之间的多对多关系，支持灵活的绑定和解绑操作。

核心接口

async def service_create_image_mapping(workpiece_id: int, image_id: int, created_by: int = -1) -> ImageMapping
async def service_get_image_mapping_by_id(mapping_id: int) -> Optional[ImageMapping]
async def service_get_all_image_mappings(skip: int = 0, limit: int = 100) -> List[ImageMapping]
async def service_get_image_mappings_by_workpiece(workpiece_id: int) -> List[ImageMapping]
async def service_get_image_mappings_by_image(image_id: int) -> List[ImageMapping]
async def service_get_image_ids_by_workpiece(workpiece_id: int) -> List[int]
async def service_get_workpiece_ids_by_image(image_id: int) -> List[int]
async def service_delete_image_mapping(mapping_id: int) -> bool
async def service_delete_image_mapping_by_workpiece_and_image(workpiece_id: int, image_id: int) -> bool
async def service_delete_all_mappings_by_workpiece(workpiece_id: int) -> int
async def service_delete_all_mappings_by_image(image_id: int) -> int

依赖关系

• 数据模型: ImageMapping 模型
• 异常处理: tortoise.exceptions.DoesNotExist, IntegrityError
• HTTP异常: fastapi.HTTPException

8. 访问日志服务 (Access Log Service)

文件引用: access_log_service.py

功能概述

访问日志服务记录系统的所有操作日志，支持审计和监控功能。

核心接口

async def service_create_access_log(action_type: str, action_title: str, action_description: str = "", related_users: str = "", related_tickets: str = "", related_workpieces: str = "", created_by: int = -1) -> AccessLog
async def service_get_access_log_by_id(log_id: int) -> Optional[AccessLog]
async def service_get_log_count() -> int
async def service_get_all_access_logs(skip: int = 0, limit: int = 100) -> List[AccessLog]
async def service_get_access_logs_by_action_type(action_type: str, skip: int = 0, limit: int = 100) -> List[AccessLog]
async def service_get_access_logs_by_user(user_id: int, skip: int = 0, limit: int = 100) -> List[AccessLog]
async def service_update_access_log(log_id: int, action_type: Optional[str] = None, action_title: Optional[str] = None, action_description: Optional[str] = None, related_users: Optional[str] = None, related_tickets: Optional[str] = None, related_workpieces: Optional[str] = None, updated_by: int = -1) -> Optional[AccessLog]
async def service_delete_access_log(log_id: int) -> bool
async def service_search_access_logs_by_keyword(keyword: str, skip: int = 0, limit: int = 100) -> List[AccessLog]

依赖关系

• 数据模型: AccessLog 模型
• 异常处理: tortoise.exceptions.DoesNotExist, IntegrityError
• HTTP异常: fastapi.HTTPException

服务层架构模式分析

1. 依赖注入模式

所有服务组件都遵循依赖注入原则，通过参数传递依赖对象，提高代码的可测试性和可维护性。

2. 异常处理统一模式

try:
    # 业务逻辑
    result = await model_operation()
    logger.info("操作成功")
    return result
except DoesNotExist:
    logger.warning("资源不存在")
    return None
except IntegrityError:
    logger.error("数据完整性错误")
    raise HTTPException(status_code=400, detail="操作失败")
except Exception as e:
    logger.error(f"未知错误: {e}")
    raise HTTPException(status_code=500, detail="服务器内部错误")

3. 日志记录模式

所有服务操作都包含详细的日志记录，支持操作审计和故障排查。

4. 数据验证模式

服务层负责业务规则验证，确保数据的完整性和一致性。

服务组件交互关系图

flowchart TD
    subgraph 前端层
        A[Web界面]
        B[移动端]
        C[API客户端]
    end
    
    subgraph 路由层
        D[用户路由]
        E[工单路由]
        F[工件路由]
        G[图片路由]
    end
    
    subgraph 服务层
        H[用户服务]
        I[工单服务]
        J[工件服务]
        K[图片服务]
        L[权限服务]
        M[日志服务]
    end
    
    subgraph 数据层
        N[关系数据库]
        O[MongoDB]
        P[文件存储]
    end
    
    A --> D
    B --> D
    C --> D
    
    D --> H
    E --> I
    F --> J
    G --> K
    
    H --> N
    I --> N
    J --> N
    K --> P
    J --> O
    
    H --> L
    H --> M
    I --> M
    J --> M
    K --> M

性能优化建议

1. 数据库查询优化

• 使用适当的索引优化频繁查询的字段
• 实现分页查询避免大数据量传输
• 使用select_related预加载关联数据

2. 缓存策略

• 对频繁访问的用户信息实现缓存
• 对权限数据使用内存缓存
• 对图片元数据使用Redis缓存

3. 异步处理

• 所有服务方法都使用async/await模式
• 耗时的图片处理操作使用后台任务
• 日志记录使用异步写入

索引

邮轮穿舱件管理系统的服务层设计遵循了现代软件架构的最佳实践，具有清晰的职责分离、完善的错误处理机制和良好的可扩展性。通过分析可以看出，系统采用了模块化设计，各服务组件职责明确，依赖关系清晰，为系统的稳定运行和后续扩展奠定了坚实基础。

参考文件列表:

• access_log_service.py
• user_service.py
• role_service.py
• ticket_service.py
• workpiece_service.py
• workpiece_info_service.py
• image_service.py
• image_mapping_service.py