نظرة عامة

# PetroNet System **منصة متكاملة لمراقبة وإدارة الوقود في منغوليا** **PetroNet** تجمع استيراد المنتجات النفطية وتخزينها وتوزيعها وبيعها بالتجزئة في منغوليا ضمن تدفق بيانات واحد، وتراقبه في الزمن الحقيقي، وتعطي الجهة المنظِّمة وشركات الوقود والسائق الأرقام نفسها. النظام مبني لهيئة الموارد المعدنية والنفط (AMGTG) ويحل محل نظام **mpetro** الحالي — انظر [متطلبات النظام](https://plan.petronet.mn/). PetroNet System **ليس تطبيقًا واحدًا، بل منظومة**. السائق والمحطة وشركة الوقود والجهة المنظِّمة يؤدون أربعة أعمال مختلفة، ولكلٍّ منصة مبنية لعمله. وتحتها جميعًا مجموعة بيانات واحدة، وهوية واحدة، وسجل تدقيق واحد.

Монгол  ·  العربية  ·  中文  ·  English  ·  Français  ·  Русский  ·  Español

---

## المشكلة في منغوليا أكثر من 200 شركة وقود، وأكثر من 110 مستودعات، وأكثر من 1500 محطة تعبئة. بياناتها موجودة في نظامين لا يتحدثان إلى بعضهما، ومعظمها يُدخل **يدويًا**، مرة أو مرتين في الأسبوع. لا يوجد مكان واحد يستطيع أن يجيب، الآن، عن عدد اللترات من كل نوع وأين هي. لذلك يُدار الاحتياطي الوطني بالتقدير، وحين يضيق العرض لا تبقى إلا أدوات فجّة — أيام اللوحات الزوجية والفردية، وسقف موحّد قدره 50,000 توغريك لكل تعبئة، والطوابير. هذه ليست مشكلة إمداد فحسب، بل مشكلة معلومات — وهذا بالضبط نوع المشكلات التي تستطيع البرمجيات حلّها فعلًا. ## ماذا تفعل المنصة

		الصفحة العامة
1	سلسلة العهدة — عقد الاستيراد ← الجمارك ← المختبر ← المستودع ← النقل ← خزان المحطة ← الفوهة ← المستهلك. كل لتر يُتتبَّع رجوعًا إلى دفعته.	/supply
2	نقطة بيع للمحطات — طبقة تعريفات تتحدث إلى المضخات ومقاييس الخزانات من أي صانع، من وحدة تحكّم حديثة إلى عدّاد نبضات، وتواصل البيع عند انقطاع الشبكة.	/stations
3	القسائم — استحقاقات تُنشأ فقط من وقود وصل فعليًا، ثم توزَّع حسب القرب والحاجة ومدة الانتظار.	/vouchers
4	الرقابة الحكومية — المخزون والسعر والجودة والضرائب والفروق على لوحة واحدة، فوق سجل تدقيق لا يمكن إعادة كتابته.	/oversight

تعمل المنصة بوضعين على بنية تحتية واحدة. في الأزمة توزِّع بالحصص: تتغير الحدود والحصص خلال دقائق، وتحتفظ الفئات ذات الأولوية باحتياطيها، وتصدر القسائم بنافذة زمنية. وفي بقية الوقت تراقب: متابعة الضرائب والأسعار والجودة والمخزون، ومطابقة آلية بين الاستيراد والتخزين والبيع، وتنبؤ بالطلب، وإنذارات للاحتياطي الاستراتيجي. ## المنظومة

المنصة	لمن	ماذا تحمل
منصة المواطن	السائقون والمواطنون	أقرب محطة وأنواعها ومستوى مخزونها والاستحقاق اليومي والقسيمة. الهوية من eID
بوابة الشركات	شركات الوقود	سجل المستودعات والمحطات، أرصدة الخزانات، وتقديم تقارير كل فترة وتصحيحها
مركز قيادة الجهة المنظِّمة	AMGTG والمفتشون	التجميع اليومي الوطني، وأيام المخزون، وفجوات التغطية، وفروق المطابقة، والتنبيهات
نقطة البيع ووكيل الحافة في المحطة	محطات التعبئة	الفوهات والخزانات والورديات والدفع والإيصالات فوق قاعدة محلية: البيع لا يتوقف بتوقف الشبكة
مستودع البيانات والتحليلات	المحللون والإدارة	تغذية يومية من الأنظمة التشغيلية، وتنظيف، ونمذجة بلغة الأعمال، مع ذكاء الأعمال والتنبؤ
وحدة التحكّم والمراقبة	المشغّلون	المؤسسات والصلاحيات والتدقيق خلف تسجيل دخول خاص، إلى جانب المقاييس والتنبيهات والنسخ الاحتياطي

