Initial commit

docs/前端数据问题排查指南.md

@@ -0,0 +1,266 @@
+# MeshRay 前端数据获取问题排查指南
+
+## 🎯 问题现象
+
+前端页面无法获取数据，可能的原因和解决方法如下：
+
+---
+
+## 🔍 排查步骤
+
+### 1️⃣ 检查服务是否正常启动
+
+```bash
+# 查看服务启动日志
+.\meshray.exe
+```
+
+**正常输出**:
+```
+MeshRay v2.0.0 - Starting...
+✅ 正在启动 MeshRay 服务进程...
+🏠 MeshRay 启动成功，🌐 访问地址：http://localhost:9531
+💡 提示：请在浏览器中打开上述地址访问管理面板
+```
+
+---
+
+### 2️⃣ 检查数据库是否有数据
+
+**方法 A: 通过 API 检查**
+
+在浏览器访问：`http://localhost:9531/api/v1/networks`
+
+- ✅ **如果有数据**: 返回 JSON 数组
+- ❌ **如果无数据**: 需要先创建网络
+
+**方法 B: 直接查看数据库文件**
+
+数据库位置：`./data/meshray.db`
+
+可以使用 SQLite 工具查看：
+```sql
+-- 查看网络列表
+SELECT * FROM networks;
+
+-- 查看设备列表
+SELECT * FROM devices;
+```
+
+---
+
+### 3️⃣ 检查浏览器控制台
+
+按 `F12` 打开浏览器开发者工具，查看：
+
+#### Console（控制台）
+查找 JavaScript 错误：
+```javascript
+// 可能的错误示例
+❌ TypeError: Cannot read property 'id' of undefined
+❌ ReferenceError: route is not defined
+```
+
+#### Network（网络）
+查看 API 请求状态：
+
+**正常请求**:
+```
+Request URL: http://localhost:9531/api/v1/devices?network_id=1
+Status: 200 OK
+Response: {"data": [...]}
+```
+
+**错误情况**:
+```
+❌ Status: 404 Not Found
+   → 路由配置问题
+   
+❌ Status: 401 Unauthorized
+   → Token 过期或未登录
+   
+❌ Status: 500 Internal Server Error
+   → 后端服务错误
+   
+❌ (failed) / pending
+   → 后端服务未启动
+```
+
+---
+
+### 4️⃣ 检查路由参数传递
+
+在 Detail.vue 中添加调试代码：
+
+```javascript
+// 在 loadNetworkDetails 函数开头添加
+console.log('🔍 当前路由参数:', route.params.id)
+console.log('🔍 完整路由对象:', route)
+```
+
+**正常情况**:
+```
+🔍 当前路由参数：1
+🔍 完整路由对象：{ params: { id: '1' }, ... }
+```
+
+**异常情况**:
+```
+🔍 当前路由参数：undefined
+❌ 路由参数未正确传递
+```
+
+---
+
+### 5️⃣ 测试 API 连通性
+
+在浏览器控制台执行：
+
+```javascript
+// 测试健康检查
+fetch('/api/v1/health')
+  .then(r => r.json())
+  .then(d => console.log('✅ 服务正常:', d))
+  .catch(e => console.error('❌ 服务异常:', e))
+
+// 测试获取网络列表
+fetch('/api/v1/networks', {
+  headers: {
+    'Authorization': 'Bearer ' + localStorage.getItem('token')
+  }
+})
+.then(r => r.json())
+.then(d => console.log('📋 网络列表:', d))
+.catch(e => console.error('❌ 获取失败:', e))
+```
+
+---
+
+## 🛠️ 常见问题与解决
+
+### 问题 1: 数据库为空
+
+**症状**: 所有列表都显示为空
+
+**解决**:
+1. 访问 `/networks/create` 创建第一个网络
+2. 或使用默认配置初始化
+
+---
+
+### 问题 2: Token 过期
+
+**症状**: 
+- 页面跳转回登录页
+- API 返回 401 错误
+
+**解决**:
+1. 清除浏览器缓存
+2. 重新登录获取新 Token
+
+---
+
+### 问题 3: 路由参数丢失
+
+**症状**: 
+- Detail 页面无法加载数据
+- `route.params.id` 为 undefined
+
+**解决**:
+1. 检查是否正确访问 `/networks/:id` 路径
+2. 确保从列表页点击跳转时携带了正确的 ID
+
+---
+
+### 问题 4: 前后端端口不一致
+
+**症状**: 
+- 前端运行在 3000 端口（开发模式）
+- 后端运行在 9531 端口
+
+**解决**:
+```bash
+# 前端开发模式
+cd web
+npm run dev  # 启动 Vite 开发服务器
+
+# 后端生产模式
+.\meshray.exe  # 启动后端服务
+```
+
+**注意**: 开发模式下前端会代理到后端，确保代理配置正确
+
+---
+
+## 📊 验证清单
+
+- [ ] 后端服务已启动（访问 http://localhost:9531）
+- [ ] 数据库中至少有一个网络
+- [ ] 已成功登录并获取 Token
+- [ ] 浏览器控制台无 JavaScript 错误
+- [ ] Network 面板显示 API 请求返回 200
+- [ ] 路由参数 `route.params.id` 有正确的值
+- [ ] API 响应中包含 `data` 字段
+
+---
+
+## 🎯 快速测试脚本
+
+在浏览器控制台执行以下代码快速诊断：
+
+```javascript
+(async () => {
+  console.log('🔍 === MeshRay 健康检查 ===')
+  
+  // 1. 检查服务
+  try {
+    const health = await fetch('/api/v1/health').then(r => r.json())
+    console.log('✅ 服务状态:', health)
+  } catch (e) {
+    console.error('❌ 服务未响应:', e)
+    return
+  }
+  
+  // 2. 检查登录状态
+  const token = localStorage.getItem('token')
+  if (!token) {
+    console.warn('⚠️ 未登录，请先登录系统')
+    return
+  }
+  console.log('✅ 已登录，Token:', token.substring(0, 20) + '...')
+  
+  // 3. 检查网络列表
+  try {
+    const networks = await fetch('/api/v1/networks', {
+      headers: { 'Authorization': `Bearer ${token}` }
+    }).then(r => r.json())
+    console.log('📋 网络数量:', networks.data?.length || 0)
+    if (networks.data?.length > 0) {
+      console.log('📋 第一个网络:', networks.data[0])
+    } else {
+      console.warn('⚠️ 数据库中无网络，请先创建')
+    }
+  } catch (e) {
+    console.error('❌ 获取网络列表失败:', e)
+  }
+  
+  console.log('=== 检查完成 ===')
+})()
+```
+
+---
+
+## 📞 需要更多帮助？
+
+如果以上方法都无法解决问题，请提供：
+
+1. 浏览器控制台的完整错误信息
+2. Network 面板中失败请求的详细信息
+3. 后端服务的日志输出
+4. 当前访问的 URL 路径
+
+这样可以更快速地定位问题！
+
+---
+
+*MeshRay | 故障排查指南 | v1.0*