# OrderTimeTrackService - Service Quản Lý Thời Gian Nhận Tiền

## Tổng Quan

`OrderTimeTrackService` là một service chuyên dụng để quản lý việc cập nhật thời gian nhận tiền trong bảng `OrderTimeTrack`. Service này được thiết kế để có thể tái sử dụng ở nhiều nơi khác nhau trong hệ thống.

## Mục Đích

- **Tái sử dụng**: Có thể sử dụng trong nhiều service khác nhau (CashierService, ReconciliationService, TransferPaymentBillService, etc.)
- **Tập trung hóa**: Tất cả logic cập nhật thời gian nhận tiền được tập trung vào một service
- **Dễ bảo trì**: Thay đổi logic chỉ cần sửa ở một nơi
- **Batch processing**: Hỗ trợ cập nhật nhiều đơn hàng cùng lúc

## Các Trường Thời Gian Được Quản Lý

| Trường | Mô Tả | Điều Kiện Cập Nhật |
|--------|-------|-------------------|
| `HeadSourceFeeTime` | Thời gian nhận tiền cước nguồn | Khi `SourceFeeStage = Head (9)` |
| `HeadDestFeeTime` | Thời gian nhận tiền cước đích | Khi `DestFeeStage = Head (9)` |
| `HeadTransferFeeTime` | Thời gian nhận tiền cước chuyển khoản | Khi `TransferFeeStage = Head (9)` |
| `HeadDeductCodFeeTime` | Thời gian nhận tiền cước cấn trừ COD | Khi `DeductCodFeeStage = Head (9)` và `PayFeeType = COD` |

## Interface

### IOrderTimeTrackService

```csharp
public interface IOrderTimeTrackService
{
    /// <summary>
    /// Cập nhật thời gian nhận tiền cho một đơn hàng
    /// </summary>
    Task<BaseResult> UpdateFinancialTimesAsync(
        int orderId,
        OrderFeeStage? sourceFeeStage = null,
        OrderFeeStage? destFeeStage = null,
        OrderFeeStage? transferFeeStage = null,
        OrderCodStage? codStage = null,
        OrderFeeStage? deductCodFeeStage = null,
        int? updatedBy = null,
        string updatedByUserName = null,
        DateTimeOffset? currentTime = null);

    /// <summary>
    /// Cập nhật thời gian nhận tiền cho nhiều đơn hàng
    /// </summary>
    Task<BaseResult> UpdateFinancialTimesBatchAsync(
        List<OrderTimeTrackUpdateModel> orderUpdates,
        int updatedBy,
        string updatedByUserName,
        DateTimeOffset? currentTime = null);
}
```

### OrderTimeTrackUpdateModel

```csharp
public class OrderTimeTrackUpdateModel
{
    public int OrderId { get; set; }
    public OrderFeeStage? SourceFeeStage { get; set; }
    public OrderFeeStage? DestFeeStage { get; set; }
    public OrderFeeStage? TransferFeeStage { get; set; }
    public OrderCodStage? CodStage { get; set; }
    public OrderFeeStage? DeductCodFeeStage { get; set; }
}
```

## Cách Sử Dụng

### 1. Dependency Injection

Service đã được đăng ký trong `DependencyRegister.cs`:

```csharp
services.AddTransient<IOrderTimeTrackService, OrderTimeTrackService>();
```

### 2. Sử dụng trong Service

```csharp
public class YourService
{
    private readonly IOrderTimeTrackService _orderTimeTrackService;

    public YourService(IOrderTimeTrackService orderTimeTrackService)
    {
        _orderTimeTrackService = orderTimeTrackService;
    }

    public async Task<BaseResult> YourMethod()
    {
        // Cập nhật thời gian nhận tiền
        var result = await _orderTimeTrackService.UpdateFinancialTimesAsync(
            orderId: 123,
            sourceFeeStage: OrderFeeStage.Head,
            updatedBy: 456,
            updatedByUserName: "admin@example.com"
        );

        return result;
    }
}
```

### 3. Batch Update

