PRD: Quản trị Cấp phép & Kích hoạt (Back Office)

Module	Gói & giấy phép	PRD ID	PRD-LADM-001
Trạng thái	Sẵn sàng dev	FEAT	LADM
Epic	BANA-1337	Plane	BANA-1739
Ngày	2026-06-30	Phiên bản	v1.0
Gói	@nx/licensing	URD	LADM
Surface	BO · Vận hành
Phụ trách	Phát Nguyễn

Quản trị Cấp phép & Kích hoạt là gì

Engine cấp phép - gói, vòng đời giấy phép, kích hoạt thiết bị, entitlement lúc chạy - đã tồn tại, nhưng như bộ máy chạy hậu trường. Đội vận hành không có một bề mặt quản lý để định nghĩa cái ta bán (các gói thuê bao) hay để xem và vận hành giấy phép toàn nền tảng: ai đang giữ gói nào, giấy phép nào đang hiệu lực hay hết hạn, thiết bị nào đã kích hoạt.

PRD này là console cấp phép của Đội vận hành: nó biến engine thành các màn thao tác được - soạn gói, duyệt giấy phép toàn nền tảng, và quản kích hoạt. Nó bổ trợ cho onboarding, vốn tự cấp một license khi tạo client (Onboarding); console này là nơi định nghĩa gói và quản lý giấy phép về sau.

Console bao gồm những gì

Cho Đội vận hành chạy cấp phép từ Back Office: soạn các gói thuê bao (3 loại: Dùng thử / Thuê bao / Vĩnh viễn, kèm entitlement và điều khoản thời hạn - ân hạn - giới hạn kích hoạt), xem và vận hành mọi giấy phép cấp cho merchant hoặc người dùng (cấp, sửa, tạm ngưng, khôi phục, gia hạn, thu hồi theo ma trận 4 trạng thái), và quản kích hoạt thiết bị toàn nền tảng - tất cả mà không đụng vào database.

Đội vận hành chạy cấp phép như thế nào

Đội vận hành soạn một gói thuê bao kèm entitlement; duyệt danh sách giấy phép toàn nền tảng, lọc theo trạng thái hoặc loại đối tượng, mở một giấy phép để xem gói, các mốc ngày và thiết bị đã kích hoạt; cấp một giấy phép cho merchant (hoặc người dùng) mới; khi cần thì tạm ngưng, gia hạn, hoặc thu hồi - mỗi thao tác đều qua hộp xác nhận.

Chỗ dễ sai nhất

Thu hồi là một chiều, và gói không mang giá tiền

Thu hồi một giấy phép không thể hoàn tác - hộp xác nhận phải cảnh báo rõ trước khi thực hiện. Gói được soạn ở console này không có giá tiền: "điều khoản" của gói chỉ gồm thời hạn, ân hạn, giới hạn kích hoạt. Định giá và thu tiền nằm ngoài phạm vi console này.

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

Mục tiêu

• Soạn gói thuê bao - tạo, sửa, list các gói kèm loại (Dùng thử / Thuê bao / Vĩnh viễn), entitlement, và điều khoản thời hạn / ân hạn / giới hạn kích hoạt.
• Thấy giấy phép toàn nền tảng - list và soi mọi giấy phép, cấp cho merchant hoặc người dùng, kèm trạng thái và các mốc ngày.
• Vận hành một giấy phép - cấp, sửa (tên + mốc ngày), tạm ngưng / khôi phục, gia hạn, thu hồi theo ma trận trạng thái.
• Quản kích hoạt thiết bị - list, soi, thêm, sửa, xóa các thiết bị kích hoạt theo giấy phép.

Loại trừ

• Bản thân engine cấp phép - chạy hậu trường.
• Tự cấp license trong onboarding - đó là luồng onboarding (Onboarding).
• Trải nghiệm entitlement / paywall phía merchant tiêu thụ lúc chạy.
• Giá bán của gói - gói không mang giá tiền; định giá và thu tiền nằm ngoài console này.

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

