用户管理功能文档

概述

本文档详细分析邮轮穿舱件管理系统后台的用户管理功能实现，涵盖用户注册、登录、信息管理等核心功能。通过分析user相关的model、schema、service和router组件，提供完整的架构视图和实现细节。

系统架构概览

用户管理模块采用分层架构设计，遵循FastAPI最佳实践：

flowchart TD
    A[用户请求] --> B[Router层]
    B --> C[Service层]
    C --> D[Model层]
    D --> E[数据库]
    E --> D
    D --> C
    C --> B
    B --> A

1. 数据模型层 (Model)

1.1 用户模型 (User Model)

用户模型定义了数据库表结构和字段约束：

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, null=False, 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)

字段说明：

• username: 用户名，唯一且必填
• password: 密码，使用bcrypt加密存储
• email: 邮箱地址，唯一约束
• sms: 手机号码
• status: 用户状态，支持四种状态枚举
• openid: 微信OpenID，支持微信登录
• is_system: 标识是否为系统用户
• 审计字段：created_by, updated_by, created_at, updated_at

用户状态枚举：

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

参考文件：

• app/models/user.py

2. 数据模式层 (Schema)

2.1 用户输入模式 (UserSchemaIn)

用于用户创建和注册的数据验证：

class UserSchemaIn(BaseModel):
    username: str
    password: str
    email: Optional[str] = None
    sms: Optional[str] = None
    status: Optional[UserStatus] = UserStatus.ACTIVE
    openid: Optional[str] = None
    is_system: Optional[bool] = False

2.2 用户输出模式 (UserSchemaOut)

用于API响应数据格式化：

class UserSchemaOut(BaseModel):
    id: int
    username: str
    email: Optional[str] = None
    sms: Optional[str] = None
    status: str
    openid: Optional[str] = None
    is_system: bool
    created_by: Optional[int] = None
    updated_by: Optional[int] = None
    created_at: datetime
    updated_at: datetime

2.3 用户更新模式 (UserUpdateSchema)

支持部分更新的数据模式：

class UserUpdateSchema(BaseModel):
    username: Optional[str] = None
    password: Optional[str] = None
    email: Optional[str] = None
    sms: Optional[str] = None
    status: Optional[UserStatus] = None
    openid: Optional[str] = None
    is_system: Optional[bool] = None

2.4 用户登录模式 (UserLoginSchema)

登录认证专用数据模式：

class UserLoginSchema(BaseModel):
    username: str
    password: str

参考文件：

• app/schemas/user_schema.py

3. 服务层 (Service)

3.1 密码安全工具

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'))

3.2 核心业务服务

flowchart TD
    A[用户注册] --> B[密码哈希]
    B --> C[唯一性校验]
    C --> D[创建用户]
    D --> E[返回结果]
    
    F[用户登录] --> G[多方式查找]
    G --> H[密码验证]
    H --> I[状态检查]
    I --> J[返回用户信息]

3.2.1 用户创建服务

async def service_create_user(user_data: UserSchemaIn, created_by: int = -1) -> UserSchemaOut:
    """
    创建新用户，包含完整的业务逻辑验证
    - 用户名唯一性检查
    - 邮箱唯一性检查
    - 密码安全哈希
    - 审计信息记录
    """

3.2.2 用户查询服务

提供多种查询方式：

• 按ID查询：service_get_user_by_id()
• 按用户名查询：service_get_user_by_username()
• 按OpenID查询：service_get_user_by_openid()
• 分页查询所有用户：service_get_all_users()

3.2.3 用户认证服务

async def service_authenticate_user(login_data: UserLoginSchema) -> Optional[UserSchemaOut]:
    """
    用户认证流程：
    1. 支持用户名/邮箱/手机号登录
    2. 密码验证（bcrypt）
    3. 用户状态检查
    4. 返回认证结果
    """

3.2.4 用户管理服务

• 用户信息更新：service_update_user()
• 用户删除：service_delete_user()
• 状态管理：service_change_user_status()

参考文件：

• app/service/user_service.py

4. 路由层 (Router)

