docs: 重新组织文档结构，按开发阶段分类

新的目录结构:
  01-项目入门/     # 新人必读，项目基础
  02-开发规范/     # 编码标准和规范
  03-技术实现/     # 具体开发指导
  04-高级开发/     # 进阶开发技巧
  05-部署运维/     # 发布和部署
  06-功能模块/     # 特定功能文档

 新增导航文档:
- docs/README.md - 完整的文档导航和使用指南
- 各目录下的README.md - 分类说明和使用指导

 优化效果:
- 开发者可以按阶段快速定位需要的文档
- 新人有清晰的学习路径
- 不同角色有针对性的文档推荐
- 提供了问题导向的快速查找功能

docs/06-功能模块/auth/表单验证规范.md

@@ -0,0 +1,324 @@
+# 表单验证规范文档
+
+## 概述
+
+本文档详细说明了登录和注册表单的验证规则、UI交互规范和错误处理机制。
+
+## 验证规则
+
+### 1. 用户名验证
+
+#### 规则
+- **必填项**: 是
+- **长度**: 1-50字符
+- **格式**: 只能包含字母、数字和下划线
+- **正则表达式**: `^[a-zA-Z0-9_]+$`
+
+#### 错误提示
+- 空值: "用户名不能为空"
+- 长度不符: "用户名长度应为1-50字符"
+- 格式错误: "用户名只能包含字母、数字和下划线"
+
+### 2. 邮箱验证
+
+#### 规则
+- **必填项**: 是（注册时）
+- **格式**: 标准邮箱格式
+- **正则表达式**: `^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$`
+
+#### 错误提示
+- 空值: "邮箱不能为空"
+- 格式错误: "请输入有效的邮箱地址"
+
+### 3. 密码验证
+
+#### 规则
+- **必填项**: 是
+- **长度**: 8-128字符
+- **复杂度**: 必须包含字母和数字
+- **安全性**: 不允许纯数字或纯字母
+
+#### 错误提示
+- 空值: "密码不能为空"
+- 长度不足: "密码长度至少8位"
+- 长度超限: "密码长度不能超过128位"
+- 复杂度不够: "密码必须包含字母和数字"
+
+### 4. 确认密码验证
+
+#### 规则
+- **必填项**: 是（注册时）
+- **一致性**: 必须与密码字段完全一致
+
+#### 错误提示
+- 空值: "确认密码不能为空"
+- 不一致: "两次输入的密码不一致"
+
+### 5. 验证码验证
+
+#### 规则
+- **必填项**: 是（注册时）
+- **长度**: 6位数字
+- **格式**: 纯数字
+- **有效性**: 必须先获取验证码
+
+#### 错误提示
+- 空值: "验证码不能为空"
+- 长度错误: "验证码必须是6位数字"
+- 格式错误: "验证码必须是6位数字"
+- 未获取: "请先获取邮箱验证码"
+
+## UI交互规范
+
+### 1. 必填项标识
+
+所有必填字段都使用水平布局来显示标签、红色星号和右对齐的错误提示：
+
+#### 结构设计
+```
+VBoxContainer (字段容器)
+├── HBoxContainer (标签和错误提示容器)
+│   ├── Label (字段名称)
+│   ├── Label (红色星号 " *")
+│   ├── Control (弹性空间) [size_flags_horizontal = 3]
+│   └── Label (红色错误提示) [右对齐，默认隐藏]
+└── LineEdit (输入框)
+```
+
+#### 视觉效果
+- **标签**: 黑色文本，如 "用户名"、"邮箱"、"密码"
+- **星号**: 红色文本 `Color(1, 0.2, 0.2, 1)`，内容为 " *"
+- **弹性空间**: Control节点，`size_flags_horizontal = 3`，占据剩余空间
+- **错误提示**: 红色文本，12px字体，右对齐显示 (`horizontal_alignment = 2`)
+- **布局**: 标签和星号左对齐，错误提示右对齐
+
+#### 交互行为
+- **正常状态**: 显示 `用户名 *                    `
+- **错误状态**: 显示 `用户名 *          用户名不能为空`
+- **输入时**: 错误提示自动隐藏，回到正常状态
+
+#### 优势
+- 错误提示右对齐，与输入框右边缘对齐，视觉更整齐
+- 利用弹性空间实现左右分布，布局更美观
+- 不占用额外的垂直空间
+- 避免UI布局被拉长导致溢出
+- 保持界面紧凑美观
+- 红色星号和错误提示颜色一致，视觉统一
+- 错误提示位置固定，不会因为文本长度变化而影响布局
+
+### 2. 实时验证
+
+#### 失焦验证
+- 当用户离开输入框时（`focus_exited`）触发验证
+- 立即显示相应的错误提示
+- 错误提示显示在输入框下方
+
+#### 输入时验证
+- 当用户开始输入时（`text_changed`）隐藏错误提示
+- 提供即时的视觉反馈
+- 避免在用户输入过程中显示错误
+
+### 3. 错误提示样式
+
+#### 视觉设计
+- **颜色**: 红色 `Color(1, 0.2, 0.2, 1)`
+- **字体大小**: 12px
+- **位置**: 输入框正下方
+- **显示状态**: 默认隐藏，验证失败时显示
+
+#### 错误信息特点
+- 简洁明了，直接指出问题
+- 提供解决建议
+- 使用友好的语言
+
+### 4. 按钮状态管理
+
+#### 发送验证码按钮
+- **正常状态**: "发送验证码"
+- **冷却状态**: "重新发送(60)" (倒计时)
+- **禁用状态**: 请求进行中时禁用
+
+#### 提交按钮
+- **正常状态**: 可点击
+- **禁用状态**: 表单验证失败或请求进行中时禁用
+- **加载状态**: 显示"正在注册..."等提示
+
+## 验证流程
+
+### 1. 登录表单验证流程
+
+```
+用户输入 → 失焦验证 → 显示错误(如有) → 点击登录 → 整体验证 → 提交请求
+```
+
+#### 验证步骤
+1. 检查用户名是否为空
+2. 检查密码是否为空
+3. 所有验证通过后提交登录请求
+
+### 2. 注册表单验证流程
+
+```
+用户输入 → 失焦验证 → 显示错误(如有) → 获取验证码 → 输入验证码 → 点击注册 → 整体验证 → 邮箱验证 → 用户注册
+```
+
+#### 验证步骤
+1. 验证用户名格式和长度
+2. 验证邮箱格式
+3. 验证密码强度
+4. 验证确认密码一致性
+5. 验证验证码格式和有效性
+6. 发送邮箱验证请求
+7. 验证成功后发送注册请求
+
+### 3. 验证码获取流程
+
+```
+输入邮箱 → 验证邮箱格式 → 检查冷却时间 → 发送验证码 → 开始冷却计时
+```
+
+#### 冷却机制
+- **冷却时间**: 60秒
+- **按钮状态**: 显示倒计时
+- **重复发送**: 冷却结束后可重新发送
+
+## 错误处理机制
+
+### 1. 客户端验证
+
+#### 即时验证
+- 在用户输入过程中提供即时反馈
+- 防止用户提交无效数据
+- 提升用户体验
+
+#### 提交前验证
+- 在发送请求前进行完整验证
+- 确保所有必填项都已正确填写
+- 避免无效的网络请求
+
+### 2. 服务器验证
+
+#### 后端验证
+- 服务器端进行二次验证
+- 处理服务器返回的错误信息
+- 显示相应的错误提示
+
+#### 网络错误处理
+- 连接失败提示
+- 超时处理
+- 服务器错误提示
+
+### 3. 用户引导
+
+#### 错误恢复
+- 清晰的错误提示
+- 提供解决方案
+- 引导用户正确操作
+
+#### 成功反馈
+- 注册成功提示
+- 自动跳转到登录界面
+- 自动填充用户名
+
+## 代码实现
+
+### 1. 验证函数
+
+每个字段都有对应的验证函数：
+- `validate_username(username: String) -> Dictionary`
+- `validate_email(email: String) -> Dictionary`
+- `validate_password(password: String) -> Dictionary`
+- `validate_confirm_password(password: String, confirm: String) -> Dictionary`
+- `validate_verification_code(code: String) -> Dictionary`
+
+### 2. 事件处理
+
+#### 失焦事件
+- `_on_register_username_focus_exited()`
+- `_on_register_email_focus_exited()`
+- `_on_register_password_focus_exited()`
+- `_on_register_confirm_focus_exited()`
+- `_on_verification_focus_exited()`
+
+#### 输入事件
+- `_on_register_username_text_changed(new_text: String)`
+- `_on_register_email_text_changed(new_text: String)`
+- `_on_register_password_text_changed(new_text: String)`
+- `_on_register_confirm_text_changed(new_text: String)`
+- `_on_verification_text_changed(new_text: String)`
+
+### 3. 整体验证
+
+- `validate_login_form() -> bool`
+- `validate_register_form() -> bool`
+
+## 测试用例
+
+### 1. 用户名测试
+
+| 输入 | 预期结果 | 错误信息 |
+|------|----------|----------|
+| "" | 失败 | "用户名不能为空" |
+| "a" | 成功 | - |
+| "test_user123" | 成功 | - |
+| "test@user" | 失败 | "用户名只能包含字母、数字和下划线" |
+| "a".repeat(51) | 失败 | "用户名长度应为1-50字符" |
+
+### 2. 邮箱测试
+
+| 输入 | 预期结果 | 错误信息 |
+|------|----------|----------|
+| "" | 失败 | "邮箱不能为空" |
+| "test@example.com" | 成功 | - |
+| "invalid-email" | 失败 | "请输入有效的邮箱地址" |
+| "test@" | 失败 | "请输入有效的邮箱地址" |
+
+### 3. 密码测试
+
+| 输入 | 预期结果 | 错误信息 |
+|------|----------|----------|
+| "" | 失败 | "密码不能为空" |
+| "1234567" | 失败 | "密码长度至少8位" |
+| "12345678" | 失败 | "密码必须包含字母和数字" |
+| "abcdefgh" | 失败 | "密码必须包含字母和数字" |
+| "abc12345" | 成功 | - |
+
+### 4. 验证码测试
+
+| 输入 | 预期结果 | 错误信息 |
+|------|----------|----------|
+| "" | 失败 | "验证码不能为空" |
+| "12345" | 失败 | "验证码必须是6位数字" |
+| "1234567" | 失败 | "验证码必须是6位数字" |
+| "12345a" | 失败 | "验证码必须是6位数字" |
+| "123456" | 成功 | - |
+
+## 最佳实践
+
+### 1. 用户体验
+
+- **即时反馈**: 在用户输入时提供即时的视觉反馈
+- **清晰提示**: 错误信息要简洁明了，易于理解
+- **引导操作**: 通过UI引导用户完成正确的操作流程
+
+### 2. 性能优化
+
+- **避免过度验证**: 不在每次字符输入时都进行复杂验证
+- **合理的验证时机**: 在失焦和提交时进行验证
+- **缓存验证结果**: 避免重复验证相同的内容
+
+### 3. 安全考虑
+
+- **客户端+服务端**: 双重验证确保数据安全
+- **敏感信息**: 密码等敏感信息不在客户端明文存储
+- **防止暴力破解**: 验证码冷却机制防止频繁请求
+
+### 4. 可维护性
+
+- **模块化设计**: 每个验证规则独立成函数
+- **统一的错误处理**: 使用统一的错误显示机制
+- **可配置的规则**: 验证规则可以根据需求调整
+
+## 更新日志
+
+- **v1.0.0** (2025-12-24): 初始版本，包含完整的表单验证规范

