# GSModbus 使用操作指南

## 系统概述

GSModbus 是一个通用的、配置驱动的 C# Windows Forms 应用程序，用于实现 PLC 与 MES 系统之间的 Modbus TCP 通信。系统通过 JSON 配置文件实现动态配置，无需修改代码即可适配不同的 PLC 设备和地址映射。

## 快速开始

### 1. 启动应用程序

双击 `GSModbus.exe` 或使用以下命令启动：
```bash
dotnet run
```

### 2. 选择配置文件

应用程序启动后，您需要选择适合的配置文件：

#### 方法一：点击"选择配置文件"按钮
1. 点击界面上的 **"选择配置文件"** 按钮
2. 在弹出的文件选择对话框中，导航到 `config` 文件夹
3. 选择合适的配置文件（通常是 `.json` 文件）
4. 点击"打开"

#### 方法二：使用预置配置文件
系统提供两个预配置文件：

1. **production_config.json** - 生产环境配置（推荐）
   - 位置：`config/production_config.json`
   - 基于实际需求文档配置
   - PLC地址：192.168.3.250:502
   - 包含完整的 D6000-D6048 地址映射

2. **modbus_config.json** - 演示配置
   - 位置：`config/modbus_config.json`
   - 用于学习和测试

### 3. 测试数据库连接（可选）

配置文件加载成功后，如果启用了数据库功能，系统会自动显示数据库连接状态：

#### 数据库连接界面说明
- **数据库状态显示**：位于PLC连接状态右侧，显示当前数据库连接状态
- **测试数据库按钮**：用于手动测试数据库连接
- **状态指示器**：绿色表示连接成功，红色表示连接失败

#### 数据库连接测试步骤
1. 检查数据库状态显示（位于PLC连接状态右侧）
2. 点击 **"测试数据库"** 按钮验证数据库连接
3. 观察状态变化：
   - 🟢 **连接成功**：显示绿色状态和成功信息
   - 🔴 **连接失败**：显示红色状态和错误信息
4. 如果连接失败，请检查数据库配置和网络连接

#### 自动表创建功能
系统支持自动创建必需的数据库表：
- **PRODUCTION_DATA**：存储从PLC读取的生产数据
- **COMMUNICATION_LOG**：记录通信事件和状态
- **ERROR_LOG**：记录系统错误和异常
- **STATISTICS**：保存通信统计信息

**注意**：Oracle 11g数据库采用原生SQL方式创建表，确保最佳兼容性

### 4. 连接 PLC

数据库连接确认无误后（如果启用了数据库功能）：
1. 检查界面上的配置文件状态显示为绿色
2. 确认数据库状态显示为绿色（如果启用）
3. 点击 **"连接PLC"** 按钮
4. 等待连接状态变为"已连接"（绿色）
5. 开始接收 PLC 数据并自动保存到数据库（如果启用）

## 配置文件详解

### 配置文件结构

配置文件采用 JSON 格式，主要包含以下部分：

```json
{
  "ConfigVersion": "1.0",
  "ProjectName": "项目名称",
  "Connection": {
    "IpAddress": "192.168.3.250",
    "Port": 502
  },
  "InputAddresses": {
    "ControlSignals": { ... },
    "ProductData": { ... },
    "MeasurementData": { ... }
  },
  "Database": { ... }
}
```

### 关键配置项说明

#### 1. 连接配置 (Connection)
```json
{
  "Connection": {
    "IpAddress": "192.168.3.250",    // PLC IP地址
    "Port": 502,                     // Modbus TCP端口
    "ConnectionTimeoutMs": 5000,     // 连接超时时间
    "OperationTimeoutMs": 3000       // 操作超时时间
  }
}
```

#### 2. 数据地址配置 (InputAddresses)
系统支持三种数据类别：

- **ControlSignals** - 控制信号（如心跳、数据就绪信号）
- **ProductData** - 产品数据（如型号、测试结果、时间戳）
- **MeasurementData** - 测量数据（如尺寸、电压、电流等）

