邮轮穿舱件管理系统后台 - 集成指南
概述
本文档详细介绍了邮轮穿舱件管理系统后台与其他系统集成的接口规范和技术方案。该系统基于FastAPI框架构建，采用微服务架构，支持与微信小程序、计算机视觉核心系统(CVCore)等多个外部系统的集成。
系统架构总览
flowchart TD
subgraph 外部系统
A[微信小程序]
B[计算机视觉核心系统]
C[对象存储服务]
end
subgraph 邮轮穿舱件管理系统
D[API网关层]
E[业务逻辑层]
F[数据访问层]
end
A --> D
B --> D
D --> E
E --> F
F --> C
1. 微信小程序集成
1.1 认证流程
系统通过OAuth 2.0协议与微信小程序进行集成，支持两种登录方式：
1.1.1 自动注册登录流程
sequenceDiagram
participant 小程序 as 微信小程序
participant API as 后台API
participant 微信 as 微信服务器
participant DB as 数据库
小程序->>API: POST /wechat/loginWithAutoRegister
API->>微信: 调用jscode2session API
微信-->>API: 返回openid和session_key
API->>DB: 根据openid查询用户
alt 用户不存在
API->>DB: 自动创建新用户
DB-->>API: 返回用户信息
else 用户存在
DB-->>API: 返回用户信息
end
API->>API: 生成JWT token
API-->>小程序: 返回Bearer token
1.1.2 用户名密码绑定登录流程
sequenceDiagram
participant 小程序 as 微信小程序
participant API as 后台API
participant 微信 as 微信服务器
participant DB as 数据库
小程序->>API: POST /wechat/loginWithUsrPwd
API->>微信: 调用jscode2session API
微信-->>API: 返回openid
API->>DB: 验证openid绑定关系
alt 未绑定
API-->>小程序: 返回绑定错误
else 已绑定
API->>DB: 验证用户名密码
DB-->>API: 返回验证结果
API->>API: 生成JWT token
API-->>小程序: 返回Bearer token
end
1.2 接口规范
1.2.1 微信登录接口
请求路径: POST /wechat/loginWithAutoRegister
请求参数:
{
"code": "微信小程序登录凭证"
}
响应格式:
{
"access_token": "JWT令牌",
"token_type": "bearer"
}
错误码:
400: 微信API调用失败403: 用户状态异常500: 服务器内部错误
参考文件: app/routers/wechat/login.py
1.3 配置要求
系统通过环境变量配置微信小程序参数：
WECHAT_APPID: 微信小程序AppIDWECHAT_SECRET: 微信小程序Secret
参考文件: app/core/settings.py
2. 计算机视觉核心系统(CVCore)集成
2.1 集成架构
flowchart LR
subgraph CVCore系统
A[图像上传服务]
B[图像识别服务]
C[对象存储服务]
end
subgraph 本系统
D[图像管理模块]
E[CV集成服务]
end
E --> A
E --> B
E --> C
D --> E
2.2 功能接口
2.2.1 图像上传接口
方法: upload_image_to_cvcore(image: bytes)
功能: 将图像上传到CVCore系统并返回存储信息
请求示例:
# 上传图像到CVCore
response = await upload_image_to_cvcore(image_data)
响应格式:
{
"file_url": "访问URL",
"file_mime": "文件类型",
"file_key": "存储键"
}
2.2.2 图像搜索接口
方法: sdk_search_image(key: str)
功能: 在CVCore系统中搜索匹配的图像
请求参数:
key: 图像在OSS中的存储键
参考文件: app/lib/cvcore.py
2.3 配置管理
CVCore集成通过以下配置参数控制：
cvc_target_url: CVCore服务地址cvc_api_key: API访问密钥
参考文件: app/core/settings.py
3. 数据模型集成
3.1 用户模型
系统用户模型支持微信OpenID绑定，实现多平台身份统一：
classDiagram
class User {
+Int id
+CharField username
+CharField password
+CharField email
+CharField sms
+CharField status
+CharField openid
+BooleanField is_system
+Int created_by
+Int updated_by
+DatetimeField created_at
+DatetimeField updated_at
}
class UserStatus {
<<enumeration>>
ACTIVE
INACTIVE
SUSPENDED
DELETED
}
User --> UserStatus : status字段引用
参考文件: app/models/user.py
4. 网络通信层
4.1 异步HTTP客户端
系统使用httpx库实现异步HTTP请求，支持与外部系统的稳定通信：
classDiagram
class AsyncRequests {
-AsyncClient client
+async get(url, **kwargs)
+async post(url, **kwargs)
+async close()
}
参考文件: app/lib/netrequest.py
4.2 错误处理机制
系统实现了完善的错误处理机制，包括：
- HTTP异常处理
- 网络超时处理
- 重试机制
- 日志记录
5. 安全集成规范
5.1 JWT认证
系统使用JWT进行API认证：
- 算法: HS256
- 密钥: 通过环境变量配置
- 过期时间: 300分钟
参考文件: app/core/settings.py
5.2 CORS配置
系统配置了宽松的CORS策略，支持跨域访问：
app.add_middleware(
CORSMiddleware,
allow_origins=["*"],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
参考文件: app/main.py
6. 部署与配置
6.1 环境配置
系统支持多环境部署，通过环境变量区分：
- 开发环境:
development - 测试环境:
staging - 生产环境:
production
6.2 服务端点
系统支持多个服务端点：
- 开发服务器: http://localhost:8001
- 测试服务器: https://api-staging.c0726.qualitysafeguard.com
- 生产服务器: https://api.c0726.qualitysafeguard.com
参考文件: app/main.py
索引
邮轮穿舱件管理系统后台通过标准化的接口规范与微信小程序、计算机视觉核心系统等外部服务实现了无缝集成。系统采用模块化设计，具有良好的扩展性和维护性，能够满足复杂的业务集成需求。
关键技术特点
- 标准化接口: 遵循RESTful API设计原则
- 异步通信: 使用异步HTTP客户端提高性能
- 安全认证: 完善的JWT认证和错误处理机制
- 配置灵活: 支持多环境部署和动态配置
- 文档完整: 提供详细的接口文档和错误码说明
后续扩展建议
- 增加API限流和熔断机制
- 完善监控和日志分析功能
- 支持更多的第三方服务集成
- 优化图像处理性能