PRD: Organizer & merchant

Module	Thương mại	PRD ID	PRD-ORG-001
Trạng thái	Sẵn sàng dev	FEAT	ORG
Epic	—	Plane	BANA-1494
Ngày	2026-06-01	Phiên bản	v1.0
Gói	@nx/commerce	URD	ORG
Surface	BO · Vận hànhClient · Chủ/QL
Phụ trách	Phát Nguyễn

Organizer & merchant là gì

Mọi thứ trong BANA đều móc vào một merchant - sản phẩm, đơn hàng, tồn kho, tài chính. PRD này định nghĩa nền tảng doanh nghiệp cho toàn hệ thống: một tổ chức (Organizer) cho thương hiệu, và ít nhất một chi nhánh (Merchant) cho đơn vị bán hợp pháp, kèm kênh bán và danh mục riêng của merchant đó.

Organizer là ảo, merchant là pháp lý

Organizer là thương hiệu: tên đa ngôn ngữ, slug, phân cấp, branding. Nó không có tồn tại pháp lý - không mã số thuế, không tài khoản hóa đơn điện tử, không ví, không loại hình kinh doanh. Mọi thuộc tính pháp lý và tài chính - loại hình kinh doanh, định danh thuế, thông tin hóa đơn điện tử, tài khoản tài chính và ví, tiền tệ, ngành hàng, địa điểm vật lý - thuộc về merchant, và không bao giờ về organizer. Mỗi organizer luôn có đúng một merchant trụ sở chính, tạo cùng lúc với organizer trong bước onboarding. Bảng đầy đủ các nguyên tắc organizer/merchant nằm ở §8.1.

Vì sao feature này tồn tại

Nếu phải dựng từng mảnh bằng tay thì vừa chậm vừa dễ lỗi. Một bước thất bại giữa chừng để lại doanh nghiệp dở dang. Trùng slug chỉ lộ ra lúc bấm lưu. Và không có quy tắc nhất quán cho việc ai được thấy organizer, merchant nào. Feature này giải quyết trọn: dựng toàn bộ cấu trúc trong một bước, lưu merchant trọn gói cùng kênh bán và danh mục, kiểm tra slug trước khi submit, và lọc mọi danh sách theo vai trò của người dùng.

Một doanh nghiệp, từ lúc đăng ký tới lúc bán được hàng

Chủ mới onboard: organizer, merchant mặc định, kênh bán và quyền truy cập được tạo cùng nhau trong một bước. Sau đó chủ thêm merchant khác, từng cái một hoặc kèm luôn danh mục và kênh của nó. Khi cần sửa, chủ mở màn Sửa merchant và đổi thông tin merchant cùng kênh bán và danh mục của nó trong một lần lưu duy nhất - lưu được là được hết, có lỗi thì không có gì thay đổi. Mỗi người dùng sau đó mở launchpad và chỉ thấy đúng các organizer và merchant mà role của họ cho phép: chủ thấy doanh nghiệp của mình, nhân viên thấy merchant được giao, Super Admin thấy tất cả.

Chỗ dễ sai nhất

Merchant mang mã số thuế, organizer thì không

Organizer là thương hiệu, không phải đơn vị bán hợp pháp. Định danh thuế, tài khoản hóa đơn điện tử, ví, và loại hình kinh doanh đều thuộc về merchant. Một thương hiệu có thể phủ nhiều merchant với đăng ký thuế khác nhau - nhầm hai vai trò này là nhầm luôn chỗ lưu mọi thuộc tính pháp lý và tài chính của doanh nghiệp.

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

Mục tiêu

• Onboarding một bước tạo organizer, một merchant mặc định, các kênh bán của nó, và quyền truy cập owner cùng nhau - tất cả hoặc không gì cả.
• Lưu một merchant cùng danh mục và kênh bán của nó trong một bước. Trong lần lưu đó, một mục gửi kèm chi tiết thì được cập nhật, một mục mới được thêm, và một mục đánh dấu gỡ thì được gỡ.
• Một kiểm tra slug trước khi submit xác nhận tính duy nhất - toàn cục cho organizer, theo từng organizer cho merchant.
• Các launchpad lọc theo role (tóm tắt và tổng quan, gồm số người dùng đang giữ mỗi role) để mỗi người dùng chỉ thấy các organizer và merchant mà role của họ cho phép.
• Một back-office organizer được làm lại (trang tạo/sửa, hiển thị theo role).
• Nguyên tắc organizer vs merchant - organizer luôn là thương hiệu ảo; mọi thuộc tính pháp lý và tài chính thuộc về một merchant, không bao giờ về organizer.

