邮轮穿舱件管理系统后台 - 核心组件文档

概述

邮轮穿舱件管理系统后台是一个基于FastAPI框架构建的企业级管理系统，专门用于邮轮穿舱件的全生命周期管理。系统采用模块化设计，包含用户管理、权限控制、工单管理、图像处理等核心业务功能。

参考文件:

• README.md

系统架构

整体架构图

flowchart TD
    subgraph 前端层
        A1[桌面端应用]
        A2[微信小程序]
        A3[巡检设备]
        A4[维修设备]
    end
    
    subgraph API网关层
        B[FastAPI应用]
    end
    
    subgraph 业务逻辑层
        C1[用户管理服务]
        C2[权限控制服务]
        C3[工单管理服务]
        C4[图像处理服务]
        C5[工件管理服务]
    end
    
    subgraph 数据访问层
        D1[用户模型]
        D2[角色模型]
        D3[工单模型]
        D4[图像模型]
        D5[工件模型]
    end
    
    subgraph 数据存储层
        E1[PostgreSQL数据库]
        E2[对象存储OSS]
    end
    
    A1 --> B
    A2 --> B
    A3 --> B
    A4 --> B
    B --> C1
    B --> C2
    B --> C3
    B --> C4
    B --> C5
    C1 --> D1
    C2 --> D2
    C3 --> D3
    C4 --> D4
    C5 --> D5
    D1 --> E1
    D2 --> E1
    D3 --> E1
    D4 --> E1
    D5 --> E1
    C4 --> E2

核心模块依赖关系

flowchart TD
    subgraph 核心模块
        M1[app/main.py]
        M2[app/core/]
        M3[app/models/]
        M4[app/routers/]
        M5[app/service/]
        M6[app/schemas/]
    end
    
    subgraph 核心组件
        C1[用户管理]
        C2[权限控制]
        C3[工单管理]
        C4[图像处理]
        C5[工件管理]
    end
    
    M1 --> M2
    M1 --> M4
    M2 --> M3
    M4 --> M5
    M5 --> M3
    M4 --> M6
    M5 --> M6
    
    C1 --> M3/user.py
    C1 --> M5/user_service.py
    C1 --> M4/user_router.py
    C2 --> M2/authorize.py
    C2 --> M3/role.py
    C3 --> M3/ticket.py
    C3 --> M5/ticket_service.py
    C4 --> M3/image.py
    C4 --> M5/image_service.py
    C5 --> M3/workpiece.py
    C5 --> M5/workpiece_service.py

1. 用户管理模块

1.1 用户数据模型

用户实体类定义：

class User(Model):
    id = fields.IntField(primary_key=True)
    username = fields.CharField(max_length=255, unique=True, null=False)
    password = fields.CharField(max_length=511, null=False)
    email = fields.CharField(max_length=255, unique=True, null=True)
    sms = fields.CharField(max_length=255, null=True)
    status = fields.CharField(max_length=255, default=UserStatus.ACTIVE.value)
    openid = fields.CharField(max_length=255, null=True)
    is_system = fields.BooleanField(default=False)
    created_by = fields.IntField(null=True, default=-1)
    updated_by = fields.IntField(null=True, default=-1)
    created_at = fields.DatetimeField(auto_now_add=True)
    updated_at = fields.DatetimeField(auto_now=True)

用户状态枚举：

class UserStatus(Enum):
    ACTIVE = "active"      # 活跃状态
    INACTIVE = "inactive"  # 非活跃状态
    SUSPENDED = "suspended" # 暂停状态
    DELETED = "deleted"    # 删除状态

参考文件:

• app/models/user.py

1.2 用户服务层

核心服务功能：

flowchart TD
    A[用户请求] --> B[用户服务层]
    B --> C1[创建用户]
    B --> C2[查询用户]
    B --> C3[更新用户]
    B --> C4[删除用户]
    B --> C5[用户认证]
    B --> C6[状态管理]
    
    C1 --> D1[密码哈希]
    C1 --> D2[唯一性校验]
    C2 --> D3[多条件查询]
    C3 --> D4[数据验证]
    C5 --> D5[密码验证]
    C5 --> D6[状态检查]

密码安全机制：

• 使用bcrypt算法进行密码哈希
• 自动生成盐值增强安全性
• 支持密码验证功能

参考文件:

• app/service/user_service.py

1.3 用户API接口

用户路由配置：

user_router = APIRouter(
    prefix="/users", 
    tags=["用户管理"], 
    dependencies=[Depends(require_scopes(["system:read"], mode="AND")), Depends(verify_jwt_token)], 
)

API接口列表：

