# 连接配置页面使用指南

## 📋 概述

全新的连接配置页面采用现代化设计，使用分组表单卡片 + 右侧摘要 + 底部粘性操作栏的布局，提供直观的配置管理体验。

## 🎯 功能特性

### ✨ 核心功能
- **分组表单管理**：4个配置分组（基础网络、MQTT、HTTP/回调、代理与安全）
- **实时变更检测**：自动对比初始值，显示变更数量和状态
- **分组测试**：每个分组独立测试连接状态
- **发布前对比**：可视化显示配置差异，支持选择性发布
- **响应式布局**：完美适配桌面端和移动端

### 🔧 技术特性
- **表单验证**：IP地址、URL、端口等格式校验
- **敏感值保护**：密钥等敏感字段默认掩码显示
- **文件上传**：支持证书文件上传，格式验证
- **Mock API**：完整的模拟后端接口，支持异步测试

## 🏗️ 架构设计

### 文件结构
```
src/
├── api/mock/
│   └── connection.js           # Mock API 接口
├── views/config/connectconf/
│   └── index.vue              # 连接配置主页面
└── components/                # 通用组件
    ├── XtGroupedFormCard/     # 分组表单卡片
    ├── XtRightSummaryPanel/   # 右侧摘要面板
    ├── XtStickyActionBar/     # 底部粘性操作栏
    ├── XtTestConnectionDrawer/ # 测试连接抽屉
    └── XtDiffPublishDialog/   # 差异发布对话框
```

### 组件关系图
```mermaid
graph TD
    A[连接配置页面] --> B[分组表单卡片]
    A --> C[右侧摘要面板]
    A --> D[底部操作栏]
    A --> E[测试连接抽屉]
    A --> F[发布确认对话框]
    
    B --> B1[基础网络]
    B --> B2[MQTT配置]
    B --> B3[HTTP/回调]
    B --> B4[代理与安全]
    
    C --> C1[统计信息]
    C --> C2[配置项列表]
    C --> C3[快速操作]
    
    D --> D1[保存草稿]
    D --> D2[测试全部]
    D --> D3[发布变更]
    D --> D4[回滚配置]
```

## 📱 响应式设计

### 断点设置
- **≥1440px**：两列卡片布局 + 右侧摘要面板
- **1280-1439px**：单列卡片布局 + 右侧摘要面板
- **<1280px**：单列卡片布局 + 顶部摘要按钮（抽屉形式）
- **<768px**：移动端优化布局

### 布局适配
```scss
// 大屏双列布局
@media (min-width: 1440px) {
  .form-groups {
    grid-template-columns: 1fr 1fr;
  }
}

// 中屏隐藏右侧面板
@media (max-width: 1279px) {
  .desktop-summary {
    display: none;
  }
  .mobile-only {
    display: block;
  }
}

// 移动端优化
@media (max-width: 768px) {
  .page-header {
    padding: var(--spacing-4);
  }
  .form-groups {
    gap: var(--spacing-4);
  }
}
```

## 🔧 配置字段说明

### 1. 基础网络配置
| 字段名 | 类型 | 必填 | 校验规则 | 说明 |
|--------|------|------|----------|------|
| toolIp | String | ✅ | IP格式 | 工具机IP地址 |
| serverIp | String | ✅ | IP格式 | 服务器IP地址 |
| enableProxy | Boolean | - | - | 是否启用代理 |
| netProxy | String | - | URL格式 | 网络代理地址 |

### 2. MQTT 配置
| 字段名 | 类型 | 必填 | 校验规则 | 说明 |
|--------|------|------|----------|------|
| mqttBroker | String | ✅ | MQTT URL格式 | MQTT代理地址 |
| mqttProductId | String | ✅ | 3-50字符 | 产品ID |
| mqttDeviceId | String | ✅ | 3-50字符 | 设备ID |
| mqttSecret | String | ✅ | 最少8位 | 设备密钥（敏感字段） |