Loại trừ

• Truy cập liên organizer hoặc chia sẻ merchant giữa các organizer.
• Chuyển quyền sở hữu (Planned).
• Làm lại việc quản lý sale channel / danh mục độc lập - các đường này đã có sẵn (xem PRD-SC-001 / PRD-CAT-001); PRD này lo phần onboarding và màn Sửa merchant của merchant.
• Xóa vĩnh viễn - mọi thứ chỉ bị vô hiệu hóa hoặc lưu trữ và có thể khôi phục.

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

Thước đo	Mục tiêu / tín hiệu
Onboarding thành công	Mỗi onboarding hoàn tất đều tạo ra organizer, merchant mặc định, kênh và quyền owner - hoặc không để lại gì
Tính toàn vẹn slug	Không slug organizer nào trùng trên toàn hệ thống; không slug merchant nào trùng trong cùng một organizer
Tính toàn vẹn lần lưu	Không có merchant nào bị lưu dở dang (không sót kênh hay danh mục thừa)
Cô lập giữa các doanh nghiệp	Dữ liệu của doanh nghiệp này không lọt sang doanh nghiệp khác qua danh sách lọc theo role
Thời gian onboarding	Thời gian trung vị từ lúc đăng ký đến lúc có merchant dùng được giảm dần

3. Persona & Tình huống

Persona	Mục tiêu
Chủ doanh nghiệp	Onboard doanh nghiệp, quản lý organizer cùng các merchant của nó, kiểm soát kênh và danh mục
Quản lý	Quản lý các merchant trong phạm vi cùng kênh và danh mục của chúng
Nhân viên	Chỉ xem các merchant được phân công
Super Admin	Thấy mọi organizer và merchant (không lọc theo role)

Tình huống lõi: chủ mới onboard (organizer + merchant mặc định + kênh + quyền truy cập trong một bước) → thêm merchant khác từng cái hoặc kèm luôn danh mục và kênh → sửa một merchant cùng kênh và danh mục của nó trong một lần lưu → mỗi người dùng mở launchpad chỉ thấy đúng các organizer và merchant mà role của họ cho phép.

4. User Stories

#	Là một	Tôi muốn	Để
01	chủ doanh nghiệp	onboarding tạo organizer của tôi, một merchant mặc định, các kênh bán của nó, và quyền owner của tôi trong một bước	tôi bắt đầu bán mà không phải thiết lập từng mảnh bằng tay
02	chủ doanh nghiệp	thêm, đổi, hoặc gỡ danh mục và kênh bán của một merchant trong một lần lưu	toàn bộ merchant được đối soát một lần và không bao giờ áp dụng dở dang
03	chủ doanh nghiệp	tính duy nhất của slug được kiểm tra trước khi submit	tôi không bao giờ mất một form vì một va chạm đến muộn
04	nhân viên	launchpad của mình chỉ hiển thị các merchant tôi được phân công	tôi không bao giờ thấy dữ liệu của doanh nghiệp khác
05	super admin	thấy mọi organizer và merchant	tôi hỗ trợ và kiểm toán xuyên các doanh nghiệp

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