Chỉ số	Mục tiêu / tín hiệu
Gói-tới-bán	Một gói định nghĩa ở đây chọn được ngay khi cấp giấy phép
Thấy giấy phép	Đội vận hành trả lời "đối tượng nào giữ giấy phép nào / trạng thái nào" từ một màn, không truy vấn database
Vận hành được	Đội vận hành cấp, tạm ngưng hoặc thu hồi một giấy phép mà không cần engineering

3. Persona & Tình huống

Persona	Mục tiêu ở tính năng này
Đội vận hành	Định nghĩa gói, cấp và vận hành giấy phép, quản kích hoạt thiết bị
Chủ quản kinh doanh	Đặt danh mục gói mà kinh doanh chào

Tình huống chính: Đội vận hành soạn một gói thuê bao kèm entitlement; duyệt danh sách giấy phép toàn nền tảng, lọc theo trạng thái hoặc loại đối tượng, mở một giấy phép để xem gói, các mốc ngày và thiết bị đã kích hoạt; cấp một giấy phép cho merchant (hoặc người dùng) mới; khi cần thì tạm ngưng, gia hạn, hoặc thu hồi - mỗi thao tác đều qua hộp xác nhận.

4. User Stories

#	Là một	Tôi muốn	Để
01	Đội vận hành	soạn gói thuê bao kèm entitlement	kinh doanh có danh mục để chào
02	Đội vận hành	thấy mọi giấy phép kèm trạng thái và đối tượng được cấp	có cái nhìn toàn nền tảng
03	Đội vận hành	cấp một giấy phép cho merchant hoặc người dùng, và thu hồi khi cần	cấp hoặc cắt dịch vụ
04	Đội vận hành	gia hạn, tạm ngưng, hoặc khôi phục một giấy phép	quản vòng đời của nó mà không cắt hẳn
05	Đội vận hành	sửa tên và các mốc ngày của một giấy phép	chỉnh điều khoản mà không phải cấp lại
06	Đội vận hành	quản kích hoạt thiết bị của một giấy phép	biết thiết bị nào đang dùng nó và gỡ thiết bị khi cần

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

#	Yêu cầu	Trạng thái	URD ref
FR-001	Soạn gói thuê bao - quản lý danh sách gói và điều khoản của từng gói. • Xem danh sách, tạo mới và sửa gói thuê bao. • Mỗi gói mang một loại: Dùng thử / Thuê bao / Vĩnh viễn. • Mỗi gói mang bộ quyền lợi (entitlements) đi kèm. • Mỗi gói mang điều khoản thời hạn / ân hạn / giới hạn kích hoạt.	✅	URD-LADM-001 · URD-LADM-008
FR-002	Khai entitlement (quyền tính năng) cho gói. • Entitlement gồm mã, kiểu dữ liệu, giá trị. • Chỉ khai được trên gói đã lưu.	✅	URD-LADM-001 · URD-LADM-008
FR-003	Danh sách và chi tiết giấy phép toàn nền tảng. • Danh sách có 7 cột. • Lọc theo 6 tiêu chí.	✅	URD-LADM-002 · URD-LADM-007
FR-004	Cấp giấy phép cho merchant hoặc người dùng. • Đối tượng nhận giấy phép: merchant hoặc người dùng. • Khóa giấy phép sinh tự động.	✅	URD-LADM-004
FR-005	Sửa giấy phép: tên và các mốc ngày. • Sửa được tên và 3 mốc ngày. • Các mốc ngày phải theo đúng thứ tự chặt.	✅	URD-LADM-005
FR-006	Vòng đời giấy phép: tạm ngưng / khôi phục / gia hạn / thu hồi theo ma trận 4 trạng thái.	✅	URD-LADM-005
FR-007	Quản kích hoạt thiết bị: danh sách, chi tiết, thêm / sửa / xóa.	✅	URD-LADM-003
FR-008	Góc nhìn thương mại trên danh sách giấy phép. • Thêm cột gói và cột seat. • Lọc thêm theo merchant và theo gói.	🚧	URD-LADM-002 · URD-LADM-007
FR-009	Cấp giấy phép dùng thử tự cấp bằng một thao tác.	🚧	URD-LADM-004
FR-010	Hiện mức dùng seat và chặn vượt giới hạn kích hoạt. • Chi tiết giấy phép hiện mức dùng seat. • Chặn kích hoạt thêm khi vượt giới hạn kích hoạt.	🚧	URD-LADM-003 · URD-LADM-007
FR-011	Lịch sử thao tác append-only trên giấy phép.	🚧	URD-LADM-005
FR-012	Console chỉ dành cho Đội vận hành.	✅	URD-LADM-006

