PRD: Khuyến mãi, phương thức & quy tắc phân khúc

Module	Định giá	PRD ID	PRD-PROMO-001
Trạng thái	Sẵn sàng dev	FEAT	PROMO
Epic	—	Plane	BANA-1573
Ngày	2026-06-15	Phiên bản	v1.0
Gói	@nx/pricing	URD	PROMO
Surface	Client · Chủ/QL
Phụ trách	Phát Nguyễn

Khuyến mãi, phương thức & quy tắc phân khúc là gì

Feature này cho phép merchant cấu hình một chiến dịch giảm giá như một đối tượng độc lập, hoàn chỉnh: một khuyến mãi (Promotion) mang đúng một phương thức (Promotion Method) - số tiền cố định hoặc phần trăm; nhắm vào dòng hàng, cả đơn hàng, hoặc vận chuyển; phân bổ theo từng món, trải đều, hoặc một lần - và một cơ chế: giảm thẳng (tiêu chuẩn) hoặc deal mua-X-tặng-Y (mua-tặng). Ba tập quy tắc phân khúc chiến dịch: điều kiện quyết định ai/khi nào đủ điều kiện, nguồn quyết định cần mua gì, đích quyết định cái gì được giảm. Toàn bộ đồ thị - khuyến mãi, phương thức, cả ba tập quy tắc - được tạo và sửa trong một aggregate nguyên tử; số đếm quy tắc được lưu lúc tạo và chưa được tính lại khi cập nhật aggregate.

Việc áp giảm giá khi thanh toán là một bước sau này có chủ đích; PRD này đặc tả aggregate cấu hình khuyến mãi - khuyến mãi, phương thức và ba tập quy tắc.

Vì sao cần một đối tượng khuyến mãi hạng nhất

Định giá đã chọn fare (FARE) và tính thuế (TAX), nhưng merchant chưa có cách diễn đạt một chiến dịch giảm giá - "giảm 10% đồ uống trước 17h", "mua 2 cà phê tặng 1", "giảm 50.000₫ cho đơn trên 300.000₫". Một chiến dịch không phải là một fare: nó trải trên nhiều dòng hàng, có thể nhắm vào đơn hàng hoặc vận chuyển thay vì một món, và phải nói không chỉ giảm bao nhiêu mà còn ai đủ điều kiện, cái gì kích hoạt, và cái gì được giảm.

Không có đối tượng khuyến mãi hạng nhất, chủ merchant hoàn toàn không thể dựng các ưu đãi này, và dữ liệu cần để áp chúng khi thanh toán cũng không tồn tại. Bước tăng trưởng này lấp khoảng trống cấu hình: cho chủ merchant một khuyến mãi với một phương thức, một cơ chế tiêu chuẩn hoặc mua-tặng, và ba tập quy tắc riêng biệt, tất cả được soạn và sửa như một đơn vị nguyên tử - nên một chiến dịch luôn được lưu trọn vẹn hoặc không lưu gì cả, không bao giờ dựng dở.

Một ví dụ từ đầu tới cuối

Bước	Việc xảy ra	Kết quả
Chủ merchant tạo khuyến mãi "Mua 2 cà phê, tặng 1"	Gửi một request duy nhất: cơ chế mua-tặng, một phương thức phần trăm giá trị 100 nhắm dòng hàng (nguồn-tối-thiểu 2, đích 1), một quy tắc nguồn (đồ uống đủ điều kiện), một quy tắc đích (đồ uống được tặng), một quy tắc điều kiện giới hạn kênh dùng tại chỗ	Khuyến mãi, phương thức và cả ba quy tắc được lưu cùng nhau trong một lần gọi nguyên tử; số đếm quy tắc đọc lại đúng
Sau đó chủ merchant sửa lại chiến dịch	Gửi một cập nhật aggregate: bỏ quy tắc kênh, nâng giới hạn lượt dùng	Toàn bộ thay đổi được lưu trong một lần lưu nguyên tử duy nhất

Chỗ dễ sai nhất

Số đếm quy tắc không tự cập nhật khi sửa aggregate

Số đếm quy tắc điều kiện / nguồn / đích được ghi một lần lúc tạo aggregate. Cập nhật aggregate về sau - thêm, sửa, hoặc xóa quy tắc - chưa tính lại các con số này, nên số đếm hiển thị có thể lệch khỏi số quy tắc thực sự đang lưu sau một lần sửa.

