Skip to content

PRD: Tổ chức & merchant

ModuleCommerce (CORE-03)PRD IDPRD-ORG-001
Trạng tháiShippedOwnerCommerce squad
Ngày2026-06-01 (v1.1: 2026-06-12 · v1.2: 2026-06-15)Phiên bảnv1.2
Packages@nx/commerce · @nx/coreURDORG · MER · ACC

Changelog — v1.2 (2026-06-15): Bổ sung phần nội bộ onboarding mà các phiên bản trước bỏ qua: hai đường onboarding (tự phục vụ vs aggregate quản trị), saga hai pha có bù trừ của aggregate, idempotency, cấp license cho owner mới, các mặc định hardcode (merchant trụ sở, kênh bán, mẫu danh mục F&B), sáu bước onboarding, ba dòng cấp quyền owner, mặc định enum của merchant, ghi chú scope đường đọc, và quy tắc không giới hạn số merchant. Toàn bộ nội dung v1.1 và trước đó giữ nguyên.

TL;DR

Cho chủ doanh nghiệp dựng toàn bộ cấu trúc của họ trong một bước: một tổ chức (thương hiệu) và các merchant (đơn vị bán hàng hợp pháp), mỗi đơn vị có kênh bán và danh mục. Sau đó một merchant được lưu cùng kênh bán và danh mục của nó trong một bước duy nhất, nên cấu trúc không bao giờ dở dang. Một kiểm tra slug trước khi submit bảo vệ tính duy nhất, và các launchpad lọc theo role chỉ hiển thị cho mỗi người dùng những tổ chức và merchant họ được phép thấy.

1. Bối cảnh & Vấn đề

Mọi thứ trong KICKO đều móc vào một merchant - sản phẩm, đơn hàng, tồn kho, tài chính. Thứ đầu tiên một chủ mới cần là một cấu trúc doanh nghiệp: một tổ chức cho thương hiệu và ít nhất một merchant cho đơn vị bán hợp pháp, mỗi đơn vị có kênh bán và danh mục riêng. Dựng từng mảnh thì chậm, dễ lỗi, và để lại doanh nghiệp dở dang khi một bước thất bại giữa chừng; trùng slug lộ ra muộn; và không có quy tắc nhất quán về việc một người dùng được thấy những tổ chức và merchant nào. Feature này dựng toàn bộ cấu trúc trong một bước, cho lưu một merchant 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 role của người dùng.

2. Mục tiêu & Ngoài phạm vi

Mục tiêu

  • Onboarding một bước tạo tổ chức, 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 tổ chức, theo từng tổ chức 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 tổ chức 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 tổ chức vs merchant - tổ chức 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ề tổ chức.

Ngoài phạm vi

  • 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 (Planned).
  • Quản lý kênh bán hoặc danh mục riêng lẻ, ngoài lần lưu gộp merchant (Planned).
  • Xóa vĩnh viễn - mọi thứ được vô hiệu hóa hoặc lưu trữ và có thể khôi phục.

3. Chỉ số Thành công

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

4. Persona & Tình huống Sử dụng

PersonaMục tiêu
Chủ doanh nghiệpOnboard một doanh nghiệp, quản lý tổ chức và 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 và kênh và danh mục của chúng
Nhân viênChỉ xem các merchant được phân công
Super AdminThấy mọi tổ chức và merchant (không lọc theo role)

Tình huống lõi: một chủ mới onboard (tổ chức + merchant mặc định + kênh + quyền truy cập trong một bước) → thêm các merchant khác từng cái một, vài cái cùng lúc, hoặc cùng danh mục và kênh của chúng → 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ở một launchpad hiển thị đúng các tổ chức và merchant mà role của họ cho phép.

5. User Story

  • Là một chủ doanh nghiệp, tôi muốn onboarding tạo tổ chức 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.
  • Là một chủ doanh nghiệp, tôi muốn 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.
  • Là một chủ doanh nghiệp, tôi muốn 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.
  • Là một nhân viên, tôi muố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.
  • Là một super admin, tôi muốn thấy mọi tổ chức và merchant, để tôi hỗ trợ và kiểm toán xuyên các doanh nghiệp.

