14 KiB
14 KiB
section, title, status, version, reviewer_notes
| section | title | status | version | reviewer_notes |
|---|---|---|---|---|
| 01 | Tổng quan dự án | approved | 1 |
1. Tổng quan dự án (System Overview)
1.1 Mục tiêu & Phạm vi
Mục tiêu
Xây dựng một sàn thương mại điện tử marketplace đa người bán (multi-vendor B2C/B2B2C), quy mô lớn, cho phép:
- Khách hàng (có tài khoản hoặc khách vãng lai) tìm kiếm, mua sắm sản phẩm từ nhiều người bán khác nhau trong cùng một trải nghiệm mua hàng thống nhất.
- Người bán thứ ba (Seller/Vendor) tự đăng ký, được xác minh (KYC), tự quản lý sản phẩm/tồn kho/đơn hàng của mình và nhận thanh toán (payout) định kỳ từ sàn.
- Sàn (Platform) thu hoa hồng (commission) trên mỗi giao dịch thành công theo bảng cấu hình theo ngành hàng, đồng thời quản trị chất lượng seller, catalog toàn sàn, khuyến mãi và xử lý tranh chấp.
Bài toán cốt lõi cần giải quyết: kết nối nhiều người bán với người mua trên một nền tảng dùng chung, xử lý được khối lượng giao dịch lớn (hàng trăm nghìn SKU, hàng trăm nghìn–hàng triệu user, cao điểm hàng nghìn–chục nghìn concurrent users mùa flash sale), đảm bảo dòng tiền minh bạch giữa khách hàng – sàn – seller (thanh toán, hoa hồng, payout, hoàn tiền/đổi trả).
Phạm vi trong MVP (In-scope)
- Danh mục & tìm kiếm sản phẩm đa người bán (catalog, filter, search).
- Giỏ hàng đa seller trong cùng một đơn hàng, checkout, tách đơn theo seller.
- Thanh toán: VNPay, Momo, COD (thu tiền mặt khi giao hàng).
- Quản lý đơn hàng: tạo, theo dõi trạng thái, huỷ, đổi trả.
- Tài khoản khách hàng: đăng ký/đăng nhập (email/password + tuỳ chọn Google/Facebook), địa chỉ giao hàng, lịch sử đơn hàng, wishlist.
- Seller onboarding & KYC thủ công (upload giấy phép kinh doanh/CMND, admin duyệt).
- Quản trị sản phẩm & tồn kho: seller tự quản lý, admin giám sát toàn sàn.
- Cấu hình & tính hoa hồng (commission) theo ngành hàng (category), admin chỉnh được.
- Payout cho seller: định kỳ hàng tuần, qua chuyển khoản ngân hàng, có kỳ giữ tiền (hold) sau giao hàng thành công.
- Khuyến mãi/mã giảm giá cơ bản.
- Đánh giá & nhận xét sản phẩm.
- Chương trình loyalty/điểm thưởng và hạng thành viên (Bạc/Vàng/Kim cương).
- Thông báo email/SMS xác nhận đơn hàng.
- Đa ngôn ngữ: Tiếng Việt (mặc định), Tiếng Anh, Tiếng Trung, Tiếng Hàn, Tiếng Nhật (VI/EN/ZH/KO/JA).
- Đa tiền tệ hiển thị: giao dịch bằng VND, hiển thị quy đổi tham khảo sang các tiền tệ khác (không giao dịch trực tiếp bằng ngoại tệ).
- Tích hợp vận chuyển: GHN, GHTK.
- Quản trị vận hành: xử lý tồn kho, đóng gói, giao hàng (Ops/Warehouse); xử lý khiếu nại/tranh chấp giữa khách hàng và seller (CSR).
- Nền tảng client: web responsive.
Ngoài phạm vi MVP (Out-of-scope — hoãn sang giai đoạn sau)
- Affiliate marketing.
- Subscription / bán hàng định kỳ.
- Ứng dụng mobile app native (phase 1 chỉ web responsive).
- Hoá đơn điện tử tự động cho seller.
- Phân biệt commission theo seller tier (MVP chỉ phân biệt theo ngành hàng).
- SSO/IdP doanh nghiệp (không có khách hàng B2B enterprise ở MVP).
1.2 Đối tượng sử dụng
| Nhóm người dùng | Mô tả | Cấp phân quyền chính |
|---|---|---|
| Khách vãng lai (Guest) | Chưa có tài khoản | Duyệt sản phẩm, tìm kiếm, thêm giỏ hàng, checkout không cần đăng nhập (guest checkout). Không truy cập lịch sử đơn hàng, wishlist, loyalty. |
| Khách hàng đã đăng ký (Customer) | Người mua có tài khoản | Toàn quyền trên tài khoản cá nhân: quản lý hồ sơ/địa chỉ, lịch sử đơn hàng, wishlist, điểm thưởng/hạng thành viên, viết đánh giá, khiếu nại/yêu cầu đổi trả đơn của chính mình. |
| Người bán (Seller/Vendor) | Bên thứ ba bán hàng trên sàn, đã qua KYC | Quản lý catalog sản phẩm và tồn kho của riêng mình, xử lý đơn hàng thuộc gian hàng của mình, xem báo cáo doanh thu/hoa hồng/payout của mình. Không truy cập dữ liệu seller khác hoặc cấu hình toàn sàn. Khuyến khích bật MFA. |
| Quản trị viên sàn (Platform Admin) | Vận hành và quản trị toàn sàn | Toàn quyền: duyệt/khoá seller (KYC), quản trị catalog toàn sàn, cấu hình bảng hoa hồng theo ngành hàng, cấu hình khuyến mãi, giám sát payout, xử lý escalation tranh chấp. Bắt buộc MFA. |
| Nhân viên vận hành/kho (Ops/Warehouse staff) | Thuộc sàn hoặc thuộc seller | Xử lý tồn kho, đóng gói, cập nhật trạng thái giao hàng; phối hợp với đơn vị vận chuyển (GHN/GHTK). Phạm vi giới hạn theo đơn hàng/gian hàng được phân công. |
| Nhân viên chăm sóc khách hàng (CSR) | Bộ phận hỗ trợ | Xử lý khiếu nại, yêu cầu đổi trả, tranh chấp giữa khách hàng và seller; có quyền xem (read) thông tin đơn hàng liên quan để hỗ trợ, không có quyền chỉnh sửa cấu hình hệ thống. |
Ghi chú phân quyền chi tiết hơn (RBAC/ma trận quyền theo chức năng) sẽ được đặc tả trong mục 8 (Thiết kế bảo mật) — mục này chỉ mô tả ở mức nghiệp vụ.
1.3 Thuật ngữ (Glossary)
| Thuật ngữ (EN, PascalCase) | Nghĩa tiếng Việt |
|---|---|
| Guest | Khách vãng lai, chưa đăng ký tài khoản |
| Customer | Khách hàng đã đăng ký tài khoản |
| Seller (Vendor) | Người bán thứ ba đăng ký kinh doanh trên sàn |
| PlatformAdmin | Quản trị viên sàn |
| OpsStaff | Nhân viên vận hành/kho |
| CustomerServiceRep (CSR) | Nhân viên chăm sóc khách hàng |
| Product | Sản phẩm do seller đăng bán |
| ProductVariant (SKU) | Biến thể/đơn vị tồn kho cụ thể của một sản phẩm (VD: theo size, màu) |
| Category | Ngành hàng/danh mục sản phẩm, dùng làm cơ sở cấu hình hoa hồng |
| Cart | Giỏ hàng của khách hàng, có thể chứa sản phẩm từ nhiều seller |
| CartItem | Một dòng sản phẩm trong giỏ hàng |
| Order | Đơn hàng của khách hàng; một Order có thể tách thành nhiều Order con theo seller |
| OrderItem | Một dòng sản phẩm trong đơn hàng |
| Payment | Giao dịch thanh toán của khách hàng (VNPay/Momo/COD) |
| Shipment | Lô hàng giao cho khách, gắn với đơn vị vận chuyển (GHN/GHTK) |
| ReturnRequest | Yêu cầu đổi trả hàng của khách hàng |
| Dispute | Tranh chấp giữa khách hàng và seller cần CSR/Admin xử lý |
| Promotion (Coupon) | Chương trình khuyến mãi/mã giảm giá |
| Review | Đánh giá/nhận xét sản phẩm của khách hàng |
| Notification | Thông báo gửi cho người dùng (email/SMS) |
| CommissionRule | Quy tắc/bảng cấu hình hoa hồng theo ngành hàng |
| Payout | Khoản chi trả định kỳ cho seller sau khi trừ hoa hồng |
| KYCDocument | Hồ sơ định danh/giấy tờ pháp lý seller nộp để xác minh (KYC) |
| LoyaltyAccount | Tài khoản điểm thưởng của khách hàng |
| LoyaltyTransaction | Giao dịch tích/đổi điểm thưởng |
| MembershipTier | Hạng thành viên (Bạc/Vàng/Kim cương) theo tổng chi tiêu 12 tháng |
| Wishlist | Danh sách sản phẩm yêu thích của khách hàng |
| Currency | Đơn vị tiền tệ hiển thị (giao dịch chính = VND) |
| Language | Ngôn ngữ giao diện (VI/EN/ZH/KO/JA) |
1.4 Giả định (Assumptions)
Các giả định dưới đây được chốt từ docs/00-project-brief.md (mục 5 — Giả định đã chốt), kèm rủi ro tương ứng. Đây là các điều kiện được xem là đúng khi thiết kế các mục tiếp theo; nếu thực tế khác đi, cần rà soát lại thiết kế liên quan.
- Nền tảng client MVP = web responsive, mobile app = phase 2. Rủi ro: nếu phần lớn traffic mục tiêu thực tế đến từ mobile app native, trải nghiệm và tỷ lệ chuyển đổi MVP có thể thấp hơn kỳ vọng; cần bổ sung roadmap mobile sớm hơn nếu dữ liệu thị trường cho thấy nhu cầu cao.
- Cổng thanh toán = VNPay + Momo + COD; vận chuyển = GHN + GHTK. Rủi ro: nếu doanh nghiệp đã có hợp đồng/ưu đãi với đối tác khác, cần thay đổi tích hợp và có thể phát sinh chi phí/thời gian điều chỉnh thiết kế.
- Kỳ giữ tiền (payout hold) = 3-7 ngày sau giao hàng thành công. Rủi ro: nếu chính sách đổi trả thực tế dài hơn (VD. 15-30 ngày cho một số ngành hàng), dòng tiền payout và mô hình đối soát (reconciliation) cần điều chỉnh lại; có thể phát sinh tranh chấp với seller nếu thời gian hold không rõ ràng trong hợp đồng seller.
- Tuân thủ pháp lý = áp dụng đầy đủ NĐ52/85 (thông báo website TMĐT), NĐ13/2023 (bảo vệ dữ liệu cá nhân), PCI-DSS scope giảm qua cổng thanh toán bên thứ ba; hoá đơn điện tử cho seller hoãn phase 2. Rủi ro: nếu doanh nghiệp thực tế cần cấp phép "Sàn giao dịch TMĐT" đầy đủ (không chỉ thông báo) do quy mô/mô hình kinh doanh cụ thể, cần rà soát pháp lý bổ sung trước khi go-live; thiếu hoá đơn điện tử cho seller ở MVP có thể gây khó khăn vận hành kế toán cho seller.
- Chương trình loyalty: 1 điểm/10.000đ, 100 điểm = 10.000đ giảm giá, 3 hạng Bạc/Vàng/Kim cương theo chi tiêu 12 tháng gần nhất. Rủi ro: nếu chiến lược kinh doanh thực tế muốn cơ chế tích/đổi điểm khác (VD. theo ngành hàng, theo chương trình đối tác), cần điều chỉnh mô hình dữ liệu loyalty và luồng tính điểm.
- Độ trễ mục tiêu <2s (catalog/search), <3s (checkout); uptime mục tiêu 99.9%. Rủi ro: nếu SLA hợp đồng với đối tác/khách hàng doanh nghiệp yêu cầu cao hơn (VD. 99.95%+), cần đầu tư thêm cho multi-AZ/multi-region và có thể tăng chi phí hạ tầng đáng kể.
- Tech stack không bắt buộc, kiến trúc sư tự đề xuất theo best practice cho quy mô lớn; cloud = AWS; dự án greenfield, không có hệ thống cũ cần tích hợp/migrate; ngân sách/timeline chưa xác định (giả định theo lộ trình MVP tiêu chuẩn ~9-12 tháng). Rủi ro: nếu ngân sách/timeline thực tế bị giới hạn chặt hơn giả định, phạm vi MVP (đặc biệt các hạng mục mở rộng như 5 ngôn ngữ, loyalty, kiến trúc scale-out ngay từ đầu) có thể cần cắt giảm hoặc chia nhỏ thành nhiều release.
- Xác thực/bảo mật: không có SSO doanh nghiệp; Customer dùng email/password + tuỳ chọn Google/Facebook OAuth; Admin bắt buộc MFA, Seller khuyến khích MFA. Rủi ro: nếu về sau có đối tác B2B lớn yêu cầu tích hợp SSO/IdP riêng, cần bổ sung thiết kế xác thực liên kết (federation) sau này.
- UI/Brand: không có brand guideline cố định, dùng design system chuẩn (VD. Material/Ant Design) làm nền tảng; đa ngôn ngữ quản lý qua i18n framework cho 5 ngôn ngữ (VI/EN/ZH/KO/JA). Rủi ro: nếu doanh nghiệp có bộ nhận diện thương hiệu riêng cần tuân thủ nghiêm ngặt, giai đoạn thiết kế UI cần thời gian điều chỉnh thêm; bản dịch 5 ngôn ngữ cần quy trình quản lý nội dung đa ngôn ngữ (translation workflow) chưa được đặc tả chi tiết.
- Vận hành: môi trường Dev/Staging/Production trên AWS; đội ops trực theo ca; hỗ trợ giờ hành chính + escalation 24/7 cho sự cố nghiêm trọng. Rủi ro: nếu tổ chức chưa có đội ops 24/7 sẵn sàng, cần lên kế hoạch tuyển dụng/thuê ngoài dịch vụ vận hành trước go-live.
1.5 Ràng buộc (Constraints)
- Pháp lý: Phải tuân thủ Nghị định 52/2013 và 85/2021 (thông báo website TMĐT dạng sàn giao dịch với Bộ Công Thương), Nghị định 13/2023 (bảo vệ dữ liệu cá nhân) do hệ thống lưu trữ PII của khách hàng và seller (bao gồm giấy tờ KYC). Phạm vi PCI-DSS được thu hẹp vì không lưu trữ dữ liệu thẻ thanh toán (giao cho VNPay/Momo xử lý).
- Công nghệ/hạ tầng: Triển khai trên AWS; không có ràng buộc tech stack cụ thể nào khác — kiến trúc sư tự đề xuất theo best practice phù hợp quy mô lớn (mục 3 sẽ quyết định).
- Tích hợp bắt buộc: Cổng thanh toán VNPay, Momo; đơn vị vận chuyển GHN, GHTK; chuyển khoản ngân hàng cho payout seller.
- Quy mô: Kiến trúc phải hỗ trợ hàng trăm nghìn SKU trở lên, hàng trăm nghìn đến hàng triệu người dùng đăng ký, cao điểm hàng nghìn đến hàng chục nghìn concurrent users (mùa flash sale) ngay từ thiết kế ban đầu.
- Ngân sách & thời gian: Chưa được xác định chính thức bởi chủ dự án; giả định theo lộ trình MVP tiêu chuẩn (xem Giả định #7). Cần chủ dự án xác nhận lại trước khi lập kế hoạch triển khai chi tiết.
- Không có hệ thống cũ: Dự án hoàn toàn mới (greenfield), không có ERP/kho/CRM cũ cần tích hợp hoặc di trú dữ liệu.