用户服务 - 邮轮穿舱件管理系统后台
文档概述
本文档详细分析了邮轮穿舱件管理系统后台的用户管理相关业务逻辑实现，包括认证、授权、用户CRUD等核心功能。通过深入分析代码结构和依赖关系，提供了全面的技术文档。
系统架构概述
邮轮穿舱件管理系统采用FastAPI框架构建，使用Tortoise-ORM进行数据库操作，实现了完整的用户管理体系。系统采用JWT令牌进行身份认证，基于角色的权限控制机制。
数据模型分析
用户模型 (User Model)
用户模型定义了系统用户的基本属性和状态管理。
classDiagram
class User {
+id: IntField (PK)
+username: CharField (unique)
+password: CharField
+email: CharField (unique)
+sms: CharField
+status: CharField
+openid: CharField
+is_system: BooleanField
+created_by: IntField
+updated_by: IntField
+created_at: DatetimeField
+updated_at: DatetimeField
}
class UserStatus {
<<enumeration>>
ACTIVE
INACTIVE
SUSPENDED
DELETED
}
User --> UserStatus : status
核心字段说明：
username: 唯一用户名，用于登录和身份识别password: 使用bcrypt加密存储的密码status: 用户状态，支持激活、未激活、暂停、删除四种状态openid: 微信OpenID，支持微信登录集成is_system: 标识是否为系统内置用户
参考文件：
角色权限模型 (Role Model)
角色模型管理用户的权限分配和访问控制。
classDiagram
class Role {
+user_id: IntField
+scope_list: CharField
+scope_group: CharField
+created_by: IntField
+updated_by: IntField
+created_at: DatetimeField
+updated_at: DatetimeField
}
class User {
+id: IntField
}
Role --> User : user_id
核心字段说明：
user_id: 关联的用户IDscope_list: 权限列表，以逗号分隔的权限字符串scope_group: 权限组标识，用于批量权限管理
参考文件：
数据验证模式
用户数据验证模式
系统使用Pydantic模型进行数据验证和序列化。
classDiagram
class UserSchemaIn {
<<BaseModel>>
+username: str
+password: str
+email: Optional[str]
+sms: Optional[str]
+status: Optional[UserStatus]
+openid: Optional[str]
+is_system: Optional[bool]
}
class UserSchemaOut {
<<BaseModel>>
+id: int
+username: str
+email: Optional[str]
+sms: Optional[str]
+status: str
+openid: Optional[str]
+is_system: bool
+created_by: Optional[int]
+updated_by: Optional[int]
+created_at: datetime
+updated_at: datetime
}
class UserUpdateSchema {
<<BaseModel>>
+username: Optional[str]
+password: Optional[str]
+email: Optional[str]
+sms: Optional[str]
+status: Optional[UserStatus]
+openid: Optional[str]
+is_system: Optional[bool]
}
class UserLoginSchema {
<<BaseModel>>
+username: str
+password: str
}
UserSchemaIn <|-- UserUpdateSchema : extends
模式功能：
UserSchemaIn: 用户创建时的输入验证UserSchemaOut: 用户信息输出时的序列化UserUpdateSchema: 用户信息更新时的部分更新支持UserLoginSchema: 用户登录凭据验证
参考文件：
业务服务层实现
用户服务 (User Service)
用户服务层实现了核心的业务逻辑处理。
flowchart TD
A[用户服务入口] --> B[密码处理]
A --> C[用户CRUD操作]
A --> D[用户认证]
B --> B1[密码哈希]
B --> B2[密码验证]
C --> C1[创建用户]
C --> C2[查询用户]
C --> C3[更新用户]
C --> C4[删除用户]
C --> C5[状态管理]
D --> D1[用户名/邮箱/手机验证]
D --> D2[密码匹配]
D --> D3[状态检查]
密码安全处理
def service_util_hash_password(password: str) -> str:
"""使用bcrypt进行密码哈希处理"""
salt = bcrypt.gensalt()
hashed = bcrypt.hashpw(password.encode('utf-8'), salt)
return hashed.decode('utf-8')
def service_util_verify_password(password: str, hashed_password: str) -> bool:
"""验证密码是否匹配"""
return bcrypt.checkpw(password.encode('utf-8'), hashed_password.encode('utf-8'))
参考文件：
用户创建流程
sequenceDiagram
participant Client
participant UserService
participant Database
participant Logger
Client->>UserService: service_create_user(user_data)
UserService->>Database: 检查用户名唯一性
Database-->>UserService: 返回检查结果
UserService->>Database: 检查邮箱唯一性
Database-->>UserService: 返回检查结果
UserService->>UserService: 密码哈希处理
UserService->>Database: 创建用户记录
Database-->>UserService: 返回用户对象
UserService->>Logger: 记录创建日志
UserService-->>Client: 返回UserSchemaOut
关键特性：
- 用户名和邮箱唯一性验证
- 自动密码哈希处理
- 完整的审计日志记录
- 异常处理和错误信息返回
参考文件：
用户认证流程
stateDiagram-v2
[*] --> 接收登录请求
接收登录请求 --> 用户查找: 通过用户名/邮箱/手机
用户查找 --> 用户不存在: 查找失败
用户查找 --> 密码验证: 用户存在
密码验证 --> 认证失败: 密码不匹配
密码验证 --> 状态检查: 密码匹配
状态检查 --> 认证失败: 状态非激活
状态检查 --> 认证成功: 状态正常
认证失败 --> [*]
认证成功 --> [*]
认证特性：
- 支持用户名、邮箱、手机号多种登录方式
- 多因素身份验证支持
- 用户状态检查机制
- 详细的认证日志记录
参考文件：
角色权限服务 (Role Service)
角色服务管理用户的权限分配和验证。
classDiagram
class RoleService {
+service_get_user_scopes(user_id: int) List[str]
+service_grant_user_a_scope(user_id: int, scope_name: str)
+service_revoke_user_a_scope(user_id: int, scope_name: str)
}
class Role {
+user_id: int
+scope_list: str
}
RoleService --> Role : 操作
核心方法：
service_get_user_scopes: 获取用户的所有权限service_grant_user_a_scope: 授予用户特定权限service_revoke_user_a_scope: 撤销用户特定权限
参考文件：
API路由层实现
用户管理路由 (User Router)
用户路由层提供RESTful API接口。
flowchart TD
subgraph 用户管理API
A1[POST /users] --> A2[创建用户]
B1[POST /users/register] --> B2[用户注册]
C1[GET /users] --> C2[获取用户列表]
D1[GET /users/{id}] --> D2[根据ID获取用户]
E1[GET /users/username/{name}] --> E2[根据用户名获取用户]
F1[PUT /users/{id}] --> F2[更新用户信息]
G1[DELETE /users/{id}] --> G3[删除用户]
H1[PATCH /users/{id}/status] --> H2[修改用户状态]
I1[POST /users/authenticate] --> I2[用户认证]
end
subgraph 认证授权
J1[JWT验证] --> J2[权限检查]
J2 --> J3[访问日志]
end
A2 --> J1
B2 --> J1
C2 --> J1
D2 --> J1
E2 --> J1
F2 --> J1
G3 --> J1
H2 --> J1
I2 --> J1
路由权限控制
user_router = APIRouter(
prefix="/users",
tags=["用户管理"],
dependencies=[Depends(require_scopes(["system:read"], mode="AND")), Depends(verify_jwt_token)],
)
权限控制特性：
- 全局JWT令牌验证
- 基于作用域的细粒度权限控制
- AND/OR两种权限检查模式
- 自动访问日志记录
参考文件：
用户创建API
@user_router.post("/",
response_model=UserSchemaOut,
status_code=201,
name="创建用户",
summary="创建新用户",
description="创建一个新的用户账户")
async def api_create_user(
user_data: UserSchemaIn,
current_user=Depends(require_scopes(["system:write"]))
) -> UserSchemaOut:
参考文件：
认证路由 (Auth Router)
认证路由处理JWT令牌的生成和验证。
sequenceDiagram
participant Client
participant AuthRouter
participant UserService
participant RoleService
participant Authorize
participant Logger
Client->>AuthRouter: POST /token (username, password)
AuthRouter->>UserService: service_authenticate_user()
UserService-->>AuthRouter: 用户信息
AuthRouter->>RoleService: service_get_user_scopes()
RoleService-->>AuthRouter: 权限列表
AuthRouter->>Authorize: create_jwt_token()
Authorize-->>AuthRouter: JWT令牌
AuthRouter->>Logger: 记录认证日志
AuthRouter-->>Client: 返回令牌
参考文件：
认证授权系统
JWT令牌管理
classDiagram
class Authorize {
+create_jwt_token(data: Dict) Dict
+verify_jwt_token(token: str) Dict
+require_scopes(scopes: List, mode: str) Callable
}
class JWTConfig {
+SECRET_KEY: str
+ALGORITHM: str
+ACCESS_TOKEN_EXPIRE_MINUTES: int
}
class ScopeDefinition {
+SCOPE: Dict
+ROLE_SCOPES: Dict
}
Authorize --> JWTConfig : 配置
Authorize --> ScopeDefinition : 权限定义
令牌创建流程
def create_jwt_token(data: Dict[str, Any], expires_delta: Optional[timedelta] = None) -> Dict[str, str]:
to_encode = data.copy()
# 设置过期时间
expire = datetime.now(timezone('Asia/Shanghai')) + timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
to_encode.update({"exp": expire})
# 创建JWT令牌
encoded_jwt = jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
return {
"access_token": encoded_jwt,
"token_type": "bearer"
}
参考文件：
权限检查机制
def require_scopes(scopes: list[str], mode: Literal["AND","OR"]="AND") -> Callable:
async def _dep(token: str = Depends(oauth2_scheme)):
# JWT解码和验证
payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
# 权限检查逻辑
if mode == "AND":
ok = set(scopes).issubset(token_scopes)
else: # "OR"
ok = not token_scopes.isdisjoint(scopes)
权限模式：
AND模式：要求用户拥有所有指定的权限OR模式：要求用户拥有至少一个指定的权限
参考文件：
权限作用域定义
系统定义了完整的作用域体系，支持细粒度的权限控制。
graph TD
A[权限作用域] --> B[工件权限]
A --> C[任务权限]
A --> D[日志权限]
A --> E[图像权限]
A --> F[系统权限]
A --> G[接入权限]
B --> B1[workpiece:read]
B --> B2[workpiece:write]
C --> C1[task:read]
C --> C2[task:write]
D --> D1[log:read]
D --> D2[log:write]
E --> E1[image:read]
E --> E2[image:write]
F --> F1[system:read]
F --> F2[system:write]
G --> G1[inspect:access]
G --> G2[maintenance:access]
G --> G3[miniapp:access]
角色权限映射：
desktop: 拥有所有权限作用域miniapp: 工件、任务、图像相关权限和小程序接入inspect: 巡检接入权限maintenance: 维修接入权限
参考文件：
系统依赖关系分析
模块依赖关系
flowchart TD
subgraph 数据层
A1[User Model]
A2[Role Model]
end
subgraph 服务层
B1[User Service]
B2[Role Service]
B3[Access Log Service]
end
subgraph 路由层
C1[User Router]
C2[Auth Router]
end
subgraph 核心组件
D1[Authorize]
D2[Logger]
D3[Settings]
end
A1 --> B1
A2 --> B2
B1 --> C1
B2 --> C1
B3 --> C1
B1 --> C2
B2 --> C2
D1 --> C1
D1 --> C2
D2 --> B1
D2 --> B2
D2 --> C1
D2 --> C2
D3 --> D1
数据流分析
flowchart LR
A[客户端请求] --> B[API路由]
B --> C[权限验证]
C --> D[业务服务]
D --> E[数据模型]
E --> F[数据库]
F --> E
E --> D
D --> G[响应序列化]
G --> H[客户端响应]
C --> I[访问日志]
D --> I
I --> J[日志存储]
性能和安全考虑
安全特性
- 密码安全: 使用bcrypt进行密码哈希，防止彩虹表攻击
- JWT安全: 使用HS256算法，配置安全的密钥和过期时间
- 权限控制: 基于作用域的细粒度权限验证
- 输入验证: 使用Pydantic进行严格的数据验证
- SQL注入防护: 使用ORM防止SQL注入攻击
性能优化
- 数据库查询优化: 使用ORM的延迟加载和查询优化
- 缓存策略: JWT令牌减少数据库查询频率
- 分页支持: 用户列表查询支持分页，避免大数据量传输
- 异步处理: 使用异步IO提高并发处理能力
索引
邮轮穿舱件管理系统的用户服务模块实现了完整的用户管理体系，包括：
- 完整的CRUD操作: 支持用户的创建、读取、更新、删除全生命周期管理
- 强大的认证系统: 支持多种登录方式和JWT令牌认证
- 细粒度的权限控制: 基于作用域的权限管理体系
- 完善的安全机制: 密码加密、输入验证、权限验证等多层安全防护
- 完整的审计日志: 所有操作都有详细的日志记录
系统架构清晰，模块职责明确，具有良好的可扩展性和维护性。通过合理的依赖注入和接口设计，支持未来的功能扩展和系统演进。
主要参考文件：