FlexometerSetup

基于 Electron + React + Vite 开发的传感器监测应用程序

---

📖 目录

• 用户指南
• 开发者文档

---

👥 用户指南

系统要求

• 操作系统: Windows 10/11, macOS 10.15+, Ubuntu 18.04+
• 内存: 4GB RAM 以上
• 存储空间: 200MB 可用空间

安装方法

1. 从 Releases 页面下载最新版本的安装包
2. 运行安装程序，按照向导完成安装
3. 安装完成后，从桌面快捷方式或开始菜单启动应用

主要功能

🔍 设备管理

• 设备搜索: 自动扫描局域网内的传感器设备
• 设备连接: 支持 TCP 连接，实时监控设备状态
• 设备断开: 安全断开设备连接

📊 数据监控

• 实时数据显示: 支持多传感器同时监控
• 数据可视化: Chart.js 图表展示传感器数据趋势
• 历史数据: 保存最近 10 个数据点的历史记录

⚙️ 系统设置

• 基本参数配置:
  • 图像发送时间间隔
  • 零点计数设置
  • 数据帧率调节
  • 视频帧率调节
  • 阈值参数配置
  • 无效数据计数
• 系统功能:
  • 系统清零使能
  • 图像发送控制（开始/停止）
• 重连功能:
  • 断线自动重连
  • 可配置重连间隔（5-60秒）
  • 重连状态实时显示
• 报警功能:
  • 可配置X/Y轴上下限阈值
  • 超阈值自动报警
  • 报警状态实时显示
• 数据记录:
  • 实时数据记录（CSV格式）
  • 报警数据记录（CSV格式）
  • 自定义存储路径
  • 按日期和设备IP分类存储

🔧 测量点管理

• 传感器配置: 实时加载和设置传感器参数
• 数据覆盖更新: 每次加载时更新传感器列表
• 状态监控: 实时显示设备连接状态

使用说明

1. 首次使用

   • 启动应用后，点击"搜索设备"发现网络中的传感器
   • 选择目标设备，点击"连接"建立通信

2. 数据监控

   • 连接成功后，在"挠度采集"页面可查看实时数据
   • 数据会自动更新，支持多传感器同时显示

3. 参数配置

   • 在"系统设置"页面可调整各项参数
   • 修改参数后点击"设置"按钮保存

4. 数据记录与存储

   • 在"系统设置"页面配置存储路径
   • 启用"实时数据"记录功能可保存所有传感器数据
   • 启用"报警功能"并勾选"报警数据"可记录超阈值数据
   • 数据文件按日期自动分类：存储路径/设备IP/实时数据(或报警数据)/YYYYMMDD.csv

5. 报警监控

   • 在"系统设置"中配置X/Y轴上下限阈值
   • 启用报警功能后，超阈值数据会触发报警
   • 报警数据自动记录到单独的CSV文件中

故障排除

设备连接失败

• 检查设备和计算机是否在同一网络
• 确认设备 IP 地址和端口号正确
• 重启应用和设备后重试

自动重连功能

• 在"系统设置"中启用重连功能
• 可设置重连间隔（5-60秒）
• 重连状态会实时显示在界面上

数据显示异常

• 检查设备连接状态
• 确认传感器配置是否正确
• 查看日志文件排查问题

数据记录问题

• 确认存储路径是否有写入权限
• 检查磁盘空间是否充足
• 验证实时数据或报警数据开关是否已启用

报警功能异常

• 检查报警功能是否已启用
• 确认阈值设置是否合理
• 验证报警数据记录开关是否已勾选

应用崩溃或无响应

• 重启应用
• 检查系统资源使用情况
• 联系技术支持

技术支持

• 作者: cles
• 主页: https://blog.clesbit.top
• 邮箱: 208023732@qq.com
• 问题反馈: 请在项目仓库提交 Issue

---

🛠️ 开发者文档

技术栈

• 前端框架: React 18
• 构建工具: Vite
• 桌面框架: Electron
• 状态管理: Zustand
• UI 框架: Ant Design
• 图表库: Chart.js
• 样式: CSS Modules
• 打包工具: electron-builder

项目结构