#	Yêu cầu	Trạng thái	URD ref
FR-001	Onboarding tạo organizer + merchant mặc định + kênh bán + quyền owner cùng nhau, tất cả hoặc không. Người dùng tạo trở thành Owner.	✅	URD-ORG-001..003 · URD-MER-001 · URD-SC-001
FR-002	Organizer yêu cầu một tên đa ngôn ngữ và một slug. Một định danh không sửa được gán lúc tạo.	✅	URD-ORG-004..005
FR-003	Organizer và merchant tìm được theo mã hệ thống, lùi về slug (mã nghiệp vụ hiển thị không dùng để tìm). Owner có thể cập nhật profile organizer.	✅	URD-ORG-006..007 · URD-MER-009
FR-004	Màn Sửa merchant hỗ trợ đính kèm file trên organizer.	✅	URD-ORG-008
FR-005	Owner có thể tạo một merchant từng cái một, hoặc kèm luôn danh mục và kênh bán của nó.	✅	URD-MER-002..004
FR-006	Slug merchant duy nhất trong organizer của nó. Một kiểm tra slug xác nhận tính duy nhất organizer/merchant trước khi submit.	🔶	URD-MER-005 · URD-ORG-004
FR-007	Một merchant có thể được xem cùng kênh và danh mục của nó. Owner có thể cập nhật thông tin merchant.	✅	URD-MER-006..007
FR-008	Trong màn Sửa merchant, một mục kèm chi tiết được cập nhật, một mục mới được thêm, và một mục đánh dấu gỡ được gỡ. Việc gỡ được tách biệt rõ với "giữ nguyên".	✅	URD-MER-008 · URD-MER-015
FR-009	Danh sách organizer và merchant, cùng tổng của chúng, được lọc theo role (Admin thấy tất cả).	✅	URD-ORG-009 · URD-MER-010..011 · URD-ACC-004..005
FR-010	Owner chỉ thấy organizer và merchant của chính mình. • Owner có thể tạo, xem, và cập nhật chúng. • Bộ lọc role của launchpad từ chối giá trị không hợp lệ (danh sách thường của người chưa được cấp quyền trả về rỗng).	✅	URD-ACC-006..007 · URD-ACC-012
FR-011	Launchpad trả về tóm tắt và tổng quan lọc theo role, gồm số người dùng đang giữ mỗi role.	✅	URD-ORG-009 · URD-MER-010
FR-012	Organizer/merchant có thể bị vô hiệu hóa, đảo ngược được. • Merchant trụ sở chính có thể được chỉ định lại. • Organizer/merchant có thể được lưu trữ ở dạng chỉ-đọc.	🔶	URD-ORG-010..012
FR-013	Mọi thuộc tính pháp lý và tài chính thuộc về merchant - 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ệ - và không bao giờ về organizer.	✅	URD-MER-016
FR-014	Mỗi organizer có đúng một merchant trụ sở chính - tạo lúc onboarding và ghi nhận trên organizer trong cùng một bước.	✅	URD-MER-017
FR-015	Ngành của một merchant phải là ngành hàng hợp lệ. Onboarding tạo sẵn các kênh bán mặc định và mẫu danh mục mặc định cho những ngành đó.	✅	URD-MER-018
FR-016	Merchant là nơi nhập định danh thuế. Hồ sơ HĐĐT sau đó tự động dùng lại, không nhập lại.	✅	URD-MER-019
FR-017	Tồn tại hai đường onboarding. • Onboarding tự phục vụ chạy như một thao tác tất-cả-hoặc-không và cấp quyền Owner cho người dùng gọi, không license. • Onboarding quản trị (aggregate) tạo một owner user mới kèm một license.	✅	URD-ORG-014..015
FR-018	Onboarding quản trị là thao tác hai pha. • Pha 1 tạo organizer, merchant trụ sở chính, và các mặc định cục bộ. • Pha 2 tạo owner user, cấp quyền owner, và license. • Khi pha 2 thất bại, hệ thống bù trừ ngược lại theo nỗ lực tối đa (từng bước thu hồi có ghi log).	✅	URD-ORG-015
FR-019	Onboarding quản trị có tính idempotent qua một idempotency key tùy chọn gửi kèm request. • Gọi lại sau khi đã hoàn tất → key phát lại đúng kết quả cũ. • Gọi đồng thời cùng key đang xử lý → lần sau bị từ chối. • Không gửi key thì lần gọi đó không được bảo vệ.	✅	URD-ORG-016
FR-020	License được cấp cho owner user mới. Mã kích hoạt / hợp đồng của nó được trả lại cho người gọi, không bao giờ lưu.	✅	URD-ACC-013
FR-021	Onboarding tự tạo một bộ mặc định. • Đúng một merchant trụ sở chính (slug suy ra, tên "Headquarter", cờ trụ sở, phương pháp thuế trực tiếp). • Các kênh bán mặc định theo ngành (F&B: Offline + Take away; Retail: Counter + Online; ticket / khác: không có). • Mẫu danh mục theo ngành (F&B và Retail; ticket / khác không nhận gì).	✅	URD-ORG-017 · URD-MER-020
FR-022	Việc cấp quyền owner được ghi nhận là ba dòng truy cập - thành viên của organizer, thành viên của merchant, và gán role Owner. • Đường tự phục vụ ghi đúng ba dòng. • Đường quản trị đạt cùng kết quả bằng hai dòng thành viên cộng gán role lúc tạo owner user.	✅	URD-ACC-014
FR-023	Merchant có giá trị mặc định cho ba trường: loại hình kinh doanh, ngành, và tiền tệ. • Loại hình kinh doanh: Household mặc định / Business. • Ngành: Retail / F&B mặc định / Ticket / Other. • Tiền tệ: mặc định VND.	✅	URD-MER-021
FR-024	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). • Trạng thái từng bước suy ra lúc đọc từ dữ liệu hiện có, không lưu cờ. • Dữ liệu của một bước bị xóa thì bước đó trở lại chưa-hoàn-thành. • Launchpad hiển thị dưới dạng đã-hoàn-thành / tổng.	✅	URD-MER-022
FR-025	Tính duy nhất slug nhận biết gỡ bỏ - một slug đã gỡ được giải phóng để dùng lại. • Onboarding quản trị tự gắn một hậu tố định danh duy nhất khi slug va chạm. • Không có giới hạn số merchant mỗi organizer.	✅	URD-MER-023
FR-026	Các kết quả list, count, và find organizer / merchant được lọc trong ứng dụng từ các grant truy cập của người gọi (engine ủy quyền trung tâm hiện không gác các đường đọc này).	✅	URD-ACC-016
FR-027	Tạo merchant quản trị rẽ nhánh theo người gọi. • Admin back-office scope Owner tới merchant mới. • Một owner organizer tự liên kết mình.	✅	URD-ACC-015
FR-028	Đổi merchant trụ sở chính phát ra một sự kiện báo merchant trụ sở chính đã thay đổi tới các consumer hạ nguồn.	✅	URD-ORG-018
FR-029	Danh sách organizer / merchant hỗ trợ tìm kiếm chữ tự do và một chế độ chọn loại-trừ-đã-gán cho các picker gán quyền.	✅	URD-ORG-009 · URD-MER-010
FR-030	Màn merchant hiển thị một tóm tắt sáu số đếm. Launchpad organizer ghi nhớ và hiển thị thời điểm truy cập gần nhất của từng mục.	✅	URD-MER-010

