نمایش مبدأ برای راهنمای Hesabix CLI

این راهنما برای سروری است که Hesabix با '''deploy.sh''' نصب شده و دستور '''hesabix''' در مسیر سیستم (معمولاً <code>/usr/local/bin/hesabix</code>) در دسترس است. همهٔ دستورات '''باید با کاربر ریشه''' اجرا شوند (مثلاً <code>sudo hesabix ...</code>).

== پیش‌نیازها و مفاهیم ==

* '''مسیر ریشهٔ نصب (APP_ROOT)''' به‌طور پیش‌فرض <code>/opt/hesabix</code> است. اگر متغیر محیطی <code>APP_ROOT</code> روی سرور شما متفاوت است، اسکریپت از همان مقدار استفاده می‌کند.
* فایل '''<code>${APP_ROOT}/.deploy_env</code>''' پس از اولین deploy ساخته می‌شود و شامل تنظیماتی مانند آدرس مخزن Git، نام شاخه، دامنهٔ API و UI است. برای دستورات <code>-update</code> و <code>-services</code> وجود این فایل '''ضروری''' است.
* منبع رسمی اسکریپت CLI در مخزن: <code>${APP_ROOT}/app/scripts/hesabix</code> (معادل <code>app/scripts/hesabix</code> در checkout).
* اگر بدون ریشه اجرا کنید، پیام خطا می‌گیرید و اسکریپت متوقف می‌شود.

== خلاصهٔ دستورات ==
{| class="wikitable"
!دستور
!کاربرد
|-
|<code>sudo hesabix -update</code>
|به‌روزرسانی کامل از مخزن، مایگریشن، ری‌استارت سرویس‌ها، بیلد وب Flutter، همگام‌سازی فایل‌های UI و reload nginx
|-
|<code>sudo hesabix -update -source URL -branch NAME</code>
|همان به‌روزرسانی با '''یک‌بار''' نادیده گرفتن آدرس مخزن و نام شاخهٔ ذخیره‌شده در <code>.deploy_env</code>
|-
|<nowiki>stop|restart|status}</nowiki>
|کنترل واحدهای systemd هسابیکس (و در صورت نصب، pgAdmin4)
|-
|<code>sudo hesabix -cli reload</code>
|کپی مجدد اسکریپت CLI از مخزن به <code>/usr/local/bin/hesabix</code>
|-
|<code>sudo hesabix -h</code> یا <code>sudo hesabix --help</code>
|نمایش راهنمای کوتاه
|}

== hesabix -update (به‌روزرسانی سرور) ==

=== هدف ===
اجرای '''pipeline کامل به‌روزرسانی''' که در فایل <code>${APP_ROOT}/app/update.sh</code> پیاده‌سازی شده است: گرفتن آخرین کد از Git، نصب/به‌روزرسانی وابستگی‌های Python، اجرای مایگریشن Alembic، ری‌استارت سرویس‌های بک‌اند، بیلد release وب Flutter، کپی خروجی به وب‌سرور و در نهایت '''reload''' nginx.

=== نحوهٔ اجرا ===
<pre>
sudo hesabix -update
sudo hesabix -update -source https://example.com/your-repo.git -branch main
</pre>

* '''<code>-source REPO_URL</code>''' (اختیاری): برای '''همان اجرا''' مقدار <code>REPO_URL</code> را override می‌کند (قبل از فراخوانی <code>update.sh</code> به صورت <code>export REPO_URL=...</code>).
* '''<code>-branch NAME</code>''' (اختیاری): برای همان اجرا نام شاخهٔ Git را override می‌کند (<code>export BRANCH=...</code>).
* اگر هر دو را ندهید، مقادیر از <code>.deploy_env</code> (پس از <code>source</code> شدن) خوانده می‌شوند.

=== گام‌های اصلی (خلاصهٔ فنی) ===

# '''Git:''' رفتن به <code>${APP_ROOT}/app</code>، هم‌راستا کردن remote با <code>REPO_URL</code> در صورت تفاوت، <code>fetch</code>، checkout شاخه روی <code>origin/&#x3C;BRANCH&#x3E;</code> و <code>pull --ff-only</code>. اگر pull معمولی به‌دلیل تغییرات محلی یا عدم fast-forward شکست بخورد، اسکریپت با '''<code>git reset --hard origin/&#x3C;BRANCH&#x3E;</code>''' سعی در هم‌راستاسازی اجباری می‌کند (تغییرات و commitهای محلی روی آن clone از بین می‌روند).
# '''بک‌اند:''' فعال‌سازی venv در <code>hesabixAPI</code>، تنظیم آینهٔ pip هسابیکس، نصب editable با pip، اطمینان از سازگاری جدول <code>alembic_version</code>، اجرای <code>alembic upgrade head</code>، <code>chown</code> به <code>www-data</code>، <code>systemctl restart</code> برای <code>hesabix-api</code>، <code>hesabix-rq-worker</code> و <code>hesabix-notification-moderation</code> و بررسی فعال بودن API.
# '''فرانت (Flutter web):''' به‌روزرسانی اختیاری SDK در <code>/opt/flutter</code>، بیلد با <code>build_web.sh</code> (حالت release، تمیز کردن، نصب وابستگی‌ها)، آدرس پایهٔ API از روی دامنه و در صورت وجود گواهی Let's Encrypt (یا <code>API_PUBLIC_SCHEME</code>)، rsync خروجی به <code>/var/www/&#x3C;UI_DOMAIN&#x3E;/</code>.
# '''Nginx:''' تنظیم <code>client_max_body_size</code> برای API در صورت وجود فایل کانفیگ، اجرای اسکریپت اختیاری برای قوانین کش UI، <code>nginx -t</code> و <code>systemctl reload nginx</code>.
# '''سلامت API (اختیاری):''' در صورت وجود <code>curl</code>، تلاش برای فراخوانی health endpoint (خطا در این مرحله '''مرگبار''' نیست).

