Northern-Thailand-Ping-River-Monitor/docs/STATION_MANAGEMENT_GUIDE.md

# 🏔️ Station Management Guide - Northern Thailand Ping River Monitor

## 🎯 **Overview**

The Northern Thailand Ping River Monitor now includes comprehensive station management capabilities, allowing you to dynamically add, update, and remove monitoring stations through the web API.

## 🌊 **Current Coverage**

The system currently monitors **16 water stations** along the Ping River Basin:

### **Upper Ping River (Chiang Mai Province)**
- **P.20** - Ban Chiang Dao (บ้านเชียงดาว)
- **P.75** - Ban Chai Lat (บ้านช่อแล)
- **P.92** - Ban Muang Aut (บ้านเมืองกึ๊ด)
- **P.4A** - Ban Mae Taeng (บ้านแม่แตง)
- **P.67** - Ban Tae (บ้านแม่แต)
- **P.21** - Ban Rim Tai (บ้านริมใต้)
- **P.103** - Ring Bridge 3 (สะพานวงแหวนรอบ 3)

### **Middle Ping River**
- **P.1** - Nawarat Bridge (สะพานนวรัฐ) - *Main reference station*
- **P.82** - Ban Sob win (บ้านสบวิน)
- **P.84** - Ban Panton (บ้านพันตน)
- **P.81** - Ban Pong (บ้านโป่ง)
- **P.5** - Tha Nang Bridge (สะพานท่านาง)

### **Lower Ping River**
- **P.77** - Baan Sop Mae Sapuord (บ้านสบแม่สะป๊วด)
- **P.87** - Ban Pa Sang (บ้านป่าซาง)
- **P.76** - Banb Mae I Hai (บ้านแม่อีไฮ)
- **P.85** - Baan Lai Kaew (บ้านหล่ายแก้ว)

## 🔧 **Station Management API**

### **List All Stations**
```bash
GET /stations
```

**Response:**
```json
[
  {
    "station_id": 1,
    "station_code": "P.20",
    "thai_name": "บ้านเชียงดาว",
    "english_name": "Ban Chiang Dao",
    "latitude": 19.36731448032191,
    "longitude": 98.9688487015384,
    "geohash": null,
    "status": "active"
  }
]
```

### **Get Specific Station**
```bash
GET /stations/{station_id}
```

### **Add New Station**
```bash
POST /stations
Content-Type: application/json

{
  "station_code": "P.NEW",
  "thai_name": "สถานีใหม่",
  "english_name": "New Station",
  "latitude": 18.7875,
  "longitude": 99.0045,
  "geohash": "w5q6uuhvfcfp25",
  "status": "active"
}
```

### **Update Station Information**
```bash
PUT /stations/{station_id}
Content-Type: application/json

{
  "thai_name": "ชื่อใหม่",
  "english_name": "Updated Name",
  "latitude": 18.8000,
  "longitude": 99.0100
}
```

### **Delete Station**
```bash
DELETE /stations/{station_id}
```

## 🧪 **Testing Station Management**

Use the provided test script to verify station management functionality:

```bash
# Test all station management endpoints
python test_station_management.py
```

This will:
1. List existing stations
2. Create a test station
3. Retrieve station details
4. Update station information
5. Verify changes
6. Delete the test station
7. Confirm deletion

## 📊 **Station Data Model**

### **Required Fields**
- `station_code`: Unique identifier (e.g., "P.1", "P.20")
- `thai_name`: Thai language name
- `english_name`: English language name

### **Optional Fields**
- `latitude`: GPS latitude coordinate (-90 to 90)
- `longitude`: GPS longitude coordinate (-180 to 180)
- `geohash`: Geohash string for location
- `status`: Station status ("active", "inactive", "maintenance", "error")

### **Validation Rules**
- Station codes must be unique
- Latitude must be between -90 and 90
- Longitude must be between -180 and 180
- Names cannot be empty
- Status must be valid enum value

## 🌐 **Web Interface**

Access the station management interface through the web dashboard:

1. **Start the API server:**
   ```bash
   python run.py --web-api
   ```

2. **Open your browser:**
   - Dashboard: http://localhost:8000
   - API Documentation: http://localhost:8000/docs

3. **Use the interactive API docs** to test station management endpoints

## 🔄 **Integration with Data Collection**

- **Dynamic Station Discovery**: New stations are automatically included in data collection
- **Real-time Updates**: Station information changes are reflected immediately
- **Data Continuity**: Historical data is preserved when updating station details
- **Error Handling**: Invalid stations are skipped during data collection

## 📍 **Geographic Coverage**

The Ping River Basin monitoring network covers:

- **Total Distance**: ~400 km from Chiang Dao to Nakhon Sawan
- **Elevation Range**: 300m to 1,200m above sea level
- **Catchment Area**: ~25,000 km²
- **Major Cities**: Chiang Mai, Lamphun, Tak, Nakhon Sawan

## 🚀 **Usage Examples**

### **Add a New Upstream Station**
```bash
curl -X POST "http://localhost:8000/stations" \
  -H "Content-Type: application/json" \
  -d '{
    "station_code": "P.UPSTREAM",
    "thai_name": "สถานีต้นน้ำ",
    "english_name": "Upstream Station",
    "latitude": 19.5000,
    "longitude": 98.9000,
    "status": "active"
  }'
```

### **Update Station Coordinates**
```bash
curl -X PUT "http://localhost:8000/stations/1" \
  -H "Content-Type: application/json" \
  -d '{
    "latitude": 19.3700,
    "longitude": 98.9700
  }'
```

### **Mark Station for Maintenance**
```bash
curl -X PUT "http://localhost:8000/stations/5" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "maintenance"
  }'
```

## 🔒 **Best Practices**

### **Station Naming**
- Use consistent code format (P.XX)
- Include both Thai and English names
- Use descriptive location names

### **Coordinate Accuracy**
- Use high-precision GPS coordinates (6+ decimal places)
- Verify coordinates match actual station location
- Include geohash for efficient spatial queries

### **Status Management**
- Set status to "maintenance" during repairs
- Use "inactive" for temporarily offline stations
- Use "error" for stations with data quality issues

### **Data Integrity**
- Test new stations before adding to production
- Backup station configuration before major changes
- Monitor data quality after station updates

## 🎯 **Future Enhancements**

Planned improvements for station management:

1. **Bulk Operations** - Import/export multiple stations
2. **Station Groups** - Organize stations by river section
3. **Automated Validation** - GPS coordinate verification
4. **Historical Tracking** - Track station configuration changes
5. **Alert Integration** - Notifications for station status changes
6. **Map Interface** - Visual station management on interactive map

## 📞 **Support**

For station management issues:

1. Check the API documentation at `/docs`
2. Run the test script: `python test_station_management.py`
3. Review logs for error details
4. Verify station data format and validation rules

The station management system provides flexible control over your monitoring network while maintaining data integrity and system reliability.