1. Mục tiêu & Loại trừ

Mục tiêu

• Một đối tượng khuyến mãi với cơ chế (tiêu chuẩn hoặc mua-tặng), một mã hoặc kích hoạt tự động, khoảng thời gian hiệu lực, giới hạn lượt dùng và trạng thái vòng đời.
• Đúng một phương thức cho mỗi khuyến mãi khai báo cơ chế: cố định hoặc phần trăm, một đích (dòng hàng / đơn hàng / vận chuyển), một phân bổ (theo từng món / trải đều / một lần), và giới hạn số lượng được giảm.
• Hỗ trợ mua-tặng: một phương thức khai báo số lượng nguồn tối thiểu (phải mua) và số lượng đích (được giảm).
• Ba tập quy tắc phân khúc - điều kiện (trên khuyến mãi), nguồn và đích (trên phương thức) - dùng lại mô hình quy tắc chung (thuộc tính, toán tử, giá trị, logic AND).
• Một aggregate nguyên tử cho tạo và cập nhật trên khuyến mãi + phương thức + mọi tập quy tắc, với số đếm quy tắc được lưu lúc tạo (chưa được tính lại khi cập nhật) và trộn quy tắc theo hình dạng khi cập nhật.
• Xóa lan truyền loại bỏ phương thức và mọi quy tắc đính kèm cùng khuyến mãi.

Loại trừ

• Áp giảm giá khuyến mãi khi định giá lúc thanh toán - bộ tính chưa được đấu nối vào bất kỳ luồng mô phỏng nào (URD-PROMO-006, vẫn là Không làm trong bước này).
• Chọn fare và tính thuế - thuộc FARE và TAX.
• Quy đổi đa tiền tệ cho số tiền giảm (tiền tệ và tỷ giá được mang theo, không quy đổi ở đây).
• Lưu trữ đơn hàng, phát hành hóa đơn, tác động lên tồn kho hoặc thanh toán.

2. Thước đo thành công

Thước đo	Mục tiêu / dấu hiệu
Tính nguyên tử	Một bước con thất bại (thiếu trường quy tắc, không có phương thức) không lưu lại gì
Aggregate trọn vẹn	Mỗi khuyến mãi được lưu có đúng một phương thức; các tập quy tắc được lưu cùng nó
Số đếm chính xác	Số đếm quy tắc điều kiện / nguồn / đích khớp với quy tắc được lưu lúc tạo; khi cập nhật aggregate số đếm chưa được tính lại và có thể lệch
Toàn vẹn khi sửa	Cập nhật aggregate tạo, sửa và xóa quy tắc trong một lần lưu nguyên tử theo hình dạng mục
Toàn vẹn mã	Không có hai khuyến mãi còn sống trong cùng một merchant dùng chung một mã (thiết kế đích - xem Rủi ro)

3. Persona & Tình huống

Persona	Mục tiêu trong tính năng này
Chủ merchant / Quản lý	Dựng một chiến dịch giảm giá - chọn cơ chế, đích, và các quy tắc phân khúc nó
Nhân viên marketing	Soạn ưu đãi giới hạn thời gian (giờ vàng, ngày trong tuần, theo kênh) và rút lại qua trạng thái
Hệ thống (thanh toán tương lai)	Đọc một đồ thị khuyến mãi hoàn chỉnh, hợp lệ để áp tại điểm bán (bước tăng trưởng sau)

Kịch bản chính: chủ merchant tạo khuyến mãi "Mua 2 cà phê, tặng 1" - cơ chế mua-tặng, một phương thức phần trăm giá trị 100 nhắm dòng hàng với nguồn-tối-thiểu 2 và đích 1, một quy tắc nguồn (đồ uống đủ điều kiện) và một quy tắc đích (đồ uống tặng), cộng một quy tắc điều kiện giới hạn kênh dùng tại chỗ. Khuyến mãi, phương thức và cả ba quy tắc được lưu trong một lời gọi nguyên tử; số đếm quy tắc đọc lại đúng. Sau đó chủ merchant sửa aggregate để bỏ quy tắc kênh và nâng giới hạn lượt dùng - tất cả trong một lần lưu nguyên tử.

