feat: connect to backend!

Author: tobenot

docs/07-optional-backend-integration.md

@@ -4,6 +4,14 @@
 
 我们提供了一个模板后端项目 [tobenot/Basic-Web-Game-Backend](https://github.com/tobenot/Basic-Web-Game-Backend)，您可以直接使用它，或基于此模板创建自己的后端项目。该后端通过 **GitHub Packages** 发布一个私有的npm包来共享API类型契约。
 
+**🎮 新增：后端功能演示模块**
+
+本模板现在包含一个完整的后端集成演示模块 (`src/games/demo-with-backend`)，展示了如何实现：
+- 魔法链接登录
+- tRPC类型安全API调用
+- JWT令牌管理
+- 用户状态管理
+
 您估计会想使用自己的后端项目，请将下文中的所有 `@<您的GitHub用户名>` 替换为您的实际GitHub用户名。
 
 ---
@@ -12,6 +20,25 @@
 
 如果您已经熟悉流程，可以直接按照以下步骤操作：
 
+### **🎮 体验后端演示（推荐）**
+
+1. **启动后端服务**：
+   ```bash
+   # 在 Basic-Web-Game-Backend 项目中
+   npm run dev
+   ```
+
+2. **访问演示**：
+   启动前端开发服务器后，访问 `/demo-with-backend` 路由
+
+3. **体验功能**：
+   - 输入邮箱地址
+   - 检查邮箱或控制台获取魔法链接
+   - 点击链接完成登录
+   - 查看用户仪表板
+
+### **🔧 手动集成后端**
+
 1.  **创建 `.npmrc` 文件**：
     在项目根目录添加 `.npmrc` 文件，并包含以下内容：
     ```ini
@@ -196,6 +223,59 @@ jobs:
 
 ---
 
+## **🎮 后端演示模块详解**
+
+### **模块结构**
+
+```
+src/games/demo-with-backend/
+├── components/
+│   ├── LoginScreen.tsx    # 登录界面组件
+│   └── Dashboard.tsx      # 用户仪表板组件
+├── hooks/
+│   └── useAuth.ts         # 认证状态管理Hook
+├── services/
+│   └── trpc.ts           # tRPC客户端配置
+├── index.tsx             # 模块入口
+└── README.md             # 模块说明文档
+```
+
+### **核心功能**
+
+1. **魔法链接登录**：
+   - 用户输入邮箱地址
+   - 后端发送包含魔法链接的邮件
+   - 用户点击链接完成登录
+
+2. **JWT令牌管理**：
+   - 自动解析和验证JWT令牌
+   - 令牌过期自动清理
+   - 登录状态持久化
+
+3. **tRPC集成**：
+   - 类型安全的API调用
+   - 自动错误处理
+   - 完整的TypeScript支持
+
+### **如何移除**
+
+如果不需要后端功能，可以轻松移除：
+
+1. **删除模块**：
+   ```bash
+   rm -rf src/games/demo-with-backend
+   ```
+
+2. **移除路由**：
+   在 `src/App.tsx` 中删除相关导入和路由
+
+3. **清理依赖**（可选）：
+   ```bash
+   npm uninstall @trpc/client
+   ```
+
+---
+
 ## **总结**
 通过这种方式，前后端团队可以解耦，同时保持类型安全：
 1.  **后端**：每次推送到`main`分支时，自动发布一个包含最新API类型的新版本包。

docs/letter_to_backend/BACKEND_INTEGRATION_GUIDE.md

@@ -0,0 +1,145 @@
+# 后端集成指南
+
+## 前端现状
+
+我们正在开发一个基于React + TypeScript的前端游戏项目，需要与后端进行集成。目前遇到了一些连接问题，需要后端配合解决。
+
+## 当前问题
+
+### 1. 404 Not Found 错误
+```
+Failed to load resource: the server responded with a status of 404 (Not Found)
+/api/trpc/auth.requestLoginLink?batch=1:1
+```
+
+### 2. JSON解析错误
+```
+Failed to execute 'json' on 'Response': Unexpected end of JSON input
+```
+
+### 3. tRPC类型不匹配
+TypeScript编译时出现tRPC类型不兼容的错误。
+
+## 前端配置
+
+### 依赖版本
+- `@trpc/client`: ^11.4.3
+- `@tobenot/basic-web-game-backend-contract`: ^1.0.0
+
+### API端点
+前端期望的后端API端点：
+- `GET /api/trpc/auth.healthCheck` (健康检查)
+- `POST /api/trpc/auth.requestLoginLink` (请求登录链接)
+- `POST /api/trpc/auth.verifyMagicToken` (验证魔法令牌)
+- `GET /api/trpc/user.getMe` (获取用户信息)
+
+### 请求格式
+tRPC批量请求格式：
+```json
+{
+  "0": {
+    "json": {
+      "email": "[email protected]"
+    }
+  }
+}
+```
+
+## 需要后端配合的事项
+
+### 1. 确认API端点
+请确认后端是否提供了以下端点：
+- `/api/trpc/auth.healthCheck` (POST) - 健康检查
+- `/api/trpc/auth.requestLoginLink` (POST) - 请求登录链接
+- `/api/trpc/auth.verifyMagicToken` (POST) - 验证魔法令牌
+- `/api/trpc/user.getMe` (GET) - 获取用户信息
+
+### 2. 检查CORS配置
+前端运行在 `http://localhost:5173`，需要后端允许跨域请求：
+```javascript
+// 后端CORS配置示例
+app.use(cors({
+  origin: ['http://localhost:5173', 'http://localhost:3000'],
+  credentials: true
+}));
+```
+
+### 3. 验证tRPC配置
+确保后端tRPC配置正确：
+```javascript
+// 后端tRPC配置
+const appRouter = router({
+  auth: authRouter,
+  user: userRouter,
+  // ... 其他路由
+});
+
+export type AppRouter = typeof appRouter;
+```
+
+### 4. 检查响应格式
+tRPC期望的响应格式：
+```json
+{
+  "result": {
+    "data": {
+      "success": true
+    }
+  }
+}
+```
+
+## 测试步骤
+
+### 1. 启动后端服务
+```bash
+cd Basic-Web-Game-Backend
+npm run dev
+```
+
+### 2. 测试API端点
+```bash
+# 测试健康检查
+curl -X GET http://localhost:3000/api/trpc/auth.healthCheck \
+  -H "Content-Type: application/json"
+
+# 测试登录链接请求
+curl -X POST http://localhost:3000/api/trpc/auth.requestLoginLink \
+  -H "Content-Type: application/json" \
+  -d '{"0":{"json":{"email":"[email protected]"}}}'
+```
+
+### 3. 检查前端连接
+访问 `http://localhost:5173/demo-with-backend` 查看连接状态。
+
+## 调试信息
+
+### 前端调试
+- 打开浏览器开发者工具
+- 查看Console和Network标签页
+- 页面会显示后端连接状态指示器
+
+### 后端调试
+- 检查服务器日志
+- 确认端口3000是否被占用
+- 验证tRPC路由是否正确注册
+
+## 联系信息
+
+如果遇到问题，请检查：
+1. 后端服务是否正常运行在端口3000
+2. API端点是否正确配置
+3. CORS设置是否允许前端域名
+4. tRPC版本是否与前端兼容
+
+## 预期结果
+
+成功集成后，用户应该能够：
+1. 在登录页面输入邮箱
+2. 收到魔法链接（开发环境下在控制台显示）
+3. 点击链接完成登录
+4. 看到用户仪表板
+
+---
+
+**注意**：这是一个演示模块，用于展示前后端集成的完整流程。如果不需要后端功能，可以轻松移除整个模块。 

docs/letter_to_backend/README.md

@@ -0,0 +1,39 @@
+
+## 🔐 Optional Backend Integration
+
+This template includes a **backend integration demo** that showcases how to integrate with a backend service using tRPC and magic link authentication.
+
+### 🚀 Try the Backend Demo
+
+1. **Start the backend service** (from [Basic-Web-Game-Backend](https://github.com/tobenot/Basic-Web-Game-Backend)):
+   ```bash
+   npm run dev
+   ```
+
+2. **Access the demo** at `/demo-with-backend` route
+
+3. **Experience the features**:
+   - Magic link authentication
+   - Type-safe API calls with tRPC
+   - JWT token management
+   - Real-time user state
+
+### 📖 Learn More
+
+For detailed backend integration documentation, see [Backend Integration Guide](./docs/07-optional-backend-integration.md).
+
+### 🗑️ Remove Backend Features
+
+If you don't need backend functionality, you can easily remove it:
+
+1. **Delete the demo module**:
+   ```bash
+   rm -rf src/games/demo-with-backend
+   ```
+
+2. **Remove the route** from `src/App.tsx`
+
+3. **Clean up dependencies** (optional):
+   ```bash
+   npm uninstall @trpc/client
+   ```

docs/letter_to_backend/test-backend-simple.js

@@ -0,0 +1,110 @@
+const API_BASE_URL = 'http://localhost:3000';
+
+async function testBackendConnection() {
+	console.log('🔍 测试后端连接...\n');
+
+	// 测试1: 检查服务器是否运行
+	console.log('1. 检查服务器状态...');
+	try {
+		const response = await fetch(`${API_BASE_URL}/api/trpc/auth.healthCheck`, {
+			method: 'GET',
+			headers: {
+				'Content-Type': 'application/json',
+			}
+		});
+
+		console.log(`   状态码: ${response.status}`);
+		console.log(`   状态文本: ${response.statusText}`);
+
+		if (response.ok) {
+			console.log('   ✅ 服务器响应正常');
+			try {
+				const data = await response.json();
+				if (data.result?.data?.status === 'ok') {
+					console.log('   ✅ 健康检查通过');
+				} else {
+					console.log('   ⚠️  健康检查失败');
+				}
+			} catch (e) {
+				console.log('   ⚠️  无法解析健康检查响应');
+			}
+		} else {
+			console.log('   ❌ 服务器响应异常');
+		}
+
+		// 尝试读取响应内容
+		try {
+			const text = await response.text();
+			console.log(`   响应内容: ${text.substring(0, 200)}...`);
+		} catch (e) {
+			console.log('   无法读取响应内容');
+		}
+
+	} catch (error) {
+		console.log(`   ❌ 连接失败: ${error.message}`);
+	}
+
+	// 测试2: 检查CORS
+	console.log('\n2. 检查CORS配置...');
+	try {
+		const response = await fetch(`${API_BASE_URL}/api/trpc/auth.healthCheck`, {
+			method: 'OPTIONS',
+			headers: {
+				'Origin': 'http://localhost:5173',
+				'Access-Control-Request-Method': 'GET',
+				'Access-Control-Request-Headers': 'Content-Type',
+			}
+		});
+
+		const corsHeaders = response.headers.get('access-control-allow-origin');
+		if (corsHeaders) {
+			console.log(`   ✅ CORS已配置: ${corsHeaders}`);
+		} else {
+			console.log('   ⚠️  未找到CORS配置');
+		}
+	} catch (error) {
+		console.log(`   ❌ CORS检查失败: ${error.message}`);
+	}
+
+	// 测试3: 检查其他端点
+	console.log('\n3. 检查其他端点...');
+	const endpoints = [
+		'auth.requestLoginLink',
+		'auth.verifyMagicToken',
+		'user.getMe',
+		'announcement.getAnnouncement'
+	];
+
+	for (const endpoint of endpoints) {
+		try {
+			const response = await fetch(`${API_BASE_URL}/api/trpc/${endpoint}`, {
+				method: 'POST',
+				headers: {
+					'Content-Type': 'application/json',
+				},
+				body: JSON.stringify({
+					0: {
+						json: endpoint === 'auth.requestLoginLink' ? { email: '[email protected]' } : {}
+					}
+				})
+			});
+
+			console.log(`   ${endpoint}: ${response.status} ${response.statusText}`);
+		} catch (error) {
+			console.log(`   ${endpoint}: 连接失败`);
+		}
+	}
+
+	console.log('\n📋 总结:');
+	console.log('- 如果看到404错误，说明端点不存在');
+	console.log('- 如果看到405错误，说明端点存在但方法不对');
+	console.log('- 如果看到CORS错误，需要配置跨域');
+	console.log('- 如果看到JSON解析错误，说明响应格式不对');
+	console.log('\n💡 建议:');
+	console.log('1. 确保后端服务运行在 http://localhost:3000');
+	console.log('2. 检查tRPC路由配置');
+	console.log('3. 验证CORS设置');
+	console.log('4. 确认API端点路径正确');
+}
+
+testBackendConnection().catch(console.error);