#### 3. 数据类型支持
- **Byte**: 单字节数值 (0-255)
- **Integer**: 多字节整数，支持缩放
- **String**: 字符串，支持大端/小端编码
- **Timestamp**: 时间戳，支持自定义格式
- **Float**: 浮点数
- **Boolean**: 布尔值

### 自定义配置文件

#### 创建新的配置文件
1. 复制现有的配置文件（如 `production_config.json`）
2. 修改以下关键参数：
   - `IpAddress`: PLC的IP地址
   - `Port`: Modbus TCP端口（通常为502）
   - `ProjectName`: 项目名称
   - 地址映射：根据实际PLC地址修改各字段的 `Address` 值

#### 配置文件示例
```json
{
  "ConfigVersion": "1.0",
  "ProjectName": "我的项目",
  "Connection": {
    "IpAddress": "192.168.1.100",
    "Port": 502
  },
  "InputAddresses": {
    "ProductData": {
      "ProductModel": {
        "Address": 6004,
        "DataType": "String",
        "Length": 10,
        "DisplayName": "产品型号"
      }
    }
  }
}
```

## 操作流程

### 标准操作流程

1. **启动应用程序**
   - 运行 GSModbus.exe

2. **加载配置文件**
   - 点击"选择配置文件"按钮
   - 选择合适的 `.json` 配置文件
   - 确认配置文件状态显示为绿色

3. **连接PLC**
   - 点击"连接PLC"按钮
   - 等待连接状态变为"已连接"

4. **监控数据**
   - 查看日志窗口中的实时数据
   - 监控连接状态和统计信息

5. **断开连接**
   - 点击"断开连接"按钮
   - 或直接关闭应用程序

### 日志解读

系统日志按类别显示接收的数据：

```
📊 [数据 #1] 14:30:25.123
   控制信号:
     • PLC心跳: 1
     • 数据就绪: 数据就绪
   产品数据:
     • 产品型号: ABC123
     • 测试结果: 合格
   测量数据:
     • 工作电压: 24.50 V
     • 工作电流: 1.25 A
   --------------------------------------------------
```

## 数据库功能

### 数据库配置

系统支持多种数据库：
- Oracle 11g（推荐用于生产环境）
- SQL Server
- MySQL
- SQLite

### 配置数据库连接

在配置文件中设置数据库参数：
```json
{
  "Database": {
    "Enabled": true,
    "Type": "Oracle",
    "ConnectionString": "Data Source=localhost:1521/XE;User Id=PRODUCTION_MES;Password=your_password;",
    "AutoCreateTables": true,
    "DataRetentionDays": 90,
    "Tables": {
      "ModbusDataTable": "PRODUCTION_DATA",
      "CommunicationLogTable": "COMMUNICATION_LOG",
      "ErrorLogTable": "ERROR_LOG",
      "StatisticsTable": "STATISTICS"
    }
  }
}
```

#### 数据库配置参数说明
- **Enabled**：是否启用数据库功能（true/false）
- **Type**：数据库类型（Oracle、SqlServer、MySQL、SQLite）
- **ConnectionString**：数据库连接字符串
- **AutoCreateTables**：是否自动创建数据库表
- **DataRetentionDays**：数据保留天数（0表示不自动清理）
- **Tables**：自定义表名配置（可选，使用默认名称如果未指定）

### 数据库表结构

系统自动创建以下表：

#### 1. PRODUCTION_DATA（生产数据表）
- **ID**：主键，自增序列
- **READ_TIME**：数据读取时间
- **PROJECT_NAME**：项目名称
- **PLC_IP_ADDRESS**：PLC IP地址
- **CONTROL_SIGNALS_JSON**：控制信号数据（JSON格式）
- **PRODUCT_DATA_JSON**：产品数据（JSON格式）
- **MEASUREMENT_DATA_JSON**：测量数据（JSON格式）
- **RAW_REGISTERS_JSON**：原始寄存器数据（调试用）
- **CREATED_AT**：记录创建时间

