الطلبيات

الغرض ومنطق العمل

كل Order = شحنة واحدة (CI/BL/ETA…). عند الحفظ يُستورد السيريال ويُنشأ OrderSerial لكل رقم. تاريخ warehouse_arrival_at + grace_period_months يحددان نافذة تسجيل الكفالة.

إذا فشل الاستيراد عند الإنشاء: تُحذف الطلبية بالكامل (all-or-nothing). راجع الإشعار و trace_id.

راجع خريطة الطلبيات والسيريالات.

الارتباطات

المورد	الحقل / العلاقة	الأثر
Suppliers	`supplier_id` — مطلوب	المورد في الصين. Transfer يُقفل على MARVEL.
Products	بنود `serial_lines.product_id`	كل سيريال يُربط بمنتج عند الاستيراد.
Serials	`serials()`	RelationManager Serials + عداد Serials في الجدول.
Markets	`market_id`، OrderMarkets	بلد البيع + توزيع الكميات (صلاحية manage markets).
Warranty Durations	`grace_period_months` + warehouse	نافذة السماح بالتسجيل بعد وصول المستودع.
Warranties	OrderSerial.serial_number	التطبيق يبحث عن السيريال في هذه الطلبية.

أوضاع الطلبية (Order mode) — متى تستخدم أي وضع؟

الحقل Order mode / نوع الطلبية (serial_mode) لا يُحفظ في قاعدة البيانات — يوجّهك في النموذج فقط. ما يُحفظ هو order_type: new أو transfer.

الوضع في اللوحة	order_type	متى تستخدمه	ما الذي يظهر / يختفي
New Order — Manual / Range	`new`	شحنة جديدة من المصنع. السيريالات قليلة أو متسلسلة (نطاق رقمي).	بنود Product lines. Supplier حر. تستخدم Manual Serials أو Range Start + QTY.
New Order — Import per line	`new`	شحنة جديدة لكن كل منتج له ملف Excel/CSV منفصل (آلاف السيريالات).	نفس بنود Product lines. لكل بند ترفع Serial Number File — الملف له الأولوية على باقي الحقول.
Transfer Order	`transfer`	نقل مخزون سيريالات موجودة مسبقاً إلى طلبية MARVEL (إعادة توزيع / نقل داخلي).	يختفي repeater البنود. Supplier يُقفل على MARVEL. يظهر Transfer serial file فقط.

ماذا يحدث عند Save في كل وضع؟

الوضع	السلوك
Manual / Import per line	يُنشأ Order → يُمرّر كل بند إلى محرك الاستيراد → يُنشأ `OrderSerial` لكل رقم. إن فشل التحقق (تكرار، بند بلا سيريالات…) → تُحذف الطلبية بالكامل عند الإنشاء.
Transfer	لكل سيريال في الملف: إن وُجد في النظام → يُنقل إلى هذه الطلبية + يُسجّل Serial Transfer + `is_transferred = true` + يُحتفظ بـ Made In الأصلي. إن لم يُوجد → يُنشأ سيريال جديد بـ `product_id = null` (يظهر في Unassigned Serials).

Manual و Import per line يستخدمان نفس محرك الاستيراد — الفرق عملي: في Manual تعتمد على الكتابة اليدوية أو النطاق؛ في Import ترفع ملفاً لكل بند.

الاستيراد الكبير يُ queued تلقائياً → إشعار «Large import queued» مع trace_id و run_id. الطلبية تُنشأ لكن السيريالات تُكمل في الخلفية.

بنود المنتج (Product lines) — الحقول والحالات

تظهر فقط عندما Order mode ≠ Transfer. كل بند = منتج واحد + طريقة إدخال السيريالات. يمكن إضافة عدة بنود (منتج A + منتج B…).

ترتيب الأولوية — كيف يختار النظام مصدر السيريالات؟

لكل بند، النظام يأخذ السيريالات من مصدر واحد حسب هذا الترتيب (الأول الموجود يفوز):

Serial Number File — إن رُفع ملف → يُقرأ العمود A فقط (صفاً صفاً). يُتجاهل Manual و Range.
Manual Serials — إن لم يُرفع ملف وكان الحقل غير فارغ → سطر = سيريال واحد (الأسطر الفارغة تُتخطى).
Range Start Serial + QTY — إن لم يُرفع ملف و Manual فارغ → يُولَّد نطاق من Range Start بعدد QTY.

