调整readme

2025-12-06 17:12:24 +08:00
parent 9e0b559c05
commit 419d2939f6
61 changed files with 3688 additions and 4802 deletions
--- a/README.md
+++ b/README.md
@@ -7,17 +7,40 @@
 - 🎮 2D 多人在线游戏
 - 🌐 网页版优先（HTML5 导出）
 - 📱 预留移动端适配
- 💬 实时对话系统
+- 💬 实时对话系统（支持表情、群聊、历史记录）
 - 🔄 角色在线/离线状态切换
 - 🎨 Datawhale 品牌场景
+- 👤 角色外观自定义系统
+- 🤝 社交功能（好友系统、私聊、关系网络）
+- 📊 数据分析和性能监控
+- 🔒 安全防护（输入验证、速率限制）

 ## 技术栈

+### 客户端
 - **游戏引擎**: Godot 4.5.1
- **客户端语言**: GDScript
- **服务器**: Node.js + TypeScript + WebSocket
- **包管理**: Yarn
- **数据格式**: JSON
+- **编程语言**: GDScript
+- **UI框架**: Godot Control 节点系统
+- **动画系统**: Tween + AnimationPlayer
+- **测试框架**: GUT (Godot Unit Test) + 自定义属性测试
+
+### 服务器
+- **运行时**: Node.js 24.7.0+
+- **编程语言**: TypeScript
+- **网络协议**: WebSocket (ws 库)
+- **包管理**: Yarn 1.22.22+
+- **数据存储**: JSON 文件系统
+
+### 开发工具
+- **版本控制**: Git
+- **部署**: Docker + Nginx
+- **监控**: 自定义健康检查和日志系统
+- **备份**: 自动备份管理器
+
+### 数据格式
+- **消息协议**: JSON
+- **角色数据**: Dictionary (GDScript) / Object (TypeScript)
+- **配置文件**: JSON / YAML

 ## 快速开始

@@ -102,14 +125,88 @@ ai_community/
 ├── scenes/                # 游戏场景
 │   ├── Main.tscn         # 主场景
 │   ├── DatawhaleOffice.tscn # Datawhale 办公室
+│   ├── PlayerCharacter.tscn # 玩家角色
+│   ├── RemoteCharacter.tscn # 远程角色
+│   ├── ErrorNotification.tscn # 错误通知
 │   └── TestGameplay.tscn # 测试场景
 ├── scripts/               # GDScript 脚本
+│   ├── 核心系统/
+│   │   ├── Main.gd       # 主控制器
+│   │   ├── NetworkManager.gd # 网络管理
+│   │   ├── GameStateManager.gd # 状态管理
+│   │   └── WorldManager.gd # 世界管理
+│   ├── 角色系统/
+│   │   ├── CharacterController.gd # 角色控制
+│   │   ├── CharacterCustomization.gd # 外观自定义
+│   │   ├── CharacterPersonalization.gd # 个性化
+│   │   └── CharacterProfile.gd # 角色档案
+│   ├── 对话系统/
+│   │   ├── DialogueSystem.gd # 对话管理
+│   │   ├── GroupDialogueManager.gd # 群聊
+│   │   ├── PrivateChatSystem.gd # 私聊
+│   │   └── EmojiManager.gd # 表情管理
+│   ├── 社交系统/
+│   │   ├── FriendSystem.gd # 好友系统
+│   │   ├── RelationshipNetwork.gd # 关系网络
+│   │   └── SocialManager.gd # 社交管理
+│   └── 安全与监控/
+│       ├── SecurityManager.gd # 安全管理
+│       ├── RateLimiter.gd # 速率限制
+│       └── PerformanceMonitor.gd # 性能监控
 ├── assets/                # 游戏资源
+│   ├── fonts/            # 字体文件
+│   ├── sprites/          # 精灵图
+│   ├── tilesets/         # 瓦片集
+│   └── ui/               # UI 资源
 ├── tests/                 # 测试文件
+│   ├── RunPropertyTests.gd # 属性测试运行器
+│   └── test_*.gd         # 各类测试
 ├── server/                # WebSocket 服务器
+│   ├── src/              # 服务器源码
+│   │   ├── server.ts     # 主服务器
+│   │   ├── api/          # API 接口
+│   │   ├── backup/       # 备份管理
+│   │   ├── logging/      # 日志系统
+│   │   └── monitoring/   # 监控系统
+│   └── admin/            # 管理界面
 └── .kiro/specs/          # 项目规范文档