FR-001 - Soạn gói thuê bao ✅

• Danh sách gói - cột: Tên (song ngữ) · Sản phẩm · Loại (nhãn màu) · Trạng thái (nhãn màu) · Thứ tự. Lọc: Tên, Sản phẩm, Loại, Trạng thái (Thứ tự không lọc). Hành động từng dòng: Sửa · Xóa (hộp xác nhận nêu tên gói).
• Form gói:

Trường	Bắt buộc	Quy tắc
Tên	bắt buộc	song ngữ EN/VI, ≤ 200 ký tự
Mô tả	tùy chọn	văn bản một ngôn ngữ (không song ngữ), nhiều dòng
Sản phẩm	bắt buộc	sản phẩm thương mại mà gói thuộc về
Loại	bắt buộc	3 giá trị: Dùng thử · Thuê bao · Vĩnh viễn
Trạng thái	bắt buộc	Đang hoạt động (mặc định) · Ngừng hoạt động · Lưu trữ
Thứ tự	tùy chọn	số nguyên ≥ 0 (mặc định 0) - thứ tự hiển thị trong danh mục
Thời hạn	-	số ≥ 0 + đơn vị ngày / tuần / tháng / năm (mặc định 0 ngày)
Thời gian ân hạn	-	số ≥ 0 + đơn vị ngày / tuần / tháng / năm (mặc định 0 ngày)
Giới hạn kích hoạt	-	số nguyên ≥ 0 (mặc định 0) - chính là số seat của gói

• Cạnh form có thẻ xem trước cập nhật trực tiếp theo dữ liệu nhập: tên, loại, trạng thái, thời hạn, giới hạn kích hoạt, ân hạn.
• Gói không có giá tiền - "điều khoản" của gói chỉ gồm thời hạn, ân hạn, giới hạn kích hoạt.
• Rời form đang sửa dở → cảnh báo mất thay đổi.

FR-002 - Entitlement của gói ✅

Mỗi gói mang một danh sách quyền tính năng (entitlement / feature flag), quản lý trong màn sửa gói - gói phải lưu xong mới thêm được.

Trường	Bắt buộc	Quy tắc
Mã	bắt buộc	mã tính năng, vd max_users
Tên	bắt buộc	song ngữ EN/VI, ≤ 200 ký tự
Mô tả	tùy chọn	song ngữ EN/VI, ≤ 400 ký tự
Kiểu dữ liệu	bắt buộc	Bật-tắt · Số · Chữ · JSON
Giá trị	-	ô nhập đổi theo kiểu đã chọn; chưa chọn kiểu thì ô bị khóa; đổi kiểu thì giá trị về mặc định của kiểu
Trạng thái	bắt buộc	Đang hoạt động · Ngừng hoạt động
Thứ tự	tùy chọn	số nguyên

• Bảng entitlement: Mã · Tên · Kiểu dữ liệu · Trạng thái · Thứ tự; sửa qua hộp thoại, xóa có xác nhận nêu mã.

FR-003 - Danh sách + chi tiết giấy phép ✅

• Cột: Khóa giấy phép · Tên (song ngữ) · Trạng thái (nhãn màu) · Loại đối tượng (Merchant · Người dùng) · Mã đối tượng · Ngày bắt đầu · Ngày hết hạn.
• Lọc: khóa, tên, trạng thái, loại đối tượng, ngày bắt đầu, ngày hết hạn. (Lọc theo tên merchant và theo gói ở FR-008.)
• Chi tiết giấy phép: đầu trang hiện khóa (sao chép một chạm) + trạng thái; khối thông tin: Tên, Gói, Loại đối tượng, Mã đối tượng, Ngày phát hành, Ngày bắt đầu, Ngày hết hạn, Ngày hết ân hạn, Lần xác thực gần nhất; khối entitlement kế thừa từ gói (chỉ đọc); khối kích hoạt của giấy phép (xóa được từng kích hoạt, có xác nhận).

