URD: Gói & giấy phép

Module	CORE-15	Phiên bản	v0.1
Trạng thái	Built	Ngày	2026-06-05

Tài liệu nghiệp vụ. URD này là danh sách tính năng của Gói & giấy phép - mỗi tính năng bên dưới là một Khu vực chức năng (<AREA>). Cùng <AREA> đó định khóa cho PRD của tính năng (PRD-<AREA>-NNN) và test case (TC-<AREA>-NNN), và mỗi tính năng được liệt kê trong danh mục tính năng Delivery. Xem quy ước Feature Spine.

1. Mục đích

Định nghĩa các yêu cầu hướng người dùng cho module Gói & giấy phép - gói tái sử dụng, phát hành và 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 - để người vận hành nền tảng kiểm soát chính xác mỗi merchant được phép chạy gì, merchant có thể tự cấp một gói dùng thử miễn phí, và mọi service khác có thể thực thi tính năng cùng hạn mức thiết bị ngoại tuyến dựa trên một chứng chỉ đã ký đáng tin cậy.

2. Phạm vi

Bao gồm	Loại trừ
Gói tái sử dụng: dùng thử / thuê bao / vĩnh viễn	Hóa đơn, lập hóa đơn, nhắc nợ
Cờ tính năng có kiểu và hạn mức thiết bị theo gói	Tích hợp thanh toán / tính phí thuê bao
Danh mục gói công khai	Đo lường mức sử dụng / theo dõi nhịp tim
Phát hành giấy phép + vòng đời (gia hạn / tạm ngưng / khôi phục / thu hồi)	Thực thi tính năng lúc chạy (việc của từng bên tiêu thụ)
Tự cấp gói dùng thử miễn phí	Giao diện quản lý giấy phép (việc của frontend)
Kích hoạt thiết bị (ràng buộc fingerprint, hạn mức thiết bị)	Xác minh chứng chỉ (mọi service khác, ngoại tuyến)
Kiểm tra hiệu lực lúc chạy trả về chứng chỉ đã ký	Quét hết hạn chủ động (hết hạn được phát hiện lười)
Ghi đè mặc định của gói theo từng giấy phép
Nhật ký kiểm toán sự kiện chỉ-thêm

3. Định nghĩa

Thuật ngữ	Định nghĩa
Gói	Một khuôn mẫu tái sử dụng mà giấy phép được phát hành từ đó; mang kiểu, thời hạn, thời gian ân hạn, hạn mức thiết bị, và các cờ tính năng
Cờ tính năng	Một cặp khóa/giá trị có kiểu trên một gói (boolean / number / text / json) bật/tắt một tính năng hoặc đặt một hạn mức
Giấy phép	Một quyền sử dụng đã phát hành ràng buộc vào một merchant hoặc người dùng, với một khóa duy nhất và một trạng thái vòng đời
Kích hoạt	Việc ràng buộc một giấy phép vào một thiết bị, định danh bằng fingerprint, được đếm vào hạn mức thiết bị
Hạn mức thiết bị	Số thiết bị duy nhất tối đa có thể kích hoạt trên một giấy phép
Thời gian ân hạn	Khoảng sau khi hết hạn mà trong đó giấy phép vẫn được công nhận, được đánh dấu là trong-ân-hạn
Chứng chỉ	Một ảnh chụp đã ký về trạng thái và tập tính năng đã phân giải của một giấy phép, được các service khác tin cậy ngoại tuyến
Ghi đè	Các điều chỉnh theo từng giấy phép lên hạn mức thiết bị hoặc giá trị tính năng của một gói

4. Mô hình khái niệm

Chỉ ở mức khái niệm - schema đầy đủ nằm trong domain model của developer.

5. Danh mục tính năng

Danh sách tính năng của module này. Mỗi dòng là một tính năng (một Khu vực chức năng). Chi tiết ở §6. Được phản chiếu trong danh mục tính năng Delivery.

Feature ID	Tính năng	Phase	Trạng thái	Ưu tiên
PLN	Gói & Cờ tính năng	P1	Built	High
LIC	Vòng đời giấy phép	P1	Built	High
ACT	Kích hoạt thiết bị	P2	Built	High
VAL	Kiểm tra hiệu lực & Quyền sử dụng lúc chạy	P1	Built	High

Trạng thái: live từ Plane nếu có map, còn lại do registry khai báo. Vocabulary đồng nhất với Plane (state-group / phase).

6. Tính năng

