AXIS — مجتمع المهندسين

نسخة أولية قابلة للنشر على Vercel باستخدام Next.js وNeon PostgreSQL. الواجهة عربية RTL وتستند إلى تصور AXIS المرفق.

الهوية البصرية

• اللون الأساسي: أزرق AXIS #007BFF، والسماوي #00C4CC، مع كحلي داكن للنصوص والمساحات.
• الشعار الكامل: public/axis-logo.svg (والنسخة الداكنة public/axis-logo-dark.svg).
• الرمز المنفصل: public/axis-mark.svg وأيقونات PWA داخل public/icons/.
• راجع docs/BRAND_GUIDE.md لقواعد استخدام الشعار حسب السياق. لا تستخدم صورة لوحة الشعار المرجعية كصورة واجهة.

ما الذي يتضمنه المشروع؟

• صفحة تعريف عامة لا تعرض منشورات أو بيانات أعضاء.
• إنشاء حساب وتسجيل دخول بكلمة مرور؛ كلمات المرور تُخزَّن بهيئة scrypt مع salt عشوائي.
• مجتمع مغلق: صفحات المشاركات والملف الشخصي والإعدادات والإشعارات وواجهات APIs الخاصة بالمجتمع تتطلب جلسة فعالة وحسابًا موثقًا.
• طلب توثيق نقابي يدوي يتطلب الاسم ورقم العضوية، مع صورة كارنيه اختيارية ومرفقات إضافية اختيارية. عدم رفع الصورة لا يعني اعتماد الحساب تلقائيًا؛ تظل الموافقة بعد مراجعة مسؤول مختص.
• لوحة إدارة مستقلة على /admin/login و/admin، لإدارة طلبات التوثيق والأعضاء والبلاغات والأحداث حسب دور الحساب.
• شبكة اجتماعية تشمل منشورات وصورًا، إعجابات وردودًا ومشاركة داخل AXIS، ودليل مهندسين وملفات عامة ومتابعة ومجموعات ومحادثات خاصة وإشعارات مرتبطة بالمحتوى، إلى جانب البلاغات والأحداث والاعتمادات المهنية.
• رقم العضوية يُخزَّن مشفرًا بـ AES-256-GCM، وتُستخدم بصمة HMAC لمنع تكرار الرقم من غير الاحتفاظ ببصمة عامة سهلة التخمين. لا يظهر رقم العضوية للأعضاء.
• ملفات إثبات التوثيق محفوظة في قاعدة البيانات ومقيدة لمسؤولي الإدارة والمراجعة. أحجام الإثباتات والصور محدودة لتناسب النسخة الأولى.

المتطلبات

• Node.js 20.9 أو أحدث.
• حساب Neon PostgreSQL.
• حساب Vercel للنشر.

إعداد محلي

1. انسخ .env.example إلى .env.local.

2. من Neon افتح Connect واختر قاعدة البيانات والفرع، وانسخ عنوان الاتصال pooled إلى DATABASE_URL. يمكن وضع اتصال direct في DATABASE_URL_UNPOOLED لتطبيق المخطط وإدارة البيانات. لا تضع الأسرار في Git.

3. أنشئ مفتاحين مختلفين من 32 بايت (64 حرف hex):

   node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"
   

   بديلًا من ذلك، شغّل npm run secrets:generate لعرض مفتاحين مختلفين، ثم انسخهما إلى DATA_ENCRYPTION_KEY وMEMBERSHIP_HMAC_KEY. لا تستخدم المفتاح نفسه للحاجتين، ولا تغيّر المفتاحين من غير خطة لترحيل بيانات التوثيق الحالية.

4. ثبّت الحزم وشغّل إنشاء الجداول:

   npm install
   npm run db:migrate
   npm run dev
   

5. يمكن تفعيل استعادة كلمة المرور وتأكيد البريد الإلكتروني عبر Resend: اضبط RESEND_API_KEY وEMAIL_FROM على عنوان مرسل موثّق في Resend، واضبط APP_URL على عنوان المنصة الفعلي. من دون إعداد البريد ستظهر رسالة توضح أن الاستعادة/التأكيد غير مفعّلين.

