Cấu Hình Hoa Hồng

I. Tổng quan

1. Vấn đề

Các cửa hàng cần một cơ chế linh hoạt để tính và quản lý hoa hồng cho nhân viên. Hoa hồng có thể được tính theo nhiều tiêu chí khác nhau (nguồn đơn, công thức, giá trị đơn, danh mục sản phẩm, hình thức bán sỉ/lẻ) và cần hỗ trợ cấu trúc phân cấp cha-con để quản lý nhiều nhóm nhân viên với chính sách hoa hồng riêng biệt.

2. Giải pháp

Cung cấp tính năng Cấu hình hoa hồng với cấu trúc cha-con:

Cấu hình cha: Gom nhóm nhân viên và chứa nhiều cấu hình con.
Cấu hình con: Định nghĩa chi tiết dạng tính và cách tính hoa hồng.

Hỗ trợ 5 dạng tính và 3 cách tính, cho phép tùy biến linh hoạt theo nghiệp vụ từng cửa hàng.

3. Đối tượng

Quản lý / Chủ cửa hàng: Tạo và cấu hình chính sách hoa hồng.
Nhân viên bán hàng: Đối tượng được áp dụng hoa hồng theo cấu hình đã thiết lập.

4. Tầm nhìn/insight

Hỗ trợ mô hình hoa hồng đa tầng (multi-level) cho các chuỗi cửa hàng.
Tích hợp báo cáo hoa hồng tự động theo kỳ (tuần/tháng).
Mở rộng thêm các dạng tính theo sản phẩm đơn lẻ hoặc theo nhóm nhân viên trong tương lai.

II. Yêu cầu chức năng

1. Danh sách tính năng

Tạo mới cấu hình hoa hồng cha
Thêm/xóa nhân viên trong cấu hình cha
Tạo/sửa/xóa cấu hình hoa hồng con trong cấu hình cha
Chọn dạng nhân viên cho cấu hình con
Chọn dạng tính hoa hồng (5 dạng)
Chọn cách tính hoa hồng (3 cách)
Cài đặt mức bậc thang (nhiều mức giá trị)
Lưu và kích hoạt cấu hình

2. Đặc tả chi tiết

2.1. Luồng tạo cấu hình hoa hồng

Cấu hình → Cấu hình hoa hồng → Tạo mới
    └── Bước 1: Tạo cấu hình cha
            ├── Nhập tên cấu hình
            └── Thêm danh sách nhân viên áp dụng
    └── Bước 2: Tạo cấu hình con
            ├── Nhập tên cấu hình con
            ├── Chọn dạng nhân viên
            ├── Chọn dạng tính hoa hồng (1 trong 5 dạng)
            └── Chọn cách tính hoa hồng (1 trong 3 cách)
    └── Bước 3: Lưu cấu hình
            ├── Bấm "Đồng ý" để hoàn thành thiết lập cấu hình con
            └── Bấm "Lưu" để lưu toàn bộ cấu hình cha

2.2. Cấu hình cha

Trường	Mô tả	Bắt buộc
Tên cấu hình	Tên định danh cho nhóm cấu hình hoa hồng	✅
Danh sách nhân viên	Các nhân viên được áp dụng cấu hình hoa hồng	✅

Một cấu hình cha có thể chứa nhiều cấu hình con.

2.3. Cấu hình con — Dạng nhân viên

Dạng nhân viên xác định điều kiện để cấu hình con được kích hoạt. Chỉ khi nhân viên thuộc đúng dạng đã chọn, hoa hồng mới được tính.

2.4. Cấu hình con — 5 Dạng tính hoa hồng

Dạng 1: Phân loại theo nhiều điều kiện bộ lọc

Khi cần áp dụng hoa hồng với nhiều tiêu chí kết hợp, bạn có thể thêm bộ điều kiện (condition group) cho từng cấu hình nguồn đơn. Mỗi điều kiện trong nhóm được nối với nhau theo logic VÀ (AND) — tức là đơn hàng phải thỏa tất cả điều kiện trong nhóm mới được tính hoa hồng. Issue: khi user cài đặt bộ lọc mà ko cover hết case???

Các điều kiện có thể kết hợp:

Điều kiện	Mô tả	Ví dụ
Nguồn đơn	Đơn hàng đến từ nguồn nào	Facebook, Zalo, Website
Khoảng thời gian	Chỉ áp dụng trong khung giờ / ngày / tháng nhất định	8:00–22:00, Thứ 2–Thứ 6
Giá trị đơn hàng tối thiểu	Đơn phải đạt ngưỡng giá trị nhất định	≥ 500.000 VNĐ
Hình thức bán	Kết hợp thêm điều kiện sỉ hoặc lẻ	Chỉ đơn lẻ
Trạng thái đơn	Chỉ tính hoa hồng khi đơn ở trạng thái hoàn thành	Đã giao / Đã thanh toán

Cách cấu hình nhiều nhóm điều kiện (OR giữa các nhóm):

Nếu muốn áp dụng hoa hồng theo nhiều tập điều kiện khác nhau (ví dụ: nhóm A hoặc nhóm B đều được tính), bạn tạo nhiều cấu hình con độc lập — mỗi cấu hình con là một nhóm điều kiện riêng. Các cấu hình con trong cùng cấu hình cha được xét theo logic HOẶC (OR).

Cấu hình cha: "Hoa hồng đa nguồn"
    ├── Cấu hình con 1: Facebook + Giá trị ≥ 500k  → Hoa hồng 5%
    ├── Cấu hình con 2: Zalo + Giá trị ≥ 300k      → Hoa hồng 3%
    └── Cấu hình con 3: Website (không giới hạn)   → Hoa hồng 2%

Lưu ý: Nếu một đơn hàng thỏa nhiều cấu hình con cùng lúc, hệ thống sẽ áp dụng theo thứ tự ưu tiên (cấu hình con được xếp trước có độ ưu tiên cao hơn). Cần xác nhận với dev về cách xử lý xung đột.

Dạng 2: Theo công thức

POS cung cấp các mục tính toán sẵn có.
Người dùng tùy chỉnh công thức tính hoa hồng phù hợp với nghiệp vụ cửa hàng.

Trường	Mô tả	Bắt buộc
Công thức	Kết hợp các mục tính toán do POS cung cấp	✅

Dạng 3: Theo giá trị đơn hàng

Hoa hồng được tính dựa trên giá trị đơn hàng.
Cài đặt mức hoa hồng tương ứng với từng mức giá trị.

Trường	Mô tả	Bắt buộc
Mức hoa hồng	Giá trị hoặc % áp dụng trên đơn	✅

Dạng 4: Theo danh mục sản phẩm

Nhân viên lên đơn có sản phẩm thuộc danh mục được chọn thì được hưởng hoa hồng.
Cần chọn danh mục sản phẩm cụ thể khi cấu hình.

Trường	Mô tả	Bắt buộc
Danh mục sản phẩm	Một hoặc nhiều danh mục được áp dụng	✅
Mức hoa hồng	Giá trị hoặc % áp dụng theo danh mục	✅

Dạng 5: Theo hình thức bán sỉ/lẻ

Hoa hồng được tính theo doanh thu của đơn hàng, phân biệt hình thức bán sỉ hoặc bán lẻ.
Chỉ cần cấu hình mức hoa hồng trên doanh thu.

Trường	Mô tả	Bắt buộc
Hình thức bán	Sỉ / Lẻ	✅
Mức hoa hồng	Giá trị hoặc % áp dụng trên doanh thu	✅

2.5. Cấu hình con — 3 Cách tính hoa hồng

Cách 1: Theo giá trị phần trăm (%)

Hoa hồng = Giá trị đơn hàng (hoặc doanh thu) × tỉ lệ % đã cài đặt.

Cách 2: Theo giá trị VNĐ

Hoa hồng = Số tiền cố định (VNĐ) cho mỗi đơn hàng/doanh thu đạt điều kiện.

Cách 3: Theo mức (Bậc thang)

Người dùng cài đặt nhiều mức giá trị khác nhau.
Khi giá trị đơn hàng hoặc doanh thu đạt đủ một mức, cấu hình hoa hồng tương ứng mức đó sẽ được kích hoạt.

Mức	Giá trị đạt từ	Hoa hồng áp dụng
1	X₁ VNĐ	Y₁ % hoặc Y₁ VNĐ
2	X₂ VNĐ	Y₂ % hoặc Y₂ VNĐ
…	…	…