5.1 Hai đường onboarding

Onboarding có hai điểm vào riêng biệt với mô hình sở hữu, hoàn tất, và cấp phát khác nhau. Các phiên bản PRD trước chỉ mô tả đường tự phục vụ. Màn hình Back Office của đường quản trị được đặc tả riêng tại PRD-BOP-001; PRD này giữ phần mô hình dùng chung cho cả hai surface.

Khía cạnh	Onboarding tự phục vụ	Onboarding quản trị (aggregate)
Điều khiển bởi	Người dùng đang đăng ký (chưa có organizer)	Một operator back-office cấp phát cho một khách hàng
Owner	Người dùng gọi trở thành Owner	Một owner user mới được tạo
Tính nguyên tử	Một thao tác cục bộ tất cả hoặc không	Quy trình hai pha: pha 1 cục bộ + pha 2 từ xa, có bù trừ
License	Không	Một license được cấp cho owner user mới
Idempotency	Không	Một idempotency key (tùy chọn, gửi kèm request) - phát lại nếu hoàn tất, từ chối nếu đang-xử-lý; không gửi key thì không được bảo vệ
Hình dạng request	Tên và slug của organizer cùng ngành và các ngành con (tùy chọn) của merchant	Organizer + merchant + thông tin owner mới + ý định license

Cả hai đường tạo ra cùng cấu trúc mặc định (§5.2) và cùng bộ ba dòng cấp quyền owner (FR-022).

5.2 Các mặc định tự tạo

Mỗi onboarding (đường nào cũng vậy) cấp phát một bộ mặc định cố định, không cấu hình được:

Mặc định	Quy tắc
Merchant trụ sở chính	Đúng một, slug suy ra từ slug organizer, tên "Headquarter", được đánh dấu trụ sở, phương pháp thuế trực tiếp; ghi nhận trên organizer làm trụ sở chính của nó
Kênh bán	Theo ngành - F&B: Offline + Take away; Retail: Counter + Online; ticket / khác: không có - với slug suy ra từ slug merchant
Mẫu danh mục	Ngành F&B và Retail - các danh mục mặc định từ mẫu danh mục hệ thống (khớp theo sector); ngành ticket và khác nhận không gì
Cấp quyền owner	Ba dòng truy cập - thành viên của organizer, thành viên của merchant, gán role Owner (FR-022)

5.3 Các bước tiến trình onboarding

