Initial commit

docs/前端嵌入验证清单.md

@@ -0,0 +1,215 @@
+# MeshRay 前端嵌入验证清单
+
+## ✅ 验证步骤
+
+### 1. 检查 embed.go 配置
+
+**文件**: `web/embed.go`
+```go
+//go:embed all:static
+var WebAssets embed.FS
+```
+
+✅ 正确 - 使用 `all:static` 嵌入 static 目录
+
+---
+
+### 2. 检查 server.go 路由
+
+**文件**: `internal/api/server.go`
+
+**关键代码**:
+```go
+// 剥离 static 外层目录
+if embedFS, err := fs.Sub(web.WebAssets, "static"); err == nil {
+    staticFS = embedFS
+}
+
+// 注册根路径
+s.engine.GET("/", func(c *gin.Context) {
+    file, err := staticFS.Open("index.html")
+    if err == nil {
+        content, _ := io.ReadAll(file)
+        c.Data(200, "text/html; charset=utf-8", content)
+        return
+    }
+})
+```
+
+✅ 正确 - 根路径和 NoRoute 都已配置
+
+---
+
+### 3. 编译验证
+
+```bash
+cd e:\Project\MeshRay
+go build -o meshray.exe .
+```
+
+✅ 编译成功，无错误
+
+---
+
+### 4. 运行测试
+
+```bash
+./meshray.exe
+```
+
+**预期日志**:
+```
+使用内嵌的静态文件
+🌐 MeshRay 启动成功！
+📍 访问地址：http://localhost:8080
+```
+
+---
+
+### 5. 浏览器访问
+
+打开浏览器访问：`http://localhost:8080`
+
+**预期效果**:
+- ✅ 显示 MeshRay 登录页面或仪表盘
+- ✅ Vue 3 + Element Plus 正常加载
+- ✅ Tailwind CSS 样式生效
+- ✅ 页面布局完整（侧边栏 + 主内容）
+
+---
+
+## 🔍 常见问题排查
+
+### 问题 1: 访问 http://localhost:8080 显示空白页
+
+**可能原因**:
+- ❌ CDN 资源加载失败（网络问题）
+- ❌ JavaScript 执行错误
+- ❌ 路由配置问题
+
+**解决方法**:
+1. 打开浏览器开发者工具 (F12)
+2. 查看 Console 错误信息
+3. 检查 Network 面板 CDN 资源是否加载成功
+
+---
+
+### 问题 2: 显示 "Failed to load index.html"
+
+**可能原因**:
+- ❌ embed.go 配置错误
+- ❌ static 目录不存在
+- ❌ 编译时未包含 web 包
+
+**解决方法**:
+```bash
+# 检查 static 目录是否存在
+ls web/static/
+
+# 重新编译
+go clean
+go build -o meshray.exe .
+```
+
+---
+
+### 问题 3: API 请求失败
+
+**可能原因**:
+- ❌ 后端服务未启动
+- ❌ API 路径错误
+- ❌ CORS 问题
+
+**解决方法**:
+1. 检查后端日志
+2. 确认 API 路径：`/api/v1/...`
+3. 开发环境需要 CORS 中间件
+
+---
+
+## 📋 文件清单
+
+### 必须存在的文件
+
+```
+e:\Project\MeshRay\
+├── web/
+│   ├── static/
+│   │   ├── index.html          ✅ 主页面
+│   │   └── js/
+│   │       └── app.js          ✅ Vue 应用
+│   └── embed.go                ✅ Go embed 配置
+├── internal/
+│   └── api/
+│       └── server.go           ✅ 路由配置
+└── meshray.exe                 ✅ 编译产物
+```
+
+---
+
+## 🎯 验证命令
+
+### PowerShell 一键验证
+
+```powershell
+# 1. 检查文件存在
+Test-Path web/static/index.html
+Test-Path web/static/js/app.js
+Test-Path web/embed.go
+
+# 2. 清理并重新编译
+go clean
+go build -o meshray.exe .
+
+# 3. 运行程序
+./meshray.exe
+
+# 4. 等待 3 秒后测试 API
+Start-Sleep -Seconds 3
+Invoke-RestMethod http://localhost:8080/health
+```
+
+---
+
+## 🐛 调试技巧
+
+### 1. 启用详细日志
+
+在 `server.go` 中添加：
+
+```go
+s.logger.Info("静态文件内容:", 
+    zap.Any("files", staticFS))
+```
+
+### 2. 测试根路径
+
+```bash
+curl http://localhost:8080/
+```
+
+应该返回 HTML 内容
+
+### 3. 测试 API
+
+```bash
+curl http://localhost:8080/health
+```
+
+应该返回：`{"status":"ok"}`
+
+---
+
+## ✅ 成功标准
+
+- [x] 编译无错误
+- [ ] 程序启动成功
+- [ ] 访问 http://localhost:8080 显示页面
+- [ ] Vue 应用正常加载
+- [ ] API 调用成功
+- [ ] 控制台无严重错误
+
+---
+
+**最后更新**: 2026-03-20  
+**当前状态**: ✅ 编译成功，待运行验证