محیط توسعه

پروژه با Vite اجرا می‌شود: تغییر در SCSS، JS یا HTML بلافاصله بدون رفرش کامل اعمال می‌شود و مسیر صفحات تمیز است.

اجرای پروژه

npm run dev -- --host 0.0.0.0 --port 5173

باگ رایج	علت و راه‌حل
استایل‌ها در حالت توسعه اعمال نمی‌شوند	Vite فایل `.scss` را به‌صورت ماژول JS سرو می‌کند؛ در `src/partials/head.html` لینک با `?direct` نوشته شده تا مستقیم با `Content-Type: text/css` سرو شود
مسیر `/dashboards/analytics.html` خطای ۴۰۴ می‌دهد	میان‌افزار توسعه در `tools/nova-plugin.mjs` مسیر تمیز را به `src/pages/**` نگاشت می‌کند؛ بعد از افزودن صفحه جدید یک‌بار سرور را ری‌استارت کنید

ساختار کار در روزمره

صفحه جدید؟ در tools/manifest.mjs یک آیتم به سایدبار اضافه کنید و npm run gen:pages بگیرید.
کامپوننت جدید؟ فایل SCSS را در src/scss/components/ بسازید و به src/scss/main.scss وصل کنید.
رفتار جدید؟ منطق را در src/js/core/ (عمومی) یا src/js/pages/ (مخصوص یک بخش) بنویسید.
داده جدید؟ در src/data/ اضافه کنید و از طریق src/services/ مصرف کنید؛ هرگز در کنترل‌کننده داده خام ننویسید.

جریان ساخت