docs/06-功能模块/auth/认证测试指南.md

@@ -0,0 +1,283 @@
+# 表单验证测试指南
+
+## 测试概述
+
+本文档提供了完整的表单验证功能测试步骤，确保所有验证规则和用户交互都能正常工作。
+
+## 测试环境准备
+
+### 1. 启动后端服务
+```bash
+# 确保后端服务运行在 https://whaletownend.xinghangee.icu
+# 或者本地开发环境: http://localhost:3000
+npm start
+# 或者你的后端启动命令
+```
+
+### 2. 打开Godot项目
+- 启动Godot编辑器
+- 打开鲸鱼镇项目
+- 运行主场景
+
+## 登录表单测试
+
+### 测试用例1: 必填项验证
+
+#### 步骤
+1. 点击"注册居民身份"进入登录界面
+2. 不输入任何内容，直接点击用户名输入框外的区域
+3. 不输入任何内容，直接点击密码输入框外的区域
+4. 点击"进入小镇"或"密码登录"按钮
+
+#### 预期结果
+- 用户名输入框下方显示红色错误提示："用户名不能为空"
+- 密码输入框下方显示红色错误提示："密码不能为空"
+- 按钮点击无效，不会提交表单
+
+### 测试用例2: 实时反馈
+
+#### 步骤
+1. 触发上述错误提示后
+2. 在用户名输入框中输入任意字符
+3. 在密码输入框中输入任意字符
+
+#### 预期结果
+- 开始输入时，对应的错误提示立即消失
+- 提供即时的视觉反馈
+
+### 测试用例3: 正常登录
+
+#### 步骤
+1. 输入有效的用户名："testuser"
+2. 输入任意密码："password123"
+3. 点击"进入小镇"
+
+#### 预期结果
+- 无错误提示显示
+- 成功进入游戏主界面
+- 显示用户名信息
+
+## 注册表单测试
+
+### 测试用例4: 用户名验证
+
+#### 测试数据
+| 输入 | 预期结果 | 错误信息 |
+|------|----------|----------|
+| (空) | 失败 | "用户名不能为空" |
+| "test@user" | 失败 | "用户名只能包含字母、数字和下划线" |
+| "a".repeat(51) | 失败 | "用户名长度应为1-50字符" |
+| "test_user123" | 成功 | 无错误提示 |
+
+#### 步骤
+1. 点击"注册居民身份"
+2. 依次输入上述测试数据
+3. 每次输入后点击其他输入框（触发失焦验证）
+
+### 测试用例5: 邮箱验证
+
+#### 测试数据
+| 输入 | 预期结果 | 错误信息 |
+|------|----------|----------|
+| (空) | 失败 | "邮箱不能为空" |
+| "invalid-email" | 失败 | "请输入有效的邮箱地址" |
+| "test@" | 失败 | "请输入有效的邮箱地址" |
+| "test@example.com" | 成功 | 无错误提示 |
+
+#### 步骤
+1. 在邮箱输入框中依次输入测试数据
+2. 每次输入后点击其他输入框
+
+### 测试用例6: 密码验证
+
+#### 测试数据
+| 输入 | 预期结果 | 错误信息 |
+|------|----------|----------|
+| (空) | 失败 | "密码不能为空" |
+| "1234567" | 失败 | "密码长度至少8位" |
+| "12345678" | 失败 | "密码必须包含字母和数字" |
+| "abcdefgh" | 失败 | "密码必须包含字母和数字" |
+| "abc12345" | 成功 | 无错误提示 |
+
+#### 步骤
+1. 在密码输入框中依次输入测试数据
+2. 每次输入后点击其他输入框
+
+### 测试用例7: 确认密码验证
+
+#### 步骤
+1. 在密码框输入："abc12345"
+2. 在确认密码框输入：""（空）
+3. 点击其他输入框
+4. 在确认密码框输入："different123"
+5. 点击其他输入框
+6. 在确认密码框输入："abc12345"
+7. 点击其他输入框
+
+#### 预期结果
+- 步骤3: 显示"确认密码不能为空"
+- 步骤5: 显示"两次输入的密码不一致"
+- 步骤7: 无错误提示
+
+### 测试用例8: 验证码功能
+
+#### 步骤
+1. 不输入邮箱，直接点击"发送验证码"
+2. 输入无效邮箱"invalid"，点击"发送验证码"
+3. 输入有效邮箱"test@example.com"，点击"发送验证码"
+4. 立即再次点击"发送验证码"
+5. 在验证码输入框输入"12345"（5位）
+6. 在验证码输入框输入"12345a"（包含字母）
+7. 在验证码输入框输入"123456"（正确格式）
+
+#### 预期结果
+- 步骤1: 邮箱框显示"邮箱不能为空"，聚焦到邮箱输入框
+- 步骤2: 邮箱框显示"请输入有效的邮箱地址"
+- 步骤3: 显示"正在发送验证码..."，按钮变为禁用状态
+- 步骤4: 显示冷却提示"请等待 XX 秒后再次发送"
+- 步骤5: 验证码框显示"验证码必须是6位数字"
+- 步骤6: 验证码框显示"验证码必须是6位数字"
+- 步骤7: 无错误提示
+
+### 测试用例9: 完整注册流程
+
+#### 步骤
+1. 填写所有必填信息：
+   - 用户名: "testuser"
+   - 邮箱: "test@example.com"
+   - 密码: "password123"
+   - 确认密码: "password123"
+2. 点击"发送验证码"
+3. 查看控制台获取验证码
+4. 输入验证码
+5. 点击"注册"按钮
+
+#### 预期结果
+- 所有验证通过，无错误提示
+- 显示"正在验证邮箱..."
+- 显示"邮箱验证成功，正在注册..."
+- 显示"注册成功！"
+- 自动返回登录界面
+- 用户名自动填入登录表单
+
+## 边界情况测试
+
+### 测试用例10: 网络异常
+
+#### 步骤
+1. 关闭后端服务
+2. 尝试发送验证码
+3. 尝试注册
+
+#### 预期结果
+- 显示"网络连接失败，请检查服务器是否启动"
+- 按钮重新启用
+
+### 测试用例11: 快速操作
+
+#### 步骤
+1. 快速连续点击"发送验证码"按钮
+2. 快速连续点击"注册"按钮
+
+#### 预期结果
+- 按钮在请求期间被禁用
+- 防止重复提交
+
+### 测试用例12: 表单切换
+
+#### 步骤
+1. 在注册表单中输入信息并触发错误提示
+2. 点击"返回登录"
+3. 再次点击"注册居民身份"
+
+#### 预期结果
+- 切换到登录界面时，注册表单状态保持
+- 再次进入注册界面时，表单被清空，错误提示被隐藏
+
+## 性能测试
+
+### 测试用例13: 响应速度
+
+#### 步骤
+1. 快速在各个输入框之间切换
+2. 快速输入和删除文本
+3. 观察错误提示的显示和隐藏速度
+
+#### 预期结果
+- 验证响应迅速，无明显延迟
+- UI更新流畅，无卡顿现象
+
+## 兼容性测试
+
+### 测试用例14: 不同输入法
+
+#### 步骤
+1. 使用中文输入法输入用户名
+2. 使用英文输入法输入用户名
+3. 输入特殊字符
+
+#### 预期结果
+- 中文字符被正确验证为无效格式
+- 英文字符正常通过验证
+- 特殊字符按规则验证
+
+## 测试检查清单
+
+### 功能完整性
+- [ ] 所有必填项都有红色星号标识
+- [ ] 失焦验证正常工作
+- [ ] 实时输入反馈正常
+- [ ] 错误提示准确显示
+- [ ] 验证码发送和验证功能正常
+- [ ] 注册流程完整可用
+
+### 用户体验
+- [ ] 错误提示清晰易懂
+- [ ] 按钮状态管理正确
+- [ ] 表单切换流畅
+- [ ] 成功反馈及时
+
+### 错误处理
+- [ ] 网络异常处理正确
+- [ ] 服务器错误处理正确
+- [ ] 边界情况处理正确
+
+### 性能表现
+- [ ] 验证响应速度快
+- [ ] UI更新流畅
+- [ ] 内存使用正常
+
+## 测试报告模板
+
+### 测试环境
+- Godot版本: 
+- 操作系统: 
+- 后端服务状态: 
+- 测试时间: 
+
+### 测试结果
+| 测试用例 | 状态 | 备注 |
+|----------|------|------|
+| 登录表单验证 | ✅/❌ | |
+| 注册表单验证 | ✅/❌ | |
+| 验证码功能 | ✅/❌ | |
+| 网络异常处理 | ✅/❌ | |
+| 完整注册流程 | ✅/❌ | |
+
+### 发现的问题
+1. 问题描述
+   - 重现步骤
+   - 预期结果
+   - 实际结果
+   - 严重程度
+
+### 改进建议
+1. 功能改进
+2. 用户体验优化
+3. 性能优化
+
+---
+
+**测试完成日期**: ___________  
+**测试人员**: ___________  
+**测试版本**: v1.0.0