whale-town-front/docs/api_update_log.md

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: 频率限制

更新的状态码映射

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状态码和明确错误信息

实现细节

# 在ResponseHandler中处理409冲突
if response_code == 409:
    if "邮箱已存在" in message:
        result.message = "📧 邮箱已被注册，请使用其他邮箱或直接登录"
    elif "用户名已存在" in message:
        result.message = "👤 用户名已被使用，请换一个"

4. 测试模式支持

功能描述

• 开发环境下邮件服务返回206状态码
• 验证码在响应中返回，无需真实发送邮件

实现细节

# 处理206测试模式响应
elif response_code == 206 and error_code == "TEST_MODE_ONLY":
    is_success = true
    print("🧪 测试模式响应: ", message)

Toast显示优化

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分钟
• 提供重试建议和详细错误信息

实现细节

"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样式

# 更深的颜色和更好的对比度
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新增方法

# 重新发送邮箱验证码
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新增处理方法

# 处理重新发送邮箱验证码响应
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. 响应处理逻辑优化

更精确的成功判断

# 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

更详细的错误类型判断

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. 发送邮箱验证码

# 会自动检查邮箱冲突
var request_id = NetworkManager.send_email_verification("user@example.com", callback)

2. 处理409冲突

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. 处理测试模式

# 测试模式下验证码会在控制台显示
if data.get("error_code") == "TEST_MODE_ONLY":
    var verification_code = data.data.verification_code
    print("测试验证码: ", verification_code)

4. 处理频率限制

# 提供重试建议
if error_info.get("response_code") == 429:
    show_retry_suggestion(data.get("throttle_info", {}))

---

🔄 向后兼容性

保持的兼容性

• ✅ 现有的API调用方式不变
• ✅ 现有的回调函数签名不变
• ✅ 现有的Toast显示接口不变

新增的功能

• ✅ 更丰富的错误处理
• ✅ 更好的用户体验
• ✅ 更详细的状态反馈

---

📝 注意事项

开发环境

• 测试模式下验证码会在控制台显示
• 206状态码表示测试模式，属于成功响应
• 建议在开发时关注控制台输出

生产环境

• 验证码通过真实邮件发送
• 需要正确配置邮件服务
• 频率限制会严格执行

错误处理

• 优先检查HTTP状态码
• 再检查业务错误码
• 提供用户友好的错误提示

---

🚀 后续计划

短期优化

• 添加更多的API接口支持
• 优化Toast显示的动画效果
• 添加音效反馈

长期规划

• 支持多语言错误消息
• 添加离线模式支持
• 实现请求重试机制

---

更新完成时间: 2025-12-25
测试状态: ✅ 已通过基础测试
部署建议: 建议在测试环境充分验证后再部署到生产环境