Mỗi tính năng một tiểu mục, theo thứ tự Danh mục tính năng. Mỗi tính năng giữ chung phần mô tả, yêu cầu, và tiêu chí chấp nhận. Độ ưu tiên = MoSCoW (Must / Should / Could / Won't).

PLN - Gói & Cờ tính năng Built

Feature ID: licensing/PLN · Phase: P1 · PRD: PRD-PLN-001 · Dev: @nx/licensing

Tính năng làm gì cho người dùng: người vận hành nền tảng định nghĩa các gói tái sử dụng - dùng thử, thuê bao, hoặc vĩnh viễn - mỗi gói mang một thời hạn, một thời gian ân hạn tùy chọn, một hạn mức thiết bị, và một túi các cờ tính năng có kiểu mà giấy phép phát hành từ gói sẽ cấp.

Yêu cầu

ID	P	Yêu cầu
URD-PLN-001	M	Tạo một gói kiểu dùng thử, thuê bao, hoặc vĩnh viễn
URD-PLN-002	M	Một gói định nghĩa một thời hạn (hoặc null cho vĩnh viễn) và một thời gian ân hạn tùy chọn
URD-PLN-003	M	Một gói tùy chọn giới hạn số thiết bị (hạn mức thiết bị); null = không giới hạn
URD-PLN-004	M	Gắn cờ tính năng có kiểu vào một gói: boolean, number, text, hoặc json
URD-PLN-005	M	Một cờ tính năng có thể bị vô hiệu hóa, phân giải về mặc định rỗng/tắt của kiểu mà không cần xóa
URD-PLN-006	M	Mã của cờ tính năng là duy nhất trong một gói
URD-PLN-007	S	Gói mang tên hiển thị và mô tả đa ngôn ngữ và một thứ tự hiển thị
URD-PLN-008	M	Một danh mục công khai liệt kê các gói đang hoạt động kèm tính năng đang hoạt động, theo thứ tự hiển thị
URD-PLN-009	S	Gói được xóa mềm (vô hiệu hóa/lưu trữ), không bao giờ bị xóa cứng từ ứng dụng

Chấp nhận

AC-PLN-01: Gói kèm tính năng

Cho trước	Khi	Thì
Người vận hành tạo một gói thuê bao	Họ đặt thời hạn, thời gian ân hạn, hạn mức thiết bị, và vài cờ tính năng	Gói được lưu; các mã cờ tính năng là duy nhất trong gói
Một cờ tính năng đặt là vô hiệu hóa	Tính năng của gói được phân giải	Cờ đó trả về mặc định rỗng/tắt của kiểu thay vì giá trị đã cấu hình

AC-PLN-02: Danh mục công khai

Cho trước	Khi	Thì
Vài gói đang hoạt động và một gói đã lưu trữ	Danh mục được yêu cầu	Chỉ các gói đang hoạt động xuất hiện, theo thứ tự hiển thị, mỗi gói kèm tính năng đang hoạt động được lồng vào

LIC - Vòng đời giấy phép Built

Feature ID: licensing/LIC · Phase: P1 · PRD: PRD-PLN-001 · Dev: @nx/licensing

Tính năng làm gì cho người dùng: một giấy phép được phát hành từ một gói và ràng buộc vào một merchant hoặc người dùng với một khóa duy nhất, rồi đi qua một vòng đời được theo dõi - gia hạn, tạm ngưng, khôi phục, thu hồi - với mọi thay đổi được kiểm toán và chứng chỉ được ký lại.

Yêu cầu

ID	P	Yêu cầu
URD-LIC-001	M	Phát hành một giấy phép từ một gói, ràng buộc vào một merchant hoặc người dùng, với một khóa sinh ra duy nhất
URD-LIC-002	M	Một giấy phép đã phát hành tính thời điểm hết hạn từ thời hạn và thời gian ân hạn của gói (vĩnh viễn = không hết hạn)
URD-LIC-003	M	Một giấy phép có trạng thái: hoạt động, tạm ngưng, hết hạn, hoặc thu hồi
URD-LIC-004	M	Tạm ngưng một giấy phép đang hoạt động, rồi khôi phục nó về hoạt động
URD-LIC-005	M	Gia hạn một giấy phép để kéo dài hiệu lực; gia hạn một giấy phép đã hết hạn sẽ khôi phục nó về hoạt động
URD-LIC-006	M	Gia hạn bị từ chối với giấy phép vĩnh viễn (không có thời hạn để kéo dài)
URD-LIC-007	M	Thu hồi một giấy phép vĩnh viễn; trạng thái thu hồi là cuối cùng và không thể gia hạn hay khôi phục
URD-LIC-008	M	Một merchant tự cấp một giấy phép dùng thử miễn phí duy nhất; một gói dùng thử đã có sẽ được trả về thay vì nhân đôi
URD-LIC-009	M	Mọi hành động vòng đời được ghi lại trong một nhật ký sự kiện chỉ-thêm
URD-LIC-010	M	Mỗi thay đổi vòng đời ký lại và phát hành lại chứng chỉ của giấy phép
URD-LIC-011	S	Một giấy phép có thể ghi đè hạn mức thiết bị và giá trị tính năng của gói

Chấp nhận

AC-LIC-01: Phát hành & vòng đời

Cho trước	Khi	Thì
Một gói thuê bao	Một giấy phép được phát hành cho một merchant	Một khóa duy nhất được sinh ra; hết hạn = bắt đầu + thời hạn; trạng thái hoạt động; một sự kiện đã tạo được ghi lại
Một giấy phép đang hoạt động	Nó bị tạm ngưng rồi khôi phục	Trạng thái đi hoạt động → tạm ngưng → hoạt động; cả hai hành động được kiểm toán
Một giấy phép vĩnh viễn	Thử gia hạn	Bị từ chối - giấy phép vĩnh viễn không có thời hạn để kéo dài
Một giấy phép đã hết hạn	Nó được gia hạn	Trạng thái về hoạt động với một kỳ hiệu lực mới bắt đầu từ bây giờ
Bất kỳ giấy phép nào	Nó bị thu hồi	Trạng thái → thu hồi (cuối cùng); gia hạn/khôi phục về sau bị từ chối

AC-LIC-02: Gói dùng thử miễn phí

Cho trước	Khi	Thì
Một merchant chưa có gói dùng thử	Họ yêu cầu một gói dùng thử miễn phí	Một giấy phép dùng thử được phát hành cho họ
Một merchant đã có gói dùng thử	Họ lại yêu cầu một gói dùng thử miễn phí	Gói dùng thử đang có được trả về; không tạo bản sao

ACT - Kích hoạt thiết bị Built

Feature ID: licensing/ACT · Phase: P2 · PRD: PRD-ACT-001 · Dev: @nx/licensing

Tính năng làm gì cho người dùng: một giấy phép được ràng buộc vào các thiết bị cụ thể bằng fingerprint; mỗi thiết bị duy nhất tiêu thụ một chỗ, hạn mức thiết bị của gói được thực thi, và một thiết bị có thể bị hủy kích hoạt để giải phóng chỗ của nó.

Yêu cầu

ID	P	Yêu cầu
URD-ACT-001	M	Kích hoạt một giấy phép trên một thiết bị, định danh bằng fingerprint, kèm nhãn, nền tảng, hostname tùy chọn
URD-ACT-002	M	Kích hoạt lại cùng thiết bị trên cùng giấy phép sẽ tái dùng chỗ hiện có (bất biến lặp)
URD-ACT-003	M	Số chỗ thiết bị duy nhất không thể vượt quá hạn mức thiết bị của gói (hoặc của ghi đè)
URD-ACT-004	M	Hạn mức thiết bị null nghĩa là kích hoạt thiết bị không giới hạn
URD-ACT-005	M	Hủy kích hoạt một thiết bị để giải phóng chỗ của nó
URD-ACT-006	S	Kích hoạt và hủy kích hoạt được ghi lại trong nhật ký sự kiện
URD-ACT-007	M	Kích hoạt bị từ chối khi giấy phép không ở trạng thái hoạt động (tạm ngưng / hết hạn / thu hồi / chưa bắt đầu)

Chấp nhận

AC-ACT-01: Thực thi hạn mức thiết bị

Cho trước	Khi	Thì
Một giấy phép hạn mức 2 chỗ và 2 thiết bị đang hoạt động	Một thiết bị duy nhất thứ ba kích hoạt	Bị từ chối - đã đạt hạn mức thiết bị
Cùng thiết bị đã đang hoạt động	Nó kích hoạt lại	Chỗ hiện có được tái dùng; không tiêu thụ chỗ mới
Một thiết bị đã được cấp phép	Nó bị hủy kích hoạt	Chỗ được giải phóng và có thể được thiết bị khác nhận

AC-ACT-02: Kích hoạt được canh theo trạng thái giấy phép

Cho trước	Khi	Thì
Một giấy phép tạm ngưng, hết hạn, hoặc đã thu hồi	Một thiết bị thử kích hoạt trên nó	Bị từ chối - giấy phép không ở trạng thái hoạt động
Một giấy phép hoạt động còn chỗ trống	Một thiết bị kích hoạt trên nó	Một chỗ được tiêu thụ và việc kích hoạt thành công

Đã xây theo PRD-ACT-001.

VAL - Kiểm tra hiệu lực & Quyền sử dụng lúc chạy Built

Feature ID: licensing/VAL · Phase: P1 · PRD: PRD-PLN-001 · Dev: @nx/licensing

Tính năng làm gì cho người dùng: một service kiểm tra một khóa giấy phép và nhận về trạng thái giấy phép, tập tính năng đã phân giải, mức dùng chỗ thiết bị, và một chứng chỉ đã ký mà các service khác tin cậy ngoại tuyến để giới hạn tính năng và chỗ thiết bị.

Yêu cầu

ID	P	Yêu cầu
URD-VAL-001	M	Kiểm tra một khóa giấy phép và trả về liệu nó có hiệu lực cùng một mã kết quả
URD-VAL-002	M	Một giấy phép không hoạt động (tạm ngưng / thu hồi / hết hạn) kiểm tra ra không hợp lệ với mã theo trạng thái
URD-VAL-003	M	Một giấy phép chưa đến hạn bắt đầu kiểm tra ra không hợp lệ (chưa bắt đầu)
URD-VAL-004	M	Một giấy phép quá hạn nhưng còn trong ân hạn kiểm tra ra hợp lệ với mã thời gian ân hạn
URD-VAL-005	M	Một giấy phép quá ân hạn được chuyển lười sang hết hạn lúc kiểm tra và trả về không hợp lệ
URD-VAL-006	M	Kiểm tra trả về tập tính năng đã phân giải, có áp dụng các ghi đè theo giấy phép
URD-VAL-007	M	Khi cung cấp một fingerprint thiết bị, kiểm tra xử lý chỗ (tái dùng hoặc tạo mới trong hạn mức)
URD-VAL-008	M	Một lần kiểm tra thành công trả về một chứng chỉ đã ký mà các service khác có thể xác minh ngoại tuyến
URD-VAL-009	S	Kiểm tra ghi lại thời điểm kiểm tra cuối lên giấy phép (cố gắng tốt nhất)

Chấp nhận

AC-VAL-01: Kết quả kiểm tra

Cho trước	Khi	Thì
Một giấy phép hoạt động, còn hạn	Nó được kiểm tra	Hợp lệ; tính năng đã phân giải và một chứng chỉ đã ký được trả về
Một giấy phép trong thời gian ân hạn	Nó được kiểm tra	Hợp lệ với một mã thời gian ân hạn
Một giấy phép quá ân hạn	Nó được kiểm tra	Nó bị chuyển sang hết hạn và trả về không hợp lệ (hết hạn)
Một giấy phép tạm ngưng hoặc thu hồi	Nó được kiểm tra	Không hợp lệ với mã trạng thái tương ứng

AC-VAL-02: Kiểm tra kèm một thiết bị

Cho trước	Khi	Thì
Một giấy phép hợp lệ còn chỗ trống và một fingerprint mới	Nó được kiểm tra với fingerprint đó	Một chỗ được tiêu thụ và việc kiểm tra thành công
Một giấy phép hợp lệ đã đạt hạn mức và một fingerprint mới	Nó được kiểm tra với fingerprint đó	Kiểm tra thất bại - đã đạt hạn mức thiết bị

7. Ràng buộc & Phi mục tiêu

Ràng buộc

ID	Ràng buộc
C-01	Một giấy phép luôn ràng buộc vào đúng một chủ thể (merchant hoặc người dùng)
C-02	Một khóa giấy phép là duy nhất trong số các giấy phép còn sống
C-03	Một mã cờ tính năng là duy nhất trong một gói
C-04	Một chỗ cho mỗi cặp (giấy phép, fingerprint thiết bị) duy nhất
C-05	Số chỗ thiết bị đang hoạt động không bao giờ vượt quá hạn mức thiết bị hiệu lực
C-06	Thu hồi là cuối cùng - không gia hạn hay khôi phục
C-07	Nhật ký sự kiện là chỉ-thêm và sống sót sau khi giấy phép bị xóa
C-08	Hết hạn được phát hiện lười lúc kiểm tra; không có bộ quét nền
C-09	Các service khác chỉ xác minh chứng chỉ ngoại tuyến; chúng không bao giờ gọi cấp phép lúc chạy để cấp quyền

Phi mục tiêu

• Hóa đơn, lập hóa đơn, và nhắc nợ
• Tích hợp thanh toán / tính phí thuê bao
• Đo lường mức sử dụng và theo dõi nhịp tim
• Quét hết hạn chủ động / theo lịch
• Thực thi tính năng lúc chạy (mỗi module tiêu thụ tự giới hạn)
• Giao diện quản lý giấy phép (việc của frontend)

8. Lịch sử phiên bản

Ngày	Tác giả	Mô tả	Phiên bản
2026-06-05	Claude (AI pair)	URD ban đầu soạn từ package @nx/licensing và tài liệu developer (Feature Spine)	v0.1