用户API文档

文档概述

1.1 文档用途

本文档详细描述了邮轮穿舱件管理系统后台中用户管理相关的所有RESTful API接口，包括用户的创建、查询、更新、删除以及认证等功能。

1.2 适用对象

前端开发人员
后端开发人员
系统集成人员
测试人员

1.3 系统架构概述

邮轮穿舱件管理系统采用FastAPI框架构建，使用Tortoise-ORM进行数据库操作，支持JWT认证机制。用户管理模块是系统的核心组件之一，负责用户身份验证和权限管理。

2. 接口规范

2.1 基础信息

基础URL: http://localhost:8000
协议: HTTP/HTTPS
数据格式: JSON
字符编码: UTF-8

2.2 认证方式

除用户注册和JWT令牌获取接口外，其他接口均需要JWT认证。

请求头要求:

Authorization: Bearer <JWT_TOKEN>
Content-Type: application/json

2.3 通用响应格式

成功响应

{
  "data": {},
  "message": "操作成功"
}

错误响应

{
  "detail": "错误描述信息"
}

2.4 状态码说明

200: 请求成功
201: 创建成功
204: 删除成功（无内容返回）
400: 请求参数错误
401: 未授权/认证失败
404: 资源不存在
500: 服务器内部错误

2.5 用户状态枚举

active: 激活状态
inactive: 非激活状态
suspended: 暂停状态
deleted: 已删除状态

3. 系统架构与代码结构

3.1 用户管理模块架构图

flowchart TD
    subgraph "用户管理模块"
        A[用户路由层<br/>user_router.py] --> B[用户服务层<br/>user_service.py]
        B --> C[数据模型层<br/>user.py]
        B --> D[数据模式层<br/>user_schema.py]
    end
    
    subgraph "核心组件"
        E[认证模块<br/>authorize.py] --> A
        F[日志模块<br/>loggers.py] --> A
        G[访问日志<br/>access_log_service.py] --> A
    end
    
    subgraph "数据库"
        H[Tortoise ORM] --> C
    end
    
    A --> I[客户端]

3.2 类关系图

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 UserSchemaIn {
        +str username
        +str password
        +Optional[str] email
        +Optional[str] sms
        +Optional[UserStatus] status
        +Optional[str] openid
        +Optional[bool] is_system
    }
    
    class UserSchemaOut {
        +int id
        +str username
        +Optional[str] email
        +Optional[str] sms
        +str status
        +Optional[str] openid
        +bool is_system
        +Optional[int] created_by
        +Optional[int] updated_by
        +datetime created_at
        +datetime updated_at
    }
    
    class UserUpdateSchema {
        +Optional[str] username
        +Optional[str] password
        +Optional[str] email
        +Optional[str] sms
        +Optional[UserStatus] status
        +Optional[str] openid
        +Optional[bool] is_system
    }
    
    class UserLoginSchema {
        +str username
        +str password
    }
    
    class UserStatus {
        <<enumeration>>
        ACTIVE
        INACTIVE
        SUSPENDED
        DELETED
    }
    
    UserSchemaIn --> UserStatus
    UserSchemaOut --> UserStatus
    UserUpdateSchema --> UserStatus
    User --> UserStatus

3.3 数据流图

flowchart LR
    A[客户端请求] --> B[用户路由层]
    B --> C[参数验证]
    C --> D[权限验证]
    D --> E[业务逻辑处理]
    E --> F[数据库操作]
    F --> G[响应格式化]
    G --> H[返回客户端]
    
    subgraph "安全层"
        I[JWT验证] --> D
        J[权限检查] --> D
    end
    
    subgraph "数据层"
        K[数据模型] --> F
        L[数据模式] --> C
    end
    
    subgraph "日志层"
        M[访问日志] --> B
        N[业务日志] --> E
    end

4. 接口详情

4.1 认证接口

4.1.1 获取JWT令牌

接口名称: 获取JWT令牌
请求方法: POST
请求路径: /token
功能描述: 用户登录获取JWT访问令牌
权限要求: 无

请求参数:

参数名	类型	必填	描述	示例值
username	string	是	用户名	"admin"
password	string	是	密码	"password123"

请求体格式: application/x-www-form-urlencoded

