نظرة عامة
# Gerege Nexus
**Gerege Eco System · منصة خاصة**
تربط Gerege Nexus مؤسسات Gerege Eco System وخدماته ومستخدميه. الدخول متاح للمستخدمين المصرح لهم مسبقًا فقط. تتحقق eID من الهوية، ويمنح مسؤولو المؤسسة صلاحية الدخول.
Gerege Nexus هي الأساس الذي يضم واجهة خلفية بلغة Go وواجهة ويب (web shell) بـ Next.js
وقاعدة بيانات PostgreSQL ولوحة تحكم المشغّل (control plane) والعملاء الأصليين (native clients).
تضيف مستودعات التوزيع (distribution) تطبيقات الأعمال على شكل وحدات Go تُجمَّع وقت البناء
(compile-time). هذا المستودع الأساسي ليس حزمة ERP جاهزة لجميع القطاعات.
> **النطاق الفعلي (2026-10-25):** [`catalog/apps.json`](https://github.com/gerege-systems/private-gerege-nexus/blob/main/catalog/apps.json) فارغ — لا تحمل النواة أي تطبيق أعمال؛ كل تطبيق يأتي من كتالوج التوزيعة.
> آخر تطبيق، وهو `io.gerege.nexus.sso_clients`، انتقل في 2026-08-25 إلى
> [appstore-gerege-nexus](https://github.com/gerege-systems/appstore-gerege-nexus)،
> وأي distribution يجلبه من متجر التطبيقات. قد يبقى في هذا المستودع سجل migration أو
> ترجمات الواجهة الأمامية لتطبيقات مثل contacts وproducts وinventory وbilling وdocuments
> وgovernment workflow وعملاء SSO، لكن الوحدات العاملة لتلك التطبيقات غير موجودة في هذا
> الملف التنفيذي الأساسي. لا تُفتح مسارات تلك التطبيقات على هذا deployment.
Монгол
·
العربية
·
中文
·
English
·
Français
·
Русский
·
Español
## ما الذي يحتويه هذا المستودع بالضبط
| الجزء | التنفيذ الحالي |
| --- | --- |
| Tenant plane | تسجيل الدخول، session، عضوية المستأجر (tenant membership)، RBAC، الملف الشخصي، تثبيت/إزالة التطبيقات، AI API، الأجهزة، email verification، SSO client/provider، reporting engine |
| Operator plane | دورة حياة المستأجر، دخول المشغّل عبر TOTP، audit، الدعم، quota/metering، feature flag، runtime settings/credentials، الإعلانات، إدارة backup/deploy |
| التطبيقات المدمجة (Built-in) | لا يوجد. كل تطبيق يأتي عبر الكتالوج — بعد مغادرة `sso_clients` في 2026-08-25 لا يحتوي هذا الملف التنفيذي على أي تطبيق أعمال |
| Web | صفحة الهبوط العامة، login/setup، الملف الشخصي، app store، settings، control plane — جميعها مبنية على `@gerege-systems/ui` (Tailwind 4)؛ شاشات التطبيقات (عميل SSO، المستندات، جهات الاتصال) باقية في shell بلا حياة لغياب وحداتها |
| Native | shell لأنظمة macOS وiOS/iPadOS وWindows وAndroid؛ وPWA على Linux |
| Observability | `/health`، `/ready`، `/metrics`، structured log، OTLP/Sentry اختياريان؛ compose منفصل للمراقبة |
وجود route أو جدول أو service في المنصة الأساسية لا يعني بالضرورة وجود تطبيق أعمال
ظاهر للمستخدم. لا تعمل مسارات الوحدة إلا عندما تنفّذ وحدة compile-time عقد
[`pkg/nexus`](https://github.com/gerege-systems/private-gerege-nexus/blob/main/backend/pkg/nexus)، وتُسجَّل في binary، وتُدرج في الكتالوج، وتُثبَّت لدى
المستأجر المعني.
### غير موجود في هذا الملف التنفيذي الأساسي
- تطبيقات الأعمال contacts وproducts وinventory وbilling
- تطبيق الأقسام/الموظفين الخاص بـ Organisation & People (أما legal profile للمؤسسة
فيبقى جزءًا من المنصة على `/organisation`)
- وحدة backend للمستندات (Documents) وواجهة التقارير. يوجد في هذا المستودع عميل frontend
اختياري لـ contract/inbox، لكن contract API المطابق له غير موجود بعد في base الحالي ولا في
distribution المسمى `client-gerege-nexus`؛ وما لم يستجب endpoint فعليًا لا يظهر رابطه على
صفحة الهبوط
- واجهة/وحدة Government services workflow
- المحطة بأكملها — اللوحة، والقنوات، وpeer/exchange API، وعقد المغلّف. في 2026-08-27
انتقل آخر جزء منها إلى `client-gerege-nexus`
- موصلات الأنظمة الخارجية وwebhook (Google Drive وDropbox وMeet وURL العميل). انتقلت
أيضًا في 2026-08-27؛ ولم يبقَ في النواة سوى تشفير ختم بيانات الاعتماد
(`nexus.SecretSealer`). كما أُزيل من النواة سلوك الإرسال الآلي للمستندات الموقّعة إلى
الخارج
- adaptive circuit breaker عام، وsingleflight، ومحرك generic retry
انفصل بعض هذه الأجزاء إلى مستودعات product distribution. لمعرفة كيفية كتابة الوحدة
ووصولها عبر الكتالوج راجع [`docs/MODULES.md`](modules.md)، ولكيفية أخذ distribution
للنواة وتحديثها راجع [`docs/DISTRIBUTION.md`](distribution.md)، وللبنية المعمارية الحالية
راجع [`docs/ARCHITECTURE.md`](architecture.md).
## القدرات الأساسية
- Module SDK وقت البناء: عقود route وpermission وmenu وdependency وmigration
وreport وAI tool وcapability.
- app installation وبوابة RBAC لكل مستأجر. تُرجع مسارات الوحدة غير المثبتة/المعطّلة
`403`.
- كتالوج محلي أو كتالوج بعيد موقّع بـ Ed25519؛ مع cache fallback ومزامنة
يدوية/في الخلفية.
- تسجيل الدخول بكلمة المرور وeID وДАН وGoogle وupstream OIDC؛ إضافة إلى مزوّد
OAuth2/OIDC.
- مخططات PostgreSQL `workspace` و`registry` و`operator`، مع حماية RLS/role.
- عند إعداد Redis: إبطال cache بين النسخ المتماثلة (replicas) وrate limit مشترك؛
وعند عدم إعداده: fallback لعملية واحدة.
- load shedding للطلبات المتزامنة. لكل عميل خارجي سياسة timeout/retry خاصة به؛ ولا
يُعدّ generic circuit breaker غير الموجود جزءًا من المنصة.
- عند توفر مفتاح Gemini: chat وspeech-to-text وtext-to-speech وtranslation. تسجّل
وحدة distribution بنفسها أدوات AI الخاصة ببيانات الأعمال؛ ولا يختلق deployment الأساسي
أرقام inventory أو billing.
- نظام التصميم: web shell والكونسول مبنيان على `@gerege-systems/ui`، والمصدر الوحيد
للرموز (tokens) هو `theme.css` الخاص بالمكتبة. يغيّر كل deployment مظهره دون تعديل
الشيفرة عبر متغيرات البيئة `BRAND_THEME_*` وCSS المأخوذ من «Get code» في ui.gecore.mn/#theme
([`DEVELOPMENT.md`](development.md#харагдацыг-тохируулах-theme)).
- عملاء E-ID وДАН وХУР موجودون في المنصة. في بيئة `production` تكون mock معطّلة
افتراضيًا؛ ولاستخدام الخدمة الفعلية يلزم credential خاص بكل منها.
## بنية المستودع
## التشغيل
### المتطلبات المسبقة
- Docker Compose، أو
- Go 1.26+ وNode.js 20+ وPostgreSQL 16+
### Docker Compose
يشغّل Compose كلًا من PostgreSQL وRedis وmigration لمرة واحدة والواجهة الخلفية والواجهة
الأمامية. تُستخدم العناوين التالية:
- Tenant web:
- Control plane web:
- API health:
حساب العرض التجريبي للتطوير (Development demo account):
| الحقل | القيمة |
| --- | --- |
| البريد الإلكتروني | `admin@example.com` |
| كلمة المرور | `Password123!` |
| Tenant | `Demo Corporation` (`demo`) |
يكون `SEED_DEMO_DATA` مفعّلًا افتراضيًا في جميع البيئات عدا production.
في production لا يُنشأ demo account ما لم تُمرَّر القيمة `true` صراحةً.
### يدويًا
شغّل PostgreSQL أولًا (وRedis عند الحاجة)، ثم:
في terminal آخر:
لا تُستنتج إعدادات production من README. اتبع [`.env.example`](https://github.com/gerege-systems/private-gerege-nexus/blob/main/.env.example) للمتغيرات
الكاملة والقيم الافتراضية الآمنة، و[proxmox-gerege-net](https://github.com/erdenebatt/proxmox-gerege-net) (`stack/nexus`)
لإعدادات النشر الفعلي، و[`docs/OPERATIONS.md`](operations.md) لخطوات إنشاء أول tenant/operator.
## المصادر الفعلية للواجهة البرمجية والكتالوج
قائمة API في README ليست عقدًا كاملًا. المصادر التي تُتحقق مع الشيفرة:
- لقطة مسارات المنصة (Platform route snapshot):
[`backend/pkg/host/testdata/routes.txt`](https://github.com/gerege-systems/private-gerege-nexus/blob/main/backend/pkg/host/testdata/routes.txt)
- لقطة الواجهة العامة لـ Module SDK:
[`backend/pkg/nexus/testdata/api.txt`](https://github.com/gerege-systems/private-gerege-nexus/blob/main/backend/pkg/nexus/testdata/api.txt)
- Base catalog: [`catalog/apps.json`](https://github.com/gerege-systems/private-gerege-nexus/blob/main/catalog/apps.json) (بوابة API فقط)
- عقد SSO في Module SDK:
[`backend/pkg/nexus/ssoclients.go`](https://github.com/gerege-systems/private-gerege-nexus/blob/main/backend/pkg/nexus/ssoclients.go)
- الإعدادات: [`.env.example`](https://github.com/gerege-systems/private-gerege-nexus/blob/main/.env.example)
تشمل endpoint العامة الأساسية `/health` و`/ready` و`/metrics` وauth وsetup
وOAuth2/OIDC وapp store وdevice enrollment وemail verification. المسارات التي تتطلب
tenant session، ومسارات control plane، ومسارات الوحدات، لكلٍّ منها حمايته المستقلة.
## الاختبارات
يضيف CI إلى ذلك race test مدعومًا بـ migration، وحدود API/route، وPWA، وhost،
وتقرير translation-gap، وDocker build، و`govulncheck`، و`gosec`، وبناء native client.
راجع الأوامر الفعلية في [`.github/workflows/ci.yml`](https://github.com/gerege-systems/private-gerege-nexus/blob/main/.github/workflows/ci.yml)
و[`security.yml`](https://github.com/gerege-systems/private-gerege-nexus/blob/main/.github/workflows/security.yml)
و[`native-clients.yml`](https://github.com/gerege-systems/private-gerege-nexus/blob/main/.github/workflows/native-clients.yml).
## حالة اللغات والتوثيق
النصوص المصدرية للواجهة بالمنغولية والإنجليزية؛ وتوجد طبقات overlay للعربية والصينية
والفرنسية والروسية والإسبانية. تعود overlay الناقصة (fallback) إلى الإنجليزية ويُبلغ CI عن
الثغرات — لا نَعِد بأن كل شاشة مترجمة بنسبة 100%.
README متوفر بسبع لغات. ليست كل وثيقة تقنية مترجمة إلى اللغات السبع؛ لغة كل ملف وحالته
مدوّنة في [`docs/README.md`](documents.md). الملفات التي تحمل أسماء `PLAN` و`PROPOSAL`
و`PROMPT` و`WORKLOG` ليست عقد runtime الحالي، ولا يجوز اعتمادها وحدها مصدرًا لتعليمات
التشغيل.
## الأمان وحالة المشروع
لا تُنشر الثغرات في public issue؛ استخدم إجراء private reporting الموضح في
[`SECURITY.md`](security.md).
مشروع خاص. جميع الحقوق محفوظة.
backend/
cmd/ أدوات api وmigrate وbootstrap وcatalog
db/migrations/ ترحيلات PostgreSQL الأساسية
internal/kernel/ آليات منخفضة المستوى مشتركة بين الـ planes الثلاثة
internal/operator/ deployment/operator plane
internal/workspace/ plane يعمل نيابةً عن المؤسسة
internal/person/ المساحة الخاصة بالشخص — /api/v1/me
internal/apps/ نقطة تجميع distribution module (فارغة حاليًا)
pkg/nexus/ SDK العام لـ distribution module
pkg/host/ entry point العام لتشغيل distribution binary
frontend/ Next.js web shell وواجهة control plane
catalog/ catalog الأساسي وmanifest وchronicle
native-apps/ عملاء macOS وiOS/iPadOS وWindows وAndroid
deploy/ image, compose, nginx, monitoring
docs/ فهرس الوثائق الحالية والتاريخية والمقترحات
cd backend
go mod download
DATABASE_URL="postgres://postgres:postgrespassword@localhost:5432/platform_db?sslmode=disable" \
go run ./cmd/migrate up
PUBLIC_ORIGIN=http://nexus.localhost:3000 \
ALLOWED_ORIGINS=http://nexus.localhost:3000,http://admin.localhost:3000 \
CONTROL_PLANE_HOST=admin.localhost \
go run ./cmd/api