PRD: Gói dịch vụ & cờ tính năng

Module	Gói & giấy phép	PRD ID	PRD-PLN-001
Trạng thái	Sẵn sàng dev	FEAT	PLN
Epic	—	Plane	BANA-1508
Ngày	2026-06-05	Phiên bản	v1.0
Gói	@nx/licensing	URD	PLN
Surface	Backend
Phụ trách	Phát Nguyễn

Gói dịch vụ & cờ tính năng là gì

BANA được bán dưới dạng các gói dịch vụ (Plan) đóng gói những bộ tính năng và hạn mức thiết bị khác nhau. Sản phẩm cần một nơi duy nhất định nghĩa mỗi gói có gì, trước khi bất kỳ giấy phép nào được phát hành từ nó. Không có nơi đó, mỗi module lại tự định nghĩa gói và tính năng theo cách riêng, khiến danh mục gói không nhất quán và không tái sử dụng được giữa các bề mặt đăng ký, nâng cấp.

PRD này thiết lập khuôn mẫu gói: các gói tái sử dụng - dùng thử, thuê bao, vĩnh viễn - mang một thời hạn, một thời gian ân hạn, một hạn mức thiết bị, và một túi cờ tính năng (Feature Flag) có kiểu, với mã duy nhất trong mỗi gói.

Việc phát hành giấy phép nằm ở PRD khác

PRD này chỉ định nghĩa khuôn mẫu gói - không phát hành giấy phép, không chạy vòng đời, không kích hoạt thiết bị. Việc phát hành giấy phép, gia hạn, tạm ngưng, khôi phục, thu hồi, kích hoạt thiết bị và kiểm tra hiệu lực lúc chạy dựa trên các gói này được đặc tả ở PRD-ACT-001.

Một gói, từ lúc tạo tới lúc lưu trữ

Việc xảy ra	Trạng thái gói
Người vận hành tạo gói, đặt thời hạn 365 ngày, ân hạn 15 ngày, hạn mức thiết bị	Đang soạn
Gắn các cờ tính năng có kiểu, mỗi mã duy nhất trong gói	Đang soạn
Đặt tên, mô tả song ngữ và thứ tự hiển thị	Đang soạn
Kích hoạt gói	Đang hoạt động - xuất hiện trong danh mục công khai đúng thứ tự
Gói không còn bán	Đã lưu trữ - biến mất khỏi danh mục, dữ liệu vẫn còn nguyên

Một danh mục gói công khai liệt kê các gói đang hoạt động theo đúng thứ tự hiển thị, cho các bề mặt đăng ký và nâng cấp đọc.

Chỗ dễ sai nhất

Lưu trữ không phải xóa

Một gói không còn dùng được xóa mềm (lưu trữ) - không bao giờ bị xóa cứng khỏi ứng dụng. Gói biến mất khỏi danh mục công khai, nhưng dữ liệu của nó và mọi giấy phép đã phát hành từ nó vẫn còn nguyên. Mã của một cờ tính năng phải duy nhất trong mỗi gói, và ràng buộc này được ép ở tầng lưu trữ, không chỉ ở tầng ứng dụng.

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

Mục tiêu

• Người vận hành định nghĩa các gói tái sử dụng (dùng thử / thuê bao / vĩnh viễn) với thời hạn, thời gian ân hạn, và hạn mức thiết bị.
• Gắn các cờ tính năng có kiểu (boolean / number / text / json) vào một gói, với mã cờ duy nhất trong mỗi gói.
• Gói mang tên hiển thị và mô tả song ngữ cùng một thứ tự hiển thị.
• Cung cấp một danh mục gói công khai liệt kê các gói đang hoạt động kèm tính năng đang bật, theo thứ tự hiển thị.
• Xóa mềm (lưu trữ) một gói không còn dùng, không bao giờ xóa cứng.

Loại trừ

