# API Documentation - Driver Finance Management

Tài liệu này mô tả các API liên quan đến quản lý tài chính dành cho ứng dụng lái xe (Driver App).

## Mục lục
1. [Lấy thông tin tài chính tổng quan](#1-lấy-thông-tin-tài-chính-tổng-quan)
2. [Tìm kiếm đơn hàng tài chính (có phân trang)](#2-tìm-kiếm-đơn-hàng-tài-chính-có-phân-trang)

---

## 1. Lấy thông tin tài chính tổng quan
Lấy tổng số tiền cước (lấy/giao) và tiền thu hộ (COD) mà lái xe đang cầm, kèm danh sách 10 đơn hàng gần nhất.

### Thông tin cơ bản
- **Endpoint**: `GET /api/DriverFinance/GetFinancialInfo`
- **Authorization**: Bearer Token (Role: `DriverApp.GetFinancialInfo`)

### Response
```json
{
  "TotalSourceFee": 150000,
  "TotalDestFee": 50000,
  "TotalCollectAmount": 1000000,
  "TotalAmount": 1200000,
  "RecentOrders": [
    {
      "OrderId": 12345,
      "OrderCode": "LD123456789",
      "PartnerCode": "PN123",
      "SourceFee": 50000,
      "DestFee": 0,
      "CollectAmount": 500000,
      "TotalAmount": 550000,
      "Status": 5,
      "StatusStr": "Đã lấy hàng",
      "PhysicalStatus": 1,
      "PhysicalStatusStr": "Bình thường",
      "PayFeeType": 1,
      "PayFeeTypeStr": "Người gửi trả",
      "CreatedDate": "2024-03-09T10:00:00",
      "CreatedDateStr": "09/03/2024 10:00",
      "Note": "Giao gấp",
      "CustomerName": "Nguyễn Văn A",
      "CashierType": "SourceFee",
      "IsOriginalCashier": true,
      "CollectedTime": "2024-03-09T10:30:00+07:00",
      "CollectedTimeStr": "09/03/2024 10:30",
      "DepositStatus": "Cước lấy: Chưa nộp"
    }
  ]
}
```

---

## 2. Tìm kiếm đơn hàng tài chính (có phân trang)
Tìm kiếm danh sách các đơn hàng mà lái xe đang cầm tiền hoặc đã từng thu tiền, hỗ trợ lọc theo thời gian và từ khóa.

### Thông tin cơ bản
- **Endpoint**: `POST /api/DriverFinance/SearchFinancialOrders`
- **Authorization**: Bearer Token (Role: `DriverApp.SearchFinancialOrders`)

### Request
**Request Body (JSON):**
```json
{
  "Pagination": {
    "PageIndex": 1,
    "PageSize": 20
  },
  "Search": {
    "PredicateObject": {
      "Keyword": "LD123",
      "CollectedStart": "2024-03-01T00:00:00Z",
      "CollectedEnd": "2024-03-09T23:59:59Z"
    }
  },
  "Sort": {
    "Predicate": "CreatedTime",
    "Reverse": true
  }
}
```

**Request Parameters:**
- `Keyword` (string): Tìm kiếm theo mã đơn hàng hoặc mã đối tác.
- `CollectedStart` (DateTime): Thời gian bắt đầu thu tiền.
- `CollectedEnd` (DateTime): Thời gian kết thúc thu tiền.

### Response
```json
{
  "Pagination": {
    "TotalItemCount": 100,
    "NumberOfPages": 5
  },
  "Items": [
    {
      "OrderId": 12345,
      "OrderCode": "LD123456789",
      "PartnerCode": "PN123",
      "SourceFee": 50000,
      "DestFee": 0,
      "CollectAmount": 500000,
      "TotalAmount": 550000,
      "Status": 5,
      "StatusStr": "Đã lấy hàng",
      "PhysicalStatus": 1,
      "PhysicalStatusStr": "Bình thường",
      "PayFeeType": 1,
      "PayFeeTypeStr": "Người gửi trả",
      "CreatedDate": "2024-03-09T10:00:00",
      "CreatedDateStr": "09/03/2024 10:00",
      "Note": "Giao gấp",
      "CustomerName": "Nguyễn Văn A",
      "PicUserName": "driver01",
      "RouteName": "Hà Nội - Hải Phòng",
      "SourceAddress": "Số 1 Đại Cồ Việt, Hà Nội",
      "DestAddress": "Lê Hồng Phong, Hải Phòng",
      "CashierType": "SourceFee",
      "IsOriginalCashier": true,
      "CollectedTime": "2024-03-09T10:30:00+07:00",
      "CollectedTimeStr": "09/03/2024 10:30",
      "ContactName": "Trần Thị B",
      "ContactPhone": "0987654321",
      "ContactAddress": "Số 1 Đại Cồ Việt, Hà Nội",
      "AddressType": "Source",
      "DepositStatus": "Cước lấy: Chưa nộp"
    }
  ]
}
```

> [!NOTE]
> **Logic phân quyền dữ liệu**
> API tự động lọc theo `UserId` của user đang đăng nhập. Driver chỉ thấy được các đơn hàng mà mình đang cầm tiền (Cashier) hoặc đã từng thu tiền ban đầu (Original Cashier).

> [!IMPORTANT]
> **Trường `DepositStatus` - Trạng thái nộp tiền**
>
> Trường này hiển thị trạng thái nộp tiền theo từng loại phí mà lái xe đã thu:
>
> | Loại phí | Chưa nộp | Đã nộp |
> |----------|----------|--------|
> | Cước lấy hàng | `OriginalSourceFeeCashierId == SourceFeeCashierId == userId` và `SourceFeeStage == 2` | `OriginalSourceFeeCashierId != SourceFeeCashierId` và `SourceFeeStage > 2` |
> | Cước giao hàng | `OriginalDestFeeCashierId == DestFeeCashierId == userId` và `DestFeeStage == 2` | `OriginalDestFeeCashierId != DestFeeCashierId` và `DestFeeStage > 2` |
> | Tiền thu hộ COD | `OriginalCodCashierId == CodCashierId == userId` và `CodStage == 2` | `OriginalCodCashierId != CodCashierId` và `CodStage > 2` |
>
> Nếu lái xe thu nhiều loại phí trong cùng 1 đơn, trạng thái sẽ hiển thị dạng: `"Cước lấy: Chưa nộp, COD: Đã nộp"`.

> [!IMPORTANT]
> **JSON Property Case**
> Mặc định Backend sử dụng **PascalCase** cho tất cả các thuộc tính JSON.
