Kapasite planlama API tasarlarken asıl zorluk, yalnızca uç noktaları tanımlamak değil; planlama mantığının beslendiği veri sözleşmesini, zaman modelini ve entegrasyon sınırlarını tutarlı kılmaktır. RESTful yaklaşım, kaynak odaklı bir dil kurmanıza yardımcı olur; ancak üretim planlama alanında kaynakların ömrü, ilişkileri ve değişim hızları klasik CRUD kalıplarını zorlar. Bu rehber, teknik literatürde yer alan REST ilkelerini üretim yönetimi prensipleriyle birleştirerek; kapasite, takvim, vardiya, iş merkezi, rota ve kısıt verisinin API yüzeyinde nasıl temsil edileceğini ele alır. Hedef, istemci ekiplerin öngörülebilir sözleşmelerle çalışması, veri tutarlılığı tartışmalarının azalması ve kapasite planlama hesaplarının denetlenebilir hale gelmesidir.
Kapasite planlama alan modeli ve kaynak tasarımı
Kapasite planlama, kaynakların (iş merkezleri, hatlar, ekipman, operatör havuzları) belirli zaman dilimlerinde sunabildiği üretim yeteneğini, talep ve kısıtlarla birlikte ele alır. RESTful bir kapasite planlama API için ilk adım, planlama hesaplarının dayandığı çekirdek kaynakları ayrıştırmaktır. Kaynak sınırlarını doğru çizmek, hem sürümleme yükünü hem de veri çoğaltmayı azaltır.
Çekirdek kaynak kümeleri
- Varlık kaynakları: work-centers, resources, products, routings, operations gibi nispeten yavaş değişen tanımlar.
- Zaman kaynakları: calendars, shifts, exceptions, maintenance-windows gibi zaman kısıtını belirleyen tanımlar.
- Durum kaynakları: wip, orders, allocations, constraints gibi planlama sırasında sık güncellenen, yaşam döngüsü belirgin veriler.
- Türetilmiş kaynaklar: capacity-slots, available-capacity, load-profiles gibi hesap sonucu ortaya çıkan ve önbellek/yeniden hesap stratejisi gerektiren görünümler.
Sektörde yaygın kabul gören yaklaşıma göre, türetilmiş verileri “kaynak” gibi sunarken, hangi girdilerle ve hangi hesap sürümüyle üretildiğini belirtmek gerekir. Bu nedenle, hesaplanmış yanıtların meta alanlarında hesap zamanı, veri anlık görüntüsü referansı ve kullanılan kısıt seti gibi izler yer almalıdır.
RESTful kapasite planlama API sözleşmesi: URI, metot, idempotensi
REST, uniform arayüz ve temsil (representation) ilkeleriyle çalışır. Kapasite planlama API sözleşmesinde bu ilkelere bağlı kalmak, istemci tarafında sürprizleri azaltır. Özellikle planlama işlemleri “komut” gibi algılanmaya yatkın olduğundan, kaynak temsiline geri dönmek önemlidir.
URI ve metot seçiminde teknik ölçütler
- GET yan etkisiz olmalıdır; kapasite hesaplaması tetikleniyorsa bile sunucu tarafında kalıcı durum üretmemesi tercih edilir.
- POST yeni bir kaynak üretir: örneğin bir planlama çalıştırması “plan-runs” kaynağı olarak modellenebilir.
- PUT idempotent güncelleme içindir; vardiya tanımı veya takvim kuralı gibi belirli bir kimliğe sahip kaynaklarda öngörülebilirlik sağlar.
- PATCH kısmi güncellemelerde kullanılabilir; ancak eşzamanlılık kontrolü (ETag/If-Match) ile birlikte ele alınmalıdır.
İdempotensi, özellikle planlama tarafında tekrar eden isteklerin çift kayıt, çift rezervasyon veya tutarsız tahsis üretmesini engellemek için gereklidir. POST ile başlatılan planlama çalıştırmalarında idempotency-key benzeri bir istemci anahtarı kabul etmek, ağ tekrarlarında aynı “plan-run” kaynağına dönmeyi mümkün kılar.
Filtreleme, sıralama ve sayfalama
Kapasite planlama API uç noktalarında veri hacmi yönetimi bir sözleşme konusudur. Filtrelerde alan adlarının alan modeline birebir oturması, istemci sorgularının kalıcı hale gelmesini sağlar. Sayfalama için cursor tabanlı yaklaşım, zaman sıralı olaylarda tutarlılığı artırır. Sıralama (sort) ve alan seçimi (fields) desteği, gereksiz yükü azaltır; ancak bu özellikler için sabit bir isimlendirme standardı belirlemek gerekir.
Zaman, takvim ve vardiya verisinin API’de temsili
Kapasite planlama hesaplarının çoğu, zaman modelinin doğruluğuna bağlanır. Saat dilimi, yaz saati değişimi, vardiya kesişimleri, istisna günleri ve bakım pencereleri; kapasiteyi yalnızca miktar değil, zaman koordinatlarında da sınırlar. Bu nedenle kapasite planlama API tasarımında zaman temsilini açık bir sözleşme haline getirmek gerekir.
Zaman sözleşmesi: format, saat dilimi, sınırlar
- Tüm zaman damgalarında ISO 8601 kullanımı ve saat dilimi bilgisinin açık taşınması.
- Kaynak takvimlerinin “yerel” saat dilimi ile bağlı olduğu durumlarda, yanıt meta verisinde calendarTimeZone alanı.
- Zaman aralıklarının [start, end) gibi yarı açık aralık mantığıyla tanımlanması; çakışma testlerini sadeleştirir.
Vardiya tanımlarında “kural” ve “istisna” ayrımı faydalıdır. Kural katmanı (örneğin haftalık desen) nispeten stabil kalırken, istisnalar (tatil, planlı bakım, beklenmeyen kapanış) ayrı bir kaynak olarak yönetilir. Böylece istemciler, kapasite hesaplarında hangi istisna setinin uygulandığını izleyebilir.
Takvim kaynaklarının referans bütünlüğü
İş merkezinin takvim bağlamı, kapasite planlama API içinde açık bir ilişki olmalıdır: work-center → calendar → shifts → exceptions. Bu ilişki zinciri, hesaplanan “capacity-slots” temsillerinde kaynak referanslarıyla geri taşınır. Denetlenebilirlik için, bir slotun hangi vardiya kuralından türediği, hangi istisna ile kırpıldığı ve hangi bakım penceresi nedeniyle devre dışı kaldığı takip edilebilir olmalıdır.
ISA-95 hizalama, entegrasyon sınırları ve veri tutarlılığı
Üretim yönetimi prensipleri çerçevesinde, kapasite planlama verisi farklı katmanlardan beslenir: ürün ağaçları ve operasyon tanımları, iş emri durumları, WIP hareketleri, duruş kayıtları, planlı bakım planları. ISA-95, işlevsel ayrımı ve bilgi akışını tanımlamak için referans bir çerçeve sunar. Kapasite planlama API tasarımında bu çerçeve, “hangi veri nereden gelir ve kim otoritedir” sorusuna yanıt üretir.
Otorite (system of record) prensibi
- Rota ve operasyon tanımlarında tek bir otorite belirlenir; API bu tanımları ya yönetir ya da salt okunur sunar.
- İş emri yaşam döngüsünde durum geçişleri bir süreç sözleşmesiyle tanımlanır; kapasite tahsisi bu geçişlerle uyumlu olmalıdır.
- WIP ve duruş gibi yüksek frekanslı verilerde gecikme toleransı ve tutarlılık modeli (eventual/strong) açıkça belirtilir.
Entegrasyon katmanında, olay temelli akışlarla API sözleşmesinin ayrışması önemlidir. Kapasite planlama API, olayların ham akışını değil; planlama kararına etkisi olan normalize edilmiş durumları sunmayı hedeflemelidir. Böylece istemci planlama algoritmaları, kaynaklar arasında farklı yorumlara düşmeden aynı veri dilini kullanır.
Güvenlik, yetkilendirme ve denetlenebilirlik
Kapasite planlama API, üretim planları ve kaynak kullanımı gibi hassas bilgiler barındırır. Teknik literatürde önerilen yaklaşım; kimlik doğrulama, yetkilendirme, veri maskeleme ve iz kayıtlarının birlikte ele alınmasıdır. Güvenlik tasarımı, uç nokta bazında “kim neyi hangi kapsamda görür ve değiştirir” şeklinde somut bir sözleşmeye dönüştürülmelidir.
Yetkilendirme modeli
- Kapsam (scope) temelli erişim: read:capacity, write:calendar, run:planning gibi ayrımlar.
- Kaynak bazlı politika: belirli work-center grupları veya tesis seviyesinde erişim sınırları.
- Değişiklik denetimi: takvim ve vardiya güncellemelerinde değişiklik gerekçesi ve onay akışı ihtiyacına uygun alanlar.
Denetlenebilirlik için, değişikliklerin izlenmesi yalnızca “kim değiştirdi” kaydı değildir. Kapasite planlama API içinde, planlama çalıştırmalarının girdileri (kısıt seti, takvim sürümü, rota sürümü), çıktıları ve hata durumları aynı dilde kayıt altına alınmalıdır. Bu yaklaşım, planlama sonuçlarına ilişkin teknik incelemeleri veri seviyesinde mümkün kılar.
Hata modeli, gözlemlenebilirlik ve performans sınırları
RESTful API’lerde hata sözleşmesi, istemci geliştiriciler için en az kaynak sözleşmesi kadar belirleyicidir. Kapasite planlama API, doğrulama hataları (şema), iş kuralı ihlalleri (kısıt), çakışmalar (eşzamanlı güncelleme) ve dış bağımlılık sorunlarını (entegrasyon) birbirinden ayırmalıdır. Bu ayrım, geri deneme stratejilerini ve kullanıcıya gösterilecek teknik mesajları netleştirir.
| Durum | Anlam | İstemci davranışı |
|---|---|---|
| 400 | Şema/format hatası | İstek verisini düzelt |
| 409 | Sürüm çakışması veya kural ihlali | Kaynağı yeniden oku, çatışmayı çöz |
| 422 | Alan kısıtlarıyla uyumsuz içerik | İş kuralı mesajlarını işle |
| 429 | Oran sınırı aşıldı | Geri çekil, yeniden dene |
| 503 | Geçici servis erişilemezliği | Politikaya göre yeniden dene |
Gözlemlenebilirlik: metrik, iz ve korelasyon
- Her istekte korelasyon kimliği; dağıtık izleme ile ilişkilendirme.
- Planlama çalıştırmalarında aşama süreleri: veri toplama, kısıt çözme, sonuç yazma gibi etapların ayrı ölçümü.
- Yanıtlarda cache ve hesap meta verisi; aynı sorgunun aynı anlık görüntüyle üretildiğini doğrulama imkanı.
Performans tarafında “hangi uç nokta hangi yük profiline göre tasarlanır” sorusu açık kalmamalıdır. Özellikle hesaplanan kapasite görünümleri için asenkron çalışma (plan-runs) ve sonuçların sayfalı okunması, büyük veri setlerinde zaman aşımı riskini azaltır. Kapasite planlama API sözleşmesi, zaman aralığı sorgularında üst sınırlar, maksimum sonuç boyutu ve sunucu tarafı zaman aşımı davranışı gibi parametreleri dokümante etmelidir.
Kapasite planlama API tasarımında başarı ölçütü, uç noktaların sayısı değil; kaynak modelinin tutarlılığı, zaman sözleşmesinin açıklığı, güvenlik politikasının uygulanabilirliği ve hata dilinin öngörülebilirliğidir. RESTful ilkeleri, üretim planlama alanının kendine özgü zaman ve kısıt yapısıyla birlikte ele aldığınızda, entegrasyon maliyeti düşer ve planlama hesaplarının denetlenebilirliği artar. Kapasite planlama API sözleşmenizi ISA-95 hizalaması, takvim-vardiya modeli ve gözlemlenebilirlik gereksinimleriyle birlikte değerlendirmek isterseniz MESPlus ile iletişime geçerek teknik bir çerçeve üzerinden ilerleyebilirsiniz.