### 3. HTTP/回调 配置
| 字段名 | 类型 | 必填 | 校验规则 | 说明 |
|--------|------|------|----------|------|
| httpBase | String | ✅ | HTTP/HTTPS URL | HTTP基础地址 |
| httpTimeout | Number | ✅ | 1000-300000 | 超时时间（毫秒） |

### 4. 代理与安全配置
| 字段名 | 类型 | 必填 | 校验规则 | 说明 |
|--------|------|------|----------|------|
| packetFilter | Boolean | - | - | 数据包过滤开关 |
| certFile | File | - | 证书格式，<2MB | 证书文件 |

## 🧪 校验规则

### IP地址验证
```javascript
const ipPattern = /^(25[0-5]|2[0-4]\d|1?\d?\d)(\.(25[0-5]|2[0-4]\d|1?\d?\d)){3}$/
```

### URL验证
```javascript
const urlPattern = /^https?:\/\/.+/
```

### MQTT地址验证
```javascript
const mqttPattern = /^mqtt:\/\/.+:\d+$/
```

### 端口范围验证
```javascript
const portRange = { min: 1, max: 65535 }
```

## 🔄 交互流程

### 1. 页面加载流程
```mermaid
sequenceDiagram
    participant U as 用户
    participant P as 页面
    participant A as Mock API
    
    U->>P: 访问连接配置页面
    P->>A: 调用 getConfig()
    A-->>P: 返回当前配置和草稿
    P->>P: 初始化表单数据
    P->>P: 计算变更状态
    P-->>U: 显示配置界面
```

### 2. 配置变更流程
```mermaid
sequenceDiagram
    participant U as 用户
    participant P as 页面
    participant S as 摘要面板
    
    U->>P: 修改配置字段
    P->>P: 触发字段验证
    P->>P: 计算变更差异
    P->>S: 更新摘要统计
    S-->>U: 实时显示变更状态
```

### 3. 测试连接流程
```mermaid
sequenceDiagram
    participant U as 用户
    participant P as 页面
    participant D as 测试抽屉
    participant A as Mock API
    
    U->>P: 点击"测试该组"
    P->>D: 打开测试抽屉
    P->>A: 调用 testConnection()
    A-->>P: 返回测试日志
    P->>D: 显示时间轴日志
    D-->>U: 展示测试结果
```

### 4. 发布配置流程
```mermaid
sequenceDiagram
    participant U as 用户
    participant P as 页面
    participant Diff as 差异对话框
    participant A as Mock API
    
    U->>P: 点击"发布"
    P->>P: 生成配置差异
    P->>Diff: 显示差异对话框
    U->>Diff: 选择要发布的字段
    Diff->>A: 调用 publishConfig()
    A-->>Diff: 返回发布结果
    Diff->>P: 更新原始数据
    P-->>U: 显示发布成功
```

## 🎨 UI/UX 特性

### 敏感值保护
```javascript
// 密钥字段默认掩码显示
showSecrets: {
  mqttSecret: false  // 默认隐藏
}

// 点击眼睛图标切换显示
toggleSecret(field) {
  this.showSecrets[field] = !this.showSecrets[field]
}
```

### 变更检测
```javascript
// 实时计算变更数量
dirtyCount() {
  let count = 0
  Object.keys(this.formData).forEach(key => {
    if (JSON.stringify(this.formData[key]) !== JSON.stringify(this.originalData[key])) {
      count++
    }
  })
  return count
}
```

### 错误统计
```javascript
// 统计表单验证错误
errorCount() {
  let count = 0
  const forms = ['networkForm', 'mqttForm', 'httpForm', 'securityForm']
  forms.forEach(formName => {
    if (this.$refs[formName]) {
      this.$refs[formName].fields.forEach(field => {
        if (field.validateState === 'error') {
          count++
        }
      })
    }
  })
  return count
}
```