electron-app/
├── build/                    # 构建资源（图标等）
├── src/
│   ├── main/                # 主进程代码
│   │   ├── index.js         # 主进程入口
│   │   ├── ipcRouter.js     # IPC 路由处理
│   │   ├── autoUpdaterManager.js # 自动更新管理
│   │   └── reconnectManager.js   # 重连管理
│   ├── preload/             # 预加载脚本
│   │   └── index.js
│   └── renderer/            # 渲染进程代码
│       ├── index.html       # HTML 模板
│       └── src/
│           ├── App.jsx      # 应用主组件
│           ├── main.jsx     # 渲染进程入口
│           ├── components/  # React 组件
│           │   ├── AutoUpdater/           # 自动更新组件
│           │   ├── DeflectionCollection/  # 挠度数据采集
│           │   ├── ImageCollection/       # 图像采集
│           │   ├── MeasurementPointSetting/ # 测量点设置
│           │   ├── SiderHeader/           # 侧边栏头部
│           │   └── SystemSettings/        # 系统设置
│           ├── stores/      # Zustand 状态管理
│           │   ├── deviceStore.js    # 设备状态管理
│           │   └── rectangleStore.js # 矩形选择状态
│           ├── common/      # 公共模块
│           │   └── ipcEvents.js # IPC事件常量
│           ├── hooks/       # 自定义Hook
│           └── assets/      # 静态资源
├── logs/                    # 日志文件目录
├── dist/                    # 构建输出目录
├── electron-builder.yml    # 打包配置
├── electron.vite.config.mjs # Vite 配置
└── package.json

开发环境搭建

环境要求

• Node.js 16.0+
• npm 或 yarn

安装依赖

# 克隆项目
git clone <repository-url>
cd electron-app

# 安装依赖
npm install

开发命令

# 启动开发服务器
npm run dev

# 代码格式化
npm run format

# 代码检查
npm run lint

# 构建项目
npm run build

# 打包为可执行文件（不生成安装包）
npm run build:unpack

# 打包为 Windows 安装包
npm run build:win

# 打包为 macOS 安装包
npm run build:mac

# 打包为 Linux 安装包
npm run build:linux

核心模块说明

IPC 通信 (ipcRouter.js)

负责主进程与渲染进程之间的通信，包括：

• 设备搜索和连接管理
• TCP 数据传输处理
• 传感器参数配置
• 系统功能控制

主要事件类型：

// 设备管理
DEVICE_SEARCH         // 设备搜索
DEVICE_CONNECT        // 设备连接
DEVICE_DISCONNECT     // 设备断开

// 数据传输
RESULT_REPLY          // 传感器数据
IMAGE_REPLY           // 图像数据
HEARTBEAT_REPLY       // 心跳包

// 传感器管理
SENSORS_GET / SET     // 传感器配置

// 基本参数配置
IMAGE_SEND_TIME_GET / SET      // 图像发送间隔
ZERO_COUNT_GET / SET           // 零点计数
RESULT_COUNT_GET / SET         // 结果计数
DATA_FPS_GET / SET             // 数据帧率
VIDEO_FPS_GET / SET            // 视频帧率
THRESHOLD_GET / SET            // 阈值
INVALID_DATA_COUNT_GET / SET   // 无效数据计数

// 系统功能
IMAGE_SEND_ENABLED    // 图像发送使能
IS_CLEAR_ZERO        // 系统清零使能

// 重连功能
RECONNECT_CONFIG     // 重连配置
RECONNECT_STATUS     // 重连状态

// 文件操作
OPEN_DIRECTORY       // 打开目录
SELECT_DIRECTORY     // 选择目录
ENSURE_DIRECTORY     // 确保目录存在
APPEND_TO_FILE       // 追加文件内容
CHECK_FILE_EXISTS    // 检查文件是否存在
WRITE_CSV_HEADER     // 写入CSV文件头

状态管理 (stores/)

使用 Zustand 管理全局状态：

• deviceStore.js: 设备连接状态
• rectangleStore.js: 矩形选择状态

UI 组件 (components/)

主要组件模块：

