Hesabix - سیستم حسابداری جامع

Hesabix یک سیستم حسابداری کامل و مدرن است که شامل یک API قدرتمند (FastAPI + SQLAlchemy) و رابط کاربری زیبا (Flutter) می‌باشد. این سیستم برای مدیریت مالی کسب‌وکارهای کوچک و متوسط طراحی شده است.

ویژگی‌های اصلی

🚀 API Backend (hesabixAPI)

• FastAPI - فریمورک مدرن و سریع برای ساخت API
• SQLAlchemy - ORM قدرتمند برای مدیریت پایگاه داده
• MySQL - پایگاه داده رابطه‌ای قابل اعتماد
• Alembic - مدیریت migration های پایگاه داده
• Pydantic - اعتبارسنجی و سریالیزاسیون داده‌ها
• JWT Authentication - سیستم احراز هویت امن
• Multi-language Support - پشتیبانی از چندین زبان (فارسی/انگلیسی)
• Jalali Calendar - تقویم شمسی برای کاربران ایرانی

📱 Frontend (hesabixUI)

• Flutter - فریمورک کراس‌پلتفرم برای موبایل، وب و دسکتاپ
• Material Design - رابط کاربری مدرن و زیبا
• Responsive Design - سازگار با تمام اندازه‌های صفحه
• Multi-platform - اجرا روی Android، iOS، Web و Desktop
• Persian Font Support - پشتیبانی کامل از فونت فارسی (Vazirmatn)

ساختار پروژه

hesabix/
├── hesabixAPI/          # Backend API (FastAPI)
│   ├── app/            # کد اصلی اپلیکیشن
│   ├── adapters/       # لایه‌های دسترسی به داده
│   ├── migrations/     # فایل‌های migration پایگاه داده
│   └── tests/          # تست‌های واحد
├── hesabixUI/          # Frontend (Flutter)
│   └── hesabix_ui/     # پروژه Flutter اصلی
├── docs/               # مستندات پروژه
└── scripts/            # اسکریپت‌های کمکی

پیش‌نیازها

برای Backend (API)

• Python 3.11+
• MySQL 8.0+
• pip (Python package manager)

برای Frontend (UI)

• Flutter SDK 3.9.2+
• Dart SDK
• Git

برای Linux Desktop

• GTK+ 3.0 development libraries
• CMake
• Ninja build system
• C++ compiler (clang++ یا gcc)

نصب و راه‌اندازی

1. کلون کردن پروژه

git clone <repository-url>
cd hesabix

2. راه‌اندازی Backend (API)

# ورود به دایرکتوری API
cd hesabixAPI

# ایجاد محیط مجازی
python3 -m venv .venv
source .venv/bin/activate  # در Windows: .venv\Scripts\activate

# نصب وابستگی‌ها
pip install -e .[dev]

# کپی کردن فایل تنظیمات
cp env.example .env

# ویرایش فایل .env و تنظیم اطلاعات پایگاه داده
# DB_USER=root
# DB_PASSWORD=your_password
# DB_HOST=localhost
# DB_PORT=3306
# DB_NAME=hesabixpy

# اجرای migration ها
alembic upgrade head

# اجرای سرور API
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

3. راه‌اندازی Frontend (UI)

# ورود به دایرکتوری UI
cd hesabixUI/hesabix_ui

# نصب وابستگی‌ها
flutter pub get

# اجرای اپلیکیشن
flutter run

اسکریپت‌های کمکی

پروژه شامل چندین اسکریپت کمکی برای سهولت در استفاده است:

اجرای API محلی

./run_local.sh serve    # اجرای سرور API
./run_local.sh migrate  # اجرای migration ها
./run_local.sh test     # اجرای تست‌ها

اجرای Flutter Web

./run_web.sh                    # اجرای وب اپلیکیشن
./run_web.sh --port 8081        # اجرا روی پورت مشخص
./run_web.sh --mode debug       # اجرا در حالت debug

اجرای Flutter Linux Desktop