## 📊 Mock API 说明

### API 接口清单
| 接口名称 | 功能 | 延迟 | 失败率 |
|----------|------|------|--------|
| `getConfig()` | 获取配置 | 300ms | 0% |
| `saveDraft()` | 保存草稿 | 500ms | 10% |
| `publishConfig()` | 发布配置 | 1000ms | 5% |
| `rollbackConfig()` | 回滚配置 | 800ms | 3% |
| `testConnection()` | 测试连接 | 800-1500ms | 动态 |

### 测试日志格式
```javascript
{
  ts: 1640995200000,           // 时间戳
  step: '连接数据库',           // 步骤名称
  status: 'ok',                // 状态: 'ok'|'warn'|'fail'
  cost: 120,                   // 耗时(ms)
  tip: '连接成功',             // 提示信息
  details: '详细日志信息...'    // 详细信息(可选)
}
```

### 差异数据格式
```javascript
{
  key: 'database.host',        // 配置键
  name: '数据库主机',          // 显示名称
  path: 'config.database',     // 配置路径
  oldValue: 'localhost',       // 原值
  newValue: '192.168.1.100',   // 新值
  isChanged: true,             // 是否变更
  isNew: false,                // 是否新增
  isDeleted: false,            // 是否删除
  description: '主机地址变更'   // 变更说明
}
```

## 🚀 使用示例

### 1. 基本使用
```vue
<template>
  <!-- 页面会自动加载配置数据 -->
  <div>
    <!-- 修改配置字段会自动触发变更检测 -->
    <!-- 右侧摘要面板会实时更新统计信息 -->
    <!-- 底部操作栏会显示变更和错误数量 -->
  </div>
</template>
```

### 2. 测试连接
```javascript
// 测试单个分组
await this.testGroup('基础网络')

// 测试所有分组
await this.handleTestAll()
```

### 3. 配置发布
```javascript
// 获取配置差异
const diffs = getConfigDiffs(this.originalData, this.formData)

// 发布选中的配置
await publishConfig(['toolIp', 'serverIp'])
```

### 4. 主题适配
所有组件都自动支持明暗主题切换：
```javascript
// 切换主题
window.toggleTheme()

// 设置特定主题
window.setTheme('dark')  // 或 'light', 'auto'
```

## 🔧 自定义扩展

### 1. 添加新的配置分组
```vue
<XtGroupedFormCard
  title="新分组"
  desc="新分组的描述"
  @test="() => testGroup('新分组')"
  @reset="() => resetGroup('newGroup')"
>
  <!-- 表单内容 -->
</XtGroupedFormCard>
```

### 2. 扩展验证规则
```javascript
formRules: {
  newField: [
    { required: true, message: '请输入新字段', trigger: 'blur' },
    { validator: customValidator, trigger: 'blur' }
  ]
}
```

### 3. 自定义测试步骤
```javascript
// 在 mock/connection.js 中添加
const testSteps = {
  '新分组': [
    {
      name: '检查新配置',
      getTip: (status, config) => {
        return status === 'ok' ? '配置正确' : '配置错误'
      }
    }
  ]
}
```

## 🐛 常见问题

### Q: 为什么表单验证不生效？
**A**: 确保在 `handleFieldChange` 方法中正确映射了表单引用：
```javascript
const formMap = {
  newField: 'newForm'  // 添加新字段映射
}
```

### Q: 如何添加新的敏感字段？
**A**: 在 `showSecrets` 对象中添加字段，并在模板中使用 `show-password` 属性：
```javascript
showSecrets: {
  newSecret: false
}
```

### Q: 移动端摘要面板不显示怎么办？
**A**: 检查响应式断点设置，确保 `isMobile` 计算属性正确：
```javascript
isMobile() {
  return this.windowWidth < 1280
}
```

## 📞 技术支持

如有任何问题或建议，请联系前端开发团队。

**Happy Coding! 🎉**