FR-004 - Cấp giấy phép ✅

Trường	Bắt buộc	Quy tắc
Gói	bắt buộc	chọn từ danh mục gói, hiển thị kèm sản phẩm
Loại đối tượng	bắt buộc	Merchant · Người dùng
Đối tượng	bắt buộc	chọn theo loại đã chọn; ô bị khóa cho tới khi chọn loại; đổi loại thì lựa chọn bị xóa để chọn lại
Tên	tùy chọn	song ngữ EN/VI
Tiền tố khóa	tùy chọn	≤ 32 ký tự; chỉ chữ, số, dấu gạch ngang

• Khóa giấy phép sinh tự động (mang tiền tố nếu có) - không nhập tay.

FR-005 - Sửa giấy phép ✅

• Sửa được: Tên + 3 mốc ngày Ngày bắt đầu / Ngày hết hạn / Ngày hết ân hạn.
• Ràng buộc chặt: bắt đầu < hết hạn < hết ân hạn - trùng ngày cũng không hợp lệ.
• Bất biến sau khi cấp: gói, đối tượng, khóa giấy phép.

FR-006 - Vòng đời giấy phép ✅

Giấy phép có 4 trạng thái: Đang hiệu lực · Hết hạn · Tạm ngưng · Đã thu hồi. Ma trận thao tác:

Thao tác	Cho phép từ trạng thái	Ghi chú
Tạm ngưng	Đang hiệu lực	ô lý do tùy chọn
Khôi phục	Tạm ngưng	-
Gia hạn	Đang hiệu lực · Hết hạn	gói Vĩnh viễn không gia hạn được
Thu hồi	Mọi trạng thái trừ Đã thu hồi	một chiều, không hoàn tác - hộp xác nhận cảnh báo rõ; ô lý do tùy chọn

• Mọi thao tác vòng đời đều qua hộp xác nhận; menu thao tác chỉ hiện những thao tác hợp lệ với trạng thái hiện tại.

FR-007 - Kích hoạt thiết bị ✅

• Danh sách - cột: Giấy phép · Mã thiết bị (fingerprint) · Nền tảng · Nhãn · Hostname · IP · Ngày tạo. Lọc: mã thiết bị, nền tảng, nhãn, hostname, IP, ngày tạo.
• Thêm: Giấy phép (bắt buộc, chọn theo khóa giấy phép) + Mã thiết bị (bắt buộc); Nền tảng / Nhãn / Hostname tùy chọn; IP do hệ thống ghi.
• Sửa: chỉ nền tảng / nhãn / hostname - giấy phép và mã thiết bị bất biến sau khi tạo.
• Xóa = xóa hẳn (kích hoạt không có trạng thái riêng; "hủy kích hoạt" chính là xóa), luôn qua hộp xác nhận nêu mã thiết bị - làm được từ danh sách kích hoạt, trang chi tiết kích hoạt, hoặc trang chi tiết giấy phép.
• Chi tiết kích hoạt: thông tin thiết bị (mã, nền tảng, nhãn, hostname, IP, ngày tạo/cập nhật) + khối giấy phép gắn kèm (khóa mở sang được trang giấy phép, tên, trạng thái, gói, hết hạn).

FR-008 - Góc nhìn thương mại trên danh sách giấy phép 🚧

Danh sách giấy phép có thêm cột Gói, cột Seat (số kích hoạt đã dùng / giới hạn), và lọc theo merchant (theo tên, không phải mã thô) cùng theo gói.

FR-009 - Giấy phép dùng thử tự cấp 🚧

Một thao tác cấp nhanh giấy phép dùng thử cho đối tượng, không phải chọn tay gói - hệ thống tự chọn gói loại Dùng thử và sinh giấy phép trong một chạm.

FR-010 - Mức dùng seat 🚧

Chi tiết giấy phép hiện số thiết bị đã kích hoạt trên giới hạn kích hoạt của gói (vd 3/5) và chặn thêm kích hoạt khi đã chạm giới hạn.

FR-011 - Lịch sử thao tác append-only 🚧

