> ## Documentation Index
> Fetch the complete documentation index at: https://tomotek.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# US-ADM-05: Quản lý danh sách người giới thiệu

> Là một Admin, Tôi muốn quản lý danh sách người giới thiệu trong hệ thống, Để tôi có thể tạo, chỉnh sửa, xem và quản lý các tài khoản giới thiệu cùng số liệu hoạt động của họ.

## Điều kiện tiên quyết (Pre-conditions)

* Admin đã đăng nhập thành công vào hệ thống quản trị.

## Giao diện Danh sách Người giới thiệu

Màn hình chính hiển thị bảng quản lý với các tính năng:

```mermaid theme={null}
flowchart LR
    A[Màn hình Danh sách Người giới thiệu] --> B[Bảng dữ liệu]
    A --> C[Thanh tìm kiếm]
    A --> D[Phân trang]
    A --> E[Nút Thêm mới]
    A --> F[Nút Import Excel]
    C --> C1[Tìm kiếm theo Tên, Số điện thoại hoặc Mã giới thiệu]
```

### Cấu trúc bảng danh sách:

| Cột thông tin | Mô tả |
| - | - |
| **Họ và tên** | Tên đầy đủ của người giới thiệu |
| **Email** | Email liên hệ |
| **Số điện thoại** | Số điện thoại liên lạc |
| **Mã giới thiệu** | Mã code duy nhất 4 ký tự |
| **Số lượng Merchant** | Số lượng Merchant đã đăng ký thành công bằng mã này |
| **Ngày tạo** | Thời gian tạo tài khoản |
| **Hành động** | Các nút: Sửa, Xóa, Xem danh sách Merchant |

## Thêm mới Người giới thiệu

1. Admin nhấn nút **Thêm mới** ở góc trên bên phải
2. Hiện Modal form nhập thông tin: Họ và tên, Email, Số điện thoại (Frontend không có trường nhập Mã giới thiệu).
3. Admin điền thông tin và nhấn **Lưu**
4. Hệ thống (Backend) tự động sinh Mã giới thiệu ngẫu nhiên (4 ký tự) dựa trên tên và lưu vào hệ thống.
5. Validate thông tin → Tạo thành công → Thêm vào bảng danh sách (hiển thị Mã giới thiệu do BE trả về).

### Yêu cầu trường thông tin:

| Trường thông tin | Bắt buộc | Validate & Ràng buộc |
| - | - | - |
| **Họ và tên** | Bắt buộc | Text input, tối đa 255 ký tự |
| **Email** | Bắt buộc | Đúng định dạng email, **phải là duy nhất** trong danh sách người giới thiệu.  Lỗi: `Email đã tồn tại` |
| **Số điện thoại** | Bắt buộc | Định dạng Việt Nam 10-11 số, **phải là duy nhất** trong danh sách người giới thiệu.  Lỗi: `Số điện thoại đã tồn tại` |

> **Lưu ý về Mã giới thiệu:** Mã giới thiệu sẽ do Backend tự động sinh (gồm các chữ cái đầu của tên viết hoa, loại bỏ dấu + bù thêm số ngẫu nhiên để đủ 4 ký tự. Ví dụ: `Nguyễn Văn An` → `NVA0`) và trả về sau khi tạo thành công. Frontend không cần gửi field này lên khi tạo mới. Mã này đảm bảo tính duy nhất (unique) trên toàn hệ thống.

## Import danh sách bằng Excel

Cho phép Admin thêm hàng loạt người giới thiệu thông qua file Excel để tiết kiệm thời gian.

1. **Tải file mẫu (Download Template)**
   * Hệ thống cung cấp file Excel mẫu bao gồm các cột: `Họ và tên` (Bắt buộc), `Email` (Bắt buộc), `Số điện thoại` (Bắt buộc). Không có cột `Mã giới thiệu`.
   * Có kèm theo ghi chú định dạng ở dòng tiêu đề (header).

2. **Quy tắc Validate File**
   * **Định dạng file:** `.xlsx`, `.xls`, `.csv`
   * **Dung lượng tối đa:** 5MB
   * **Ràng buộc dữ liệu từng dòng:**
     * `Họ và tên`, `Email`, `Số điện thoại` validate định dạng tương tự như thêm mới thủ công.
     * Kiểm tra trùng lặp Email, SĐT trong chính file Excel.
     * Kiểm tra trùng lặp Email, SĐT với dữ liệu hiện có trong hệ thống.
     * `Mã giới thiệu`: Backend sẽ tự động sinh cho từng dòng hợp lệ theo quy tắc giống như Thêm mới thủ công.