• Phát hành giấy phép và vòng đời của nó (gia hạn / tạm ngưng / khôi phục / thu hồi) - đặc tả ở PRD-ACT-001.
• Kích hoạt thiết bị và thực thi hạn mức thiết bị - đặc tả ở PRD-ACT-001.
• Kiểm tra hiệu lực lúc chạy và chứng chỉ đã ký - đặc tả ở PRD-ACT-001.
• Tính tiền, xuất hóa đơn, đòi nợ, hay tích hợp tính phí thanh toán.
• Một giao diện quản lý gói (thuộc về frontend).

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

Thước đo	Mục tiêu / tín hiệu
Đúng đắn danh mục	Danh mục công khai chỉ hiển thị gói đang hoạt động, đúng theo thứ tự hiển thị đã đặt
Duy nhất cờ tính năng	Không có hai cờ tính năng cùng mã trong cùng một gói
Không xóa cứng	100% gói bị vô hiệu hóa đi qua xóa mềm (lưu trữ); không gói nào bị xóa cứng khỏi ứng dụng

3. Persona & Tình huống

Persona	Mục tiêu trong tính năng này
Người vận hành nền tảng	Định nghĩa gói & cờ tính năng; đặt tên/mô tả song ngữ và thứ tự hiển thị; lưu trữ gói không còn dùng
Chủ merchant / bề mặt đăng ký	Duyệt danh mục gói công khai để chọn hoặc nâng cấp

Tình huống cốt lõi: người vận hành tạo một gói kèm thời hạn, ân hạn, hạn mức thiết bị → gắn các cờ tính năng có kiểu với mã duy nhất → đặt tên, mô tả song ngữ và thứ tự hiển thị → kích hoạt gói, gói xuất hiện trong danh mục công khai đúng theo thứ tự → khi gói không còn dùng, người vận hành lưu trữ nó; gói biến mất khỏi danh mục nhưng dữ liệu vẫn còn.

4. User Stories

#	Là một	Tôi muốn	Để
01	người vận hành nền tảng	định nghĩa các gói tái sử dụng với thời hạn, ân hạn, và hạn mức thiết bị	tôi đóng gói những gì mỗi tầng merchant được phép chạy
02	người vận hành nền tảng	gắn các cờ tính năng có kiểu vào một gói với mã duy nhất	mỗi tính năng được bật/tắt hoặc giới hạn rõ ràng, không trùng lặp
03	người vận hành nền tảng	đặt tên, mô tả song ngữ và thứ tự hiển thị cho một gói	danh mục công khai hiển thị đúng và dễ đọc ở cả hai ngôn ngữ
04	chủ merchant	xem một danh mục công khai các gói đang hoạt động	tôi chọn hoặc nâng cấp gói của mình
05	người vận hành nền tảng	lưu trữ một gói không còn bán	nó biến mất khỏi danh mục mà không mất dữ liệu hay ảnh hưởng tới các giấy phép đã phát hành từ nó

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