6. أنشئ حساب مدير النظام من جهازك بعد ضبط ADMIN_EMAIL, ADMIN_USERNAME, ADMIN_DISPLAY_NAME, ADMIN_PASSWORD في .env.local أو في shell، ثم:

   npm run admin:create
   

   كلمة المرور الإدارية يجب أن تكون 12 حرفًا على الأقل. لا توجد صفحة لتسجيل مدير ذاتيًا. سجّل الدخول من /admin/login.

7. اختبر رحلة المستخدم: التسجيل ← طلب التوثيق ← مراجعة الإدارة ← الموافقة ← دخول /feed. واختبر الدليل /people، والمجموعات /groups، والرسائل /messages، واستعادة كلمة المرور /forgot-password.

النشر على Vercel

1. ارفع المشروع إلى مستودع Git خاص، ثم استورده في Vercel باعتباره مشروع Next.js.
2. من الأفضل إنشاء دور PostgreSQL محدود الصلاحيات للتطبيق (مثل axis_app) من لوحة Neon، ومنحه صلاحيات CONNECT وUSAGE وSELECT, INSERT, UPDATE, DELETE للجداول. يمكن تنفيذ db/grant-app-role.sql بعد إنشاء الدور axis_app وضبط كلمة مروره. احتفظ بدور المالك لاتصال الترحيل فقط. استخدم كلمة مرور قوية خاصة بدور التطبيق.
3. أضف في إعدادات المشروع، لكل من Production وPreview حسب الحاجة، متغيرات البيئة التالية كـ Sensitive/Encrypted:
   • DATABASE_URL — اتصال Neon pooled.
   • DATA_ENCRYPTION_KEY — مفتاح AES-256-GCM.
   • MEMBERSHIP_HMAC_KEY — مفتاح HMAC منفصل.
   • APP_URL — أصل الموقع الفعلي، مثل https://your-project.vercel.app بعد توفره.
4. طبّق المخطط باستخدام npm run db:migrate من بيئة آمنة لها وصول إلى Neon. لا تعتمد على زيارة صفحة الموقع لإنشاء الجداول.
5. أنشئ المدير بالأمر npm run admin:create من جهازك مع اتصال Neon نفسه. لا تضف ADMIN_PASSWORD كمتغير بيئة دائم للإنتاج إذا لم تكن تحتاجه لعملية التهيئة.
6. قبل نشر هذا الـ Sprint، حدّث قاعدة Neon عبر npm run db:migrate من بيئة آمنة بدور المالك، أو نفّذ ملف الترحيل الموحّد db/migrations/20261025_one_sprint.sql في Neon SQL Editor. يحتوي الملف على ترحيلات الردود والمشاركة الداخلية والشبكة الاجتماعية والرسائل وتحديد المعدل، وهو مصمم لإعادة التنفيذ دون حذف المستخدمين أو المنشورات أو التعليقات الحالية.
7. أعد النشر بعد ضبط البيئة، ثم اختبر /, /register, /login, /verification, /admin/login, /admin، ورفض الوصول إلى /feed قبل التوثيق.

تأكد من ضبط APP_URL على النطاق النهائي. قارن دائمًا إعدادات Production مع Preview حتى لا تستخدم قاعدة الإنتاج دون قصد في تجارب المعاينة.

تطبيق الهاتف (PWA)

المنصة تدعم التثبيت كـ Progressive Web App (PWA) عبر HTTPS؛ لا يلزم إنشاء تطبيق منفصل في متجر التطبيقات لبدء تجربة التثبيت. تشمل ملفات PWA ملف public/manifest.webmanifest وأيقونات Android/iOS وتسجيل Service Worker وصفحة توضيح عند انقطاع الاتصال.

• iPhone/iPad: افتح رابط AXIS في المتصفح، اضغط مشاركة، ثم «إضافة إلى الشاشة الرئيسية». قد تختلف أسماء القوائم بين المتصفحات، ويكون Safari خيارًا مناسبًا إذا لم يظهر الأمر.
• Android: اضغط «تثبيت AXIS كتطبيق» عند ظهور الزر، أو افتح قائمة المتصفح واختر تثبيت التطبيق/إضافة إلى الشاشة الرئيسية.
• الخصوصية: الـ Service Worker لا يخزن صفحات المستخدم أو لوحة الإدارة أو مسارات API أو الصور الخاصة. عند عدم توفر الإنترنت تظهر صفحة إرشاد عامة؛ تحميل المشاركات وعمليات تسجيل الدخول تتطلب اتصالًا بالشبكة.
• التحقق: نفّذ npm run pwa:check ثم npm run typecheck وnpm run build. افحص التثبيت الفعلي بعد النشر عبر HTTPS وعلى جهاز iOS وAndroid.