./run_linux.sh                  # اجرای دسکتاپ اپلیکیشن
./run_linux.sh --mode release   # اجرا در حالت release
./run_linux.sh --clean          # پاک کردن build و اجرای مجدد

تنظیمات محیط

متغیرهای محیطی API (.env)

# تنظیمات عمومی
APP_NAME=Hesabix API
ENVIRONMENT=development
DEBUG=true
API_V1_PREFIX=/api/v1
APP_VERSION=0.1.0

# پایگاه داده
DB_USER=root
DB_PASSWORD=your_password
DB_HOST=localhost
DB_PORT=3306
DB_NAME=hesabixpy
SQLALCHEMY_ECHO=false

# لاگ‌گیری
LOG_LEVEL=INFO

تنظیمات Flutter

برای تنظیم آدرس API در Flutter، از متغیر محیطی استفاده کنید:

flutter run --dart-define API_BASE_URL=http://localhost:8000

API Endpoints

احراز هویت

• POST /api/v1/auth/login - ورود کاربر
• POST /api/v1/auth/register - ثبت نام کاربر
• POST /api/v1/auth/refresh - تمدید توکن

سلامت سیستم

• GET /api/v1/health - بررسی وضعیت API

کسب‌وکار

• GET /api/v1/businesses - لیست کسب‌وکارها
• POST /api/v1/businesses - ایجاد کسب‌وکار جدید
• PUT /api/v1/businesses/{id} - ویرایش کسب‌وکار

محصولات

• GET /api/v1/products - لیست محصولات
• POST /api/v1/products - ایجاد محصول جدید
• PUT /api/v1/products/{id} - ویرایش محصول

فاکتورها و پرداخت‌ها

• GET /api/v1/receipts - لیست فاکتورها
• POST /api/v1/receipts - ایجاد فاکتور جدید
• GET /api/v1/payments - لیست پرداخت‌ها

ویژگی‌های خاص

تقویم شمسی

سیستم از تقویم شمسی پشتیبانی کامل می‌کند و تمام تاریخ‌ها به صورت خودکار تبدیل می‌شوند.

چندزبانه

• پشتیبانی از زبان‌های فارسی و انگلیسی
• امکان اضافه کردن زبان‌های جدید
• ترجمه خودکار رابط کاربری

امنیت

• احراز هویت JWT
• رمزگذاری رمز عبور با Argon2
• اعتبارسنجی ورودی‌ها
• محافظت در برابر SQL Injection

توسعه و مشارکت

اجرای تست‌ها

# تست‌های Backend
cd hesabixAPI
pytest

# تست‌های Frontend
cd hesabixUI/hesabix_ui
flutter test

کد استایل

# Backend
black .
ruff check .

# Frontend
flutter analyze

ساخت برای تولید

# ساخت API
cd hesabixAPI
pip install -e .

# ساخت Flutter
cd hesabixUI/hesabix_ui
flutter build web
flutter build linux
flutter build apk

عیب‌یابی

مشکلات رایج

1. خطای اتصال به پایگاه داده

   • بررسی تنظیمات .env
   • اطمینان از اجرای MySQL
   • بررسی دسترسی‌های کاربر

2. مشکلات Flutter

   • اجرای flutter clean
   • حذف پوشه build
   • اجرای مجدد flutter pub get

3. مشکلات Linux Desktop

   • نصب وابستگی‌های مورد نیاز
   • استفاده از اسکریپت run_linux.sh

لاگ‌ها

• API logs: در کنسول سرور نمایش داده می‌شوند
• Flutter logs: با flutter logs قابل مشاهده است

مجوز

این پروژه تحت مجوز MIT License منتشر شده است.

پشتیبانی

برای گزارش باگ یا درخواست ویژگی جدید، لطفاً issue جدیدی در repository ایجاد کنید.

تیم توسعه

• Backend: FastAPI + SQLAlchemy + MySQL
• Frontend: Flutter + Material Design
• DevOps: Docker + Scripts
• Documentation: Markdown + Persian

---

Hesabix - سیستم حسابداری مدرن برای کسب‌وکارهای ایرانی 🇮🇷