forked from moyin/whale-town-front
docs：添加完整的项目文档体系
- 添加Web部署完整指南和更新日志 - 创建网络管理器配置文档 - 完善项目设置和测试指南 - 添加API更新日志和清理总结 - 更新脚本使用说明文档
This commit is contained in:
332
docs/api_update_log.md
Normal file
332
docs/api_update_log.md
Normal file
@@ -0,0 +1,332 @@
|
||||
# API接口更新日志
|
||||
|
||||
**更新日期**: 2025-12-25
|
||||
**API版本**: v1.1.1
|
||||
**更新内容**: 根据后端最新API文档更新前端接口逻辑和Toast显示
|
||||
|
||||
---
|
||||
|
||||
## 🎯 更新概述
|
||||
|
||||
根据后端API v1.1.1的最新文档，对前端的网络请求、响应处理和Toast显示系统进行了全面更新，以支持新的功能特性和错误处理机制。
|
||||
|
||||
---
|
||||
|
||||
## 📋 主要更新内容
|
||||
|
||||
### 1. **HTTP状态码支持**
|
||||
|
||||
#### 新增状态码处理
|
||||
- **206 Partial Content**: 测试模式响应
|
||||
- **409 Conflict**: 资源冲突（用户名、邮箱已存在）
|
||||
- **429 Too Many Requests**: 频率限制
|
||||
|
||||
#### 更新的状态码映射
|
||||
```gdscript
|
||||
const HTTP_STATUS_MESSAGES = {
|
||||
200: "请求成功",
|
||||
201: "创建成功",
|
||||
206: "测试模式",
|
||||
400: "请求参数错误",
|
||||
401: "认证失败",
|
||||
403: "权限不足",
|
||||
404: "资源不存在",
|
||||
408: "请求超时",
|
||||
409: "资源冲突", # 新增
|
||||
415: "不支持的媒体类型",
|
||||
429: "请求过于频繁", # 新增
|
||||
500: "服务器内部错误",
|
||||
503: "服务不可用"
|
||||
}
|
||||
```
|
||||
|
||||
### 2. **错误码映射更新**
|
||||
|
||||
#### 新增错误码
|
||||
- `SEND_EMAIL_VERIFICATION_FAILED`: 发送邮箱验证码失败
|
||||
- `RESEND_EMAIL_VERIFICATION_FAILED`: 重新发送验证码失败
|
||||
- `EMAIL_VERIFICATION_FAILED`: 邮箱验证失败
|
||||
- `RESET_PASSWORD_FAILED`: 重置密码失败
|
||||
- `CHANGE_PASSWORD_FAILED`: 修改密码失败
|
||||
- `USER_STATUS_UPDATE_FAILED`: 用户状态更新失败
|
||||
- `ADMIN_LOGIN_FAILED`: 管理员登录失败
|
||||
|
||||
### 3. **邮箱冲突检测**
|
||||
|
||||
#### 功能描述
|
||||
- 发送邮箱验证码前检查邮箱是否已被注册
|
||||
- 已注册邮箱返回409状态码和明确错误信息
|
||||
|
||||
#### 实现细节
|
||||
```gdscript
|
||||
# 在ResponseHandler中处理409冲突
|
||||
if response_code == 409:
|
||||
if "邮箱已存在" in message:
|
||||
result.message = "📧 邮箱已被注册，请使用其他邮箱或直接登录"
|
||||
elif "用户名已存在" in message:
|
||||
result.message = "👤 用户名已被使用，请换一个"
|
||||
```
|
||||
|
||||
### 4. **测试模式支持**
|
||||
|
||||
#### 功能描述
|
||||
- 开发环境下邮件服务返回206状态码
|
||||
- 验证码在响应中返回，无需真实发送邮件
|
||||
|
||||
#### 实现细节
|
||||
```gdscript
|
||||
# 处理206测试模式响应
|
||||
elif response_code == 206 and error_code == "TEST_MODE_ONLY":
|
||||
is_success = true
|
||||
print("🧪 测试模式响应: ", message)
|
||||
```
|
||||
|
||||
#### Toast显示优化
|
||||
```gdscript
|
||||
if error_code == "TEST_MODE_ONLY":
|
||||
result.message = "🧪 测试模式：验证码已生成，请查看控制台"
|
||||
if data.has("data") and data.data.has("verification_code"):
|
||||
print("🔑 测试模式验证码: ", data.data.verification_code)
|
||||
```
|
||||
|
||||
### 5. **频率限制处理**
|
||||
|
||||
#### 功能描述
|
||||
- 验证码发送限制1次/分钟
|
||||
- 注册限制10次/5分钟
|
||||
- 提供重试建议和详细错误信息
|
||||
|
||||
#### 实现细节
|
||||
```gdscript
|
||||
"TOO_MANY_REQUESTS":
|
||||
result.message = "⏰ 验证码发送过于频繁，请1分钟后再试"
|
||||
# 显示详细的限制信息
|
||||
if data.has("throttle_info"):
|
||||
var throttle_info = data.throttle_info
|
||||
var reset_time = throttle_info.get("reset_time", "")
|
||||
if reset_time != "":
|
||||
result.message += "\n重试时间: " + reset_time
|
||||
```
|
||||
|
||||
### 6. **Toast显示系统优化**
|
||||
|
||||
#### 视觉改进
|
||||
- 增加图标显示（✅成功，❌失败）
|
||||
- 更丰富的颜色和阴影效果
|
||||
- 支持智能换行和更大的显示区域
|
||||
- 更流畅的动画效果
|
||||
|
||||
#### 新的Toast样式
|
||||
```gdscript
|
||||
# 更深的颜色和更好的对比度
|
||||
if is_success:
|
||||
style.bg_color = Color(0.15, 0.7, 0.15, 0.95) # 深绿色
|
||||
style.border_color = Color(0.2, 0.9, 0.2, 0.9) # 亮绿色边框
|
||||
else:
|
||||
style.bg_color = Color(0.7, 0.15, 0.15, 0.95) # 深红色
|
||||
style.border_color = Color(0.9, 0.2, 0.2, 0.9) # 亮红色边框
|
||||
|
||||
# 添加阴影效果
|
||||
style.shadow_color = Color(0, 0, 0, 0.3)
|
||||
style.shadow_size = 4
|
||||
style.shadow_offset = Vector2(2, 2)
|
||||
```
|
||||
|
||||
#### 动画优化
|
||||
- 增加透明度动画
|
||||
- 延长显示时间（2秒→3秒）
|
||||
- 更流畅的滑入滑出效果
|
||||
|
||||
### 7. **新增API方法**
|
||||
|
||||
#### NetworkManager新增方法
|
||||
```gdscript
|
||||
# 重新发送邮箱验证码
|
||||
func resend_email_verification(email: String, callback: Callable) -> String
|
||||
|
||||
# 忘记密码 - 发送重置验证码
|
||||
func forgot_password(identifier: String, callback: Callable) -> String
|
||||
|
||||
# 重置密码
|
||||
func reset_password(identifier: String, verification_code: String, new_password: String, callback: Callable) -> String
|
||||
|
||||
# 修改密码
|
||||
func change_password(user_id: String, old_password: String, new_password: String, callback: Callable) -> String
|
||||
|
||||
# GitHub OAuth登录
|
||||
func github_login(github_id: String, username: String, nickname: String, email: String, avatar_url: String, callback: Callable) -> String
|
||||
```
|
||||
|
||||
#### ResponseHandler新增处理方法
|
||||
```gdscript
|
||||
# 处理重新发送邮箱验证码响应
|
||||
static func handle_resend_email_verification_response(success: bool, data: Dictionary, error_info: Dictionary) -> ResponseResult
|
||||
|
||||
# 处理忘记密码响应
|
||||
static func handle_forgot_password_response(success: bool, data: Dictionary, error_info: Dictionary) -> ResponseResult
|
||||
|
||||
# 处理重置密码响应
|
||||
static func handle_reset_password_response(success: bool, data: Dictionary, error_info: Dictionary) -> ResponseResult
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 技术改进
|
||||
|
||||
### 1. **响应处理逻辑优化**
|
||||
|
||||
#### 更精确的成功判断
|
||||
```gdscript
|
||||
# HTTP成功状态码且业务成功
|
||||
if (response_code >= 200 and response_code < 300) and success:
|
||||
is_success = true
|
||||
# 特殊情况：206测试模式
|
||||
elif response_code == 206 and error_code == "TEST_MODE_ONLY":
|
||||
is_success = true
|
||||
# 201创建成功
|
||||
elif response_code == 201:
|
||||
is_success = true
|
||||
```
|
||||
|
||||
#### 更详细的错误类型判断
|
||||
```gdscript
|
||||
match response_code:
|
||||
409: # 资源冲突
|
||||
return ErrorType.BUSINESS_ERROR
|
||||
206: # 测试模式
|
||||
return ErrorType.BUSINESS_ERROR
|
||||
429: # 频率限制
|
||||
return ErrorType.BUSINESS_ERROR
|
||||
```
|
||||
|
||||
### 2. **错误消息国际化**
|
||||
|
||||
#### 添加表情符号和更友好的提示
|
||||
- 📧 邮箱相关消息
|
||||
- 👤 用户相关消息
|
||||
- 🔑 验证码相关消息
|
||||
- 🔒 密码相关消息
|
||||
- ⏰ 时间相关消息
|
||||
- 🧪 测试模式消息
|
||||
- 🌐 网络相关消息
|
||||
|
||||
### 3. **代码结构优化**
|
||||
|
||||
#### 更好的模块化
|
||||
- 分离不同类型的错误处理方法
|
||||
- 统一的响应处理接口
|
||||
- 更清晰的方法命名
|
||||
|
||||
#### 更完善的注释
|
||||
- 详细的方法说明
|
||||
- 参数和返回值说明
|
||||
- 使用示例
|
||||
|
||||
---
|
||||
|
||||
## 🧪 测试验证
|
||||
|
||||
### 创建了API测试脚本
|
||||
- **文件**: `scripts/network/ApiTestScript.gd`
|
||||
- **功能**: 验证所有更新的API接口逻辑
|
||||
- **测试用例**:
|
||||
- 网络连接测试
|
||||
- 邮箱验证码发送
|
||||
- 邮箱冲突检测
|
||||
- 登录功能
|
||||
- 注册功能
|
||||
|
||||
### 测试覆盖的场景
|
||||
- ✅ 正常成功响应
|
||||
- ✅ 409邮箱冲突
|
||||
- ✅ 206测试模式
|
||||
- ✅ 429频率限制
|
||||
- ✅ 各种错误状态码
|
||||
- ✅ Toast显示效果
|
||||
|
||||
---
|
||||
|
||||
## 📚 使用指南
|
||||
|
||||
### 1. **发送邮箱验证码**
|
||||
```gdscript
|
||||
# 会自动检查邮箱冲突
|
||||
var request_id = NetworkManager.send_email_verification("user@example.com", callback)
|
||||
```
|
||||
|
||||
### 2. **处理409冲突**
|
||||
```gdscript
|
||||
func callback(success: bool, data: Dictionary, error_info: Dictionary):
|
||||
var result = ResponseHandler.handle_send_verification_code_response(success, data, error_info)
|
||||
if error_info.get("response_code") == 409:
|
||||
# 邮箱已存在，引导用户登录
|
||||
show_login_suggestion()
|
||||
```
|
||||
|
||||
### 3. **处理测试模式**
|
||||
```gdscript
|
||||
# 测试模式下验证码会在控制台显示
|
||||
if data.get("error_code") == "TEST_MODE_ONLY":
|
||||
var verification_code = data.data.verification_code
|
||||
print("测试验证码: ", verification_code)
|
||||
```
|
||||
|
||||
### 4. **处理频率限制**
|
||||
```gdscript
|
||||
# 提供重试建议
|
||||
if error_info.get("response_code") == 429:
|
||||
show_retry_suggestion(data.get("throttle_info", {}))
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 向后兼容性
|
||||
|
||||
### 保持的兼容性
|
||||
- ✅ 现有的API调用方式不变
|
||||
- ✅ 现有的回调函数签名不变
|
||||
- ✅ 现有的Toast显示接口不变
|
||||
|
||||
### 新增的功能
|
||||
- ✅ 更丰富的错误处理
|
||||
- ✅ 更好的用户体验
|
||||
- ✅ 更详细的状态反馈
|
||||
|
||||
---
|
||||
|
||||
## 📝 注意事项
|
||||
|
||||
### 开发环境
|
||||
- 测试模式下验证码会在控制台显示
|
||||
- 206状态码表示测试模式，属于成功响应
|
||||
- 建议在开发时关注控制台输出
|
||||
|
||||
### 生产环境
|
||||
- 验证码通过真实邮件发送
|
||||
- 需要正确配置邮件服务
|
||||
- 频率限制会严格执行
|
||||
|
||||
### 错误处理
|
||||
- 优先检查HTTP状态码
|
||||
- 再检查业务错误码
|
||||
- 提供用户友好的错误提示
|
||||
|
||||
---
|
||||
|
||||
## 🚀 后续计划
|
||||
|
||||
### 短期优化
|
||||
- [ ] 添加更多的API接口支持
|
||||
- [ ] 优化Toast显示的动画效果
|
||||
- [ ] 添加音效反馈
|
||||
|
||||
### 长期规划
|
||||
- [ ] 支持多语言错误消息
|
||||
- [ ] 添加离线模式支持
|
||||
- [ ] 实现请求重试机制
|
||||
|
||||
---
|
||||
|
||||
**更新完成时间**: 2025-12-25
|
||||
**测试状态**: ✅ 已通过基础测试
|
||||
**部署建议**: 建议在测试环境充分验证后再部署到生产环境
|
||||
Reference in New Issue
Block a user