# API Documentation - Agency Management (Quản lý Đại lý)

## Mục lục
1. [Tìm kiếm đại lý (Search)](#1-tìm-kiếm-đại-lý)
2. [Tạo mới / Cập nhật đại lý (CreateOrUpdate)](#2-tạo-mới--cập-nhật-đại-lý)
3. [Lấy chi tiết đại lý (GetById)](#3-lấy-chi-tiết-đại-lý)
4. [Tự động hoàn thành (AutoComplete)](#4-tự-động-hoàn-thành)
5. [Xóa đại lý (Delete)](#5-xóa-đại-lý)
6. [Cập nhật trạng thái (UpdateStatus)](#6-cập-nhật-trạng-thái)
7. [Lấy cây đại lý (GetTree)](#7-lấy-cây-đại-lý)

---

## 1. Tìm kiếm đại lý

- **Endpoint**: `POST /api/Agency/Search`
- **Authorization**: `Agency.Search`

**Request Body:**
```json
{
  "Pagination": {
    "PageIndex": 1,
    "PageSize": 15
  },
  "Search": {
    "PredicateObject": {
      "Keyword": "LADA"
    }
  },
  "Sort": {
    "Predicate": "CreatedTime",
    "Reverse": true
  }
}
```

**Response:**
```json
{
  "Result": 1,
  "Message": "Thành công",
  "Data": {
    "Items": [
      {
        "Id": 1,
        "Name": "Chi nhánh Hà Nội",
        "Code": "HN001",
        "Status": 3,
        "AgencyType": 2
      }
    ],
    "TotalRow": 100
  }
}
```

---

## 2. Tạo mới / Cập nhật đại lý

- **Endpoint**: `POST /api/Agency/CreateOrUpdate`
- **Authorization**: `Agency.CreateOrUpdate`

> [!NOTE]
> Nếu `Id = 0`, hệ thống sẽ **tạo mới**. Nếu `Id > 0`, hệ thống sẽ **cập nhật** bản ghi tương ứng.

> [!IMPORTANT]
> Các trường `UpdatedBy` và `UpdatedByUserName` được hệ thống tự động gán từ JWT token, **không cần truyền từ client**.

**Request Body:**
```json
{
  "Id": 0,
  "Name": "Chi nhánh Hà Nội",
  "Code": "HN001",
  "Description": "Chi nhánh tại Hà Nội",
  "ParentId": 0,
  "RepresentativeId": 0,
  "ManagerId": 5,
  "DisplayOrder": 1,
  "Status": 1,
  "AgencyType": 2,
  "CityId": 1,
  "DistrictId": 10,
  "WardId": 100,
  "Address": "123 Đường ABC, Phường XYZ",
  "CompanyName": "Công ty TNHH ABC",
  "CompanyPhone": "0901234567",
  "FounderName": "Nguyễn Văn A",
  "CompanyTaxCode": "0123456789",
  "CompanyAddress": "123 Đường ABC, Quận 1, TP.HCM"
}
```

**Request Parameters:**

| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
| `Id` | int | ✅ | `0` = Tạo mới, `> 0` = Cập nhật |
| `Name` | string | ✅ | Tên chi nhánh / đại lý |
| `Code` | string | | Mã chi nhánh |
| `Description` | string | | Mô tả |
| `ParentId` | int | | ID đại lý cha (0 nếu là gốc) |
| `RepresentativeId` | int | | ID người đại diện pháp lý |
| `ManagerId` | int | | ID quản lý |
| `DisplayOrder` | int | | Thứ tự hiển thị |
| `Status` | int | | Xem bảng `AgencyStatus` bên dưới |
| `AgencyType` | int | ✅ | Xem bảng `AgencyType` bên dưới |
| `CityId` | int | | ID Tỉnh/Thành phố |
| `DistrictId` | int | | ID Quận/Huyện |
| `WardId` | int | | ID Phường/Xã |
| `Address` | string | | Địa chỉ chi tiết |
| `CompanyName` | string | | Tên doanh nghiệp |
| `CompanyPhone` | string | | SĐT doanh nghiệp |
| `FounderName` | string | | Tên người sáng lập |
| `CompanyTaxCode` | string | | Mã số thuế |
| `CompanyAddress` | string | | Địa chỉ doanh nghiệp (dùng xuất hóa đơn) |

**Enum - AgencyStatus:**

| Giá trị | Mô tả |
|---|---|
| `1` | Chờ kích hoạt |
| `3` | Đang hoạt động |
| `4` | Khóa 1 chiều |
| `5` | Dừng hoạt động |

**Enum - AgencyType:**

| Giá trị | Mô tả |
|---|---|
| `1` | Phòng ban của LADA |
| `2` | Chi nhánh nhượng quyền |
| `3` | Chi nhánh của LADA |

**Response:**
```json
{
  "Result": 1,
  "Message": "Thành công",
  "Data": 5
}
```

> [!NOTE]
> `Data` trả về là `Id` của bản ghi vừa tạo mới hoặc cập nhật.

---

## 3. Lấy chi tiết đại lý

- **Endpoint**: `GET /api/Agency/GetById?id={id}`
- **Authorization**: `Agency.GetById`

**Request Parameters:**
- `id` (int, required): ID của đại lý cần lấy thông tin.

**Response:**
```json
{
  "Result": 1,
  "Message": "Thành công",
  "Data": {
    "Id": 5,
    "Name": "Chi nhánh Hà Nội",
    "Code": "HN001",
    "Description": "Chi nhánh tại Hà Nội",
    "ParentId": 0,
    "RepresentativeId": 0,
    "ManagerId": 10,
    "DisplayOrder": 1,
    "Status": 3,
    "AgencyType": 2,
    "CityId": 1,
    "DistrictId": 10,
    "WardId": 100,
    "Address": "123 Đường ABC",
    "CompanyName": "Công ty TNHH ABC",
    "CompanyPhone": "0901234567",
    "FounderName": "Nguyễn Văn A",
    "CompanyTaxCode": "0123456789",
    "CompanyAddress": "123 Đường ABC, Quận 1, TP.HCM"
  }
}
```

---

## 4. Tự động hoàn thành

- **Endpoint**: `GET /api/Agency/AutoComplete?keyword={keyword}`
- **Authorization**: `Agency.AutoComplete`

**Request Parameters:**
- `keyword` (string, optional): Từ khóa tìm kiếm theo tên hoặc mã đại lý. Mặc định là chuỗi rỗng.

**Response:**
```json
{
  "Result": 1,
  "Message": "Thành công",
  "Data": [
    {
      "Id": 5,
      "Name": "Chi nhánh Hà Nội",
      "Code": "HN001"
    }
  ]
}
```

> [!TIP]
> Endpoint này dùng cho các dropdown/select box cần tìm kiếm đại lý nhanh mà không cần phân trang.

---

## 5. Xóa đại lý

- **Endpoint**: `DELETE /api/Agency/Delete?id={id}`
- **Authorization**: `Agency.Delete`

**Request Parameters:**
- `id` (int, required): ID của đại lý cần xóa.

> [!IMPORTANT]
> Thông tin người thực hiện xóa được lấy tự động từ JWT token, không cần truyền thêm.

**Response:**
```json
{
  "Result": 1,
  "Message": "Thành công",
  "Data": null
}
```

---

## 6. Cập nhật trạng thái

- **Endpoint**: `PUT /api/Agency/UpdateStatus`
- **Authorization**: `Agency.UpdateStatus`

> [!IMPORTANT]
> Các trường `UpdatedBy` và `UpdatedByUserName` được hệ thống tự động gán từ JWT token, **không cần truyền từ client**.

**Request Body:**
```json
{
  "Id": 5,
  "NewStatus": 3
}
```

**Request Parameters:**

| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
| `Id` | int | ✅ | ID của đại lý cần cập nhật trạng thái |
| `NewStatus` | int | ✅ | Trạng thái mới (xem bảng `AgencyStatus`) |

**Response:**
```json
{
  "Result": 1,
  "Message": "Thành công",
  "Data": null
}
```

---

## 7. Lấy cây đại lý

- **Endpoint**: `GET /api/Agency/GetTree?keyword={keyword}`
- **Authorization**: `Founder`

> [!IMPORTANT]
> Endpoint này yêu cầu role **`Founder`** - chỉ dành cho người sáng lập/quản trị hệ thống cấp cao nhất.

**Request Parameters:**
- `keyword` (string, optional): Từ khóa lọc trong cây đại lý. Mặc định là chuỗi rỗng.

**Response:**
```json
{
  "Result": 1,
  "Message": "Thành công",
  "Data": [
    {
      "Id": 1,
      "Name": "LADA Head Office",
      "Code": "HQ",
      "AgencyType": 1,
      "Children": [
        {
          "Id": 5,
          "Name": "Chi nhánh Hà Nội",
          "Code": "HN001",
          "AgencyType": 3,
          "Children": []
        }
      ]
    }
  ]
}
```

> [!NOTE]
> Kết quả trả về dạng cây phân cấp. Mỗi node có danh sách `Children` chứa các đại lý con trực thuộc.