تحتها جميعًا ملف Go تنفيذي واحد وقاعدة بيانات واحدة وهوية واحدة: المنظومة هنا تعني مساحات عمل كثيرة لا خوادم كثيرة. وإلى الخارج ترتبط بالجمارك والسجل الحكومي و e-Barimt و eID ومقاييس الخزانات في الميدان. ## قرار التصميم > **القسيمة ليست وعدًا، بل لتر محجوز.** لا توجد القسيمة إلا بعد أن يدخل الوقود فعليًا خزان المحطة ويؤكد مقياس الخزان الآلي ارتفاع المستوى. ينتج عن ذلك أمران. لا يستطيع النظام أن يعد بأكثر مما يملك، فلا يبقى للطابور ما يتشكل حوله. والمحطة التي لا تُبلِّغ عن توريداتها لا تولّد أي قسيمة، فلا يُرسَل إليها أحد — الامتثال يفرضه التصميم لا المفتّش. ## سلسلة العهدة

المرحلة	ما يُسجَّل	المصدر
الاستيراد	العقد، المورّد، النوع، الحمولة، شروط التسليم، السعر، التاريخ المتوقع	بوابة المستورد / API
الحدود	رقم البيان، رمز النظام المنسق، الرسوم، منفذ العبور	الجمارك
الجودة	الأوكتان، الكثافة، الكبريت، الماء، شهادة المختبر	مختبر معتمد
القياس	اللترات المرصودة، الحرارة، الكثافة ← اللترات عند 15 °م	ASTM D1250 / API MPMS 11.1
المستودع	الخزان، السعة، المستوى، السعة الحرة، المنقول إلى الاحتياطي الحكومي	مقاييس الخزانات
النقل	الصهريج، السائق، الكمية المحمَّلة، الوجهة، مسار GPS، الختم الإلكتروني	وحدة الناقل
المحطة	الكمية المستلمة، ارتفاع المستوى، الفرق، الموظف المستلم	مقياس الخزان + تأكيد
الفوهة	العدّاد التراكمي، اللترات والمبلغ لكل معاملة، قراءات الورديات	وحدة تحكّم الساحة
المستهلك	الاستحقاق، القسيمة، الصرف، الإيصال، ضريبة القيمة المضافة	PetroNet + e-Barimt