=== لاگ ===
خروجیٔ زمانی به فایل '''<code>${APP_ROOT}/update.log</code>''' نیز append می‌شود؛ برای عیب‌یابی پس از به‌روزرسانی این فایل را بررسی کنید.

=== پیش‌نیازهای مهم ===

* وجود <code>${APP_ROOT}/app/.git</code> و متغیرهای '''<code>API_DOMAIN</code>'''، '''<code>UI_DOMAIN</code>'''، '''<code>BRANCH</code>'''، '''<code>REPO_URL</code>''' (در env یا <code>.deploy_env</code>).
* وجود <code>${APP_ROOT}/.db_password</code> برای اتصال PostgreSQL در مراحل مایگریشن.
* وجود venv بک‌اند: <code>hesabixAPI/.venv</code> (در غیر این صورت باید یک بار deploy کامل انجام شده باشد).
* نصب Flutter در PATH سرور (طبق deploy).

'''نکتهٔ امنیتی:''' اگر روی سرور تغییرات محلی در مخزن دارید که نمی‌خواهید از دست بروند، قبل از <code>-update</code> از آن‌ها '''پشتیبان''' بگیرید؛ مسیر بازیابی خودکار ممکن است با reset سخت، تاریخچهٔ محلی را حذف کند.

== hesabix -services (مدیریت سرویس‌های systemd) ==

=== واحدهای هدف ===

* '''هسته (اجباری):''' <code>hesabix-api</code>، <code>hesabix-rq-worker</code>، <code>hesabix-notification-moderation</code>
* '''اختیاری:''' اگر واحد <code>pgadmin4.service</code> روی سیستم '''loaded''' باشد، در start/restart/stop/status لحاظ می‌شود.

=== اعمال‌ها ===
{| class="wikitable"
!عمل
!توضیح
|-
|<code>start</code>
|روشن کردن سرویس‌های هسته به ترتیب، سپس pgAdmin4 (در صورت وجود)
|-
|<code>stop</code>
|خاموش کردن به ترتیب '''معکوس''' (ابتدا pgAdmin4 در صورت وجود، سپس هسته)
|-
|<code>restart</code>
|تنظیم drop-in محیطی برای API (<code>HESABIX_ALLOW_SUDO_JOURNALCTL=1</code>)، <code>daemon-reload</code> و ری‌استارت همه
|-
|<code>status</code>
|نمایش وضعیت هر واحد با <code>systemctl status</code>
|}
<pre>
sudo hesabix -services status
sudo hesabix -services restart
</pre>اگر یکی از واحدهای هسته روی میزبان نصب/loaded نباشد، اسکریپت با پیام خطا خارج می‌شود و از شما می‌خواهد مرحلهٔ backend در deploy را دوباره اجرا کنید.

== hesabix -cli reload (به‌روزرسانی خودِ دستور hesabix) ==
گاهی پس از <code>git pull</code> دستی یا deploy، نسخهٔ نصب‌شده در <code>/usr/local/bin/hesabix</code> با نسخهٔ داخل مخزن (<code>${APP_ROOT}/app/scripts/hesabix</code>) یکی نیست. این دستور:

* فایل منبع را از مخزن می‌خواند، در یک فایل موقت کپی می‌کند، با '''sha256sum''' یا '''cmp''' با مقصد مقایسه می‌کند؛
* اگر یکسان باشد: پیام «hesabix CLI is already up-to-date.» و خروج بدون تغییر؛
* اگر متفاوت باشد: جایگزینی اتمی با <code>mv</code> و <code>chmod 755</code> روی <code>/usr/local/bin/hesabix</code>.
<pre>
sudo hesabix -cli reload
</pre>'''مهم:''' <code>-cli</code> را '''نباید''' هم‌زمان با <code>-update</code> یا <code>-services</code> ترکیب کنید؛ اسکریپت خطا می‌دهد. همچنین <code>-update</code> و <code>-services</code> را '''نمی‌توان''' در یک خط با هم زد.

تنها action پشتیبانی‌شده برای <code>-cli</code> در حال حاضر '''reload''' است.

== محدودیت‌های ترکیب آرگومان‌ها ==

* <code>-cli ...</code> '''فقط به تنهایی'''.
* یا <code>-update</code> '''یا''' <code>-services ACTION</code> — نه هر دو.
* بدون آرگومان (و بدون حالت خاص): در صورت وجود deploy، رفتار پیش‌فرض نمایش usage است (بسته به اینکه آیا فقط CLI خالی فراخوانی شده یا نه؛ برای دیدن قطعی، <code>-h</code> بزنید).

== رفع اشکال سریع ==

* API بالا نمی‌آید پس از update: <code>journalctl -u hesabix-api -n 100 --no-pager</code>
* مایگریشن خطا داد: لاگ <code>update.log</code> و خروجی Alembic در همان اجرا
* Nginx reload نشد: خروجی <code>nginx -t</code> در مرحلهٔ ۴ اسکریپت update

----''این صفحه از رفتار اسکریپت‌های <code>app/scripts/hesabix</code> و <code>app/update.sh</code> در مخزن Hesabix استخراج شده است؛ در صورت تغییر نسخه، متن را با همان فایل‌ها تطبیق دهید.''