تحديثات المخطط لهذه النسخة

تحتاج هذه النسخة مخطط Neon الذي يحتوي على الردود وإعجابات التعليقات والمشاركة الداخلية ومتابعة المهندسين والمجموعات والمحادثات والرموز المؤقتة لاستعادة كلمة المرور/تأكيد البريد وجدول تحديد المعدل.

• من بيئة موثوقة، اضبط DATABASE_URL_UNPOOLED على اتصال دور مالك قاعدة البيانات ثم شغّل npm run db:migrate، أو نفّذ ملف db/migrations/20261025_one_sprint.sql في Neon SQL Editor.
• لا تستخدم اتصال axis_app محدود الصلاحيات لتنفيذ تغييرات المخطط.
• بعد تحديث Neon، انشر التطبيق واختبر رحلة التسجيل والتوثيق، إنشاء/تعديل/حذف المنشور، متابعة مهندس، طلب انضمام لمجموعة مغلقة، إرسال رسالة خاصة، الرد والإعجاب، المشاركة الداخلية، والإشعارات.

أدوار الإدارة

• admin: إدارة كاملة، بما فيها إدارة الأعضاء.
• reviewer: مراجعة العضوية والمستندات والشهادات المهنية.
• moderator: مراجعة البلاغات وإدارة أهم الأحداث.
• member: لا يدخل المجتمع حتى يصبح verification_status='verified'.

يُنشأ أول admin باستخدام السكريبت، وتُمنع الإدارة من التسجيل الذاتي. الدخول الإداري له مسار منفصل ومحدد المعدل.

ملفات المشروع المهمة

src/app/             الصفحات وواجهات API
src/components/      مكونات الواجهة
src/lib/              الجلسات والتشفير وقاعدة البيانات والحد من الطلبات
src/app/people/       دليل المهندسين والملفات العامة
src/app/groups/       المجموعات الهندسية
src/app/messages/     المحادثات الخاصة
db/schema.sql         مخطط PostgreSQL
db/migrations/        ترحيلات idempotent لنسخ الإنتاج
scripts/migrate.mjs   إنشاء/تحديث المخطط
scripts/create-admin.mjs  إنشاء أول مدير
.env.example          أسماء المتغيرات المطلوبة دون أسرار

حدود النسخة الأولية قبل فتحها للجمهور

• التوثيق يدوي؛ لا توجد واجهة تكامل مع نقابة المهندسين.
• استعادة كلمة المرور وتأكيد البريد مدعومتان عبر Resend عند ضبط RESEND_API_KEY وEMAIL_FROM وAPP_URL؛ هذه المزايا غير فعالة افتراضيًا حتى إعداد مزود البريد والتحقق من نطاق الإرسال.
• رفع الصور ومستندات التحقق محدود بالحجم وتخزينه في Postgres مناسب لاختبار MVP؛ عند زيادة الاستخدام انقل الصور والمرفقات إلى تخزين كائنات خاص مع روابط موقعة قصيرة العمر.
• راجع سياسة الاحتفاظ بمستندات التوثيق والقانون المحلي، ونفّذ اختبارًا أمنيًا قبل استقبال بيانات حقيقية.
• لا تدّعي أن المشروع تم نشره أو اختباره ضد قاعدة بيانات فعلية إلى أن تنفذ خطوات الإعداد والاختبارات المذكورة.

أوامر التحقق

npm run typecheck
npm test
npm run build

npm test اختبار بنيوي ثابت لوجود بوابات التوثيق والإدارة الأساسية؛ ليس بديلًا لاختبار تكاملي على Neon أو اختبار نشر حقيقي.

Mobile push notifications

AXIS supports opt-in Web Push for installed browsers and mobile web apps. Set VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY, and VAPID_SUBJECT in the deployment environment. Users explicitly enable notifications in Settings; members waiting for verification can enable them on the verification screen. On iPhone, users must add AXIS to the Home Screen and open the installed app before requesting push permission. Push notifications supplement the in-app notification center; browser/platform delivery is not guaranteed.