GraphQL মিউটেশন (লিখন)

Business প্ল্যান থেকে GraphQL এন্ডপয়েন্ট 12টি রাইট মিউটেশন সমর্থন করে: কাজের নির্দেশনা, অ্যাসেট ও পার্টসে তৈরি, হালনাগাদ ও মুছে ফেলা, সঙ্গে ইনভেন্টরি মুভমেন্টের জন্য adjustStock। মিউটেশনগুলো অ্যাপ্লিকেশন নিজে যে সার্ভিস ব্যবহার করে সেগুলোর মধ্য দিয়েই যায়, তাই অডিট লগ, নোটিফিকেশন ও রেফারেন্সের স্বয়ংক্রিয় নম্বরকরণ (WO-XX, ASS-XX, PART-XX) হুবহু একইভাবে কাজ করে। একাদশটি, addMeterReading, মিটার রিডিং (চালু থাকার ঘণ্টা, কাউন্টার) রেকর্ড করে — নিচে দেখুন। দ্বাদশটি, setPurchaseOrderErpReference, আপনার ERP-এর নথি নম্বর একটি ক্রয়াদেশে লিখে দেয় (শুধু FULL অ্যাক্সেসের কী দিয়ে) এবং কোনো webhook চালু করে না, তাই আপনার ERP কখনো নিজের লেখা ফেরত পায় না।

উপলব্ধ মিউটেশন

• createWorkOrder(input) → WorkOrder
• updateWorkOrder(id, input) → WorkOrder
• deleteWorkOrder(id) → DeleteResult
• createAsset(input) → Asset
• updateAsset(id, input) → Asset
• deleteAsset(id, force?) → DeleteResult
• createPart(input) → Part
• updatePart(id, input) → Part
• deletePart(id, force?) → DeleteResult
• adjustStock(id, quantity, reason?, vendorId?, documentNumber?) → Part
• addMeterReading(meterId, value?, incrementValue?, date?, notes?, confirmRegression?) → MeterReading
• setPurchaseOrderErpReference(id, erpReference?) → PurchaseOrder

ইনপুট আকৃতি

প্রতিটি মিউটেশনের একটি InputType থাকে, যাতে শুধু নিরাপদ ফিল্ড আছে — companyId, sequenceNumber, reference ও createdById সার্ভার-সাইডে পূরণ হয়। আপনি শুধু title, description, status, priority, assetId, locationId ইত্যাদি পাঠান। পার্ট ইনপুটে barcode, maxStockLevel, locationId ও vendorId-ও দেওয়া যায়, আর quantity/minQuantity/maxStockLevel দশমিক মান (যেমন 0.5) গ্রহণ করে। এনামারেটেড ফিল্ড যাচাই করা হয়: priority হতে হবে LOW, MEDIUM, HIGH, CRITICAL-এর একটি; কাজের নির্দেশনার status OPEN, SCHEDULED, IN_PROGRESS, ON_HOLD, COMPLETED, VALIDATED, CANCELLED, CLOSED-এর একটি; অ্যাসেটের status OPERATIONAL, DEGRADED, DOWN, MAINTENANCE, STANDBY, RETIRED-এর একটি। অন্য যেকোনো মান BAD_REQUEST দিয়ে প্রত্যাখ্যাত হয়। যন্ত্রাংশের ইনপুট customReference-ও গ্রহণ করে — যন্ত্রাংশটির জন্য আপনার নিজের কোড (যেমন আপনার ERP-এর কোড), যার সঙ্গে পরে part(barcode:) মেলে। এর অনন্যতা বাধ্যতামূলক নয়: সেটি নিশ্চিত করা আপনার দায়িত্ব।

উদাহরণ: একটি কাজের নির্দেশনা তৈরি করুন

একটি কাজের নির্দেশনা তৈরি: mutation($i: WorkOrderCreateInput!) { createWorkOrder(input: $i) { id title reference status createdAt } } ভেরিয়েবলসহ {"i": {"title": "Pump #3 leak", "priority": "HIGH"}}

স্টক সমন্বয়

একটি পার্টের পরিমাণ পরিবর্তন করতে চিহ্নযুক্ত ডেল্টা সহ adjustStock ব্যবহার করুন — খরচের জন্য ঋণাত্মক, গ্রহণের জন্য ধনাত্মক। এটি একটি একক পরমাণুবৎ লেনদেনে পরিমাণ আপডেট করে এবং একটি StockMovement অডিট সারি লেখে, এবং কখনও স্টককে শূন্যের নিচে নামতে দেয় না। যে পার্টের স্টক লোকেশন অনুযায়ী ট্র্যাক করা হয়, তার জন্য locationId দিন: মুভমেন্টটি সেই লোকেশনে প্রয়োগ হয়, আর এটি ছাড়া কলটি প্রত্যাখ্যাত হয়: errors[0].extensions.code হয় BAD_REQUEST এবং extensions.reason হয় LOCATION_STOCK_REQUIRES_LOCATION। অন্যদিকে updatePart(quantity) একটি পরম মান সেট করে: একই কারণে লোকেশন অনুযায়ী ট্র্যাক করা পার্টে এটি প্রত্যাখ্যাত হয়, আর অন্য ক্ষেত্রে পার্থক্যটি একটি ADJUSTMENT মুভমেন্ট হিসেবে রেকর্ড করে। আপনি পণ্যের উৎসও লিখে রাখতে পারেন: vendorId এবং documentNumber (সরবরাহকারীর চালান বা ডেলিভারি নোট নম্বর, সর্বোচ্চ ৬৪ অক্ষর) স্টক মুভমেন্টেই সংরক্ষিত হয়, ফলে ইতিহাসে দেখা যায় কে সরবরাহ করেছে এবং কোন নথির ভিত্তিতে। দুটিই ঐচ্ছিক — সাধারণ ব্যবহারে কোনোটিই পাঠানো হয় না। সরবরাহকারীকে আপনার কোম্পানির হতে হবে।