كل عقدة تُطابَق مع سابقتها، فيدل الفرق مباشرة على متى وأين وفي عهدة من ظهر. ## ما هو منجز بالفعل هذه ليست خطة بل سجل لما هو موجود في المستودع، مغطّى باختبارات ومُشغَّل على PostgreSQL حقيقي. القائمة الكاملة وما يليها في [خطة التطوير](https://plan.petronet.mn/plan/). - سجل المستودعات والمحطات، اللوحات، الحالة، التحقق عبر XYP - دليل المنتجات بتصنيف JODI، سبعة أنواع - صلاحيات الجهة المنظِّمة، وخلفها سياسة على مستوى الصفوف - السياسة كبيانات — الحدود والتفاوتات والمواعيد، قابلة للتغيير دون إصدار - الجرد الفني للمحطات (الفئات A–D) - فترات التقارير والتقديمات والبنود والاستنتاجات - قواعد التحقق — التوازن، الاستمرارية، السعة، الانحراف، القياس - تصحيح الحجم عند 15 °م (ASTM D1250 / API MPMS 11.1) - إصدارات التقارير وسلسلة تجزئة فوقها - تصدير واستيراد قوالب Excel - مسار المراجعة — الاعتماد، الإعادة، مبدأ الأربع أعين - الحركات، مع اللوحة وحالة الإغلاق والفرق - التجميع اليومي الوطني، والتغطية، وأيام المخزون المتبقية - كشف البيانات غير الواردة وتقرير فجوات التغطية - المطابقة ΔA–ΔE - سبعة تقارير بصيغتي Excel و CSV، مجدولة وتُرسل بالبريد - بيانات مفتوحة: التجميع اليومي الوطني على `/api/v1/petro/public/daily` - شاشة تقارير الشركات وشاشة الجهة المنظِّمة ## كيف بُني PetroNet هو **توزيعة من المستوى الثاني** لمنصة [Gerege Nexus](https://github.com/gerege-systems/open-gerege-nexus). لا يوجد كود للنواة في هذا المستودع — سطر واحد في `go.mod` هو كل الأمر. ما يعيش هنا هو منطق أعمال الوقود (`modules/petro/`) وما بُني له من خريطة وشاشات تشغيل وصفحات عامة (`frontend/`). تسجّل الوحدة مساراتها وقوائمها وصلاحياتها وترحيلاتها عبر عقد `pkg/nexus` العام، وتُجمَّع في ملف Go تنفيذي واحد. أما الهوية وتعدد المستأجرين و RBAC و SSO والتقارير وسجل التدقيق فتأتي من المنصة ولا تُعاد كتابتها هنا. هذه العملية تتحقق من الأشخاص بنفسها: تسجيل دخول خاص بها، ومُصدِر OIDC خاص، وقاعدة بيانات خاصة. ويُعرَّف المواطنون عبر [eID Mongolia](https://eidmongolia.mn) بدل كلمة مرور كان على هذا النظام حفظها. ## بنية المستودع

main.go                   يسجّل وحدة petro ويشغّل مضيف المنصة
modules/petro/            وحدة الوقود: السجل، التقارير، الرقابة، القسائم
  migrations/             SQL هذه الوحدة، تاريخ واحد
cmd/petro-import/         مستورد لبيانات mpetro الحالية
catalog/                  كتالوج التطبيقات والبيانات الوصفية وسجل الإصدارات
frontend/                 عميل الويب بـ Next.js — الموقع العام والخريطة وشاشات التشغيل
deploy/                   Dockerfile وحزمة compose والمراقبة وسكربتات النسخ الاحتياطي
nginx/                    المضيفات الافتراضية الستة لهذه العملية
docs/                     هذا التوثيق، بسبع لغات

## البدء المتطلبات: Go 1.26+ و Node.js 20+ و PostgreSQL 16+ (أو Docker).

# كل شيء دفعة واحدة
docker compose -f deploy/docker-compose.yml up -d

# أو واجهة البرمجة وحدها
go run .

# وعميل الويب
cd frontend && npm ci && npm run dev

