Монгол العربية

中文

English

Français

Русский

Español

Gerege Nexus

منصة متكاملة للعمليات الرقمية

Gerege Nexus منصة معيارية مفتوحة المصدر تربط الخدمات والعمليات والأنظمة والبيانات عبر المؤسسات العامة والخاصة. تضع اللغة المنغولية في المقام الأول، وتتكامل مباشرة مع البنية التحتية الرقمية الوطنية في منغوليا (DAN و E-ID و XYP / ХУР).

كلمة Nexus تعني نقطة الاتصال: حيث تلتقي المؤسسات والخدمات وسير العمل والأنظمة والمستخدمون والبيانات. المنصة نفسها ليست مرتبطة بقطاع واحد — الوحدات التي تعمل فوقها هي ما يحدد طبيعة كل عملية نشر.

تُجمَّع الوحدات في ملف تنفيذي واحد بلغة Go، بينما يقرر متجر تطبيقات مدعوم بـ PostgreSQL أي التطبيقات مفعَّلة لكل مستأجر — فصل معياري دون قفزات الشبكة أو الكلفة التشغيلية للخدمات المصغَّرة.

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

المؤلفون

المساهم	الدور
Gerege Systems Development Team (@gerege-systems)	البنية المعمارية، نواة المنصة
Gemini AI	توليد الشيفرة، التوثيق
Claude AI	تحليل الشيفرة، تدقيق الأمان

القدرات الأساسية

١. نواة معيارية أحادية عالية الأداء

وحدات Go مُجمَّعة وقت البناء — contacts و products و inventory و billing و documents و sso_clients تُجمَّع في ملف تنفيذي واحد وتُستدعى داخل العملية نفسها.
متجر تطبيقات لكل مستأجر — صلاحيات التطبيقات والقوائم و RBAC تُدار من PostgreSQL (app_installations).
محلِّل التبعيات — حل تكراري على رسم بياني موجَّه لا دوري، مع كشف الدورات والتحقق من قيود semver.
مزامنة الفهرس — catalog/apps.json هو المصدر الوحيد للحقيقة، ويُوفَّق جدول apps معه عند كل إقلاع.

٢. محرك مرونة سحابي المنشأ

الوحدة	الغرض
`resilience/breaker.go`	قاطع دائرة تكيُّفي على نهج SRE في Google
`resilience/loadshedder.go`	إسقاط الحمل بـ `503` + `Retry-After` عند الضغط
`resilience/singleflight.go`	دمج العمل المكرَّر الجاري تنفيذه
`resilience/retry.go`	إعادة المحاولة بتراجع أُسّي

٣. البنية التحتية الرقمية الوطنية

XYP — تبادل معلومات الدولة (platform/gerege/xyp.go): السجل المدني للمواطنين (WS100101) والتحقق من الكيانات الاعتبارية (WS100201).
الهوية الرقمية الوطنية E-ID و DAN (developer.gerege.mn، eidmongolia.mn) — توقيع رقمي بالبنية التحتية للمفاتيح العامة، ورمز لمرة واحدة عبر الهاتف، ودخول موحَّد مصرفي، وتحقق بيومتري من الوجه.
مزوِّد OAuth2 / OIDC مدمج (/.well-known/openid-configuration) يُصدر رموز client-credentials للأنظمة الخارجية.
تأكيد البريد الإلكتروني (platform/emailverify) — مسار موحَّد لإثبات ملكية عنوان، تستدعيه كل وحدات التطبيقات داخل العملية. ترسل الرسالة الخدمة المستضافة (enigma.mn)، فلا تحتفظ المنصّة بأي بيانات اعتماد بريد ولا تملك عنوان مُرسِل. يُسجَّل التأكيد عند عودة الشخص، وتعمل تلك العودة مرة واحدة فقط. يظهر في الإعدادات ← تأكيد البريد الإلكتروني.

ملاحظة. وضع المحاكاة لـ E-ID و DAN و XYP هو تسهيل للتطوير فقط. مع ENVIRONMENT=production يُعطَّل تلقائيًا، فلا يمكن مطلقًا لرقم تسجيل مُلفَّق أن يجتاز المصادقة.

٤. مساعد الذكاء الاصطناعي والتحليلات

المساعد الذكي (platform/ai/copilot.go) — محادثة مُصنَّفة حسب النية وموصولة ببيانات المستأجر الحية.
متنبئ الطلب على المخزون (platform/ai/inventory_forecaster.go) — توصيات لمخزون الأمان ونقطة إعادة الطلب انطلاقًا من حركة المخزون التاريخية.

تطبيقات الأعمال

