راهنمای کامل Hscript ، زبان گزارش سازی حسابیکس

این راهنما برای کاربران عادی و گزارش‌نویسان نوشته شده است. هدف آن توضیح ساده و کامل سیستم گزارش‌ساز اسکریپتی حسابیکس است؛ از ورود به صفحه تا ساخت داشبورد، قالب‌بندی عدد/تاریخ، خروجی PDF/Excel و کار با هوش مصنوعی.

HScript چیست؟ یک زبان ساده شبیه پایتون است که داخل حسابیکس اجرا می‌شود. با آن می‌توانید داده بگیرید، محاسبه کنید و گزارش/داشبورد بسازید — بدون دسترسی مستقیم به دیتابیس و بدون خطر اجرای کد ناامن.

۱) از کجا شروع کنیم؟

مسیر دسترسی

1. وارد پنل کسب‌وکار شوید.
2. از منوی راست، بخش سرویس‌ها و افزونه‌ها، گزینه گزارش‌ساز اسکریپتی را باز کنید.
3. یا از صفحه گزارش‌ها کارت گزارش‌ساز اسکریپتی را انتخاب کنید.
4. آدرس مستقیم: /business/{شناسه-کسب‌وکار}/hscript

دسترسی لازم

کار	دسترسی موردنیاز
دیدن/اجرا/ذخیره گزارش	reports → view
خروجی PDF و Excel	reports → export

اگر دسترسی ندارید، از مدیر کسب‌وکار بخواهید مجوز گزارش‌ها را برای شما فعال کند.

افزونه و سقف استفاده

• بدون خرید افزونه هم می‌توانید کار کنید (پلن رایگان با سقف محدود).
• با فعال‌سازی افزونه گزارش‌ساز اسکریپتی (HScript) از بازار افزونه‌ها، سقف تعداد گزارش ذخیره‌شده و تعداد اجرا بالاتر می‌رود.
• در بالای صفحه، در صورت نیاز بنر ارتقا نمایش داده می‌شود.

۲) آشنایی با صفحه استودیو

وقتی گزارش جدید می‌سازید یا یکی را ویرایش می‌کنید، وارد استودیو HScript می‌شوید.

بخش	کاربرد
عنوان گزارش	نامی که در فهرست گزارش‌ها دیده می‌شود
ادیتور اسکریپت (چپ‌چین)	محل نوشتن کد HScript
پارامترها (JSON)	مقادیر متغیر مثل بازه تاریخ؛ اختیاری
پیش‌نمایش	نتیجه KPI، جدول و نمودار بعد از اجرا
اعتبارسنجی	فقط بررسی نحو اسکریپت (بدون گرفتن داده)
اجرا	اجرای واقعی و ساخت پیش‌نمایش
ذخیره / انتشار	ذخیره پیش‌نویس یا انتشار برای استفاده
PDF / Excel	خروجی فایل (نیازمند دسترسی export)
از AI بساز	کمک گرفتن از هوش مصنوعی برای نوشتن/اصلاح اسکریپت

نکته: ادیتور کد همیشه چپ‌چین (LTR) است تا خواندن کد راحت باشد؛ حتی اگر پنل شما راست‌چین باشد.

۳) اولین گزارش در ۳۰ ثانیه

اسکریپت نمونه زیر را در استودیو بگذارید و دکمه اجرا را بزنید:

report.calendar("jalali")
report.number_format(style="western")
report.dashboard(columns=12)
report.title("داشبورد فروش")
rows = invoices.all(limit=50)
report.kpi("تعداد فاکتور", rows.count(), format="integer", span=4)
report.kpi("جمع بدهکار", rows.sum("total_debit"), format="currency", span=4)
report.card("وضعیت", "آماده", subtitle="پیش‌نمایش", span=4)
report.row_break()
top_rows = rows.top(10, by="total_debit")
report.bar_chart(top_rows, x="code", y="total_debit", title="بیشترین بدهکار", span=6)
report.table(
  rows.limit(15),
  columns=["code", "document_date", "total_debit", "total_credit"],
  formats={"total_debit": "currency", "total_credit": "currency"},
  title="آخرین فاکتورها",
  span=6
)