#### 2. COMMUNICATION_LOG（通信日志表）
- **ID**：主键，自增序列
- **LOG_TIME**：日志时间
- **PROJECT_NAME**：项目名称
- **PLC_IP_ADDRESS**：PLC IP地址
- **EVENT_TYPE**：事件类型（连接、断开、数据读取等）
- **EVENT_DESCRIPTION**：事件描述
- **IS_SUCCESS**：是否成功（1/0）
- **DURATION_MS**：操作耗时（毫秒）
- **ADDITIONAL_DATA_JSON**：附加数据

#### 3. ERROR_LOG（错误日志表）
- **ID**：主键，自增序列
- **ERROR_TIME**：错误发生时间
- **PROJECT_NAME**：项目名称
- **PLC_IP_ADDRESS**：PLC IP地址
- **ERROR_TYPE**：错误类型
- **ERROR_MESSAGE**：错误消息
- **STACK_TRACE**：堆栈跟踪
- **SEVERITY**：严重级别（High/Medium/Low）
- **RETRY_COUNT**：重试次数
- **IS_RESOLVED**：是否已解决（1/0）

#### 4. STATISTICS（统计信息表）
- **ID**：主键，自增序列
- **STATISTICS_TIME**：统计时间
- **PROJECT_NAME**：项目名称
- **PLC_IP_ADDRESS**：PLC IP地址
- **TOTAL_CONNECTION_ATTEMPTS**：总连接尝试次数
- **SUCCESSFUL_CONNECTIONS**：成功连接次数
- **TOTAL_DATA_READS**：总数据读取次数
- **SUCCESSFUL_DATA_READS**：成功数据读取次数
- **TOTAL_ERRORS**：总错误次数
- **AVERAGE_RESPONSE_TIME_MS**：平均响应时间
- **MAX_RESPONSE_TIME_MS**：最大响应时间
- **MIN_RESPONSE_TIME_MS**：最小响应时间
- **CONNECTION_SUCCESS_RATE**：连接成功率
- **DATA_READ_SUCCESS_RATE**：数据读取成功率
- **PERIOD_START**：统计周期开始时间
- **PERIOD_END**：统计周期结束时间

**注意**：Oracle 11g表创建采用原生SQL语句，与SqlSugar ORM分离以确保兼容性

## 故障排除

### 常见问题及解决方法

#### 1. 无法连接 PLC
**现象**: 点击连接后显示"连接PLC失败"
**解决方法**:
- 检查PLC IP地址是否正确
- 确认网络连接是否正常
- 验证PLC Modbus TCP服务是否启用
- 检查防火墙设置

#### 2. 配置文件加载失败
**现象**: 配置文件状态显示为红色
**解决方法**:
- 检查JSON格式是否正确
- 验证必填字段是否完整
- 确认文件路径是否存在

#### 3. 数据读取异常
**现象**: 连接成功但无数据或数据错误
**解决方法**:
- 检查地址映射是否正确
- 验证数据类型配置
- 确认PLC寄存器数据是否有效

#### 4. 数据库连接失败
**现象**: 数据库状态显示为红色，或点击"测试数据库"按钮后显示连接失败
**解决方法**:
- **检查连接字符串**：确认数据库IP、端口、用户名、密码正确
- **验证数据库服务**：确认Oracle/SQL Server等数据库服务正在运行
- **检查网络连接**：确保应用程序能访问数据库服务器
- **验证用户权限**：确认数据库用户有创建表和读写数据的权限
- **Oracle特殊问题**：如果是Oracle数据库，确保已安装Oracle Client或使用Oracle.ManagedDataAccess

#### 5. Oracle数据库特殊问题
**现象**: 提示"ORA-00936: 缺失表达式"或其他Oracle语法错误
**解决方法**:
- 系统已针对Oracle 11g进行优化，使用原生SQL方式创建表
- 确保Oracle连接字符串格式正确：`Data Source=IP:PORT/SERVICE_NAME;User Id=USERNAME;Password=PASSWORD;`
- 检查Oracle服务名称和监听器配置
- 如需手动创建表，参考`DatabaseManager.cs`中的Oracle建表脚本

#### 6. 自动建表失败
**现象**: 数据库连接成功但表创建失败
**解决方法**:
- 检查数据库用户是否有CREATE TABLE权限
- 对于Oracle，确保用户有足够的表空间配额
- 检查表名是否与现有对象冲突
- 查看应用程序日志获取详细错误信息
- 如果需要，可以手动执行建表脚本