#	Yêu cầu	Trạng thái	URD ref
FR-001	Tạo một gói với loại, thời hạn và thời gian ân hạn. • Loại gói: dùng thử / thuê bao / vĩnh viễn. • Thời hạn: một giá trị cụ thể, hoặc null nếu là gói vĩnh viễn. • Thời gian ân hạn: tùy chọn.	✅	URD-PLN-001..002
FR-002	Gói có thể giới hạn số thiết bị bằng một hạn mức thiết bị. • Đặt hạn mức thiết bị (tùy chọn): giới hạn số thiết bị được phép trên gói. • Hạn mức bằng null: không giới hạn số thiết bị.	✅	URD-PLN-003
FR-003	Gắn cờ tính năng có kiểu vào gói, với hành vi rõ ràng khi vô hiệu hóa. • Kiểu cờ tính năng: boolean / number / text / json. • Cờ đã vô hiệu hóa: phân giải về giá trị rỗng/tắt mặc định theo kiểu của nó.	✅	URD-PLN-004..005
FR-004	Cung cấp một danh mục gói công khai. • Chỉ liệt kê các gói đang hoạt động, theo đúng thứ tự hiển thị đã đặt. • Mỗi gói kèm theo các tính năng đang bật của gói đó.	✅	URD-PLN-008
FR-005	Mã của một cờ tính năng là duy nhất trong mỗi gói.	✅	URD-PLN-006
FR-006	Gói mang các thông tin hiển thị cho danh mục công khai. • Tên hiển thị và mô tả: song ngữ (Tiếng Anh / Tiếng Việt). • Thứ tự hiển thị: một giá trị dùng để sắp xếp gói trong danh mục.	✅	URD-PLN-007
FR-007	Gói không còn dùng được xóa mềm, không xóa cứng. • Gói được xóa mềm (lưu trữ) khi không còn dùng. • Gói không bao giờ bị xóa cứng khỏi ứng dụng.	✅	URD-PLN-009

5.1 Tiêu chí nghiệm thu

• Người vận hành tạo một gói thuê bao với thời hạn 365 ngày và ân hạn 15 ngày → gói được lưu, sẵn sàng để chọn khi phát hành giấy phép từ đó.
• Người vận hành tạo một gói vĩnh viễn, không đặt thời hạn → gói được lưu với thời hạn null.
• Người vận hành đặt hạn mức thiết bị của một gói là null → gói cho phép số thiết bị không giới hạn khi giấy phép được phát hành từ nó.
• Người vận hành gắn một cờ tính năng kiểu boolean vào một gói rồi vô hiệu hóa nó → khi phân giải, tính năng trả về giá trị tắt mặc định thay vì giá trị đã cấu hình trước đó.
• Người vận hành thử gắn hai cờ tính năng cùng mã vào một gói → thao tác thứ hai bị từ chối vì mã đã tồn tại trong gói đó.
• Người vận hành đặt tên và mô tả song ngữ (Tiếng Anh / Tiếng Việt) cùng thứ tự hiển thị cho một gói → cả hai ngôn ngữ hiển thị đúng trên danh mục, theo đúng thứ tự đã đặt.
• Mở danh mục gói công khai → chỉ các gói đang hoạt động hiển thị, theo đúng thứ tự hiển thị đã đặt, mỗi gói kèm các tính năng đang bật của nó.
• Người vận hành lưu trữ một gói → gói biến mất khỏi danh mục công khai nhưng dữ liệu của gói vẫn còn nguyên trong hệ thống, không bị xóa cứng.

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

Lĩnh vực	Yêu cầu
Toàn vẹn dữ liệu	Mã cờ tính năng là duy nhất trong mỗi gói; ràng buộc được thực thi ở tầng lưu trữ, không chỉ ở tầng ứng dụng
Tính bất biến	Một gói bị lưu trữ (xóa mềm) không bao giờ bị xóa cứng; các tham chiếu tới gói, như giấy phép đã phát hành từ nó, vẫn còn nguyên
Tenancy & authz	Quản lý gói và cờ tính năng được giới hạn bởi các permission scope licensing
i18n	Tên hiển thị và mô tả của gói là song ngữ (Tiếng Anh / Tiếng Việt)

7. UX & Luồng

Bề mặt thuần backend trên gói và cờ tính năng. Không có giao diện quản lý gói trong increment này; các bề mặt đăng ký và nâng cấp đọc danh mục gói công khai. Việc phát hành giấy phép từ các gói này, kích hoạt thiết bị, và kiểm tra hiệu lực lúc chạy được đặc tả ở PRD-ACT-001.

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

Khái niệm	Vai trò
Gói	Template tái sử dụng - loại, thời hạn, thời gian ân hạn, hạn mức thiết bị, tên/mô tả song ngữ, thứ tự hiển thị
Cờ tính năng của gói	Một cờ tính năng có kiểu trên một gói (boolean / number / text / json), mã duy nhất trong mỗi gói