+    ├── godot-ai-town-game/ # 主游戏规格
+    └── character-appearance-customization/ # 角色自定义规格
 ```

+## 核心功能
+
+### 🎨 角色外观自定义
+- 头部、身体、脚部颜色自定义
+- 预设颜色方案和自定义颜色选择器
+- 实时预览和平滑动画效果
+- 随机生成和重置功能
+
+### 💬 增强对话系统
+- 对话历史记录管理
+- 表情符号支持
+- 群组对话功能
+- 对话过滤和审核机制
+
+### 🤝 社交功能
+- 好友系统（添加、删除、列表管理）
+- 私聊功能（一对一消息）
+- 角色关系网络（关系强度追踪）
+- 社区活动和事件系统
+
+### 🔒 安全防护
+- 输入验证和过滤
+- 速率限制（防止滥用）
+- 会话管理和超时机制
+- 数据传输安全性
+
+### 📊 监控与分析
+- 用户行为数据收集
+- 游戏统计和分析
+- 性能监控和报警
+- 服务器健康检查
+- 自动备份和日志管理
+
 ## 服务器 API

 WebSocket 服务器监听端口: `8080`
@@ -125,20 +222,100 @@ WebSocket 服务器监听端口: `8080`

 ### 主要消息类型
 - `auth_request` / `auth_response` - 身份验证
- `character_create` - 创建角色
+- `character_create` - 创建角色（支持外观数据）
 - `character_move` - 角色移动
 - `character_state` - 角色状态更新
 - `dialogue_send` - 发送对话
 - `world_state` - 世界状态同步
+- `friend_request` - 好友请求
+- `private_message` - 私聊消息

 详细 API 文档请参考 `server/README.md`

-## Web 导出
+## Web 导出和部署

-1. 在 Godot 中打开 "项目" -> "导出"
-2. 添加 "HTML5" 导出预设
-3. 配置导出选项
-4. 点击 "导出项目"
+### 快速导出
+
+1. 在 Godot 中打开 "项目" → "导出"
+2. 添加 "Web" 导出预设
+3. 配置导出选项（线程支持、资源嵌入等）
+4. 导出到 `web_build/` 目录
+
+### 本地测试
+
+```bash
+cd web_build
+python -m http.server 8000
+```
+
+访问 http://localhost:8000 测试游戏
+
+### 生产部署
+
+项目已配置 Docker + Nginx 部署方案：
+
+1. **构建 Web 版本**：在 Godot 中导出到 `web_assets/`
+2. **启动服务器**：
+   ```bash
+   cd server
+   yarn build
+   yarn start
+   ```
+3. **使用 Docker**：
+   ```bash
+   docker-compose -f docker-compose.prod.yml up -d
+   ```
+
+nginx 配置已针对 Godot Web 优化（CORS 头部、MIME 类型、缓存策略等），配置文件位于 `nginx/nginx.conf`
+
+## 项目规格系统
+
+本项目采用规范化的开发流程，使用 Spec 文档系统管理需求、设计和实施：
+
+### 📋 规格文档结构
+
+每个功能模块包含三个核心文档：
+
+1. **requirements.md** - 需求文档
+   - 用户故事和验收标准
+   - 明确的功能需求定义
+   - 可验证的验收条件
+
+2. **design.md** - 设计文档
+   - 系统架构和组件设计
+   - 数据模型和接口定义
+   - 正确性属性（Property-Based Testing）
+   - 错误处理和测试策略
+
+3. **tasks.md** - 任务文档
+   - 详细的实施计划
+   - 任务分解和依赖关系
+   - 进度追踪和完成状态
+
+### 🎯 当前规格模块
+
+#### 主游戏系统 (.kiro/specs/godot-ai-town-game/)
+- **12个核心需求**：角色创建、移动、对话、场景、网络等
+- **30个正确性属性**：确保系统行为的可验证性
+- **23个主要任务组**：涵盖从初始化到最终交付的完整流程
+
+#### 角色外观自定义 (.kiro/specs/character-appearance-customization/)
+- **8个功能需求**：默认外观、自定义界面、颜色调整等
+- **18个正确性属性**：保证自定义系统的正确性
+- **模块化设计**：易于扩展和维护
+
+### ✅ 正确性属性测试
+
+项目使用属性基础测试（Property-Based Testing）确保系统正确性：
+
+- **测试覆盖**：48个正确性属性（30个主游戏 + 18个角色自定义）
+- **测试迭代**：每个属性至少100次随机测试
+- **测试标注**：`# Feature: [feature-name], Property X: [description]`
+
+示例属性：
+- 角色创建唯一性：任意两个角色的ID必须唯一
+- 数据序列化往返：序列化后反序列化应得到等价对象
+- 碰撞检测：角色不能穿过障碍物

 ## 开发指南

