# MeshRay 全功能遍历与问题排查计划

## 📋 遍历方法论

### 用户视角遍历
- **起点**: 用户第一个触点（登录/注册）
- **路径**: 按照实际使用流程
- **覆盖**: 前端页面 → API 接口 → 业务逻辑 → 数据库
- **深度**: 每个功能的完整实现链路

### 技术栈遍历
- **前端**: Vue 组件、路由、状态管理、API 调用
- **后端**: Handler → Service → Model/Store
- **核心**: Ctr → Core → WireGuard
- **数据**: SQLite 表结构、关系、完整性

---

## 🗺️ 功能模块地图

### 1. 用户认证与系统入口
- [ ] 登录页面 (`/login`)
- [ ] 注册页面 (`/register`)
- [ ] 首页/Dashboard (`/`)
- [ ] 系统配置

### 2. 网络管理（核心功能）
- [ ] 网络列表页面 (`/networks`)
- [ ] 创建网络
- [ ] 网络详情
- [ ] 网络配置
- [ ] Peer 管理
- [ ] IP 地址分配

### 3. STUN/TURN 服务
- [ ] STUN 服务器配置
- [ ] TURN 服务器配置
- [ ] 服务可用性检测
- [ ] 自动打洞配置

### 4. DDNS 服务
- [ ] DDNS Provider 配置
- [ ] DDNS Usage 管理
- [ ] 域名绑定
- [ ] 自动更新

### 5. 系统管理
- [ ] 备份恢复
- [ ] 通知中心
- [ ] 系统更新检查
- [ ] 日志查看

### 6. Core 协议层
- [ ] Core 客户端连接
- [ ] 设备发现
- [ ] NAT 类型检测
- [ ] 打洞策略
- [ ] 中继 fallback

---

## 🔍 详细遍历路径

### 路径 1: 用户首次使用 - 创建网络

**前端**:
1. 登录 → Dashboard
2. 点击"创建网络"
3. 填写网络配置（名称、IP 段、MTU 等）
4. 提交创建
5. 跳转到网络详情

**后端**:
1. `POST /api/v1/networks`
2. `handler.NetworkHandler.CreateNetwork`
3. `service.NetworkService.CreateNetwork`
4. 验证配置
5. 生成雪花 ID
6. 分配子网
7. 创建管理员 Peer
8. 保存到数据库

**Core 层**:
1. Ctr 监听网络创建事件
2. 配置 WG 设备
3. 生成密钥对
4. 设置监听端口

**排查点**:
- ✅ 雪花 ID 生成是否正确（uint64 处理）
- ✅ 子网分配算法
- ✅ Peer 配置生成
- ✅ WG 设备创建成功
- ✅ 数据库事务完整性

---

### 路径 2: 添加 Peer（用户态模式）

**前端**:
1. 网络详情页 → "添加 Peer"
2. 选择"用户态模式"
3. 填写 Peer 信息（名称、IP）
4. 下载配置文件
5. 启动 Peer

**后端**:
1. `POST /api/v1/networks/{id}/peers`
2. `handler.PeerHandler.CreatePeer`
3. `service.PeerService.CreatePeer`
4. 验证 IP 可用性
5. 生成 Peer 配置
6. 返回 WireGuard 配置

**Core 层**:
1. Ctr 收到 Peer 创建事件
2. 调用 `wg.AddPeer`
3. 配置用户态 WG 设备
4. 设置代理规则

**排查点**:
- ✅ Peer IP 冲突检测
- ✅ 配置文件格式正确
- ✅ WG 设备添加成功
- ✅ 路由表更新
- ✅ 连通性测试

---

### 路径 3: STUN 自动配置

**前端**:
1. 网络详情 → STUN 配置
2. 启用 STUN 穿透
3. 选择 STUN 服务器
4. 保存配置

**后端**:
1. `PUT /api/v1/networks/{id}/stun`
2. `handler.NetworkHandler.UpdateSTUNConfig`
3. `service.STUNService.Configure`
4. 验证 STUN 服务器可用性
5. 更新网络配置

**Core 层**:
1. Ctr 监听 STUN 配置变更
2. 自动配置 STUN 给 WG
3. 设置 endpoint 发现机制

**排查点**:
- ✅ STUN 服务器可达性
- ✅ WG Endpoint 自动填充
- ✅ NAT 类型检测准确
- ✅ 打洞成功率统计

---

### 路径 4: TURN 中继 fallback

**前端**:
1. 网络详情 → TURN 配置
2. 启用 TURN 中继
3. 配置 TURN 服务器
4. 设置 fallback 条件

