# API Quản Lý Thu Ngân (Cashier)

## Tổng quan

API này cung cấp các chức năng quản lý số tiền mà nhân viên thu ngân (hoặc lái xe) đang giữ, bao gồm việc tìm kiếm số dư hiện tại và thực hiện thu tiền để ghi nhận vào hệ thống tài chính/ví điện tử.

---

## 1. Tìm kiếm số dư thu ngân

Dùng để lấy danh sách nhân viên và số tiền họ đang nắm giữ (COD, phí lấy, phí giao) cùng với các đơn hàng liên quan.

### Endpoint
```
POST /api/Cashier/Search
```

**Authorization**: Bearer Token (JWT)

**Role Required**: `Cashier.Search`

### Request

**Format**: `application/json`

**Model**: `SmartTableParam`

| Thuộc tính | Kiểu dữ liệu | Mô tả |
|------------|-------------|-------|
| `Search.PredicateObject.Keyword` | `string` | Từ khóa tìm kiếm (tên, username) |
| `Pagination.PageIndex` | `int` | Trang hiện tại (mặc định 1) |
| `Pagination.PageSize` | `int` | Số bản ghi mỗi trang (mặc định 15) |
| `Sort.Predicate` | `string` | Trường cần sắp xếp (ví dụ: "FullName") |
| `Sort.Reverse` | `boolean` | `true` để sắp xếp giảm dần, `false` tăng dần |

**Ví dụ Request Body**:
```json
{
  "Pagination": {
    "PageIndex": 1,
    "PageSize": 15
  },
  "Sort": {
    "Predicate": "FullName",
    "Reverse": false
  },
  "Search": {
    "PredicateObject": {
      "Keyword": "driver01"
    }
  }
}
```

### Response

**Success Response (200 OK)**

**Model**: `SmartTableResult<CashierBalanceItem>`

| Thuộc tính | Kiểu dữ liệu | Mô tả |
|------------|-------------|-------|
| `TotalRecord` | `int` | Tổng số bản ghi tìm thấy |
| `Items` | `List<CashierBalanceItem>` | Danh sách kết quả |

**Chi tiết `CashierBalanceItem`**:
| Thuộc tính | Kiểu dữ liệu | Mô tả |
|------------|-------------|-------|
| `Id` | `int` | ID của người dùng |
| `FullName` | `string` | Họ và tên |
| `UserName` | `string` | Tên đăng nhập |
| `CodAmount` | `decimal` | Số tiền COD đang giữ |
| `SourceFeeAmount` | `decimal` | Phí lấy hàng đang giữ |
| `DestFeeAmount` | `decimal` | Phí giao hàng đang giữ |
| `ExpectedCodAmount` | `decimal` | Số tiền COD dự kiến (đang trên đường) |
| `ExpectedSourceFeeAmount` | `decimal` | Phí lấy dự kiến |
| `ExpectedDestFeeAmount` | `decimal` | Phí giao dự kiến |
| `OrderList` | `List<CashierBalanceOrderItem>` | Chi tiết danh sách đơn hàng |

**Ví dụ Response**:
```json
{
  "TotalRecord": 1,
  "Items": [
    {
      "Id": 1024,
      "FullName": "Nguyễn Văn Lái Xe",
      "UserName": "driver01",
      "CodAmount": 1500000,
      "SourceFeeAmount": 11000,
      "DestFeeAmount": 22000,
      "OrderList": [
        {
          "Id": 5001,
          "Code": "LADA123456",
          "CodAmount": 500000,
          "SourceFee": 11000,
          "DestFee": 0
        }
      ]
    }
  ]
}
```

---

## 2. Thu tiền từ nhân viên (Collect)

Ghi nhận việc thu tiền từ người dùng khác (lái xe) vào ví của người thu tiền đang đăng nhập. Giao dịch sẽ đồng thời cập nhật trạng thái tài chính của các đơn hàng liên quan.

### Endpoint
```
POST /api/Cashier/Collect
```

**Authorization**: Bearer Token (JWT)

**Role Required**: `Cashier.CollectCashier`

### Request

**Format**: `application/json`

**Model**: `CollectCashierModel`