3. Danh sách nghiệp vụ

4. Giao diện

Màn hình Cấu hình cha

Input: Tên cấu hình
Multi-select: Danh sách nhân viên
Button: “Thêm cấu hình con”
Button: “Lưu”

Màn hình Cấu hình con

Input: Tên cấu hình con
Dropdown: Dạng nhân viên
Radio/Tab: Chọn dạng tính (5 dạng)
Radio: Chọn cách tính (%, VNĐ, Bậc thang)
Nếu chọn Bậc thang: Hiển thị bảng thêm nhiều mức
Button: “Đồng ý”

III. Yêu cầu phi chức năng

Hiệu năng: Tính toán hoa hồng phải được xử lý nhanh khi lên đơn, không làm chậm luồng tạo đơn.
Bảo mật: Chỉ Quản lý / Chủ cửa hàng có quyền tạo, sửa, xóa cấu hình hoa hồng.
Giới hạn: Một nhân viên không được thuộc nhiều cấu hình cha cùng lúc để tránh xung đột hoa hồng.
Tính nhất quán: Khi cấu hình được cập nhật, chỉ áp dụng cho các đơn hàng mới, không hồi tố đơn cũ.

IV. Dependency (liên quan & phụ thuộc)

Quản lý nhân viên: Danh sách nhân viên, dạng nhân viên (role/loại).
Quản lý đơn hàng: Nguồn đơn, giá trị đơn, hình thức bán (sỉ/lẻ).
Danh mục sản phẩm: Cấu hình hoa hồng theo danh mục phụ thuộc vào module quản lý danh mục.
Báo cáo hoa hồng: Dữ liệu cấu hình được sử dụng để tổng hợp báo cáo hoa hồng định kỳ.

V. API Contract (dev viết)

Method	Endpoint	Mô tả
GET	`/commission-configs`	Lấy danh sách cấu hình hoa hồng
POST	`/commission-configs`	Tạo mới cấu hình hoa hồng cha
PUT	`/commission-configs/:id`	Cập nhật cấu hình cha
DELETE	`/commission-configs/:id`	Xóa cấu hình cha
POST	`/commission-configs/:id/children`	Tạo cấu hình con
PUT	`/commission-configs/:id/children/:childId`	Cập nhật cấu hình con
DELETE	`/commission-configs/:id/children/:childId`	Xóa cấu hình con

VI. Test case (BA hoặc tester viết)

Happy Path

STT	Kịch bản	Kết quả mong đợi
1	Tạo cấu hình cha với tên hợp lệ và có nhân viên	Tạo thành công, hiển thị trong danh sách
2	Thêm cấu hình con dạng “Theo nguồn đơn”, cách tính “%”	Cấu hình con được lưu và áp dụng đúng nguồn đơn
3	Thêm cấu hình con dạng “Theo giá trị đơn”, cách tính “VNĐ”	Hoa hồng cố định được tính đúng khi đơn đạt điều kiện
4	Thêm cấu hình con dạng “Bậc thang” với 3 mức	Hoa hồng được áp dụng đúng theo mức đạt được
5	Thêm cấu hình con dạng “Theo danh mục” với danh mục cụ thể	Hoa hồng tính đúng khi đơn có sản phẩm thuộc danh mục
6	Thêm cấu hình con dạng “Sỉ/Lẻ”, cách tính “%”	Hoa hồng được tính đúng theo doanh thu sỉ hoặc lẻ

Exception Path

STT	Kịch bản	Kết quả mong đợi
1	Tạo cấu hình cha không nhập tên	Hiển thị lỗi “Vui lòng nhập tên cấu hình”
2	Tạo cấu hình cha không có nhân viên	Hiển thị lỗi “Vui lòng thêm ít nhất 1 nhân viên”
3	Thêm cấu hình con bậc thang nhưng không nhập giá trị mức	Hiển thị lỗi yêu cầu nhập đầy đủ giá trị các mức
4	Xóa cấu hình cha đang được áp dụng cho đơn hàng hiện tại	Hiển thị cảnh báo xác nhận trước khi xóa
5	Nhân viên thuộc 2 cấu hình cha khác nhau	Hiển thị lỗi xung đột, yêu cầu chỉ chọn 1 cấu hình cha