GraphQL Mutation များ (ရေးသားခြင်း)

Business plan မှစ၍ GraphQL endpoint သည် ရေးသားမှု mutation 12 ခုကို ပံ့ပိုးသည်- Work Order၊ Asset နှင့် Part များအပေါ် ဖန်တီးခြင်း၊ မွမ်းမံခြင်းနှင့် ဖျက်ခြင်း၊ ထို့အပြင် ကုန်ပစ္စည်းရွှေ့ပြောင်းမှုအတွက် adjustStock။ Mutation များသည် အက်ပ်ကိုယ်တိုင်အသုံးပြုသည့် service များကိုပင် ဖြတ်သန်းသောကြောင့် audit log၊ notification နှင့် reference အလိုအလျောက်ထုတ်ပေးခြင်း (WO-XX၊ ASS-XX၊ PART-XX) တို့သည် အတူတူပင် အလုပ်လုပ်သည်။ ဆယ့်တစ်ခုမြောက် addMeterReading သည် မီတာဖတ်ချက်များ (လည်ပတ်ချိန်နာရီ၊ ကောင်တာ) ကို မှတ်တမ်းတင်သည် — အောက်တွင် ကြည့်ပါ။ ဆယ့်နှစ်ခုမြောက် setPurchaseOrderErpReference သည် သင့် ERP ၏ စာရွက်စာတမ်းနံပါတ်ကို ဝယ်ယူမှုအမိန့်ပေါ်သို့ ရေးသွင်းသည် (FULL access key ဖြင့်သာ)။ webhook တစ်ခုမျှ မဖြစ်ပေါ်စေသဖြင့် သင့် ERP သည် မိမိရေးသွင်းမှုကို ဘယ်တော့မှ ပြန်မရပါ။

ရရှိနိုင်သော mutation များ

• 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

Input ပုံစံ

mutation တစ်ခုစီတွင် လုံခြုံသော field များသာပါဝင်သည့် InputType ရှိသည် — companyId, sequenceNumber, reference နှင့် createdById ကို server ဘက်မှ ဖြည့်ပေးသည်။ သင်သည် title, description, status, priority, assetId, locationId စသည်တို့ကိုသာ ပို့ရမည်ဖြစ်သည်။ Part input များသည် barcode, maxStockLevel, locationId နှင့် vendorId ကိုပါ လက်ခံပြီး၊ quantity/minQuantity/maxStockLevel တို့သည် ဒဿမကိန်း (ဥပမာ 0.5) ကို လက်ခံသည်။ Enum အမျိုးအစား field များကို စစ်ဆေးသည်- priority သည် LOW, MEDIUM, HIGH, CRITICAL ထဲမှတစ်ခု၊ work order ၏ status သည် OPEN, SCHEDULED, IN_PROGRESS, ON_HOLD, COMPLETED, VALIDATED, CANCELLED, CLOSED ထဲမှတစ်ခု၊ asset ၏ status သည် OPERATIONAL, DEGRADED, DOWN, MAINTENANCE, STANDBY, RETIRED ထဲမှတစ်ခု ဖြစ်ရမည်။ အခြားတန်ဖိုးများကို BAD_REQUEST ဖြင့် ငြင်းပယ်သည်။ အပိုပစ္စည်း input များသည် customReference ကိုပါ လက်ခံသည် — ထိုပစ္စည်းအတွက် သင့်ကိုယ်ပိုင်ကုဒ် (ဥပမာ သင့် ERP ကုဒ်) ဖြစ်ပြီး၊ ထို့နောက် part(barcode:) က ၎င်းနှင့် ကိုက်ညီပါသည်။ တစ်မူထူးခြားမှုကို မတောင်းဆိုပါ — ၎င်းမှာ သင့်တာဝန်ဖြစ်သည်။

ဥပမာ - work order တစ်ခု ဖန်တီးခြင်း

Work order တစ်ခု ဖန်တီးရန်- mutation($i: WorkOrderCreateInput!) { createWorkOrder(input: $i) { id title reference status createdAt } } variable များနှင့်အတူ {"i": {"title": "Pump #3 leak", "priority": "HIGH"}}

လက်ကျန်ပစ္စည်း ချိန်ညှိခြင်း