6. Yêu cầu Chức năng

#Yêu cầuURD ref
FR-1Onboarding tạo tổ chức + 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 OwnerURD-ORG-001..003 · URD-MER-001 · URD-SC-001
FR-2Tổ chức 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ạoURD-ORG-004..005
FR-3Tổ chức và merchant tìm được theo định danh, lùi về slug; owner có thể cập nhật profile tổ chứcURD-ORG-006..007 · URD-MER-009
FR-4Lần lưu gộp hỗ trợ đính kèm file trên tổ chứcURD-ORG-008
FR-5Owner có thể tạo một merchant 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 nóURD-MER-002..004
FR-6Slug merchant duy nhất trong tổ chức của nó; một kiểm tra slug xác nhận tính duy nhất tổ chức/merchant trước khi submitURD-MER-005 · URD-ORG-004
FR-7Mộ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 merchantURD-MER-006..007
FR-8Trong lần lưu gộp, 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ỡ - với việc gỡ tách biệt khỏi "giữ nguyên"URD-MER-008 · URD-MER-015
FR-9Danh sách tổ chức 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-10Owner chỉ thấy tổ chức và merchant của chính mình; owner có thể tạo, xem, và cập nhật chúng; một role không nhận diện được bị từ chối, không bao giờ hiển thị danh sách rỗngURD-ACC-006..007 · URD-ACC-012
FR-11Launchpad 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 roleURD-ORG-009 · URD-MER-010
FR-12Tổ chức/merchant có thể bị vô hiệu hóa (đảo ngược được), chỉ định một merchant trụ sở, hoặc được lưu trữ (chỉ-đọc)URD-ORG-010..012
FR-13Mọ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ề tổ chứcURD-MER-016
FR-14Mỗ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 trong cùng một bướcURD-MER-017
FR-15Ngà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 và mẫu danh mục mặc định cho những ngành đóURD-MER-018
FR-16Merchant là nơi nhập định danh thuế; hồ sơ HĐĐT sau đó tự động dùng lại, không nhập lạiURD-MER-019
FR-17Tồn tại hai đường onboarding: 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 license; onboarding quản trị (aggregate) tạo một owner user mới kèm một licenseURD-ORG-014..015
FR-18Onboarding quản trị là thao tác hai pha - pha 1 tạo tổ chức, merchant trụ sở, và các mặc định cục bộ; pha 2 tạo owner user, cấp quyền owner, và license - và bù trừ ngược lại đầy đủ khi pha 2 thất bạiURD-ORG-015
FR-19Onboarding quản trị có tính idempotent: một Idempotency-Key (header hoặc payload) phát lại kết quả đã hoàn tất và từ chối một lần thử đồng thời là đang-xử-lýURD-ORG-016
FR-20License đượ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ưuURD-ACC-013
FR-21Onboarding tự tạo một bộ mặc định cố định - đúng một merchant trụ sở (slug suy ra, tên "Headquarter", cờ trụ sở, phương pháp thuế trực tiếp), hai kênh bán (Offline, Take away), và mẫu danh mục F&B (chỉ ngành F&B; retail / ticket / khác không nhận gì)URD-ORG-017 · URD-MER-020
FR-22Việc cấp quyền owner được ghi nhận là ba dòng truy cập - join-domain tới tổ chức, join-domain tới merchant, và assign-role OwnerURD-ACC-014
FR-23Mặc định enum của merchant: 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-24Tiế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ị trong launchpad dưới dạng đã-hoàn-thành / tổngURD-MER-022
FR-25Tính duy nhất slug nhận biết soft-delete (một slug đã gỡ được giải phóng để dùng lại); onboarding quản trị tự thêm hậu tố một token duy nhất khi slug va chạm; không có giới hạn số merchant mỗi tổ chứcURD-MER-023
FR-26Các đường đọc list, count, và find tổ chức / merchant được scope tại handler từ các grant truy cập 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)URD-ACC-016
FR-27Aggregate-create 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 tổ chức tự liên kết mìnhURD-ACC-015
FR-28Đổi merchant trụ sở phát ra một sự kiện organization-HQ-changed tới các consumer hạ nguồnURD-ORG-018