方法	路径	功能	权限要求
POST	/users/	创建用户	system:write
POST	/users/register	用户注册	无
GET	/users/	获取用户列表	system:read
GET	/users/{user_id}	根据ID获取用户	system:read
GET	/users/username/{username}	根据用户名获取用户	system:read
PUT	/users/{user_id}	更新用户信息	system:write
DELETE	/users/{user_id}	删除用户	system:write
PATCH	/users/{user_id}/status	修改用户状态	system:write
POST	/users/authenticate	用户认证	无

参考文件:

• app/routers/user_router.py

2. 权限控制模块

2.1 JWT认证机制

令牌创建流程：

sequenceDiagram
    participant U as 用户
    participant A as 认证服务
    participant J as JWT服务
    
    U->>A: 提交凭据
    A->>J: 请求创建令牌
    J->>J: 生成过期时间
    J->>J: 编码用户数据
    J->>A: 返回访问令牌
    A->>U: 返回认证结果

令牌验证流程：

sequenceDiagram
    participant U as 用户
    participant A as API网关
    participant J as JWT服务
    participant P as 权限服务
    
    U->>A: 携带令牌请求
    A->>J: 验证令牌有效性
    J->>J: 解码令牌数据
    J->>P: 获取用户权限
    P->>A: 返回权限信息
    A->>U: 返回请求结果

2.2 权限作用域系统

权限作用域定义：

作用域	描述	适用角色
workpiece:read	读取工件信息	所有角色
workpiece:write	写入工件信息	桌面端、小程序
task:read	读取任务信息	所有角色
task:write	写入任务信息	桌面端、小程序
image:read	读取图像信息	所有角色
image:write	写入图像信息	桌面端、小程序
system:read	读取系统信息	桌面端
system:write	写入系统信息	桌面端
inspect:access	巡检接入	巡检用户
maintenance:access	维修接入	维修用户
miniapp:access	小程序接入	小程序用户

角色权限映射：

ROLE_SCOPES = {
    "desktop": SCOPE.keys(),  # 桌面端拥有所有权限
    "miniapp": ["workpiece:read", "workpiece:write", "task:read", "task:write", "image:read", "image:write", "miniapp:access"],
    "inspect": ["inspect:access"],
    "maintenance": ["maintenance:access"],
}

参考文件:

• app/core/authorize.py

2.3 权限验证机制

作用域检查函数：

def require_scopes(scopes: list[str], mode: Literal["AND","OR"]="AND") -> Callable:
    """
    依赖项，用于检查 JWT 令牌是否包含指定的作用域
    """
    # AND模式：需要包含所有指定作用域
    # OR模式：只需包含其中一个作用域

使用示例：

# 路由级别权限控制
dependencies=[Depends(require_scopes(["system:read"], mode="AND"))]

# 函数级别权限控制
current_user=Depends(require_scopes(["system:write"], mode="AND"))

参考文件:

• app/core/authorize.py

3. 工单管理模块

3.1 工单数据模型

工单实体类定义：

class Ticket(Model):    
    ticket_id = fields.IntField(primary_key=True)
    ticket_type = fields.CharField(max_length=255, default="任务工单")
    ticket_status = fields.CharField(max_length=255, default="未开始")
    target_workpiece = fields.IntField(null=True, default=-1)
    ticket_from = fields.CharField(max_length=255, default="")
    ticket_tos = fields.CharField(max_length=255, default="")
    ticket_content = fields.TextField(null=True, default="")
    ticket_title = fields.CharField(max_length=255, default="")
    feedback_text = fields.TextField(null=True, default="")
    image_list = fields.CharField(max_length=1025, default="")
    reference_list = fields.CharField(max_length=1025, default="")
    created_by = fields.IntField(null=True, default=-1)
    updated_by = fields.IntField(null=True, default=-1)
    created_at = fields.DatetimeField(auto_now_add=True)
    updated_at = fields.DatetimeField(auto_now=True)

工单核心字段说明：

字段	类型	描述
ticket_type	String	工单类型（任务工单、维护工单等）
ticket_status	String	工单状态（未开始、进行中、已完成等）
target_workpiece	Int	关联的目标工件ID
image_list	String	关联的图片列表（JSON格式）
reference_list	String	引用工单列表

参考文件:

• app/models/ticket.py

3.2 工单业务流程

工单状态流转图：

stateDiagram-v2
    [*] --> 未开始
    未开始 --> 进行中 : 分配任务
    进行中 --> 已完成 : 完成任务
    进行中 --> 已暂停 : 暂停任务
    已暂停 --> 进行中 : 恢复任务
    进行中 --> 已取消 : 取消任务
    已完成 --> [*] : 归档
    已取消 --> [*] : 关闭

