تشريح ملف التصدير

حين تفتح ملف تصدير لأول مرة ستتساءل عمّا أصابه. سطران يبدآن بـ //، والثالث يبدأ بـ :-record:SalesInvoice، وهناك أوراق إضافية باسم details وpaymentLines في كل منها عمود غامض عنوانه #headerconnector، وعدة حقول تظهر مرتين — مرة ككود ومرة كاسم.

ولكل ذلك غرض: فالملف وثيقة ذات اتجاهين. السطور التي تقرؤها موجّهة إليك، وسطور العلامات موجّهة إلى النظام، حتى إذا رفعت الملف نفسه عرف بالضبط أي نوع كيان يحمل وأي خلية تخصّ أي حقل. وحين تتقن قراءة هذا التخطيط تصير قادرًا على كتابته أيضًا، وهكذا تبني ملف استيراد من الصفر.

الورقة الرئيسية

خذ ملف تصدير حقيقيًا لفاتورتَي مبيعات. تبدو الورقة الأولى هكذا، والعمود A محجوز للعلامات والبيانات الفعلية تبدأ من العمود B:

	A	B	C	D	E
1	//	Export list of SalesInvoice	created on: Sat Aug 01 19:22:52 2026
2	//	الدفتر	الدفتر: الاسم	الكود	التاريخ الفعلي
3	:-record:SalesInvoice	book	book@name	code	valueDate
4		SalesInvoice$#SINV	فاتورة مبيعات	SINV0000035	01-02-2024
5		SalesInvoice$#SINV	فاتورة مبيعات	SINV0000004	23-04-2024

أربعة أنواع من السطور، ولا تعدّل منها إلا نوعًا واحدًا:

السطر الأول — العنوان التعريفي. الرمز // يعني «تعليق، تجاهلني». وهو يسجّل ما الذي صُدِّر ومتى. ولا شيء فيه يهمّ النظام.

السطر الثاني — العناوين البشرية. تعليق أيضًا. وهي المسمّيات التي تراها على الشاشة، مكتوبة باللغة التي كنت تستعملها وقت التصدير — مسمّيات عربية إن كانت الجلسة عربية. وهذا هو السطر الذي تقرؤه أثناء العمل في الورقة. غيّره أو احذفه أو ترجمه؛ فالاستيراد لا يبالي به. وآخر عمود فيه دائمًا عنوان الأخطاء.

السطر الثالث — العناوين الحقيقية. هذا هو السطر المهم. فـ :-record:SalesInvoice في العمود A يعلن نوع الكيان، وكل خلية بعده هي معرّف حقل — الاسم الداخلي للحقل الذي يملؤه ذلك العمود. لا شيء هنا مترجم، ولا ينبغي تعديل شيء هنا باستهتار: غيِّر valueDate إلى التاريخ الفعلي وسيتوقف ذلك العمود عن العمل ببساطة.

السطر الرابع فما بعده — بياناتك. العمود A يُترك فارغًا. وهذه هي المنطقة الوحيدة التي تضيف فيها سطورًا أو تعدّلها أو تحذفها.

لا تفرز السطور الثلاثة الأولى ولا تعد ترتيبها

سيسحب أمر الفرز في Excel سطور العلامات إلى وسط بياناتك بلا تردد. حدِّد دائمًا سطور البيانات وحدها قبل الفرز، وإلا صار الملف غير مقروء للاستيراد.

أوراق التفاصيل

فاتورة المبيعات ليست سطرًا مسطّحًا — فلها سطور أصناف وسطور دفع ومستندات تسليم. وكل مجموعة منها تصير ورقة مستقلة باسم المجموعة (details وpaymentLines وstockDocs)، وكل ورقة موصولة بسطور الهيدر التابعة لها.

هذه ورقة details من ملف التصدير نفسه:

	A	B	C	D
1	//	#headerconnector	الصنف	الكمية
2	:-detail:details	#code	details.item.item	details.quantity.quantity.primeQty.value
3		SINV0000035	9999	1
4		SINV0000004	01001	10

يعلن العمود A المجموعة عبر :-detail:details. والعمود B هو الرابط: عنوانه #code، وكل سطر فيه يكرر كود الفاتورة التي ينتمي إليها ذلك السطر. فالسطر 3 أعلاه يخصّ الفاتورة SINV0000035، والسطر 4 يخصّ SINV0000004. هذه هي آلية الربط كلها — بلا معادلات ولا أرقام سطور، مجرد تكرار كود الأب في كل سطر.

