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

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	بدون قالب (همان عدد خام)

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"})

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

وقتی از 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 در استودیو (نیازمند reports.export). خروجی همان Spec را به PDF امن تبدیل می‌کند.

از دکمه 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 نشان می‌دهد. با تنظیم تقویم و قالب عدد، گزارش‌ها دقیقاً به سبک کسب‌وکار شما نمایش داده می‌شوند.