URD: Commerce

Module	CORE-03	Phiên bản	v0.4
Trạng thái	Built	Ngày	2026-05-30

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 nguyên tử, 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 nguyên tử.
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. Yêu cầu Chức năng

Mỗi vùng chức năng một bảng. Mã <AREA> khớp với ID test-case. Mức ưu tiên = MoSCoW (Must / Should / Could / Won't).

5.1 Tổ chức (ORG)

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 nguyên tử 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)

5.2 Merchant (MER)

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

5.3 Kênh Bán (SC)

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ữ

5.4 Danh mục (CAT)

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)

5.5 Chính sách Xóa (DEL)

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

5.6 Cấu hình (CFG)

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)

5.7 Truy cập (ACC)

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)

6. Tiêu chí Chấp nhận

AC-ORG-01: Onboarding là nguyên tử

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-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 nguyên tử; đị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-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

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

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à nguyên tử — 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-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