Mọi thao tác trên giấy phép (cấp, sửa, tạm ngưng, khôi phục, gia hạn, thu hồi) để lại lịch sử append-only - ai, lúc nào, lý do - xem được trên chi tiết giấy phép.

FR-012 - Chỉ dành cho Đội vận hành ✅

Console chỉ mở được bằng tài khoản Back Office của Đội vận hành; user của một merchant không truy cập được. Console nằm trong mục "Hỗ trợ" của Back Office.

5.1 Tiêu chí nghiệm thu

• Tạo gói thiếu tên, sản phẩm, loại hoặc trạng thái → lỗi, không lưu; tên > 200 ký tự → lỗi; gói mới mặc định Đang hoạt động, thứ tự 0, thời hạn / ân hạn 0 ngày, giới hạn kích hoạt 0.
• Entitlement chỉ thêm được trên gói đã lưu; đổi kiểu dữ liệu làm ô giá trị về mặc định của kiểu; chưa chọn kiểu thì ô giá trị bị khóa.
• Cấp giấy phép: chưa chọn loại đối tượng thì ô đối tượng bị khóa; đổi loại đối tượng thì lựa chọn đối tượng bị xóa; tiền tố khóa 33 ký tự hoặc chứa ký tự ngoài chữ/số/gạch ngang → lỗi; khóa sinh tự động.
• Sửa giấy phép: đặt ngày hết hạn ≤ ngày bắt đầu → lỗi; hết ân hạn ≤ hết hạn → lỗi; không sửa được gói / đối tượng / khóa.
• Giấy phép Đang hiệu lực: menu hiện Tạm ngưng, Gia hạn, Thu hồi (không có Khôi phục); Tạm ngưng: hiện Khôi phục, Thu hồi; Hết hạn: hiện Gia hạn, Thu hồi; Đã thu hồi: không còn thao tác vòng đời nào.
• Thu hồi luôn kèm cảnh báo không thể hoàn tác; Tạm ngưng và Thu hồi có ô lý do tùy chọn; giấy phép của gói Vĩnh viễn không gia hạn được.
• Kích hoạt: sửa không đổi được giấy phép / mã thiết bị; xóa luôn qua xác nhận nêu mã thiết bị; từ chi tiết kích hoạt bấm sang được trang giấy phép.
• User của một merchant không mở được console.

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

Khía cạnh	Yêu cầu
Phạm vi & phân quyền	Toàn nền tảng, chỉ tài khoản Back Office của Đội vận hành; không tới được bởi user của một merchant
Truy vết	Thao tác giấy phép để lại lịch sử append-only (ai, lúc nào, lý do), xem được trên chi tiết giấy phép
Toàn vẹn	Một giấy phép gắn đúng một đối tượng (merchant hoặc người dùng); thu hồi là trạng thái cuối
An toàn thao tác	Mọi thao tác đổi trạng thái hoặc xóa đều qua hộp xác nhận nêu rõ hệ quả
i18n	Tên gói / giấy phép nhập song ngữ EN/VI; nhãn loại và trạng thái hiển thị song ngữ

7. UX & Luồng

Đội vận hành chạy cấp phép như thế nào:

Console bao gồm những gì:

Console nằm trong mục "Hỗ trợ" của Back Office. Gói được soạn; giấy phép và kích hoạt được duyệt toàn nền tảng; mọi thao tác đổi trạng thái đều qua hộp xác nhận.

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

Khái niệm	Vai trò trong màn này
Gói thuê bao	Gói kinh doanh: loại (Dùng thử / Thuê bao / Vĩnh viễn) + thời hạn, ân hạn, giới hạn kích hoạt + entitlement; không mang giá tiền
Entitlement	Quyền tính năng của gói: mã + kiểu dữ liệu (Bật-tắt / Số / Chữ / JSON) + giá trị
Giấy phép	Một gói cấp cho đúng một đối tượng, có khóa sinh tự động và 4 trạng thái vòng đời
Đối tượng	Merchant hoặc người dùng - bên được cấp giấy phép
Kích hoạt thiết bị	Một thiết bị gắn với một giấy phép, chiếm một seat; không có trạng thái riêng - xóa là hủy kích hoạt
Seat	Giới hạn kích hoạt khai trên gói; mức dùng hiển thị ở chi tiết giấy phép (FR-010)

