跳到主要内容

邮轮穿舱件管理系统后台 - 系统定制指南

概述​

本文档详细说明如何根据具体需求定制邮轮穿舱件管理系统的功能和界面。该系统基于FastAPI框架构建，采用模块化架构设计，支持灵活的定制和扩展。

系统架构分析​

整体架构图​

flowchart TD
    subgraph 前端层
        A[Web界面]
        B[微信小程序]
        C[移动端应用]
    end
    
    subgraph API网关层
        D[FastAPI应用]
        E[认证中间件]
        F[异常处理]
    end
    
    subgraph 业务逻辑层
        G[用户服务]
        H[工件管理]
        I[工单系统]
        J[图像处理]
    end
    
    subgraph 数据访问层
        K[用户模型]
        L[工件模型]
        M[工单模型]
        N[图像模型]
    end
    
    subgraph 数据存储层
        O[PostgreSQL]
        P[文件存储]
        Q[缓存系统]
    end
    
    A --> D
    B --> D
    C --> D
    D --> E
    E --> F
    F --> G
    F --> H
    F --> I
    F --> J
    G --> K
    H --> L
    I --> M
    J --> N
    K --> O
    L --> O
    M --> O
    N --> P
    D --> Q

核心组件依赖关系​

flowchart TD
    A[app/main.py] --> B[app/core/settings.py]
    A --> C[app/routers/]
    A --> D[app/service/]
    A --> E[app/models/]
    
    C --> F[用户路由]
    C --> G[工件路由]
    C --> H[工单路由]
    C --> I[图像路由]
    
    D --> J[用户服务]
    D --> K[工件服务]
    D --> L[工单服务]
    D --> M[图像服务]
    
    E --> N[用户模型]
    E --> O[工件模型]
    E --> P[工单模型]
    E --> Q[图像模型]
    
    F --> J
    G --> K
    H --> L
    I --> M
    
    J --> N
    K --> O
    L --> P
    M --> Q

用户管理模块定制​

用户模型结构​

classDiagram
    class User {
        +IntField id
        +CharField username
        +CharField password
        +CharField email
        +CharField sms
        +CharField status
        +CharField openid
        +BooleanField is_system
        +IntField created_by
        +IntField updated_by
        +DatetimeField created_at
        +DatetimeField updated_at
    }
    
    class UserStatus {
        <<enumeration>>
        ACTIVE
        INACTIVE
        SUSPENDED
        DELETED
    }
    
    User --> UserStatus : 状态关联

参考文件：

用户服务定制​

1. 密码加密定制​

系统使用bcrypt进行密码加密，可在app/service/user_service.py中修改加密算法：

def service_util_hash_password(password: str) -> str:
    """
    密码哈希工具函数
    """
    salt = bcrypt.gensalt()
    hashed = bcrypt.hashpw(password.encode('utf-8'), salt)
    return hashed.decode('utf-8')

参考文件：

2. 用户认证流程定制​

sequenceDiagram
    participant Client
    participant Router
    participant Service
    participant Model
    
    Client->>Router: POST /users/authenticate
    Router->>Service: service_authenticate_user()
    Service->>Model: 查询用户(用户名/邮箱/手机)
    Model-->>Service: 返回用户信息
    Service->>Service: 验证密码
    Service->>Service: 检查用户状态
    Service-->>Router: 返回认证结果
    Router-->>Client: 返回用户信息或错误

参考文件：

用户路由定制​

1. 权限控制定制​

系统使用JWT令牌和权限范围控制，可在路由中修改权限要求：

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

参考文件：

2. API端点定制​

系统提供完整的CRUD操作，支持以下定制：

  • 创建用户：可添加自定义验证逻辑
  • 用户注册：支持自主注册流程
  • 用户查询：支持分页和条件查询
  • 用户更新：支持部分更新
  • 用户删除：软删除或硬删除
  • 状态管理：支持多种用户状态

参考文件：

配置系统定制​

环境配置架构​

classDiagram
    class Settings {
        +str env
        +str application_debug
        +str application_name
        +str application_version
        +str application_description
        +str JWT_SECRET_KEY
        +str JWT_ALGORITHM
        +int JWT_ACCESS_EXPIRE_MINUTES
        +str wechat_appid
        +str wechat_secret
        +dict tortoise_orm_config_dict
        +str cvc_target_url
        +str cvc_api_key
        +_set_application_attributes()
        +_set_wechat_config_attributes()
    }
    
    class BaseSettings {
        <<abstract>>
    }
    
    Settings --|> BaseSettings