اگر داده فاکتور داشته باشید، KPI، نمودار و جدول را در پیش‌نمایش می‌بینید.

۴) مفاهیم پایه به زبان ساده

داده از کجا می‌آید؟

شما SQL نمی‌نویسید. فقط از درگاه‌های مجاز استفاده می‌کنید:

ماژول	معنی ساده	مثال
invoices	فاکتورها/اسناد فروش و مشابه	invoices.all(limit=50)
customers	مشتریان	customers.all(limit=100)
products	کالا/خدمات	products.all(limit=100)
payments	دریافت/پرداخت	payments.this_month()

همیشه فقط دادهٔ همین کسب‌وکار برمی‌گردد؛ نمی‌توانید به کسب‌وکار دیگر دسترسی پیدا کنید.

نتیجه گزارش چیست؟

خروجی یک Report Spec است: ساختار استاندارد شامل عنوان، کارت‌های آماری (KPI)، جدول، نمودار و تنظیمات. همین ساختار در پنل، PDF و Excel استفاده می‌شود.

چه چیزهایی ممنوع است؟

• import و دسترسی به فایل/شبکه
• SQL خام و دستورات سیستم‌عامل
• تغییر business_id یا دور زدن امنیت

این محدودیت‌ها عمدی است تا گزارش‌نویسی امن بماند.

۵) بلوک‌های گزارش (report.*)

عنوان و متن

report.title("گزارش فروش ماه")
report.heading("خلاصه", level=2)
report.text("این گزارش به‌صورت خودکار ساخته شده است.")
report.section("جزئیات")

KPI و کارت

report.kpi("تعداد", 120, format="integer")
report.kpi("مبلغ", 15000000, format="currency", hint="ریال")
report.card("وضعیت", "فعال", subtitle="تا امروز")

جدول

rows = invoices.all(limit=30)
report.table(
  rows,
  columns=["code", "document_date", "total_debit"],
  formats={"total_debit": "currency"},
  title="فاکتورها"
)

نمودار

data = rows.top(8, by="total_debit")
report.bar_chart(data, x="code", y="total_debit", title="بیشترین‌ها")
report.line_chart(data, x="code", y="total_debit", title="روند")
report.pie_chart(data, label="code", value="total_debit", title="سهم")

داشبورد و چیدمان

report.dashboard(columns=12)
report.kpi("A", 1, span=4)
report.kpi("B", 2, span=4)
report.kpi("C", 3, span=4)
report.row_break()
report.table(rows, span=12)

• columns: شبکه ۶ یا ۱۲ یا ۲۴ ستونه
• span: عرض هر بلوک در شبکه
• row_break(): رفتن به ردیف بعد

۶) قالب‌بندی اعداد (جداکننده هزارگان و بیشتر)

تنظیم پیش‌فرض گزارش

# سبک غربی: 1,234,567.50
report.number_format(style="western")

# سبک فارسی (جداکننده فارسی): 1٬234٬567٫50
report.number_format(style="fa")

یا دستی:

report.number_format(thousands_sep=",", decimal_sep=".")

قالب‌های آماده

مقدار format	نتیجه نمونه برای ۱۲۳۴۵۶۷٫۵
integer	1,234,568 (گرد شده بدون اعشار)
number	با جداکننده هزارگان
number:2	1,234,567.50
currency یا money	1,234,568 (پیش‌فرض بدون اعشار)
currency:0	1,234,568
decimal:3	1,234,567.500
percent	۱۲٫۵٪ برای مقدار ۱۲٫۵
raw	بدون قالب (همان عدد خام)

در KPI

report.kpi("فروش", 12500000, format="currency")
report.kpi("رشد", 12.5, format="percent")
report.kpi("نرخ", 0.3567, format="number:4")

در جدول (برای هر ستون)

report.table(
  rows,
  columns=["code", "total_debit", "total_credit"],
  formats={
    "total_debit": "currency",
    "total_credit": "currency"
  }
)

قالب‌بندی دستی داخل متن

msg = "جمع کل: " + format_number(2500000, "currency")
report.text(msg)

