微信API文档
概述
本文档详细记录了邮轮穿舱件管理系统后台中微信小程序相关的所有接口，包括用户绑定、登录认证、用户管理和图片识别等功能。通过分析wechat目录下的所有组件，提供了完整的接口说明、代码结构分析和依赖关系映射。
目录结构
1. 微信模块架构
微信模块采用分层架构设计，包含路由层、服务层和数据模型层。所有微信相关接口都集中在app/routers/wechat目录下。
flowchart TD
subgraph 微信模块架构
A[微信路由层] --> B[用户服务层]
A --> C[图片服务层]
A --> D[工单服务层]
B --> E[用户数据模型]
C --> F[图片数据模型]
D --> G[工单数据模型]
end
文件引用：
2. 接口详细说明
2.1 用户绑定接口
接口路径： POST /miniapp/bind
功能描述： 通过微信code绑定系统用户，支持现有用户绑定和新用户创建。
请求参数：
{
"code": "微信登录凭证",
"username": "用户名",
"password": "密码"
}
响应模型： UserSchemaOut
业务逻辑流程图：
flowchart TD
A[接收绑定请求] --> B{微信配置检查}
B -->|配置缺失| C[返回500错误]
B -->|配置正常| D[调用微信jscode2session]
D --> E{微信API响应}
E -->|API错误| F[返回400错误]
E -->|成功| G{用户是否存在}
G -->|不存在| H[返回404错误]
G -->|存在| I[密码验证]
I -->|验证失败| J[返回401错误]
I -->|验证成功| K[更新用户openid]
K --> L[返回绑定成功]
核心代码逻辑：
- 微信配置验证
- 微信API调用获取openid
- 用户存在性检查
- 密码验证
- OpenID绑定更新
文件引用：
2.2 登录认证接口
2.2.1 自动注册登录
接口路径： POST /wechat/loginWithAutoRegister
功能描述： 微信小程序自动注册登录，用户不存在时自动创建。
请求参数：
{
"code": "微信登录凭证"
}
响应模型： OAuthBearerToken
2.2.2 用户名密码登录
接口路径： POST /wechat/loginWithUsrPwd
功能描述： 微信小程序用户名密码登录，要求用户已绑定微信。
请求参数：
{
"code": "微信登录凭证",
"username": "用户名",
"password": "密码"
}
登录流程序列图：
sequenceDiagram
participant Client as 微信小程序
participant API as 微信登录API
participant WeChat as 微信服务器
participant UserService as 用户服务
Client->>API: POST /wechat/loginWithAutoRegister
API->>WeChat: jscode2session API调用
WeChat-->>API: 返回openid
API->>UserService: 根据openid查询用户
alt 用户不存在
UserService-->>API: 用户不存在
API->>UserService: 自动创建用户
UserService-->>API: 创建成功
else 用户存在
UserService-->>API: 返回用户信息
end
API->>API: 生成JWT Token
API-->>Client: 返回Bearer Token
文件引用：
2.3 用户管理接口
2.3.1 获取用户资料
接口路径： GET /miniapp/user/userProfile
功能描述： 获取当前登录用户的详细信息。
认证要求： JWT Token认证
响应模型： UserSchemaOut
2.3.2 更新用户资料
接口路径： PUT /miniapp/user/userProfile
功能描述： 更新当前登录用户的个人信息。
请求参数：
{
"username": "新用户名",
"email": "邮箱",
"sms": "手机号"
}
认证要求： JWT Token认证
文件引用：
2.4 图片识别接口
接口路径： GET /miniapp/image/workpiece/{workpiece_id}/images
功能描述： 根据产品ID获取对应的产品图片列表。
路径参数：
workpiece_id: 产品ID（整数）
响应模型： 图片实体列表
文件引用：
2.5 统计管理接口
接口路径： GET /miniapp/statistics/brief
功能描述： 获取工单统计摘要信息。
认证要求： JWT Token认证
响应数据：
{
"total_tickets": 100,
"open_tickets": 30,
"closed_tickets": 70
}
文件引用：
3. 代码结构分析
3.1 模块依赖关系
微信模块的代码结构采用清晰的层次分离：
graph TD
A[微信路由层] --> B[核心服务层]
A --> C[数据模型层]
B --> D[微信API调用]
B --> E[用户认证服务]
B --> F[数据持久化]
subgraph 路由模块
A1[bind.py] --> A
A2[login.py] --> A
A3[user.py] --> A
A4[image.py] --> A
A5[statistics.py] --> A
end
subgraph 服务模块
B1[user_service.py] --> B
B2[image_service.py] --> B
B3[ticket_service.py] --> B
end
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 UserStatus {
<<enumeration>>
ACTIVE
INACTIVE
SUSPENDED
DELETED
}
User --> UserStatus : 使用状态枚举
文件引用：
4. 依赖关系映射
4.1 外部依赖
flowchart LR
A[微信模块] --> B[FastAPI框架]
A --> C[Tortoise ORM]
A --> D[微信API]
A --> E[bcrypt加密]
A --> F[httpx HTTP客户端]
4.2 内部依赖关系
微信绑定模块依赖：
app.core.settings- 系统配置app.core.loggers- 日志记录app.schemas.user_schema- 用户数据模型app.service.user_service- 用户服务
微信登录模块依赖：
app.core.authorize- JWT认证app.core.util- 工具函数app.service.user_service- 用户服务
5. 数据模型说明
5.1 用户状态枚举
class UserStatus(Enum):
ACTIVE = "active" # 活跃状态
INACTIVE = "inactive" # 非活跃状态
SUSPENDED = "suspended" # 暂停状态
DELETED = "deleted" # 删除状态
5.2 用户模型字段说明
| 字段名 | 类型 | 说明 | 约束 |
|---|---|---|---|
| id | IntField | 主键ID | 主键 |
| username | CharField | 用户名 | 唯一，非空 |
| password | CharField | 密码哈希 | 非空 |
| CharField | 邮箱地址 | 唯一，可空 | |
| sms | CharField | 手机号码 | 可空 |
| status | CharField | 用户状态 | 非空，默认active |
| openid | CharField | 微信OpenID | 可空 |
| is_system | BooleanField | 系统用户标志 | 非空，默认False |
文件引用：
6. 错误处理机制
6.1 微信API错误处理
微信模块实现了完善的错误处理机制：
flowchart TD
A[微信API调用] --> B{配置检查}
B -->|配置缺失| C[返回500内部错误]
B -->|配置正常| D[API请求]
D --> E{请求成功}
E -->|网络错误| F[返回502网关错误]
E -->|API错误| G[返回400客户端错误]
E -->|成功但数据异常| H[返回502网关错误]
E -->|完全成功| I[继续业务流程]
6.2 业务逻辑错误处理
用户认证错误：
- 用户不存在：返回404状态码
- 密码错误：返回401状态码
- 用户状态异常：返回403状态码
数据完整性错误：
- 用户名重复：IntegrityError异常
- 邮箱重复：IntegrityError异常
6.3 安全考虑
- 密码安全：使用bcrypt进行密码哈希
- 认证机制：JWT Token认证
- 输入验证：Pydantic模型验证
- 错误信息：避免泄露敏感信息
文件引用：
索引
微信模块为邮轮穿舱件管理系统提供了完整的微信小程序集成方案，包括用户绑定、登录认证、用户管理和业务功能接口。模块设计遵循了良好的架构原则，具有清晰的依赖关系和完整的错误处理机制。
核心特性：
- 支持微信自动注册和绑定登录
- 完整的用户状态管理
- 安全的密码处理和认证机制
- 模块化的代码结构设计
- 完善的错误处理和日志记录
该模块为微信小程序提供了稳定可靠的后端支持，确保了系统的安全性和可用性。