Toàn văn yêu cầu và tiêu chí nghiệm thu nằm trong URD Commerce. PRD này tham chiếu chúng thay vì lặp lại.

6.1 Hai đường onboarding

Onboarding có hai điểm vào riêng biệt với mô hình sở hữu, transaction, 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ụ.

Khía cạnhOnboarding tự phục vụOnboarding quản trị (aggregate)
Điều khiển bởiNgười dùng đang đăng ký (chưa có tổ chức)Một operator back-office cấp phát cho một khách hàng
OwnerNgười dùng gọi trở thành OwnerMột owner user mới được tạo
TransactionMột transaction cục bộ (tất cả hoặc không)Saga hai pha: pha 1 cục bộ + pha 2 từ xa, có bù trừ
LicenseKhôngMột license được cấp cho owner user mới
IdempotencyKhôngIdempotency-Key (header hoặc payload) - phát lại nếu hoàn tất, từ chối nếu đang-xử-lý
Hình dạng request{ organization: { name, slug }, merchant: { industry, sectors? } }Tổ chức + merchant + thông tin owner mới + ý định license

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

6.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 địnhQuy tắc
Merchant trụ sởĐúng một, slug suy ra từ slug tổ chức, tên "Headquarter", cờ trụ sở được đặt, phương pháp thuế trực tiếp; ghi nhận trên tổ chức làm trụ sở của nó
Kênh bánĐúng hai - OfflineTake away - với slug suy ra từ slug merchant
Mẫu danh mụcChỉ ngành F&B - các danh mục mặc định từ mẫu danh mục hệ thống; ngành retail, ticket, và khác nhận không gì
Cấp quyền ownerBa dòng truy cập - join-domain tới tổ chức, join-domain tới merchant, assign-role Owner (FR-22)

6.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 merchantkênh bántài khoản tài chínhthông tin thuếsản phẩmnhâ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 đủ.

7. Yêu cầu Phi chức năng

AreaRequirement
Tất cả hoặc khôngOnboarding và mọi lần lưu gộp hoàn tất trọn vẹn hoặc không để lại gì - một thất bại một phần không lưu gì
Tính toàn vẹn dữ liệuTính duy nhất slug được áp đặt (toàn cục cho tổ chức, theo từng tổ chức cho merchant, theo từng merchant cho kênh); không xóa vĩnh viễn gì - các mục được vô hiệu hóa hoặc lưu trữ và có thể khôi phục
Cô lập & truy cậpMọi danh sách, tổng, và thay đổi đều lọc theo role; owner chỉ thấy tổ chức 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ả; một role không nhận diện được 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 tổ chức/merchant và các nhãn hiển thị cho người dùng được hiển thị bằng nhiều ngôn ngữ
Nguồn sự thậtCommerce là nguồn sự thật; thay đổi merchant tự động lan tới các phần phụ thuộc như hóa đơn

8. UX & Luồng

Onboarding aggregate quản trị - saga & bù trừ

Đường quản trị trải qua ba dịch vụ và bù trừ đầy đủ nếu pha từ xa thất bại, nên không bao giờ để lại một khách hàng cấp phát dở dang.

Các màn hình chính trong back-office và POS client: trang tạo/sửa organizer, form tạo/sửa merchant kèm kiểm tra slug, 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).

9. Dữ liệu & Miền

Khái niệmVai trò
Tổ chức (Organization)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 tổ chức - slug (duy nhất theo tổ chức), 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, tùy chọn là nhóm add-on
Quyền truy cập (Access)Việc cấp một tổ chức 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.

9.1 Tổ chức vs merchant - các nguyên tắc