请求示例:

curl -X POST "http://localhost:8000/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=password123"

响应示例:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

错误响应:

{
  "detail": "Login Failed, Invalid credentials"
}

代码实现参考: user_router.py

4.2 用户管理接口

4.2.1 用户注册

接口名称: 用户注册
请求方法: POST
请求路径: /users/register
功能描述: 用户自主注册新账户
权限要求: 无

请求参数:

参数名	类型	必填	描述	示例值
username	string	是	用户名	"newuser"
password	string	是	密码	"password123"
email	string	否	邮箱地址	"user@example.com"
sms	string	否	手机号码	"13800138000"
status	string	否	用户状态	"active"
openid	string	否	微信OpenID	"wx_openid_123"
is_system	boolean	否	是否系统用户	false

请求体格式: JSON

请求示例:

curl -X POST "http://localhost:8000/users/register" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newuser",
    "password": "password123",
    "email": "user@example.com",
    "sms": "13800138000"
  }'

响应示例:

{
  "id": 1,
  "username": "newuser",
  "email": "user@example.com",
  "sms": "13800138000",
  "status": "active",
  "openid": null,
  "is_system": false,
  "created_by": null,
  "updated_by": null,
  "created_at": "2024-01-01T10:00:00",
  "updated_at": "2024-01-01T10:00:00"
}

代码实现参考: user_router.py | user_service.py

4.2.2 创建用户（管理员）

接口名称: 创建用户
请求方法: POST
请求路径: /users/
功能描述: 管理员创建新用户账户
权限要求: 需要JWT认证

请求参数: 同用户注册接口

请求示例:

curl -X POST "http://localhost:8000/users/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -d '{
    "username": "adminuser",
    "password": "password123",
    "email": "admin@example.com",
    "is_system": true
  }'

代码实现参考: user_router.py

4.2.3 获取用户列表

接口名称: 获取用户列表
请求方法: GET
请求路径: /users/
功能描述: 分页获取用户列表
权限要求: 需要JWT认证

查询参数:

参数名	类型	必填	描述	示例值	限制
skip	integer	否	跳过的记录数	0	≥0
limit	integer	否	返回的记录数	100	1-1000

请求示例:

curl -X GET "http://localhost:8000/users/?skip=0&limit=10" \
  -H "Authorization: Bearer <JWT_TOKEN>"

响应示例:

[
  {
    "id": 1,
    "username": "user1",
    "email": "user1@example.com",
    "sms": "13800138001",
    "status": "active",
    "openid": null,
    "is_system": false,
    "created_by": 1,
    "updated_by": 1,
    "created_at": "2024-01-01T10:00:00",
    "updated_at": "2024-01-01T10:00:00"
  },
  {
    "id": 2,
    "username": "user2",
    "email": "user2@example.com",
    "sms": "13800138002",
    "status": "active",
    "openid": null,
    "is_system": false,
    "created_by": 1,
    "updated_by": 1,
    "created_at": "2024-01-01T11:00:00",
    "updated_at": "2024-01-01T11:00:00"
  }
]

代码实现参考: user_router.py | user_service.py

4.2.4 根据ID获取用户

接口名称: 根据ID获取用户
请求方法: GET
请求路径: /users/{user_id}
功能描述: 根据用户ID获取用户详细信息
权限要求: 需要JWT认证

路径参数:

参数名	类型	必填	描述	示例值
user_id	integer	是	用户ID	1

请求示例:

curl -X GET "http://localhost:8000/users/1" \
  -H "Authorization: Bearer <JWT_TOKEN>"

响应示例:

{
  "id": 1,
  "username": "user1",
  "email": "user1@example.com",
  "sms": "13800138001",
  "status": "active",
  "openid": null,
  "is_system": false,
  "created_by": 1,
  "updated_by": 1,
  "created_at": "2024-01-01T10:00:00",
  "updated_at": "2024-01-01T10:00:00"
}

代码实现参考: user_router.py | user_service.py

4.2.5 根据用户名获取用户

接口名称: 根据用户名获取用户
请求方法: GET
请求路径: /users/username/{username}
功能描述: 根据用户名获取用户详细信息
权限要求: 需要JWT认证