Sau khi cấu trúc tồn tại, merchant theo dõi sáu bước onboarding có thứ tự, hiển thị trong launchpad merchant dưới dạng số đã-hoàn-thành / tổng:

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

Launchpad báo bao nhiêu trong sáu bước đã xong để một owner thấy còn lại gì trước khi merchant được thiết lập đầy đủ.

5.4 Tiêu chí nghiệm thu

• Onboarding tự phục vụ: hoàn tất tạo đủ organizer + merchant trụ sở chính + kênh bán theo ngành + ba dòng quyền owner; gây lỗi ở bất kỳ bước nào → không còn lại bản ghi nào.
• Onboarding quản trị: gọi lại với cùng idempotency key sau khi hoàn tất → nhận lại đúng kết quả cũ, không cấp phát thêm; hai lần gọi đồng thời cùng key → lần sau bị từ chối là đang-xử-lý; pha 2 thất bại → license bị thu hồi, owner user bị xóa, merchant và organizer bị gỡ (kiểm tra log từng bước bù trừ).
• Lưu gộp merchant: mục kèm chi tiết được cập nhật; mục mới được thêm; mục chỉ gửi định danh (đánh dấu gỡ) bị gỡ; mục vắng mặt khỏi payload giữ nguyên; lỗi giữa chừng → không thay đổi nào được lưu.
• Slug: tạo organizer trùng slug bị từ chối; tạo merchant trùng slug trong cùng organizer bị từ chối; merchant đã gỡ giải phóng slug cho lần dùng sau; onboarding quản trị gặp slug trùng tự gắn hậu tố và vẫn thành công.
• Launchpad & cô lập: nhân viên chỉ thấy merchant được phân công; owner chỉ thấy organizer/merchant của mình; Super Admin thấy tất cả; giá trị role không hợp lệ trên bộ lọc launchpad bị từ chối tường minh.
• Sáu bước: hoàn thiện dữ liệu của một bước → số đã-hoàn-thành tăng tương ứng; xóa dữ liệu của bước đó → số giảm về lại (suy ra lúc đọc, không lưu cờ).
• Kiểm tra slug trên giao diện trước khi submit chặn được trùng lặp; vô hiệu hóa organizer/merchant hoạt động đúng; đổi merchant trụ sở chính thực hiện được từ giao diện; server chặn ghi vào bản ghi đã lưu trữ.

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

Lĩnh vực	Yêu cầu
Tất cả hoặc không	Onboarding tự phục vụ và mọi lần lưu ở màn Sửa merchant đều hoàn tất trọn vẹn hoặc không để lại gì; riêng onboarding quản trị là quy trình hai pha với bù trừ nỗ lực tối đa (§5.1)
Toàn vẹn dữ liệu	Slug được ép duy nhất (toàn cục cho organizer, theo từng organizer cho merchant, theo từng merchant cho kênh); không xóa vĩnh viễn - các mục chỉ bị vô hiệu hóa hoặc lưu trữ và có thể khôi phục
Cô lập & truy cập	Mọi danh sách, số tổng và thay đổi đều lọc theo role; owner chỉ thấy organizer và merchant của mình, nhân viên chỉ thấy merchant được phân công, Admin thấy tất cả; role không nhận diện được thì bị từ chối
Định danh	Định danh gán lúc tạo và không bao giờ đổi
Ngôn ngữ	Tên organizer/merchant và các nhãn hiển thị cho người dùng đều ở nhiều ngôn ngữ
Nguồn sự thật	Commerce là nguồn sự thật. Hai luồng lan cụ thể sang hóa đơn: thông tin thuế của merchant được đồng bộ sang hồ sơ HĐĐT mỗi lần lưu, và việc đổi merchant trụ sở chính phát một thông báo tới bên hóa đơn

7. UX & Luồng

Onboarding aggregate quản trị - quy trình hai pha & bù trừ. Đường quản trị trải qua ba năng lực và bù trừ ngược lại theo nỗ lực tối đa nếu pha từ xa thất bại - từng bước thu hồi được ghi log để đội vận hành xử lý phần còn sót (hiếm gặp) - nên không để lại một khách hàng cấp phát dở dang.

Các màn hình chính nằm ở app quản trị của Owner (client) và Back Office: trang tạo/sửa organizer, form tạo/sửa merchant, các launchpad organizer và merchant lọc theo role, và các phần cài đặt merchant (ngôn ngữ, e-invoice, payment, ví tài chính). Màn onboarding của Back Office: xem PRD-BOP-001.

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

