URD: Commerce

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

Tài liệu nghiệp vụ. URD này chính là danh sách tính năng của Commerce - mỗi tính năng bên dưới là một Vùng chức năng (<AREA>). Cùng mã <AREA> đó key cho PRD (PRD-<AREA>-NNN) và test (TC-<AREA>-NNN) của tính năng, 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

Commerce cho phép chủ doanh nghiệp dựng lên và vận hành cấu trúc doanh nghiệp: một Tổ chức duy nhất (thương hiệu) và một hoặc nhiều Merchant (các đơn vị điểm bán hợp pháp), mỗi đơn vị có kênh bán và danh mục sản phẩm riêng. Module cung cấp onboarding một bước tạo toàn bộ cấu trúc một cách liền mạch, cộng với quản lý vòng đời đầy đủ của từng thực thể sau đó.

2. Phạm vi

Bao gồm	Loại trừ
Tạo tổ chức qua onboarding	Vòng đời & đăng nhập nhân viên (→ Quản lý Người dùng)
Hồ sơ tổ chức, phân cấp, cài đặt, đính kèm	Định nghĩa vai trò/quyền (→ Quyền hạn)
Tạo merchant (đơn, hàng loạt, aggregate)	Nội dung catalog sản phẩm (→ Sản phẩm)
Phân loại loại hình kinh doanh	Mức tồn kho (→ Tồn kho)
Quản lý kênh bán	Xử lý đơn hàng / checkout (→ Đơn hàng)
Quản lý danh mục với cờ add-on	Xử lý thanh toán (→ Thanh toán)
Chính sách xóa theo từng merchant	Phát hành hóa đơn điện tử (→ Thuế & Hóa đơn)
Cấu hình merchant mã hóa	Đặc tả API kỹ thuật (→ tài liệu developer)
Lọc dữ liệu theo vai trò

3. Định nghĩa

Thuật ngữ	Định nghĩa
Organization	Thực thể thương hiệu ảo cấp cao nhất. Container cha cho merchant, người dùng và thiết bị. Mang thương hiệu, không mang định danh pháp lý.
Merchant	Một đơn vị điểm bán vật lý/pháp lý dưới một tổ chức nơi giao dịch diễn ra. Nắm thông tin thuế, hồ sơ hóa đơn và ví.
Sale Channel	Một kênh bán trong một merchant (vd ăn tại chỗ, mang đi, giao hàng). Hỗ trợ phân cấp.
Category	Một nhóm sản phẩm trong một merchant. Có thể được đánh dấu là add-on.
Business Type	Phân loại điều khiển giao diện POS: DEFAULT, TICKET, FNB, THEATER.
Aggregate Operation	Một yêu cầu duy nhất tạo hoặc cập nhật một merchant cùng với danh mục và kênh bán của nó, một cách liền mạch.
Deletion Policy	Cấu hình theo từng merchant điều khiển hành vi cascade khi xóa thực thể.
Configuration	Cài đặt khóa-giá trị mã hóa cho một merchant (nhà cung cấp thanh toán, tích hợp).
Slug	Định danh thân thiện URL. Duy nhất toàn cục cho tổ chức; duy nhất theo tổ chức cho merchant; duy nhất theo merchant cho kênh bán.

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

Chỉ mang tính khái niệm - schema đầy đủ nằm trong mô hình miền developer.

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

Danh sách tính năng của module. Mỗi dòng là một tính năng (một Vùng chức năng). Chi tiết ở §6. Đối chiếu với danh mục tính năng Delivery.

