邮轮穿舱件管理系统后台 - 审计模型设计文档

概述

本文档详细记录了邮轮穿舱件管理系统后台的审计和日志相关数据模型设计。系统采用分层架构设计，通过访问日志模型记录用户操作行为，提供完整的审计追踪能力。

目录

1. 数据模型设计
2. 服务层架构
3. API接口设计
4. 日志记录机制
5. 系统架构图
6. 数据流程图
7. 类关系图
8. 性能分析

数据模型设计

AccessLog 访问日志模型

系统核心的审计数据模型，用于记录所有用户操作行为。

erDiagram
    ACCESS_LOG {
        int log_id PK "日志ID"
        string action_type "操作类型"
        string action_title "操作标题"
        string action_description "操作描述"
        string related_users "相关用户"
        string related_tickets "相关工单"
        string related_workpieces "相关工件"
        int created_by "创建人"
        int updated_by "更新人"
        datetime created_at "创建时间"
        datetime updated_at "更新时间"
    }

字段说明：

字段名	类型	约束	描述
log_id	IntField	Primary Key	日志唯一标识符
action_type	CharField(255)	Not Null	操作类型分类
action_title	CharField(255)	Not Null	操作标题
action_description	CharField(255)	Not Null	详细操作描述
related_users	CharField(255)	Nullable	关联用户ID列表
related_tickets	CharField(255)	Nullable	关联工单ID列表
related_workpieces	CharField(255)	Nullable	关联工件ID列表
created_by	IntField	Nullable	记录创建者
updated_by	IntField	Nullable	最后更新者
created_at	DatetimeField	Auto Add	创建时间戳
updated_at	DatetimeField	Auto Update	更新时间戳

参考文件：

• access_log.py

服务层架构

AccessLogService 访问日志服务

提供完整的CRUD操作和查询功能，支持多种检索方式。

classDiagram
    class AccessLogService {
        +service_create_access_log()
        +service_get_access_log_by_id()
        +service_get_all_access_logs()
        +service_get_access_logs_by_action_type()
        +service_get_access_logs_by_user()
        +service_update_access_log()
        +service_delete_access_log()
        +service_search_access_logs_by_keyword()
        +service_get_log_count()
    }
    
    class AccessLog {
        +log_id: int
        +action_type: str
        +action_title: str
        +action_description: str
        +related_users: str
        +related_tickets: str
        +related_workpieces: str
        +created_by: int
        +updated_by: int
        +created_at: datetime
        +updated_at: datetime
    }
    
    AccessLogService --> AccessLog : 操作

服务方法说明：

方法名	参数	返回值	功能描述
service_create_access_log	操作信息	AccessLog	创建新访问日志记录
service_get_access_log_by_id	log_id	Optional[AccessLog]	根据ID查询日志
service_get_all_access_logs	skip, limit	List[AccessLog]	分页获取所有日志
service_get_access_logs_by_action_type	action_type, skip, limit	List[AccessLog]	按操作类型筛选
service_get_access_logs_by_user	user_id, skip, limit	List[AccessLog]	按用户关联查询
service_update_access_log	更新参数	Optional[AccessLog]	更新日志信息
service_delete_access_log	log_id	bool	删除日志记录
service_search_access_logs_by_keyword	keyword, skip, limit	List[AccessLog]	关键词搜索
service_get_log_count	无	int	获取日志总数

参考文件：

• access_log_service.py

API接口设计

日志管理API路由

提供RESTful风格的审计日志查询和管理接口。

sequenceDiagram
    participant Client
    participant LogRouter
    participant AccessLogService
    participant Database
    
    Client->>LogRouter: GET /log/detail/{log_id}
    LogRouter->>AccessLogService: service_get_access_log_by_id(log_id)
    AccessLogService->>Database: SELECT * FROM access_log WHERE log_id=?
    Database-->>AccessLogService: AccessLog对象
    AccessLogService-->>LogRouter: 返回结果
    LogRouter-->>Client: 日志详情
    
    Client->>LogRouter: GET /log/all?skip=0&limit=100
    LogRouter->>AccessLogService: service_get_all_access_logs(skip, limit)
    AccessLogService->>Database: SELECT * FROM access_log ORDER BY created_at DESC
    Database-->>AccessLogService: 日志列表
    AccessLogService-->>LogRouter: 分页结果
    LogRouter-->>Client: 日志列表
    
    Client->>LogRouter: DELETE /log/{log_id}
    LogRouter->>AccessLogService: service_delete_access_log(log_id)
    AccessLogService->>Database: DELETE FROM access_log WHERE log_id=?
    Database-->>AccessLogService: 删除结果
    AccessLogService-->>LogRouter: 操作状态
    LogRouter-->>Client: 删除确认

API端点详情：

端点	方法	参数	描述	认证要求
/log/detail/{log_id}	GET	log_id: int	获取指定日志详情	需要认证
/log/all	GET	skip: int, limit: int	分页获取所有日志	需要认证
/log/type/{action_type}	GET	action_type: str, skip, limit	按操作类型筛选	需要认证
/log/user/{user_id}	GET	user_id: int, skip, limit	按用户查询日志	需要认证
/log/search	GET	keyword: str, skip, limit	关键词搜索日志	需要认证
/log/{log_id}	DELETE	log_id: int	删除日志记录	管理员权限

参考文件：

• log_router.py

日志记录机制

系统日志配置

采用Loguru库实现高性能的日志记录系统，支持控制台和文件双输出。

