邮轮穿舱件管理系统后台 - 高级主题

目录

• 系统架构概述
• 核心功能模块
• 定制开发指南
• 系统架构图
• 数据模型关系
• API路由架构
• 高级功能实现
• 性能优化建议

系统架构概述

邮轮穿舱件管理系统是一个基于FastAPI构建的现代化Web应用，采用分层架构设计，支持多环境配置和模块化开发。系统集成了用户管理、工单处理、工件跟踪、图像管理等功能模块。

核心架构特点：

• FastAPI框架：高性能异步Web框架
• Tortoise-ORM：异步ORM支持多种数据库
• JWT认证：基于令牌的身份验证机制
• 多环境配置：支持开发、测试、生产环境
• 模块化设计：清晰的业务边界和职责分离

参考文件：

• app/main.py
• app/core/settings.py

核心功能模块

1. 用户管理模块

提供完整的用户生命周期管理，包括注册、认证、权限控制和状态管理。

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
        +authenticate()
        +change_status()
    }
    
    class UserService {
        +create_user()
        +get_user_by_id()
        +get_user_by_username()
        +update_user()
        +delete_user()
        +authenticate_user()
        +hash_password()
        +verify_password()
    }
    
    class UserRouter {
        +api_create_user()
        +api_register_user()
        +api_get_users()
        +api_get_user_by_id()
        +api_update_user()
        +api_delete_user()
        +api_authenticate_user()
    }
    
    UserService --> User : 操作
    UserRouter --> UserService : 调用

参考文件：

• app/models/user.py
• app/service/user_service.py
• app/routers/user_router.py

2. 工件管理模块

管理邮轮穿舱件的核心业务数据，支持状态跟踪和关联工单。

classDiagram
    class Workpiece {
        +IntField workpiece_id
        +IntField workpiece_status
        +IntField inspect_reference
        +IntField maintainance_reference
        +IntField created_by
        +IntField updated_by
        +DatetimeField created_at
        +DatetimeField updated_at
    }
    
    class WorkpieceService {
        +create_workpiece()
        +get_workpiece_by_id()
        +update_workpiece_status()
        +get_workpiece_list()
    }

参考文件：

• app/models/workpiece.py

3. 工单管理模块

处理业务流程中的各种工单，支持工单流转和状态管理。

classDiagram
    class Ticket {
        +IntField ticket_id
        +CharField ticket_type
        +CharField ticket_status
        +IntField target_workpiece
        +CharField ticket_from
        +CharField ticket_tos
        +TextField ticket_content
        +CharField ticket_title
        +TextField feedback_text
        +CharField image_list
        +CharField reference_list
        +IntField created_by
        +IntField updated_by
        +DatetimeField created_at
        +DatetimeField updated_at
    }

参考文件：

• app/models/ticket.py

定制开发指南

1. 新增业务模块开发流程

步骤1：创建数据模型

# app/models/your_module.py
from tortoise import Model, fields

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

步骤2：创建Schema定义

# app/schemas/your_schema.py
from pydantic import BaseModel
from typing import Optional

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

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

步骤3：创建业务服务层

# app/service/your_service.py
from app.models.your_module import YourModel
from app.schemas.your_schema import YourSchemaIn, YourSchemaOut

async def service_create_your_model(data: YourSchemaIn) -> YourSchemaOut:
    # 业务逻辑实现
    pass

步骤4：创建API路由

# app/routers/your_router.py
from fastapi import APIRouter, Depends
from app.service.your_service import service_create_your_model
from app.schemas.your_schema import YourSchemaIn, YourSchemaOut

your_router = APIRouter(prefix="/your", tags=["你的模块"])

@your_router.post("/", response_model=YourSchemaOut)
async def api_create_your_model(data: YourSchemaIn):
    return await service_create_your_model(data)

步骤5：注册路由到主应用

# app/main.py 中添加
from app.routers.your_router import your_router
app.include_router(your_router)

2. 配置管理定制

系统支持多环境配置，通过JSON文件管理不同环境的配置参数：

flowchart TD
    A[环境变量 ENV] --> B{环境类型}
    B -->|development| C[读取 .config/development.*.json]
    B -->|staging| D[读取 .config/staging.*.json]
    B -->|production| E[读取 .config/production.*.json]
    C --> F[应用配置]
    D --> F
    E --> F

参考文件：

• app/core/settings.py

系统架构图

整体架构视图

flowchart TD
    subgraph 前端层
        A[Web界面]
        B[移动端应用]
        C[微信小程序]
    end
    
    subgraph API网关层
        D[FastAPI应用]
        E[认证中间件]
        F[异常处理]
    end
    
    subgraph 业务服务层
        G[用户服务]
        H[工件服务]
        I[工单服务]
        J[图像服务]
    end
    
    subgraph 数据访问层
        K[Tortoise ORM]
        L[数据库]
    end
    
    A --> D
    B --> D
    C --> D
    D --> E
    E --> F
    F --> G
    F --> H
    F --> I
    F --> J
    G --> K
    H --> K
    I --> K
    J --> K
    K --> L