#	التطبيق	المعرِّف	المسار	الوصف
١	المؤسسة والأشخاص	`io.gerege.nexus.organisation`	`/organisation`	الأقسام والعاملون فيها. تُثبَّت افتراضيًا لكل مستأجر جديد ويمكن إزالتها؛ أما الهوية القانونية للمؤسسة فليست تطبيقًا بل جزء من المنصة
٢	الربط بالحكومة الإلكترونية	`io.gerege.nexus.egov`	`/egov`	استعلامات ХУР عن الأفراد والكيانات الاعتبارية، وحالة قناتي eID و ДАН، وسجل الاستعلامات. تُثبَّت افتراضيًا ويمكن إزالتها
٣	جهات الاتصال	`io.gerege.nexus.contacts`	`/contacts`	دليل العملاء والمورِّدين مع تعبئة تلقائية من XYP
٤	المنتجات	`io.gerege.nexus.products`	`/products`	الفهرس والتسعير ووحدات SKU لكل مستأجر
٥	المخزون	`io.gerege.nexus.inventory`	`/inventory`	المستودعات ومستويات المخزون وسجل الحركة
٦	الفوترة و e-Barimt	`io.gerege.nexus.billing`	`/billing`	إصدار الفواتير، ضريبة ١٠٪، إيصالات e-Barimt
٧	المستندات الرقمية والتوقيع الإلكتروني	`io.gerege.nexus.documents`	`/documents`	توجيه المستندات والتوقيعات والموافقات
٨	عملاء SSO	`io.gerege.nexus.sso_clients`	`/sso-clients`	تسجيل عملاء OAuth2 للأنظمة التي تُسجّل دخول المستخدمين عبر هذه المنصة

لا تُفتح المسارات إلا بعد تثبيت التطبيق وتفعيله للمستأجر؛ وإلا فإن البوابة تُعيد 403 Forbidden.

بنية المستودع

backend/
  cmd/api/            خادم واجهة HTTP البرمجية (+ بيانات العرض التجريبي)
  cmd/migrate/        مُنفِّذ ترحيلات Goose
  db/migrations/      ترحيلات SQL
  internal/
    module.go         عقد وحدة Go
    apps/             وحدات الأعمال
    platform/         خدمات نواة المنصة
frontend/             عميل الويب Next.js 16 (App Router)
catalog/              فهرس متجر التطبيقات وبياناته الوصفية
deploy/               Dockerfile الإنتاج وإعدادات Nginx
docs/                 التوثيق والترجمات

البدء

المتطلبات المسبقة

Go 1.26+
Node.js 20+
PostgreSQL 16+ (أو Docker Compose)

١. Docker Compose

docker compose up -d

تعمل الترحيلات في خدمة migrate مخصَّصة تعمل لمرة واحدة قبل بدء الواجهة البرمجية.

٢. يدويًا

الواجهة الخلفية:

cd backend
go mod download
DATABASE_URL="postgres://postgres:postgrespassword@localhost:5432/platform_db?sslmode=disable" \
  go run ./cmd/migrate up
go run ./cmd/api

الواجهة الأمامية:

cd frontend
npm ci
npm run dev

افتح http://localhost:3000.

بيانات الدخول التجريبية

الحقل	القيمة
البريد الإلكتروني	`admin@example.com`
كلمة المرور	`Password123!`
المستأجر	`Demo Corporation` (`slug: demo`)

يُنشأ حساب العرض التجريبي خارج بيئة الإنتاج فقط. أما في الإنتاج فلا يُنشأ إلا عند ضبط SEED_DEMO_DATA=true صراحةً.

النشر الآلي

كل دفع إلى main يُشغِّل deploy.yml:

١. بناء صور الواجهة الخلفية والأمامية ورفعها إلى GHCR (:latest و :<sha>).

٢. نسخ docker-compose.prod.yml إلى الخادم.

٣. كتابة ملف .env على الخادم من أسرار GitHub وسحب الصور.

٤. تشغيل الترحيلات حتى اكتمالها، ثم تبديل الواجهة البرمجية والواجهة الأمامية.

٥. فحص /health و /ready، وطباعة سجلات الحاويات وإفشال التشغيل إذا لم يكن النشر سليمًا.

للنشر يدويًا: Actions ← Deploy to Production ← Run workflow، مع إمكانية تثبيت وسم صورة محدَّد.

الأسرار المطلوبة في المستودع:

السر	مطلوب	الوصف
`DEPLOY_SSH_KEY`	نعم	المفتاح الخاص لمستخدم النشر. بدونه يُتخطَّى النشر
`POSTGRES_PASSWORD`	نعم	كلمة مرور قاعدة البيانات على الخادم
`SSO_DEFAULT_CLIENT_SECRET`	نعم	إلزامي لعميل OAuth2 المدمج في الإنتاج
`DEPLOY_HOST` / `DEPLOY_USER` / `DEPLOY_PORT`	لا	الافتراضي `nexus.gerege.mn` / `deploy` / `22`
`PUBLIC_ORIGIN`	لا	الافتراضي `https://nexus.gerege.mn`

نطاق الإنتاج هو nexus.gerege.mn، الذي حلَّ محل openerp.gerege.mn عند إعادة التسمية إلى Gerege Nexus. يحدِّد PUBLIC_ORIGIN في موضع واحد سياسة CORS ومُصدِر OIDC وعنوان استدعاء eID، لذا فإن تغييره يستتبع معه DNS وشهادة TLS وكل عميل ثبَّت المُصدِر لديه.