@@ -148,11 +325,19 @@ WebSocket 服务器监听端口: `8080`
 3. 配置碰撞层
 4. 在 WorldManager 中注册场景

+### 添加新功能
+1. 在 `.kiro/specs/` 创建新的规格目录
+2. 编写 requirements.md（需求和验收标准）
+3. 编写 design.md（架构和正确性属性）
+4. 编写 tasks.md（实施计划）
+5. 实现功能并编写属性测试
+
 ### 代码风格
 - 变量和函数使用 `snake_case`
 - 类名使用 `PascalCase`
 - 常量使用 `UPPER_CASE`
- 详细规范请参考 `CODING_STYLE.md`
+- 私有变量使用 `_leading_underscore`
+- 详细规范请参考 [开发者技术文档](DEVELOPER_GUIDE.md)

 ## 故障排除

@@ -169,36 +354,35 @@ A: 查看控制台详细错误信息，确保所有文件已保存

 ## 📚 完整文档

-### 用户文档
- **[用户使用手册](USER_MANUAL.md)** - 完整的游戏使用指南
+### 核心文档
 - **[快速测试指南](HOW_TO_TEST.md)** - 测试游戏功能
+- **[开发者技术文档](DEVELOPER_GUIDE.md)** - 技术架构和 API 参考
 - **[环境配置指南](SETUP.md)** - 开发环境配置
-
-### 开发文档
- **[开发者技术文档](DEVELOPER_GUIDE.md)** - 完整的技术文档和 API 参考
- **[代码风格指南](CODING_STYLE.md)** - 代码规范和最佳实践
- **[测试指南](tests/TEST_GUIDE.md)** - 测试框架和使用方法
- **[属性测试指南](tests/PROPERTY_TEST_GUIDE.md)** - 属性测试详解
-
-### 运维文档
- **[部署和运维指南](DEPLOYMENT_GUIDE.md)** - 生产环境部署
+- **[项目状态](PROJECT_STATUS.md)** - 当前开发状态
 - **[服务器文档](server/README.md)** - WebSocket 服务器详解

-### 项目管理
- **[项目状态](PROJECT_STATUS.md)** - 当前开发状态
- **[演示指南](DEMO_GUIDE.md)** - 项目演示和展示
- **[项目规范](.kiro/specs/godot-ai-town-game/)** - 需求、设计和任务文档
+### 项目规范
+- **[主游戏规格](.kiro/specs/godot-ai-town-game/)** - 核心游戏系统的需求、设计和任务
+  - [需求文档](.kiro/specs/godot-ai-town-game/requirements.md) - 12个核心需求，30个正确性属性
+  - [设计文档](.kiro/specs/godot-ai-town-game/design.md) - 架构设计和技术方案
+  - [任务文档](.kiro/specs/godot-ai-town-game/tasks.md) - 实施计划和进度追踪
+- **[角色外观自定义规格](.kiro/specs/character-appearance-customization/)** - 角色个性化系统
+  - [需求文档](.kiro/specs/character-appearance-customization/requirements.md) - 8个功能需求，18个正确性属性
+  - [设计文档](.kiro/specs/character-appearance-customization/design.md) - UI设计和数据模型

 ## 🎯 快速导航

 | 我想... | 查看文档 |
 |---------|----------|
-| 🎮 **玩游戏** | [用户使用手册](USER_MANUAL.md) |
 | 🧪 **测试功能** | [快速测试指南](HOW_TO_TEST.md) |
 | 💻 **开发扩展** | [开发者技术文档](DEVELOPER_GUIDE.md) |
-| 🚀 **部署上线** | [部署和运维指南](DEPLOYMENT_GUIDE.md) |
-| 📊 **项目演示** | [演示指南](DEMO_GUIDE.md) |
-| 🔧 **配置环境** | [环境配置指南](SETUP.md) |
+| <EFBFBD> **配置扩环境** | [环境配置指南](SETUP.md) |
+| <EFBFBD> ***查看进度** | [项目状态](PROJECT_STATUS.md) |
+| 🖥️ **服务器 API** | [服务器文档](server/README.md) |
+| 📋 **了解需求** | [主游戏需求](.kiro/specs/godot-ai-town-game/requirements.md) |
+| 🏗️ **查看架构** | [系统设计文档](.kiro/specs/godot-ai-town-game/design.md) |
+| ✅ **追踪任务** | [任务列表](.kiro/specs/godot-ai-town-game/tasks.md) |
+| 🎨 **角色自定义** | [外观自定义规格](.kiro/specs/character-appearance-customization/) |

 ## 许可证