Mutasi GraphQL (Tulis)

Bermula dari pelan Business, titik akhir GraphQL menyokong 12 mutation tulis: cipta, kemas kini dan padam pada Perintah Kerja, Aset dan Alat Ganti, serta adjustStock untuk pergerakan stok. Mutation melalui perkhidmatan yang sama seperti yang digunakan aplikasi itu sendiri, jadi log audit, pemberitahuan dan penjanaan rujukan automatik (WO-XX, ASS-XX, PART-XX) berkelakuan serupa. Yang kesebelas, addMeterReading, merekod bacaan meter (jam operasi, pembilang) — lihat di bawah. Yang kedua belas, setPurchaseOrderErpReference, menulis nombor dokumen ERP anda pada pesanan belian (hanya dengan kunci akses FULL) dan tidak mencetuskan sebarang webhook, jadi ERP anda tidak pernah menerima semula tulisannya sendiri.

Mutasi yang tersedia

• 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

Bentuk input

Setiap mutasi mempunyai InputType dengan medan selamat sahaja — companyId, sequenceNumber, reference dan createdById diisi di pihak pelayan. Anda hanya menghantar title, description, status, priority, assetId, locationId, dan sebagainya. Input Part juga menerima barcode, maxStockLevel, locationId dan vendorId, dan quantity/minQuantity/maxStockLevel menerima perpuluhan (cth. 0.5). Medan berjenis enum disahkan: priority mesti salah satu daripada LOW, MEDIUM, HIGH, CRITICAL; status perintah kerja salah satu daripada OPEN, SCHEDULED, IN_PROGRESS, ON_HOLD, COMPLETED, VALIDATED, CANCELLED, CLOSED; status aset salah satu daripada OPERATIONAL, DEGRADED, DOWN, MAINTENANCE, STANDBY, RETIRED. Nilai lain ditolak dengan BAD_REQUEST. Input alat ganti turut menerima customReference — kod anda sendiri bagi bahagian itu (contohnya kod ERP anda), yang kemudian dipadankan oleh part(barcode:). Keunikannya tidak dikuatkuasakan: itu tanggungjawab anda.

Contoh: cipta arahan kerja

Mencipta perintah kerja: mutation($i: WorkOrderCreateInput!) { createWorkOrder(input: $i) { id title reference status createdAt } } dengan pemboleh ubah {"i": {"title": "Pump #3 leak", "priority": "HIGH"}}

Melaraskan stok

Untuk menukar kuantiti alat ganti, gunakan adjustStock dengan delta bertanda — negatif untuk mengguna, positif untuk menerima. Ia mengemas kini kuantiti dan menulis baris audit StockMovement dalam satu transaksi atomik, dan tidak sesekali membenarkan stok jatuh di bawah sifar. Bagi alat ganti yang stoknya dijejaki mengikut lokasi, hantar locationId: pergerakan itu dikenakan pada lokasi tersebut, dan tanpanya panggilan ditolak: errors[0].extensions.code ialah BAD_REQUEST dan extensions.reason ialah LOCATION_STOCK_REQUIRES_LOCATION. Sebaliknya, updatePart(quantity) menetapkan nilai mutlak: ia ditolak pada alat ganti yang dijejaki mengikut lokasi atas sebab yang sama, dan selain itu merekodkan perbezaannya sebagai pergerakan ADJUSTMENT. Anda juga boleh merekodkan asal barang: vendorId dan documentNumber (nombor invois atau nota penghantaran pembekal, maksimum 64 aksara) disimpan pada pergerakan itu sendiri, jadi sejarah menunjukkan siapa yang membekalkan dan di bawah dokumen yang mana. Kedua-duanya pilihan — penggunaan biasa tidak menghantar satu pun. Pembekal mesti milik syarikat anda.

Merekod bacaan meter

addMeterReading merekod bacaan pada meter — jam operasi, pembilang, odometer, tolok — supaya sistem luaran (SCADA, get laluan PLC, ERP) dapat menyuap penyelenggaraan pencegahan berasaskan meter tanpa sesiapa menaip semula angkanya. Cari id meter dahulu: query { meters(assetId: 7) { id reference name unit type lastReadingValue lastReadingDate } } Kemudian hantar SAMA ADA value (jumlah mutlak yang ditunjukkan meter) ATAU incrementValue (contohnya jam operasi sejak bacaan terakhir, yang ditambah oleh pelayan kepada bacaan sebelumnya) — tepat satu daripadanya: mutation { addMeterReading(meterId: 12, value: 1250.5, date: "2026-09-25T06:00:00Z") { id value date isAnomaly } } date adalah pilihan (ISO 8601, lalai sekarang) dan boleh pada masa lalu, tidak sekali-kali pada masa hadapan. Pada meter RUNTIME dan COUNTER, nilai yang lebih rendah daripada bacaan sebelumnya ditolak dengan BAD_REQUEST — selepas meter ditetapkan semula atau diganti, hantar semula dengan confirmRegression: true. Bacaan melalui perkhidmatan yang sama seperti skrin meter dalam aplikasi: jika ia yang terkini, pencetus meter dan penyelenggaraan pencegahan berasaskan meter berjalan tepat seperti bacaan yang ditaip oleh juruteknik. Mutasi ini memerlukan kunci dengan akses FULL.

Atribusi

Setiap mutasi dijalankan sebagai pemilik kunci — orang yang diwakili oleh kunci itu — dengan kebenarannya, keterlihatan datanya dan namanya dalam log audit. Kunci tidak sekali-kali meluluskan langkah aliran kerja, walaupun pemiliknya boleh berbuat demikian.

Cuba semula dengan selamat (Idempotency-Key)

Tamat masa rangkaian tidak memberitahu sama ada sesuatu mutasi telah dijalankan. Hantar pengepala Idempotency-Key (8 hingga 64 huruf, digit atau sempang — UUID boleh digunakan) bersama setiap permintaan yang menulis data, dan hantar kunci YANG SAMA apabila anda mencubanya semula. Selama 7 hari, cubaan semula dengan kunci yang sama memulangkan hasil tersimpan panggilan pertama (respons membawa "Idempotent-Replayed: true") dan bukannya menjalankan mutasi sekali lagi: tiada arahan kerja kedua, tiada pergerakan stok berganda.

• Satu kunci bagi setiap penulisan. Dalam permintaan yang mengandungi beberapa mutasi beralias, setiap mutasi direkodkan secara berasingan di bawah kunci itu. Nilai yang dihantar tidak dibandingkan: kunci yang sama dengan nilai berbeza mengembalikan hasil panggilan pertama.
• Panggilan yang gagal tidak menyimpan apa-apa: mencubanya semula dengan kunci yang sama akan menjalankannya sekali lagi.
• IDEMPOTENCY_KEY_REUSED — dengan kunci ini, nama yang sama (medan atau alias) telah menjalankan mutasi lain, atau pemanggil lain telah menggunakan kunci ini: gunakan kunci baharu untuk penulisan baharu.
• IDEMPOTENCY_IN_PROGRESS — panggilan pertama masih berjalan: tunggu beberapa saat dan cuba semula.

Ralat biasa

• GRAPHQL_VALIDATION_FAILED — bentuk input tidak sepadan (contohnya title wajib tiada)
• BAD_REQUEST — pengesahan nilai gagal (contohnya title melebihi 500 aksara)
• FORBIDDEN — pelan anda di bawah Business
• NOT_FOUND — id tidak wujud atau milik syarikat lain
• FORBIDDEN — tahap akses kunci terlalu rendah (contohnya kunci READ memanggil mutation)