# 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  
**当前状态**: ✅ 编译成功，待运行验证