إن لم يُوفَّر أي من الثلاثة → خطأ NO_SERIALS_PROVIDED → فشل الاستيراد (وحذف الطلبية عند الإنشاء).

جدول الحقول

الحقل	التقني	مطلوب؟	الشرح
Product	`product_id`	مطلوب	كل سيريال في هذا البند يُربط بهذا المنتج.
QTY	`quantity`	مع Range	عدد السيريالات المُولَّدة. مطلوب > 0 مع Range Start. يُتجاهل إن وُجد ملف أو Manual.
Warranty	`warranty`	اختياري	أشهر — تُنسخ لكل سيريال في البند.
Private Warranty	`pwarranty`	اختياري	كفالة خاصة — تُنسخ لكل سيريال.
Batch Number	`batch_number`	اختياري	يُنسخ لكل سيريال. بديل للبحث في الكفالة — التكرار مسموح.
Date Code	`date_code`	اختياري	مثل Batch — بديل للسيريال في API الكفالة.
Made In (line)	`made_in`	اختياري	تجاوز لـ Made In رأس الطلبية. إن تُرك فارغاً → يُؤخذ من رأس الطلبية.
Range Start Serial	`serial_start`	شرطي	أول رقم في النطاق — انظر الحالات أدناه.
Manual Serials	`manual_serials`	شرطي	سيريال لكل سطر — انظر الحالات أدناه.
Serial Number File	`serials_file`	شرطي	xlsx / xls / csv / txt — العمود A = السيريال.

حالات عملية — ماذا تملأ في كل سيناريو؟

السيناريو	Product	QTY	Range Start	Manual	File	النتيجة
ملف Excel من المصنع	✓	—	فارغ	فارغ	✓ xlsx	كل صف في العمود A = سيريال. QTY و Range لا يُستخدمان.
نطاق متسلسل (100 بطارية)	✓	100	`BT20260001`	فارغ	فارغ	يُولّد 100 رقماً: BT20260001 … BT20260100 (انظر قواعد الزيادة).
قائمة يدوية قصيرة	✓	—	فارغ	سطر لكل SN	فارغ	كل سطر في Manual = سيريال واحد. QTY لا يُستخدم.
بند بلا أي سيريال	✓	0 أو فارغ	فارغ	فارغ	فارغ	❌ `NO_SERIALS_PROVIDED` — فشل الاستيراد.
Range بدون QTY	✓	0 أو فارغ	SN001	فارغ	فارغ	❌ لا يُولّد نطاق — QTY يجب أن يكون > 0.
ملف + Range معاً	✓	50	SN001	—	✓	الملف فقط — Range و QTY يُتجاهلان.

Range Start Serial — كيف يعمل النطاق؟

عندما لا يُرفع ملف وManual Serials فارغ، املأ:

Range Start Serial = أول رقم في التسلسل (مثال: ML-PL-000100)
QTY = كم سيريال تريد توليده (مثال: 5)

النظام يجد آخر مجموعة أرقام في النص ويزيدها واحداً واحداً مع الحفاظ على عدد الخانات (zero-padding):

Range Start	QTY	السيريالات المُولَّدة
`ML000100`	3	ML000100 ، ML000101 ، ML000102
`SN-2026-0099`	2	SN-2026-0099 ، SN-2026-0100
`ABC` (بلا أرقام)	3	ABC0 ، ABC1 ، ABC2

تأكد أن QTY = العدد الفعلي للقطع. النطاق لا يتحقق من «فراغات» في التسلسل — يولّد أرقاماً رياضياً فقط.

Manual Serials — قواعد الكتابة

سيريال واحد في كل سطر (Enter بين كل رقم).
الأسطر الفارغة تُتخطى.
لا تضع فاصلة بين الأرقام في سطر واحد — كل سطر = سيريال مستقل.
مثال:

SN-A-001
SN-A-002
SN-A-003

Serial Number File — تنسيق الملف

الصيغ: xlsx، xls، csv، txt.
العمود A فقط — الصف الأول إن كان فيه رقم يُعتبر سيريال (لا يوجد صف عناوين إلزامي).
الخلايا الفارغة في العمود A تُتخطى.
بند واحد = ملف واحد. لمنتجين → بندان → ملفان.

