roadmap/farm_model_documentation.md

# Farm Model Documentation

## Overview
Model Farm adalah entitas inti dalam sistem manajemen lahan pertanian yang menyimpan informasi detail tentang lahan/kebun yang dikelola oleh petani. Model ini berfungsi sebagai pusat data geografis, karakteristik fisik, infrastruktur, dan metadata lahan pertanian dalam ekosistem Happy Farmer.

## Business Context
Model Farm berfungsi sebagai:
- **Land Registry**: Registrasi dan dokumentasi lahan pertanian
- **Geographic Information System**: Penyimpanan data geografis dan pemetaan
- **Infrastructure Management**: Tracking fasilitas dan infrastruktur lahan
- **Production Planning**: Basis untuk perencanaan produksi dan budgeting
- **Asset Management**: Pengelolaan aset lahan sebagai investasi
- **Compliance Tracking**: Dokumentasi legal dan sertifikasi lahan

## Model Structure

### Primary Fields

#### **Identification & Basic Info**
- **`id`** (String, Primary Key): Unique identifier menggunakan CUID
- **`farmerId`** (String, Foreign Key): Referensi ke petani pemilik/pengelola
- **`farmCode`** (String, Unique): Kode unik farm untuk identifikasi
- **`name`** (String, Required): Nama farm/kebun
- **`address`** (String, Optional): Alamat lengkap farm
- **`village`** (String, Optional): Desa/kelurahan lokasi farm
- **`district`** (String, Optional): Kecamatan lokasi farm
- **`province`** (String, Optional): Provinsi lokasi farm
- **`postalCode`** (String, Optional): Kode pos area farm

#### **Geographic Data**
- **`area`** (Decimal, Optional): Luas lahan dalam hektar
- **`latitude`** (Float, Optional): Koordinat lintang
- **`longitude`** (Float, Optional): Koordinat bujur
- **`boundaries`** (JSON, Optional): Polygon boundaries dalam format GeoJSON
- **`elevation`** (Float, Optional): Ketinggian di atas permukaan laut (meter)

#### **Soil & Environmental Characteristics**
- **`soilType`** (String, Optional): Jenis tanah (lempung, pasir, dll)
- **`soilPH`** (Float, Optional): Tingkat keasaman tanah (pH)
- **`waterSource`** (WaterSource Enum, Optional): Sumber air utama
- **`irrigationType`** (IrrigationType Enum, Optional): Sistem irigasi yang digunakan
- **`slope`** (SlopeType Enum, Optional): Tingkat kemiringan lahan
- **`climate`** (ClimateType Enum, Optional): Jenis iklim daerah

#### **Infrastructure & Facilities**
- **`hasElectricity`** (Boolean, Default: false): Ketersediaan listrik
- **`hasWaterAccess`** (Boolean, Default: false): Akses air bersih
- **`hasStorageFacility`** (Boolean, Default: false): Fasilitas penyimpanan
- **`hasProcessingUnit`** (Boolean, Default: false): Unit pengolahan
- **`accessRoadType`** (RoadType Enum, Optional): Jenis akses jalan

#### **Visual Documentation**
- **`mainPhotoUrl`** (String, Optional): URL foto utama farm
- **`aerialPhotoUrl`** (String, Optional): URL foto udara/drone
- **`soilPhotoUrl`** (String, Optional): URL foto sampel tanah

#### **Legal & Ownership**
- **`ownershipType`** (FarmOwnership Enum, Optional): Status kepemilikan lahan
- **`landCertificateNumber`** (String, Optional): Nomor sertifikat tanah
- **`landCertificateUrl`** (String, Optional): URL dokumen sertifikat

#### **Agricultural Information**
- **`establishedYear`** (Integer, Optional): Tahun pendirian/mulai dikelola
- **`totalInvestment`** (Decimal, Optional): Total investasi pada farm
- **`annualProduction`** (Decimal, Optional): Estimasi produksi tahunan (kg)
- **`mainCrops`** (String Array): Komoditas utama yang ditanam
- **`farmingSystem`** (FarmingSystem Enum, Optional): Sistem pertanian yang digunakan
- **`organicCertified`** (Boolean, Default: false): Status sertifikasi organik

#### **Metadata**
- **`description`** (String, Optional): Deskripsi detail farm
- **`notes`** (String, Optional): Catatan tambahan
- **`isActive`** (Boolean, Default: true): Status aktif farm
- **`createdAt`** (DateTime, Default: now()): Tanggal pembuatan record
- **`updatedAt`** (DateTime, Auto-update): Tanggal terakhir diupdate

## Enums Definition

### WaterSource
- **RAIN_FED**: Mengandalkan air hujan
- **IRRIGATION_CANAL**: Saluran irigasi
- **WELL**: Sumur
- **RIVER**: Sungai
- **POND**: Kolam/embung
- **GROUNDWATER**: Air tanah
- **SPRING**: Mata air
- **MIXED**: Kombinasi sumber air

