# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

GSModbus is a **universal, configuration-driven** C# Windows Forms application for Modbus TCP communication between PLC and MES systems. The system supports **dynamic configuration** through JSON files, making it adaptable to different PLC setups and address mappings without code changes.

## Development Environment

- **Framework**: .NET 8.0 
- **Platform**: Windows desktop application
- **UI**: Windows Forms
- **Target**: x64 Windows
- **Dependencies**: EasyModbusTCP, System.Text.Json, SqlSugar

## Database Environment

Oracle Database 11g Enterprise Edition Release 11.2.0.1.0 - 64bit Production

- PL/SQL Release 11.2.0.1.0 - Production
- CORE 11.2.0.1.0 Production
- TNS for 64-bit Windows: Version 11.2.0.1.0 - Production
- NLSRTL Version 11.2.0.1.0 - Production

**IMPORTANT**: All code must be compatible with Oracle 11g Release 11.2.0.1.0
所有的回答都需要基于这个版本可以兼容的做法

## Common Commands

### Build and Run
```bash
# Build the project
dotnet build

# Run the application
dotnet run

# Run configuration demo
dotnet run --project . -- demo

# Build for release
dotnet build -c Release

# Clean build artifacts
dotnet clean
```

### Development
```bash
# Restore dependencies
dotnet restore

# Build and run in one command
dotnet run
```

## Project Architecture

### Core Components

#### 1. Configuration System (`Config/`)
- **ModbusConfiguration.cs**: Configuration data models including database settings
- **ConfigurationManager.cs**: Config loading, validation, and management
- **modbus_config.json**: Demo JSON configuration template
- **production_config.json**: Production configuration based on actual requirements

#### 2. Universal Communication (`UniversalModbusManager.cs`)
- **Configuration-driven**: Uses JSON config for all settings
- **Dynamic data parsing**: Supports multiple data types (string, integer, timestamp, etc.)
- **Automatic reconnection**: Configurable retry logic
- **Real-time statistics**: Connection and communication metrics
- **Database integration**: Automatic data logging to database

#### 3. Data Processing
- **DynamicModbusData.cs**: Dynamic data container with type-safe access
- **ModbusDataParser.cs**: Configuration-based data parsing and formatting

#### 4. Database Layer (`Database/`)
- **DatabaseManager.cs**: SqlSugar-based database operations
- **DatabaseEntities.cs**: Entity models for data storage
- **Supports**: Oracle 11g, SQL Server, MySQL, SQLite

#### 5. User Interface
- **Form1.cs**: Simplified Windows Forms UI with log-based data display
- **ConfigDemo.cs**: Console demo for testing configuration system

#### 6. Legacy Components (for reference)
- **ModbusManager.cs**: Original hardcoded implementation

### Configuration-Driven Design

The system uses **JSON configuration files** to define:

1. **Connection Settings**: IP address, port, timeouts
2. **Communication Parameters**: Heartbeat intervals, polling rates  
3. **Address Mappings**: Dynamic field definitions with:
   - Register addresses
   - Data types (Byte, Integer, String, Timestamp, Float, Boolean)
   - Parsing rules (encoding, scaling, decimal places)
   - Display formatting (units, value mappings)
4. **Database Configuration**: Connection strings, table names, retention policies

#### Example Configuration Structure:
```json
{
  "Connection": {
    "IpAddress": "192.168.3.250",
    "Port": 502
  },
  "InputAddresses": {
    "ProductData": {
      "ProductModel": {
        "Address": 6004,
        "DataType": "String",
        "Length": 10,
        "DisplayName": "产品型号"
      }
    },
    "MeasurementData": {
      "WorkingVoltage": {
        "Address": 6041,
        "DataType": "Integer", 
        "Scale": 0.01,
        "Unit": "V",
        "DisplayName": "工作电压"
      }
    }
  }
}
```

### Key Features

1. **Universal Compatibility**: Works with any PLC by changing configuration
2. **Dynamic Data Types**: Supports strings, integers, timestamps, floats, booleans
3. **Flexible Encoding**: Big-endian/little-endian support for multi-byte data
4. **Value Mapping**: Configurable display formatting (e.g., 0="失败", 1="成功")
5. **Automatic Scaling**: Convert raw values to engineering units
6. **Database Integration**: Automatic data logging with SqlSugar ORM
7. **Multi-Database Support**: Oracle 11g, SQL Server, MySQL, SQLite
8. **Robust Error Handling**: Validation, retry logic, and detailed logging
9. **Simplified UI**: Log-based data display instead of hardcoded controls