**后端**:
1. `PUT /api/v1/networks/{id}/turn`
2. `handler.NetworkHandler.UpdateTURNConfig`
3. `service.TURNServerService.Validate`
4. 测试 TURN 服务器连接
5. 保存配置

**Core 层**:
1. Ctr 监听 TURN 配置
2. 监控打洞失败
3. 自动切换到 TURN 中继
4. 更新 Peer 配置

**排查点**:
- ✅ TURN 凭证生成
- ✅ fallback 触发条件
- ✅ 中继路由优先级
- ✅ 切换延迟

---

### 路径 5: DDNS 全自动模式

**前端**:
1. DDNS 管理 → 创建 Provider
2. 配置 API Token
3. 创建 DDNS Usage
4. 绑定到网络

**后端**:
1. `POST /api/v1/ddns/providers`
2. `POST /api/v1/ddns/usages`
3. `POST /api/v1/networks/{id}/bind-ddns`
4. 验证 Provider 配置
5. 测试 DNS API
6. 建立绑定关系

**Core 层**:
1. 监听 IP 变化
2. 自动更新 DNS 记录
3. 同步到所有 Peer

**排查点**:
- ✅ Provider 验证逻辑
- ✅ DNS 记录创建成功
- ✅ IP 检测准确性
- ✅ 更新频率控制
- ✅ 错误重试机制

---

### 路径 6: 备份与恢复

**前端**:
1. 系统管理 → 备份
2. 点击"创建备份"
3. 下载备份文件
4. 上传备份恢复

**后端**:
1. `POST /api/v1/system/backup`
2. `handler.BackupHandler.CreateBackup`
3. `service.BackupService.CreateBackup`
4. 导出数据库
5. 打包配置文件
6. 返回 ZIP 文件

**恢复流程**:
1. `POST /api/v1/system/restore`
2. 上传 ZIP 文件
3. 解压
4. 恢复数据库
5. 恢复配置
6. 重启服务

**排查点**:
- ✅ 数据库导出完整
- ✅ 配置文件备份
- ✅ 压缩包格式正确
- ✅ 恢复时事务安全
- ✅ 服务重启成功

---

### 路径 7: 实时通知推送

**前端**:
1. WebSocket 连接
2. 监听通知事件
3. 显示通知弹窗
4. 标记已读

**后端**:
1. WebSocket 握手
2. 认证中间件
3. 维护连接池
4. 广播通知

**排查点**:
- ✅ WebSocket 认证
- ✅ 心跳保活
- ✅ 断线重连
- ✅ 消息不丢失
- ✅ 并发连接处理

---

### 路径 8: Core 协议通信

**Core 客户端**:
1. TLS 握手
2. 认证（Token/mTLS）
3. 能力协商
4. 订阅事件

**Core 服务端**:
1. 监听端口
2. 接受连接
3. 验证客户端
4. 发送事件

**排查点**:
- ✅ Proto 定义一致性
- ✅ TLS 证书验证
- ✅ 消息序列化
- ✅ 错误处理
- ✅ 重连机制

---

## 🐛 重点排查问题清单

### P0 - 严重问题
1. **网络创建失败** - 雪花 ID、子网分配
2. **Peer 无法连接** - WG 配置、路由表
3. **STUN 打洞无效** - Endpoint 发现
4. **DDNS 更新失败** - API 调用、权限

### P1 - 重要问题
1. **备份恢复不完整** - 表遗漏、配置缺失
2. **通知推送延迟** - WebSocket 连接
3. **TURN 切换失败** - fallback 逻辑
4. **Core 连接断开** - 心跳、重连

### P2 - 次要问题
1. **UI 显示异常** - 数据格式化
2. **错误提示不清** - 错误包装
3. **性能问题** - 查询优化
4. **文档缺失** - API 注释

---

## 🔧 排查工具与方法

### 代码审查
- ✅ TODO/FIXME 标记
- ✅ 错误处理完整性
- ✅ 日志输出充分性
- ✅ 边界条件检查

### 运行时排查
- ✅ 编译检查
- ✅ 单元测试
- ✅ 集成测试
- ✅ 手动验证

### 数据验证
- ✅ 数据库约束
- ✅ 外键关系
- ✅ 索引效率
- ✅ 事务完整性

---

## 📊 预期输出

1. **问题清单** - 按优先级分类
2. **修复方案** - 具体代码修改
3. **验证结果** - 测试通过证明
4. **文档更新** - 使用说明完善

---

**开始时间**: 2026-03-20  
**预计耗时**: 2-3 小时  
**目标**: 零遗漏、零死角、全功能可用