路径参数:

参数名	类型	必填	描述	示例值
username	string	是	用户名	"user1"

请求示例:

curl -X GET "http://localhost:8000/users/username/user1" \
  -H "Authorization: Bearer <JWT_TOKEN>"

代码实现参考: user_router.py | user_service.py

4.2.6 更新用户信息

接口名称: 更新用户信息
请求方法: PUT
请求路径: /users/{user_id}
功能描述: 根据用户ID更新用户信息
权限要求: 需要JWT认证

路径参数:

参数名	类型	必填	描述	示例值
user_id	integer	是	用户ID	1

请求参数:

参数名	类型	必填	描述	示例值
username	string	否	用户名	"newusername"
password	string	否	密码	"newpassword123"
email	string	否	邮箱地址	"newemail@example.com"
sms	string	否	手机号码	"13900139000"
status	string	否	用户状态	"inactive"
openid	string	否	微信OpenID	"new_wx_openid"
is_system	boolean	否	是否系统用户	true

请求示例:

curl -X PUT "http://localhost:8000/users/1" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -d '{
    "email": "newemail@example.com",
    "sms": "13900139000"
  }'

代码实现参考: user_router.py | user_service.py

4.2.7 删除用户

接口名称: 删除用户
请求方法: DELETE
请求路径: /users/{user_id}
功能描述: 根据用户ID删除用户
权限要求: 需要JWT认证

路径参数:

参数名	类型	必填	描述	示例值
user_id	integer	是	用户ID	1

请求示例:

curl -X DELETE "http://localhost:8000/users/1" \
  -H "Authorization: Bearer <JWT_TOKEN>"

成功响应: HTTP 204 No Content（无响应体）

代码实现参考: user_router.py | user_service.py

4.2.8 修改用户状态

接口名称: 修改用户状态
请求方法: PATCH
请求路径: /users/{user_id}/status
功能描述: 修改指定用户的状态
权限要求: 需要JWT认证

路径参数:

参数名	类型	必填	描述	示例值
user_id	integer	是	用户ID	1

请求参数:

参数名	类型	必填	描述	示例值
status	string	是	用户状态	"suspended"

请求示例:

curl -X PATCH "http://localhost:8000/users/1/status" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -d '"suspended"'

代码实现参考: user_router.py | user_service.py

4.2.9 用户认证

接口名称: 用户认证
请求方法: POST
请求路径: /users/authenticate
功能描述: 验证用户名和密码
权限要求: 无

请求参数:

参数名	类型	必填	描述	示例值
username	string	是	用户名	"user1"
password	string	是	密码	"password123"

请求示例:

curl -X POST "http://localhost:8000/users/authenticate" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "user1",
    "password": "password123"
  }'

代码实现参考: user_router.py | user_service.py

5. 数据模型说明

5.1 用户数据模型（User）

数据库表: users

字段名	类型	描述	约束
id	IntField	用户ID	主键
username	CharField	用户名	唯一，非空
password	CharField	密码	非空
email	CharField	邮箱	唯一，可为空
sms	CharField	手机号码	可为空
status	CharField	用户状态	非空，默认active
openid	CharField	微信OpenID	可为空
is_system	BooleanField	是否系统用户	非空，默认false
created_by	IntField	创建人	可为空
updated_by	IntField	更新人	可为空
created_at	DatetimeField	创建时间	非空，自动添加
updated_at	DatetimeField	更新时间	非空，自动更新

代码实现参考: user.py

5.2 数据模式（Schemas）

系统使用Pydantic模型进行数据验证和序列化：

UserSchemaIn: 用户输入数据验证
UserSchemaOut: 用户输出数据序列化
UserUpdateSchema: 用户更新数据验证
UserLoginSchema: 用户登录数据验证

代码实现参考: user_schema.py

6. 安全特性

6.1 密码安全

使用bcrypt算法进行密码哈希
密码强度验证
防止时序攻击

6.2 认证机制

JWT令牌认证
权限范围控制
令牌过期机制

6.3 数据验证

输入参数验证
SQL注入防护
XSS攻击防护

7. 错误处理

7.1 常见错误码