4. 图像处理模块

4.1 图像数据模型

图像实体类定义：

class Image(Model):
    id = fields.IntField(pk=True)
    key = fields.CharField(max_length=255)  # OSS存储键
    created_by = fields.IntField(null=True, default=-1)
    updated_by = fields.IntField(null=True, default=-1)
    created_at = fields.DatetimeField(auto_now_add=True)
    updated_at = fields.DatetimeField(auto_now=True)

图像处理流程：

flowchart LR
    A[图像上传] --> B[OSS存储]
    B --> C[元数据记录]
    C --> D[图像分析]
    D --> E[结果存储]
    E --> F[工单关联]

4.2 计算机视觉集成

CV核心配置：

cvc_target_url: str = Field(default="http://localhost:8000")
cvc_api_key: str = Field(default="abc")

系统集成计算机视觉核心服务，用于图像分析和缺陷检测。

参考文件:

• app/core/settings.py

5. 工件管理模块

5.1 工件数据模型

工件实体类定义：

class Workpiece(Model):
    workpiece_id = fields.IntField(primary_key=True)
    workpiece_status = fields.IntField(null=True, default=0)
    inspect_reference = fields.IntField(null=True, default=0)
    maintainance_reference = fields.IntField(null=True, default=0)
    created_by = fields.IntField(null=True, default=-1)
    updated_by = fields.IntField(null=True, default=-1)
    created_at = fields.DatetimeField(auto_now_add=True)
    updated_at = fields.DatetimeField(auto_now=True)

工件状态管理：

• workpiece_status: 工件当前状态
• inspect_reference: 关联的巡检工单
• maintainance_reference: 关联的维护工单

参考文件:

• app/models/workpiece.py

6. 系统配置模块

6.1 环境配置管理

配置加载机制：

class Settings(BaseSettings):
    env: str = Field("development", alias="ENV")
    
    @model_validator(mode="after")
    def _set_application_attributes(self) -> Self:
        with open(f".config/{self.env}.application.json", "r") as f:
            attributes = json.load(f)
        # 加载应用配置

多环境支持：

• development: 开发环境
• staging: 测试环境
• production: 生产环境

参考文件:

• app/core/settings.py

6.2 微信小程序集成

微信配置：

wechat_appid: str | None = Field(default=None, alias="WECHAT_APPID")
wechat_secret: str | None = Field(default=None, alias="WECHAT_SECRET")

支持微信小程序用户认证和业务集成。

7. 数据流分析

7.1 用户认证数据流

sequenceDiagram
    participant C as 客户端
    participant R as 路由层
    participant S as 服务层
    participant M as 模型层
    participant D as 数据库
    
    C->>R: POST /users/authenticate
    R->>S: service_authenticate_user()
    S->>M: User.filter()
    M->>D: 查询用户
    D->>M: 返回用户数据
    M->>S: 用户对象
    S->>S: 密码验证
    S->>R: 认证结果
    R->>C: JWT令牌

7.2 工单创建数据流

sequenceDiagram
    participant C as 客户端
    participant R as 工单路由
    participant S as 工单服务
    participant M as 工单模型
    participant D as 数据库
    participant L as 日志服务
    
    C->>R: POST /tickets/
    R->>L: 记录访问日志
    R->>S: service_create_ticket()
    S->>M: Ticket.create()
    M->>D: 插入工单记录
    D->>M: 返回工单ID
    M->>S: 工单对象
    S->>R: 创建结果
    R->>C: 工单信息

8. 性能优化考虑

8.1 数据库优化

• 使用索引优化常用查询字段
• 分页查询避免大数据量加载
• 连接池管理数据库连接

8.2 缓存策略

• JWT令牌缓存验证结果
• 频繁访问数据缓存
• 图像处理结果缓存

8.3 安全考虑

• BCrypt密码哈希算法
• JWT令牌过期机制
• 权限最小化原则
• 输入数据验证和清理

索引

邮轮穿舱件管理系统后台采用分层架构设计，各模块职责清晰，通过完善的权限控制机制确保系统安全。系统支持多端接入（桌面端、小程序、巡检设备、维修设备），具备完整的用户管理、工单管理、图像处理等核心业务功能。

核心优势：

1. 模块化设计 - 各功能模块独立，便于维护和扩展
2. 权限精细控制 - 基于作用域的权限管理系统
3. 多端支持 - 支持不同类型客户端的接入
4. 安全可靠 - 完善的认证授权机制
5. 可扩展性 - 易于集成新的业务功能

系统为邮轮穿舱件的全生命周期管理提供了坚实的技术支撑，能够有效提升管理效率和工作质量。