• AutoUpdater/: 自动更新组件
• DeflectionCollection/: 挠度数据采集和可视化
• ImageCollection/: 图像采集显示
• MeasurementPointSetting/: 测量点配置
• SystemSettings/: 系统参数设置和数据记录配置
• SiderHeader/: 侧边栏头部

数据记录系统

实时数据记录

• 格式：CSV文件，包含UTF-8 BOM确保中文正确显示
• 存储路径：存储路径/设备IP/实时数据/YYYYMMDD.csv
• 表头格式：数据记录时间,测点1基准标靶,测点1计算系数,测点1xReal坐标,测点1yReal坐标,...
• 记录条件：勾选"实时数据"开关且设备已连接

报警数据记录

• 格式：CSV文件，专门记录超阈值数据
• 存储路径：存储路径/设备IP/报警数据/YYYYMMDD.csv
• 表头格式：报警记录时间,测点位置,基准标靶,计算系数,xReal坐标,yReal坐标,报警类型,阈值范围,超出值
• 记录条件：同时勾选"报警功能"和"报警数据"开关
• 报警类型：X轴上限超出、X轴下限超出、Y轴上限超出、Y轴下限超出

报警检测逻辑

• 检测X/Y轴坐标是否超出设定的上下限阈值
• null或undefined值不参与报警检测
• 每个测点可同时触发X轴和Y轴报警
• 超出值计算：实际值与阈值的差值

日志系统

使用 electron-log 记录应用日志：

• 开发环境: 日志保存在项目根目录 logs/main.log
• 生产环境: 日志保存在用户数据目录
• 日志内容: IPC 命令、TCP 响应、错误信息等

网络通信

UDP 设备发现

• 端口: 2230
• 广播地址: 255.255.255.255
• 超时机制: 5秒全局超时，收到响应后1秒延迟等待更多设备
• 命令格式: {"command": "name", "type": "get"}

TCP 数据传输

• 默认端口: 2233
• 协议: JSON over TCP
• 消息格式: {"command": "xxx", "type": "xxx", "values": "xxx"}\n\n
• 心跳机制: 设备每2秒发送心跳包，应用5秒检测一次，10秒无心跳则认为断开

自动重连机制

• 可配置是否启用自动重连
• 重连间隔可设置（5-60秒）
• 连接超时时间为重连间隔的80%，最小3秒
• 重连状态实时通知渲染进程
• 支持心跳超时后自动重连

构建和部署

图标配置

将图标文件放入 build/ 目录：

• Windows: icon.ico (256x256, 多分辨率)
• macOS: icon.icns
• Linux: icon.png (512x512)

打包配置

主要配置在 electron-builder.yml：

appId: com.freesun.app
productName: FlexometerSetup
directories:
  buildResources: build

win:
  executableName: FlexometerSetup

nsis:
  oneClick: false # 启用安装向导
  allowToChangeInstallationDirectory: true # 允许选择安装路径
  createDesktopShortcut: always # 创建桌面快捷方式

发布流程

1. 本地构建测试

   npm run build:win
   

2. 创建 Release

   • 在代码仓库创建新的 Release
   • 上传生成的 setup.exe 安装包
   • 添加版本说明和更新日志

开发规范

代码风格

• 使用 Prettier 格式化代码
• 使用 ESLint 进行代码检查
• 组件文件使用 PascalCase 命名
• 样式文件使用 CSS Modules

IPC 事件规范

• 所有IPC事件名称统一定义在 common/ipcEvents.js 中
• 事件名称使用 模块:操作 格式，如 device:connect
• 主进程和渲染进程必须使用 IPC_EVENT 常量，禁止硬编码字符串
• 文件操作事件统一使用 file: 前缀

状态管理规范

• 使用 useRef 避免回调函数中的闭包问题
• 长期状态使用 Zustand 全局状态管理
• 组件内部状态优先使用 useState

提交规范

使用语义化提交信息：

feat: 添加新功能
fix: 修复问题
docs: 更新文档
style: 代码格式调整
refactor: 代码重构
test: 添加测试
chore: 构建或工具相关

分支管理

• main: 主分支，用于发布
• develop: 开发分支
• feature/*: 功能分支
• hotfix/*: 热修复分支

贡献指南

1. Fork 项目仓库
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'feat: add amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

---