# 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 和后端日志

准备开始测试了吗？🎯