add redme.md
This commit is contained in:
parent
4d7a31409c
commit
030438c236
282
README.md
Normal file
282
README.md
Normal file
|
|
@ -0,0 +1,282 @@
|
||||||
|
# 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. کلون کردن پروژه
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone <repository-url>
|
||||||
|
cd hesabix
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. راه‌اندازی Backend (API)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# ورود به دایرکتوری 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)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# ورود به دایرکتوری UI
|
||||||
|
cd hesabixUI/hesabix_ui
|
||||||
|
|
||||||
|
# نصب وابستگی‌ها
|
||||||
|
flutter pub get
|
||||||
|
|
||||||
|
# اجرای اپلیکیشن
|
||||||
|
flutter run
|
||||||
|
```
|
||||||
|
|
||||||
|
## اسکریپت‌های کمکی
|
||||||
|
|
||||||
|
پروژه شامل چندین اسکریپت کمکی برای سهولت در استفاده است:
|
||||||
|
|
||||||
|
### اجرای API محلی
|
||||||
|
```bash
|
||||||
|
./run_local.sh serve # اجرای سرور API
|
||||||
|
./run_local.sh migrate # اجرای migration ها
|
||||||
|
./run_local.sh test # اجرای تست‌ها
|
||||||
|
```
|
||||||
|
|
||||||
|
### اجرای Flutter Web
|
||||||
|
```bash
|
||||||
|
./run_web.sh # اجرای وب اپلیکیشن
|
||||||
|
./run_web.sh --port 8081 # اجرا روی پورت مشخص
|
||||||
|
./run_web.sh --mode debug # اجرا در حالت debug
|
||||||
|
```
|
||||||
|
|
||||||
|
### اجرای Flutter Linux Desktop
|
||||||
|
```bash
|
||||||
|
./run_linux.sh # اجرای دسکتاپ اپلیکیشن
|
||||||
|
./run_linux.sh --mode release # اجرا در حالت release
|
||||||
|
./run_linux.sh --clean # پاک کردن build و اجرای مجدد
|
||||||
|
```
|
||||||
|
|
||||||
|
## تنظیمات محیط
|
||||||
|
|
||||||
|
### متغیرهای محیطی API (.env)
|
||||||
|
|
||||||
|
```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، از متغیر محیطی استفاده کنید:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
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
|
||||||
|
|
||||||
|
## توسعه و مشارکت
|
||||||
|
|
||||||
|
### اجرای تست‌ها
|
||||||
|
```bash
|
||||||
|
# تست‌های Backend
|
||||||
|
cd hesabixAPI
|
||||||
|
pytest
|
||||||
|
|
||||||
|
# تست‌های Frontend
|
||||||
|
cd hesabixUI/hesabix_ui
|
||||||
|
flutter test
|
||||||
|
```
|
||||||
|
|
||||||
|
### کد استایل
|
||||||
|
```bash
|
||||||
|
# Backend
|
||||||
|
black .
|
||||||
|
ruff check .
|
||||||
|
|
||||||
|
# Frontend
|
||||||
|
flutter analyze
|
||||||
|
```
|
||||||
|
|
||||||
|
### ساخت برای تولید
|
||||||
|
```bash
|
||||||
|
# ساخت 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](LICENSE) منتشر شده است.
|
||||||
|
|
||||||
|
## پشتیبانی
|
||||||
|
|
||||||
|
برای گزارش باگ یا درخواست ویژگی جدید، لطفاً issue جدیدی در repository ایجاد کنید.
|
||||||
|
|
||||||
|
## تیم توسعه
|
||||||
|
|
||||||
|
- **Backend**: FastAPI + SQLAlchemy + MySQL
|
||||||
|
- **Frontend**: Flutter + Material Design
|
||||||
|
- **DevOps**: Docker + Scripts
|
||||||
|
- **Documentation**: Markdown + Persian
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Hesabix** - سیستم حسابداری مدرن برای کسب‌وکارهای ایرانی 🇮🇷
|
||||||
Loading…
Reference in a new issue