{
  "name": "TarlaKapasite",
  "version": "1.0.0",
  "language": "tr",
  "description": "Tam işletme/çalışma genişliği, ilerleme hızı, EFC / TFC × 100 olarak verilen tarla etkinliği ve alan üzerinden teorik/efektif saha kapasitesi ile iş süresini hesaplayan kanonik sözleşme.",
  "canonical_area_unit": "ha",
  "input_contract": {
    "additional_properties": "ignored",
    "fields": {
      "working_width_m": {
        "type": "number",
        "unit": "m",
        "required": true,
        "range": {
          "exclusive_minimum": 0
        },
        "finite": true,
        "definition": "TFC hesabında kullanılan makinenin tam işletme/çalışma genişliği.",
        "basis": "Iowa A3-24, PDF s.4, Eq. (1): TFC makinenin tam işletme genişliği (full operating width) ve ortalama tarla hızıyla hesaplanır.",
        "note": "Ölçülen tam genişlik katalog değerinden farklıysa ölçülen tam genişlik kullanılabilir; örtüşme sonrası net şerit genişliği girilmez.",
        "double_count_warning": "FE örtüşmeyi zaten içeriyorsa genişlikten örtüşmeyi ayrıca düşmeyin.",
        "source_ids": [
          "iowa_state_field_capacity"
        ]
      },
      "speed_kmh": {
        "type": "number",
        "unit": "km/h",
        "required": true,
        "range": {
          "exclusive_minimum": 0
        },
        "finite": true,
        "basis": "Görev girdi sözleşmesi"
      },
      "field_efficiency_percent": {
        "type": "number",
        "unit": "%",
        "required": true,
        "range": {
          "exclusive_minimum": 0,
          "maximum": 100
        },
        "finite": true,
        "definition": "EFC / TFC × 100 olarak tanımlanan tarla etkinliği yüzdesi.",
        "basis": "Iowa A3-24, PDF s.4, Eq. (3): FE (%) = EFC / TFC × 100.",
        "includes": [
          "Tam işletme genişliğinin kullanılamaması ve örtüşme",
          "Dönüş",
          "Doldurma",
          "Boşaltma",
          "Tıkanma kontrolü",
          "Diğer tarla içi gecikmeler"
        ],
        "excludes": [
          "Tarla dışı günlük servis",
          "Tarlaya gidiş-geliş",
          "Büyük onarım"
        ],
        "note": "Bu değer kullanıcının ölçümü veya açık plan varsayımıdır; motor varsayılan etkinlik kullanmaz.",
        "double_count_warning": "FE örtüşmeyi zaten içeriyorsa genişlikten örtüşmeyi ayrıca düşmeyin.",
        "source_ids": [
          "iowa_state_field_capacity",
          "clemson_field_capacity"
        ]
      },
      "area_ha": {
        "type": "number",
        "unit": "ha",
        "required": true,
        "range": {
          "minimum": 0
        },
        "finite": true,
        "basis": "Görev girdi sözleşmesi",
        "note": "Alan 0 olduğunda iş süresi 0'dır."
      },
      "shift_hours": {
        "type": "number",
        "unit": "h/shift",
        "required": false,
        "range": {
          "exclusive_minimum": 0
        },
        "finite": true,
        "basis": "Görev girdi sözleşmesi",
        "note": "Verilmezse shift_count_exact ve shift_count_ceil null döner."
      }
    }
  },
  "ui_localized_number_parsing": {
    "machine_api_type": "number",
    "machine_api_accepts_strings": false,
    "accepted_ui_decimal_separators": [
      ",",
      "."
    ],
    "boundary": "Virgül veya nokta içeren form metni yalnız UI katmanında ayrıştırılır. UI, ayrıştırdığı sonlu number değerini window.TarlaKapasite.calculate(input) motoruna geçirir.",
    "rule": "Başı ve sonu kırpılmış, tek ondalık ayraçlı basit form metni kabul edilir. Virgül ondalık noktasına çevrilir. Binlik ayraç, aynı metinde iki ayraç türü, tekrar eden ayraç, boş metin ve üs gösterimli metin kabul edilmez.",
    "examples": {
      "ui_text_accepted": [
        "6",
        "6,5",
        "6.5",
        ".5",
        ",5"
      ],
      "ui_text_rejected": [
        "",
        "1.234,5",
        "1,234.5",
        "1e3"
      ],
      "machine_api_rejected": [
        "6",
        "6,5",
        "6.5"
      ]
    }
  },
  "area_conversion": {
    "canonical_input": "area_ha",
    "ui_optional_input_unit": "da",
    "identity": "1 ha = 10 da",
    "da_to_ha": {
      "expression": "area_da / 10",
      "result_unit": "ha"
    },
    "ha_to_da": {
      "expression": "area_ha * 10",
      "result_unit": "da"
    },
    "note": "Makine çağrısı alanı kanonik olarak area_ha ile alır; dekar seçen arayüz değeri hesaplamadan önce hektara dönüştürür.",
    "source_ids": [
      "meb_area_relations",
      "bipm_si_brochure"
    ]
  },
  "output_contract": {
    "envelope": {
      "success": {
        "ok": true,
        "value": "calculation-result",
        "error": null
      },
      "failure": {
        "ok": false,
        "value": null,
        "error": {
          "code": "error-code",
          "field": "field-name-or-null",
          "message": "human-readable-message"
        }
      }
    },
    "fields": {
      "theoretical_capacity_ha_h": {
        "type": "number",
        "unit": "ha/h",
        "nullable": false
      },
      "effective_capacity_ha_h": {
        "type": "number",
        "unit": "ha/h",
        "nullable": false
      },
      "work_time_h": {
        "type": "number",
        "unit": "h",
        "nullable": false
      },
      "work_time_min": {
        "type": "number",
        "unit": "min",
        "nullable": false
      },
      "shift_count_exact": {
        "type": "number",
        "unit": "shift",
        "nullable": true,
        "null_when": "shift_hours is omitted"
      },
      "shift_count_ceil": {
        "type": "integer",
        "unit": "shift",
        "nullable": true,
        "null_when": "shift_hours is omitted"
      }
    }
  },
  "formulas": {
    "theoretical_capacity_ha_h": {
      "expression": "working_width_m * speed_kmh / 10",
      "unit": "ha/h",
      "conversion_trace": [
        "working_width_m * speed_kmh = w m * v km/h",
        "1 km = 1000 m olduğundan v km/h = v * 1000 m/h",
        "w m * v * 1000 m/h = w * v * 1000 m²/h",
        "1 ha = 10000 m² olduğundan w * v * 1000 m²/h = w * v * (1000/10000) ha/h",
        "1000/10000 = 0,1 = 1/10; sonuç w * v / 10 ha/h"
      ],
      "source_ids": [
        "iowa_state_field_capacity",
        "clemson_field_capacity",
        "bipm_si_brochure"
      ]
    },
    "effective_capacity_ha_h": {
      "expression": "theoretical_capacity_ha_h * field_efficiency_percent / 100",
      "unit": "ha/h",
      "definition": "field_efficiency_percent = EFC / TFC * 100",
      "note": "Yüzde girdisi kesre çevrilmek üzere 100'e bölünür. FE tam genişliğin kullanılamamasını/örtüşmeyi ve tarla içi gecikmeleri kapsar; tarla dışı günlük servis, tarlaya gidiş-geliş ve büyük onarımı kapsamaz.",
      "double_count_warning": "FE örtüşmeyi zaten içeriyorsa genişlikten örtüşmeyi ayrıca düşmeyin.",
      "source_ids": [
        "iowa_state_field_capacity",
        "clemson_field_capacity"
      ]
    },
    "work_time_h": {
      "expression": "area_ha / effective_capacity_ha_h",
      "unit": "h",
      "zero_area_rule": "area_ha === 0 ise sonuç 0",
      "basis": "Görev çıktı ve formül sözleşmesi"
    },
    "work_time_min": {
      "expression": "work_time_h * 60",
      "unit": "min",
      "basis": "60 min = 1 h",
      "source_ids": [
        "bipm_si_brochure"
      ]
    },
    "shift_count_exact": {
      "expression": "work_time_h / shift_hours",
      "unit": "shift",
      "condition": "shift_hours is provided",
      "basis": "Görev çıktı ve formül sözleşmesi"
    },
    "shift_count_ceil": {
      "expression": "ceil(shift_count_exact)",
      "unit": "shift",
      "condition": "shift_hours is provided",
      "basis": "Görev çıktı ve formül sözleşmesi"
    }
  },
  "example": {
    "request": {
      "working_width_m": 6,
      "speed_kmh": 8,
      "field_efficiency_percent": 75,
      "area_ha": 36,
      "shift_hours": 8
    },
    "response": {
      "ok": true,
      "value": {
        "theoretical_capacity_ha_h": 4.8,
        "effective_capacity_ha_h": 3.6,
        "work_time_h": 10,
        "work_time_min": 600,
        "shift_count_exact": 1.25,
        "shift_count_ceil": 2
      },
      "error": null
    }
  },
  "double_count_regression": {
    "recommended": {
      "meaning": "Kaynak tanımlı FE örtüşmeyi zaten içerirken tam işletme/çalışma genişliğini kullanma",
      "request": {
        "working_width_m": 6,
        "speed_kmh": 8,
        "field_efficiency_percent": 75,
        "area_ha": 36
      },
      "expected": {
        "effective_capacity_ha_h": 3.6,
        "work_time_h": 10
      }
    },
    "not_recommended": {
      "meaning": "Aynı FE ile yüzde 10 örtüşmeyi genişlikten ayrıca düşerek çift sayma",
      "request": {
        "working_width_m": 5.4,
        "speed_kmh": 8,
        "field_efficiency_percent": 75,
        "area_ha": 36
      },
      "expected": {
        "effective_capacity_ha_h": 3.24,
        "work_time_h": 11.11111111111111
      }
    },
    "warning": "FE örtüşmeyi zaten içeriyorsa genişlikten örtüşmeyi ayrıca düşmeyin."
  },
  "null_example_without_shift": {
    "request": {
      "working_width_m": 1,
      "speed_kmh": 10,
      "field_efficiency_percent": 100,
      "area_ha": 1
    },
    "response": {
      "ok": true,
      "value": {
        "theoretical_capacity_ha_h": 1,
        "effective_capacity_ha_h": 1,
        "work_time_h": 1,
        "work_time_min": 60,
        "shift_count_exact": null,
        "shift_count_ceil": null
      },
      "error": null
    }
  },
  "error_codes": {
    "INVALID_INPUT": {
      "field": null,
      "when": "input null ise, dizi ise veya bir nesne değilse"
    },
    "INVALID_WORKING_WIDTH": {
      "field": "working_width_m",
      "when": "değer eksik, number tipinde değil, sonlu değil veya <= 0 ise"
    },
    "INVALID_SPEED": {
      "field": "speed_kmh",
      "when": "değer eksik, number tipinde değil, sonlu değil veya <= 0 ise"
    },
    "INVALID_FIELD_EFFICIENCY": {
      "field": "field_efficiency_percent",
      "when": "değer eksik, number tipinde değil, sonlu değil, <= 0 veya > 100 ise",
      "note": "Etkinlik 0 reddedilir; sonsuz süre üretilmez."
    },
    "INVALID_AREA": {
      "field": "area_ha",
      "when": "değer eksik, number tipinde değil, sonlu değil veya < 0 ise"
    },
    "INVALID_SHIFT_HOURS": {
      "field": "shift_hours",
      "when": "alan mevcutken değer number tipinde değil, sonlu değil veya <= 0 ise"
    },
    "CALCULATION_OUT_OF_RANGE": {
      "field": null,
      "when": "geçerli girdilerle yapılan bir ara veya nihai hesap JavaScript Number aralığında sonlu ve kullanılabilir sonuç üretmezse",
      "note": "Başarılı yanıtta Infinity veya NaN bulunmaz."
    }
  },
  "precision": {
    "engine_number_format": "IEEE-754 binary64 JavaScript Number",
    "intermediate_rounding": false,
    "machine_result_rounding": false,
    "presentation_rounding": "Yalnız kullanıcı arayüzü gösteriminde uygulanabilir; makine sonucunu değiştirmez.",
    "json_safety": "Başarılı sayısal sonuçların tamamı sonludur; NaN ve Infinity döndürülmez."
  },
  "sources": {
    "iowa_state_field_capacity": {
      "title": "Estimating the Field Capacity of Farm Machines",
      "publisher": "Iowa State University Extension and Outreach",
      "url": "https://www.extension.iastate.edu/agdm/crops/pdf/a3-24.pdf",
      "relevant_location": "PDF s.1 ve s.4, Eq. (1), Eq. (3) ve Eq. (4)",
      "relevant_relation": "Saha kapasitesinin planlama kullanımları; TFC tam işletme genişliğiyle hesaplanır; imperial birimlerde TFC = width * speed / 8.25, FE (%) = EFC / TFC * 100 ve EFC = TFC * field_efficiency_percent / 100. FE tam genişliğin kullanılamamasını/örtüşmeyi ve tarla içi gecikmeleri içerir; tarla dışı günlük servis, tarlaya gidiş-geliş ve büyük onarımı içermez.",
      "audit_note": "Güncel PDF'nin s.3 ve s.5 metin katmanında DRAFT ibaresi vardır; kullanılan formüller PDF s.4'teki denklemlerden doğrulanmıştır.",
      "verified": true
    },
    "clemson_field_capacity": {
      "title": "Estimated Peanut Combine Field Capacities",
      "publisher": "Clemson University Cooperative Extension",
      "url": "https://precisionag.sites.clemson.edu/Extension_Guides/Peanut_Combine_Field_Capacity.pdf",
      "relevant_location": "Tek sayfalık PDF",
      "relevant_relation": "Imperial birimlerde TFC = speed * width / 8.25 ve EFC = TFC * FE; belgede kullanılan FE değerlerinin kullanıcının operasyonuyla uyuşmayabileceği uyarısı vardır.",
      "verified": true
    },
    "bipm_si_brochure": {
      "title": "The International System of Units (SI), 9th edition",
      "publisher": "Bureau International des Poids et Mesures",
      "url": "https://www.bipm.org/documents/20126/41483022/SI-Brochure-9-EN.pdf/2d2b50bf-f2b4-9661-f402-5f9d66e4b507?download=true&t=1780410776583&version=7.0",
      "relevant_location": "PDF s.28, s.30 ve s.36",
      "relevant_relation": "kilo = 10^3; 1 ha = 10^4 m²; 1 h = 60 min; percent = parts per hundred",
      "verified": true
    },
    "meb_area_relations": {
      "title": "Bağıntılar",
      "publisher": "T.C. Millî Eğitim Bakanlığı",
      "url": "https://megep.meb.gov.tr/mte_program_modul/moduller_pdf/Ba%C4%9F%C4%B1nt%C4%B1lar.pdf",
      "relevant_location": "PDF s.31",
      "relevant_relation": "1 daa = 1000 m² ve 1 ha = 10 daa = 10000 m²",
      "verified": true
    }
  }
}