```csharp
var orderUpdates = new List<OrderTimeTrackUpdateModel>
{
    new OrderTimeTrackUpdateModel
    {
        OrderId = 123,
        SourceFeeStage = OrderFeeStage.Head,
        CodStage = OrderCodStage.Head
    },
    new OrderTimeTrackUpdateModel
    {
        OrderId = 124,
        DestFeeStage = OrderFeeStage.Head
    }
};

var result = await _orderTimeTrackService.UpdateFinancialTimesBatchAsync(
    orderUpdates,
    updatedBy: 456,
    updatedByUserName: "admin@example.com"
);
```

## Các Trường Hợp Sử Dụng

### 1. CashierService
- **Khi nào**: Thu tiền từ lái xe
- **Cập nhật**: `HeadSourceFeeTime`, `HeadDestFeeTime`, `HeadDeductCodFeeTime`

### 2. ReconciliationService
- **Khi nào**: Chuyển khoản thành công
- **Cập nhật**: `HeadTransferFeeTime`

### 3. TransferPaymentBillService
- **Khi nào**: Tạo phiếu chuyển khoản
- **Cập nhật**: `HeadTransferFeeTime`

### 4. ExpenseService
- **Khi nào**: Chi tiêu từ ví
- **Cập nhật**: `HeadSourceFeeTime`, `HeadDestFeeTime`

## Lưu Ý Quan Trọng

### 1. Stage Values
- **OrderFeeStage.Head = 9**: FOUNDER, CO-FOUNDER, ACCOUNTANT
- **OrderFeeStage.Branch = 3**: COORDINATOR
- **OrderCodStage.Head = 9**: FOUNDER, CO-FOUNDER, ACCOUNTANT
- **OrderCodStage.Branch = 3**: COORDINATOR

### 2. PayFeeType = COD
- Chỉ cập nhật `HeadDeductCodFeeTime` khi `PayFeeType = COD` (cấn trừ COD)
- Khi `PayFeeType = COD`, tiền COD đã bao gồm cước phí

### 3. Error Handling
- Service không throw exception để không ảnh hưởng đến flow chính
- Lỗi được log và trả về trong `BaseResult`

### 4. Performance
- Sử dụng stored procedure `SP_UpdateOrderTimeTrackFinancialTimes`
- Hỗ trợ batch processing để tối ưu performance

## Stored Procedure

Service sử dụng stored procedure `SP_UpdateOrderTimeTrackFinancialTimes` với các parameters:

```sql
@OrderId INT,
@SourceFeeStage INT = NULL,        -- OrderFeeStage: 3=Branch, 9=Head
@DestFeeStage INT = NULL,          -- OrderFeeStage: 3=Branch, 9=Head  
@TransferFeeStage INT = NULL,      -- OrderFeeStage: 3=Branch, 9=Head
@CodStage INT = NULL,              -- OrderCodStage: 3=Branch, 9=Head
@DeductCodFeeStage INT = NULL,     -- OrderFeeStage: 3=Branch, 9=Head (khi PayFeeType = COD)
@CurrentTime DATETIMEOFFSET = NULL,
@UpdatedBy INT,
@UpdatedByUserName NVARCHAR(255),
@Result INT OUTPUT,
@Message NVARCHAR(500) OUTPUT
```

## Ví Dụ Thực Tế

Xem file `OrderTimeTrackServiceUsageExample.cs` để biết cách sử dụng chi tiết trong các trường hợp khác nhau.

## Migration

Khi thêm service mới vào project hiện tại:

1. **Đăng ký service** trong `DependencyRegister.cs` ✅
2. **Cập nhật constructor** của các service cần sử dụng ✅
3. **Thay thế logic cũ** bằng cách gọi service mới ✅
4. **Test** các chức năng liên quan ✅

## Kết Luận

`OrderTimeTrackService` cung cấp một cách tiếp cận tập trung và có thể tái sử dụng để quản lý thời gian nhận tiền trong hệ thống. Service này giúp:

- **Giảm code duplication**
- **Tăng tính nhất quán**
- **Dễ dàng bảo trì và mở rộng**
- **Hỗ trợ batch processing**
- **Error handling tốt hơn**