4. User Stories

#	Là một	Tôi muốn	Để
01	chủ merchant	tạo một khuyến mãi, phương thức và mọi quy tắc của nó trong một request	chiến dịch không bao giờ bị lưu dở
02	chủ merchant	chọn số tiền cố định hay phần trăm và nhắm nó vào dòng hàng, đơn hàng hoặc vận chuyển	ưu đãi khớp với cái tôi đang quảng bá
03	chủ merchant	dựng deal mua-X-tặng-Y bằng cách đặt số lượng nguồn phải mua và số lượng đích được giảm	các ưu đãi combo kinh điển khả thi
04	nhân viên marketing	phân khúc một ưu đãi bằng quy tắc điều kiện, nguồn và đích	nó chỉ kích hoạt với đúng giỏ hàng trên đúng kênh
05	nhân viên marketing	rút một ưu đãi bằng cách chuyển trạng thái sang ngừng hoặc hết hạn	nó dừng mà không bị xóa
06	chủ merchant	sửa quy tắc của một khuyến mãi đang có - thêm, đổi và bỏ - trong một lần lưu	bảo trì là một bước nguyên tử duy nhất

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

#	Yêu cầu	Trạng thái	URD ref
FR-001	Một khuyến mãi, phương thức duy nhất của nó, và các tập quy tắc được tạo cùng nhau trong một aggregate nguyên tử.	✅	URD-PROMO-001
FR-002	Một khuyến mãi có nhiều nhất một phương thức.	✅	URD-PROMO-003
FR-003	Phương thức giảm theo số tiền cố định hoặc theo phần trăm, và mang giá trị giảm tương ứng.	✅	URD-PROMO-008
FR-004	Phương thức nhắm vào một trong ba đích: dòng hàng, đơn hàng, hoặc vận chuyển.	✅	URD-PROMO-009
FR-005	Phương thức khai báo cách phân bổ khoản giảm. • Ba cách phân bổ: theo từng món, trải đều trên các món, hoặc một lần cho cả nhóm. • Phương thức có thể giới hạn số lượng được hưởng giảm.	✅	URD-PROMO-010..011
FR-006	Một khuyến mãi là loại tiêu chuẩn hoặc loại mua-tặng. • Khuyến mãi tiêu chuẩn giảm trực tiếp trên đích đã chọn. • Phương thức mua-tặng khai báo số lượng nguồn tối thiểu và số lượng đích được tặng.	✅	URD-PROMO-007 · URD-PROMO-012
FR-007	Ba tập quy tắc phân khúc một chiến dịch. • Quy tắc điều kiện đặt trên khuyến mãi: ai và đơn nào đủ điều kiện. • Quy tắc nguồn đặt trên phương thức: món nào được tính là hàng mua. • Quy tắc đích đặt trên phương thức: món nào được giảm hoặc được tặng. • Cả ba dùng lại cùng một mô hình quy tắc chung.	✅	URD-PROMO-013 · URD-PROMO-004
FR-008	Số đếm quy tắc điều kiện / nguồn / đích được lưu sẵn trên khuyến mãi. • Số đếm được đặt lúc tạo aggregate. • Số đếm chưa được tính lại khi cập nhật aggregate, nên có thể lệch sau khi sửa quy tắc.	🔶	URD-PROMO-014
FR-009	Một khuyến mãi mang ba thuộc tính điều phối. • Một mã duy nhất tùy chọn; không nhập mã thì hệ thống tự sinh. • Một cờ cho biết khuyến mãi có được cộng dồn với khuyến mãi khác hay không. • Một cờ cho biết giá trị giảm đã gồm thuế hay chưa.	✅	URD-PROMO-015..016
FR-010	Một khuyến mãi mang khoảng thời gian hiệu lực, giới hạn lượt dùng, và số lượt đã dùng đang chạy.	✅	URD-PROMO-017
FR-011	Một khuyến mãi đi qua các trạng thái vòng đời, mặc định là nháp.	✅	URD-PROMO-018
FR-012	Cập nhật aggregate trộn các quy tắc trong một lần lưu nguyên tử. • Mỗi mục quy tắc gửi lên được hiểu là tạo mới, sửa, hoặc xóa theo hình dạng của chính nó. • Cả lần lưu thành công trọn vẹn hoặc không thay đổi gì.	✅	URD-PROMO-019 · URD-PROMO-002
FR-013	Xóa một khuyến mãi lan truyền tới phương thức và mọi quy tắc đính kèm, một cách nguyên tử.	✅	URD-PROMO-020
FR-014	Khuyến mãi, phương thức và quy tắc được giới hạn trong merchant của chính người dùng, và xóa là xóa mềm.	✅	URD-PROMO-005