মিটার রিডিং রেকর্ড করা

addMeterReading একটি মিটারে রিডিং রেকর্ড করে — চালু থাকার ঘণ্টা, কাউন্টার, ওডোমিটার, গেজ — যাতে কোনো বাইরের সিস্টেম (SCADA, PLC গেটওয়ে, ERP) কাউকে সংখ্যাটি হাতে না লিখিয়েই মিটার-ভিত্তিক প্রতিরোধমূলক রক্ষণাবেক্ষণে তথ্য দিতে পারে। প্রথমে মিটারের id খুঁজে নিন: query { meters(assetId: 7) { id reference name unit type lastReadingValue lastReadingDate } } তারপর পাঠান হয় value (মিটারে দেখানো মোট পরম মান), নয়তো incrementValue (যেমন শেষ রিডিংয়ের পর থেকে চালু থাকার ঘণ্টা, যা সার্ভার আগের রিডিংয়ের সঙ্গে যোগ করে) — দুটির ঠিক একটি: mutation { addMeterReading(meterId: 12, value: 1250.5, date: "2026-09-25T06:00:00Z") { id value date isAnomaly } } date ঐচ্ছিক (ISO 8601, ডিফল্ট এখন) এবং অতীতে হতে পারে, কখনোই ভবিষ্যতে নয়। RUNTIME ও COUNTER মিটারে আগের রিডিংয়ের চেয়ে কম মান BAD_REQUEST দিয়ে প্রত্যাখ্যাত হয় — মিটার রিসেট বা বদলানোর পর confirmRegression: true দিয়ে আবার পাঠান। রিডিংটি অ্যাপের মিটার স্ক্রিনের একই সার্ভিসের মধ্য দিয়ে যায়: এটি সর্বশেষ হলে মিটার ট্রিগার ও মিটার-ভিত্তিক প্রতিরোধমূলক রক্ষণাবেক্ষণ ঠিক তেমনই চালু হয় যেমন কোনো টেকনিশিয়ানের লেখা রিডিংয়ে হয়। এই মিউটেশনের জন্য FULL অ্যাক্সেসের কি প্রয়োজন।

অ্যাট্রিবিউশন

প্রতিটি মিউটেশন কী-এর মালিক হিসেবে চলে — অর্থাৎ যে ব্যক্তির হয়ে কী কাজ করে — তাঁর অনুমতি, তাঁর ডেটা দেখার পরিসর এবং অডিট লগে তাঁর নাম নিয়ে। মালিক নিজে পারলেও কোনো কী কখনো ওয়ার্কফ্লো ধাপ অনুমোদন করে না।

নিরাপদে আবার চেষ্টা (Idempotency-Key)

নেটওয়ার্ক টাইমআউট থেকে বোঝা যায় না কোনো মিউটেশন চলেছে কি না। যে প্রতিটি অনুরোধ কিছু লেখে, তার সঙ্গে একটি Idempotency-Key হেডার পাঠান (৮ থেকে ৬৪টি অক্ষর, সংখ্যা বা হাইফেন — একটি UUID চলবে), এবং আবার চেষ্টা করার সময় একই কী পাঠান। ৭ দিন ধরে একই কী দিয়ে আবার চেষ্টা করলে মিউটেশনটি আবার চলে না, বরং প্রথম কলের সংরক্ষিত ফল ফেরত আসে (প্রতিক্রিয়ায় "Idempotent-Replayed: true" থাকে): দ্বিতীয় কোনো কাজের নির্দেশনা নয়, দ্বিগুণ স্টক চলাচলও নয়।

• প্রতিটি লেখার জন্য একটি কী। একাধিক অ্যালিয়াসযুক্ত মিউটেশনসহ একটি অনুরোধে প্রতিটি মিউটেশন সেই কী-এর অধীনে আলাদাভাবে রেকর্ড হয়। পাঠানো মানগুলো তুলনা করা হয় না: ভিন্ন মান দিয়ে একই কী পাঠালে প্রথম কলের ফলাফলই ফেরত আসে।
• ব্যর্থ কল কিছুই রাখে না: একই কী দিয়ে আবার চেষ্টা করলে সেটি আবার চলে।
• IDEMPOTENCY_KEY_REUSED — এই কী-তে একই নাম (ফিল্ড বা উপনাম) আগেই অন্য একটি মিউটেশন চালিয়েছে, অথবা অন্য কোনো কলকারী কী-টি ব্যবহার করেছে: নতুন লেখার জন্য নতুন কী ব্যবহার করুন।
• IDEMPOTENCY_IN_PROGRESS — প্রথম কলটি এখনও চলছে: কয়েক সেকেন্ড অপেক্ষা করে আবার চেষ্টা করুন।

সাধারণ ত্রুটি

• GRAPHQL_VALIDATION_FAILED — ইনপুটের গঠন মেলেনি (যেমন আবশ্যিক title অনুপস্থিত)
• BAD_REQUEST — মান যাচাই ব্যর্থ (যেমন 500 অক্ষরের বেশি title)
• FORBIDDEN — আপনার প্ল্যান Business-এর নিচে
• NOT_FOUND — id নেই বা অন্য কোম্পানির
• FORBIDDEN — কী-এর অ্যাক্সেস লেভেল যথেষ্ট নয় (যেমন READ কী দিয়ে mutation কল)