# معادل:
report.text("جمع: " + numbers.format(2500000, "currency"))

۷) تقویم شمسی و میلادی

حسابیکس دو تقویم دارد: جلالی (شمسی) و میلادی.

تنظیم تقویم گزارش

report.calendar("jalali")      # شمسی
# یا
report.calendar("gregorian")  # میلادی

با این کار:

• تاریخ‌های جدول با همان تقویم نمایش داده می‌شوند
• فیلترهای تاریخی می‌توانند با همان تقویم نوشته شوند

اگر report.calendar ننویسید، معمولاً همان تقویم پنل شما (هدر X-Calendar-Type) استفاده می‌شود.

قالب‌بندی تاریخ

report.calendar("jalali")
report.kpi("امروز", format_date("2026-07-20"))
report.text(dates.format("2026-07-20", calendar="gregorian"))

فیلتر با تاریخ شمسی

report.calendar("jalali")
rows = invoices.filter(
  from_date="1404/01/01",
  to_date="1404/12/29",
  limit=200
)
report.table(rows, columns=["code", "document_date", "total_debit"], formats={"total_debit": "currency"})

اگر سال بین حدود ۱۲۰۰ تا ۱۵۰۰ باشد و با / نوشته شود، سیستم آن را شمسی می‌فهمد و برای جستجو به میلادی تبدیل می‌کند.

۸) کار با جدول داده (HTable)

وقتی از invoices.all() یا مشابه استفاده می‌کنید، یک جدول در حافظه می‌گیرید:

rows = invoices.all(limit=100)
n = rows.count()
s = rows.sum("total_debit")
avg = rows.avg("total_debit")
top10 = rows.top(10, by="total_debit")
few = rows.limit(20)
sorted_rows = rows.sort("document_date", desc=True)

ساخت جدول دستی:

demo = table([

 {"name": "علی", "amount": 1000},
 {"name": "سارا", "amount": 2500}

])
report.table(demo, formats={"amount": "currency"})

۹) مثال‌های کاربردی بیشتر

مثال ۱: فروش ماه جاری

report.calendar("jalali")
report.number_format(style="western")
report.title("فروش این ماه")
rows = invoices.this_month(limit=500)
report.kpi("تعداد", rows.count(), format="integer")
report.kpi("جمع بدهکار", rows.sum("total_debit"), format="currency")
report.table(
  rows.limit(50),
  columns=["code", "document_date", "total_debit"],
  formats={"total_debit": "currency"}
)

مثال ۲: مقایسه ماه قبل

report.calendar("jalali")
cur = invoices.this_month(limit=1000)
prev = invoices.last_month(limit=1000)
report.kpi("این ماه", cur.sum("total_debit"), format="currency")
report.kpi("ماه قبل", prev.sum("total_debit"), format="currency")

مثال ۳: فیلتر سفارشی

report.calendar("jalali")
rows = invoices.filter(
  document_type="invoice_sales",
  from_date="1404/04/01",
  to_date="1404/04/31",
  limit=300
)
report.bar_chart(rows.top(10, by="total_debit"), x="code", y="total_debit", title="۱۰ فاکتور برتر تیر")

مثال ۴: داشبورد دو ستونه

report.dashboard(columns=12)
report.title("نمای کلی")
rows = invoices.all(limit=80)
report.kpi("تعداد", rows.count(), format="integer", span=6)
report.kpi("جمع", rows.sum("total_debit"), format="currency", span=6)
report.row_break()
report.pie_chart(rows.top(5, by="total_debit"), label="code", value="total_debit", title="سهم ۵ تای برتر", span=6)
report.table(rows.limit(10), columns=["code", "total_debit"], formats={"total_debit": "currency"}, span=6)

مثال ۵: پارامتر ورودی

در کادر پارامترها:

{
  "min_amount": 1000000
}

در اسکریپت:

min_amount = param["min_amount"]
rows = invoices.all(limit=200)

فقط نمایش مبلغ حداقل (نمونه ساده با فیلتر جدول)
report.kpi("آستانه", min_amount, format="currency")
report.table(rows.limit(30), columns=["code", "total_debit"], formats={"total_debit": "currency"})