flowchart TD
    A[应用程序日志事件] --> B[Loguru Logger]
    B --> C{日志级别判断}
    C -->|DEBUG/INFO| D[控制台输出]
    C -->|DEBUG/INFO| E[文件输出]
    D --> F[实时监控]
    E --> G[日志文件存储]
    G --> H[日志轮转管理]
    H --> I[日志压缩归档]
    I --> J[定期清理]

日志配置特性：

• 多输出目标：同时输出到控制台和文件
• 日志轮转：每天自动创建新日志文件
• 压缩存储：自动压缩历史日志文件
• 保留策略：默认保留7天日志
• 线程安全：支持多线程环境
• 异常追踪：完整的堆栈信息记录

日志格式示例：

2024-01-15 10:30:25 | INFO     | app.service.access_log_service:service_create_access_log:46 - Created access log with ID: 12345

参考文件：

• loggers.py

系统架构图

flowchart TD
    subgraph 表现层
        A1[Web客户端]
        A2[Mobile客户端]
        A3[API调用方]
    end
    
    subgraph API网关层
        B1[FastAPI路由]
        B2[中间件处理]
        B3[认证授权]
    end
    
    subgraph 业务逻辑层
        C1[AccessLogService]
        C2[其他业务服务]
        C3[数据验证]
    end
    
    subgraph 数据访问层
        D1[Tortoise ORM]
        D2[AccessLog模型]
        D3[数据库连接池]
    end
    
    subgraph 数据存储层
        E1[PostgreSQL数据库]
        E2[访问日志表]
        E3[其他业务表]
    end
    
    subgraph 基础设施层
        F1[日志记录系统]
        F2[错误监控]
        F3[性能指标]
    end
    
    A1 --> B1
    A2 --> B1
    A3 --> B1
    B1 --> C1
    B1 --> C2
    C1 --> D1
    C2 --> D1
    D1 --> E1
    C1 --> F1
    C2 --> F1

数据流程图

flowchart LR
    subgraph 操作触发
        A1[用户登录]
        A2[工单操作]
        A3[工件管理]
        A4[系统配置]
    end
    
    subgraph 审计记录
        B1[生成审计事件]
        B2[构建日志数据]
        B3[验证数据完整性]
    end
    
    subgraph 持久化存储
        C1[写入数据库]
        C2[索引构建]
        C3[备份同步]
    end
    
    subgraph 查询分析
        D1[API查询]
        D2[统计分析]
        D3[报表生成]
    end
    
    A1 --> B1
    A2 --> B1
    A3 --> B1
    A4 --> B1
    B1 --> B2
    B2 --> B3
    B3 --> C1
    C1 --> C2
    C2 --> C3
    C1 --> D1
    D1 --> D2
    D2 --> D3

类关系图

classDiagram
    class AccessLog {
        +log_id: int
        +action_type: str
        +action_title: str
        +action_description: str
        +related_users: str
        +related_tickets: str
        +related_workpieces: str
        +created_by: int
        +updated_by: int
        +created_at: datetime
        +updated_at: datetime
        +save()
        +delete()
    }
    
    class AccessLogService {
        +service_create_access_log()
        +service_get_access_log_by_id()
        +service_get_all_access_logs()
        +service_get_access_logs_by_action_type()
        +service_get_access_logs_by_user()
        +service_update_access_log()
        +service_delete_access_log()
        +service_search_access_logs_by_keyword()
        +service_get_log_count()
    }
    
    class LogRouter {
        +get_access_log_detail()
        +get_all_access_logs()
        +get_access_logs_by_type()
        +get_access_logs_by_user()
        +search_access_logs_by_keyword()
        +delete_access_log()
    }
    
    class LoggerConfig {
        +setup__logger()
        +LOG_FORMAT: str
        +LOG_RETENTION_DAYS: int
    }
    
    AccessLogService --> AccessLog : 依赖
    LogRouter --> AccessLogService : 调用
    AccessLogService --> LoggerConfig : 使用日志

性能分析

数据库查询优化

索引策略：

• log_id 主键索引 - 唯一查询
• created_at 时间索引 - 时间范围查询
• action_type 分类索引 - 类型筛选
• related_users 关联索引 - 用户行为分析

查询复杂度分析：

操作类型	时间复杂度	数据量影响	优化建议
按ID查询	O(1)	无影响	主键索引已优化
分页查询	O(n)	线性增长	限制分页大小
类型筛选	O(log n)	对数增长	添加复合索引
用户关联	O(n)	线性增长	考虑分表策略
关键词搜索	O(n)	线性增长	使用全文搜索

内存使用分析

单条日志记录内存占用：

• 基础字段：约 2KB
• 关联数据：最大 1KB
• 总内存：约 3KB/记录

批量操作内存优化：

• 分页查询限制100条记录
• 流式处理大数据集
• 异步写入减少内存压力

索引

邮轮穿舱件管理系统后台的审计模型设计采用了完整的分层架构，通过AccessLog数据模型、服务层封装和RESTful API接口，实现了全面的操作审计能力。系统具备良好的可扩展性和性能优化，能够满足企业级审计追踪需求。

核心特性：

• 完整的数据模型设计，支持多维度关联查询
• 分层架构，职责分离清晰
• 高性能日志记录机制
• 完善的API接口设计
• 良好的性能优化策略

参考文件汇总：

• access_log.py - 数据模型定义
• access_log_service.py - 服务层实现
• log_router.py - API路由设计
• loggers.py - 日志配置管理