tools/build-pages.mjs   →  src/pages/**.html        (۲۰۶ صفحه)
tools/gen-assets.mjs    →  public/assets/**        (لوگو، آواتار، محصول، برند)
tools/gen-nav.mjs       →  src/data/navigation.js + public/sitemap.xml
vite build              →  dist/assets/{css,js,fonts}
tools/flatten-dist.mjs  →  مرتب‌سازی نهایی dist/ و اصلاح مسیرهای نسبی

نکته: هرگز صفحه‌های src/pages/** را دستی ویرایش نکنید؛ این فایل‌ها در هر ساخت بازنویسی می‌شوند

برای محتوای اختصاصی، فایل هم‌نام را در src/partials/pages/<مسیر صفحه>.html بسازید.

کنترل کیفیت

npm run qa:links   # لینک‌های شکسته، فایل‌های گم‌شده، کلاس‌های بدون استایل، دسترس‌پذیری، SEO
npm run qa:smoke   # راه‌اندازی واقعی کنترل‌کننده‌ها در DOM شبیه‌سازی‌شده

خروجی qa:links روی پوشه dist/ کار می‌کند؛ پس اول npm run build بگیرید. qa:smoke نیازی به مرورگر ندارد و ۱۴۲ سناریوی صفحه را اجرا می‌کند.

هدف: هیچ تغییری را بدون سبز بودن این دو کنترل کیفیت تحویل ندهید

استانداردهای کد

ماژول‌های ES با import/export؛ بدون var، بدون jQuery و بدون متغیر جهانی خارج از window.NOVA.
CSS با ویژگی‌های منطقی (inset-inline, margin-block) — هرگز left/right مستقیم.
نام‌گذاری BEM سبک: .block, .block__element, .block--modifier.
هر تابع یک کار؛ توضیح با کامنت کوتاه در بالای فایل.
متن‌های رابط کاربری از src/locales/** خوانده می‌شوند؛ رشته فارسی داخل JS فقط برای داده نمونه مجاز است.

افزودن وابستگی

npm install chartjs-plugin-annotation

سپس در vite.config.js در صورت نیاز به manualChunks اضافه کنید و در src/js/core/charts.js مقداردهی اولیه کنید. تعداد وابستگی‌ها را کم نگه دارید؛ همه کامپوننت‌های اصلی دست‌ساز هستند.

دیباگ

window.NOVA در کنسول: دسترسی به سرویس‌ها، تم، چیدمان، NOVA.data('orders', { perPage: 5 }) و NOVA.url('users/list.html').
Ctrl + K برای پالت فرمان‌ها، Ctrl + / برای میان‌برها.
برای شبیه‌سازی خطای شبکه، mockErrors را در src/config/config.js روشن کنید.

Development environment

The project runs on Vite: changes to SCSS, JS or HTML are applied immediately without a full reload, and page routes are clean.

Running the project

npm run dev -- --host 0.0.0.0 --port 5173

Common issue	Cause and fix
Styles are not applied in development	Vite serves `.scss` files as JS modules; in `src/partials/head.html` the link is written with `?direct` so it is served directly with `Content-Type: text/css`
The `/dashboards/analytics.html` route returns 404	The dev middleware in `tools/nova-plugin.mjs` maps clean routes to `src/pages/**`; restart the server once after adding a new page

Everyday workflow

New page? Add an item to the sidebar in tools/manifest.mjs and run npm run gen:pages.
New component? Create the SCSS file in src/scss/components/ and wire it into src/scss/main.scss.
New behaviour? Write the logic in src/js/core/ (generic) or src/js/pages/ (specific to one area).
New data? Add it in src/data/ and consume it through src/services/; never write raw data in a controller.

Build flow

tools/build-pages.mjs   →  src/pages/**.html        (206 pages)
tools/gen-assets.mjs    →  public/assets/**        (logo, avatars, products, brands)
tools/gen-nav.mjs       →  src/data/navigation.js + public/sitemap.xml
vite build              →  dist/assets/{css,js,fonts}
tools/flatten-dist.mjs  →  final dist/ tidy-up and relative path fixes

Tip: never edit the src/pages/** pages by hand; these files are rewritten on every build

For custom content, create a file with the same name in src/partials/pages/<page path>.html.

Quality control

npm run qa:links   # broken links, missing files, unstyled classes, accessibility, SEO
npm run qa:smoke   # actually boots the controllers in a simulated DOM

qa:links works on the dist/ folder, so run npm run build first. qa:smoke needs no browser and runs 142 page scenarios.

Goal: never ship a change unless both of these quality checks are green

Code standards

ES modules with import/export; no var, no jQuery and no globals outside window.NOVA.
CSS with logical properties (inset-inline, margin-block) — never raw left/right.
Light BEM naming: .block, .block__element, .block--modifier.
One job per function; a short comment at the top of the file.
Interface text is read from src/locales/**; literal strings inside JS are only allowed for sample data.

Adding a dependency

npm install chartjs-plugin-annotation

Then add it to manualChunks in vite.config.js if needed and initialise it in src/js/core/charts.js. Keep dependencies few; all the core components are hand-built.

Debugging

window.NOVA in the console: access to services, theme, layout, NOVA.data('orders', { perPage: 5 }) and NOVA.url('users/list.html').
Ctrl + K for the command palette, Ctrl + / for shortcuts.
To simulate network errors, turn on mockErrors in src/config/config.js.

بيئة التطوير

يعمل المشروع على Vite: تُطبَّق التغييرات في SCSS أو JS أو HTML فوراً دون إعادة تحميل كاملة، ومسارات الصفحات نظيفة.

تشغيل المشروع

npm run dev -- --host 0.0.0.0 --port 5173

مشكلة شائعة	السبب والحل
لا تُطبَّق الأنماط في وضع التطوير	يقدّم Vite ملف `.scss` كوحدة JS؛ لذا كُتب الرابط في `src/partials/head.html` مع `?direct` ليُقدَّم مباشرة بـ `Content-Type: text/css`
المسار `/dashboards/analytics.html` يعطي خطأ ٤٠٤	يربط الوسيط البرمجي للتطوير في `tools/nova-plugin.mjs` المسار النظيف بـ `src/pages/**`؛ أعد تشغيل الخادم مرة واحدة بعد إضافة صفحة جديدة

سير العمل اليومي

صفحة جديدة؟ أضف عنصراً إلى الشريط الجانبي في tools/manifest.mjs ونفّذ npm run gen:pages.
مكوّن جديد؟ أنشئ ملف SCSS في src/scss/components/ واربطه بـ src/scss/main.scss.
سلوك جديد؟ اكتب المنطق في src/js/core/ (عام) أو src/js/pages/ (خاص بقسم واحد).
بيانات جديدة؟ أضفها في src/data/ واستهلكها عبر src/services/؛ ولا تكتب بيانات خاماً في المتحكم أبداً.

مسار البناء

tools/build-pages.mjs   →  src/pages/**.html        (٢٠٦ صفحات)
tools/gen-assets.mjs    →  public/assets/**        (الشعار، الصور الرمزية، المنتجات، العلامات)
tools/gen-nav.mjs       →  src/data/navigation.js + public/sitemap.xml
vite build              →  dist/assets/{css,js,fonts}
tools/flatten-dist.mjs  →  الترتيب النهائي لـ dist/ وتصحيح المسارات النسبية

ملاحظة: لا تعدّل صفحات src/pages/** يدوياً أبداً؛ فهذه الملفات تُعاد كتابتها في كل بناء

للمحتوى المخصص، أنشئ ملفاً بالاسم نفسه في src/partials/pages/<مسار الصفحة>.html.

ضبط الجودة

npm run qa:links   # الروابط المعطوبة، الملفات المفقودة، الفئات بلا أنماط، إمكانية الوصول، SEO
npm run qa:smoke   # تشغيل فعلي للمتحكمات في DOM محاكى

يعمل qa:links على المجلد dist/؛ لذا نفّذ npm run build أولاً. ولا يحتاج qa:smoke إلى متصفح ويشغّل ١٤٢ سيناريو صفحة.

الهدف: لا تسلّم أي تغيير ما لم ينجح فحصا الجودة هذان

معايير الشيفرة

وحدات ES مع import/export؛ بلا var وبلا jQuery وبلا متغيرات عامة خارج window.NOVA.
CSS بالخصائص المنطقية (inset-inline, margin-block) — ولا left/right مباشرة أبداً.
تسمية BEM مخففة: .block و.block__element و.block--modifier.
مهمة واحدة لكل دالة؛ وتعليق قصير أعلى الملف.
تُقرأ نصوص الواجهة من src/locales/**؛ والنصوص الحرفية داخل JS مسموحة للبيانات النموذجية فقط.

إضافة اعتمادية

npm install chartjs-plugin-annotation

ثم أضفها عند الحاجة إلى manualChunks في vite.config.js وهيّئها في src/js/core/charts.js. أبقِ عدد الاعتماديات قليلاً؛ فجميع المكونات الأساسية مصنوعة يدوياً.

تصحيح الأخطاء

window.NOVA في وحدة التحكم: وصول إلى الخدمات والسمة والتخطيط وNOVA.data('orders', { perPage: 5 }) وNOVA.url('users/list.html').
Ctrl + K للوحة الأوامر، وCtrl + / للاختصارات.
لمحاكاة خطأ في الشبكة، فعّل mockErrors في src/config/config.js.