۱۰) ذخیره، انتشار و خروجی

ذخیره و انتشار

1. ذخیره: گزارش به‌صورت پیش‌نویس نگه داشته می‌شود.
2. انتشار: گزارش برای استفاده/اجرای بعدی در وضعیت منتشرشده قرار می‌گیرد.
3. بایگانی: گزارش از فهرست فعال خارج می‌شود (حذف نرم).

PDF

از دکمه PDF در استودیو (نیازمند reports.export). خروجی همان Spec را به PDF امن تبدیل می‌کند.

Excel

از دکمه Excel. معمولاً شامل:

• شیت خلاصه (KPIها)
• یک شیت برای هر جدول
• شیت داده نمودارها

۱۱) کمک گرفتن از هوش مصنوعی

1. در استودیو روی از AI بساز کلیک کنید.
2. درخواست خود را بنویسید؛ مثلاً: «گزارش فروش ماه با KPI و نمودار میله‌ای».
3. AI با ابزارهای HScript و مستندات کمک می‌کند.
4. در منوی پیام پاسخ، می‌توانید اعمال به استودیو HScript را بزنید تا اسکریپت مستقیم وارد ادیتور شود.
5. همیشه قبل از اتکا، اجرا و در صورت نیاز اعتبارسنجی کنید.

۱۲) خطاهای رایج و راه حل =

مشکل	علت محتمل	راه حل
خطای نحوی	پرانتز/کوتیشن ناقص یا دستور چندخطی نامعتبر	پیام خطا خط را نشان می‌دهد؛ ساده کنید و دوباره اعتبارسنجی کنید
داده خالی	بازه تاریخ یا نوع سند اشتباه	از all یا بازه وسیع‌تر شروع کنید
تاریخ اشتباه دیده می‌شود	تقویم تنظیم نشده	report.calendar("jalali") بگذارید
عدد بدون جداکننده	قالب مشخص نشده	format="currency" یا formats={...}
دسترسی ندارید	مجوز گزارش	از مدیر دسترسی view/export بگیرید
سقف گزارش پر شده	پلن رایگان	افزونه را فعال کنید یا گزارش‌های قدیمی را حذف/بایگانی کنید

۱۳) نکات امنیتی و محدودیت‌ها (به زبان ساده)

• اسکریپت فقط داده همان کسب‌وکار را می‌بیند.
• تعداد فراخوانی داده، حجم خروجی و زمان اجرا سقف دارد.
• تعداد اجرای زیاد در دقیقه محدود است (برای جلوگیری از فشار به سرور).
• کد خطرناک (فایل، شبکه، import) اجرا نمی‌شود.

۱۴) واژه‌نامه کوتاه

واژه	معنی
HScript	زبان امن گزارش‌نویسی حسابیکس
Spec	ساختار خروجی گزارش (JSON)
KPI	کارت آماری (عدد مهم)
Gateway	درگاه مجاز دریافت داده
Studio	صفحه نوشتن و اجرای اسکریپت
span	عرض بلوک در داشبورد
format	قالب نمایش عدد/مقدار

۱۵) چک‌لیست شروع سریع

1. منوی گزارش‌ساز اسکریپتی را باز کنید
2. گزارش جدید بسازید
3. اسکریپت نمونه را اجرا کنید
4. report.calendar و report.number_format را مطابق نیاز تنظیم کنید
5. جدول/نمودار را شخصی‌سازی کنید
6. ذخیره و در صورت نیاز PDF/Excel بگیرید
7. برای گزارش‌های پیچیده‌تر از AI کمک بگیرید و نتیجه را بازبینی کنید

جمع‌بندی: HScript ابزاری برای ساخت گزارش سفارشی است؛ داده را از درگاه‌های امن می‌گیرد، با دستورات ساده محاسبه می‌کند، و خروجی را به‌صورت داشبورد، PDF یا Excel نشان می‌دهد. با تنظیم تقویم و قالب عدد، گزارش‌ها دقیقاً به سبک کسب‌وکار شما نمایش داده می‌شوند.