hesabixSite/WALLET_INTEGRATION.md

راهنمای اتصال کیف پول به شبکه BSC

ویژگی‌های پیاده‌سازی شده

1. Entity و Database

• ✅ Entity Wallet با فیلدهای کامل
• ✅ رابطه One-to-Many با User
• ✅ Migration برای جدول wallets
• ✅ Repository با متدهای مفید

2. Backend API

• ✅ WalletController با endpoints کامل
• ✅ WalletService برای منطق کسب‌وکار
• ✅ WalletConnectFormType برای فرم‌ها
• ✅ اعتبارسنجی و امنیت

3. Frontend

• ✅ JavaScript برای اتصال کیف پول‌ها
• ✅ پشتیبانی از MetaMask و Trust Wallet
• ✅ رابط کاربری در پروفایل
• ✅ مدیریت کیف پول‌ها (حذف، فعال/غیرفعال، تنظیم اصلی)

4. امکانات

• ✅ اتصال حداکثر 5 کیف پول per user
• ✅ تنظیم کیف پول اصلی
• ✅ فعال/غیرفعال کردن کیف پول‌ها
• ✅ حذف کیف پول‌ها
• ✅ تأیید مالکیت با امضای دیجیتال
• ✅ نمایش آدرس کوتاه شده

API Endpoints

اتصال کیف پول

POST /api/wallet/connect
{
    "walletAddress": "0x...",
    "walletType": "MetaMask",
    "signature": "..."
}

لیست کیف پول‌ها

GET /api/wallet/list

تنظیم کیف پول اصلی

PUT /api/wallet/{id}/set-primary

تغییر وضعیت

PUT /api/wallet/{id}/toggle-status

حذف کیف پول

DELETE /api/wallet/{id}

دریافت پیام برای امضا

GET /api/wallet/sign-message

نحوه استفاده

1. برای کاربران

1. وارد پروفایل خود شوید
2. به بخش "مدیریت کیف پول‌ها" بروید
3. نوع کیف پول خود را انتخاب کنید
4. روی "اتصال کیف پول" کلیک کنید
5. در کیف پول خود تراکنش را تأیید کنید
6. کیف پول شما متصل خواهد شد

2. برای توسعه‌دهندگان

استفاده از WalletService

// اتصال کیف پول
$result = $walletService->connectWallet($user, $address, $type, $signature);

// دریافت کیف پول‌های کاربر
$wallets = $walletService->getUserWallets($user);

// تنظیم کیف پول اصلی
$walletService->setPrimaryWallet($user, $walletId);

استفاده از Repository

// پیدا کردن کیف پول اصلی
$primaryWallet = $walletRepository->findPrimaryWalletByUser($user);

// بررسی وجود آدرس
$exists = $walletRepository->isWalletAddressExists($address);

امنیت

1. اعتبارسنجی

• بررسی فرمت آدرس کیف پول
• تأیید امضای دیجیتال
• محدودیت تعداد کیف پول‌ها

2. مجوزها

• فقط کاربران وارد شده
• دسترسی فقط به کیف پول‌های خود
• تأیید برای عملیات حساس

نکات مهم

1. Web3 Integration

• نیاز به MetaMask یا Trust Wallet
• پشتیبانی از شبکه BSC
• امضای پیام برای تأیید مالکیت

2. Database

• جدول wallets ایجاد شده
• رابطه با جدول user
• Indexes برای عملکرد بهتر

3. Frontend

• JavaScript در /public/js/wallet-connect.js
• CSS در template پروفایل
• آیکون کیف پول اضافه شده

مراحل بعدی (اختیاری)

1. بهبود امنیت

   • پیاده‌سازی تأیید امضای واقعی با Web3
   • اضافه کردن rate limiting
   • لاگ‌گیری عملیات

2. ویژگی‌های اضافی

   • نمایش موجودی کیف پول
   • تاریخچه تراکنش‌ها
   • اتصال به سایر شبکه‌ها

3. بهبود UI/UX

   • انیمیشن‌های بهتر
   • پیام‌های خطای دقیق‌تر
   • راهنمای استفاده

تست

برای تست عملکرد:

1. یک کاربر ایجاد کنید
2. وارد پروفایل شوید
3. کیف پول MetaMask را اتصال دهید
4. عملیات مختلف را تست کنید

پشتیبانی

در صورت بروز مشکل:

1. Console مرورگر را بررسی کنید
2. لاگ‌های Symfony را چک کنید
3. اتصال Web3 را بررسی کنید