arc/docs/PROJECTS_INTEGRATION_GUIDE.md

📘 راهنمای یکپارچه‌سازی قابلیت پروژه

✅ وضعیت پیاده‌سازی

Backend (100% تکمیل)

• ✅ مدل و Migration
• ✅ Repository و Service
• ✅ API Endpoints (7 endpoint)
• ✅ یکپارچه‌سازی با سرویس‌های موجود

Frontend (80% تکمیل)

• ✅ Models و Services
• ✅ Widget انتخاب پروژه
• ✅ صفحه لیست پروژه‌ها
• ⏳ یکپارچه‌سازی فیلترها (در حال انجام)
• ⏳ یکپارچه‌سازی فرم‌ها (در حال انجام)

---

🚀 نحوه یکپارچه‌سازی

1️⃣ افزودن فیلتر پروژه به صفحات لیست

مرحله 1: افزودن state

class _YourPageState extends State<YourPage> {
  // ... سایر stateها
  int? _selectedProjectId; // فیلتر پروژه
}

مرحله 2: import کردن widget

import 'package:hesabix_ui/widgets/project/project_filter_helper.dart';

مرحله 3: افزودن widget در بخش فیلترها

Widget _buildFilters() {
  return Column(
    children: [
      // ... سایر فیلترها
      
      ProjectFilterWidget(
        businessId: widget.businessId,
        apiClient: widget.apiClient,
        selectedProjectId: _selectedProjectId,
        onChanged: (projectId) {
          setState(() {
            _selectedProjectId = projectId;
          });
          _refreshData();
        },
      ),
    ],
  );
}

مرحله 4: افزودن به additionalFilters

DataTableConfig _buildTableConfig() {
  final additionalFilters = <dynamic>[];
  
  // ... سایر فیلترها
  
  // فیلتر پروژه
  if (_selectedProjectId != null) {
    additionalFilters.add({
      'property': 'project_id',
      'operator': '=',
      'value': _selectedProjectId,
    });
  }
  
  return DataTableConfig(
    // ...
    additionalFilters: additionalFilters,
  );
}

---

2️⃣ افزودن انتخاب پروژه به فرم‌های ثبت سند

مرحله 1: افزودن state

class _YourFormState extends State<YourForm> {
  // ... سایر stateها
  int? _selectedProjectId; // پروژه انتخابی
}

مرحله 2: import کردن widget

import 'package:hesabix_ui/widgets/project/project_selector_widget.dart';

مرحله 3: افزودن widget در فرم

Widget build(BuildContext context) {
  return Form(
    child: Column(
      children: [
        // ... سایر فیلدها
        
        // انتخاب پروژه (اختیاری)
        ProjectSelectorWidget(
          businessId: widget.businessId,
          apiClient: widget.apiClient,
          selectedProjectId: _selectedProjectId,
          onChanged: (projectId) {
            setState(() {
              _selectedProjectId = projectId;
            });
          },
          allowNull: true,
          labelText: 'پروژه (اختیاری)',
        ),
        
        // ... ادامه فرم
      ],
    ),
  );
}

مرحله 4: افزودن به payload

Future<void> _submitForm() async {
  final payload = {
    // ... سایر فیلدها
    
    'project_id': _selectedProjectId, // اضافه کردن پروژه
    
    // ... ادامه payload
  };
  
  // ارسال به API
  await yourService.create(payload);
}

---

📄 صفحات نیازمند به‌روزرسانی

لیست اسناد (فیلتر):

• invoices_list_page.dart - لیست فاکتورها
• receipts_payments_list_page.dart - لیست دریافت/پرداخت
• expense_income_list_page.dart - لیست درآمد/هزینه
• documents_page.dart - لیست کلی اسناد

فرم‌های ثبت سند (selector):

• new_invoice_page.dart - ثبت فاکتور
• فرم‌های دریافت/پرداخت
• فرم‌های درآمد/هزینه

---

🔧 اجرای Migration

برای فعال‌سازی در دیتابیس:

cd hesabixAPI
alembic upgrade head

---

🧪 تست

تست Backend:

# تست API endpoints
curl -X GET "http://localhost:8000/api/v1/businesses/1/projects" \
  -H "Authorization: Bearer YOUR_TOKEN"

تست Frontend:

1. ورود به سیستم
2. رفتن به صفحه "پروژه‌ها"
3. افزودن پروژه جدید
4. ثبت فاکتور با پروژه
5. فیلتر فاکتورها بر اساس پروژه

---

📚 API Endpoints

Method	Endpoint	توضیحات
POST	/api/v1/businesses/{id}/projects	ایجاد پروژه
GET	/api/v1/businesses/{id}/projects	لیست پروژه‌ها
GET	/api/v1/businesses/{id}/projects/active	پروژه‌های فعال (کمبوباکس)
GET	/api/v1/projects/{id}	جزئیات پروژه
PUT	/api/v1/projects/{id}	ویرایش پروژه
DELETE	/api/v1/projects/{id}	حذف پروژه
GET	/api/v1/projects/{id}/documents	اسناد پروژه

---

💡 نکات مهم

1. اختیاری بودن: پروژه در همه جا اختیاری است و اجباری نیست
2. فیلتر خودکار: فیلتر پروژه به صورت خودکار با سایر فیلترها ترکیب می‌شود
3. اعتبارسنجی: پروژه باید به همان کسب‌وکار تعلق داشته باشد
4. وضعیت: فقط پروژه‌های فعال در کمبوباکس نمایش داده می‌شوند
5. آمار: آمار مالی هر پروژه قابل مشاهده است

---

🐛 عیب‌یابی

خطای "PROJECT_NOT_FOUND":

• بررسی کنید پروژه به همان کسب‌وکار تعلق داشته باشد
• بررسی کنید پروژه فعال (is_active=true) باشد

خطای "CURRENCY_NOT_FOUND":

• ارز پروژه باید معتبر باشد
• می‌توانید بدون ارز هم پروژه ایجاد کنید (null)

فیلتر کار نمی‌کند:

• بررسی کنید additionalFilters به DataTableConfig اضافه شده باشد
• بررسی کنید _refreshData() بعد از تغییر فیلتر صدا زده شود

---

📞 پشتیبانی

در صورت بروز مشکل، موارد زیر را بررسی کنید:

1. Migration اجرا شده باشد
2. Import های لازم انجام شده باشد
3. Widget ها به درستی configure شده باشند
4. API Token معتبر باشد

---

✨ پیاده‌سازی توسط AI Assistant - دسامبر 2025