From 190b6c9a66739963b82df2d4565d6258c6440d69 Mon Sep 17 00:00:00 2001 From: moyin <2443444649@qq.com> Date: Wed, 31 Dec 2025 17:27:13 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B8=85=E7=90=86=E6=80=BB=E7=BB=93?= =?UTF-8?q?=E6=80=A7=E6=96=87=E6=A1=A3=EF=BC=8C=E4=BF=9D=E7=95=99=E8=A7=84?= =?UTF-8?q?=E8=8C=83=E7=B1=BB=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 删除 docs/CONTRIBUTORS.md (总结性文档) - 删除 docs/api_update_log.md (已不存在) - 删除 docs/cleanup_summary.md (已不存在) - 保留 docs/module_development.md (开发规范) - 保留 docs/performance_optimization.md (性能规范) - 保留 docs/scene_design.md (设计规范) --- docs/CONTRIBUTORS.md | 200 ------------------------ docs/api_update_log.md | 332 ---------------------------------------- docs/cleanup_summary.md | 137 ----------------- 3 files changed, 669 deletions(-) delete mode 100644 docs/CONTRIBUTORS.md delete mode 100644 docs/api_update_log.md delete mode 100644 docs/cleanup_summary.md diff --git a/docs/CONTRIBUTORS.md b/docs/CONTRIBUTORS.md deleted file mode 100644 index 40e298b..0000000 --- a/docs/CONTRIBUTORS.md +++ /dev/null @@ -1,200 +0,0 @@ -# 贡献者名单 - -感谢所有为 Whale Town 项目做出贡献的开发者！ - -## 🏆 核心团队 - -### 项目负责人 -- **[moyin](https://gitea.xinghangee.icu/moyin)** - 项目架构师 & 核心开发者 - - 负责项目整体架构设计 - - 用户认证系统开发 - - 代码审查和质量控制 - -### 核心开发者 -- **[jianuo](https://gitea.xinghangee.icu/jianuo)** - 前端开发专家 - - Godot引擎集成和优化 - - UI/UX设计和实现 - - 游戏核心功能开发 - -- **[angjustinl](https://gitea.xinghangee.icu/ANGJustinl)** - 系统架构师 - - 模块化架构设计 - - 性能优化和调试 - - 测试框架建设 - -## 🌟 贡献统计 - -### 代码贡献 -| 贡献者 | 提交数 | 代码行数 | 主要贡献领域 | -|--------|--------|----------|--------------| -| moyin | 50+ | 5000+ | 架构设计、认证系统 | -| jianuo | 40+ | 4000+ | UI开发、游戏逻辑 | -| angjustinl | 30+ | 3000+ | 系统优化、测试 | - -### 文档贡献 -- **项目文档**: moyin, jianuo, angjustinl -- **API文档**: moyin -- **开发规范**: 全体核心团队 -- **用户指南**: jianuo - -### 测试贡献 -- **单元测试**: angjustinl, moyin -- **集成测试**: 全体核心团队 -- **性能测试**: angjustinl -- **用户测试**: jianuo - -## 🎯 贡献领域 - -### 🔧 技术贡献 -- **架构设计** - 模块化系统设计和实现 -- **前端开发** - Godot场景和UI组件开发 -- **后端集成** - API接口集成和网络通信 -- **性能优化** - 游戏性能调优和资源管理 -- **测试开发** - 自动化测试和质量保证 - -### 📚 文档贡献 -- **技术文档** - API文档、架构文档 -- **开发指南** - 编码规范、最佳实践 -- **用户文档** - 使用说明、教程指南 -- **项目管理** - 需求分析、项目规划 - -### 🎨 设计贡献 -- **UI/UX设计** - 界面设计和用户体验优化 -- **游戏设计** - 游戏机制和玩法设计 -- **视觉设计** - 图标、插画、动画设计 -- **音频设计** - 音效、音乐制作 - -## 🚀 里程碑贡献 - -### v1.0.0 - 基础框架 (2025-12) -- **moyin**: 项目初始化和架构设计 -- **jianuo**: Godot项目搭建和基础场景 -- **angjustinl**: 核心系统和管理器实现 - -### v1.1.0 - 用户认证 (2025-12) -- **moyin**: 认证系统后端集成 -- **jianuo**: 认证界面设计和实现 -- **angjustinl**: 验证码系统优化 - -### v1.2.0 - 模块化重构 (规划中) -- **全体团队**: 模块化架构重构 -- **社区贡献者**: 新功能模块开发 - -## 🤝 如何成为贡献者 - -### 贡献方式 -1. **代码贡献** - 提交Bug修复和新功能 -2. **文档贡献** - 完善项目文档和教程 -3. **测试贡献** - 编写测试用例和质量保证 -4. **设计贡献** - UI/UX设计和游戏设计 -5. **社区贡献** - 帮助其他开发者和用户 - -### 贡献流程 -1. **Fork项目** - 创建项目副本 -2. **创建分支** - 为新功能创建专门分支 -3. **开发功能** - 遵循项目规范进行开发 -4. **提交PR** - 创建Pull Request -5. **代码审查** - 核心团队进行代码审查 -6. **合并代码** - 审查通过后合并到主分支 - -### 贡献要求 -- 遵循项目的[代码规范](./naming_convention.md) -- 添加适当的[测试用例](../tests/) -- 更新相关[文档](./README.md) -- 使用规范的[提交信息](./git_commit_guide.md) - -## 🏅 贡献者权益 - -### 认可和奖励 -- **贡献者徽章** - 在项目中展示贡献者身份 -- **技术分享** - 优先参与技术分享和讨论 -- **项目决策** - 参与重要功能的设计讨论 -- **学习机会** - 接触最新技术和最佳实践 - -### 成长路径 -1. **新手贡献者** - 修复简单Bug，完善文档 -2. **活跃贡献者** - 开发新功能，参与设计讨论 -3. **核心贡献者** - 负责重要模块，指导新人 -4. **维护者** - 项目管理，技术决策 - -## 📊 贡献统计 - -### 月度活跃贡献者 (2025-12) -1. moyin - 15 commits -2. jianuo - 12 commits -3. angjustinl - 10 commits - -### 累计贡献排行 -1. moyin - 120+ commits, 10000+ lines -2. jianuo - 95+ commits, 8000+ lines -3. angjustinl - 80+ commits, 6000+ lines - -### 贡献类型分布 -- 代码贡献: 70% -- 文档贡献: 20% -- 测试贡献: 10% - -## 🎉 特别感谢 - -### 技术支持 -- **Godot社区** - 提供优秀的游戏引擎和技术支持 -- **开源社区** - 提供各种优秀的开源工具和库 - -### 测试反馈 -- **内测用户** - 提供宝贵的测试反馈和建议 -- **社区用户** - 报告Bug和提出改进建议 - -### 设计灵感 -- **像素游戏社区** - 提供设计灵感和创意想法 -- **独立游戏开发者** - 分享开发经验和最佳实践 - -## 📞 联系贡献者 - -### 核心团队联系方式 -- **项目讨论**: [Gitea Discussions](https://gitea.xinghangee.icu/datawhale/whale-town/discussions) -- **技术交流**: [Issues](https://gitea.xinghangee.icu/datawhale/whale-town/issues) -- **即时沟通**: 项目内部群组 - -### 贡献者社区 -- **新手指导** - 核心团队提供一对一指导 -- **技术分享** - 定期举办技术分享会 -- **代码审查** - 专业的代码审查和反馈 - -## 🔮 未来规划 - -### 团队扩展 -- 招募更多前端开发者 -- 寻找游戏设计专家 -- 欢迎UI/UX设计师加入 - -### 技术发展 -- 探索新的游戏技术 -- 优化性能和用户体验 -- 扩展平台支持 - -### 社区建设 -- 建立贡献者激励机制 -- 完善新手指导体系 -- 加强社区交流和合作 - ---- - -## 📝 贡献者协议 - -通过向本项目贡献代码，您同意： - -1. **开源协议** - 您的贡献将遵循项目的MIT开源协议 -2. **代码质量** - 遵循项目的代码规范和质量标准 -3. **知识产权** - 确保贡献的代码不侵犯第三方知识产权 -4. **持续维护** - 对您贡献的代码承担一定的维护责任 - ---- - -
- -**🙏 感谢每一位贡献者的付出！** - -**让我们一起打造更好的 Whale Town！** - -[🚀 开始贡献](../README.md#🤝-贡献指南) | [📖 开发指南](./module_development.md) | [💬 加入讨论](https://gitea.xinghangee.icu/datawhale/whale-town/discussions) - -
\ No newline at end of file diff --git a/docs/api_update_log.md b/docs/api_update_log.md deleted file mode 100644 index 2c3ffed..0000000 --- a/docs/api_update_log.md +++ /dev/null @@ -1,332 +0,0 @@ -# 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 -**测试状态**: ✅ 已通过基础测试 -**部署建议**: 建议在测试环境充分验证后再部署到生产环境 \ No newline at end of file diff --git a/docs/cleanup_summary.md b/docs/cleanup_summary.md deleted file mode 100644 index 42a7ccd..0000000 --- a/docs/cleanup_summary.md +++ /dev/null @@ -1,137 +0,0 @@ -# AuthScene 文件清理总结 - -**清理日期**: 2025-12-25 -**清理原因**: 修复Parser Error和优化代码结构 - ---- - -## 🔧 修复的问题 - -### 1. **Parser Error修复** -- **问题**: `scripts/scenes/AuthScene.gd` 第1196行有语法错误 "母和数字" -- **解决**: 完全重写了AuthScene.gd文件，移除了所有语法错误 -- **结果**: 文件现在可以正常解析，无语法错误 - -### 2. **代码结构优化** -- **重构验证逻辑**: 使用StringUtils工具类统一处理验证 -- **简化代码**: 移除重复的验证代码 -- **提高可维护性**: 更清晰的方法组织和注释 - ---- - -## 🗑️ 删除的文件 - -### 已删除 -1. **`scripts/network/NetworkTest.gd`** - - **原因**: 功能重复，已有更完善的ApiTestScript.gd - - **影响**: 无，功能已被ApiTestScript.gd替代 - -### 保留的文件 -1. **`tests/auth/auth_ui_test.gd`** - 保留，用于UI测试 -2. **`tests/auth/enhanced_toast_test.gd`** - 保留，用于Toast系统测试 -3. **`core/utils/StringUtils.gd`** - 保留，提供通用验证工具 - ---- - -## ✅ 优化后的AuthScene.gd结构 - -### 文件组织 -``` -AuthScene.gd (约600行，结构清晰) -├── 节点引用和变量定义 -├── 初始化和信号连接 -├── 按钮事件处理 -├── 网络响应处理 -├── 验证码冷却管理 -├── Toast消息系统 -├── UI工具方法 -├── 表单验证方法 -├── 表单验证事件 -└── 资源清理 -``` - -### 主要改进 -1. **使用StringUtils**: 统一的验证逻辑 -2. **清晰的方法分组**: 按功能组织代码 -3. **完整的错误处理**: 支持最新API v1.1.1 -4. **优化的Toast系统**: 更好的视觉效果和动画 - ---- - -## 🧪 测试验证 - -### 语法检查 -```bash -# 所有文件通过语法检查 -✅ scripts/scenes/AuthScene.gd - No diagnostics found -✅ core/managers/NetworkManager.gd - No diagnostics found -✅ core/managers/ResponseHandler.gd - No diagnostics found -``` - -### 功能测试 -- ✅ Toast显示系统正常 -- ✅ 表单验证逻辑正确 -- ✅ 网络请求处理完整 -- ✅ 验证码冷却机制有效 - ---- - -## 📊 代码质量提升 - -### 前后对比 -| 指标 | 清理前 | 清理后 | 改进 | -|------|--------|--------|------| -| 语法错误 | 1个 | 0个 | ✅ 修复 | -| 代码行数 | ~1400行 | ~600行 | ✅ 精简57% | -| 重复代码 | 多处 | 无 | ✅ 消除 | -| 可读性 | 中等 | 高 | ✅ 提升 | -| 维护性 | 中等 | 高 | ✅ 提升 | - -### 代码质量指标 -- **圈复杂度**: 降低 -- **代码重复率**: 显著减少 -- **方法长度**: 更合理 -- **注释覆盖**: 完整 - ---- - -## 🔄 兼容性保证 - -### API兼容性 -- ✅ 保持所有公共方法签名不变 -- ✅ 保持所有信号定义不变 -- ✅ 保持节点引用路径不变 - -### 功能兼容性 -- ✅ 登录功能完整 -- ✅ 注册功能完整 -- ✅ 验证码功能完整 -- ✅ Toast显示功能增强 - ---- - -## 📝 后续建议 - -### 短期 -1. **测试验证**: 在实际环境中测试所有功能 -2. **性能监控**: 观察Toast动画性能 -3. **用户反馈**: 收集UI体验反馈 - -### 长期 -1. **单元测试**: 为验证逻辑添加更多单元测试 -2. **集成测试**: 完善端到端测试覆盖 -3. **代码审查**: 定期进行代码质量审查 - ---- - -## 🎯 总结 - -通过这次清理，我们成功： - -1. **修复了语法错误** - AuthScene.gd现在可以正常解析 -2. **优化了代码结构** - 更清晰、更易维护 -3. **提升了代码质量** - 减少重复，提高可读性 -4. **保持了功能完整** - 所有原有功能都得到保留和增强 -5. **删除了冗余文件** - 清理了不必要的测试文件 - -AuthScene现在是一个干净、高效、易维护的认证界面组件，完全支持最新的API v1.1.1规范。 \ No newline at end of file