Khái niệm	Vai trò
Organizer	Thương hiệu ảo - tên đa ngôn ngữ, slug duy nhất toàn cục, trạng thái, vị trí trong một phân cấp
Merchant	Đơn vị bán hàng hợp pháp dưới một organizer - slug (duy nhất theo organizer), loại hình kinh doanh, tiền tệ, trạng thái
Kênh bán (Sale channel)	Một kênh bán trong một merchant (tại chỗ, mang đi, giao hàng); slug duy nhất theo merchant
Nhóm hàng (Category)	Một nhóm sản phẩm trong một merchant
Quyền truy cập (Access)	Việc cấp một organizer hoặc merchant theo role cho một người dùng; điều phối mọi danh sách lọc theo role

Chỉ ở mức khái niệm - chi tiết dữ liệu và quy tắc đầy đủ nằm trong domain model commerce.

8.1 Organizer vs merchant - các nguyên tắc

Nguyên tắc	Quy tắc
Org là ảo	Organizer là thương hiệu: tên, slug, phân cấp, branding. Nó không có tồn tại pháp lý - không MST, không tài khoản HĐĐT, không ví, không loại hình kinh doanh.
Merchant là pháp lý	Mọi thuộc tính pháp lý và tài chính thuộc về một merchant: loại hình kinh doanh (hộ kinh doanh hoặc doanh nghiệp, điều khiển quy tắc hóa đơn), định danh thuế (MST + địa chỉ đăng ký), thông tin HĐĐT, tài khoản tài chính và ví, tiền tệ, ngành hàng, và địa điểm vật lý.
Một trụ sở chính mỗi org	Onboarding tạo organizer và merchant trụ sở chính của nó cùng nhau; một organizer không bao giờ tồn tại mà thiếu merchant này.
Định danh & slug	Định danh của merchant gán lúc tạo và không bao giờ đổi. Slug của nó duy nhất trong organizer giữa các merchant đang hoạt động - gỡ một merchant giải phóng slug để dùng lại.
Mặc định theo ngành	Ngành của một merchant phải là ngành hàng hợp lệ; onboarding tạo sẵn các kênh bán mặc định và các mẫu danh mục cho những ngành đó.
Quyền sở hữu	Người onboarding trở thành Owner của organizer mới và merchant của nó. Một người dùng có thể sở hữu nhiều organizer; một merchant không bao giờ chuyển giữa các organizer.
Phân cấp	Merchant có thể tạo phân cấp cha-con trong organizer của mình - merchant con dưới merchant chính, không bao giờ xuyên organizer.
Định danh thuế chảy xuống	MST nhập một lần trên merchant và hồ sơ HĐĐT tự động dùng lại - sửa trên merchant là con đường duy nhất được hỗ trợ.

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

Phụ thuộc vào

#	Feature	Phụ thuộc điều gì
01	User Management (CORE-01)	owner và nhân viên thuộc về organizer và các merchant của nó.
02	Permissions (CORE-02)	role được scope theo organizer hoặc merchant; onboarding cấp quyền truy cập cho owner.

Giả định

#	Giả định	Sai thì sao
01	Một người dùng đã xác thực chưa có organizer điều khiển onboarding.	Một người dùng đã có sẵn organizer mà vẫn đi qua onboarding thì hệ thống tạo thêm một organizer/merchant trùng lặp thay vì dẫn họ vào cấu trúc đã có.
02	Có một bộ role để các launchpad và danh sách lọc được theo role (kèm một Admin thấy tất cả).	Thiếu một bộ role đầy đủ, hoặc thiếu vai trò Admin thấy tất cả, thì các launchpad và danh sách không có cơ sở để lọc đúng - dẫn tới lộ dữ liệu chéo doanh nghiệp hoặc chặn nhầm người có quyền hợp lệ.
03	Input slug được chuẩn hóa về dạng thân thiện URL trước khi kiểm tra tính duy nhất.	Bỏ qua hoặc làm sai bước chuẩn hóa thì kiểm tra tính duy nhất so hai chuỗi chưa cùng dạng, để lọt các slug trùng nhau trên URL thực tế nhưng khác nhau ở dấu, hoa/thường hoặc khoảng trắng.

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