## 高级功能

### 1. 命令行参数

```bash
# 运行演示模式
dotnet run -- demo

# 指定配置文件
dotnet run -- --config "path/to/config.json"
```

### 2. 配置验证

系统在加载配置文件时会自动验证：
- **连接配置**：IP地址格式、端口号范围、超时设置
- **地址映射**：地址完整性、数据类型有效性、字段长度
- **数据库配置**：连接字符串格式、数据库类型支持
- **表配置**：表名有效性、命名规范

### 3. 数据库连接测试

系统提供实时数据库连接测试功能：
- **自动检测**：配置加载后自动检测数据库连接状态
- **手动测试**：点击"测试数据库"按钮进行连接验证
- **状态显示**：实时显示连接状态（绿色=成功，红色=失败）
- **错误诊断**：显示详细的连接失败原因

### 4. 自动表管理

数据库表自动创建和管理功能：
- **智能检测**：自动检测表是否存在，避免重复创建
- **兼容处理**：Oracle使用原生SQL，其他数据库使用SqlSugar ORM
- **错误容错**：表已存在时不会报错，继续正常运行
- **日志记录**：详细记录表创建过程和结果

### 3. 自动重连

系统支持自动重连功能：
- 连接断开时自动尝试重连
- 可配置重连间隔和最大重试次数
- 重连状态实时显示

## 部署注意事项

### 系统要求
- .NET 8.0 或更高版本
- Windows 操作系统
- 网络连接到目标PLC

### 配置文件管理
- 将配置文件放在 `config/` 目录下
- 建议为不同项目创建独立的配置文件
- 定期备份重要的配置文件
- 使用有意义的文件名（如：`生产线A_config.json`、`测试环境_config.json`）

### 数据库安全
- **连接字符串保护**：避免在配置文件中使用明文密码
- **权限控制**：为应用程序创建专用数据库用户，仅授予必要权限
- **数据加密**：敏感数据在传输和存储时进行加密
- **访问日志**：启用数据库访问日志记录

### 性能优化
- **连接池**：系统自动管理数据库连接池
- **批量操作**：支持批量插入数据以提高性能
- **自动清理**：根据配置自动清理过期数据
- **索引优化**：关键字段已创建适当索引

### 安全考虑
- 保护数据库连接字符串中的密码
- 限制网络访问权限
- 定期更新系统组件

## 技术支持

### 日志文件位置
- 应用程序日志：界面日志窗口
- 系统调试信息：控制台输出

### 配置示例
参考 `config/` 目录下的示例配置文件：
- `production_config.json` - 生产环境配置
- `modbus_config.json` - 基础配置模板

### 文档资源
- `config/Oracle使用指南.md` - Oracle 11g数据库配置指南
- `docu/需求.txt` - 原始需求文档和PLC地址映射
- `CLAUDE.md` - 开发者指南和项目架构说明
- `docu/MES地址.xlsx` - 详细的PLC地址映射表

### 数据库相关文件
- `Database/DatabaseManager.cs` - 数据库管理核心代码
- `Database/DatabaseEntities.cs` - 数据库实体定义
- `config/production_config.json` - 包含数据库配置的生产环境配置
- `GSModbus.csproj` - 项目文件，包含数据库驱动包引用

---

---

## 更新记录

### 版本 1.1（当前版本）
**更新日期**: 2024年12月  
**主要更新**:
- ✅ 新增数据库连接测试按钮和状态显示
- ✅ 增强Oracle 11g兼容性，使用原生SQL建表
- ✅ 自动表创建功能，支持多种数据库类型
- ✅ 改进数据库配置管理，支持自定义表名
- ✅ 优化错误处理和日志记录
- ✅ 添加数据库性能优化和安全增强

### 版本 1.0
**更新日期**: 2024年  
**功能**: GSModbus基础通信系统

---

**适用于**: GSModbus通用Modbus通信系统  
**数据库支持**: Oracle 11g, SQL Server, MySQL, SQLite  
**开发框架**: .NET 8.0 Windows Forms