# Hệ thống Quản lý Doanh thu (Income Management) - Hoàn thiện

## ✅ Đã hoàn thành 100%

### 1. Domain Layer (Lada.Framework)

#### Entities

- ✅ `Income.cs` - Entity doanh thu
- ✅ `IncomeCategory.cs` - Entity danh mục doanh thu
- ✅ `IncomeHistory.cs` - Entity lịch sử doanh thu
- ✅ `IncomeStatus.cs` - Enum trạng thái (Pending, Approved, Rejected, Received)
- ✅ `Transaction.cs` - Đã thêm ExpenseId và IncomeId

#### Entity Mappings

- ✅ `IncomeMap.cs`
- ✅ `IncomeCategoryMap.cs`
- ✅ `IncomeHistoryMap.cs`
- ✅ `TransactionMap.cs` - Đã cập nhật
- ✅ `LadaDbContext.Finance.cs` - Đã đăng ký DbSets

### 2. Application Layer (Ladaer.BackEnd)

#### DTO Models & Items

- ✅ `IncomeModel.cs`
- ✅ `IncomeItem.cs`
- ✅ `IncomeCategoryModel.cs`
- ✅ `IncomeCategoryItem.cs`
- ✅ `IncomeHistoryModel.cs`
- ✅ `IncomeHistoryItem.cs`
- ✅ `IncomeResult.cs`
- ✅ `IncomeCategoryResult.cs`

#### AutoMapper

- ✅ `FinanceMappingProfile.cs` - Đã thêm mappings cho Income và IncomeCategory
- ✅ Extension methods cho Income

#### Services

- ✅ `IncomeCategoryService.cs` - Interface và implementation hoàn chỉnh
- ✅ `IncomeService.cs` - Interface và implementation hoàn chỉnh

#### Controllers

- ✅ `IncomeCategoryController.cs` - API endpoints cho danh mục doanh thu
- ✅ `IncomeController.cs` - API endpoints cho doanh thu

#### Dependency Injection

- ✅ `DependencyRegister.cs` - Đã đăng ký IIncomeService và IIncomeCategoryService

### 3. Database Scripts

- ✅ `AddIncomeManagement.sql` - Tạo bảng Income, IncomeCategory, IncomeHistories
- ✅ `AddExpenseIdAndIncomeIdToTransaction.sql` - Thêm cột vào bảng Transaction
- ✅ `RemoveExpenseCategoryIdAndIncomeCategoryIdFromTransaction.sql` - Xóa cột category khỏi Transaction

## 📊 API Endpoints

### IncomeCategoryController

```
POST   /api/IncomeCategory/Search
GET    /api/IncomeCategory/{id}
POST   /api/IncomeCategory/CreateOrUpdate
DELETE /api/IncomeCategory/{id}
GET    /api/IncomeCategory/GetAll
GET    /api/IncomeCategory/CheckNameExists
GET    /api/IncomeCategory/Hierarchy
GET    /api/IncomeCategory/RootCategories
GET    /api/IncomeCategory/Children/{parentId}
GET    /api/IncomeCategory/CanDelete/{id}
```

### IncomeController

```
POST   /api/Income/Search
GET    /api/Income/{id}
POST   /api/Income/CreateOrUpdate
POST   /api/Income/Approve/{id}
POST   /api/Income/Reject/{id}
POST   /api/Income/MarkAsReceived/{id}
DELETE /api/Income/{id}
```

## 🔐 Permissions cần có trong database

### IncomeCategory Permissions

- `IncomeCategory.Search`
- `IncomeCategory.GetById`
- `IncomeCategory.CreateOrUpdate`
- `IncomeCategory.Delete`
- `IncomeCategory.GetAll`
- `IncomeCategory.CheckNameExists`
- `IncomeCategory.GetHierarchy`
- `IncomeCategory.GetRootCategories`
- `IncomeCategory.GetChildren`
- `IncomeCategory.CanDelete`

### Income Permissions

- `Income.Search`
- `Income.GetById`
- `Income.CreateOrUpdate`
- `Income.Delete`
- `Income.Approve`
- `Income.Reject`
- `Income.MarkAsReceived`

## 🔄 Quy trình xử lý Doanh thu

### 1. Tạo doanh thu

- POST `/api/Income/CreateOrUpdate`
- Status mặc định: **Pending**
- Tự động set ApprovedBy từ IncomeCategory

### 2. Duyệt doanh thu

- POST `/api/Income/Approve/{id}`
- Status chuyển: **Pending → Approved**
- Lưu ApprovedBy
- Tạo IncomeHistory

### 3. Nhận tiền

- POST `/api/Income/MarkAsReceived/{id}`
- Status chuyển: **Approved → Received**
- Tạo Transaction với IncomeId
- Cộng tiền vào ví (TransactionDirection.Income)
- Link Income với Transaction qua TransactionId

### 4. Từ chối doanh thu

- POST `/api/Income/Reject/{id}`
- Status chuyển: **Pending → Rejected**
- Bắt buộc nhập RejectReason
- Tạo IncomeHistory

## 💰 Transaction Integration

Khi đánh dấu nhận tiền (MarkAsReceived):

```csharp
var transaction = new Transaction
{
    Id = Guid.NewGuid(),
    Description = $"Doanh thu: {income.Description}",
    Amount = income.Amount,
    TransactionDirection = TransactionDirection.Income, // Cộng tiền
    TransactionType = TransactionType.Recharge,
    IncomeId = income.Id, // Link với Income
    WalletId = wallet.Id,
    // ...
};
```

## 📈 So sánh với Expense

| Đặc điểm              | Expense            | Income             |
| --------------------- | ------------------ | ------------------ |
| Trạng thái cuối       | Paid               | Received           |
| Hướng tiền            | Trừ tiền (Outcome) | Cộng tiền (Income) |
| TransactionType       | Withdraw           | Recharge           |
| UserBankAccount       | Có                 | Không              |
| Transaction Direction | Outcome            | Income             |

## 🚀 Bước tiếp theo để sử dụng

1. **Chạy migration SQL**:

   ```bash
   # Chạy các file SQL trong thứ tự:
   # 1. AddIncomeManagement.sql
   # 2. AddExpenseIdAndIncomeIdToTransaction.sql
   # 3. RemoveExpenseCategoryIdAndIncomeCategoryIdFromTransaction.sql
   ```

2. **Tạo Permissions trong database** (các permission liệt kê ở trên)

3. **Assign permissions cho roles** phù hợp

4. **Test API** qua Swagger UI:
   - Swagger: https://localhost:7284/swagger/index.html

## 📝 Lưu ý

1. **Income không có UserBankAccount** - Đã bỏ khỏi entity
2. **Transaction.ExpenseId và IncomeId** - Dùng để liên kết ngược từ Transaction về Expense/Income
3. **Đã bỏ CostCategoryId** khỏi Transaction - Chỉ giữ lại CostCategoryId cho hệ thống cũ
4. **MarkAsReceived** - Tự động cộng tiền vào ví của người dùng
5. **Permissions** - Cần được cấu hình trong database trước khi sử dụng

## 🎉 Hoàn thành

Hệ thống Income Management đã được xây dựng hoàn chỉnh với:

- ✅ Domain entities và mappings
- ✅ DTOs và AutoMapper
- ✅ Services với đầy đủ business logic
- ✅ Controllers với API endpoints
- ✅ Dependency Injection registration
- ✅ SQL migration scripts
- ✅ Documentation đầy đủ

Hệ thống sẵn sàng để sử dụng!