ولاحظ كذلك أن معرفات حقول التفاصيل تحمل اسم المجموعة كبادئة: details.item.item لا item. والنقاط تتبع المسار الحقيقي للحقل داخل السجل، ولهذا يطول بعضها — فـ details.quantity.quantity.primeQty.value ليس إلا «الكمية بالوحدة الرئيسية في هذا السطر».

سطر تفاصيل لا يطابق كودُه شيئًا يُهمَل بصمت

إن أضفت سطرًا إلى ورقة details وأخطأت في كتابة كود الفاتورة في العمود B فلن يرفع ذلك السطر خطأً. فليس له هيدر يرتبط به، ومن ثمّ يُتجاهل بهدوء. وحين تختفي سطور بعد الاستيراد فابدأ بفحص هذا العمود.

وثمة حدّان جديران بالمعرفة. أسماء الأوراق تُقتطع عند 31 حرفًا (وهو حدّ Excel نفسه)، مع حذف حروف العلة لضغط أسماء المجموعات الطويلة — فقد لا يطابق اسم الورقة معرّف الحقل تمامًا. كما أن تفاصيل التفاصيل لا تُصدَّر: فإن كان لسطر التفاصيل جدول فرعي خاص به فلن يظهر ذلك المستوى الثاني في الملف ولا يمكن استيراده بهذه الطريقة.

وإن ألغيت خيار التفاصيل في ورقة منفصلة فالمعلومات نفسها تُكتب داخل الورقة الواحدة: أسفل كل سطر هيدر يأتي سطر عنوان :-detail:details، ثم سطور ذلك السجل، ثم سطر :-enddetail، ثم الهيدر التالي. وهو تخطيط مضغوط لكن يصعب العمل عليه يدويًا — والأوراق المنفصلة شبه دائمًا هي الخيار الأفضل.

قراءة عناوين الأعمدة

معظم العناوين مجرد معرّف حقل. وأربعة أنواع منها تحمل معنى إضافيًا.

field — مرجع

عمود مثل customer أو warehouse يحمل كودًا لا اسمًا: 10011 و00. وعند الاستيراد يُبحث عن ذلك الكود للعثور على السجل الحقيقي.

وقليل من المراجع يبدو أغرب من الكود المجرد. فدفاتر المستندات وتوجيهاتها تُكتب هكذا SalesInvoice$#SINV — نوع الكيان ثم كود الدفتر نفسه. وهذا طبيعي؛ اتركه كما صُدِّر.

field@name — الاسم إلى جوار الكود

بعد عمود customer مباشرة ستجد customer@name يحمل «عميل 11». وهذا العمود موجود لغرض واحد: أن تكون ورقةٌ مليئة بالأكواد مقروءةً لإنسان.

أعمدة الأسماء تُتجاهل عند الاستيراد

تُكتب أعمدة @name عند التصدير وتُتجاهل تمامًا عند الاستيراد. وتعديل أحدها لا يغيّر شيئًا — فإن أردت توجيه سطر إلى عميل آخر فعليك تغيير عمود الكود لا عمود الاسم. وكم من عملية استيراد «فشلت بصمت» لأن أحدهم عدّل النصف المقروء وحده.

field#type + field#code — مرجع يمكن أن يشير إلى أي شيء

بعض الحقول تحمل رابطًا إلى أكثر من نوع سجل. فـ «الذمة» في الفاتورة قد تكون عميلًا أو موردًا أو موظفًا. وتُصدَّر هذه الحقول في عمودين متجاورين:

subsidiary#type	subsidiary#code
Customer	10011

الأول يقول أي نوع من السجلات، والثاني يقول أيّها بعينه. وكلاهما لازم، ولا بد أن يبقيا متجاورين وبهذا الترتيب — النوع أولًا ثم الكود.

@errors — بطاقة النتيجة

آخر عمود في كل ورقة هو @errors، ويكون فارغًا عند التصدير. وحين ترفع الملف يكتب فيه الاستيراد سبب فشل كل سطر فاشل. وتفصيل ذلك في استيراد السجلات.

أعمدة المعرّفات

