PRD: Onboarding Merchant (Back Office)
| Module | Thương mại | PRD ID | PRD-BOP-001 |
| Trạng thái | Sẵn sàng dev | FEAT | BOP · BANA-1437 |
| Epic | BANA-1337 | Plane | BANA-1533 |
| Ngày | 2026-06-30 | Phiên bản | v1.0 |
| Gói | @nx/commerce · @nx/helpdesk | URD | BOP |
| Surface | BO · Vận hành | ||
| Phụ trách | Hải Cao · Phát Nguyễn | ||
Onboarding Merchant (Back Office) là gì
Ký một client trước đây nghĩa là nhảy qua lại nhiều công cụ và nhờ engineering: tạo tổ chức (Organizer) chỗ này, chi nhánh (Merchant) chỗ kia, tài khoản chủ chỗ khác, gắn gói dịch vụ bằng tay. Không có một nơi duy nhất để lấy một client vừa ký và dựng họ lên.
Luồng onboarding là một màn dẫn dắt tại Back Office, nơi đội vận hành đăng ký một client mới trọn vẹn trên bốn phần theo thứ tự: Organizer → Chủ → Merchant → Gói, kèm một thẻ xem trước cập nhật trực tiếp bên cạnh form. Đây là cửa trước của Back Office; quản lý merchant về sau nằm ở Quản lý Merchant.
Prefill từ inquiry, hoàn tất nguyên tử
Vào luồng từ một inquiry thì màn tự prefill thông tin doanh nghiệp và liên hệ của lead, ops không phải gõ lại. Thẻ xem trước phản ánh từng thay đổi ngay khi ops gõ, để soát lại trước khi hoàn tất.
Bấm hoàn tất tạo cùng lúc organizer, merchant trụ sở, tài khoản chủ, merchant đầu tiên, và license - nguyên tử, lỗi ở đâu thì không sót lại phần nào. Xong việc, màn đưa thẳng ops tới merchant mới, sẵn sàng cấu hình và bán ngay.
Chỗ dễ sai nhất
Bấm hoàn tất lại sau lỗi mạng không được tạo client thứ hai
Gửi lại cùng dữ liệu sau một lỗi mạng phải an toàn: không tạo trùng client, và logo đã tải lên không bị tải lại. Server chỉ lưu mật khẩu dạng băm; mật khẩu tạm của chủ chỉ thấy được trong phiên nhập - sau khi hoàn tất không xem lại được.
1. Mục tiêu & Loại trừ
Mục tiêu
- Một màn onboarding dẫn dắt bốn phần theo thứ tự: Organizer → Chủ → Merchant → Gói, kèm thẻ xem trước cập nhật trực tiếp theo form.
- Prefill từ một inquiry để ops khỏi gõ lại thông tin lead.
- Tạo organizer, merchant trụ sở, tài khoản chủ, merchant đầu tiên, và license thành một kết quả nguyên tử (atomic).
- Đưa ops tới tab Thông tin chung của merchant mới, sẵn sàng cấu hình.
Loại trừ
- Quản lý merchant sau onboarding - hồ sơ, vòng đời, thiết lập thanh toán (Quản lý Merchant).
- Cấu hình mẫu danh mục / kênh bán / mẫu khởi tạo và nhóm thuế như màn độc lập (
CAT,SC, System Config). - Import danh mục hàng loạt, support center, và dashboard quản trị - các năng lực back office riêng (dashboard là Phân tích Merchant).
- Tự đăng ký phía chủ trong app client.
2. Thước đo thành công
| Chỉ số | Mục tiêu / tín hiệu |
|---|---|
| Thời gian onboard | Một client đã ký được dựng lên trong một phiên back office, không cần engineering |
| Nguyên tử | Hoặc tạo cả client (organizer + merchant + chủ + merchant + license), hoặc không gì cả |
| Liền mạch lead | Client đến từ inquiry được onboard mà không gõ lại thông tin đã biết |
| Bàn giao | Khi hoàn tất ops được đưa thẳng tới merchant mới để tiếp tục thiết lập |
3. Persona & Tình huống
| Persona | Mục tiêu ở tính năng này |
|---|---|
| Đội vận hành | Dựng một client vừa ký lên trọn vẹn |
| Nhân viên onboarding / kinh doanh | Biến một inquiry thành một merchant sống, sẵn sàng bán |
Tình huống chính: ops bắt đầu onboarding (thường từ một inquiry, vốn prefill thông tin doanh nghiệp và liên hệ), điền organizer, tài khoản chủ, và merchant đầu tiên, chọn một gói dịch vụ trong khi thẻ xem trước phản ánh từng thay đổi, và hoàn tất; hệ thống tạo organizer kèm merchant trụ sở, chủ, merchant, và license cùng nhau, và mở tab Thông tin chung của merchant mới.
4. User Stories
| # | Là một | Tôi muốn | Để |
|---|---|---|---|
| 01 | ops | một màn dẫn dắt đi từ organizer tới gói | không sót bước khi dựng một client |
| 02 | ops | luồng được prefill từ inquiry | khỏi gõ lại thông tin lead |
| 03 | ops | tùy chọn sinh mật khẩu chủ | bàn giao cho chủ credential ban đầu |
| 04 | ops | thấy bản xem trước cập nhật trực tiếp những gì sẽ được tạo | soát lại trước khi hoàn tất |
| 05 | ops | mọi thứ được tạo cùng nhau hoặc không gì cả | không bao giờ kẹt với một client làm dở |
| 06 | ops | được đưa tới merchant mới khi xong | cấu hình nó ngay |
5. Yêu cầu chức năng
| # | Yêu cầu | Trạng thái | URD ref |
|---|---|---|---|
FR-001 | Phần Organizer - 6 trường, kèm quy tắc theo từng trường. • Bắt buộc: Tên organizer (song ngữ VI/EN) · Ngành (F&B · Bán lẻ · Vé - khóa chọn, sắp ra mắt · Khác) · Loại hình (danh mục loại hình kinh doanh, hiện: Hộ kinh doanh). • Tùy chọn: Mã số thuế (văn bản tự do) · Logo (ảnh tải lên). • Nhân viên phụ trách: chỉ đọc, tự điền theo người đang đăng nhập. | ✅ | URD-BOP-001 · URD-ORG-001 |
FR-002 | Phần Chủ - tài khoản chủ đầu tiên của client, 6 trường đều bắt buộc. • Họ, Tên: hai trường riêng. • Username: duy nhất toàn hệ thống - trùng thì hoàn tất bị từ chối, báo lỗi nêu đích danh username. • Số điện thoại, Email: mỗi trường là một danh sách, thêm được nhiều mục; mỗi mục phải đúng định dạng. • Mật khẩu: kèm nút sinh mật khẩu tạm điền thẳng vào trường; ops copy để bàn giao. | ✅ | URD-BOP-001 · URD-ACC-001 |
FR-003 | Phần Merchant - đúng 2 trường, cả hai bắt buộc. • Tên merchant (song ngữ VI/EN). • Địa chỉ. | ✅ | URD-MER-001 |
FR-004 | Phần Gói - danh sách gói dịch vụ dạng thẻ, chọn đúng một, bắt buộc. • Chọn xong hiện khối chi tiết của gói. • Mã hợp đồng: chỉ bắt buộc khi gói được chọn yêu cầu hợp đồng; định dạng chỉ gồm chữ, số, và gạch nối (-), tối đa 256 ký tự. • Sai định dạng, hoặc thiếu khi bắt buộc, báo lỗi trên trường và chặn hoàn tất. | ✅ | URD-BOP-002 |
FR-005 | Prefill từ một inquiry khi luồng bắt đầu từ đó. • Tên doanh nghiệp của lead gieo vào tên organizer và tên merchant. • Họ, tên, điện thoại, email của lead gieo vào phần Chủ. • Loại hình của lead chỉ được nhận khi khớp một giá trị hợp lệ trong danh mục, không khớp thì dùng mặc định. • Mọi giá trị prefill đều sửa được trước khi hoàn tất. | ✅ | URD-BOP-001 |
FR-006 | Thẻ xem trước cố định bên cạnh form, cập nhật tức thời theo từng thay đổi. • Hiện tên organizer + logo, thông tin chủ (họ tên, username, điện thoại, email), merchant (tên, địa chỉ), và tóm tắt gói đã chọn. • Ops soát toàn bộ những gì sẽ được tạo mà không rời màn. | ✅ | URD-BOP-001 |
FR-007 | Hoàn tất tạo organizer, merchant trụ sở, chủ, merchant, và license trong một thao tác nguyên tử - lỗi ở bất kỳ đâu thì không entity nào được tạo. • An toàn khi bấm lại: hoàn tất lại sau lỗi mạng với cùng dữ liệu không tạo trùng client, logo đã tải lên không bị tải lại. • Khi inquiry là nguồn, kết quả được gắn ngược về inquiry đó. • Thành công thì thông báo và mở thẳng tab Thông tin chung của merchant trụ sở mới. • Rời màn khi còn thay đổi chưa lưu thì cảnh báo. | ✅ | URD-MER-001 · URD-MER-017 |
5.1 Tiêu chí nghiệm thu
- Bỏ trống bất kỳ trường bắt buộc nào (tên organizer, ngành, loại hình, họ, tên, username, điện thoại, email, mật khẩu, tên merchant, địa chỉ, gói) thì hoàn tất bị chặn và trường đó báo lỗi.
- Ngành "Vé" hiển thị nhưng khóa chọn (sắp ra mắt).
- Trường "Nhân viên phụ trách" hiển thị đúng tên người đang đăng nhập và không sửa được.
- Thêm được nhiều số điện thoại / nhiều email cho chủ; số điện thoại sai định dạng hoặc email sai định dạng báo lỗi trên đúng dòng đó.
- Bấm nút sinh mật khẩu thì trường mật khẩu được điền một mật khẩu tạm.
- Chọn gói yêu cầu hợp đồng mà bỏ trống mã hợp đồng thì báo lỗi; nhập mã có ký tự ngoài chữ/số/gạch nối hoặc dài quá 256 ký tự thì báo lỗi; gói không yêu cầu hợp đồng thì mã hợp đồng bỏ trống được.
- Vào luồng từ một inquiry: tên doanh nghiệp, họ/tên, điện thoại, email của lead đã điền sẵn; loại hình lạ (không khớp danh mục) không được nhận mà rơi về mặc định.
- Thẻ xem trước đổi ngay khi gõ vào bất kỳ trường nào nó hiển thị.
- Hoàn tất thành công tạo đủ 5 thứ: organizer, merchant trụ sở, tài khoản chủ, merchant, license - đăng nhập được bằng tài khoản chủ vừa tạo.
- Hoàn tất thất bại (ví dụ trùng username) thì không entity nào tồn tại sau đó; báo lỗi nêu đích danh trường trùng.
- Bấm hoàn tất lại sau lỗi mạng với cùng dữ liệu không tạo client thứ hai; logo không bị upload lần hai.
- Hoàn tất xong màn chuyển thẳng tới tab Thông tin chung của merchant trụ sở mới.
6. Yêu cầu phi chức năng
| Khía cạnh | Yêu cầu |
|---|---|
| Nguyên tử | Cả client được tạo trong một thao tác tất-cả-hoặc-không-gì; lỗi thì không để lại gì |
| An toàn khi bấm lại | Gửi lại cùng dữ liệu sau lỗi mạng không tạo trùng; logo đã tải không tải lại |
| Phân quyền | Onboarding gác cho vai trò ops |
| An toàn credential | Server chỉ lưu mật khẩu dạng băm; mật khẩu tạm chỉ thấy được trong phiên nhập - sau hoàn tất không xem lại được |
| Duy nhất | Username của chủ duy nhất toàn hệ thống; slug của merchant duy nhất trong organization |
| i18n | Nhãn song ngữ (EN/VI) |
7. UX & Luồng
Ops onboard một client như thế nào:
Các phần trên màn:
Màn nằm trong mục "Khách hàng & Merchant" của Back Office, vào từ danh sách inquiry hoặc trực tiếp. Bốn phần xếp theo thứ tự trên một màn, thẻ xem trước ghim bên cạnh.
8. Dữ liệu & Miền nghiệp vụ
| Khái niệm | Vai trò trong luồng này |
|---|---|
| Organizer | Cha thương hiệu được tạo đầu tiên |
| Merchant (trụ sở) | Đơn vị bán hàng pháp lý tạo dưới organizer, đánh dấu là trụ sở |
| Tài khoản chủ | User đầu tiên, với định danh đăng nhập (username, điện thoại, email) và mật khẩu ban đầu |
| Merchant | Merchant vật lý đầu tiên bắt trong onboarding |
| Gói dịch vụ / license | Gói chọn cho client, phát hành thành license |
| Inquiry | Lead tùy chọn mà luồng prefill từ đó và gắn kết quả ngược về |
Chỉ ở mức khái niệm - onboarding tạo các thứ này cùng nhau như một aggregate; mô hình dữ liệu nằm ở tài liệu developer.
9. Phụ thuộc & Giả định
Phụ thuộc vào
| # | Feature | Phụ thuộc điều gì |
|---|---|---|
| 01 | Organizer & merchant (PRD-ORG-001) | onboarding tạo organizer + merchant trụ sở. |
| 02 | Licensing | gói dịch vụ / license gắn ở phần Gói (Licensing). |
| 03 | Inquiry | lead tùy chọn prefill cho luồng (CRM inquiry). |
| 04 | Tài khoản người dùng | tài khoản chủ và các định danh của nó. |
| 05 | Mẫu danh mục theo ngành & nhóm thuế | phần URD-BOP-002 tương ứng nằm ở PRD khác: Danh mục bán hàng, Kênh bán hàng, và BO Tax Groups. |
Giả định
| # | Giả định | Sai thì sao |
|---|---|---|
| 01 | Ops đã đăng nhập với vai trò có quyền onboard. | Không có quyền thì màn onboarding bị chặn theo phân quyền, ops không dựng được client. |
| 02 | Có gói dịch vụ để chọn; một số gói yêu cầu mã hợp đồng. | Phần Gói là trường bắt buộc (FR-004); không có gói nào để chọn thì trường này không điền được, và hoàn tất bị chặn như mọi trường bắt buộc khác. |
10. Kế hoạch phát hành & Tiêu chí
| Khía cạnh | Kế hoạch |
|---|---|
| Phase | P1 - luồng onboarding trong Back Office |
| Rollout | User ops; không feature flag |
| Migration | Không - nó tạo client mới |
| Tiêu chí ra mắt | Toàn bộ Tiêu chí nghiệm thu ở §5.1 đạt |
| Theo dõi | Tỷ lệ hoàn tất onboarding; tỷ lệ lỗi/rollback |
Tham chiếu
- URD: Commerce -
BOP(Backoffice Portal) ·ORG·MER - Liên quan: PRD-MER-001 - Quản lý Merchant · PRD-ORG-001 - Organizer & merchant
- Module: Commerce - URD · Lộ trình: Phase 2 - Theo tháng
- Developer: @nx/commerce
Rủi ro & Câu hỏi mở
| # | Rủi ro / câu hỏi | Giảm thiểu / trạng thái |
|---|---|---|
| 01 | Client làm dở nếu một phần lỗi | Hoàn tất là nguyên tử - mọi entity tạo cùng nhau hoặc không gì cả (FR-007) |
| 02 | Bấm hoàn tất hai lần / retry sau lỗi mạng | Gửi lại cùng dữ liệu không tạo trùng; logo không upload lại (FR-007) |
| 03 | Bàn giao mật khẩu ban đầu của chủ | Mật khẩu tạm chỉ thấy trong phiên nhập; server chỉ lưu dạng băm (FR-002) |
| 04 | Gói yêu cầu hợp đồng | Mã hợp đồng bắt buộc có điều kiện + kiểm tra định dạng (chữ/số/gạch nối, ≤256 ký tự) trước khi hoàn tất (FR-004) |
| 05 | Trùng username hoặc slug | Bắt buộc duy nhất; báo lỗi nêu đích danh trường bị trùng (FR-002) |
Câu hỏi thường gặp
| # | Câu hỏi | Trả lời |
|---|---|---|
| 01 | Có giống quản lý một merchant không? | Không - cái này dựng một client mới. Sửa merchant về sau là Quản lý Merchant. |
| 02 | Nếu client đến từ một inquiry? | Luồng bắt đầu từ inquiry đó và prefill thông tin doanh nghiệp và liên hệ; kết quả onboard được gắn ngược về inquiry. |
| 03 | Cuối cùng tạo ra những gì? | Organizer, merchant trụ sở, tài khoản chủ, merchant đầu tiên, và license - cùng nhau. |
| 04 | Chủ tự onboard không? | PRD này lo onboarding do ops chạy trong back office; tự thiết lập phía chủ là một luồng riêng, phía client. |