Chỉ ở mức khái niệm - engine cấp phép (gói, vòng đời, kích hoạt, validation) chạy hậu trường; mô hình dữ liệu ở tài liệu developer.

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

Phụ thuộc

#	Feature	Phụ thuộc điều gì
01	Engine cấp phép (Licensing)	gói, vòng đời giấy phép, và kích hoạt mà bề mặt này điều khiển.
02	Onboarding (Onboarding)	tự cấp một license lúc tạo client, dùng gói định nghĩa ở đây.
03	Merchant & Người dùng (Commerce)	các đối tượng một giấy phép gắn vào.

Giả định

#	Giả định	Sai thì sao
01	Đội vận hành đã đăng nhập với vai trò quản trị cấp phép.	Nếu một tài khoản không có vai trò này vẫn vào được console, dữ liệu giấy phép của mọi merchant bị lộ và có thể bị thao túng ngoài ý muốn (xem URD-LADM-006).
02	Gói phải tồn tại (và Đang hoạt động) trước khi cấp được giấy phép theo gói đó.	Nếu cấp giấy phép được phép trước khi gói tồn tại hoặc đang hoạt động, giấy phép đó tham chiếu tới một gói không có thật hoặc đã ngừng bán, và entitlement của nó không xác định được.

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

Khía cạnh	Kế hoạch
Phase	P1 - console cấp phép đã có trong Back Office
Rollout	User Đội vận hành; không feature flag
Migration	Không - nó điều khiển engine cấp phép hiện có
Tiêu chí phát hành	Soạn được gói đủ trường + entitlement; cấp được giấy phép cho merchant / người dùng với khóa tự sinh; 4 thao tác vòng đời chạy đúng ma trận trạng thái kèm xác nhận; kích hoạt thêm / sửa / xóa được; mọi màn chỉ Đội vận hành tới được
Theo dõi	Lượng soạn gói và thao tác giấy phép; tỷ lệ thu hồi

Tham chiếu

• URD: Licensing - LADM · PLN · LIC · ACT
• Liên quan: Onboarding (tự cấp phép)
• Module: Licensing - URD · Lộ trình: Phase 2 - Theo tháng
• Developer: @nx/licensing

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

#	Rủi ro / câu hỏi	Giảm thiểu / trạng thái
01	Soạn gói chỉ ops, hay có vai trò commercial-admin riêng?	Mở - bắt đầu gác Đội vận hành; tách vai trò sau nếu cần
02	Thu hồi có cần cửa sổ ân hạn vs giải phóng seat ngay?	Mở - hiện thu hồi là một chiều tức thời; seat chưa được đếm hay giải phóng khi thu hồi (FR-010)
03	Danh sách giấy phép toàn nền tảng có thể lớn	Lọc theo 6 tiêu chí + đếm được; lọc theo merchant / gói bổ sung ở FR-008
04	Vận hành giấy phép nhạy cảm	Mọi thao tác qua hộp xác nhận + lý do; lịch sử append-only truy vết thao tác nhạy cảm (FR-011)

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

#	Câu hỏi	Trả lời
01	Đây có phải engine cấp phép không?	Không - engine dựng hậu trường; cái này là console Đội vận hành điều khiển nó.
02	Giấy phép được tạo lần đầu ở đâu?	Thường onboarding tự cấp một cái khi tạo client; console này soạn gói và quản lý giấy phép về sau.
03	Giấy phép có cấp cho người dùng lẻ không?	Có - khi cấp, chọn loại đối tượng là Merchant hoặc Người dùng.
04	Cấp giấy phép dùng thử thế nào?	Có thể cấp bằng một gói loại Dùng thử qua form cấp, hoặc dùng thao tác cấp dùng thử một-chạm (FR-009) tự chọn gói dùng thử và sinh giấy phép.
05	Kích hoạt là gì?	Một thiết bị gắn với một giấy phép, chiếm một seat của nó; muốn hủy kích hoạt thì xóa bản ghi kích hoạt (có xác nhận).
06	User của một merchant có mở được màn này không?	Không - nó toàn nền tảng và dành cho Đội vận hành.