بحسب الخيارات التي أشّرت عليها عند التصدير قد ترى أيضًا:

• id في الورقة الرئيسية — معرّف السجل الداخلي، ولا يظهر إلا إن أشّرت على إضافة حقل المعرف. وهو مفيد حين لا يكون للسجلات كود يُعتمد عليه في المطابقة.
• details.id و**details.masterRowId** و**details.sourceLineId** في أوراق التفاصيل — وهي موجودة افتراضيًا لأن إضافة حقل معرف السطور مفعّل.

ومعرفات السطور تلك أهمّ مما تبدو. فحين يحمل كل سطر تفاصيل في ملفك معرّفه تُحدِّث إعادةُ الاستيراد تلك السطور بعينها. وحين تغيب المعرفات تُطابَق السطور بالموضع بدلًا من ذلك — فالسطر الأول في الملف يكتب فوق السطر الأول في السجل، والثاني فوق الثاني، وهكذا. فإن كنت قد حذفت سطورًا أو أعدت ترتيبها في Excel فستكتب المطابقةُ بالموضع قيمًا في السطور الخطأ بصمت.

حين تضيف سجلات جديدة تمامًا امسح المعرّفات

نسخُ سطر مُصدَّر لإنشاء سجل جديد مع إبقاء id فيه يقول للاستيراد «حدِّث السجل صاحب هذا المعرّف» — فتكتب فوق الأصل بدل أن تنشئ شيئًا. أفرغ خلايا id وdetails.id وmasterRowId وsourceLineId في السطور المقصود أن تكون جديدة، وأعطِ السجل الجديد كودًا خاصًا به.

تفاصيل أخرى جديرة بالمعرفة

المرفقات. إن لم تؤشر على تجاهل المرفقات فحقول الملفات تحمل قيمة مثل 4f2c…/contract.pdf وتصل الملفات نفسها في -attachments.zip منفصل. ولاستيراد المرفقات ارفع ذلك الملف المضغوط في حقل المرفقات في النافذة وأبقِ أسماء الملفات في الخلايا.

الأرقام. تُحذف الأصفار الزائدة، فتُصدَّر 100.00 هكذا 100. وهذا شكلي فحسب؛ والقيمة لم تتغير.

الحقول التي لا تراها. إن كان ملف صلاحياتك يخفي حقلًا فإن عموده يُحذف من ملف تصديرك كليًا. ومن الطبيعي أن يحصل مستخدمان يصدّران الشاشة نفسها على ملفين بأعمدة مختلفة.

بضعة حقول غير معتادة — توجيهات المستندات وقيم مدخلات الإعدادات والمعايير النصية — أكبر وأعقد من أن تتسع لها خلية، فتُصدَّر في عمود واحد مضغوط يبدأ عنوانه بـ &. اترك تلك الخلايا كما هي تمامًا؛ فهي تعود صحيحة في الرحلة ذهابًا وإيابًا لكن لا يمكن تحريرها يدويًا.

شكل JSON

اختيار JSON بدل Excel يعطيك المحتوى نفسه لكن ببنية صريحة بدل أن تكون مسطّحة:

{"SalesInvoice": [
  {
    "book": "SalesInvoice$#SINV",
    "code": "SINV0000035",
    "valueDate": "01-02-2024",
    "customer": "10011",
    "subsidiary": { "entityType": "Customer", "code": "10011" },
    "money": { "currency": "KWD", "currencyRate": 1 },
    "details": [
      { "item": { "itemCode": "9999", "item": "9999" },
        "quantity": { "quantity": { "primeQty": { "value": 1, "uom": "SRV" } } },
        "price": { "unitPrice": 100, "netValue": 100 } }
    ]
  }
]}

معرفات الحقول المنقوطة في ورقة Excel تصير كائنات متداخلة — فـ details.item.item في Excel هي details ← item ← item هنا. والزوج #type/#code يصير كائنًا فيه entityType وcode. ومجموعات التفاصيل مصفوفات داخل الهيدر، فلا حاجة إلى عمود ربط.

وصيغة JSON هي الأفضل حين يكون منتج البيانات برنامجًا أو نظامًا آخر، وهي ما تتبادله أدوات استيراد السجلات للذكاء الاصطناعي. أما ما سيحرّره إنسان فاستعمل له Excel.