| Thuộc tính | Kiểu dữ liệu | Bắt buộc | Mô tả |
|------------|-------------|----------|-------|
| `FromUserId` | `int` | ✅ | ID người nộp tiền (lái xe) |
| `CashAmount` | `decimal` | ✅ | Số tiền mặt nộp |
| `TransferAmount` | `decimal` | ✅ | Số tiền chuyển khoản nộp |
| `TotalAmount` | `decimal` | ✅ | Tổng số tiền nộp (`CashAmount` + `TransferAmount`) |
| `Note` | `string` | ❌ | Ghi chú |
| `OrderList` | `List` | ✅ | Danh sách đơn hàng được thu tiền |

**Chi tiết `CollectCashierOrderModel` trong `OrderList`**:
| Thuộc tính | Kiểu dữ liệu | Mô tả |
|------------|-------------|-------|
| `Id` | `int` | ID đơn hàng |
| `CodAmount` | `decimal` | Số tiền COD thu từ đơn này |
| `SourceFee` | `decimal` | Phí lấy thu từ đơn này |
| `DestFee` | `decimal` | Phí giao thu từ đơn này |

**Ví dụ Request Body**:
```json
{
  "FromUserId": 1024,
  "CashAmount": 533000,
  "TransferAmount": 0,
  "TotalAmount": 533000,
  "Note": "Thu tiền cuối ca sáng",
  "OrderList": [
    {
      "Id": 5001,
      "CodAmount": 500000,
      "SourceFee": 11000,
      "DestFee": 22000
    }
  ]
}
```

### Response

**Success Response (200 OK)**

```json
{
  "Result": 1,
  "Message": "Success"
}
```

---

## Codes Example

### JavaScript (Fetch)
```javascript
const searchCashier = async (keyword) => {
  const response = await fetch('/api/Cashier/Search', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({
      Pagination: { PageIndex: 1, PageSize: 15 },
      Search: { PredicateObject: { Keyword: keyword } }
    })
  });
  return await response.json();
};
```

### C# (HttpClient)
```csharp
public async Task<BaseResult> CollectMoney(CollectCashierModel model)
{
    var content = new StringContent(JsonConvert.SerializeObject(model), Encoding.UTF8, "application/json");
    var response = await _httpClient.PostAsync("/api/Cashier/Collect", content);
    return await response.Content.ReadFromJsonAsync<BaseResult>();
}
```

---

## Luồng xử lý kỹ thuật (Collect Money)

1. **Xác thực**: Kiểm tra Token và quyền `Cashier.CollectCashier`.
2. **Ví điện tử**: Tự động tìm hoặc tạo ví cá nhân cho người thu tiền (người đăng nhập).
3. **Transaction**:
    - Khởi tạo Database Transaction.
    - Tạo một bản ghi `Transaction` loại `CollectFromDriver` (thu tiền từ lái xe).
    - Liên kết các đơn hàng trong `OrderList` với transaction này qua bảng `TransactionOrder`.
4. **Cập nhật trạng thái đơn hàng**:
    - Duyệt `OrderList`, cập nhật `OrderFin`: Gán `CashierId`, `CashierUsername` và đẩy `Stage` lên mức tương ứng (Head/Branch) tùy vào role của người thu.
    - Nếu là lần thu đầu tiên, lưu thông tin `OriginalCashier` và thời gian thu (`CollectedTime`).
5. **Cập nhật số dư**: Cộng `TotalAmount` vào số dư ví của người thu tiền.
6. **Hành trình**: Tạo `OrderTrack` ghi nhận lịch sử thu tiền cho từng đơn hàng.
7. **Commit**: Hoàn tất giao dịch.

---

## Ghi chú quan trọng
- ✅ Tham số JSON sử dụng **PascalCase**.
- ✅ `FromUserId` là người nộp tiền, còn người nhận tiền được lấy tự động từ Token.
- ✅ Hệ thống hỗ trợ thu nhiều phần (COD, phí lấy, phí giao) trong cùng một request.

---

## Metadata
- **Version**: 1.0
- **Last Updated**: 2025-12-21
- **Author**: AI Assistant
