Skip to main content

[DDD] Thiết kế Chi tiết Trang Nhập SĐT (Đăng ký)

Tóm tắt tài liệu

Tài liệu này mô tả thiết kế kỹ thuật chi tiết cho Trang Nhập Số điện thoại cho quy trình Đăng ký (Phone Entry Register Page). Đây là bước đầu tiên trong quy trình đăng ký tài khoản mới, nơi người dùng cung cấp số điện thoại để xác minh.

1. Tổng quan (Overview)​

1.1. Bối cảnh và Vấn đề​

Để đăng ký một tài khoản mới, người dùng cần cung cấp một phương thức liên lạc và xác minh duy nhất. Số điện thoại là một lựa chọn phổ biến. Trang này cung cấp một biểu mẫu đơn giản để người dùng nhập số điện thoại, bắt đầu quy trình đăng ký và xác minh qua OTP.

1.2. Mục tiêu & Phi mục tiêu (Goals and Non-Goals)​

Mục tiêu (Goals)​

  • Cung cấp một biểu mẫu để người dùng mới nhập số điện thoại.
  • Xác thực định dạng số điện thoại của Việt Nam bằng Zod.
  • Sử dụng useMutation của React Query để xử lý việc gọi API gửi OTP một cách có quản lý trạng thái (loading, error, success).
  • Gửi yêu cầu đến API để gửi mã OTP xác minh đến số điện thoại đã nhập.
  • Điều hướng người dùng đến trang xác minh OTP (/verify-otp/:phoneNumber) sau khi gửi yêu cầu thành công.

Phi mục tiêu (Non-Goals)​

  • Kiểm tra xem số điện thoại đã tồn tại hay chưa ở phía client (backend sẽ xử lý việc này và trả về lỗi nếu cần).
  • Đăng nhập cho người dùng hiện tại (có liên kết đến trang đăng nhập).

2. Kiến trúc Tổng thể (Overall Architecture)​

Trang này sử dụng React Query để quản lý trạng thái của lệnh gọi API, giúp đơn giản hóa việc xử lý loading và error.

3. Thiết kế Chi tiết (Detailed Design)​

3.1. Thiết kế Giao diện & Luồng người dùng (UI & User Flow)​

  • Components: Input, Button, CountryCodeSelect.
  • Libraries: React Hook Form, Zod, React Query, Sonner.
  • Luồng người dùng:
    1. Người dùng truy cập trang /register (hoặc một route tương tự).
    2. Giao diện hiển thị một ô nhập số điện thoại và bộ chọn mã quốc gia.
    3. Người dùng nhập số điện thoại. Chỉ các ký tự số được chấp nhận.
    4. Người dùng nhấn nút "Enter".
    5. handleSubmit kích hoạt validation của Zod.
    6. Nếu SĐT không hợp lệ, lỗi được hiển thị.
    7. Nếu SĐT hợp lệ, hàm onSubmit được gọi, và nó sẽ kích hoạt phoneVerifyMutation.mutate(data).
    8. Nút "Enter" bị vô hiệu hóa và hiển thị trạng thái "Processing..." (isPending từ useMutation).
    9. useMutation thực hiện lệnh gọi API:
      • onSuccess: Người dùng được điều hướng đến /verify-otp/:phoneNumber.
      • onError: Một toast lỗi được hiển thị cho người dùng (ví dụ: "Xác minh điện thoại thất bại", có thể do SĐT đã tồn tại).

3.2. Quản lý Trạng thái với React Query (useMutation)​

const phoneVerifyMutation = useMutation({
  mutationFn: async (data: PhoneForm) => {
    // ... logic gọi API bằng axios
    return fullPhoneNumber;
  },
  onSuccess: (phoneNumber) => {
    navigate(`/verify-otp/${phoneNumber}`);
  },
  onError: () => {
    toast.error(t('toast.phoneEntry.phoneVerificationFailed'));
  },
});
  • mutationFn: Hàm không đồng bộ thực hiện logic gọi API thực tế. Nó trả về dữ liệu khi thành công hoặc ném ra lỗi khi thất bại.
  • onSuccess: Callback được thực thi khi mutationFn thành công. Nó nhận dữ liệu trả về từ mutationFn làm đối số.
  • onError: Callback được thực thi khi mutationFn ném ra lỗi.
  • isPending: useMutation cung cấp một cờ isPending mà component có thể sử dụng để hiển thị trạng thái loading.

3.3. Thiết kế API (API Design)​

Endpoint: POST /auth/api/v1/send-otp

Request Body: FormData

  • phone_number: string (ví dụ: +84901234567)

Response (Success - 200 OK):

{
  "message": "OTP sent successfully."
}

Response (Error):

  • 409 Conflict: Nếu số điện thoại đã được đăng ký. 
    { "message": "Phone number already exists." }

4. Các yếu tố phi chức năng (Non-Functional Requirements)​

4.1. Bảo mật (Security)​

  • Tương tự như trang quên mật khẩu, backend nên có cơ chế rate limiting để ngăn chặn việc lạm dụng API gửi OTP.

4.2. Trải nghiệm người dùng (UX)​

  • Việc sử dụng useMutation giúp quản lý trạng thái disabled và loading của nút một cách rõ ràng, ngăn người dùng gửi lại biểu mẫu nhiều lần trong khi yêu cầu đầu tiên đang được xử lý.
  • Cung cấp một liên kết rõ ràng cho người dùng đã có tài khoản để điều hướng đến trang đăng nhập là một thực hành UX tốt.

5. Rủi ro và Phương án giảm thiểu (Risks and Mitigation)​

Rủi roMức độ ảnh hưởngKhả năng xảy raPhương án giảm thiểu
Người dùng không nhận được OTP do nhà mạng chậm trễTrung bìnhTrung bìnhTrang xác minh OTP (VerifyOtpPage) nên có chức năng "Gửi lại mã" với một khoảng thời gian chờ để xử lý trường hợp này.
Thông báo lỗi không rõ ràng (ví dụ: "Thất bại")ThấpTrung bìnhCải thiện xử lý lỗi trong callback onError để phân tích lỗi từ API và hiển thị thông báo cụ thể hơn cho người dùng, ví dụ: "Số điện thoại này đã được đăng ký. Vui lòng đăng nhập."

Tài liệu tham khảo: