مستندات دیوان

دیوان یک قالب HTML پنل مدیریت است که از پایه برای زبان فارسی و چیدمان راست‌به‌چپ طراحی و پیاده‌سازی شده است. برخلاف قالب‌هایی که نسخه‌ی لاتین را آینه می‌کنند، در دیوان همه‌ی مقادیر جهت‌دار با ویژگی‌های منطقی CSS (margin-inline، inset-inline و …) نوشته شده‌اند؛ به همین دلیل تغییر جهت به LTR بدون هیچ فایل اضافه‌ای انجام می‌شود.

دیوان علاوه بر لایه‌ی ظاهری، یک لایه‌ی داده و یک بک‌اند مرجعِ اجراشدنی هم دارد؛ یعنی می‌توانید ظرف چند دقیقه پنل را با داده‌ی واقعی و پایگاه‌داده بالا بیاورید و بعد آن را به بک‌اند خودتان وصل کنید.

برای استفاده از خروجی آماده (پوشه‌ی dist)

• وب‌سرورهر وب‌سروری که فایل ایستا سرو کند (Apache، Nginx، IIS، LiteSpeed)
• مرورگرChrome/Edge ۹۰+، Firefox ۹۰+، Safari ۱۵+
• Node.jsلازم نیست

برای توسعه یا اجرای بک‌اند مرجع

• Node.jsنسخه ۲۲ یا بالاتر (برای ماژول داخلی node:sqlite)
• npmلازم نیست — پروژه هیچ بسته‌ای نصب نمی‌کند

روش اول — استفاده‌ی مستقیم از خروجی آماده

1. فایل فشرده را باز کنید.
2. محتویات پوشه‌ی dist/ را روی هاست خود آپلود کنید.
3. نشانی سایت را باز کنید؛ پنل با داده‌ی نمونه بالا می‌آید.

روش دوم — اجرای بک‌اند مرجع (پنل + پایگاه‌داده)

# در ریشه‌ی پروژه
node backend/server.js

# پنل روی این نشانی بالا می‌آید:
# http://localhost:4405

در نخستین اجرا، پایگاه‌داده‌ی SQLite ساخته و با داده‌ی نمونه پر می‌شود. برای ساخت دوباره‌ی داده، فایل backend/divan.db را پاک کنید.

روش سوم — توسعه روی سورس

# ساخت خروجی از روی source/
node build/build.js

# اجرای تست‌های هسته
node build/test-core.mjs

DIVAN/
├── dist/                  خروجی آماده‌ی آپلود (همین را روی هاست بگذارید)
│   ├── *.html             ۲۱ صفحه‌ی کامل
│   └── assets/
│       ├── css/           divan.css و نسخه‌ی فشرده
│       ├── js/            ماژول‌های ES
│       ├── fonts/         وزیرمتن (مجوز OFL)
│       └── img/           لوگو و آیکون سایت
│
├── source/                سورس قابل ویرایش
│   ├── layouts/           چیدمان‌های app، auth و blank
│   ├── partials/          سایدبار، نوار بالا، پاورقی، head
│   ├── pages/             محتوای هر صفحه (بدون تکرار پوسته)
│   ├── styles/            توکن‌ها، پایه، چیدمان، کامپوننت‌ها
│   ├── scripts/
│   │   ├── core/          jalali، format، validate، api، dom، icons
│   │   ├── components/    جدول، نمودار، تاریخ، مودال، فرم، اعلان
│   │   └── pages/         منطق اختصاصی هر صفحه
│   └── assets/            فونت و تصاویر
│
├── backend/               بک‌اند مرجع Node.js + SQLite
├── build/                 اسکریپت ساخت و تست
└── documentation/         همین مستندات به‌صورت آفلاین

همه‌ی تنظیمات در یک فایل جمع شده‌اند: assets/js/core/config.js (در سورس: source/scripts/core/config.js).

export const config = {
  app: { name: 'دیوان', version: '1.0.0' },

  // 'demo' = داده‌ی محلی بدون سرور | 'rest' = اتصال به API واقعی
  dataSource: 'demo',

  rest: {
    baseUrl: '/api/v1',
    authHeader: 'Authorization',
    credentials: 'same-origin',
    timeout: 15000,
    retry: 1,
  },

  ui: {
    theme: 'light',          // light | dark | system
    accent: 'lapis',         // lapis | turquoise | saffron | pomegranate
    direction: 'rtl',        // rtl | ltr
    density: 'comfortable',  // comfortable | compact
    sidebar: 'expanded',     // expanded | mini
    perPage: 10,
    currency: 'toman',       // toman | rial
  },
};

مقادیر ui فقط پیش‌فرض هستند؛ انتخاب کاربر در localStorage ذخیره می‌شود و بر آن‌ها اولویت دارد.

پنل هرگز مستقیم fetch نمی‌زند؛ همه‌ی صفحات فقط با core/api.js صحبت می‌کنند. پشت این لایه دو آداپتور وجود دارد.

سه گام تا اتصال

1. در config.js مقدار dataSource را به 'rest' تغییر دهید و baseUrl را بنویسید.
2. نقاط پایانی جدول بخش بعد را در بک‌اند خود پیاده کنید (یا از بک‌اند مرجع الگو بگیرید).
3. پاسخ‌ها را در پوشش استاندارد برگردانید. اگر ساختار API شما متفاوت است، تنها تابع unwrap در core/adapters/rest.js را تغییر دهید.

قالب پاسخ

// موفق — تک‌آیتم
{ "ok": true, "data": { "id": 1, "code": "ORD-1405123456" } }

// موفق — فهرست صفحه‌بندی‌شده
{
  "ok": true,
  "data": [ ... ],
  "meta": { "total": 240, "page": 1, "perPage": 10, "pages": 24 }
}

// ناموفق
{
  "ok": false,
  "error": {
    "code": "validation",
    "message": "اطلاعات وارد شده معتبر نیست.",
    "fields": { "mobile": "شماره موبایل معتبر نیست." }
  }
}

کلیدهای fields با نام name ورودی‌های فرم مطابقت دارند و به‌صورت خودکار زیر همان فیلد نمایش داده می‌شوند.

افزودن صفحه‌ی تازه

یک فایل در source/pages/ بسازید و در ابتدای آن فراداده بنویسید:

<!-- divan
title: انبار
layout: app
script: warehouse
crumbs: داشبورد|index.html > انبار
-->

<div class="page-head">
  <h1 class="page-title">انبار</h1>
</div>

سپس node build/build.js را اجرا کنید؛ صفحه ساخته می‌شود.

ساخت یک جدول داده

import DataTable from '../components/datatable.js';
import api from '../core/api.js';

const table = new DataTable(document.querySelector('[data-table]'), {
  selectable: true,
  columns: [
    { key: 'name', label: 'نام', sortable: true },
    { key: 'price', label: 'قیمت', render: (row) => moneyCell(row.price) },
  ],
  fetch: (params) => api.products.list(params),
  onRowClick: (row) => console.log(row),
});

ساخت نمودار

import { createChart } from '../components/chart.js';

createChart('[data-chart]', {
  type: 'area',              // line | area | bar | stackedBar | donut | sparkline
  labels: ['شنبه', 'یکشنبه'],
  series: [{ name: 'فروش', data: [120, 240] }],
  height: 280,
});

فرم با اعتبارسنجی

<input class="input" name="mobile" data-rules="required|mobile">

import Form from '../components/form.js';
new Form(formElement, {
  onSubmit: async (values) => api.customers.create(values),
});

قواعد آماده: required، email، mobile، landline، nationalId، companyId، iban، card، postalCode، url، username، numeric، password، min:n، max:n، minValue:n، maxValue:n.

تاریخ شمسی

import * as J from '../core/jalali.js';

J.format(new Date(), 'dddd D MMMM YYYY');  // چهارشنبه ۱۱ شهریور ۱۴۰۵
J.parse('1405/06/11');                     // { jy: 1405, jm: 6, jd: 11 }
J.fromNow(iso);                            // ۲ ساعت پیش
J.isLeapYear(1403);                        // true

تغییر رنگ برند

چهار پیش‌تنظیم آماده وجود دارد (لاجوردی، فیروزه‌ای، زعفرانی، اناری). برای رنگ دلخواه، توکن‌های معنایی را در فایل CSS خودتان بازنویسی کنید:

:root {
  --brand:        #0f766e;
  --brand-hover:  #115e59;
  --brand-active: #134e4a;
  --brand-soft:   #f0fdfa;
  --brand-soft-fg:#134e4a;
  --brand-ring:   rgba(15, 118, 110, .3);
}

تغییر فونت

:root { --font-fa: "IRANSansX", "Vazirmatn", Tahoma, sans-serif; }

فایل فونت را در assets/fonts/ بگذارید و @font-face را در styles/base/typography.css اضافه کنید.

تغییر جهت به LTR

هیچ فایل CSS جداگانه‌ای لازم نیست. کافی است dir را روی <html> تغییر دهید (یا از تنظیمات ظاهر پنل استفاده کنید):

<html lang="en" dir="ltr">

ویرایش منوی کناری

فایل source/partials/sidebar.html را ویرایش کنید. صفحه‌ی فعال به‌صورت خودکار از روی نام فایل تشخیص داده و برجسته می‌شود.

سیستم ساخت با Node اجرا می‌شود و هیچ بسته‌ای نصب نمی‌کند:

node build/build.js

این دستور کارهای زیر را انجام می‌دهد:

• چیدمان‌ها، جزءها و صفحات را ترکیب و صفحات کامل HTML می‌سازد
• @importهای CSS را ادغام و نسخه‌ی فشرده تولید می‌کند
• ماژول‌های JS، فونت‌ها و تصاویر را کپی می‌کند
• همه‌ی پیوندهای داخلی و نشانه‌های جایگزین‌نشده را بررسی می‌کند و در صورت خطا شکست می‌خورد