نظرة عامة

# 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 مُجمَّعة وقت البناء** — يحمل النواة `sso_clients` فقط. تسجل توزيعات المنتجات وحداتها عبر عقد `pkg/nexus` العام في الملف التنفيذي النهائي، وتُستدعى داخل العملية نفسها. - **متجر تطبيقات لكل مستأجر** — صلاحيات التطبيقات والقوائم و RBAC تُدار من PostgreSQL (`app_installations`). - **محلِّل التبعيات** — حل تكراري على رسم بياني موجَّه لا دوري، مع كشف الدورات والتحقق من قيود semver. - **مزامنة الفهرس** — يجلب الإنتاج فهرسًا موقّعًا من `APP_CATALOG_URL`؛ ويستخدم التطوير/العمل دون اتصال `catalog/apps.json` كبديل، ثم يزامن البيانات في `platform.apps`. ### ٢. المرونة السحابية وتعدد النسخ

الوحدة	الغرض
`internal/kernel/resilience/loadshedder.go`	إسقاط الحمل بـ `503` + `Retry-After` عند الضغط
`internal/kernel/cache/bus.go`	إبطال الذاكرة المخبأة بين النسخ عبر Redis مع بديل محلي
`internal/kernel/memo/memo.go`	ذاكرة محلية قصيرة الأجل تُبطل بالبادئة لقرارات التفويض
`internal/kernel/async/async.go`	goroutines مسماة مع استرداد panic وتسجيل المكدس

### ٣. البنية التحتية الرقمية الوطنية - **XYP — تبادل معلومات الدولة** (`internal/workspace/identity/gerege/xyp.go`): السجل المدني للمواطنين (`WS100101`) والتحقق من الكيانات الاعتبارية (`WS100201`). - **الهوية الرقمية الوطنية E-ID و DAN** ([`developer.gerege.mn`](https://developer.gerege.mn)، [`eidmongolia.mn`](https://eidmongolia.mn)) — توقيع رقمي بالبنية التحتية للمفاتيح العامة، ورمز لمرة واحدة عبر الهاتف، ودخول موحَّد مصرفي، وتحقق بيومتري من الوجه. - **مزوِّد OAuth2 / OIDC مدمج** (`/.well-known/openid-configuration`) يُصدر رموز client-credentials للأنظمة الخارجية. - **تأكيد البريد الإلكتروني** (`internal/workspace/emailverify`) — مسار موحَّد لإثبات ملكية عنوان، تستدعيه كل وحدات التطبيقات داخل العملية. ترسل الرسالة الخدمة المستضافة (`enigma.mn`)، فلا تحتفظ المنصّة بأي بيانات اعتماد بريد ولا تملك عنوان مُرسِل. يُسجَّل التأكيد عند عودة الشخص، وتعمل تلك العودة مرة واحدة فقط. يظهر في الإعدادات ← تأكيد البريد الإلكتروني. > **ملاحظة.** وضع المحاكاة لـ E-ID و DAN و XYP هو تسهيل للتطوير فقط. مع > `ENVIRONMENT=production` يُعطَّل تلقائيًا، فلا يمكن مطلقًا لرقم تسجيل مُلفَّق > أن يجتاز المصادقة. ### ٤. مساعد الذكاء الاصطناعي والتحليلات - **المساعد الذكي** (`internal/workspace/ai/copilot.go`) — محادثة مُصنَّفة حسب النية وموصولة ببيانات المستأجر الحية. - **واجهة توقع المخزون** (`internal/workspace/ai/handlers.go`) — تفوض إلى قدرة `stock_forecast` في توزيع مفعّل وتعيد `404` عند عدم وجود مزود. --- ## تطبيقات الأعمال يحتوي هذا المستودع الأساسي على تطبيق واحد فقط في `catalog/apps.json`. تسجّل توزيعات المنتجات وحداتها وترحيلاتها الخاصة عبر `pkg/nexus`؛ ولا تُعدّ تطبيقاتها ميزات موجودة في هذا المستودع.

#	التطبيق	المعرِّف	المسار	الوصف
١	عملاء SSO	`io.gerege.nexus.sso_clients`	`/sso-clients`	تسجيل عملاء OAuth2 للأنظمة التي تُسجّل دخول المستخدمين عبر هذه المنصة

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

backend/
  cmd/api/            خادم واجهة HTTP البرمجية (+ بيانات العرض التجريبي)
  cmd/migrate/        مُنفِّذ ترحيلات Goose
  db/migrations/      ترحيلات SQL
  internal/
    kernel/           عناصر تقنية مشتركة بين المستويين
    tenant/           العمل الخاص بمنظمة واحدة
    platform/         تشغيل النشر بأكمله
    apps/             الوحدات التي يحملها هذا التوزيع
  pkg/
    nexus/            SDK عام وعقود للوحدات الخارجية
    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](http://localhost:3000). ### بيانات الدخول التجريبية

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

يُنشأ حساب العرض التجريبي خارج بيئة الإنتاج فقط. أما في الإنتاج فلا يُنشأ إلا عند ضبط `SEED_DEMO_DATA=true` صراحةً. --- ## النشر الآلي كل دفع إلى `main` يُشغِّل [`deploy.yml`](https://github.com/gerege-systems/open-gerege-nexus/blob/main/.github/workflows/deploy.yml): ١. بناء صور الواجهة الخلفية والأمامية ورفعها إلى GHCR (`:latest` و `:`). ٢. نسخ `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`](https://github.com/gerege-systems/open-gerege-nexus/blob/main/deploy/.env.prod.example) للاطلاع على القيم. --- ## الإعدادات راجع [`.env.example`](https://github.com/gerege-systems/open-gerege-nexus/blob/main/.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/platform/v1/email-verifications`	سجل التأكيدات وحالة الخدمة (وحدة التحكم)
`POST`	`/oauth2/token`	رمز OAuth2 من نوع client credentials

تنتقل رموز الجلسة إما في ملف تعريف ارتباط HttpOnly أو عبر `Authorization: Bearer `. --- ## الاختبارات وضوابط الجودة

# اختبارات وحدات الواجهة الخلفية مع كاشف التسابق
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`](security.md). --- ## فهرس التوثيق

المستند	الوصف
مركز التوثيق	فهرس كل المستندات والترجمات
البنية المعمارية	المستويان، المخططات الثلاثة، وعزل البيانات
كتابة وحدة	عقد `pkg/nexus` وكيف يصل التطبيق إلى النشر
المساهمة	سير عمل المساهمة
سياسة الأمان	الإبلاغ عن الثغرات
مدونة السلوك	معايير المجتمع
سجل التغييرات	تاريخ الإصدارات

## الشكر ومصادر الإلهام ١. **[snykk/go-rest-boilerplate](https://github.com/snykk/go-rest-boilerplate)** من **[@snykk](https://github.com/snykk)** — أسس واجهة REST البرمجية بلغة Go. ٢. **[Odoo](https://github.com/odoo/odoo)** — متجر التطبيقات المعياري ونموذج التبعيات. ٣. **[go-zero](https://github.com/zeromicro/go-zero)** — محرك المرونة السحابي المنشأ. --- ## الترخيص حقوق النشر (c) 2026 **Gerege Systems Development Team, Gerege Nomadica Foundation**. يُوزَّع بموجب رخصة Apache 2.0 — راجع [`LICENSE`](https://github.com/gerege-systems/open-gerege-nexus/blob/main/LICENSE). أيقونات الأعلام من [Flaticon](https://www.flaticon.com/) ([بيان الإسناد](https://github.com/gerege-systems/open-gerege-nexus/blob/main/docs/assets/icons/ATTRIBUTION.md)).