part တစ်ခု၏ quantity ကို ပြောင်းလဲရန် signed delta ဖြင့် adjustStock ကို အသုံးပြုပါ — စားသုံးရန် အနုတ်၊ လက်ခံရန် အပေါင်း။ ၎င်းသည် quantity ကို update လုပ်ပြီး StockMovement audit row ကို atomic transaction တစ်ခုတည်းတွင် ရေးသားကာ၊ လက်ကျန်ပစ္စည်းကို ဘယ်သောအခါမျှ သုညအောက် မကျဆင်းစေပါ။ တည်နေရာအလိုက် လက်ကျန်ကို ခြေရာခံထားသော အပိုပစ္စည်းအတွက် locationId ကို ပေးပါ- လှုပ်ရှားမှုကို ထိုတည်နေရာတွင် သက်ရောက်စေပြီး၊ ၎င်းမပါဘဲ ခေါ်ဆိုပါက ငြင်းပယ်ခံရသည်- errors[0].extensions.code သည် BAD_REQUEST ဖြစ်ပြီး extensions.reason သည် LOCATION_STOCK_REQUIRES_LOCATION ဖြစ်သည်။ updatePart(quantity) မူ ပကတိတန်ဖိုးတစ်ခုကို တိုက်ရိုက်သတ်မှတ်သည်- တည်နေရာအလိုက် ခြေရာခံထားသော အပိုပစ္စည်းတွင် ထိုအကြောင်းရင်းကြောင့်ပင် ငြင်းပယ်ခံရပြီး၊ အခြားအခြေအနေများတွင် ကွာခြားချက်ကို ADJUSTMENT လှုပ်ရှားမှုအဖြစ် မှတ်တမ်းတင်သည်။ ကုန်ပစ္စည်း၏ မူလအရင်းအမြစ်ကိုလည်း မှတ်တမ်းတင်နိုင်သည်— vendorId နှင့် documentNumber (ပေးသွင်းသူ၏ ငွေတောင်းခံလွှာ သို့မဟုတ် ပစ္စည်းပို့လွှာ နံပါတ်၊ အများဆုံး ၆၄ လုံး) ကို လှုပ်ရှားမှုမှတ်တမ်းပေါ်တွင်ပင် သိမ်းဆည်းသဖြင့် မည်သူပေးသွင်းသည်၊ မည်သည့်စာရွက်စာတမ်းအရဖြစ်သည်ကို မှတ်တမ်းတွင် မြင်ရသည်။ နှစ်ခုစလုံး ရွေးချယ်နိုင်ပြီး သာမန်သုံးစွဲမှုတွင် မပို့ပါ။ ပေးသွင်းသူသည် သင့်ကုမ္ပဏီပိုင် ဖြစ်ရမည်။

မီတာဖတ်ချက်များ မှတ်တမ်းတင်ခြင်း

