sys-analysis-design/docs/sections/07-giao-dien.md

section, title, status, version, reviewer_notes

section	title	status	version	reviewer_notes
07	Thiết kế giao diện	approved	1

7. Thiết kế giao diện (UI/UX Design)

7.0 Nguyên tắc & phạm vi thiết kế

• Nền tảng: chỉ thiết kế cho web responsive (desktop, tablet, mobile-web), theo profile dự án (platforms: ["web"]). Không thiết kế ứng dụng mobile app native (out-of-scope MVP, xem mục 1.1).
• Không có brand guideline cố định (giả định #9, mục 1.4): tài liệu này không quy định màu sắc/typography cụ thể, chỉ mô tả cấu trúc bố cục, thành phần (component) và hành vi. Đội phát triển áp dụng một design system chuẩn (VD. Material Design hoặc Ant Design — xem NFR-07) làm nền tảng khi triển khai UI thật.
• Đa ngôn ngữ (FR-15/NFR-06): mọi màn hình có text hiển thị đều phải dùng khóa i18n (không hard-code chuỗi), hỗ trợ VI (mặc định)/EN/ZH/KO/JA qua component LanguageSwitcher đặt cố định ở header. Riêng ZH/KO/JA cần rà soát độ dài chuỗi dịch có thể dài hơn tiếng Việt — layout cần co giãn được (không fix-width cho label).
• Đa tiền tệ (FR-16/NFR-06): mọi nơi hiển thị giá đều hiển thị giá giao dịch chính bằng VND kèm giá quy đổi tham khảo (secondary display, không phải giá giao dịch) qua component CurrencyToggle/PriceDisplay.
• Phân quyền: tài liệu này không thiết kế lại RBAC — mỗi màn hình chỉ tham chiếu nhóm người dùng đã định nghĩa ở mục 1.2 (Guest, Customer, Seller, PlatformAdmin, OpsStaff, CSR). Chi tiết ma trận quyền thuộc mục 8.
• Quy ước mã màn hình: SCR-xx, nhóm theo persona.
• Quy ước trạng thái màn hình: mỗi màn hình chính mô tả tối thiểu 3 trạng thái: loading (khung xương/skeleton hoặc spinner), empty (không có dữ liệu), error (lỗi tải dữ liệu/lỗi nghiệp vụ) — theo yêu cầu NFR-01 (phản hồi nhanh, cần loading state rõ ràng khi tải đỉnh).

---

7.1 Wireframe & Mockup (mô tả dạng văn bản)

7.1.1 Nhóm Khách vãng lai & Khách hàng (Guest / Customer)

SCR-01 — Trang chủ & Danh mục sản phẩm

• Mục đích: điểm vào chính, giới thiệu ngành hàng, khuyến mãi, sản phẩm nổi bật; cho phép chuyển ngôn ngữ/tiền tệ.
• Persona/Role: Guest, Customer.
• FR phục vụ: FR-04 (danh mục & tìm kiếm), FR-15 (đa ngôn ngữ), FR-16 (đa tiền tệ).
• Bố cục:
  • Header (cố định): logo sàn; thanh tìm kiếm (autocomplete); LanguageSwitcher (FR-15); CurrencyToggle (FR-16, hiển thị tham khảo); icon giỏ hàng (badge số lượng); icon tài khoản/đăng nhập.
  • Section 1: banner khuyến mãi/carousel.
  • Section 2: điều hướng ngành hàng (category nav, dạng menu/mega-menu).
  • Section 3: lưới sản phẩm nổi bật — ProductCard (ảnh, tên, giá VND + giá quy đổi tham khảo, rating trung bình, tên/logo seller, badge "Ngành hàng").
  • Footer: thông tin sàn, chính sách đổi trả, liên kết ngôn ngữ, thông tin tuân thủ (thông báo Bộ Công Thương — NFR-05).
• Trạng thái: loading = skeleton lưới sản phẩm/banner; empty = ẩn section nếu không có sản phẩm nổi bật/khuyến mãi; error = banner lỗi "Không tải được dữ liệu, thử lại" + nút retry.
• Validation chính: ô tìm kiếm yêu cầu tối thiểu 1 ký tự trước khi gợi ý; không cho submit tìm kiếm rỗng.

SCR-02 — Kết quả tìm kiếm & Bộ lọc

• Mục đích: hiển thị kết quả tìm kiếm/duyệt theo ngành hàng với bộ lọc đa chiều.
• Persona/Role: Guest, Customer.
• FR phục vụ: FR-04.
• Bố cục:
  • Header: kế thừa SCR-01; thanh breadcrumb (Trang chủ > Ngành hàng > Từ khoá).
  • Sidebar trái (desktop) / bottom-sheet (mobile): bộ lọc — ngành hàng (category), khoảng giá, seller, rating, tình trạng còn hàng.
  • Vùng chính: thanh sắp xếp (giá tăng/giảm, mới nhất, bán chạy), lưới/danh sách ProductCard, phân trang hoặc infinite-scroll.
• Trạng thái: loading = skeleton lưới; empty = "Không tìm thấy sản phẩm phù hợp" + gợi ý bỏ bớt bộ lọc; error = thông báo lỗi tìm kiếm + retry.
• Validation chính: khoảng giá min ≤ max (nếu nhập tay); tối thiểu 1 bộ lọc category hợp lệ khi áp dụng.

SCR-03 — Chi tiết sản phẩm

• Mục đích: cung cấp đầy đủ thông tin sản phẩm để ra quyết định mua, xem đánh giá.
• Persona/Role: Guest, Customer.
• FR phục vụ: FR-04, FR-11 (hiển thị đánh giá), FR-16 (giá quy đổi).
• Bố cục:
  • Section 1: gallery ảnh/video sản phẩm; chọn biến thể (SKU: size/màu — cập nhật tồn kho/giá theo lựa chọn).
  • Section 2: tên sản phẩm, giá VND + giá quy đổi tham khảo, rating tổng hợp + số lượt đánh giá, thông tin seller (link tới gian hàng), nút "Thêm vào giỏ" / "Mua ngay" / "Thêm vào Wishlist" (FR-10).
  • Section 3: mô tả chi tiết, thông số kỹ thuật.
  • Section 4: danh sách đánh giá & rating (tham chiếu FR-11), phân trang.
  • Section 5: sản phẩm liên quan/gợi ý.
• Trạng thái: loading = skeleton toàn trang; empty = ẩn section đánh giá nếu chưa có review ("Chưa có đánh giá nào"); error = "Sản phẩm không tồn tại/đã bị gỡ" (liên quan FR-24 catalog moderation) + link quay lại danh mục.
• Validation chính: không cho thêm giỏ hàng nếu SKU hết hàng (nút chuyển trạng thái "Hết hàng", disabled); số lượng đặt mua ≤ tồn kho hiển thị.

SCR-04 — Giỏ hàng

• Mục đích: quản lý các sản phẩm đã chọn từ nhiều seller trước khi checkout.
• Persona/Role: Guest, Customer.
• FR phục vụ: FR-05.
• Bố cục:
  • Header: tiêu đề "Giỏ hàng của bạn" + số lượng sản phẩm.
  • Vùng chính: danh sách nhóm theo seller (mỗi nhóm = 1 seller, hiển thị tên gian hàng), mỗi dòng CartItem (ảnh, tên, biến thể, đơn giá, bộ đếm số lượng, nút xoá), checkbox chọn/bỏ chọn từng dòng hoặc cả nhóm.
  • Sidebar/footer tổng kết: tổng số lượng đã chọn, tạm tính (subtotal theo VND), nút "Tiến hành Checkout".
• Trạng thái: loading = skeleton danh sách; empty = "Giỏ hàng trống" + nút "Tiếp tục mua sắm"; error = cảnh báo dòng sản phẩm hết hàng/giá thay đổi (badge "Sản phẩm đã hết hàng" hoặc "Giá đã thay đổi", chặn không cho tick chọn).
• Validation chính: số lượng ≥ 1 và ≤ tồn kho hiện tại; phải chọn ít nhất 1 sản phẩm để bật nút Checkout.

SCR-05 — Checkout (địa chỉ, vận chuyển, tách đơn theo seller)

• Mục đích: thu thập địa chỉ giao hàng, hiển thị đơn hàng đã tách theo từng seller, áp mã giảm giá/điểm thưởng trước khi thanh toán.
• Persona/Role: Guest (guest checkout), Customer.
• FR phục vụ: FR-06 (tách đơn theo seller), FR-13 (áp coupon), FR-14 (dùng điểm thưởng).
• Bố cục:
  • Section 1: thông tin người nhận & địa chỉ giao hàng (chọn địa chỉ đã lưu — FR-03 — hoặc nhập mới; với Guest bắt buộc nhập đầy đủ).
  • Section 2: danh sách đơn con theo từng seller (mỗi khối = 1 seller, hiển thị sản phẩm, phí vận chuyển ước tính theo GHN/GHTK, thời gian giao dự kiến).
  • Section 3: ô nhập mã khuyến mãi/coupon (FR-13) — áp dụng theo toàn đơn hoặc theo từng seller tuỳ cấu hình; hiển thị số điểm thưởng khả dụng và tuỳ chọn quy đổi giảm giá (FR-14, chỉ hiện với Customer đã đăng nhập).
  • Section 4: tổng kết thanh toán (tạm tính, giảm giá, phí vận chuyển, tổng cộng theo VND).
  • CTA: nút "Tiếp tục đến thanh toán".
• Trạng thái: loading = tính lại phí vận chuyển/khuyến mãi khi thay đổi địa chỉ (spinner cục bộ); empty = không áp dụng (luôn có ít nhất 1 sản phẩm từ SCR-04); error = coupon không hợp lệ/hết hạn (thông báo inline), địa chỉ ngoài vùng phục vụ GHN/GHTK (thông báo + gợi ý địa chỉ khác).
• Validation chính: các trường địa chỉ bắt buộc (họ tên, số điện thoại định dạng VN, tỉnh/thành, địa chỉ chi tiết); mã coupon kiểm tra điều kiện áp dụng (giá trị đơn tối thiểu, ngành hàng) trước khi trừ tiền; điểm thưởng quy đổi không vượt quá số dư LoyaltyAccount.

SCR-06 — Thanh toán

• Mục đích: chọn phương thức thanh toán và hoàn tất giao dịch.
• Persona/Role: Guest, Customer.
• FR phục vụ: FR-07.
• Bố cục:
  • Section 1: chọn phương thức — VNPay, Momo, COD (radio group, mỗi lựa chọn có icon/mô tả).
  • Section 2 (nếu VNPay/Momo): chuyển hướng tới cổng thanh toán bên thứ ba (không thu thập/lưu thông tin thẻ tại hệ thống — giảm phạm vi PCI-DSS theo NFR-05).
  • Section 3: tóm tắt đơn hàng (read-only, tham chiếu từ SCR-05).
  • CTA: nút "Xác nhận thanh toán".
• Trạng thái: loading = trạng thái "Đang xử lý thanh toán..." (không cho thao tác khác, tránh double-submit); empty = không áp dụng; error = thanh toán thất bại/timeout từ cổng thanh toán → thông báo lý do + nút "Thử lại" hoặc "Chọn phương thức khác", đơn hàng giữ trạng thái "Chờ thanh toán".
• Validation chính: bắt buộc chọn 1 phương thức trước khi submit; chặn double-submit (disable nút sau khi bấm).

SCR-07 — Xác nhận đơn hàng thành công

• Mục đích: xác nhận đặt hàng thành công, cung cấp mã đơn hàng, kích hoạt thông báo.
• Persona/Role: Guest, Customer.
• FR phục vụ: FR-06, FR-12 (thông báo email/SMS xác nhận).
• Bố cục:
  • Thông điệp thành công + mã đơn hàng (hoặc danh sách mã đơn con theo từng seller nếu tách đơn).
  • Tóm tắt đơn hàng, phương thức thanh toán, địa chỉ giao hàng.
  • Ghi chú: "Email/SMS xác nhận đã được gửi tới [email/số điện thoại]" (FR-12).
  • CTA: "Theo dõi đơn hàng" (link tới SCR-10, chỉ khả dụng nếu Customer đã đăng nhập) / "Tiếp tục mua sắm".
• Trạng thái: loading = khi đang chờ webhook xác nhận thanh toán VNPay/Momo (trạng thái "Đang xác nhận thanh toán..."); error = thanh toán chưa được xác nhận sau timeout → hướng dẫn kiểm tra lại lịch sử đơn hàng hoặc liên hệ CSKH.
• Validation chính: không có form nhập liệu.

SCR-08 — Đăng ký / Đăng nhập Khách hàng

• Mục đích: tạo tài khoản hoặc đăng nhập bằng email/password hoặc mạng xã hội.
• Persona/Role: Guest → Customer.
• FR phục vụ: FR-01 (đăng ký/đăng nhập), FR-02 (social login).
• Bố cục:
  • Tab "Đăng nhập" / "Đăng ký".
  • Form đăng nhập: email, mật khẩu, link "Quên mật khẩu", nút đăng nhập.
  • Nút đăng nhập nhanh: "Đăng nhập với Google" / "Đăng nhập với Facebook" (FR-02).
  • Form đăng ký: họ tên, email, mật khẩu, xác nhận mật khẩu, checkbox đồng ý điều khoản.
• Trạng thái: loading = spinner trên nút submit; empty = không áp dụng; error = sai email/mật khẩu (thông báo chung, không tiết lộ email tồn tại hay không — chống dò tài khoản), email đã tồn tại khi đăng ký, lỗi OAuth (token hết hạn/bị từ chối quyền).
• Validation chính: email đúng định dạng; mật khẩu tối thiểu độ dài/độ phức tạp theo chính sách bảo mật (mục 8); xác nhận mật khẩu khớp; checkbox điều khoản bắt buộc tick.

SCR-09 — Hồ sơ cá nhân & Địa chỉ giao hàng

• Mục đích: quản lý thông tin cá nhân và danh sách địa chỉ giao hàng.
• Persona/Role: Customer.
• FR phục vụ: FR-03.
• Bố cục:
  • Tab "Thông tin cá nhân": họ tên, email (read-only hoặc yêu cầu xác thực lại khi đổi), số điện thoại, đổi mật khẩu.
  • Tab "Sổ địa chỉ": danh sách địa chỉ đã lưu (dạng card), đánh dấu "Địa chỉ mặc định", nút thêm/sửa/xoá.
  • Form thêm/sửa địa chỉ: modal/trang riêng — tên người nhận, số điện thoại, tỉnh/thành/quận/huyện/phường xã, địa chỉ chi tiết.
• Trạng thái: loading = skeleton danh sách địa chỉ; empty = "Chưa có địa chỉ nào" + CTA thêm mới; error = lỗi lưu thông tin (validation inline).
• Validation chính: số điện thoại đúng định dạng VN; không cho xoá địa chỉ đang là mặc định nếu chỉ còn 1 địa chỉ; tối thiểu 1 địa chỉ mặc định.

SCR-10 — Lịch sử đơn hàng & Chi tiết đơn

• Mục đích: theo dõi trạng thái, huỷ đơn, xem chi tiết từng đơn (tách theo seller).
• Persona/Role: Customer.
• FR phục vụ: FR-08.
• Bố cục:
  • Danh sách đơn hàng: filter theo trạng thái (Chờ xác nhận, Đang xử lý, Đang giao, Đã giao, Đã huỷ, Yêu cầu đổi trả), mỗi dòng hiển thị mã đơn, seller, tổng tiền, trạng thái, ngày đặt.
  • Trang chi tiết đơn: timeline trạng thái (progress stepper), danh sách sản phẩm, địa chỉ giao, phương thức thanh toán, nút "Huỷ đơn" (chỉ hiện khi đơn ở trạng thái cho phép), nút "Yêu cầu đổi trả/khiếu nại" (link SCR-11, chỉ hiện khi đơn đã giao), nút "Viết đánh giá" (link SCR-13, chỉ hiện khi đơn đã giao và sản phẩm chưa được đánh giá).
• Trạng thái: loading = skeleton danh sách/chi tiết; empty = "Bạn chưa có đơn hàng nào" + CTA mua sắm; error = lỗi tải chi tiết đơn + retry.
• Validation chính: nút "Huỷ đơn" bị disable/ẩn nếu đơn đã ở trạng thái "Đang giao"/"Đã giao" trở đi; xác nhận (dialog) trước khi huỷ đơn.

SCR-11 — Yêu cầu đổi trả & Khiếu nại

• Mục đích: khách hàng gửi yêu cầu đổi trả hoặc khiếu nại cho đơn đã giao.
• Persona/Role: Customer (khởi tạo); CSR (tiếp nhận, xem SCR-32).
• FR phục vụ: FR-09.
• Bố cục:
  • Form: chọn sản phẩm/đơn liên quan, lý do (dropdown: sai hàng, lỗi, không đúng mô tả...), mô tả chi tiết (textarea), upload ảnh/video minh chứng, chọn hình thức mong muốn (hoàn tiền/đổi hàng).
  • Sau khi gửi: hiển thị trạng thái yêu cầu (Đang chờ xử lý/Đã xử lý/Từ chối) + lịch sử trao đổi với CSR (thread dạng chat/comment).
• Trạng thái: loading = spinner khi submit/upload; empty = không áp dụng; error = ngoài thời hạn cho phép đổi trả (thông báo rõ chính sách + số ngày còn lại), upload file quá dung lượng/sai định dạng.
• Validation chính: bắt buộc chọn lý do và mô tả tối thiểu số ký tự; giới hạn dung lượng/định dạng file upload (ảnh JPG/PNG, video MP4, tối đa theo cấu hình hệ thống); chỉ cho gửi yêu cầu trong thời hạn chính sách đổi trả kể từ ngày giao thành công.

SCR-12 — Danh sách yêu thích (Wishlist)

• Mục đích: lưu sản phẩm quan tâm để mua sau.
• Persona/Role: Customer.
• FR phục vụ: FR-10.
• Bố cục: lưới ProductCard rút gọn (ảnh, tên, giá, trạng thái tồn kho), nút "Thêm vào giỏ hàng" trực tiếp từ wishlist, nút xoá khỏi danh sách.
• Trạng thái: loading = skeleton lưới; empty = "Danh sách yêu thích trống" + CTA duyệt sản phẩm; error = sản phẩm đã ngừng bán (badge "Không còn khả dụng", disable nút thêm giỏ hàng).
• Validation chính: không cho thêm giỏ hàng nếu sản phẩm hết hàng/ngừng bán.

SCR-13 — Viết đánh giá sản phẩm

• Mục đích: khách hàng đánh giá/rating sản phẩm đã mua và nhận hàng thành công.
• Persona/Role: Customer.
• FR phục vụ: FR-11.
• Bố cục: form — chọn số sao (1-5), textarea nhận xét, upload ảnh (tuỳ chọn), nút gửi; hiển thị lại thông tin sản phẩm/đơn hàng liên quan (read-only).
• Trạng thái: loading = spinner submit; error = đã đánh giá sản phẩm này rồi (chặn gửi trùng), đơn hàng chưa ở trạng thái "Đã giao" (ẩn nút viết đánh giá — xem SCR-10).
• Validation chính: bắt buộc chọn số sao; giới hạn độ dài nhận xét; mỗi OrderItem chỉ được đánh giá 1 lần.

SCR-14 — Điểm thưởng & Hạng thành viên

• Mục đích: xem số dư điểm, hạng thành viên hiện tại, lịch sử tích/đổi điểm.
• Persona/Role: Customer.
• FR phục vụ: FR-14.
• Bố cục:
  • Section 1: thẻ tổng quan — số điểm hiện có, hạng thành viên (Bạc/Vàng/Kim cương), thanh tiến trình tới hạng tiếp theo (dựa trên tổng chi tiêu 12 tháng gần nhất).
  • Section 2: bảng lịch sử LoyaltyTransaction (tích điểm từ đơn nào, đổi điểm giảm giá ở đơn nào, ngày).
  • Section 3: quy tắc chương trình (1 điểm/10.000đ, 100 điểm = 10.000đ).
• Trạng thái: loading = skeleton; empty = "Chưa có giao dịch điểm thưởng nào"; error = lỗi tải dữ liệu + retry.
• Validation chính: không có form nhập liệu (chỉ xem; đổi điểm thực hiện tại SCR-05 lúc checkout).

SCR-15 — Trung tâm thông báo

• Mục đích: xem lại lịch sử thông báo trong-app liên quan đơn hàng (bổ trợ cho email/SMS gửi ngoài hệ thống).
• Persona/Role: Customer (và tương tự cho Seller — xem SCR-17).
• FR phục vụ: FR-12.
• Bố cục: danh sách thông báo dạng timeline (xác nhận đơn hàng, cập nhật trạng thái giao hàng, kết quả đổi trả, khuyến mãi), mỗi item có icon loại, nội dung rút gọn, thời gian, trạng thái đã đọc/chưa đọc, click vào để tới màn hình liên quan (SCR-10, SCR-11...).
• Trạng thái: loading = skeleton danh sách; empty = "Không có thông báo nào"; error = lỗi tải + retry.
• Validation chính: không áp dụng (read-only).

Ghi chú traceability FR-12: yêu cầu gốc là gửi email/SMS xác nhận đơn hàng — đây là kênh ngoài giao diện web, không có "màn hình" riêng. SCR-15 (Trung tâm thông báo trong-app) là giả định bổ sung của thiết kế để tăng trải nghiệm, không thay thế kênh email/SMS. Xem openQuestions.

---

7.1.2 Nhóm Người bán (Seller)

SCR-16 — Đăng ký Seller & Upload hồ sơ KYC

• Mục đích: cho phép bên thứ ba đăng ký trở thành người bán và nộp hồ sơ xác minh.
• Persona/Role: Seller (ứng viên, chưa được duyệt).
• FR phục vụ: FR-17.
• Bố cục:
  • Bước 1 (wizard step 1): thông tin tài khoản — email, mật khẩu, tên gian hàng.
  • Bước 2: thông tin doanh nghiệp/cá nhân kinh doanh — tên, mã số thuế/CMND-CCCD, địa chỉ, ngành hàng dự kiến kinh doanh.
  • Bước 3: upload KYCDocument — giấy phép kinh doanh, CMND/CCCD (mặt trước/sau), có preview file đã upload.
  • Bước 4: xác nhận & gửi hồ sơ; hiển thị màn hình "Hồ sơ đang chờ duyệt".
• Trạng thái: loading = spinner khi upload file (progress bar); empty = không áp dụng; error = file upload sai định dạng/quá dung lượng, mã số thuế trùng với seller đã đăng ký (thông báo inline).
• Validation chính: định dạng file cho phép (PDF/JPG/PNG), giới hạn dung lượng; mã số thuế/CMND-CCCD đúng định dạng và không trùng lặp; các trường bắt buộc phải điền đủ trước khi chuyển bước tiếp theo (wizard chặn "Next" nếu bước hiện tại chưa hợp lệ).

SCR-17 — Seller Dashboard (Tổng quan)

• Mục đích: điểm vào chính của Seller sau đăng nhập, tổng hợp số liệu vận hành.
• Persona/Role: Seller (đã được duyệt KYC).
• FR phục vụ: FR-20.
• Bố cục:
  • Header: tên gian hàng, trạng thái tài khoản (Đang hoạt động/Tạm khoá), menu điều hướng (Sản phẩm, Đơn hàng, Báo cáo, Thông báo).
  • Section 1: thẻ số liệu nhanh — đơn hàng chờ xử lý, doanh thu tuần này, số dư payout sắp tới.
  • Section 2: biểu đồ doanh thu theo thời gian (tuần/tháng).
  • Section 3: danh sách đơn hàng cần chú ý (chờ xác nhận, sắp hết hạn xử lý).
• Trạng thái: loading = skeleton thẻ số liệu/biểu đồ; empty = "Chưa có dữ liệu bán hàng" (seller mới); error = lỗi tải báo cáo + retry.
• Validation chính: không áp dụng (dashboard read-only).

SCR-18 — Quản lý sản phẩm & Tồn kho (Seller)

• Mục đích: seller tự đăng bán sản phẩm, quản lý biến thể (SKU) và tồn kho.
• Persona/Role: Seller.
• FR phục vụ: FR-18.
• Bố cục:
  • Danh sách sản phẩm: bảng/lưới (ảnh, tên, ngành hàng, giá, tồn kho tổng, trạng thái hiển thị: Đang bán/Ẩn/Bị gỡ do vi phạm), filter theo ngành hàng/trạng thái, nút "Thêm sản phẩm".
  • Form thêm/sửa sản phẩm: thông tin cơ bản (tên, mô tả, ngành hàng — Category), upload ảnh/video, quản lý biến thể ProductVariant (bảng: thuộc tính biến thể, SKU code, giá bán, số lượng tồn kho).
  • Trạng thái "Bị gỡ do vi phạm" (liên quan FR-24, do Admin can thiệp) hiển thị lý do, không cho seller tự bật lại mà không chỉnh sửa theo yêu cầu.
• Trạng thái: loading = skeleton bảng sản phẩm; empty = "Chưa có sản phẩm nào" + CTA thêm mới; error = lỗi lưu (validation inline), xung đột SKU trùng.
• Validation chính: giá bán > 0; tồn kho ≥ 0 (không âm); ngành hàng bắt buộc chọn (làm cơ sở tính hoa hồng — FR-21); ảnh sản phẩm bắt buộc tối thiểu 1 ảnh.

SCR-19 — Quản lý đơn hàng (Seller)

• Mục đích: seller xem và xử lý các đơn hàng con thuộc gian hàng của mình.
• Persona/Role: Seller.
• FR phục vụ: FR-19.
• Bố cục:
  • Danh sách đơn: filter theo trạng thái (Chờ xác nhận, Đã xác nhận/Đang chuẩn bị, Đã bàn giao vận chuyển, Đã giao, Huỷ, Đổi trả), tìm theo mã đơn/khách hàng.
  • Chi tiết đơn: thông tin sản phẩm, khách hàng (ẩn bớt thông tin nhạy cảm theo NFR-04), địa chỉ giao hàng, nút hành động theo trạng thái (Xác nhận đơn / In vận đơn / Đánh dấu đã bàn giao cho Ops-vận chuyển).
• Trạng thái: loading = skeleton danh sách; empty = "Chưa có đơn hàng nào"; error = lỗi cập nhật trạng thái (VD. thao tác không hợp lệ với trạng thái hiện tại) + thông báo rõ.
• Validation chính: chỉ cho chuyển trạng thái theo đúng luồng hợp lệ (VD. không thể "Đã giao" khi chưa "Đã bàn giao vận chuyển"); giới hạn thời gian xác nhận đơn (nếu quá hạn → tự động cảnh báo/huỷ theo chính sách vận hành).

SCR-20 — Báo cáo doanh thu, hoa hồng & Payout (Seller)

• Mục đích: seller theo dõi doanh thu, hoa hồng bị trừ, lịch sử và trạng thái các đợt payout.
• Persona/Role: Seller.
• FR phục vụ: FR-20.
• Bố cục:
  • Bộ lọc theo khoảng thời gian.
  • Bảng chi tiết: mỗi dòng = 1 đơn hàng đã hoàn tất — doanh thu gộp, % hoa hồng áp dụng (theo CommissionRule của ngành hàng — tham chiếu FR-21), số tiền hoa hồng, số tiền thực nhận.
  • Bảng lịch sử Payout: đợt payout (tuần), tổng tiền, trạng thái (Đang giữ - hold/Đã chuyển khoản/Thất bại), ngày dự kiến chi trả.
• Trạng thái: loading = skeleton bảng; empty = "Chưa có giao dịch nào trong kỳ đã chọn"; error = payout thất bại (hiển thị lý do, VD sai thông tin ngân hàng) + hướng dẫn liên hệ hỗ trợ.
• Validation chính: không có form nhập liệu chính (read-only báo cáo); cập nhật thông tin tài khoản ngân hàng nhận payout có validate định dạng số tài khoản/tên ngân hàng (thuộc form cấu hình tài khoản thanh toán của seller, liên kết với SCR-09-tương tự cho seller).

SCR-21 — Đăng nhập Seller (MFA khuyến khích)

• Mục đích: đăng nhập vào khu vực quản trị gian hàng.
• Persona/Role: Seller.
• FR phục vụ: FR-27.
• Bố cục: form email/mật khẩu; sau đăng nhập, banner khuyến nghị bật MFA nếu chưa bật (không bắt buộc — theo mục 1.4 giả định #8); màn hình cấu hình MFA (bật/tắt, quét QR cho ứng dụng authenticator) trong phần cài đặt tài khoản.
• Trạng thái: loading = spinner; error = sai thông tin đăng nhập, tài khoản bị khoá bởi Admin (thông báo rõ + hướng dẫn liên hệ hỗ trợ — liên quan FR-23).
• Validation chính: tương tự SCR-08; nếu bật MFA, bắt buộc nhập mã OTP hợp lệ (6 số, hết hạn theo thời gian cấu hình) trước khi vào hệ thống.

---

7.1.3 Nhóm Quản trị viên sàn (Platform Admin)

SCR-22 — Admin Dashboard (Tổng quan vận hành sàn)

• Mục đích: tổng hợp số liệu vận hành toàn sàn để Admin theo dõi nhanh.
• Persona/Role: PlatformAdmin.
• FR phục vụ: không gắn trực tiếp 1 FR cụ thể — màn hình tổng hợp hỗ trợ giám sát chung (đơn hàng, GMV, seller chờ duyệt, tranh chấp mở). Cần xác nhận với BA nếu cần bổ sung FR riêng cho dashboard vận hành (xem openQuestions).
• Bố cục: thẻ số liệu (tổng GMV, số đơn hôm nay, số seller chờ duyệt KYC, số tranh chấp đang mở, tổng payout kỳ này); danh sách việc cần xử lý (queue rút gọn, link nhanh tới SCR-23/25/28).
• Trạng thái: loading = skeleton; empty = không áp dụng (luôn có số liệu, kể cả 0); error = lỗi tải số liệu tổng hợp + retry.
• Validation chính: không áp dụng (read-only).

SCR-23 — Duyệt/Khoá Seller (Quản lý KYC & tài khoản Seller)

• Mục đích: Admin xét duyệt hồ sơ KYC của seller mới đăng ký và giám sát/khoá seller vi phạm.
• Persona/Role: PlatformAdmin.
• FR phục vụ: FR-17 (duyệt KYC), FR-23 (quản trị seller — duyệt/khoá, giám sát).
• Bố cục:
  • Danh sách seller: filter theo trạng thái (Chờ duyệt, Đã duyệt, Bị khoá, Từ chối), tìm kiếm theo tên gian hàng/mã số thuế.
  • Chi tiết hồ sơ seller: thông tin đăng ký, xem KYCDocument (viewer ảnh/PDF), lịch sử vi phạm (nếu có), nút "Duyệt" / "Từ chối (nhập lý do)" / "Khoá tài khoản (nhập lý do)" / "Mở khoá".
• Trạng thái: loading = skeleton danh sách/chi tiết; empty = "Không có seller nào chờ duyệt"; error = lỗi tải tài liệu KYC (file hỏng/không truy cập được) + thông báo.
• Validation chính: bắt buộc nhập lý do khi Từ chối/Khoá tài khoản (để lưu vết và thông báo cho seller); không cho duyệt nếu thiếu tài liệu KYC bắt buộc.

SCR-24 — Quản trị Catalog toàn sàn

• Mục đích: Admin giám sát và can thiệp (ẩn/gỡ) sản phẩm vi phạm trên toàn sàn.
• Persona/Role: PlatformAdmin.
• FR phục vụ: FR-24.
• Bố cục: bảng sản phẩm toàn sàn với filter (ngành hàng, seller, trạng thái, bị báo cáo vi phạm), xem chi tiết sản phẩm (giống SCR-03 nhưng có thêm khu vực hành động), nút "Ẩn sản phẩm" / "Gỡ vĩnh viễn" (yêu cầu nhập lý do) / "Khôi phục".
• Trạng thái: loading = skeleton bảng; empty = "Không có sản phẩm bị báo cáo"; error = lỗi cập nhật trạng thái sản phẩm + retry.
• Validation chính: bắt buộc nhập lý do khi ẩn/gỡ sản phẩm (đồng bộ hiển thị lý do lại cho seller ở SCR-18).

SCR-25 — Cấu hình hoa hồng (Commission) theo ngành hàng

• Mục đích: Admin cấu hình/chỉnh sửa bảng % hoa hồng áp dụng theo từng Category.
• Persona/Role: PlatformAdmin.
• FR phục vụ: FR-21.
• Bố cục: bảng danh sách ngành hàng kèm % hoa hồng hiện hành, nút "Chỉnh sửa" mở form nhập % mới + ngày hiệu lực, lịch sử thay đổi (audit log rút gọn: ai đổi, khi nào, giá trị cũ/mới).
• Trạng thái: loading = skeleton bảng; empty = không áp dụng (danh mục ngành hàng luôn tồn tại từ hệ thống catalog); error = lỗi lưu cấu hình + validation inline.
• Validation chính: % hoa hồng trong khoảng hợp lệ (0-100%); ngày hiệu lực không được là ngày trong quá khứ; cảnh báo xác nhận trước khi lưu do ảnh hưởng trực tiếp tới thu nhập seller (liên quan FR-20).

SCR-26 — Quản lý Khuyến mãi / Mã giảm giá

• Mục đích: Admin tạo và quản lý chương trình khuyến mãi/coupon áp dụng toàn sàn hoặc theo ngành hàng/seller.
• Persona/Role: PlatformAdmin.
• FR phục vụ: FR-13.
• Bố cục: danh sách chương trình khuyến mãi (tên, mã coupon, loại giảm giá — %/số tiền cố định, điều kiện áp dụng, thời gian hiệu lực, trạng thái Đang chạy/Sắp diễn ra/Đã kết thúc); form tạo/sửa chương trình.
• Trạng thái: loading = skeleton danh sách; empty = "Chưa có chương trình khuyến mãi nào"; error = mã coupon trùng, khoảng thời gian không hợp lệ (kết thúc trước bắt đầu).
• Validation chính: mã coupon duy nhất; ngày kết thúc > ngày bắt đầu; giá trị giảm giá > 0 và hợp lý (VD % không vượt 100).

SCR-27 — Quản lý Payout

• Mục đích: Admin giám sát và xử lý các đợt chi trả payout hàng tuần cho seller.
• Persona/Role: PlatformAdmin.
• FR phục vụ: FR-22.
• Bố cục: danh sách đợt payout theo tuần (tổng số seller, tổng tiền, trạng thái tổng thể); chi tiết theo từng seller trong đợt (số tiền, trạng thái Đang giữ-hold/Sẵn sàng chi/Đã chuyển/Thất bại), nút "Chạy đối soát & tạo đợt payout", nút "Thử lại" cho payout thất bại.
• Trạng thái: loading = trạng thái "Đang tính toán đối soát..."; empty = "Không có seller nào đủ điều kiện payout kỳ này"; error = payout thất bại (sai thông tin tài khoản ngân hàng seller, lỗi kết nối ngân hàng) + log chi tiết.
• Validation chính: không cho chạy payout trùng kỳ đã xử lý; chỉ tính các đơn đã qua kỳ giữ tiền (hold) 3-7 ngày sau giao hàng thành công (theo giả định #3, mục 1.4) trước khi đưa vào đợt chi trả.

SCR-28 — Xử lý Tranh chấp & Khiếu nại (Admin — escalation)

• Mục đích: Admin xử lý các tranh chấp phức tạp giữa khách hàng và seller được CSR chuyển lên (escalate).
• Persona/Role: PlatformAdmin (xử lý escalation); tham chiếu chung với SCR-32 (CSR).
• FR phục vụ: FR-25.
• Bố cục: danh sách Dispute (mã, khách hàng, seller, đơn hàng liên quan, mức độ ưu tiên, trạng thái); chi tiết tranh chấp — lịch sử trao đổi, minh chứng đính kèm (từ SCR-11), nút quyết định (Hoàn tiền khách hàng / Từ chối yêu cầu / Yêu cầu seller bồi hoàn) kèm ô nhập lý do/ghi chú quyết định.
• Trạng thái: loading = skeleton danh sách/chi tiết; empty = "Không có tranh chấp cần Admin xử lý"; error = lỗi lưu quyết định + retry.
• Validation chính: bắt buộc nhập lý do quyết định (lưu vết cho đối soát); không cho đóng tranh chấp nếu chưa chọn 1 trong các hướng xử lý.

SCR-29 — Đăng nhập Admin (MFA bắt buộc)

• Mục đích: đăng nhập khu vực quản trị sàn với xác thực đa yếu tố bắt buộc.
• Persona/Role: PlatformAdmin.
• FR phục vụ: FR-27.
• Bố cục: form email/mật khẩu → bước bắt buộc nhập mã OTP (app authenticator) trước khi vào hệ thống, không có lựa chọn bỏ qua.
• Trạng thái: loading = spinner; error = sai thông tin đăng nhập, mã OTP sai/hết hạn, tài khoản chưa cấu hình MFA (chặn đăng nhập, bắt buộc thiết lập MFA lần đầu).
• Validation chính: MFA bắt buộc 100% (không có nút "Bỏ qua"); khoá tài khoản tạm thời sau nhiều lần nhập sai liên tiếp (theo chính sách mục 8).

---

7.1.4 Nhóm Nhân viên vận hành/kho (Ops/Warehouse)

SCR-30 — Danh sách đơn cần xử lý/đóng gói

• Mục đích: Ops xem danh sách đơn hàng (thuộc phạm vi được phân công theo sàn hoặc theo seller) cần đóng gói và bàn giao vận chuyển.
• Persona/Role: OpsStaff.
• FR phục vụ: FR-26.
• Bố cục: bảng đơn hàng cần xử lý (mã đơn, seller, sản phẩm, hạn xử lý), filter theo trạng thái/kho, nút "Đánh dấu đã đóng gói" → chuyển bước tạo vận đơn.
• Trạng thái: loading = skeleton bảng; empty = "Không có đơn nào cần xử lý"; error = lỗi tải danh sách + retry.
• Validation chính: chỉ hiển thị/thao tác trên đơn thuộc phạm vi được phân công (theo phân quyền mục 1.2, không thiết kế lại ở đây).

SCR-31 — Cập nhật trạng thái vận chuyển

• Mục đích: tạo vận đơn với GHN/GHTK và cập nhật trạng thái giao hàng.
• Persona/Role: OpsStaff.
• FR phục vụ: FR-26.
• Bố cục: form chọn đơn vị vận chuyển (GHN/GHTK), hiển thị phí ước tính, nút "Tạo vận đơn"; sau khi tạo — hiển thị mã vận đơn, trạng thái đồng bộ từ đơn vị vận chuyển (Đã lấy hàng/Đang giao/Giao thành công/Giao thất bại), nút cập nhật thủ công nếu cần đối soát.
• Trạng thái: loading = "Đang tạo vận đơn..."; error = API vận chuyển lỗi/timeout (thông báo + nút thử lại/chọn đơn vị khác); empty = không áp dụng.
• Validation chính: không cho tạo vận đơn trùng cho 1 đơn hàng đã có vận đơn hợp lệ; địa chỉ giao hàng phải hợp lệ với vùng phục vụ của đơn vị vận chuyển đã chọn.

---

7.1.5 Nhóm Nhân viên chăm sóc khách hàng (CSR)

SCR-32 — Hàng đợi Khiếu nại/Đổi trả (CSR)

• Mục đích: CSR tiếp nhận, xử lý các yêu cầu đổi trả/khiếu nại từ khách hàng; escalate lên Admin khi cần.
• Persona/Role: CSR (read/xử lý theo quyền hạn được mô tả mục 1.2: có quyền xem thông tin đơn hàng liên quan để hỗ trợ, không chỉnh sửa cấu hình hệ thống).
• FR phục vụ: FR-09 (tiếp nhận yêu cầu đổi trả), FR-25 (xử lý tranh chấp/khiếu nại).
• Bố cục: danh sách hàng đợi (mã yêu cầu, khách hàng, seller, đơn hàng, lý do, mức độ ưu tiên, thời gian chờ xử lý — SLA); chi tiết yêu cầu — xem minh chứng, lịch sử trao đổi (thread), nút "Phản hồi khách hàng" (nhập tin nhắn), nút "Giải quyết trực tiếp" (nếu trong thẩm quyền CSR) hoặc "Chuyển lên Admin" (escalate tới SCR-28, kèm ghi chú lý do escalate).
• Trạng thái: loading = skeleton danh sách/chi tiết; empty = "Không có yêu cầu nào đang chờ xử lý"; error = lỗi tải minh chứng đính kèm (file hỏng) + thông báo.
• Validation chính: bắt buộc nhập nội dung phản hồi trước khi gửi; bắt buộc chọn lý do khi escalate lên Admin; không cho CSR chỉnh sửa cấu hình hoa hồng/catalog/seller (ngoài phạm vi quyền — tham chiếu mục 1.2).

---

7.2 User Flow Diagram (theo persona)

7.2.1 Khách hàng — Hành trình mua hàng đầy đủ (FR-04, FR-05, FR-06, FR-07, FR-08, FR-12, FR-13, FR-14)

flowchart TD
    A["Vào trang chủ (SCR-01)"] --> B["Tìm kiếm / duyệt danh mục (SCR-02, SCR-03)"]
    B --> C{"Sản phẩm còn hàng?"}
    C -- "Không" --> B
    C -- "Có" --> D["Thêm vào giỏ hàng (SCR-04)"]
    D --> E{"Tiếp tục mua hay Checkout?"}
    E -- "Tiếp tục mua" --> B
    E -- "Checkout" --> F{"Đã đăng nhập?"}
    F -- "Chưa (Guest checkout)" --> G["Nhập thông tin Guest hoặc Đăng nhập/Đăng ký (SCR-08)"]
    F -- "Đã đăng nhập" --> H["Checkout: địa chỉ, tách đơn theo seller, áp coupon/điểm (SCR-05)"]
    G --> H
    H --> I{"Coupon/địa chỉ hợp lệ?"}
    I -- "Không" --> H
    I -- "Có" --> J["Chọn phương thức thanh toán (SCR-06)"]
    J --> K{"Thanh toán thành công?"}
    K -- "Thất bại" --> L["Hiển thị lỗi, chọn lại phương thức"] --> J
    K -- "Thành công" --> M["Xác nhận đơn hàng (SCR-07) + gửi email/SMS (FR-12)"]
    M --> N["Theo dõi đơn hàng (SCR-10)"]

7.2.2 Khách hàng — Đổi trả/Khiếu nại (FR-08, FR-09, FR-12, FR-25)

flowchart TD
    A["Lịch sử đơn hàng (SCR-10)"] --> B["Chọn đơn đã giao"]
    B --> C["Gửi yêu cầu đổi trả/khiếu nại (SCR-11)"]
    C --> D{"Trong thời hạn chính sách đổi trả?"}
    D -- "Không" --> E["Từ chối tự động + thông báo lý do (FR-12)"]
    D -- "Có" --> F["CSR tiếp nhận (SCR-32)"]
    F --> G{"Thuộc thẩm quyền CSR?"}
    G -- "Có" --> H["CSR giải quyết trực tiếp"]
    G -- "Không, cần escalate" --> I["Admin xử lý tranh chấp (SCR-28)"]
    I --> H
    H --> J["Cập nhật trạng thái + thông báo kết quả cho khách hàng (FR-12)"]

7.2.3 Seller — Đăng ký, KYC, vận hành gian hàng (FR-17, FR-18, FR-19, FR-20, FR-26, FR-27)

flowchart TD
    A["Đăng ký Seller (SCR-16)"] --> B["Upload hồ sơ KYC"]
    B --> C["Admin duyệt KYC (SCR-23)"]
    C --> D{"Hồ sơ hợp lệ?"}
    D -- "Từ chối" --> E["Thông báo lý do, seller bổ sung hồ sơ"] --> B
    D -- "Đồng ý" --> F["Đăng nhập Seller (SCR-21, MFA khuyến khích - FR-27)"]
    F --> G["Seller Dashboard (SCR-17)"]
    G --> H["Đăng sản phẩm & cập nhật tồn kho (SCR-18)"]
    G --> I["Nhận & xác nhận đơn hàng (SCR-19)"]
    I --> J["Bàn giao cho Ops đóng gói/vận chuyển (SCR-30, SCR-31 - FR-26)"]
    J --> K["Đơn hàng giao thành công"]
    K --> L["Xem báo cáo doanh thu/hoa hồng/payout (SCR-20)"]

7.2.4 Platform Admin — Vận hành & quản trị sàn (FR-13, FR-17, FR-21, FR-22, FR-23, FR-24, FR-25, FR-27)

flowchart TD
    A["Đăng nhập Admin, MFA bắt buộc (SCR-29)"] --> B["Admin Dashboard (SCR-22)"]
    B --> C["Duyệt/khoá Seller (SCR-23) - FR-17, FR-23"]
    B --> D["Cấu hình hoa hồng theo ngành hàng (SCR-25) - FR-21"]
    B --> E["Quản trị catalog toàn sàn (SCR-24) - FR-24"]
    B --> F["Quản lý khuyến mãi/coupon (SCR-26) - FR-13"]
    B --> G["Quản lý payout hàng tuần (SCR-27) - FR-22"]
    B --> H["Xử lý tranh chấp escalate từ CSR (SCR-28) - FR-25"]

7.2.5 Ops/Warehouse — Xử lý đơn hàng & vận chuyển (FR-26)

flowchart TD
    A["Danh sách đơn cần xử lý (SCR-30)"] --> B["Đóng gói sản phẩm"]
    B --> C["Tạo vận đơn qua GHN/GHTK (SCR-31)"]
    C --> D{"Tạo vận đơn thành công?"}
    D -- "Thất bại" --> E["Thử lại / chọn đơn vị vận chuyển khác"] --> C
    D -- "Thành công" --> F["Cập nhật trạng thái: Đã bàn giao vận chuyển"]
    F --> G["Đồng bộ trạng thái giao hàng (Đang giao/Giao thành công/Thất bại)"]
    G --> H["Gửi thông báo cập nhật cho khách hàng (FR-12)"]

---

7.3 Ghi chú truy vết & khoảng trống

• Tất cả FR-01 → FR-27 đã có ít nhất 1 màn hình hoặc luồng tham chiếu, trừ SCR-22 (Admin Dashboard tổng quan) — màn hình này không truy vết trực tiếp về 1 FR cụ thể, chỉ đóng vai trò tổng hợp giám sát; đã gắn cờ "cần xác nhận với BA" ngay tại mục mô tả màn hình.
• FR-12 (Thông báo email/SMS) về bản chất là kênh giao tiếp ngoài giao diện web (không phải "màn hình"); SCR-15 (Trung tâm thông báo trong-app) là bổ sung giả định của thiết kế, cần BA/PO xác nhận có thực sự cần trung tâm thông báo trong-app ở MVP hay chỉ cần email/SMS thuần tuý.
• Thiết kế không đề xuất màu sắc/typography cụ thể do project brief không có brand guideline (giả định #9, mục 1.4) — khi có brand guideline thực tế, cần cập nhật lại phần mockup trực quan (hiện tại chỉ ở dạng wireframe văn bản).