Khía cạnh	Kế hoạch
Giai đoạn	P1 cho ORG / MER / ACC (theo catalog tính năng URD)
Triển khai	Mọi merchant; không có feature flag
Migration	Không - chạy trên dữ liệu sẵn có; không xóa vĩnh viễn gì
Tiêu chí ra mắt	Onboarding tạo organizer + merchant + kênh + quyền truy cập tất cả hoặc không; màn Sửa merchant của merchant thêm, cập nhật và gỡ đúng; kiểm tra slug chặn trùng lặp; launchpad lọc theo role, không rò rỉ giữa các doanh nghiệp
Giám sát	Tỷ lệ onboarding thành công/thất bại, lỗi lưu dở dang, lượt từ chối do va chạm slug, độ phủ lọc theo role

Tham chiếu

• URD: Commerce - Organizer · Merchant · Access
• Dựa trên: Sale Channels · Categories
• Module: Commerce - URD
• Developer: @nx/commerce · 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	Thất bại giữa chừng onboarding để lại doanh nghiệp dở dang	Tự phục vụ: tất cả hoặc không. Quản trị: hai pha + bù trừ nỗ lực tối đa, từng bước thu hồi có log
02	Màn Sửa merchant gỡ nhầm mục và làm mất dữ liệu	Việc gỡ phải đánh dấu tường minh, tách hẳn khỏi "giữ nguyên"; cả lần lưu là tất cả hoặc không
03	Va chạm slug chỉ lộ ra lúc submit	Có kiểm tra slug riêng xác thực trước khi submit
04	Giá trị role không hợp lệ trên bộ lọc launchpad	Bị từ chối tường minh; các danh sách thường của người chưa được cấp quyền trả về rỗng (đúng thiết kế)
05	Chưa có chuyển quyền sở hữu	Ngoài phạm vi (Planned); ghi nhận như một ràng buộc

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

#	Câu hỏi	Trả lời
01	Onboarding có tạo mọi thứ trong một lần không?	Đường tự phục vụ: có - organizer, merchant trụ sở chính, kênh bán, và quyền owner được tạo tất cả hoặc không; thất bại thì không lưu gì. Đường quản trị chạy hai pha với bù trừ nỗ lực tối đa (xem §5.1).
02	Màn Sửa merchant của merchant quyết định thêm vs. cập nhật vs. gỡ thế nào?	Một mục kèm chi tiết được cập nhật, một mục mới được thêm, và một mục đánh dấu gỡ được gỡ - xem quy tắc này ở §5.
03	Vì sao kiểm tra slug trước khi submit?	Để một form không bao giờ bị mất vì một va chạm phát hiện muộn.
04	Vì sao hai người dùng thấy launchpad khác nhau?	Mọi danh sách đều lọc theo role - một owner chỉ thấy organizer và merchant của mình, một nhân viên chỉ thấy merchant được phân công. Super Admin thấy tất cả.
05	Có thể chuyển một merchant sang organizer khác không?	Không - chia sẻ liên organizer và chuyển quyền sở hữu nằm ngoài phạm vi (Planned).
06	Vì sao organizer không mang MST?	Vì organizer là thương hiệu, không phải đơn vị bán hợp pháp. Định danh thuế, tài khoản HĐĐT, ví, và loại hình kinh doanh đều thuộc về merchant. Một thương hiệu có thể phủ nhiều merchant với đăng ký thuế khác nhau.
07	Một người dùng có thể sở hữu nhiều organizer không?	Có. Điều cố định là chiều ngược lại: một merchant thuộc về đúng một organizer, mãi mãi.
08	Vì sao có hai đường onboarding?	Onboarding tự phục vụ thiết lập người dùng gọi làm Owner trong một thao tác tất cả hoặc không, không license. Onboarding quản trị (từ back office) tạo một owner user hoàn toàn mới và một license, nên chạy như một quy trình hai pha bù trừ đầy đủ nếu pha từ xa thất bại. Xem §5.1.
09	Idempotency key làm gì?	Nó giúp onboarding quản trị an toàn để thử lại - một request đã hoàn tất phát lại kết quả đã lưu, và một lần thử đồng thời cùng key bị từ chối là vẫn đang-xử-lý, nên một khách hàng không bị cấp phát hai lần. Key là tùy chọn - không gửi thì lần gọi đó không được bảo vệ chống cấp phát trùng. Xem FR-019.
10	Có giới hạn số merchant mỗi organizer không?	Không - một organizer có thể giữ bất kỳ số merchant nào (FR-025).