5.1 Tiêu chí nghiệm thu

• Gửi một yêu cầu tạo aggregate kèm phương thức và các quy tắc trong một request → khuyến mãi, phương thức và mọi quy tắc được lưu cùng nhau; bỏ trống một trường bắt buộc của một quy tắc trong cùng request → cả yêu cầu bị từ chối, không gì được lưu.
• Gửi một yêu cầu tạo aggregate kèm hai phương thức cho cùng một khuyến mãi → yêu cầu bị từ chối, một khuyến mãi chỉ giữ đúng một phương thức.
• Tạo một phương thức kiểu cố định với giá trị 50.000₫, hoặc kiểu phần trăm với giá trị 20 → phương thức lưu đúng kiểu và giá trị giảm đã nhập.
• Tạo một phương thức nhắm dòng hàng, rồi một phương thức khác nhắm đơn hàng, rồi một phương thức khác nhắm vận chuyển → cả ba đích đều được lưu và đọc lại đúng.
• Tạo một phương thức với phân bổ trải đều và giới hạn số lượng được giảm là 3 → phương thức áp phân bổ trải đều và không giảm quá 3 đơn vị.
• Tạo khuyến mãi mua-tặng với phương thức khai báo số lượng nguồn-tối-thiểu 2 và đích 1 → phương thức lưu đúng hai số lượng; tạo khuyến mãi tiêu chuẩn không khai báo số lượng mua-tặng → phương thức lưu bình thường, không kèm hai trường đó.
• Tạo một khuyến mãi kèm một quy tắc điều kiện, một quy tắc nguồn và một quy tắc đích trong cùng request → cả ba quy tắc được lưu, phân biệt đúng theo ngữ cảnh (điều kiện trên khuyến mãi, nguồn/đích trên phương thức).
• Tạo một khuyến mãi kèm 2 quy tắc điều kiện → đọc lại số đếm quy tắc điều kiện đúng bằng 2; cập nhật aggregate để thêm một quy tắc điều kiện thứ ba → quy tắc mới được lưu nhưng số đếm đọc lại vẫn là 2, chưa phản ánh quy tắc vừa thêm.
• Tạo một khuyến mãi không nhập mã → khuyến mãi lưu ở chế độ tự động, không có mã; tạo một khuyến mãi khác với mã "SUMMER10" cùng cờ stacking bật và cờ đã-gồm-thuế bật → cả ba trường được lưu đúng.
• Tạo một khuyến mãi với hiệu lực từ ngày A đến ngày B và giới hạn lượt dùng là 100 → ba trường được lưu; đọc lại số lượt dùng đang chạy → mặc định bằng 0.
• Tạo một khuyến mãi mới không truyền trạng thái → trạng thái mặc định là nháp; cập nhật trạng thái sang kích hoạt, rồi sang ngừng → mỗi bước chuyển đúng vòng đời.
• Cập nhật aggregate với một quy tắc không kèm id, một quy tắc kèm id và trường sửa, một quy tắc chỉ kèm id → quy tắc đầu được tạo mới, quy tắc thứ hai được sửa, quy tắc thứ ba bị xóa, tất cả trong một lần lưu.
• Xóa một khuyến mãi đang có phương thức và các quy tắc đính kèm → phương thức và mọi quy tắc bị xóa theo, không còn bản ghi mồ côi.
• Đăng nhập bằng tài khoản chủ merchant X và liệt kê khuyến mãi → chỉ khuyến mãi của merchant X được trả về; xóa một khuyến mãi rồi liệt kê lại → khuyến mãi đó không còn xuất hiện dù bản ghi vẫn còn trong hệ thống (xóa mềm).

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