Feature ID	Tính năng	Phase	Trạng thái	Ưu tiên
ORG	Tổ chức	P1	Built	High
MER	Merchant	P1	Built	High
SC	Kênh bán	P1	Built	High
CAT	Danh mục	P2	Built	High
DEL	Chính sách xóa	P2	Built	Medium
CFG	Cấu hình	P2	Built	Medium
ACC	Truy cập	P1	Built	High
RCP	Mẫu biên lai	P2	Built	Medium
FLR	Bố trí bàn & sơ đồ sàn	P2	Built	High
RTL	Loại hình bán lẻ	P2	Planned	High
BOP	Cổng Backoffice	P2	Planned	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ột mục con cho mỗi tính năng, theo thứ tự catalog. Mỗi tính năng giữ mô tả, yêu cầu, và nghiệm thu cùng nhau. Ưu tiên = MoSCoW (Must / Should / Could / Won't).

ORG - Tổ chức Built

Mã tính năng: commerce/ORG · Phase: P1 · PRDs: PRD-ORG-001 · Dev: @nx/commerce

Làm gì cho người dùng: chủ tạo một thực thể thương hiệu duy nhất qua onboarding - container cha cho mọi merchant, người dùng và thiết bị - rồi quản lý hồ sơ, phân cấp, cài đặt và đính kèm của nó suốt vòng đời.

Yêu cầu

ID	P	Yêu cầu
URD-ORG-001	M	Người dùng có thể tạo một tổ chức qua onboarding
URD-ORG-002	M	Onboarding tạo liền mạch tổ chức + merchant mặc định + kênh bán + truy cập
URD-ORG-003	M	Người dùng tạo được tự gán là Owner
URD-ORG-004	M	Tên (đa ngôn ngữ) và slug là bắt buộc; mọi trường khác tùy chọn
URD-ORG-005	M	Một định danh hệ thống duy nhất được sinh khi tạo và không sửa được
URD-ORG-006	M	Tổ chức tìm được theo ID hoặc theo slug (tra cứu cascade)
URD-ORG-007	M	Owner có thể cập nhật hồ sơ tổ chức
URD-ORG-008	M	Tạo/cập nhật aggregate hỗ trợ tệp đính kèm
URD-ORG-009	S	List/count tổ chức được lọc theo vai trò của người dùng
URD-ORG-010	S	Tổ chức có thể bị vô hiệu hóa (dữ liệu được bảo toàn, đảo ngược được)
URD-ORG-011	S	Tổ chức có thể chỉ định một merchant trụ sở
URD-ORG-012	S	Tổ chức có thể được lưu trữ (chỉ đọc vĩnh viễn)
URD-ORG-013	C	Tổ chức có thể có tổ chức con (phân cấp)
URD-ORG-014	M	Onboarding tự phục vụ chạy trong một transaction cục bộ và cấp quyền Owner cho người dùng gọi, không cấp license (PRD-ORG-001)
URD-ORG-015	M	Onboarding quản trị (aggregate) tạo một owner user mới và một license như một thao tác hai pha, bù trừ ngược lại đầy đủ khi pha 2 thất bại
URD-ORG-016	M	Onboarding quản trị có tính idempotent - một Idempotency-Key phát lại kết quả đã hoàn tất và từ chối lần thử đồng thời là đang-xử-lý
URD-ORG-017	S	Onboarding tự tạo một bộ mặc định cố định: một merchant trụ sở, hai kênh bán (Offline, Take away), và mẫu danh mục F&B (chỉ ngành F&B)
URD-ORG-018	S	Đổi merchant trụ sở phát ra một sự kiện organization-HQ-changed tới các consumer hạ nguồn

Nghiệm thu

AC-ORG-01: Onboarding là liền mạch

Cho	Khi	Thì
Một người dùng đã xác thực, chưa có tổ chức	Onboarding hoàn tất với tên + slug hợp lệ	Tổ chức (Activated) + merchant mặc định + (các) kênh mặc định được tạo; truy cập của chủ sở hữu được cấp; định danh hệ thống & slug tự sinh
Bất kỳ bước nào thất bại	Trong khi onboarding	Toàn bộ thao tác roll back - không có gì được lưu

AC-ORG-02: Tính duy nhất slug

Cho	Khi	Thì
Một tổ chức đã dùng slug "my-business"	Người dùng khác thử cùng slug	Tạo bị từ chối - slug đã được sử dụng

AC-ORG-03: Hai đường onboarding (PRD-ORG-001)

Cho	Khi	Thì
Một người dùng đã xác thực chưa có tổ chức	Hoàn tất onboarding tự phục vụ	Org + merchant trụ sở + các mặc định được tạo trong một transaction cục bộ; người dùng gọi là Owner; không cấp license
Một operator back-office cấp phát cho khách hàng	Hoàn tất onboarding quản trị (aggregate)	Một owner user mới và một license được cấp phát; khi pha 2 thất bại mọi thứ được bù trừ và không để lại gì

AC-ORG-04: Onboarding quản trị idempotent

Cho	Khi	Thì
Một request onboarding quản trị có Idempotency-Key	Gửi lại sau khi đã hoàn tất	Kết quả đã lưu được phát lại - không cấp phát tổ chức thứ hai
Cùng Idempotency-Key	Gửi lại khi vẫn đang chạy	Lần thử bị từ chối là đang-xử-lý

MER - Merchant Built

Mã tính năng: commerce/MER · Phase: P1 · PRDs: PRD-ORG-001 · Dev: @nx/commerce

Làm gì cho người dùng: chủ thêm các đơn vị điểm bán hợp pháp dưới tổ chức của mình - từng cái một, vài cái cùng lúc, hoặc cùng danh mục và kênh bán của chúng - và quản lý hồ sơ cùng vòng đời của từng merchant.

Yêu cầu

ID	P	Yêu cầu
URD-MER-001	M	Merchant mặc định được tạo trong khi onboarding
URD-MER-002	M	Owner có thể tạo thêm merchant
URD-MER-003	M	Owner có thể tạo hàng loạt nhiều merchant
URD-MER-004	M	Owner có thể tạo aggregate một merchant với danh mục + kênh bán
URD-MER-005	M	Slug merchant duy nhất trong cùng một tổ chức
URD-MER-006	M	Merchant có thể được xem cùng kênh và danh mục của nó
URD-MER-007	M	Owner có thể cập nhật thông tin merchant
URD-MER-008	M	Cập nhật aggregate: chỉ-ID = xóa, ID+dữ liệu = cập nhật, không ID = tạo
URD-MER-009	M	Merchant tìm được theo ID hoặc theo slug (tra cứu cascade)
URD-MER-010	M	List merchant được lọc theo vai trò của người dùng
URD-MER-011	M	Count merchant tôn trọng cùng cách lọc như list
URD-MER-012	S	Merchant có thể bị vô hiệu hóa (đảo ngược được)
URD-MER-013	S	Merchant có thể được lưu trữ (chỉ đọc vĩnh viễn)
URD-MER-014	C	Phân cấp merchant (cha-con)
URD-MER-015	S	Cờ xóa rõ ràng phân biệt "xóa" với "giữ nguyên" trong cập nhật aggregate
URD-MER-016	M	Mọi thuộc tính pháp lý & tài chính (loại hình kinh doanh, định danh thuế, thông tin HĐĐT, tài khoản tài chính và ví, tiền tệ) thuộc về merchant - không bao giờ về tổ chức
URD-MER-017	M	Mỗi tổ chức có đúng một merchant trụ sở, tạo lúc onboarding và ghi nhận trên tổ chức
URD-MER-018	M	Ngành của merchant phải là ngành hàng hợp lệ; onboarding tạo sẵn các kênh bán và mẫu danh mục mặc định cho những ngành đó
URD-MER-019	S	Định danh thuế nhập trên merchant tự động được hồ sơ HĐĐT dùng lại, không nhập lại
URD-MER-020	M	Merchant trụ sở được tạo với slug suy ra, tên "Headquarter", cờ trụ sở, và phương pháp thuế trực tiếp
URD-MER-021	M	Mặc định enum của merchant: loại hình kinh doanh Household (hoặc Business); ngành F&B (Retail / Ticket / Other); tiền tệ VND
URD-MER-022	S	Tiến trình onboarding là sáu bước có thứ tự trên merchant (thông tin merchant → kênh bán → tài khoản tài chính → thông tin thuế → sản phẩm → nhân viên), hiển thị dưới dạng đã-hoàn-thành/tổng trong launchpad
URD-MER-023	S	Tính duy nhất slug nhận biết soft-delete (một slug đã gỡ được giải phóng); onboarding aggregate tự thêm hậu tố một token duy nhất khi va chạm; không có giới hạn số merchant mỗi tổ chức

Nghiệm thu

AC-MER-01: Tạo aggregate

Cho	Khi	Thì
Một chủ sở hữu có tổ chức hiện có	Tạo một merchant với danh mục + kênh	Merchant, danh mục, kênh đều được tạo liền mạch; định danh được sinh
Bất kỳ con nào không hợp lệ	Trong khi tạo aggregate	Toàn bộ thao tác roll back

AC-MER-02: Cập nhật aggregate thông minh

Cho	Khi	Thì
Item con chỉ có ID	Cập nhật aggregate	Item bị xóa
Item con có ID + dữ liệu	Cập nhật aggregate	Item được cập nhật
Item con không có ID	Cập nhật aggregate	Item được tạo

AC-MER-03: Trụ sở & thuộc tính pháp lý

Cho	Khi	Thì
Một người dùng hoàn tất onboarding	Tổ chức được tạo	Một merchant trụ sở tồn tại và được ghi nhận là trụ sở của tổ chức - trong cùng một bước
Một tổ chức	Chủ tìm nơi nhập định danh thuế / HĐĐT / ví	Không có chỗ - những thứ này nhập trên merchant, không trên tổ chức
Một merchant đã nhập MST	Chủ phát hành một hóa đơn	Tự động dùng định danh thuế của merchant, không nhập lại

AC-MER-04: Các mặc định tự tạo (PRD-ORG-001)

Cho	Khi	Thì
Bất kỳ onboarding nào hoàn tất	Cấu trúc được tạo	Đúng một merchant trụ sở (slug suy ra, "Headquarter", phương pháp thuế trực tiếp) và hai kênh bán (Offline, Take away) tồn tại
Ngành onboarding là F&B	Merchant được tạo	Mẫu danh mục F&B được tạo sẵn
Ngành onboarding là retail / ticket / khác	Merchant được tạo	Không tạo sẵn mẫu danh mục nào

SC - Kênh bán Built

Mã tính năng: commerce/SC · Phase: P1 · PRDs: - · Dev: @nx/commerce

Làm gì cho người dùng: mỗi merchant có một hoặc nhiều kênh bán (ăn tại chỗ, mang đi, giao hàng), được tạo lúc onboarding và quản lý qua aggregate merchant hoặc thêm hàng loạt vào một merchant hiện có.

Yêu cầu

ID	P	Yêu cầu
URD-SC-001	M	(Các) kênh mặc định được tạo trong khi onboarding
URD-SC-002	M	Kênh được quản lý như một phần của thao tác aggregate merchant
URD-SC-003	M	Kênh có thể được tạo hàng loạt cho một merchant hiện có
URD-SC-004	M	Slug kênh duy nhất trong cùng một merchant
URD-SC-005	M	Một định danh hệ thống duy nhất được sinh khi tạo và không sửa được
URD-SC-006	C	Phân cấp kênh (cha-con)
URD-SC-007	S	Kênh có thể bị vô hiệu hóa hoặc lưu trữ

Nghiệm thu

AC-SC-01: Kênh qua aggregate

Cho	Khi	Thì
Một chủ có một merchant hiện có	Quản lý kênh qua aggregate merchant hoặc thêm hàng loạt	Kênh được tạo với một định danh hệ thống duy nhất; slug duy nhất trong merchant

CAT - Danh mục Built

Mã tính năng: commerce/CAT · Phase: P2 · PRDs: - · Dev: @nx/commerce

Làm gì cho người dùng: chủ nhóm sản phẩm thành danh mục theo từng merchant, quản lý qua aggregate merchant, với tùy chọn đánh dấu một danh mục là nhóm add-on.

Yêu cầu

ID	P	Yêu cầu
URD-CAT-001	M	Danh mục được quản lý như một phần của thao tác aggregate merchant
URD-CAT-002	M	Danh mục có thể được đổi tên qua cập nhật aggregate mà không ảnh hưởng sản phẩm của nó
URD-CAT-003	M	Danh mục có thể được xóa qua cập nhật aggregate (soft-delete)
URD-CAT-004	S	Danh mục có thể được đánh dấu là add-on (và bỏ đánh dấu)

Nghiệm thu

AC-CAT-01: Danh mục qua aggregate

Cho	Khi	Thì
Một danh mục có sản phẩm liên kết	Đổi tên qua cập nhật aggregate	Danh mục được đổi tên; sản phẩm của nó không bị ảnh hưởng
Một danh mục	Xóa qua cập nhật aggregate	Danh mục bị soft-delete

DEL - Chính sách xóa Built

Mã tính năng: commerce/DEL · Phase: P2 · PRDs: - · Dev: @nx/commerce

Làm gì cho người dùng: mỗi merchant mang một chính sách cấu hình được điều khiển cách xóa cascade - liệu một danh mục có sản phẩm liên kết có thể bị xóa hay không, và liệu xóa một danh mục có xóa luôn sản phẩm của nó.

Yêu cầu

ID	P	Yêu cầu
URD-DEL-001	S	Mỗi merchant có một chính sách xóa cấu hình được
URD-DEL-002	S	strictCategoryDeletion: khi true, bị chặn nếu danh mục có sản phẩm liên kết
URD-DEL-003	S	cascadeProductDeletion: khi true, xóa một danh mục cascade tới sản phẩm của nó
URD-DEL-004	S	Owner có thể xem và cập nhật chính sách xóa

Nghiệm thu

AC-DEL-01: Chính sách xóa

Cho	Khi	Thì
strictCategoryDeletion = true	Xóa một danh mục có sản phẩm	Bị chặn
cascadeProductDeletion = true	Xóa một danh mục	Sản phẩm của nó cũng bị xóa

CFG - Cấu hình Built

Mã tính năng: commerce/CFG · Phase: P2 · PRDs: - · Dev: @nx/commerce

Làm gì cho người dùng: merchant lưu thông tin xác thực nhà cung cấp thanh toán và cài đặt tích hợp dưới dạng cấu hình khóa-giá trị mã hóa, được tổ chức theo nhóm chức năng.

Yêu cầu

ID	P	Yêu cầu
URD-CFG-001	S	Merchant có thể lưu thông tin xác thực nhà cung cấp thanh toán và cài đặt tích hợp
URD-CFG-002	S	Thông tin xác thực nhạy cảm được mã hóa khi lưu
URD-CFG-003	S	Cấu hình được tổ chức theo nhóm (system, table, integration)

Nghiệm thu

AC-CFG-01: Cấu hình mã hóa

Cho	Khi	Thì
Một merchant lưu thông tin xác thực nhà cung cấp thanh toán	Lưu	Thông tin xác thực nhạy cảm được mã hóa khi lưu và tổ chức theo nhóm

ACC - Truy cập Built

Mã tính năng: commerce/ACC · Phase: P1 · PRDs: - · Dev: @nx/commerce

Làm gì cho người dùng: dữ liệu được cô lập theo vai trò - chủ chỉ thấy tổ chức và merchant của mình, nhân viên chỉ thấy merchant được gán, và mọi list/count được lọc tương ứng.

Yêu cầu

ID	P	Yêu cầu
URD-ACC-001	M	Truy cập người dùng được quản lý qua chính sách theo vai trò (cấp org hoặc cấp merchant)
URD-ACC-002	M	Nhân viên có thể được gán cho các merchant cụ thể
URD-ACC-003	M	Một người dùng có thể được cấp quyền truy cập nhiều tổ chức
URD-ACC-004	M	Owner chỉ thấy tổ chức và merchant của mình
URD-ACC-005	M	Mọi thao tác list/count được lọc theo vai trò của người dùng (Admin bỏ qua)
URD-ACC-006	M	Owner có thể tạo, xem và cập nhật tổ chức của mình
URD-ACC-007	M	Owner có thể tạo, cập nhật và vô hiệu hóa merchant
URD-ACC-008	M	Owner có thể quản lý kênh và danh mục qua thao tác aggregate
URD-ACC-009	M	Owner có thể gán một nhân viên cho một merchant cụ thể
URD-ACC-010	M	Nhân viên chỉ thấy merchant được gán
URD-ACC-011	M	Nhân viên không thể truy cập merchant chưa được gán
URD-ACC-012	M	Một người dùng có vai trò không nhận diện được sẽ bị từ chối (không có kết quả rỗng âm thầm)
URD-ACC-013	M	License được cấp cho owner user mới; mã kích hoạt/hợp đồng của nó được trả lại, không bao giờ lưu
URD-ACC-014	M	Việc cấp quyền owner là ba dòng truy cập - join-domain tới org, join-domain tới merchant, assign-role Owner
URD-ACC-015	M	Aggregate-create merchant quản trị rẽ nhánh theo người gọi - admin back-office scope Owner tới merchant; một owner tổ chức tự liên kết mình
URD-ACC-016	S	Các đường đọc list/count/find tổ chức/merchant được scope tại handler từ các grant của người gọi (engine chính sách trung tâm hiện không gác các đường đọc này)

Nghiệm thu

AC-ACC-01: Cô lập theo vai trò

Cho	Khi	Thì
Owner A (Org X) và Owner B (Org Y)	Owner A yêu cầu dữ liệu tổ chức/merchant	Chỉ trả dữ liệu Org X; Org Y không hiển thị
Nhân viên chỉ được gán Merchant X	Yêu cầu list merchant	Chỉ trả Merchant X

FLR - Bố trí bàn & sơ đồ sàn Built

Mã tính năng: commerce/FLR · Phase: P2 · PRDs: PRD-FLR-001 · Dev: @nx/commerce · @nx/sale

Tính năng làm gì cho người dùng: một merchant F&B thiết kế sàn vật lý thành một layout có tên chứa một cây zone (sàn → phòng → bàn) với các zone lá mang unit (bàn) có sức chứa, vị trí và style - dựng trong một aggregate nguyên tử - rồi tại POS chiếm dụng unit bằng đơn dine-in, thấy mỗi bàn trống hay bận trực tiếp, tìm bàn trống, chuyển khách giữa các vùng, và giải phóng bàn khi đơn của nó xong.

Yêu cầu

ID	P	Yêu cầu
URD-FLR-001	M	Một merchant mô hình hóa sàn thành một layout có tên; mỗi layout thuộc một merchant
URD-FLR-002	M	Một layout chứa một cây zone (sàn / phòng / bàn), tự lồng tối đa hai cấp dưới gốc layout
URD-FLR-003	M	Một zone lá chứa unit (bàn); một unit khai báo sức chứa tùy chọn, một vị trí (canvas), và một style
URD-FLR-004	M	Chủ có thể tạo một layout cùng cả cây zone lồng nhau trong một thao tác aggregate nguyên tử
URD-FLR-005	M	Cập nhật aggregate layout theo quy ước id: chỉ-id = xóa (cascade sub-tree), id+data = cập nhật, không-id = tạo
URD-FLR-006	M	Một zone tự nó cũng create/update được như một aggregate với zone con và unit lồng nhau; zone cũng có thể tạo hàng loạt
URD-FLR-007	M	Một aggregate vượt giới hạn độ sâu hai cấp, hoặc tham chiếu một zone không thuộc layout đích, bị từ chối trước khi lưu gì
URD-FLR-008	S	Chủ có thể đọc một aggregate layout (cây zone + unit) với độ sâu tối đa cấu hình được - cây đầy đủ cho back-office, nông cho POS
URD-FLR-009	S	Layout, zone và unit mỗi cái mang một trạng thái vòng đời (Activated / Deactivated / Archived) và được soft-delete
URD-FLR-010	M	Layout, zone và unit cũng được quản lý độc lập (CRUD), scope theo merchant
URD-FLR-011	M	Mở một đơn dine-in trên một hoặc nhiều unit tạo một usage chiếm dụng đánh dấu các unit đó bận trên sơ đồ sàn
URD-FLR-012	M	Một usage mang một khung đặt chỗ (từ / đến); nếu không cho thời điểm kết thúc, một khung mặc định 90 phút áp dụng
URD-FLR-013	M	Chiếm dụng theo reserved/active → success → completed (bàn được giải phóng), hoặc cancelled; một usage terminal không thể bị hủy lại
URD-FLR-014	M	Một unit hiện bận khi nó giữ một usage ở trạng thái reserved / active / success, và trống khi ngược lại
URD-FLR-015	M	POS có thể truy vấn unit khả dụng trong một zone, và zone con mà mọi unit đều trống, ở độ sâu phân giải hiện tại
URD-FLR-016	M	Nhân viên có thể chuyển một nhóm giữa các zone - usage nguồn bị hủy và unit của zone đích được chiếm cho mỗi đơn, nguyên tử
URD-FLR-017	M	Tách một đơn nhân bản các usage đang hoạt động của nó sang mỗi đơn mới; gộp chuyển chúng sang đơn còn sống
URD-FLR-018	M	Mỗi thay đổi chiếm dụng phát một sự kiện sơ đồ sàn thời gian thực để mọi máy POS đồng bộ
URD-FLR-019	S	Một usage có thể ghi thông tin khách (tên, điện thoại, email, số khách)
URD-FLR-020	S	Đơn / đặt chỗ giữ một snapshot phân bổ (unit và đường dẫn zone của nó, cùng khách) để phân bổ tồn tại trên tài liệu
URD-FLR-021	M	Mọi thao tác phân bổ scope theo merchant (x-merchant-id) và được gác bởi quyền phân bổ

Tiêu chí chấp nhận

AC-FLR-01: Aggregate sàn nguyên tử (PRD-FLR-001)

Given	When	Then
Một chủ đang thiết kế sàn	Lưu một layout với zone và unit lồng nhau trong một aggregate	Layout, zone và unit đều được tạo nguyên tử
Một item con chỉ-id / id + data / không-id	Một cập nhật aggregate layout	Con chỉ-id bị xóa (cascade), con id+data được cập nhật, con không-id được tạo
Bất kỳ bước con nào lỗi	Trong aggregate	Cả thao tác rollback - không cây dựng dở nào tồn tại

AC-FLR-02: Giới hạn độ sâu & guard thuộc-layout

Given	When	Then
Một cây zone sâu hơn hai cấp dưới gốc layout	Gửi như một aggregate	Việc lưu bị từ chối trước khi lưu gì
Một cập nhật tham chiếu một zone thuộc layout khác (hoặc không phải zone gốc)	Gửi	Việc lưu bị từ chối vì không thuộc layout

AC-FLR-03: Chiếm và giải phóng một bàn

Given	When	Then
Một bàn trống	Một đơn dine-in mở trên nó	Unit hiện bận trên sơ đồ sàn; một usage với khung đặt chỗ (mặc định 90 phút) được ghi
Một bàn có đơn đã trả (success)	Bàn được hoàn thành	Usage trở thành completed và unit hiện trống trở lại
Một usage đã completed hoặc cancelled	Một nỗ lực hủy nó	Bị từ chối - một usage terminal không thể bị hủy lại

AC-FLR-04: Khả dụng bàn trống

Given	When	Then
Một zone có một số bàn đang bận	Một truy vấn "bàn trống"	Chỉ các unit không có usage reserved/active/success được trả về
Một zone cha với vài zone con	Một truy vấn zone khả dụng	Chỉ các zone con mà mọi unit đều trống được trả về

AC-FLR-05: Chuyển một nhóm giữa các zone

Given	When	Then
Một nhóm ngồi ở phòng chính	Chuyển sang zone sân vườn	Nguyên tử: usage nguồn bị hủy và unit của sân vườn được chiếm cho mỗi đơn liên quan; cả hai động tác được phát trực tiếp
Zone nguồn không có usage hoạt động, hoặc zone đích không có unit	Thử chuyển	Bị từ chối với lý do rõ ràng; không gì thay đổi

RCP - Mẫu biên lai Built

Mã tính năng: commerce/RCP · Phase: P2 · PRDs: PRD-RCP-001 · Dev: @nx/commerce

Tính năng làm gì cho người dùng: chủ thiết kế biên lai in của mình trông ra sao - theo từng merchant hoặc từng kênh bán, và theo từng ngôn ngữ - bằng cách lắp một bố cục có tên từ một bộ khối cố định (text, đường phân tách, ảnh logo, một bảng dòng hàng, barcode, QR, và một grid cho các hàng cạnh nhau). Bố cục được kiểm tra khi lưu, một mẫu là mặc định cho mỗi ngôn ngữ, và khi thanh toán mẫu được chọn render thành một ảnh raster đơn sắc vừa khổ giấy in nhiệt 58mm hoặc 80mm.

Yêu cầu

ID	P	Yêu cầu
URD-RCP-001	M	Một mẫu biên lai có tên gắn phạm vi merchant hoặc một kênh bán
URD-RCP-002	M	Mỗi mẫu khai báo khổ giấy (58mm hoặc 80mm) và một cỡ chữ nền
URD-RCP-003	M	Tên mẫu duy nhất theo (principal, locale) và nhận biết soft-delete
URD-RCP-004	M	Mẫu theo từng locale; một merchant/kênh giữ một bộ mẫu cho mỗi ngôn ngữ
URD-RCP-005	M	Đúng một mẫu mặc định cho mỗi (principal, locale); đặt mặc định gỡ mặc định trước đó
URD-RCP-006	M	Bố cục là một danh sách khối có thứ tự từ bộ cố định: text, line, image, bảng dòng hàng, barcode, QR, grid
URD-RCP-007	M	Bố cục được kiểm tra theo bộ khối khi tạo và cập nhật; một bố cục không hợp lệ bị từ chối
URD-RCP-008	M	Khối text, dòng hàng, barcode, QR gắn với field đơn hàng động phân giải khi in
URD-RCP-009	S	Bảng dòng hàng render các cột cấu hình được (field, header, width, align, format) với hàng tiêu đề tùy chọn
URD-RCP-010	S	Một khối grid đặt các con vào cột tỉ lệ với canh / phân bố (tối đa 5 hàng)
URD-RCP-011	S	Các khối mang style trình bày (canh, độ đậm, biến đổi chữ, gạch, viền, màu, padding)
URD-RCP-012	S	Giá trị số, tiền tệ, ngày định dạng theo format đã khai báo trên khối hoặc cột
URD-RCP-013	M	Một mẫu render thành ảnh raster đơn sắc vừa khổ giấy (58mm → 384px, 80mm → 576px)
URD-RCP-014	S	Mẫu mang trạng thái vòng đời (Activated / Deactivated / Archived) và được soft-delete
URD-RCP-015	M	Mọi thao tác theo phạm vi merchant (x-merchant-id) và được kiểm soát bởi quyền mẫu biên lai
URD-RCP-016	S	Mẫu liệt kê/lọc được theo principal, locale, trạng thái, và cờ mặc định

Tiêu chí chấp nhận

AC-RCP-01: Bố cục được kiểm tra khi lưu (PRD-RCP-001)

Given	When	Then
Một chủ đang sửa bố cục biên lai	Lưu một bố cục dựng từ bộ khối cố định	Mẫu được lưu; bố cục được chấp nhận
Một bố cục có cột thiếu field hoặc một loại khối lạ	Lưu	Bị từ chối - nội dung mẫu biên lai không hợp lệ; không lưu gì

AC-RCP-02: Một mặc định cho mỗi phạm vi và ngôn ngữ

Given	When	Then
Một merchant có mẫu A là mặc định tiếng Việt	Mẫu B được đánh dấu mặc định cho tiếng Việt	B thành mặc định; A không còn mặc định - đúng một mặc định cho (principal, locale) đó
Mặc định tiếng Anh và mặc định tiếng Việt của một kênh	Xét cùng nhau	Mỗi ngôn ngữ có một mặc định riêng; chúng không ảnh hưởng nhau

AC-RCP-03: Phạm vi & render khi thanh toán

Given	When	Then
Một merchant có mẫu mặc định 80mm và một lượt thanh toán hoàn tất	Biên lai in ra	Mẫu mặc định của merchant theo ngôn ngữ của đơn được dùng, field và dòng hàng của đơn được gắn, và một raster đơn sắc rộng 576px được tạo
Một kênh bán có mẫu riêng	Một lượt bán trên kênh đó in ra	Mẫu của kênh được ưu tiên dùng thay vì của merchant

RTL - Loại hình Bán lẻ Planned

Mã tính năng: commerce/RTL · Phase: P2 · PRDs: PRD-RTL-001 · Dev: @nx/commerce

Mang lại gì cho người dùng: một cửa hàng bán lẻ tổng hợp (tạp hoá, thời trang, tiện lợi) chạy được trên KICKO theo kiểu bán lẻ - onboard với loại hình bán lẻ, nhận cấu trúc danh mục bán lẻ, và bán tại quầy scan-first không vướng bước phòng bàn/bếp. Bán lẻ là một mảng nghiệp vụ đầy đủ (quy tắc nghiệp vụ + giao diện riêng), không phải một biến thể của F&B.

Yêu cầu

ID	P	Yêu cầu
URD-RTL-001	M	Chủ quán onboard được merchant với loại hình Bán lẻ
URD-RTL-002	M	Loại hình kinh doanh là lựa chọn tường minh khi onboard - không bao giờ âm thầm mặc định F&B
URD-RTL-003	M	Merchant bán lẻ nhận mẫu danh mục bán lẻ khi onboard (như các sector F&B hiện nay)
URD-RTL-004	M	Tại POS, merchant bán lẻ có luồng bán tại quầy: quét/tìm → giỏ → thanh toán - không bước phòng bàn
URD-RTL-005	M	Thu ngân thêm hàng vào giỏ bằng cách quét barcode của variant
URD-RTL-006	M	Hóa đơn và thuế chạy đúng cho merchant bán lẻ
URD-RTL-007	S	Các bề mặt chỉ-dành-cho-F&B (sơ đồ bàn, bếp, đặt chỗ) được ẩn với merchant bán lẻ
URD-RTL-008	S	Màn hình catalog xử lý hiệu quả hàng nhiều biến thể (size/màu)
URD-RTL-009	S	Merchant bán lẻ vận hành ca và đối soát tiền mặt giống hệt F&B
URD-RTL-010	C	Tạp hoá: màn bán hiển thị thông tin lô/hạn sử dụng khi có theo dõi

Nghiệm thu

AC-RTL-01: Onboard bán lẻ

Given	When	Then
Chủ quán mới chọn loại hình Bán lẻ	Onboard hoàn tất	Merchant được tạo với mẫu danh mục bán lẻ; không thiết lập artefact F&B (sơ đồ bàn, bếp)
Chủ quán mới bỏ qua bước chọn loại hình	Submit onboard	Bắt buộc chọn - không mặc định ngầm F&B

AC-RTL-02: Bán tại quầy

Given	When	Then
Merchant bán lẻ tại POS	Thu ngân quét barcode variant	Hàng vào giỏ ngay lập tức; thanh toán hoàn tất không qua bước bàn/bếp

BOP - Cổng Backoffice Planned

Mã tính năng: commerce/BOP · Phase: P2 (T6-T8) · PRDs: PRD-BOP-001 · Dev: @nx/commerce · @nx/helpdesk

Mang lại gì cho người dùng: vận hành viên chạy một client end-to-end chỉ từ BO - onboard, cấu hình, import dữ liệu, hỗ trợ, và giám sát.

Yêu cầu

ID	P	Yêu cầu
URD-BOP-001	M	Vận hành onboard client end-to-end từ BO (org → merchant (MST) → kênh → loại hình)
URD-BOP-002	M	Cấu hình gói & giấy phép, lĩnh vực & mẫu danh mục, nhóm thuế từ BO
URD-BOP-003	M	Tra cứu giao dịch ở cấp quản trị (xuyên merchant)
URD-BOP-004	M	Import Excel hàng loạt: danh mục, sản phẩm/variant, giá, thuế - báo lỗi theo dòng, import lại không trùng
URD-BOP-005	M	Support Center trong BO: danh sách + chi tiết phiếu xử lý end-to-end
URD-BOP-006	S	Cấu hình SLA / danh mục / agent
URD-BOP-007	S	Dashboard quản trị: cửa hàng theo ngành, giao dịch theo cửa hàng
URD-BOP-008	S	Cấu hình phương thức thanh toán lên cấp quản trị

Nghiệm thu

AC-BOP-01: Vận hành client chỉ từ BO

Given	When	Then
Một client mới ký	Vận hành onboard + cấu hình chỉ qua BO	Merchant bán được - không đụng công cụ nào khác
Một file Excel catalog	Vận hành import	Catalog sẵn dùng; dòng lỗi báo theo dòng; import lại không sinh trùng

7. Ràng buộc & Mục tiêu Loại trừ

Ràng buộc

ID	Ràng buộc
C-01	Tổ chức phải tồn tại trước khi tạo merchant
C-02	Thao tác aggregate là liền mạch - tất cả hoặc không
C-03	Mọi thực thể dùng soft-delete; không có gì bị xóa vật lý
C-04	Tính duy nhất slug: toàn cục cho tổ chức, theo org cho merchant, theo merchant cho kênh
C-05	Mọi thao tác yêu cầu xác thực
C-06	Thông tin xác thực thanh toán được mã hóa khi lưu

Mục tiêu Loại trừ

• Truy cập liên-tổ-chức hoặc chia sẻ merchant giữa các tổ chức
• Chuyển quyền sở hữu (Dự kiến)
• Hard-delete bất kỳ thực thể nào
• CRUD kênh bán / danh mục độc lập ngoài aggregate merchant (Dự kiến)

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

Ngày	Tác giả	Mô tả	Ver
2026-06-15	Commerce squad	Thêm tính năng FLR Bố trí bàn & sơ đồ sàn (URD-FLR-001..021) - mô hình sàn layout/zone/unit dựng dạng aggregate nguyên tử (giới hạn độ sâu, guard thuộc-layout) cùng chiếm dụng usage trực tiếp, khả dụng, chuyển bàn, snapshot và sơ đồ sàn thời gian thực; backlink tới PRD-FLR-001	v0.8
2026-06-15	Commerce squad	Thêm tính năng RCP Mẫu biên lai (URD-RCP-001..016) - theo phạm vi merchant/kênh, theo locale, bộ khối cố định, một mặc định cho mỗi locale, render raster in nhiệt; backlink tới PRD-RCP-001	v0.7
2026-06-15	Commerce squad	Nội bộ onboarding: hai đường onboarding, saga + bù trừ, idempotency, license, các mặc định, sáu bước, các dòng cấp quyền owner (URD-ORG-014..018, MER-020..023, ACC-013..016); backlink tới PRD-ORG-001	v0.6
2026-06-04	Claude (AI pair)	Tổ chức lại theo tính năng (Feature Spine); mỗi tính năng tự mang yêu cầu + nghiệm thu	v0.5
2026-05-30	P. Nguyen	Chuyển sang quy ước module-docs; hòa hợp ID/vùng yêu cầu với test case	v0.4
2026-04-17	P. Nguyen	Gộp Organization + Merchant vào module Commerce	v0.3
2026-02-27	QE Assessment	Phát hiện QE	v0.2
2026-02-26	P. Do - Product Owner	Khởi tạo	v0.1