参考文件：

配置文件定制​

系统支持多环境配置，通过JSON文件管理：

  1. 应用配置：.config/{env}.application.json
  2. 微信配置：.config/{env}.wechat.json
  3. 数据库配置：.config/{env}.database.json

参考文件：

功能模块扩展指南​

1. 添加新业务模块​

步骤1：创建数据模型​

在app/models/目录下创建新的模型文件：

from tortoise import Model, fields

class NewModule(Model):
    id = fields.IntField(primary_key=True)
    name = fields.CharField(max_length=255)
    # 其他字段...
    
    class Meta:
        table = "new_module"

步骤2：创建Schema定义​

在app/schemas/目录下创建对应的Schema：

from pydantic import BaseModel

class NewModuleSchemaIn(BaseModel):
    name: str
    # 其他输入字段...

class NewModuleSchemaOut(BaseModel):
    id: int
    name: str
    # 其他输出字段...

步骤3：创建业务服务​

在app/service/目录下创建服务文件：

from app.models.new_module import NewModule
from app.schemas.new_module_schema import NewModuleSchemaIn, NewModuleSchemaOut

async def service_create_new_module(data: NewModuleSchemaIn) -> NewModuleSchemaOut:
    # 业务逻辑实现
    pass

步骤4：创建路由​

在app/routers/目录下创建路由文件：

from fastapi import APIRouter

new_module_router = APIRouter(prefix="/new-module", tags=["新模块"])

@new_module_router.post("/")
async def api_create_new_module():
    # API实现
    pass

步骤5：注册路由​

在app/main.py中注册新路由：

from app.routers.new_module_router import new_module_router

app.include_router(new_module_router)

参考文件：

2. 界面定制方案​

前端架构适配​

系统采用前后端分离架构，支持多种前端技术栈：

  • React/Vue/Angular：通过RESTful API集成
  • 微信小程序：已有完整支持
  • 移动端应用：基于标准HTTP接口

API文档生成​

系统自动生成OpenAPI文档，支持前端开发：

# 访问API文档
http://localhost:8001/docs

3. 权限系统扩展​

角色权限模型​

系统支持基于角色的权限控制：

classDiagram
    class User {
        +username
        +password
        +roles
    }
    
    class Role {
        +name
        +permissions
    }
    
    class Permission {
        +scope
        +description
    }
    
    User "1" -- "*" Role : 拥有
    Role "1" -- "*" Permission : 包含

定制建议：

  • 在app/models/role.py中扩展权限定义
  • 在app/core/authorize.py中修改权限验证逻辑

部署和运维定制​

1. 数据库迁移定制​

系统使用Aerich进行数据库迁移管理：

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

# 模型更新
aerich migrate
aerich upgrade

参考文件：

2. Docker部署定制​

修改Dockerfile适应特定部署环境：

FROM python:3.11-slim

# 安装依赖
COPY requirements.txt .
RUN pip install -r requirements.txt

# 复制应用代码
COPY app/ /app/app/
COPY main.py /app/

# 设置工作目录
WORKDIR /app

# 启动命令
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

性能优化建议​

1. 数据库优化​

  • 为常用查询字段添加索引
  • 使用数据库连接池
  • 实现查询缓存机制

2. API性能优化​

  • 实现分页查询
  • 使用异步处理
  • 添加响应缓存

3. 安全加固​

  • 定期更换JWT密钥
  • 实现请求频率限制
  • 添加输入验证和消毒

索引​

邮轮穿舱件管理系统采用模块化设计，支持灵活的定制和扩展。通过本文档的指导，您可以：

  1. 快速理解系统架构：掌握核心组件和依赖关系
  2. 定制业务功能：根据需求添加或修改功能模块
  3. 调整界面交互：适配不同的前端技术栈
  4. 优化系统性能：实施性能监控和优化措施
  5. 确保系统安全：加强安全防护和权限控制

系统具有良好的可扩展性和维护性，能够满足不同场景下的定制需求。

主要参考文件：