# مواصفة نقل البيانات — Data Migration Specification
## من الملفات الحالية (Excel/ورقية) إلى منصة سواعد

**الجمهور:** فريق التطوير + منسق داخلي من العميل يُعيَّن "مالك بيانات النقل"
**التوقيت:** تُنفَّذ في المرحلة E قبل التشغيل الموازي، لكن **تجهيز القوالب وتنظيف البيانات يبدأ الآن** — هو المسار الأطول زمنيًا في معظم مشاريع ERP.

---

## 1. المبادئ الملزمة

1. **لا نقل مباشر من ملف خام إلى الإنتاج أبدًا** — المسار الإلزامي: ملف خام ← قالب موحّد ← فحص آلي ← بيئة Staging ← مطابقة ← اعتماد ← إنتاج.
2. **كل كيان يُنقل بمعرّفه الجديد + مرجعه القديم** — عمود `legacy_ref` في كل جدول منقول، للتتبع العكسي عند أي خلاف مستقبلي.
3. **الأرصدة الافتتاحية قيود محاسبية فعلية** بتاريخ بداية التشغيل، لا حقولًا حرة — تخضع لنفس ضوابط التوازن والترحيل.
4. **مالك بيانات واحد لكل نطاق** (موارد بشرية، مالية، مخزون...) يوقّع على صحة بيانات نطاقه قبل وبعد النقل.

## 2. نطاقات النقل وترتيبها (التبعيات حقيقية — الترتيب ملزم)

| # | النطاق | يعتمد على | ملاحظات حرجة |
|---|---|---|---|
| 1 | الشركات والفروع ودليل الحسابات ومراكز التكلفة | — | الأساس المرجعي لكل ما بعده |
| 2 | المشاريع (النشطة + المنتهية خلال آخر سنتين) | 1 | المشاريع المنتهية تُنقل "للقراءة" لأغراض المقارنة والضمانات |
| 3 | الموظفون + عقودهم + أرصدة إجازاتهم + عهدهم | 1، 2 | رصيد الإجازة المرحّل يُعتمد من الموارد البشرية كتابيًا قبل الإدخال |
| 4 | الموردون ومقاولو الباطن والعملاء | 1 | الحسابات البنكية للموردين تُدخل بالتحقق المزدوج نفسه المطبّق في النظام |
| 5 | الأصناف وأرصدة المخزون الافتتاحية | 1، 2 | **جرد فعلي إلزامي قبل النقل** — الرصيد المنقول = رصيد الجرد الموقَّع، لا رصيد الملفات |
| 6 | المعدات وسجل ساعاتها | 1، 2 | |
| 7 | العقود المفتوحة والمستخلصات التراكمية والمحتجزات والدفعات المقدمة | 2، 4 | التراكمي المنقول يجب أن يساوي حسابيًا: مجموع مستخلصات + أوامر تغيير معتمدة |
| 8 | الأرصدة المالية الافتتاحية (ميزان مراجعة) | كل ما سبق | آخر خطوة، وبوابة القبول الأصعب (القسم 4) |

## 3. القوالب الموحدة

لكل نطاق قالب Excel بأعمدة ثابتة (يسلّمها فريق التطوير مبكرًا). قواعد عامة لكل القوالب:
- صف عناوين واحد، لا خلايا مدمجة، لا تنسيقات ألوان تحمل معنى
- التواريخ بصيغة `YYYY-MM-DD` حصريًا، الأرقام بلا فواصل آلاف نصية
- عمود `legacy_ref` إلزامي في كل قالب
- الحقول المرجعية (المشروع، الفرع، الحساب) تُملأ **بالرمز** لا بالاسم الحر — نفس درس تعارض الاسم/المعرّف الذي اكتُشف وأُصلح في النموذج التفاعلي

## 4. الفحوص الآلية (يبنيها فريق التطوير كأوامر Artisan)

| الفحص | يرفض الاستيراد عند |
|---|---|
| مرجعية | أي رمز مشروع/فرع/حساب غير موجود في الجداول الأساسية |
| تفرّد | تكرار رقم هوية موظف، رقم ضريبي مورد، رمز صنف |
| اكتمال | حقل إلزامي فارغ |
| منطقية | تاريخ مباشرة مستقبلي، راتب سالب، رصيد إجازة > الحد النظامي، تراكمي مستخلص > قيمة العقد |
| توازن | ميزان المراجعة الافتتاحي: مجموع مدين ≠ مجموع دائن (رفض فوري) |

مخرَج كل فحص: تقرير أخطاء بصف/عمود/سبب يعود لمالك البيانات للتصحيح — **التصحيح في الملف المصدر، لا يدويًا في قاعدة البيانات**.

## 5. بوابة القبول النهائية للنقل

- [ ] ميزان مراجعة النظام الجديد = ميزان المراجعة الختامي القديم (تطابق تام، صفر فرق)
- [ ] عيّنة عشوائية 20 موظفًا: الراتب والرصيد والعهدة مطابقة للملفات الموقعة
- [ ] عيّنة 20 صنفًا: رصيد النظام = رصيد الجرد الفعلي الموقّع
- [ ] لكل عقد مفتوح: (تراكمي المستخلصات + المحتجز + المقدم) متسقة حسابيًا مع قيمة العقد
- [ ] توقيع مالك البيانات لكل نطاق على محضر مطابقة

## 6. ما يبدأ به العميل اليوم (دون انتظار المطورين)

1. تعيين مالك بيانات لكل نطاق من الثمانية
2. حصر مصادر البيانات الحالية (أي ملفات، أي إصدارات، من يملك أحدث نسخة)
3. بدء تنظيف أكثر نطاقين فوضى عادةً: **الموظفون** (ازدواج سجلات، إقامات منتهية غير محدثة) و**الأصناف** (نفس الصنف بثلاثة أسماء مختلفة)
4. جدولة الجرد الفعلي للمخزون قريبًا من تاريخ النقل المستهدف