Khía cạnh	Yêu cầu
Tính nguyên tử	Toàn bộ đồ thị chiến dịch - khuyến mãi, phương thức, quy tắc điều kiện / nguồn / đích - là một lần lưu được-ăn-cả-ngã-về-không
Tenancy & phân quyền	Mọi thao tác giới hạn trong merchant của chính người dùng, xác thực và gác bởi quyền khuyến mãi / phương thức / quy tắc
Kiểm tra hợp lệ	Một quy tắc được tạo trong một aggregate phải mang thuộc tính, toán tử và kiểu dữ liệu, nếu không cả thao tác bị từ chối
Nhất quán	Số đếm quy tắc được đặt trong lần lưu nguyên tử của aggregate tạo; cập nhật aggregate chưa tính lại chúng
Độ chính xác	Giá trị giảm, số lượng tối đa và số lượng mua-tặng dùng độ chính xác 4 chữ số thập phân
i18n	Tên và mô tả khuyến mãi là song ngữ

7. UX & Luồng

Bề mặt cấu hình cho chủ merchant chọn cơ chế, đặt mã (hoặc để tự động), xác định cửa sổ hiệu lực và giới hạn lượt dùng, chọn cơ chế / đích / phân bổ của phương thức, nhập số lượng mua-tặng, và đính ba tập quy tắc. Việc sửa dùng lại cùng aggregate; trạng thái đưa chiến dịch qua vòng đời mà không cần xóa.

8. Dữ liệu & Miền nghiệp vụ

Khái niệm	Vai trò trong feature này
Khuyến mãi	Chiến dịch - cơ chế, mã/tự động, stacking, đã-gồm-thuế, cửa sổ hiệu lực, giới hạn/số lượt dùng, trạng thái; giữ các quy tắc điều kiện
Phương thức khuyến mãi	Cơ chế duy nhất - giá trị cố định/phần trăm, kiểu đích, phân bổ, giới hạn số lượng được giảm, số lượng nguồn-tối-thiểu và đích mua-tặng
Quy tắc	Một điều kiện đa hình (thuộc tính, toán tử, giá trị, ưu tiên); gắn vào khuyến mãi (điều kiện) hoặc phương thức (nguồn / đích, phân biệt bởi ngữ cảnh)

Chỉ mang tính khái niệm - schema đầy đủ và bất biến nằm trong mô hình miền Định giá. Quy tắc nguồn và đích của một phương thức là cùng một khái niệm được phân biệt bằng một thẻ ngữ cảnh được lưu; toàn vẹn được đảm bảo bởi logic aggregate, không phải bởi ràng buộc cơ sở dữ liệu.

9. Phụ thuộc & Giả định

Phụ thuộc vào

#	Feature	Phụ thuộc điều gì
01	PROMO Mô hình quy tắc chung	Quy tắc điều kiện, nguồn và đích dùng lại cùng hình dạng thuộc tính / toán tử / giá trị với logic AND; cùng mô hình này cũng dùng bởi FARE (URD-PROMO-004).
02	Commerce / Merchant	Mọi khuyến mãi, phương thức và quy tắc đều được giới hạn trong merchant của chính người dùng.
03	Mô hình định giá chung	Định nghĩa khuyến mãi, phương thức và quy tắc, các cơ chế và giá trị trạng thái.

Giả định

#	Giả định	Sai thì sao
01	Một khuyến mãi có đúng một phương thức; chiến dịch nhiều phương thức nằm ngoài phạm vi.	Một merchant cần nhiều phương thức trên cùng một khuyến mãi thì mô hình hiện tại không biểu diễn được, phải tách thành nhiều khuyến mãi riêng.
02	Quy tắc nguồn và đích chỉ có ý nghĩa với cơ chế kiểu mua-tặng; khuyến mãi tiêu chuẩn thường chỉ dùng quy tắc điều kiện.	Khai quy tắc nguồn/đích cho một khuyến mãi tiêu chuẩn không có tác dụng, vì cơ chế tiêu chuẩn không đọc tới hai tập quy tắc đó.
03	Bộ tính lúc thanh toán tiêu thụ cấu hình này là một bước tăng trưởng riêng, sau này.	Nếu bộ tính thanh toán không tôn trọng đúng hình dạng aggregate này khi được nối vào, một chiến dịch hợp lệ về cấu hình vẫn có thể áp sai lúc thanh toán.