### IrrigationType
- **FLOOD**: Irigasi banjir
- **SPRINKLER**: Sistem sprinkler
- **DRIP**: Irigasi tetes
- **FURROW**: Alur/parit
- **MANUAL**: Manual/tradisional
- **NONE**: Tidak ada irigasi

### SlopeType
- **FLAT**: Datar
- **GENTLE**: Landai
- **MODERATE**: Sedang
- **STEEP**: Curam
- **VERY_STEEP**: Sangat curam

### ClimateType
- **TROPICAL_WET**: Tropis basah
- **TROPICAL_DRY**: Tropis kering
- **SUBTROPICAL**: Subtropis
- **TEMPERATE**: Sedang
- **HIGHLAND**: Dataran tinggi

### RoadType
- **PAVED**: Jalan beraspal
- **GRAVEL**: Jalan kerikil
- **DIRT**: Jalan tanah
- **FOOTPATH**: Jalan setapak
- **NO_ACCESS**: Tidak ada akses

### FarmOwnership
- **PRIVATE_OWNED**: Milik pribadi
- **LEASED**: Sewa
- **SHARECROPPED**: Bagi hasil
- **COOPERATIVE**: Koperasi
- **GOVERNMENT**: Pemerintah
- **COMMUNAL**: Komunal
- **FAMILY_INHERITED**: Warisan keluarga

### FarmingSystem
- **MONOCULTURE**: Monokultur
- **POLYCULTURE**: Polikultur
- **MIXED_FARMING**: Pertanian campuran
- **ORGANIC**: Organik
- **CONVENTIONAL**: Konvensional
- **INTEGRATED**: Terintegrasi
- **PERMACULTURE**: Permaculture
- **AGROFORESTRY**: Agroforestri

## Relationships

### One-to-One Relationships
- **Farmer**: Setiap farm dimiliki/dikelola oleh satu petani

### One-to-Many Relationships
- **Plot**: Satu farm dapat dibagi menjadi beberapa plot
- **Harvest**: Recording hasil panen dari farm
- **FarmAttachment**: Dokumentasi dan foto farm
- **WeatherData**: Data cuaca spesifik farm
- **WeatherForecast**: Prediksi cuaca untuk farm
- **FarmInput**: Input pertanian yang digunakan
- **InputSchedule**: Jadwal penggunaan input
- **LaborRecord**: Catatan tenaga kerja
- **LaborSchedule**: Jadwal kerja
- **EquipmentUsage**: Penggunaan alat dan mesin
- **PestDiseaseRecord**: Catatan hama dan penyakit
- **FinancialRecord**: Catatan keuangan farm
- **SoilTest**: Tes laboratorium tanah

## Database Indexes

### Primary Indexes
- **`farmCode`**: Pencarian berdasarkan kode farm
- **`farmerId`**: Relasi dengan petani
- **`isActive`**: Filter farm aktif
- **`establishedYear`**: Sorting berdasarkan tahun pendirian

### Geographic Indexes
- **`latitude, longitude`**: Spatial queries dan mapping
- **Spatial Index**: Untuk GeoJSON boundaries (database-specific)

## Business Rules

### Validation Rules
1. **Unique Constraints**:
   - `farmCode` harus unik dalam sistem
   - `farmerId + name` kombinasi yang unik per petani

2. **Required Fields**:
   - `farmerId`: Wajib ada (foreign key)
   - `name`: Wajib diisi untuk identifikasi

3. **Geographic Validation**:
   - Latitude: -90 to 90
   - Longitude: -180 to 180
   - Area: > 0 jika diisi
   - Boundaries: Valid GeoJSON polygon

4. **Business Logic**:
   - `establishedYear` tidak boleh di masa depan
   - `annualProduction` harus >= 0
   - `totalInvestment` harus >= 0

### Status Management
- Farm dapat di-deactivate tanpa menghapus data
- Deactivated farm tidak dapat memiliki aktivitas baru
- Historical data tetap tersimpan untuk analytics

## Use Cases

### 1. Farm Registration
**Actor**: Petani/Admin
**Flow**:
1. Input informasi dasar farm (nama, lokasi)
2. Upload atau input koordinat GPS
3. Input karakteristik tanah dan lingkungan
4. Dokumentasi dengan foto
5. Input informasi legal (sertifikat)
6. Aktivasi farm

### 2. Farm Mapping & GIS
**Actor**: Admin/Analyst
**Flow**:
1. View farm locations pada peta
2. Analyze geographic distribution
3. Overlay dengan data cuaca/iklim
4. Identify clusters dan patterns
5. Generate geographic reports

### 3. Infrastructure Assessment
**Actor**: Field Officer/Admin
**Flow**:
1. Survey infrastruktur existing
2. Update fasilitas yang tersedia
3. Identify infrastructure gaps
4. Plan improvement programs
5. Track infrastructure development

### 4. Production Planning
**Actor**: Petani/Advisor
**Flow**:
1. Analyze farm characteristics
2. Determine suitable crops
3. Plan planting schedule
4. Estimate production capacity
5. Budget planning dan resource allocation

