连接配置页面使用指南

📋 概述

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

🎯 功能特性

✨ 核心功能

分组表单管理：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/   # 差异发布对话框

组件关系图

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：移动端优化布局

布局适配

// 大屏双列布局
@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地址验证

const ipPattern = /^(25[0-5]|2[0-4]\d|1?\d?\d)(\.(25[0-5]|2[0-4]\d|1?\d?\d)){3}$/

URL验证

const urlPattern = /^https?:\/\/.+/

MQTT地址验证

const mqttPattern = /^mqtt:\/\/.+:\d+$/

端口范围验证

const portRange = { min: 1, max: 65535 }

🔄 交互流程

1. 页面加载流程

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. 配置变更流程

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

3. 测试连接流程

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. 发布配置流程

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 特性

敏感值保护

// 密钥字段默认掩码显示
showSecrets: {
  mqttSecret: false  // 默认隐藏
}

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

变更检测

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

错误统计

// 统计表单验证错误
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	动态

测试日志格式

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

差异数据格式

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

🚀 使用示例

1. 基本使用

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

2. 测试连接

// 测试单个分组
await this.testGroup('基础网络')

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

3. 配置发布

// 获取配置差异
const diffs = getConfigDiffs(this.originalData, this.formData)

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

4. 主题适配

所有组件都自动支持明暗主题切换：

// 切换主题
window.toggleTheme()

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

🔧 自定义扩展

1. 添加新的配置分组

<XtGroupedFormCard
  title="新分组"
  desc="新分组的描述"
  @test="() => testGroup('新分组')"
  @reset="() => resetGroup('newGroup')"
>
  <!-- 表单内容 -->
</XtGroupedFormCard>

2. 扩展验证规则

formRules: {
  newField: [
    { required: true, message: '请输入新字段', trigger: 'blur' },
    { validator: customValidator, trigger: 'blur' }
  ]
}

3. 自定义测试步骤

// 在 mock/connection.js 中添加
const testSteps = {
  '新分组': [
    {
      name: '检查新配置',
      getTip: (status, config) => {
        return status === 'ok' ? '配置正确' : '配置错误'
      }
    }
  ]
}

🐛 常见问题

Q: 为什么表单验证不生效？

A: 确保在 handleFieldChange 方法中正确映射了表单引用：

const formMap = {
  newField: 'newForm'  // 添加新字段映射
}

Q: 如何添加新的敏感字段？

A: 在 showSecrets 对象中添加字段，并在模板中使用 show-password 属性：

showSecrets: {
  newSecret: false
}

Q: 移动端摘要面板不显示怎么办？

A: 检查响应式断点设置，确保 isMobile 计算属性正确：

isMobile() {
  return this.windowWidth < 1280
}

📞 技术支持

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

Happy Coding! 🎉

CONNECTION_CONFIG_GUIDE.md 10 KB History Raw