لا يحتاج الخادم سوى Docker — دون شيفرة مصدرية ودون أدوات Go/Node. راجع deploy/.env.prod.example للاطلاع على القيم.

الإعدادات

راجع .env.example للقائمة الكاملة.

المتغيِّر	الافتراضي	الوصف
`DATABASE_URL`	localhost	سلسلة الاتصال بـ PostgreSQL
`PORT`	`8080`	منفذ استماع الواجهة البرمجية
`ENVIRONMENT`	`development`	القيمة `production` تُفعِّل الإعدادات المُشدَّدة
`APP_CATALOG_PATH`	`catalog/apps.json`	مسار فهرس متجر التطبيقات
`ALLOWED_ORIGINS`	`http://localhost:3000`	قائمة المصادر المسموح بها (CORS)
`TRUST_PROXY_HEADERS`	`false`	هل يُوثَق بترويسة `X-Forwarded-For`
`SEED_DEMO_DATA`	مُفعَّل خارج الإنتاج	إنشاء حساب العرض التجريبي
`SSO_DEFAULT_CLIENT_SECRET`	—	مطلوب في الإنتاج
`EID_MOCK_MODE` / `DAN_MOCK_MODE` / `XYP_MOCK_MODE`	مُفعَّل خارج الإنتاج	محاكاة التكاملات الوطنية

نظرة عامة على الواجهة البرمجية

الطريقة	المسار	الوصف
`GET`	`/health`, `/ready`	فحوص الحياة والجاهزية
`GET`	`/metrics`	مقاييس Prometheus
`POST`	`/api/v1/auth/login`	تسجيل الدخول بالبريد وكلمة المرور
`POST`	`/api/v1/auth/eid/login`	تسجيل الدخول بالهوية الرقمية الوطنية
`POST`	`/api/v1/auth/dan/login`	تسجيل الدخول عبر بوابة DAN
`POST`	`/api/v1/auth/logout`	إبطال الجلسة
`GET`	`/api/v1/menus`	قوائم التطبيقات المفعَّلة للمستأجر
`GET`	`/api/v1/store/apps`	قائمة متجر التطبيقات
`POST`	`/api/v1/store/apps/{slug}/install`	تثبيت تطبيق (مسؤول)
`POST`	`/api/v1/verify/send`	طلب رابط تأكيد البريد من الخدمة المستضافة
`GET`	`/api/v1/verify/landed`	استقبال من أكّد عنوانه — يعمل مرة واحدة فقط
`GET`	`/api/v1/admin/email-verification/overview`	سجل التأكيدات وحالة الخدمة (مسؤول)
`POST`	`/oauth2/token`	رمز OAuth2 من نوع client credentials

تنتقل رموز الجلسة إما في ملف تعريف ارتباط HttpOnly أو عبر Authorization: Bearer <token>.

الاختبارات وضوابط الجودة

# اختبارات وحدات الواجهة الخلفية مع كاشف التسابق
cd backend && go test -race ./...

# التحليل الساكن
cd backend && go vet ./... && golangci-lint run

# فحص الثغرات
cd backend && govulncheck ./...

# بناء الواجهة الأمامية
cd frontend && npm run build

تُشغِّل منظومة التكامل المستمر الفحص اللغوي والاختبارات وبناء الواجهة الأمامية وبناء صورة Docker و govulncheck و gosec عند كل دفع وكل طلب دمج.

الأمان

رموز الجلسة قيم عشوائية بطول ٢٥٦ بت، ولا يُخزَّن منها سوى بصمة SHA-256.
تُجزَّأ كلمات المرور باستخدام bcrypt، ومحاولات تسجيل الدخول محدودة المعدل لكل عنوان IP.
يتطلب تثبيت التطبيقات أو تفعيلها أو تعطيلها وتسجيل التكاملات صلاحيات مسؤول المستأجر.
تستخدم مصادقة عملاء OAuth2 مقارنة ذات زمن ثابت.

أبلغ عن الثغرات وفق ما هو موضَّح في SECURITY.md.

فهرس التوثيق

المستند	الوصف
مركز التوثيق	فهرس كل المستندات والترجمات
مواصفات البنية المعمارية	طبقات المنصة وقرارات التصميم
دليل تأليف الوحدات	كيفية بناء وحدة تطبيق جديدة
المساهمة	سير عمل المساهمة
سياسة الأمان	الإبلاغ عن الثغرات
مدونة السلوك	معايير المجتمع
سجل التغييرات	تاريخ الإصدارات

الشكر ومصادر الإلهام

١. snykk/go-rest-boilerplate من @snykk — أسس واجهة REST البرمجية بلغة Go.

٢. Odoo — متجر التطبيقات المعياري ونموذج التبعيات.

٣. go-zero — محرك المرونة السحابي المنشأ.

الترخيص

أيقونات الأعلام من Flaticon (بيان الإسناد).