10. Kế hoạch phát hành & Tiêu chí

Khía cạnh	Kế hoạch
Phase	P3 - xem danh mục feature URD
Rollout	Mọi merchant; không cờ tính năng
Migration	Không - dữ liệu khuyến mãi / phương thức / quy tắc mới; không đổi dữ liệu fare/thuế hiện có
Tiêu chí phát hành	Tạo aggregate lưu khuyến mãi + một phương thức + mọi tập quy tắc nguyên tử; số đếm đọc lại đúng; cập nhật aggregate trộn quy tắc theo hình dạng; xóa lan truyền; mã duy nhất theo từng merchant (thiết kế đích)
Theo dõi	Tỷ lệ lỗi tạo/cập nhật aggregate theo lý do (thiếu trường quy tắc, không có phương thức, xung đột mã)

Tham chiếu

• URD: Định giá - PROMO
• PRD cùng nhóm: Bộ máy định giá Fare & Thuế
• Module: Định giá - URD
• Tài liệu kỹ thuật: @nx/pricing · Promotion System · @nx/core

Rủi ro & Câu hỏi mở

#	Rủi ro / câu hỏi	Giảm thiểu / trạng thái
01	Chiến dịch dở dang khi thất bại (khuyến mãi không phương thức, hoặc có quy tắc mồ côi)	Toàn bộ đồ thị là một lần lưu nguyên tử - bất kỳ thất bại nào cũng rollback hoàn toàn
02	Số đếm quy tắc lệch với quy tắc thực sự lưu	Số đếm được đặt trong lần lưu nguyên tử của aggregate tạo; cập nhật aggregate chưa tính lại chúng, nên số đếm có thể lệch sau một lần sửa thêm/bớt quy tắc (lỗ hổng đã biết)
03	Ý định sửa mơ hồ (thêm vs đổi vs bỏ một quy tắc)	Cập nhật aggregate theo hình dạng: không id tạo, id+trường sửa, chỉ id xóa
04	Hai khuyến mãi còn sống dùng lại một mã	Ràng buộc mã duy nhất hiện ở phạm vi toàn hệ thống (chưa gồm merchant), nên hai merchant chưa thể dùng trùng một mã; thiết kế đích là mã duy nhất theo từng merchant, cần bổ sung merchant vào ràng buộc (lỗ hổng đã biết)
05	Chủ merchant mong giảm giá áp khi thanh toán	Ngoài phạm vi bước này - bộ tính chưa được đấu nối (URD-PROMO-006)

Câu hỏi thường gặp

#	Câu hỏi	Trả lời
01	Tạo một khuyến mãi có áp giảm giá khi thanh toán không?	Không - bước này chỉ bàn giao bề mặt cấu hình. Bộ tính áp khuyến mãi khi định giá là một bước tăng trưởng riêng, sau này (URD-PROMO-006).
02	Một khuyến mãi có bao nhiêu phương thức?	Đúng một. Cơ chế (cố định/phần trăm, đích, phân bổ, số lượng mua-tặng) đều nằm trên phương thức duy nhất đó.
03	Ba tập quy tắc khác nhau ở đâu?	Quy tắc điều kiện (trên khuyến mãi) quyết định ai/khi nào đủ điều kiện; quy tắc nguồn (trên phương thức) quyết định cái gì phải mua; quy tắc đích (trên phương thức) quyết định cái gì được giảm. Nguồn và đích là cùng một khái niệm quy tắc phân biệt bởi một thẻ ngữ cảnh được lưu.
04	Tôi sửa quy tắc của một chiến dịch thế nào?	Gửi một cập nhật aggregate - quy tắc không id được tạo, quy tắc có id và trường được sửa, quy tắc chỉ có id được xóa, tất cả trong một lần lưu nguyên tử.
05	Điều gì xảy ra với phương thức và quy tắc khi tôi xóa một khuyến mãi?	Chúng bị xóa lan truyền cùng nó một cách nguyên tử - không để lại phương thức hay quy tắc mồ côi.
06	Một khuyến mãi không có mã nghĩa là gì?	Nó chỉ tự động (auto-apply). Một mã, khi có, là duy nhất trong số các khuyến mãi còn sống; thiết kế đích là duy nhất theo từng merchant.