### 5. Environmental Monitoring
**Actor**: Environmentalist/Researcher
**Flow**:
1. Track soil health parameters
2. Monitor water usage patterns
3. Assess climate impact
4. Analyze biodiversity
5. Generate sustainability reports

## Integration Points

### Internal Systems
- **Farmer Management**: Owner relationship
- **Plot Management**: Land subdivision
- **Weather System**: Location-based weather data
- **Financial System**: Investment dan revenue tracking
- **Equipment Management**: Usage pada farm specific
- **Harvest Management**: Production tracking

### External Systems
- **GIS Platforms**: Mapping dan spatial analysis
- **Weather Services**: Real-time weather data
- **Satellite Imagery**: Aerial monitoring
- **Government Systems**: Land certification integration
- **Insurance Systems**: Risk assessment
- **Bank Systems**: Collateral valuation

## Data Privacy & Security

### Sensitive Data
- Exact coordinates dan boundaries
- Legal documents (certificates)
- Financial information (investment, production)
- Infrastructure details

### Security Measures
- Role-based access untuk geographic data
- Encryption untuk sensitive coordinates
- Audit trails untuk data changes
- Backup dan disaster recovery

## Performance Considerations

### Query Optimization
- Spatial indexes untuk geographic queries
- Composite indexes untuk common filters
- Materialized views untuk analytics
- Caching untuk frequently accessed farms

### Scalability
- Geographic partitioning berdasarkan region
- Read replicas untuk mapping queries
- CDN untuk farm photos
- Efficient spatial data storage

## Analytics & Reporting

### Key Metrics
- **Total Farm Area**: Aggregate luas lahan
- **Geographic Distribution**: Sebaran lokasi farm
- **Infrastructure Penetration**: Tingkat infrastruktur
- **Production Capacity**: Kapasitas produksi total
- **Organic Certification Rate**: Persentase sertifikasi organik

### Reports
- **Farm Directory**: Katalog farm dengan details
- **Geographic Analysis**: Distribution dan clustering
- **Infrastructure Assessment**: Gap analysis
- **Production Summary**: Kapasitas dan actual production
- **Environmental Impact**: Sustainability metrics

## Quality Assurance

### Data Validation
- GPS coordinates validation
- GeoJSON polygon validation
- Realistic area calculations
- Consistent address hierarchy

### Regular Audits
- Farm visits untuk verification
- Photo updates berkala
- Infrastructure assessment
- Production capacity review

## Future Enhancements

### Planned Features
1. **Smart Mapping**:
   - AI-powered boundary detection
   - Satellite imagery integration
   - Real-time farm monitoring
   - Precision agriculture mapping

2. **IoT Integration**:
   - Sensor data collection
   - Automated irrigation systems
   - Weather station integration
   - Equipment tracking

3. **Sustainability Tracking**:
   - Carbon footprint calculation
   - Water usage monitoring
   - Biodiversity assessment
   - Soil health tracking

4. **Advanced Analytics**:
   - Predictive modeling
   - Yield optimization
   - Risk assessment
   - Market intelligence

### Integration Roadmap
- **Drone Integration**: Aerial surveying dan monitoring
- **Blockchain**: Land registry dan ownership verification
- **AI/ML**: Predictive analytics dan optimization
- **Mobile Apps**: Field data collection
- **Government APIs**: Legal compliance integration

## Sample Farm Profiles

### Small-Scale Rice Farm
```json
{
  "name": "Sawah Pak Budi",
  "area": 0.5,
  "soilType": "Clay loam",
  "waterSource": "IRRIGATION_CANAL",
  "irrigationType": "FLOOD",
  "mainCrops": ["Rice"],
  "farmingSystem": "CONVENTIONAL",
  "hasElectricity": false,
  "accessRoadType": "DIRT"
}
```

### Organic Vegetable Farm
```json
{
  "name": "Green Valley Organic",
  "area": 2.0,
  "soilType": "Sandy loam",
  "waterSource": "WELL",
  "irrigationType": "DRIP",
  "mainCrops": ["Tomato", "Lettuce", "Spinach"],
  "farmingSystem": "ORGANIC",
  "organicCertified": true,
  "hasElectricity": true,
  "hasStorageFacility": true
}
```

### Highland Coffee Plantation
```json
{
  "name": "Arabica Hills",
  "area": 5.0,
  "elevation": 1200,
  "climate": "HIGHLAND",
  "slope": "MODERATE",
  "mainCrops": ["Coffee"],
  "farmingSystem": "AGROFORESTRY",
  "establishedYear": 2010,
  "accessRoadType": "GRAVEL"
}
```

## Compliance & Certification

### Legal Requirements
- Land certificate validation
- Environmental compliance
- Water usage permits
- Organic certification (if applicable)

### Documentation Standards
- Standardized photo requirements
- GPS accuracy standards
- Boundary documentation
- Infrastructure documentation

### Audit Trail
- All changes logged dengan timestamp
- User attribution untuk modifications
- Historical versions maintained
- Compliance tracking automated