Initial commit

2026-06-30 15:14:37 +08:00
commit 15dab96872
311 changed files with 95639 additions and 0 deletions
@@ -0,0 +1,407 @@
+# DDNS Usage 功能 - 前后端联调测试指南
+
+**测试时间**: 2026-03-26  
+**服务状态**: ✅ 已启动 http://localhost:9531  
+
+---
+
+## 🎯 测试目标
+
+验证 DDNS Usage 管理功能的前后端连通性和完整流程
+
+---
+
+## 📋 测试清单
+
+### **阶段 1: 基础功能验证**
+
+#### 1.1 登录系统
+```
+访问：http://localhost:9531
+账户：admin
+密码：admin123 (或你设置的密码)
+```
+
+**预期结果**:
+- [ ] 成功登录
+- [ ] 进入 Dashboard
+
+---
+
+#### 1.2 配置 DDNS 服务（前提条件）
+
+**路径**: 服务市场 → DNS 服务 → 添加服务
+
+**填写内容**:
+```
+服务商：Cloudflare（或其他）
+名称：公司主域名
+记录类型：TXT
+域名：mesh.example.com
+API Token: cf_xxxxx (你的 Cloudflare Token)
+```
+
+**预期结果**:
+- [ ] 保存成功
+- [ ] 服务列表显示新配置的 DDNS 服务
+- [ ] 状态正常（可达）
+
+**API 验证**:
+```bash
+curl -X GET http://localhost:9531/api/v1/services?category=dns&type=ddns \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+
+---
+
+### **阶段 2: 组网创建 - 自动生成模式**
+
+#### 2.1 创建组网并启用 DDNS
+
+**路径**: 组网管理 → 创建组网
+
+**步骤 1: 基础信息**
+```
+组网名称：办公网络
+虚拟 IPv4 网段：10.0.0.0/24
+启用 DDNS 同步：✅ ON
+DDNS 服务：选择刚才配置的 DDNS 服务
+前缀模式：✨ 自动生成（默认）
+```
+
+**预期结果**:
+- [ ] DDNS 服务下拉框正确加载
+- [ ] 选择服务后显示域名信息
+- [ ] 自动生成模式显示预览信息
+- [ ] 预览格式：`_meshray.{短 ID}.{域名}`
+
+**步骤 2-4: 其他配置**
+```
+按默认或自定义填写
+```
+
+**步骤 5: 确认创建**
+
+**预期结果**:
+- [ ] 创建成功提示
+- [ ] 跳转到组网列表
+- [ ] 新组网显示在列表中
+
+---
+
+#### 2.2 验证数据库记录
+
+**API 验证**:
+```bash
+# 查询组网详情
+curl -X GET http://localhost:9531/api/v1/networks/{network_id} \
+  -H "Authorization: Bearer YOUR_TOKEN"
+
+# 期望看到 DDNS 相关字段
+{
+  "data": {
+    "ddns_enabled": true,
+    "ddns_service_id": "xxx",
+    "ddns_usage_id": "xxx",
+    "ddns_prefix": "EjRWeJyt5uU"  # Base64 编码的 ID
+  }
+}
+```
+
+**数据库验证** (可选):
+```sql
+-- 查看 Network 表
+SELECT id, name, ddns_enabled, ddns_service_id, ddns_usage_id, ddns_prefix 
+FROM networks 
+WHERE name = '办公网络';
+
+-- 查看 DDNSUsage 表
+SELECT id, provider_id, prefix_mode, record_prefix, description
+FROM ddns_usages
+WHERE record_prefix = 'EjRWeJyt5uU';
+
+-- 查看绑定关系
+SELECT * FROM network_ddns_bindings
+WHERE network_id = {network_id};
+```
+
+**预期结果**:
+- [ ] Network 表有 DDNS 字段数据
+- [ ] DDNSUsage 表有对应记录
+- [ ] PrefixMode = "auto"
+- [ ] RecordPrefix = Base64 编码的网络 ID（约 11 字符）
+- [ ] NetworkDDNSBinding 表有绑定关系
+
+---
+
+### **阶段 3: 组网创建 - 自定义模式**
+
+#### 3.1 创建第二个组网
+
+**路径**: 组网管理 → 创建组网
+
+**步骤 1: 基础信息**
+```
+组网名称：测试环境
+虚拟 IPv4 网段：10.0.1.0/24
+启用 DDNS 同步：✅ ON
+DDNS 服务：选择同一个 DDNS 服务
+前缀模式：🔧 自定义
+自定义前缀：test-env
+```
+
+**预期结果**:
+- [ ] 输入前缀后自动检测（500ms 防抖）
+- [ ] 如果前缀可用，显示绿色标签"该前缀可用"
+- [ ] 如果前缀被占用，显示红色标签"该前缀已被占用"
+
+**测试冲突场景**:
+```
+1. 输入已被占用的前缀（如第一个组网的前缀）
+2. 观察实时检测结果
+3. 修改为未使用的前缀
+4. 确认可用后再提交
+```
+
+**步骤 2-5: 完成创建**
+
+**预期结果**:
+- [ ] 创建成功
+- [ ] Database 中 RecordPrefix = "test-env"
+- [ ] PrefixMode = "custom"
+
+---
+
+#### 3.2 验证冲突检测
+
+**测试步骤**:
+1. 再次创建组网
+2. 选择自定义模式
+3. 输入已使用的前缀（如 "test-env"）
+4. 等待 500ms
+
+**预期结果**:
+- [ ] 显示红色标签"该前缀已被占用"
+- [ ] 无法提交（或提交时报错）
+
+**API 验证**:
+```bash
+# 手动调用检测接口
+curl -G "http://localhost:9531/api/v1/ddns/check-prefix" \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  --data-urlencode "service_id={service_id}" \
+  --data-urlencode "prefix=test-env"
+
+# 期望返回
+{
+  "data": {
+    "occupied": true,
+    "count": 1
+  }
+}
+```
+
+---
+
+### **阶段 4: 获取可用 Usage 列表**
+
+#### 4.1 API 测试
+
+```bash
+curl -G "http://localhost:9531/api/v1/ddns/usages/available" \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  --data-urlencode "service_id={service_id}"
+```
+
+**期望返回**:
+```json
+{
+  "data": [
+    {
+      "id": "usage_id_1",
+      "provider_id": "service_id",
+      "prefix_mode": "auto",
+      "record_prefix": "EjRWeJyt5uU",
+      "record_type": "TXT",
+      "description": "MeshSeed 同步 - 办公网络",
+      "is_occupied": true,
+      "network_id": 123456789,
+      "full_domain": "_meshray.EjRWeJyt5uU.mesh.example.com"
+    },
+    {
+      "id": "usage_id_2",
+      "prefix_mode": "custom",
+      "record_prefix": "test-env",
+      "is_occupied": true,
+      "full_domain": "_meshray.test-env.mesh.example.com"
+    }
+  ]
+}
+```
+
+**验证点**:
+- [ ] 返回正确的 JSON 结构
+- [ ] full_domain 格式正确
+- [ ] is_occupied 标记正确
+- [ ] prefix_mode 区分 auto/custom
+
+---
+
+### **阶段 5: MeshSeed 同步验证**
+
+#### 5.1 分享组网时查看 DDNS 信息
+
+**路径**: 组网管理 → 详情 → 分享 MeshSeed
+
+**预期结果**:
+- [ ] 显示 DDNS 同步开关
+- [ ] 显示将同步到的完整域名
+- [ ] 格式：`_meshray.{前缀}.{域名}`
+
+---
+
+#### 5.2 手动触发同步（可选）
+
+**API 测试**:
+```bash
+# 手动触发 DDNS 同步
+curl -X POST http://localhost:9531/api/v1/ddns/sync \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+
+**预期结果**:
+- [ ] 同步成功
+- [ ] 日志显示同步到正确的域名
+- [ ] DNS 记录包含加密的 MeshSeed
+
+---
+
+## 🔍 问题排查
+
+### **问题 1: DDNS 服务列表为空**
+
+**可能原因**:
+1. 未配置 DDNS 服务
+2. API 路径错误
+3. 鉴权失败
+
+**排查步骤**:
+```bash
+# 1. 检查服务是否存在
+curl -X GET http://localhost:9531/api/v1/services?category=dns&type=ddns \
+  -H "Authorization: Bearer YOUR_TOKEN"
+
+# 2. 查看浏览器控制台是否有错误
+F12 → Console → 查看错误信息
+
+# 3. 检查后端日志
+查看终端输出的日志信息
+```
+
+---
+
+### **问题 2: 前缀检测不工作**
+
+**可能原因**:
+1. API 路径错误
+2. 参数传递错误
+3. 数据库表不存在
+
+**排查步骤**:
+```bash
+# 1. 手动调用检测接口
+curl -G "http://localhost:9531/api/v1/ddns/check-prefix" \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  --data-urlencode "service_id={service_id}" \
+  --data-urlencode "prefix=test"
+
+# 2. 检查数据库表结构
+sqlite3 meshray.db ".schema ddns_usages"
+
+# 3. 查看前端网络请求
+F12 → Network → 查找 check-prefix 请求
+```
+
+---
+
+### **问题 3: 创建组网失败**
+
+**可能原因**:
+1. 事务处理错误
+2. 外键约束冲突
+3. 字段长度超限
+
+**排查步骤**:
+```bash
+# 1. 查看后端日志
+终端输出会显示详细错误信息
+
+# 2. 检查数据库状态
+sqlite3 meshray.db "SELECT * FROM networks ORDER BY id DESC LIMIT 1;"
+
+# 3. 查看浏览器控制台
+F12 → Console → 查看 JavaScript 错误
+```
+
+---
+
+## 📊 测试结果记录表
+
+| 测试项 | 预期结果 | 实际结果 | 状态 | 备注 |
+|--------|----------|----------|------|------|
+| DDNS 服务配置 | 保存成功 | | ⬜ | |
+| 服务列表加载 | 显示已配置的服务 | | ⬜ | |
+| 自动生成模式 | 显示预览 | | ⬜ | |
+| 自定义模式检测 | 实时检测占用 | | ⬜ | |
+| 创建组网（自动） | 成功创建 | | ⬜ | |
+| 创建组网（自定义） | 成功创建 | | ⬜ | |
+| 前缀冲突检测 | 正确识别占用 | | ⬜ | |
+| 数据库记录 | 字段完整 | | ⬜ | |
+| Usage API | 返回正确数据 | | ⬜ | |
+
+---
+
+## ✅ 验收标准
+
+### **功能完整性**
+- [x] 后端 API 全部实现
+- [x] 前端 UI 全部实现
+- [ ] 前后端联调通过
+- [ ] 完整流程无报错
+
+### **数据正确性**
+- [ ] Network 表 DDNS 字段正确存储
+- [ ] DDNSUsage 表 PrefixMode 正确标记
+- [ ] RecordPrefix 格式正确（auto 为 Base64，custom 为用户输入）
+- [ ] NetworkDDNSBinding 表绑定关系正确
+
+### **用户体验**
+- [ ] DDNS 服务列表正确加载
+- [ ] 自动生成模式有清晰预览
+- [ ] 自定义模式实时检测（500ms 防抖）
+- [ ] 占用状态直观显示（绿/红标签）
+- [ ] 错误提示清晰明确
+
+### **性能表现**
+- [ ] API 响应时间 < 200ms
+- [ ] 前端操作流畅无卡顿
+- [ ] 防抖机制正常工作
+
+---
+
+## 🚀 开始测试
+
+**服务已启动**: http://localhost:9531
+
+**测试步骤**:
+1. 点击预览按钮打开浏览器
+2. 登录系统（admin/admin123）
+3. 按照上述测试清单逐项测试
+4. 记录测试结果
+
+**发现问题**:
+- 如果发现任何 bug 或不一致，立即记录并修复
+- 如果 API 报错，检查后端日志和前端 Network 面板
+- 如果 UI 不显示，检查浏览器 Console 和后端日志
+
+准备开始测试了吗？🎯