# GET /b2c/v1/wallet/ballance

## Wallet Balance

این اندپوینت برای واکشی موجودی کیف‌پول کاربر در سیستم B2C طراحی شده است. بر اساس `group` (مقدار JWT احراز هویت)، نوع کاربر بین **B2C** و **B2B (colleague)** تشخیص داده می‌شود و سپس موجودی کیف پول از جدول `wallet` با استفاده از کنترلر مالی اصلی (`AccountingController`) فراخوانی می‌گردد.

<div class="api-docs" id="bkmrk-">---

</div>### Endpoint Info

<div class="api-docs" id="bkmrk-url%3A-%2Fb2c%2Fv1%2Fwallet%2F"><div class="endpoint-info"><div>**URL:** `/b2c/v1/wallet/ballance`</div><div>**Method:** <span class="method-get">GET</span></div><div>**Controller:** `CreditDebitController@walletBalance`</div><div>**Middleware:** `authWithJwt`</div><div>**Related Method:** `AccountingController::getBalanceWallet()`</div><div>**Database Table:** `wallet`</div></div>---

</div>### Query Parameters (JWT‑required)

<div class="api-docs" id="bkmrk-%D9%BE%D8%A7%D8%B1%D8%A7%D9%85%D8%AA%D8%B1-%D9%86%D9%88%D8%B9-%D8%A7%D9%84%D8%B2%D8%A7%D9%85%DB%8C-%D8%AA"><table class="schema-table" dir="rtl"><thead><tr><th>پارامتر</th><th>نوع</th><th>الزامی</th><th>توضیح</th></tr></thead><tbody><tr><td>group</td><td>string</td><td>✅</td><td>گروه کاربر: `b2c` یا `colleague`. هر مقدار دیگر منجر به خطای 1000 می‌شود.</td></tr><tr><td>operator</td><td>object (JWT)</td><td>✅</td><td>شیء اپراتور احراز هویت‌شده شامل فیلدهای `id`، `ceiling` و `deadline_month`</td></tr></tbody></table>

---

</div>### Logic Flow

<div class="api-docs" id="bkmrk-%F0%9F%93%A5-%DB%B1.-%D8%A8%D8%B1%D8%B1%D8%B3%DB%8C-%D9%88%D8%B1%D9%88%D8%AF%DB%8C-jwt"><div class="flowchart" dir="rtl"><div class="flow-item">📥 ۱. بررسی ورودی JWT و تعیین نوع کاربر (`$request->group`)</div><div class="flow-arrow">↓</div><div class="flow-item-decision">اگر group مقدار **b2c** داشت → `$userType='b2c'`  
اگر group مقدار **colleague** داشت → `$userType='b2b'`  
در غیر این صورت → بازگشت خطا:</div></div></div>```
{
  "error": {
    "code": 1000,
    "message": "گروه کاربری یافت نشد"
  },
  "meta": { "timestamp": 1733763100 }
}
```

<div class="api-docs" id="bkmrk-%E2%86%93-%F0%9F%93%8A-%D8%A7%D8%B3%D8%AA%D8%AE%D8%B1%D8%A7%D8%AC-%D9%85%D9%82%D8%A7%D8%AF%DB%8C%D8%B1-%D8%B2"><div class="flowchart" dir="rtl"><div class="flow-item-decision"></div><div class="flow-arrow">↓</div><div class="flow-item-process">📊 استخراج مقادیر زیر از JWT اپراتور: - `ceiling` → سقف اعتبار (Credit Ceiling)
- `deadline_month` → مهلت تسویه حساب ماهیانه

</div><div class="flow-arrow">↓</div><div class="flow-item-process">💰 صدا زدن متد `AccountingController::getBalanceWallet(type, operator.id, 'website')`</div><div class="flow-arrow">↓</div><div class="flow-item-success">✅ بازگرداندن پاسخ با ساختار استاندارد شامل موجودی و متادیتا.</div></div>---

</div>### Response Samples

#### ✅ پاسخ موفق (کاربر B2C)

```json
{
  "payload": {
    "ceiling": 2000000,
    "deadline": "2025-12",
    "wallet": {
      "credit": 5000000,
      "debit": 2500000,
      "balance": 2500000,
      "diagnosis": "creditor"
    }
  },
  "meta": { "timestamp": 1733763100 }
}
```

#### ✅ پاسخ موفق (کاربر colleague/B2B)

```json
{
  "payload": {
    "ceiling": 10000000,
    "deadline": false,
    "wallet": {
      "credit": 3200000,
      "debit": 3500000,
      "balance": -300000,
      "diagnosis": "debtor"
    }
  },
  "meta": { "timestamp": 1733763120 }
}
```

#### ❌ گروه اشتباه

```json
{
  "error": {
    "code": 1000,
    "message": "گروه کاربری یافت نشد"
  },
  "meta": { "timestamp": 1733763130 }
}
```

<div class="api-docs" id="bkmrk--1">---

</div>### Internal Logic – `AccountingController::getBalanceWallet()`

```php
static function getBalanceWallet($type, $id, $method='branch') {
    // تعیین نوع اپراتور
    if ($type == 'colleague') { $type = 'b2b'; } else { $type = 'erp'; }

    // جمع مجموع بدهکار و بستانکار
    $wallet = DB::table('wallet')
      ->selectRaw('SUM(credit) as credit, SUM(debit) as debit')
      ->where(function ($q) use ($type, $id, $method) {
          if ($method == 'branch')
              $q->where('operator_type', 'erp')->where('branch', $id);
          else
              $q->where('operator_type', $type)->where('operator', $id);
      })
      ->where('status', '!=', 2)
      ->first();

    return [
      "credit" => (int)$wallet->credit,
      "debit" => (int)$wallet->debit,
      "balance" => ($wallet->credit - $wallet->debit),
      "diagnosis" => ($wallet->credit - $wallet->debit) >= 0
        ? (($wallet->credit - $wallet->debit) == 0 ? 'neutral' : 'creditor')
        : 'debtor'
    ];
  }
```

<div class="api-docs" id="bkmrk--2">---

</div>### Technical Notes

<div class="api-docs" id="bkmrk-%D9%85%D9%86%D8%A8%D8%B9-%D8%AF%D8%A7%D8%AF%D9%87%3A-%D8%AC%D8%AF%D9%88%D9%84-wall">- منبع داده: جدول `wallet` با فیلدهای `credit` و `debit`.
- تمام رکوردهایی با وضعیت `status != 2` در محاسبه لحاظ می‌شوند.
- تشخیص نوع حساب: 
    - **creditor**: بستانکار (balance &gt; 0)
    - **debtor**: بدهکار (balance &lt; 0)
    - **neutral**: خنثی (balance = 0)
- در پاسخ نهایی، تمام مقادیر به ریال هستند و integer برگردانده می‌شوند.
- **نکته مهم:** در پیاده‌سازی فعلی خطای تایپی وجود دارد. خط زیر در متد AccountingController باید با `==` تصحیح گردد: ```
    if ($type = 'colleague')
    ```
    
    ✅ باید باشد: ```
    if ($type == 'colleague')
    ```
    
    در غیر این صورت همیشه مقدار `'colleague'` ست شده و مسیر شرطی اشتباه عمل می‌کند.

</div>