### Data Types Supported

- **Byte**: Single byte values (0-255)
- **Integer**: Multi-register integers with scaling (e.g., 12345 → 123.45)
- **String**: ASCII strings with configurable encoding
- **Timestamp**: Date/time parsing with custom formats
- **Float**: IEEE 754 floating point
- **Boolean**: True/false values

## Usage Examples

### 1. Production Configuration Loading
```csharp
var configManager = new ConfigurationManager();
await configManager.LoadConfigurationAsync("config/production_config.json");
var config = configManager.CurrentConfiguration;
```

### 2. Universal Modbus Manager with Database
```csharp
using var modbusManager = new UniversalModbusManager(config);
modbusManager.DataReceived += (sender, data) => {
    var voltage = data.GetDouble("WorkingVoltage");
    var productModel = data.GetString("ProductModel");
    // Data automatically saved to database
};
modbusManager.DatabaseLogOccurred += (sender, log) => Console.WriteLine(log);
await modbusManager.ConnectAsync();
```

### 3. Dynamic Data Access
```csharp
// Type-safe access
var testResult = data.GetBool("TestResult");
var timestamp = data.GetDateTime("RecordTime");
var productCode = data.GetString("ProductCode");

// Formatted display
var displayValue = ModbusDataParser.FormatDisplayValue(
    data.GetFieldValue("WorkingVoltage"), 
    fieldConfig
); // Returns "24.5 V"
```

### 4. Database Operations
```csharp
// Database manager is automatically created and managed
// Manual access if needed:
var dbManager = new DatabaseManager(config.Database, projectName, plcIp);
await dbManager.SaveModbusDataAsync(dynamicData);
await dbManager.LogCommunicationAsync("Connected", "Successfully connected to PLC");
```

## Configuration Files

### Production Configuration (Recommended)
- **Path**: `config/production_config.json`
- **Based on**: Actual requirements from `docu/需求.txt`
- **PLC Address**: 192.168.3.250:502
- **Database**: Oracle 11g (configurable)
- **Address Mapping**: Complete D6000-D6048 register mapping

### Demo Configuration
- **Path**: `config/modbus_config.json`  
- **Purpose**: Learning and testing
- **Template**: Generic configuration example

### Configuration Loading
1. Create new JSON file in `config/` directory
2. Use ConfigurationManager to load: `LoadConfigurationAsync("path/to/config.json")`
3. System validates configuration on load

## Migration from Legacy System

The project maintains **backward compatibility**:
- Original `ModbusManager.cs` still works with hardcoded settings
- New `UniversalModbusManager.cs` provides configuration-driven approach
- Same UI can work with either manager

## Implementation Notes

- **Thread Safety**: All communication operations are async-safe
- **Error Recovery**: Automatic reconnection with configurable retry limits  
- **Performance**: Efficient register reading with batch operations
- **Database Performance**: Connection pooling and batch inserts
- **Logging**: Detailed debug information for troubleshooting
- **Memory Management**: Proper disposal of resources and timers
- **UI Architecture**: Simplified log-based display, removed hardcoded controls

## Database Integration

### Supported Databases
- **Oracle 11g** (primary, production-ready)
- **SQL Server** 
- **MySQL**
- **SQLite**

### Database Tables (Auto-created)
- **PRODUCTION_DATA**: Main Modbus data storage
- **COMMUNICATION_LOG**: Connection events and status
- **ERROR_LOG**: Error tracking and resolution
- **STATISTICS**: Communication performance metrics

### Database Configuration
```json
{
  "Database": {
    "Enabled": true,
    "Type": "Oracle",
    "ConnectionString": "Data Source=localhost:1521/XE;User Id=PRODUCTION_MES;Password=your_password;",
    "AutoCreateTables": true,
    "DataRetentionDays": 90
  }
}
```

## Documentation

- **config/production_config.json**: Production configuration based on actual requirements
- **config/Oracle使用指南.md**: Oracle 11g setup and usage guide
- **docu/需求.txt**: Original requirements and protocol specification
- **docu/MES地址.xlsx**: Address mapping reference
- **ConfigDemo.cs**: Complete usage examples and demonstrations