يستجيب عميل الويب على [http://localhost:3000](http://localhost:3000). أي نشر بلا مؤسسة بعد يوجّه كل زائر إلى `/setup`. والرمز الذي يطلبه هذا المعالج يُكتب مرة واحدة في سجل واجهة البرمجة عند الإقلاع:

docker logs petronet2_backend 2>&1 | grep -i "setup token"

## الإعداد القائمة الكاملة في [`.env.example`](https://github.com/gerege-systems/petronet-gerege-nexus/blob/main/.env.example). والقيم التي تحدد سلوك أي عملية نشر:

المتغيّر	الوصف
PUBLIC_ORIGIN	أين تستجيب هذه النسخة. يحدد في مكان واحد CORS ومُصدِر OIDC وعنوان عودة eID
PETRONET_POSTGRES_PASSWORD	قاعدة البيانات الخاصة بهذه الحزمة
SSO_DEFAULT_CLIENT_SECRET	بدونه ترفض المنصة الإقلاع في بيئة الإنتاج
BRAND_*	اسم عملية النشر ووصفها وألوانها وأيقوناتها
SERVICE_URL_*	عناوين وحدة التحكّم ومستودع البيانات والنسخ الاحتياطي والمراقبة والتوثيق. لا تُرسم في الصفحة الرئيسية إلا المضبوطة منها
EID_RP_UUID / EID_RP_SECRET	زوج الطرف المعتمِد لـ eID. بدونه لا يتوفر الدخول عبر eID
CONTROL_PLANE_HOST	اسم المضيف الذي تستجيب عليه وحدة تحكّم المشغّل، ولا شيء غيره
PROMETHEUS_URL	من أين تقرأ وحدة التحكّم صحة المنصة

## النشر يحمل مضيف الإنتاج `/opt/petronet-v2/` — `src/` (نسخة git من هذا المستودع) و `.env` (chmod 600) و `brand/`. لا أحد يشغّل `git pull` هناك: الطريق الوحيد إلى الإنتاج هو git → CI → الـ runner المستضاف ذاتيًا على المضيف:

commit → PR → main → CI (ci.yml) ✓ → Deploy (deploy.yml)
  → self-hosted runner: deploy/ci-deploy.sh <sha>   # git reset --hard <sha>
  → ./deploy.sh                                     # build, migrate, verify, rollback

يبني `deploy.sh` صورتي الخلفية والويب من هذا المستودع معًا، فتصدر واجهة البرمجة والخريطة وشاشات التشغيل دائمًا بمراجعة واحدة. تقف ستة أسماء مضيفات جنبًا إلى جنب: المنصة (`petronet.mn`)، ووحدة تحكّم المشغّل (`admin.`)، والمراقبة (`monitor.`)، وخريطة مستودع البيانات (`dwh.`)، وهذا التوثيق (`docs.`)، وملاحظات النسخ الاحتياطي (`backups.`). ما هو كل منها، وما مزالق إعداد nginx، مشروح في [وثيقة هذه العملية](deployment.md). ## الاختبارات

go vet ./... && go test -race ./...     # Go: وحدات وتكامل مع PostgreSQL
cd frontend && npm test && npm run build

يشغّل التكامل المستمر كليهما مع كل دفعة وكل طلب سحب، ويبني صورتي Docker. ## الأمان - رموز الجلسة قيم عشوائية بطول 256 بت، ولا يُخزَّن منها إلا ملخّص SHA-256. - تُشفَّر كلمات المرور بـ bcrypt، ومحاولات الدخول محدودة بمعدل. - تُعزَل بيانات كل مؤسسة بدور في قاعدة البيانات وسياق مستأجر وأمان على مستوى الصفوف في الجداول المعلنة. ونطاق الجهة المنظِّمة سياسة في SQL لا فحص داخل معالج. - إصدارات التقارير مترابطة بالتجزئة، فلا يمكن تعديل تقديم معتمد دون أن تُظهر السلسلة ذلك. - لوحدة تحكّم المشغّل هوية وكوكيز وسجل تدقيق ودور قاعدة بيانات خاص بها، ولا تستجيب إلا على `CONTROL_PLANE_HOST`. أبلغ عن الثغرات كما هو موضّح في [`SECURITY.md`](security.md). ## فهرس التوثيق

الوثيقة	الوصف
مركز التوثيق	كل الوثائق والترجمات
متطلبات النظام	ما طلبه العميل
خطة التطوير	ما أُنجز وما يليه ومعايير القبول
المقارنات الدولية	كيف حلّت دول أخرى المسألة وما الذي أخفق
هذه العملية	أسماء المضيفات والمنافذ والنسخ — هذا المضيف فقط
البنية	المستويات والمخططات وعزل البيانات
كتابة وحدة	عقد pkg/nexus
التشغيل	النشر والمراقبة والنسخ والاستعادة
أدلة التشغيل	حين يتعطل شيء
الترجمة	سياسة اللغات والمولّد
المساهمة · الأمان · قواعد السلوك	قواعد المشروع

---

## الترخيص حقوق النشر (c) 2026 **Gerege Systems Development Team, Gerege Nomadica Foundation**. يوزَّع بموجب رخصة Apache 2.0 — انظر [`LICENSE`](https://github.com/gerege-systems/petronet-gerege-nexus/blob/main/LICENSE). أيقونات الأعلام من [Flaticon](https://www.flaticon.com/) ([الإسناد](https://github.com/gerege-systems/petronet-gerege-nexus/blob/main/docs/assets/icons/ATTRIBUTION.md)).