请求处理流程

sequenceDiagram
    participant C as 客户端
    participant A as API网关
    participant M as 中间件
    participant S as 业务服务
    participant D as 数据库
    
    C->>A: HTTP请求
    A->>M: 请求预处理
    M->>M: JWT认证
    M->>M: 权限验证
    M->>S: 路由到业务服务
    S->>D: 数据库操作
    D->>S: 返回数据
    S->>M: 业务处理结果
    M->>A: 响应封装
    A->>C: HTTP响应

参考文件：

• app/main.py
• app/core/middleware.py

数据模型关系

实体关系图

erDiagram
    USER ||--o{ WORKPIECE : creates
    USER ||--o{ TICKET : creates
    USER ||--o{ ACCESS_LOG : generates
    WORKPIECE ||--o{ TICKET : references
    TICKET ||--o{ IMAGE : contains
    
    USER {
        int id PK
        string username
        string password
        string email
        string status
        string openid
        boolean is_system
        int created_by
        int updated_by
        datetime created_at
        datetime updated_at
    }
    
    WORKPIECE {
        int workpiece_id PK
        int workpiece_status
        int inspect_reference
        int maintainance_reference
        int created_by
        int updated_by
        datetime created_at
        datetime updated_at
    }
    
    TICKET {
        int ticket_id PK
        string ticket_type
        string ticket_status
        int target_workpiece FK
        string ticket_from
        string ticket_tos
        text ticket_content
        string ticket_title
        text feedback_text
        string image_list
        string reference_list
        int created_by
        int updated_by
        datetime created_at
        datetime updated_at
    }

API路由架构

路由组织结构

flowchart TD
    A[FastAPI应用] --> B[认证路由]
    A --> C[用户管理路由]
    A --> D[工件管理路由]
    A --> E[工单管理路由]
    A --> F[图像管理路由]
    A --> G[微信小程序路由]
    A --> H[统计路由]
    A --> I[日志路由]
    
    B --> B1[登录]
    B --> B2[令牌验证]
    
    C --> C1[用户CRUD]
    C --> C2[用户状态管理]
    C --> C3[用户认证]
    
    D --> D1[工件CRUD]
    D --> D2[工件状态跟踪]
    
    E --> E1[工单CRUD]
    E --> E2[工单流转]
    
    F --> F1[图像上传]
    F --> F2[图像处理]
    
    G --> G1[微信登录]
    G --> G2[小程序API]

参考文件：

• app/main.py
• app/routers/

高级功能实现

1. 密码安全处理

系统采用bcrypt算法进行密码哈希，确保用户密码安全：

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

参考文件：

• app/service/user_service.py

2. JWT认证机制

基于JWT的分布式认证系统，支持多客户端访问：

sequenceDiagram
    participant U as 用户
    participant A as 认证服务
    participant R as 资源服务
    
    U->>A: 用户名/密码登录
    A->>A: 验证凭据
    A->>U: 返回JWT令牌
    U->>R: 携带JWT访问API
    R->>R: 验证JWT有效性
    R->>U: 返回请求数据

3. 访问日志记录

系统自动记录所有API访问日志，支持审计和故障排查：

await service_create_access_log(
    action_type="user_router",
    action_title="创建用户",
    action_description=f"用户 {current_user.get('uid')} 尝试创建新用户",
    related_users=str(g.user_id),
    related_tickets=None,
    related_workpieces=None,
)

参考文件：

• app/routers/user_router.py

性能优化建议

1. 数据库优化

• 索引优化：为常用查询字段创建索引
• 查询优化：使用select_related减少N+1查询问题
• 连接池：配置数据库连接池提高并发性能

2. 缓存策略

• Redis缓存：对热点数据实施缓存策略
• CDN加速：静态资源使用CDN分发
• 浏览器缓存：合理设置HTTP缓存头

3. 异步处理

• 异步IO：充分利用FastAPI的异步特性
• 任务队列：耗时操作使用后台任务处理
• 流式响应：大文件下载使用流式传输

4. 监控和日志

• 性能监控：实现API响应时间监控
• 错误追踪：集成错误追踪系统
• 日志分级：合理配置日志级别减少IO压力

索引

邮轮穿舱件管理系统采用了现代化的技术栈和架构设计，具有良好的可扩展性和维护性。系统通过模块化设计、分层架构和标准化接口，为定制开发提供了清晰的指导框架。

关键优势：

• 清晰的代码组织结构
• 完善的认证授权机制
• 灵活的多环境配置支持
• 完整的日志和监控体系
• 良好的性能优化空间

后续开发建议：

1. 持续完善单元测试覆盖
2. 实施API版本管理策略
3. 建立持续集成/部署流程
4. 加强安全审计和漏洞扫描
5. 优化数据库查询性能

参考文件汇总：

• app/main.py
• app/core/settings.py
• app/models/user.py
• app/models/workpiece.py
• app/models/ticket.py
• app/service/user_service.py
• app/routers/user_router.py