4.1 用户管理路由

用户路由采用权限控制设计：

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

4.2 API端点映射

graph TD
    A[POST /users/] --> B[创建用户]
    C[POST /users/register] --> D[用户注册]
    E[GET /users/] --> F[获取用户列表]
    G[GET /users/{user_id}] --> H[按ID获取用户]
    I[GET /users/username/{username}] --> J[按用户名获取用户]
    K[PUT /users/{user_id}] --> L[更新用户信息]
    M[DELETE /users/{user_id}] --> N[删除用户]
    O[PATCH /users/{user_id}/status] --> P[修改用户状态]
    Q[POST /users/authenticate] --> R[用户认证]

4.3 认证路由

@auth_router.post("/token", response_model=OAuthBearerToken)
async def api_get_token(credentials: OAuth2PasswordRequestForm = Depends()):
    """
    JWT令牌获取接口：
    1. 用户认证
    2. 获取用户权限范围
    3. 生成JWT令牌
    4. 返回访问令牌
    """

参考文件：

• app/routers/user_router.py
• app/routers/login.py

5. 安全架构

5.1 认证流程

sequenceDiagram
    participant U as 用户
    participant R as Router
    participant S as Service
    participant A as Auth
    participant DB as 数据库
    
    U->>R: POST /token
    R->>S: service_authenticate_user()
    S->>DB: 查询用户信息
    DB-->>S: 返回用户数据
    S->>S: 密码验证
    S-->>R: 认证结果
    R->>A: create_jwt_token()
    A-->>R: JWT令牌
    R-->>U: 返回令牌

5.2 权限控制

系统采用基于Scope的权限控制：

• system:read: 系统读取权限
• system:write: 系统写入权限
• 支持AND/OR权限组合模式

6. 错误处理机制

6.1 业务异常类型

异常类型	HTTP状态码	描述
IntegrityError	400	数据完整性错误（用户名/邮箱重复）
DoesNotExist	404	用户不存在
认证失败	401	用户名或密码错误
状态异常	400	用户状态不允许操作

6.2 日志记录

系统采用结构化日志记录：

• 操作审计日志
• 安全事件日志
• 性能监控日志

7. 数据流分析

7.1 用户注册数据流

flowchart LR
    A[客户端] --> B[UserSchemaIn验证]
    B --> C[唯一性检查]
    C --> D[密码哈希]
    D --> E[创建用户记录]
    E --> F[UserSchemaOut响应]
    F --> A

7.2 用户登录数据流

flowchart TD
    A[登录请求] --> B[多字段查询]
    B --> C{用户存在?}
    C -->|是| D[密码验证]
    C -->|否| E[返回401]
    D --> F{密码正确?}
    F -->|是| G[状态检查]
    F -->|否| E
    G --> H{状态正常?}
    H -->|是| I[生成JWT]
    H -->|否| J[返回状态异常]
    I --> K[返回令牌]

8. 性能优化考虑

8.1 数据库优化

• 索引优化：username、email、openid字段建立唯一索引
• 查询优化：分页查询限制返回记录数
• 连接池：使用数据库连接池管理连接

8.2 安全优化

• 密码哈希：使用bcrypt算法，自动加盐
• 令牌管理：JWT令牌支持过期时间
• 输入验证：Pydantic模型验证所有输入数据

索引

用户管理模块实现了完整的用户生命周期管理，包括注册、认证、信息管理和权限控制。系统采用分层架构设计，具有良好的可维护性和扩展性。通过详细的错误处理、安全控制和日志记录，确保了系统的稳定性和安全性。

核心特性：

• 支持多种登录方式（用户名/邮箱/手机号）
• 完整的用户状态管理
• 基于Scope的权限控制
• 微信OpenID集成支持
• 完整的审计日志记录

技术栈：

• FastAPI + Tortoise-ORM + Pydantic
• bcrypt密码加密
• JWT令牌认证
• 结构化日志记录

该模块为邮轮穿舱件管理系统提供了稳定可靠的用户管理基础，支持后续的功能扩展和集成需求。