Chỉ ở mức khái niệm - schema và bất biến đầy đủ nằm trong domain model của licensing.

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

Phụ thuộc vào

#	Feature	Phụ thuộc điều gì
01	Permissions (Permissions)	quản lý gói và cờ tính năng được giới hạn bởi các permission scope licensing.

Giả định

#	Giả định	Sai thì sao
01	Giấy phép được phát hành từ các gói này theo quy trình đặc tả ở PRD-ACT-001; PRD này chỉ định nghĩa khuôn mẫu gói.	Nếu việc phát hành giấy phép không dựa đúng khuôn mẫu gói định nghĩa ở đây, gói và giấy phép trôi dạt không khớp nhau, và danh mục gói công khai không còn phản ánh đúng cái merchant thực nhận được.
02	Lưu trữ một gói không ảnh hưởng tới các giấy phép đã phát hành từ nó trước đó.	Nếu lưu trữ làm mất hoặc làm sai lệch giấy phép đã phát hành, merchant đang dùng gói đó bị cắt tính năng đột ngột dù họ không đổi gì.

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

Khía cạnh	Kế hoạch
Phase	P1 - nền tảng của module licensing, xem danh mục feature URD
Rollout	Nền tảng của module licensing; không cờ tính năng
Migration	Không (khái niệm nền tảng)
Tiêu chí phát hành	Tạo gói → gắn cờ tính năng → kích hoạt → xuất hiện đúng trong danh mục công khai; mã cờ trùng bị từ chối; lưu trữ gói không xóa cứng dữ liệu
Theo dõi	Số gói đang hoạt động, tỷ lệ từ chối do trùng mã cờ tính năng, số lượt xem danh mục công khai

Tham chiếu

• URD: Gói & giấy phép - Gói & cờ tính năng
• Vòng đời giấy phép, kích hoạt thiết bị và kiểm tra hiệu lực lúc chạy được đặc tả ở PRD-ACT-001.
• Module: Gói & giấy phép - URD
• Developer: @nx/licensing · domain model

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

#	Rủi ro / câu hỏi	Giảm thiểu / trạng thái
01	Lưu trữ một gói đang có giấy phép hoạt động tham chiếu tới nó	Lưu trữ chỉ ẩn gói khỏi danh mục công khai, không ảnh hưởng tới các giấy phép đã phát hành trước đó
02	Chưa có giao diện quản lý gói riêng	Việc tạo/sửa gói hiện qua API; câu hỏi mở là có cần một màn hình quản trị riêng hay không

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

#	Câu hỏi	Trả lời
01	Cái này có xử lý phát hành hay vòng đời giấy phép không?	Không - PRD này chỉ định nghĩa gói và cờ tính năng. Phát hành giấy phép, gia hạn, tạm ngưng, khôi phục, thu hồi được đặc tả ở PRD-ACT-001.
02	Cái này có xử lý kích hoạt thiết bị hay kiểm tra hiệu lực lúc chạy không?	Không - hai chức năng đó cũng thuộc PRD-ACT-001, dựa trên các gói được định nghĩa ở đây.
03	Hai cờ tính năng có thể trùng mã trong cùng một gói không?	Không - mã cờ tính năng là duy nhất trong mỗi gói; thao tác tạo cờ trùng mã bị từ chối.
04	Điều gì xảy ra khi một cờ tính năng bị vô hiệu hóa?	Nó phân giải về giá trị rỗng/tắt mặc định theo kiểu của nó thay vì giá trị đã cấu hình, mà không cần xóa cờ đó.
05	Lưu trữ một gói có xóa nó khỏi hệ thống không?	Không - lưu trữ là xóa mềm. Gói biến mất khỏi danh mục công khai nhưng dữ liệu vẫn còn nguyên, không bao giờ bị xóa cứng.