قواعد التحقق المشتركة (كل الأوضاع)

القاعدة	رسالة الخطأ
لا تكرار داخل نفس الاستيراد	`DUPLICATE_IN_INPUT`
السيريال غير موجود مسبقاً في قاعدة البيانات (طلبية new)	`DUPLICATE_IN_DATABASE`
Product غير موجود	`INVALID_PRODUCT_MAPPING`
ملف تالف أو غير قابل للقراءة	`FILE_READ_FAILED`

صورة تقريبية — رأس الطلبية

Create Order

Order mode

New Order — Manual / Range

Supplier *

Factory ABC

CI number *

CI-2026-001

BL Number *

BL-8842

Order Number *

AW-1024

Warehouse arrival *

2026-03-15

Grace period (months)

12

Status

Received

حقول رأس الطلبية

الاسم	التقني	مطلوب؟	الشرح
Supplier	`supplier_id`	مطلوب	المورد. Transfer = MARVEL فقط.
CI / BL / Order Number	`ci_number`, `bl_number`, `order_number`	مطلوب	مرجع الشحنة في نظام الأوائل.
ETA / ETD / CI Date	`eta_date`, `etd_date`, `ci_date`	مطلوب	تواريخ الشحن والفاتورة.
Made In	`made_in`	مطلوب	يُنسخ لكل سيريال (Transfer يحتفظ بالأصل).
Warehouse arrival	`warehouse_arrival_at`	مطلوب	بداية grace period للكفالة.
Market Place	`market_id`	اختياري	بلد البيع الافتراضي.
Grace period	`grace_period_months`	افتراضي 12	أشهر السماح بتسجيل الكفالة.
Status	`status`	pending/received/cancelled	حالة الطلبية.
Total price/weight/volume	—	اختياري	معلومات إدارية.

Transfer — ملف النقل (بدون Product lines)

عند اختيار Transfer Order يختفي repeater البنود ويظهر حقل واحد:

الحقل	الشرح
Transfer serial file	xlsx / xls / csv / txt — العمود A = أرقام سيريالات من طلبيات سابقة. مطلوب.

Supplier يُعيَّن تلقائياً على MARVEL ولا يمكن تغييره. Made In الأصلي لكل سيريال موجود لا يُستبدل.

Relation Managers (صفحة View/Edit)

التبويب	الغرض	صلاحية
Serials	عرض/إضافة/تعديل سيريالات الطلبية	manage serials
Market Distribution	market_id + quantity لكل سوق	manage markets

خطوات إنشاء طلبية جديدة

تأكد من Products وSupplier.
Orders → + New → اختر Order mode.
املأ رأس الطلبية — خاصة warehouse_arrival و grace period.
أضف بنود منتج + سيريالات (ملف أو يدوي أو range).
Save — انتظر إشعار النجاح أو الخطأ.
View → Serials: تحقق من العدد والمنتجات.
إن وُجدت سيريالات بلا منتج → Unassigned Serials.

أين يظهر؟

الواجهة	الدور
Serials	كل سيريال مربوط بـ order_id.
Serial Track	بحث يعرض order_number و supplier.
تطبيق الكفالة	API يبحث serial في order_serials + order.grace.

أخطاء شائعة

المشكلة	السبب	الحل
Order import failed — حُذفت الطلبية	Integrity gate (تكرار، ملف فارغ…)	صحّح الملف وأعد الإنشاء. راجع trace_id.
NO_SERIALS_PROVIDED	بند بلا ملف ولا Manual ولا Range+QTY	أضف أحد مصادر السيريالات الثلاثة لكل بند.
Range Start بدون QTY	quantity = 0 أو فارغ	ضع QTY > 0 يساوي عدد القطع.
عدد سيريالات ≠ QTY	Range يولّد رياضياً فقط	تأكد أن Range Start صحيح وأن QTY = العدد المطلوب.
لا سيريالات بعد الحفظ	لم تُضف بنود أو ملف	أضف serial_lines أو transfer_file.
الكفالة خارج النافذة	warehouse_arrival + grace	صحّح التاريخ أو grace_period_months.
Transfer لا يغيّر Supplier	مقفل على MARVEL	سلوك متعمد — لا تحاول تغييره.