Nguyên tắcQuy tắc
Org là ảoTổ chức 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ở mỗi orgOnboarding tạo tổ chức merchant trụ sở của nó cùng nhau; một tổ chức 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 tổ chức 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ànhNgà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ữuNgười onboarding trở thành Owner của tổ chức mới và merchant của nó. Một người dùng có thể sở hữu nhiều tổ chức; một merchant không bao giờ chuyển giữa các tổ chức.
Phân cấpMerchant có thể tạo phân cấp cha-con trong tổ chức của mình - chi nhánh dưới cửa hàng chính, không bao giờ xuyên tổ chức.
Định danh thuế chảy xuốngMST 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ợ.

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

Phụ thuộc vào

  • User Management (CORE-01) - owner và nhân viên thuộc về tổ chức và các merchant của nó.
  • Permissions (CORE-02) - role được scope theo tổ chức hoặc merchant; onboarding cấp quyền truy cập cho owner.

Giả định

  • Một người dùng đã xác thực chưa có tổ chức điều khiển onboarding.
  • 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ả).
  • 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.

11. Rủi ro & Câu hỏi Mở

Rủi ro / câu hỏiGiảm thiểu / trạng thái
Thất bại giữa chừng onboarding để lại doanh nghiệp dở dangOnboarding là tất cả hoặc không; không lưu gì khi thất bại
Lần lưu gộp gỡ nhầm mục và làm mất dữ liệuViệc gỡ là một dấu hiệu tường minh, tách biệt khỏi "giữ nguyên"; lần lưu là tất cả hoặc không
Một va chạm slug chỉ lộ ra lúc submitMột kiểm tra slug riêng xác thực trước khi submit
Một role không nhận diện được âm thầm trả dữ liệu rỗngMột role không nhận diện được bị từ chối tường minh, không bao giờ hiển thị danh sách rỗng
Chưa có chuyển quyền sở hữuNgoài phạm vi (Planned); ghi nhận như một ràng buộc

12. Kế hoạch Phát hành & Tiêu chí Ra mắt

AspectPlan
PhaseP1 cho ORG / MER / ACC (theo catalog tính năng URD)
RolloutMọi merchant; không có feature flag
MigrationKhô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ắtOnboarding tạo tổ chức + merchant + kênh + quyền truy cập tất cả hoặc không; lần lưu gộp merchant thêm, cập nhật, và gỡ đúng; kiểm tra slug từ chối trùng lặp; launchpad lọc theo role không rò rỉ giữa các doanh nghiệp
Giám sátTỷ lệ onboarding thành công và thất bại, lỗi lưu dở dang, từ chối do va chạm slug, độ phủ lọc theo role

13. FAQ

Onboarding có tạo mọi thứ trong một lần không? Có - tổ chức, merchant mặc định, kênh bán, và quyền owner được tạo tất cả hoặc không. Nếu bất kỳ bước nào thất bại, không lưu gì.

Lần lưu gộp 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 lưu gộp ở §6.

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.

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 tổ chức 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ả.

Có thể chuyển một merchant sang tổ chức khác không? Không - chia sẻ liên tổ chức và chuyển quyền sở hữu nằm ngoài phạm vi (Planned).

Vì sao tổ chức không mang MST? Vì tổ chức 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.

Một người dùng có thể sở hữu nhiều tổ chức không? Có. Điều cố định là chiều ngược lại: một merchant thuộc về đúng một tổ chức, mãi mãi.

Vì sao có hai endpoint onboarding? Onboarding tự phục vụ thiết lập người dùng gọi làm Owner trong một transaction cục bộ 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 saga hai pha bù trừ đầy đủ nếu pha từ xa thất bại. Xem §6.1.

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 bao giờ bị cấp phát hai lần. Xem FR-19.

Có giới hạn số merchant mỗi tổ chức không? Không - một tổ chức có thể giữ bất kỳ số merchant nào (FR-25).

References

Proprietary and Confidential. Unauthorized copying, distribution, or use of this software is strictly prohibited.