错误码	描述	可能原因
400	请求参数错误	参数格式不正确或缺失
401	未授权	JWT令牌无效或过期
403	禁止访问	权限不足
404	资源不存在	用户ID不存在
409	冲突	用户名或邮箱已存在
500	服务器内部错误	数据库连接失败等

7.2 异常处理流程

sequenceDiagram
    participant C as Client
    participant R as Router
    participant S as Service
    participant D as Database
    participant E as Exception Handler
    
    C->>R: API Request
    R->>R: Parameter Validation
    R->>R: Permission Check
    R->>S: Call Service
    S->>D: Database Operation
    D-->>S: Return Result/Error
    alt Operation Success
        S-->>R: Return Data
        R-->>C: Success Response
    else Operation Failed
        S->>E: Raise Exception
        E-->>R: Error Details
        R-->>C: Error Response
    end

8. 性能考虑

8.1 数据库优化

使用索引优化查询性能
分页查询防止数据过大
连接池管理

8.2 缓存策略

用户信息缓存
认证令牌缓存
查询结果缓存

8.3 并发处理

异步请求处理
数据库连接池
锁机制防止数据竞争

9. 部署与运维

9.1 环境要求

Python 3.8+
FastAPI框架
Tortoise-ORM
bcrypt密码库

9.2 监控指标

API响应时间
错误率统计
用户活跃度
系统负载

10. 索引

本文档详细描述了邮轮穿舱件管理系统后台的用户管理API接口，涵盖了完整的CRUD操作和认证功能。系统采用分层架构设计，具有良好的可扩展性和安全性。通过标准化的RESTful接口设计，为前端开发和其他系统集成提供了清晰的接口规范。

参考文件:

文档概述​

1.1 文档用途​

1.2 适用对象​

1.3 系统架构概述​

2. 接口规范​

2.1 基础信息​

2.2 认证方式​

2.3 通用响应格式​

成功响应​

错误响应​

2.4 状态码说明​

2.5 用户状态枚举​

3. 系统架构与代码结构​

3.1 用户管理模块架构图​

3.2 类关系图​

3.3 数据流图​

4. 接口详情​

4.1 认证接口​

4.1.1 获取JWT令牌​

4.2 用户管理接口​

4.2.1 用户注册​

4.2.2 创建用户（管理员）​

4.2.3 获取用户列表​

4.2.4 根据ID获取用户​

4.2.5 根据用户名获取用户​

4.2.6 更新用户信息​

4.2.7 删除用户​

4.2.8 修改用户状态​

4.2.9 用户认证​

5. 数据模型说明​

5.1 用户数据模型（User）​

5.2 数据模式（Schemas）​

6. 安全特性​

6.1 密码安全​

6.2 认证机制​

6.3 数据验证​

7. 错误处理​

7.1 常见错误码​

7.2 异常处理流程​

8. 性能考虑​

8.1 数据库优化​

8.2 缓存策略​

8.3 并发处理​

9. 部署与运维​

9.1 环境要求​

9.2 监控指标​

10. 索引​

文档概述

1.1 文档用途

1.2 适用对象

1.3 系统架构概述

2. 接口规范

2.1 基础信息

2.2 认证方式

2.3 通用响应格式

成功响应

错误响应

2.4 状态码说明

2.5 用户状态枚举

3. 系统架构与代码结构

3.1 用户管理模块架构图

3.2 类关系图

3.3 数据流图

4. 接口详情

4.1 认证接口

4.1.1 获取JWT令牌

4.2 用户管理接口

4.2.1 用户注册

4.2.2 创建用户（管理员）

4.2.3 获取用户列表

4.2.4 根据ID获取用户

4.2.5 根据用户名获取用户

4.2.6 更新用户信息

4.2.7 删除用户

4.2.8 修改用户状态

4.2.9 用户认证

5. 数据模型说明

5.1 用户数据模型（User）

5.2 数据模式（Schemas）

6. 安全特性

6.1 密码安全

6.2 认证机制

6.3 数据验证

7. 错误处理

7.1 常见错误码

7.2 异常处理流程

8. 性能考虑

8.1 数据库优化

8.2 缓存策略

8.3 并发处理

9. 部署与运维

9.1 环境要求

9.2 监控指标

10. 索引