addMeterReading သည် မီတာတစ်ခုပေါ်တွင် ဖတ်ချက်တစ်ခုကို မှတ်တမ်းတင်သည် — လည်ပတ်ချိန်နာရီ၊ ကောင်တာ၊ အကွာအဝေးမီတာ၊ တိုင်းကိရိယာ — ထို့ကြောင့် ပြင်ပစနစ် (SCADA၊ PLC gateway၊ 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 ဖြင့် ပြန်ပို့ပါ။ ဖတ်ချက်သည် အက်ပ်ရှိ မီတာမျက်နှာပြင်နှင့် တူညီသော service ကို ဖြတ်သန်းသည်- ၎င်းသည် နောက်ဆုံးဖတ်ချက် ဖြစ်ပါက မီတာ trigger များနှင့် မီတာအခြေပြု ကြိုတင်ကာကွယ်ထိန်းသိမ်းမှုသည် နည်းပညာရှင်တစ်ဦး ရိုက်ထည့်သော ဖတ်ချက်အတိုင်း အတိအကျ အလုပ်လုပ်သည်။ ဤ mutation အတွက် FULL ဝင်ရောက်ခွင့်ရှိသော key လိုအပ်သည်။

Attribution (တာဝန်ခံအမည်တပ်ခြင်း)

ပြောင်းလဲမှု လုပ်ဆောင်ချက်တိုင်းကို ကီး၏ပိုင်ရှင် — ကီးက ကိုယ်စားပြုလုပ်ဆောင်သည့်သူ — အဖြစ် ထိုသူ၏ ခွင့်ပြုချက်များ၊ ဒေတာမြင်နိုင်မှုနှင့် စစ်ဆေးမှုမှတ်တမ်းရှိ ထိုသူ၏အမည်ဖြင့် လုပ်ဆောင်သည်။ ပိုင်ရှင်ကိုယ်တိုင် အတည်ပြုနိုင်သော်လည်း ကီးသည် လုပ်ငန်းစဉ်အဆင့်ကို ဘယ်တော့မှ အတည်မပြုပါ။

ဘေးကင်းစွာ ပြန်ကြိုးစားခြင်း (Idempotency-Key)

ကွန်ရက် အချိန်ကုန်သွားခြင်းက mutation တစ်ခု လုပ်ဆောင်ပြီးမပြီး မပြောပြပါ။ ဒေတာရေးသော တောင်းဆိုမှုတိုင်းတွင် Idempotency-Key ခေါင်းစီး (အက္ခရာ၊ ဂဏန်း သို့မဟုတ် တုံးတို ၈ လုံးမှ ၆၄ လုံး — UUID သုံးနိုင်သည်) ကို ပို့ပြီး ပြန်ကြိုးစားသည့်အခါ တူညီသော ကီး ကိုပင် ပို့ပါ။ ၇ ရက်အတွင်း တူညီသော ကီး ဖြင့် ပြန်ကြိုးစားပါက mutation ကို ထပ်မလုပ်ဘဲ ပထမခေါ်ဆိုမှု၏ သိမ်းထားသော ရလဒ်ကို ပြန်ပေးသည် (တုံ့ပြန်ချက်တွင် "Idempotent-Replayed: true" ပါသည်)။ ဒုတိယ အလုပ်အမိန့် မဖြစ်ပေါ်ပါ၊ စတော့ရွေ့လျားမှုလည်း နှစ်ခါ မမှတ်ပါ။

• ရေးသားမှုတစ်ခုလျှင် ကီး တစ်ခု။ alias ပါသော mutation အများအပြားပါဝင်သည့် တောင်းဆိုမှုတွင် mutation တစ်ခုစီကို ထို ကီး အောက်တွင် သီးခြားစီ မှတ်တမ်းတင်သည်။ ပို့သော တန်ဖိုးများကို နှိုင်းယှဉ်ခြင်း မပြုပါ- တူညီသောကီးကို မတူညီသော တန်ဖိုးများဖြင့် ပို့လျှင် ပထမခေါ်ဆိုမှု၏ ရလဒ်ကိုသာ ပြန်ပေးသည်။
• မအောင်မြင်သော ခေါ်ဆိုမှုသည် ဘာမျှ မသိမ်းပါ — တူညီသော ကီး ဖြင့် ပြန်ကြိုးစားလျှင် ထပ်မံ လုပ်ဆောင်သည်။
• IDEMPOTENCY_KEY_REUSED — ဤကီးဖြင့် တူညီသောအမည် (အကွက် သို့မဟုတ် အမည်ကွဲ) သည် အခြား mutation တစ်ခုကို လုပ်ဆောင်ပြီးဖြစ်သည်၊ သို့မဟုတ် အခြားခေါ်ဆိုသူက ဤကီးကို အသုံးပြုထားသည် — ရေးသားမှုအသစ်အတွက် ကီးအသစ်ကို သုံးပါ။
• IDEMPOTENCY_IN_PROGRESS — ပထမခေါ်ဆိုမှု လုပ်ဆောင်ဆဲဖြစ်သည် — စက္ကန့်အနည်းငယ် စောင့်ပြီး ပြန်ကြိုးစားပါ။

အများဆုံးကြုံရသော error များ

• GRAPHQL_VALIDATION_FAILED — input ပုံစံ မကိုက်ညီပါ (ဥပမာ လိုအပ်သော title မပါ)
• BAD_REQUEST — တန်ဖိုးစိစစ်ခြင်း မအောင်မြင်ပါ (ဥပမာ စာလုံး 500 ကျော် title)
• FORBIDDEN — သင့် plan သည် Business အောက်ဖြစ်သည်
• NOT_FOUND — id မရှိပါ သို့မဟုတ် အခြားကုမ္ပဏီပိုင်ဖြစ်သည်
• FORBIDDEN — key ၏ access level မလုံလောက်ပါ (ဥပမာ READ key ဖြင့် mutation ခေါ်ခြင်း)