ساختار پروژه

ساختار پروژه بر پایه یک قاعده است: تولیدشده‌ها از دست‌نویس‌ها جدا باشند. هر چیزی که با ابزار ساخته می‌شود در بالای فایلش هم نوشته شده که دستی ویرایش نشود.

novaadmin/
├── index.html                     صفحه محصول (لندینگ)
├── vite.config.js                 ورودی‌ها، alias، chunkها و افزونه‌های پروژه
├── package.json                   اسکریپت‌ها و وابستگی‌های نسخه‌قفل‌شده
├── public/                        دارایی‌های کپی‌شده بدون پردازش
│   ├── assets/{logo,logo-mark,favicon}.svg
│   ├── assets/img/{avatars,products,brands}/
│   ├── site.webmanifest
│   ├── robots.txt                 تولیدشده توسط gen-nav
│   └── sitemap.xml                تولیدشده توسط gen-nav
├── src/
│   ├── pages/**                   ۲۰۶ صفحه تولیدشده (پوسته + جای‌نگهدار محتوا)
│   ├── partials/                  قطعه‌های مشترک
│   │   ├── head.html              متا، فونت، لینک استایل
│   │   ├── header.html            هدر برنامه (جستجو، اعلان، پروفایل)
│   │   ├── overlays.html          پالت فرمان، میان‌برها، میزبان پیام‌ها
│   │   ├── customizer.html        کشوی شخصی‌سازی ظاهر
│   │   ├── footer.html            فوتر
│   │   ├── scripts.html           ورود JS
│   │   ├── docs/*.html            بدنه مستندات (تولیدشده از docs/ با gen-docs)
│   │   └── pages/<مسیر>.html      بازنویسی دستی بدنه هر صفحه (اختیاری)
│   ├── scss/
│   │   ├── main.scss              ترتیب دقیق importها
│   │   ├── base/                  توکن‌ها، پالت‌ها، تم‌ها، ریست، فونت، پل بوت‌استرپ
│   │   ├── layout/                پوسته، سایدبار، هدر، سرصفحه، مستندات، احراز هویت
│   │   ├── components/            ۲۸ فایل کامپوننت (دکمه، فرم، کارت، جدول، کانبان…)
│   │   ├── pages/                 ترکیب‌های صفحه‌ای (لندینگ، فاکتور، داشبورد)
│   │   └── utilities/             کلاس‌های کمکی که آخر می‌آیند
│   ├── js/
│   │   ├── main.js                راه‌انداز: تم → چیدمان → پوسته → مسیر صفحه
│   │   ├── core/                  ۲۰ ماژول هسته (بدون وابستگی به صفحه خاص)
│   │   └── pages/                 کنترل‌کننده هر بخش، بارگذاری تنبل
│   ├── services/                  لایه داده با قرارداد REST
│   ├── data/                      داده نمونه واقع‌گرایانه
│   ├── locales/                   دیکشنری fa/en/ar + داده‌های تولیدشده
│   └── config/config.js           تنظیمات برند، پیش‌فرض‌ها، ارز، منطقه زمانی
├── docs/                          ۲۳ منبع مارک‌داون مستندات (+ ترجمه‌ها در en/ و ar/)
└── tools/
    ├── manifest.mjs               منبع یکتای ناوبری و فهرست صفحه‌ها
    ├── build-pages.mjs            تولید صفحه‌ها + داده‌های محلی
    ├── gen-assets.mjs             تولید SVGهای لوگو، آواتار، محصول، برند
    ├── gen-nav.mjs                navigation.js + sitemap + robots
    ├── gen-docs.mjs               مارک‌داون → بدنه مستندات
    ├── flatten-dist.mjs           مرتب‌سازی خروجی نهایی
    ├── qa-links.mjs               کنترل کیفیت خروجی
    ├── smoke.mjs                  اجرای کنترل‌کننده‌ها در DOM شبیه‌سازی‌شده
    ├── package.mjs                ساخت بسته نهایی
    └── nova-plugin.mjs            افزونه Vite (include، توکن، مسیر تمیز)

قواعد مهم

src/pages/** را ویرایش نکنید. در هر ساخت بازنویسی می‌شود. برای تغییر بدنه یک صفحه، فایل هم‌نام را در src/partials/pages/ بسازید.
src/locales/generated.js و src/data/navigation.js تولیدشده‌اند. منبع آن‌ها tools/manifest.mjs و docs/ است.
دارایی‌ها در public/ بدون پردازش کپی می‌شوند. اگر می‌خواهید تصویری را Vite بهینه کند، آن را از src/ import کنید.
هر چه در src/ باشد به مرورگر می‌رود؛ فایل ابزار یا مستندات را آنجا نگذارید.

نقشه ماژول‌های هسته

ماژول	مسئولیت
`dom.js`	انتخابگرها، رندر، رویداد، ابزار کلاس
`theme.js`	تم، پالت، چیدمان، تراکم، اندازه فونت، سبک سایدبار
`layout.js`	پوسته، سایدبار، حالت موبایل، چیدمان دو ستونی
`chrome.js`	پالت فرمان، میان‌برها، اعلان‌ها، ویرایشگر ابزارک، شخصی‌ساز
`datatable.js`	جدول داده کامل (جستجو، فیلتر، مرتب‌سازی، ستون، انتخاب، خروجی)
`charts.js`	پوسته واحد ApexCharts برای حالت روشن/تاریک
`calendar.js` / `jalali.js`	تقویم ماه/هفته/روز/فهرست و تبدیل تاریخ شمسی
`kanban.js`	برد کشیدن‌و‌رهاکردن با SortableJS و ذخیره ترتیب
`i18n.js`	زبان فعال، `data-i18n`، جهت و بازآرایی متون
`numbers.js`	ارقام فارسی/عربی/لاتین، قالب ارز، اعداد فشرده
`toast.js` / `modal.js`	پیام‌ها در چهار موقعیت و گفتگوهای تأیید
`form.js` / `ui.js`	اعتبارسنجی، حالت‌های فرم، تب‌ها، آکاردئون، چاپ

نکته: در main.js ترتیب راه‌اندازی مهم است: i18n → theme → layout → dropdowns → chrome → forms → ui → route()

اگر ماژولی به DOM تولیدشده توسط کنترل‌کننده نیاز دارد، باید بعد از route() صدا زده شود.

Folder structure

The project structure rests on one rule: generated files are kept apart from hand-written ones. Anything produced by a tool also says at the top of the file that it must not be edited by hand.

novaadmin/
├── index.html                     product page (landing)
├── vite.config.js                 entries, aliases, chunks and project plugins
├── package.json                   scripts and version-locked dependencies
├── public/                        assets copied without processing
│   ├── assets/{logo,logo-mark,favicon}.svg
│   ├── assets/img/{avatars,products,brands}/
│   ├── site.webmanifest
│   ├── robots.txt                 generated by gen-nav
│   └── sitemap.xml                generated by gen-nav
├── src/
│   ├── pages/**                   206 generated pages (shell + content placeholder)
│   ├── partials/                  shared fragments
│   │   ├── head.html              meta, fonts, stylesheet link
│   │   ├── header.html            app header (search, notifications, profile)
│   │   ├── overlays.html          command palette, shortcuts, toast host
│   │   ├── customizer.html        appearance customizer drawer
│   │   ├── footer.html            footer
│   │   ├── scripts.html           JS entry
│   │   ├── docs/*.html            documentation bodies (generated from docs/ by gen-docs)
│   │   └── pages/<path>.html      manual override of a page body (optional)
│   ├── scss/
│   │   ├── main.scss              exact import order
│   │   ├── base/                  tokens, palettes, themes, reset, fonts, Bootstrap bridge
│   │   ├── layout/                shell, sidebar, header, page head, docs, auth
│   │   ├── components/            28 component files (button, form, card, table, kanban…)
│   │   ├── pages/                 page compositions (landing, invoice, dashboard)
│   │   └── utilities/             helper classes that come last
│   ├── js/
│   │   ├── main.js                bootstrapper: theme → layout → shell → page route
│   │   ├── core/                  20 core modules (no dependency on a specific page)
│   │   └── pages/                 one controller per area, lazy-loaded
│   ├── services/                  data layer with a REST contract
│   ├── data/                      realistic sample data
│   ├── locales/                   fa/en/ar dictionaries + generated data
│   └── config/config.js           brand settings, defaults, currency, time zone
├── docs/                          23 Markdown documentation sources (+ translations in en/ and ar/)
└── tools/
    ├── manifest.mjs               single source of navigation and the page list
    ├── build-pages.mjs            generates pages + locale data
    ├── gen-assets.mjs             generates logo, avatar, product and brand SVGs
    ├── gen-nav.mjs                navigation.js + sitemap + robots
    ├── gen-docs.mjs               Markdown → documentation bodies
    ├── flatten-dist.mjs           final output tidy-up
    ├── qa-links.mjs               output quality control
    ├── smoke.mjs                  runs controllers in a simulated DOM
    ├── package.mjs                builds the final package
    └── nova-plugin.mjs            Vite plugin (include, tokens, clean paths)

Important rules

Do not edit src/pages/**. It is rewritten on every build. To change a page body, create a file with the same name in src/partials/pages/.
src/locales/generated.js and src/data/navigation.js are generated. Their sources are tools/manifest.mjs and docs/.
Assets in public/ are copied without processing. If you want Vite to optimise an image, import it from src/.
Everything in src/ is shipped to the browser; do not put tool or documentation files there.

Core module map

Module	Responsibility
`dom.js`	Selectors, rendering, events, class helpers
`theme.js`	Theme, palette, layout, density, font size, sidebar style
`layout.js`	Shell, sidebar, mobile mode, two-column layout
`chrome.js`	Command palette, shortcuts, notifications, widget editor, customizer
`datatable.js`	Full data table (search, filter, sort, columns, selection, export)
`charts.js`	A single ApexCharts skin for light/dark mode
`calendar.js` / `jalali.js`	Month/week/day/list calendar and Jalali date conversion
`kanban.js`	Drag-and-drop board with SortableJS and saved order
`i18n.js`	Active language, `data-i18n`, direction and text rearrangement
`numbers.js`	Persian/Arabic/Latin digits, currency format, compact numbers
`toast.js` / `modal.js`	Toasts in four positions and confirmation dialogs
`form.js` / `ui.js`	Validation, form states, tabs, accordion, printing

Tip: the boot order in main.js matters: i18n → theme → layout → dropdowns → chrome → forms → ui → route()

If a module needs DOM produced by a controller, it must be called after route().

بنية المشروع

تقوم بنية المشروع على قاعدة واحدة: فصل الملفات المولّدة عن المكتوبة يدوياً. كل ما تنتجه الأدوات يذكر أيضاً في أعلى ملفه أنه لا يجوز تعديله يدوياً.

novaadmin/
├── index.html                     صفحة المنتج (الهبوط)
├── vite.config.js                 نقاط الدخول، الأسماء المستعارة، الأجزاء وإضافات المشروع
├── package.json                   السكربتات والاعتماديات مثبّتة الإصدار
├── public/                        أصول تُنسخ دون معالجة
│   ├── assets/{logo,logo-mark,favicon}.svg
│   ├── assets/img/{avatars,products,brands}/
│   ├── site.webmanifest
│   ├── robots.txt                 يولّده gen-nav
│   └── sitemap.xml                يولّده gen-nav
├── src/
│   ├── pages/**                   ٢٠٦ صفحات مولّدة (الهيكل + موضع المحتوى)
│   ├── partials/                  أجزاء مشتركة
│   │   ├── head.html              الوسوم الوصفية، الخطوط، رابط الأنماط
│   │   ├── header.html            ترويسة التطبيق (البحث، الإشعارات، الملف الشخصي)
│   │   ├── overlays.html          لوحة الأوامر، الاختصارات، حاوية الرسائل
│   │   ├── customizer.html        درج تخصيص المظهر
│   │   ├── footer.html            التذييل
│   │   ├── scripts.html           نقطة دخول JS
│   │   ├── docs/*.html            محتوى الوثائق (يولّده gen-docs من docs/)
│   │   └── pages/<المسار>.html    إعادة كتابة يدوية لمحتوى أي صفحة (اختياري)
│   ├── scss/
│   │   ├── main.scss              الترتيب الدقيق لعمليات الاستيراد
│   │   ├── base/                  رموز التصميم، لوحات الألوان، السمات، إعادة الضبط، الخطوط، جسر Bootstrap
│   │   ├── layout/                الهيكل، الشريط الجانبي، الترويسة، رأس الصفحة، الوثائق، المصادقة
│   │   ├── components/            ٢٨ ملف مكوّن (زر، نموذج، بطاقة، جدول، كانبان…)
│   │   ├── pages/                 تراكيب خاصة بالصفحات (الهبوط، الفاتورة، اللوحة)
│   │   └── utilities/             فئات مساعدة تأتي في النهاية
│   ├── js/
│   │   ├── main.js                المُشغّل: السمة ← التخطيط ← الهيكل ← مسار الصفحة
│   │   ├── core/                  ٢٠ وحدة نواة (دون اعتماد على صفحة بعينها)
│   │   └── pages/                 متحكم لكل قسم، بتحميل كسول
│   ├── services/                  طبقة البيانات بعقد REST
│   ├── data/                      بيانات نموذجية واقعية
│   ├── locales/                   قواميس fa/en/ar + بيانات مولّدة
│   └── config/config.js           إعدادات العلامة، القيم الافتراضية، العملة، المنطقة الزمنية
├── docs/                          ٢٣ مصدر Markdown للوثائق (+ الترجمات في en/ وar/)
└── tools/
    ├── manifest.mjs               المصدر الوحيد للتنقل وقائمة الصفحات
    ├── build-pages.mjs            توليد الصفحات + بيانات اللغات
    ├── gen-assets.mjs             توليد ملفات SVG للشعار والصور الرمزية والمنتجات والعلامات
    ├── gen-nav.mjs                navigation.js + sitemap + robots
    ├── gen-docs.mjs               Markdown ← محتوى الوثائق
    ├── flatten-dist.mjs           الترتيب النهائي للمخرجات
    ├── qa-links.mjs               ضبط جودة المخرجات
    ├── smoke.mjs                  تشغيل المتحكمات في DOM محاكى
    ├── package.mjs                بناء الحزمة النهائية
    └── nova-plugin.mjs            إضافة Vite (include، الرموز، المسارات النظيفة)

قواعد مهمة

لا تعدّل src/pages/**. تُعاد كتابته في كل بناء. لتغيير محتوى صفحة، أنشئ ملفاً بالاسم نفسه في src/partials/pages/.
الملفان src/locales/generated.js وsrc/data/navigation.js مولّدان. مصدرهما tools/manifest.mjs وdocs/.
تُنسخ الأصول في public/ دون معالجة. إذا أردت أن يحسّن Vite صورة ما، فاستوردها من src/.
كل ما في src/ يُرسل إلى المتصفح؛ لا تضع ملفات الأدوات أو الوثائق هناك.

خريطة وحدات النواة

الوحدة	المسؤولية
`dom.js`	المحددات، العرض، الأحداث، أدوات الفئات
`theme.js`	السمة، لوحة الألوان، التخطيط، الكثافة، حجم الخط، نمط الشريط الجانبي
`layout.js`	الهيكل، الشريط الجانبي، وضع الهاتف، التخطيط بعمودين
`chrome.js`	لوحة الأوامر، الاختصارات، الإشعارات، محرر الأدوات، المخصِّص
`datatable.js`	جدول بيانات كامل (بحث، فلترة، ترتيب، أعمدة، تحديد، تصدير)
`charts.js`	مظهر موحّد لـ ApexCharts للوضعين الفاتح والداكن
`calendar.js` / `jalali.js`	تقويم الشهر/الأسبوع/اليوم/القائمة وتحويل التاريخ الهجري الشمسي
`kanban.js`	لوحة سحب وإفلات بـ SortableJS مع حفظ الترتيب
`i18n.js`	اللغة النشطة، `data-i18n`، الاتجاه وإعادة ترتيب النصوص
`numbers.js`	الأرقام الفارسية/العربية/اللاتينية، صيغة العملة، الأعداد المختصرة
`toast.js` / `modal.js`	الرسائل في أربعة مواضع ونوافذ التأكيد
`form.js` / `ui.js`	التحقق، حالات النماذج، التبويبات، الأكورديون، الطباعة

ملاحظة: ترتيب التشغيل في main.js مهم: i18n → theme → layout → dropdowns → chrome → forms → ui → route()

إذا احتاجت وحدة إلى DOM ينشئه متحكم، فيجب استدعاؤها بعد route().