docs/MIGRATION_GUIDE.md

🔄 MIGRATION GUIDE - AgriSensa API v1.0 → v2.0

✅ BACKWARD COMPATIBILITY RESTORED!

📋 Ringkasan Perubahan

AgriSensa API v2.0 sekarang FULLY BACKWARD COMPATIBLE dengan frontend lama (v1.0). Semua endpoint lama masih berfungsi dengan URL yang sama.

---

🔗 ENDPOINT MAPPING

✅ Legacy Endpoints (Tanpa Prefix - WORKING!)

Semua endpoint ini masih berfungsi seperti di v1.0:

Endpoint	Method	Deskripsi	Status
/	GET	Dashboard utama	✅ Working
/analyze	POST	Analisis daun (BWD)	✅ Working
/recommendation	POST	Rekomendasi pupuk	✅ Working
/analyze-npk	POST	Analisis NPK	✅ Working
/get-prices	POST	Harga komoditas	✅ Working
/get-knowledge	POST	Knowledge base	✅ Working
/calculate-fertilizer	POST	Kalkulator pupuk	✅ Working
/upload-pdf	POST	Upload dokumen	✅ Working
/get-pdfs	GET	List dokumen	✅ Working
/view-pdf/<filename>	GET	View dokumen	✅ Working
/get-integrated-recommendation	POST	Rekomendasi terintegrasi	✅ Working
/get-spraying-recommendation	POST	Strategi penyemprotan	✅ Working
/get-ticker-prices	GET	Ticker harga	✅ Working
/get-historical-prices	POST	Harga historis	✅ Working
/get-commodity-guide	POST	Panduan komoditas	✅ Working
/get-ph-info	GET	Informasi pH	✅ Working
/recommend-crop	POST	Rekomendasi tanaman	✅ Working
/predict-yield	POST	Prediksi panen	✅ Working
/predict-yield-advanced	POST	Prediksi XAI	✅ Working
/calculate-fertilizer-bags	POST	Hitung karung pupuk	✅ Working
/get-diagnostic-tree	GET	Diagnostic tree	✅ Working
/generate-yield-plan	POST	Rencana panen	✅ Working

🆕 New API Endpoints (Dengan Prefix /api/)

Endpoint baru dengan struktur yang lebih terorganisir:

Authentication (/api/auth)

• POST /api/auth/register - Register user baru
• POST /api/auth/login - Login user
• POST /api/auth/refresh - Refresh token
• GET /api/auth/me - Get profile (Auth required)
• PUT /api/auth/me - Update profile (Auth required)
• PUT /api/auth/change-password - Ganti password (Auth required)

Analysis (/api/analysis)

• POST /api/analysis/bwd - Analisis daun
• POST /api/analysis/npk - Analisis NPK
• GET /api/analysis/npk/history - History NPK (Auth required)

Recommendations (/api/recommendation)

• POST /api/recommendation/fertilizer - Rekomendasi pupuk
• POST /api/recommendation/calculate-fertilizer - Kalkulator pupuk
• POST /api/recommendation/integrated - Rekomendasi terintegrasi
• POST /api/recommendation/spraying - Strategi penyemprotan
• GET /api/recommendation/history - History (Auth required)

Knowledge Base (/api/knowledge)

• GET /api/knowledge/crop/<commodity> - Knowledge tanaman
• GET /api/knowledge/guide/<commodity> - Panduan budidaya
• GET /api/knowledge/ph-info - Informasi pH
• GET /api/knowledge/diagnostic-tree - Diagnostic tree
• GET /api/knowledge/fertilizer-data - Data pupuk

Market Data (/api/market)

• POST /api/market/prices - Harga saat ini
• GET /api/market/ticker - Ticker harga
• POST /api/market/historical - Harga historis

ML Predictions (/api/ml)

• POST /api/ml/recommend-crop - Rekomendasi tanaman
• POST /api/ml/predict-yield - Prediksi panen
• POST /api/ml/predict-yield-advanced - Prediksi XAI
• POST /api/ml/generate-yield-plan - Rencana panen
• POST /api/ml/calculate-fertilizer-bags - Hitung karung

---

🔧 IMPLEMENTASI TEKNIS

Struktur File Baru

app/
├── routes/
│   ├── legacy.py          # ✨ NEW! Backward compatibility layer
│   ├── main.py            # Dashboard & health check
│   ├── auth.py            # Authentication endpoints
│   ├── analysis.py        # Analysis endpoints
│   ├── recommendation.py  # Recommendation endpoints
│   ├── knowledge.py       # Knowledge base endpoints
│   ├── market.py          # Market data endpoints
│   └── ml.py              # ML prediction endpoints

Legacy Routes Implementation

File app/routes/legacy.py berisi semua endpoint lama yang memanggil service layer baru:

# Contoh: Legacy endpoint memanggil service baru
@legacy_bp.route('/analyze', methods=['POST'])
def analyze_bwd_endpoint():
    # Menggunakan AnalysisService yang baru
    result = analysis_service.analyze_leaf_image(file.read())
    return jsonify({'success': True, **result})

Blueprint Registration

Di app/__init__.py:

def register_blueprints(app):
    app.register_blueprint(main_bp)
    app.register_blueprint(legacy_bp)  # No prefix!
    app.register_blueprint(analysis_bp, url_prefix='/api/analysis')
    # ... other blueprints with /api/ prefix

---

🎯 CARA MIGRASI FRONTEND (Opsional)

Opsi 1: Tetap Gunakan Endpoint Lama (Recommended untuk saat ini)

Tidak perlu ubah apa-apa! Frontend lama akan tetap berfungsi.

// Frontend lama - masih berfungsi!
fetch('/analyze', {
    method: 'POST',
    body: formData
})

Opsi 2: Migrasi Bertahap ke Endpoint Baru

Untuk fitur baru, gunakan endpoint dengan prefix /api/:

// Frontend baru - dengan authentication
fetch('/api/analysis/bwd', {
    method: 'POST',
    headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify(data)
})

---

🔐 FITUR BARU DI V2.0

1. Authentication & Authorization

• JWT-based authentication
• Role-based access control (admin, user)
• Secure password hashing

2. Rate Limiting

• 100 requests per hour per IP
• Mencegah abuse

3. CORS Support

• Cross-origin requests enabled
• Configurable origins

4. Better Error Handling

• Structured error responses
• Proper HTTP status codes
• Detailed error messages

5. Logging & Monitoring

• Structured logging
• Log rotation
• Ready for Sentry integration

6. Database Enhancements

• 4 models dengan relasi
• Migration support (Alembic)
• Better data tracking

---

📊 PERBANDINGAN RESPONSE FORMAT

Legacy Format (Tetap Sama)

{
    "success": true,
    "bwd_score": 85,
    "avg_hue_value": 45.2,
    "confidence_percent": 92.5
}

New API Format (Sama, tapi dengan tambahan metadata)

{
    "success": true,
    "data": {
        "bwd_score": 85,
        "avg_hue": 45.2,
        "confidence": 92.5
    },
    "timestamp": "2025-10-28T13:36:00Z"
}

---

✅ TESTING CHECKLIST

Manual Testing

# Test legacy endpoint
curl -X POST http://localhost:5000/analyze \
  -F "file=@test_leaf.jpg"

# Test new API endpoint
curl -X POST http://localhost:5000/api/analysis/bwd \
  -H "Content-Type: multipart/form-data" \
  -F "file=@test_leaf.jpg"

Automated Testing (Coming Soon)

# Run tests
pytest tests/

# Run with coverage
pytest --cov=app tests/

---

🐛 TROUBLESHOOTING

Issue: Endpoint tidak ditemukan (404)

Solusi:

1. Pastikan aplikasi sudah restart
2. Cek apakah legacy_bp sudah diregister
3. Verifikasi URL endpoint

Issue: CORS error di browser

Solusi:

1. Update .env dengan CORS_ORIGINS yang benar
2. Restart aplikasi

Issue: Rate limit exceeded

Solusi:

1. Tunggu 1 jam
2. Atau disable rate limiting di development:

   # app/__init__.py
   limiter = Limiter(
       key_func=get_remote_address,
       default_limits=[]  # Disable
   )
   

---

📝 CHANGELOG

v2.0.0 (2025-10-28)

Added:

• ✅ Legacy routes untuk backward compatibility
• ✅ JWT authentication
• ✅ Rate limiting
• ✅ CORS support
• ✅ Structured logging
• ✅ 4 database models dengan relasi
• ✅ Migration support
• ✅ Comprehensive documentation

Changed:

• ✅ Refactored monolithic app.py ke modular structure
• ✅ Separated business logic ke service layer
• ✅ Improved error handling

Fixed:

• ✅ SQLAlchemy metadata reserved word conflict
• ✅ Database initialization issues

Deprecated:

• ⚠️ Direct database access (gunakan models)

Removed:

• ❌ None (full backward compatibility)

---

🎓 BEST PRACTICES

Untuk Developer Baru

1. Gunakan endpoint baru (/api/*) untuk fitur baru
2. Implementasi authentication untuk fitur yang sensitif
3. Handle errors dengan proper try-catch
4. Log semua actions untuk debugging
5. Write tests untuk setiap endpoint baru

Untuk Maintenance

1. Monitor logs di folder logs/
2. Backup database secara berkala
3. Update dependencies secara teratur
4. Review security setiap bulan

---

📞 SUPPORT

Jika ada masalah atau pertanyaan:

1. Check logs: logs/agrisensa.log
2. Read docs: README_NEW.md, SETUP_LOKAL.md
3. Check issues: GitHub Issues
4. Contact: admin@agrisensa.com

---

© 2025 AgriSensa - Smart Agriculture Platform