3. **Xử lý kết quả Import**
   * Sau khi tải file lên, hệ thống sẽ hiển thị Preview (xem trước) kết quả quét dữ liệu.
   * Hiển thị số dòng **Hợp lệ** và số dòng **Lỗi** (kèm chi tiết mô tả lỗi của từng dòng, ví dụ: "Email sai định dạng", "Trùng số điện thoại").
   * **Cơ chế Import:**
     * Hệ thống chỉ Import các dòng **Hợp lệ (Valid)**.
     * Bỏ qua không Import các dòng **Lỗi (Invalid)**.
   * Hiển thị thông báo tổng kết sau khi hoàn tất: `Import thành công X bản ghi. Có Y bản ghi bị lỗi.`
   * Cho phép Admin tải xuống danh sách các dòng lỗi (file Excel) để chỉnh sửa và Import lại sau.

## Chỉnh sửa Người giới thiệu

* Cho phép chỉnh sửa tất cả các trường thông tin: Họ tên, Email, Số điện thoại, Mã giới thiệu

* **Quy tắc nghiệp vụ khi chỉnh sửa**:
  * Kiểm tra tính duy nhất (Unique) tương tự lúc thêm mới, **ngoại trừ chính bản ghi đang sửa**
  * Nếu Mã giới thiệu bị thay đổi:
    * Các Merchant cũ đã đăng ký bằng mã cũ **vẫn giữ nguyên lịch sử** và dữ liệu báo cáo
    * Từ thời điểm thay đổi, Merchant mới chỉ có thể đăng ký bằng **mã mới**
  * Tất cả các giới thiệu cũ sẽ luôn được tính cho người giới thiệu này bất kể mã có thay đổi

## Xóa Người giới thiệu

```mermaid theme={null}
flowchart TB
    A["Admin nhấn nút Xóa"] --> B{"Hiển thị Popup xác nhận"}

    B -- "Hủy" --> Z["Đóng Popup"]
    B -- "Đồng ý" --> D{"Đã có Merchant được giới thiệu?"}

    D -- "Đã có Merchant" --> E["Chuyển trạng thái sang Ngừng hoạt động (Deactivate)
    - Không xóa vật lý dữ liệu
    - Giữ nguyên lịch sử & báo cáo"]

    D -- "Chưa có Merchant nào" --> F["Xóa hoàn toàn khỏi hệ thống (Hard Delete)"]

    E --> G["Cập nhật lại bảng danh sách"]
    F --> G
```

**Ràng buộc xóa:**

* Không bao giờ xóa vật lý người giới thiệu đã có Merchant liên kết
* Dữ liệu lịch sử phải luôn được bảo toàn cho mục đích báo cáo và thống kê
* Người giới thiệu bị ngừng hoạt động sẽ không thể tạo thêm giới thiệu mới

## Xem danh sách Merchant được giới thiệu

* Tại mỗi dòng trong bảng danh sách, Admin nhấn nút **Xem danh sách**
* Hiện Modal/Danh sách chi tiết các Merchant đã được giới thiệu bởi người này
* Thông tin hiển thị:
  * Tên Merchant
  * Email Merchant
  * Ngày đăng ký thành công
  * Trạng thái tài khoản Merchant
  * Nút xem chi tiết merchant (Link tới **US-ADM-04**)

## Ràng buộc Bảo mật & Xử lý lỗi

| Quy tắc | Mô tả |
| - | - |
| Realtime Validation | Kiểm tra tính duy nhất Email, Số điện thoại, Mã giới thiệu ngay khi người dùng gõ, không đợi submit form |
| Mã giới thiệu unique | Hệ thống phải đảm bảo không bao giờ có 2 người giới thiệu cùng 1 mã, kể cả trong trường hợp đồng thời tạo |
| Dữ liệu lịch sử | Không bao giờ sửa đổi hay xóa các giao dịch giới thiệu đã xảy ra |
| Audit Log | Tất cả thao tác Thêm, Sửa, Xóa người giới thiệu đều được ghi log hành động của Admin |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.