Bỏ qua nội dung
VNexus VNexus Requirement

Phone Registries - quản lý định danh số điện thoại

Feature URL
Module
auth
Status
draft
Priority
P1
Platforms
be
AC progress
0 / 9
Last reviewed
2026-05-29

Mục tiêu

phone_registries là nguồn trung tâm để quản lý, chuẩn hóa và định danh số điện thoại trong hệ thống V-Nexus. Feature này giúp hệ thống tránh trùng lặp số điện thoại, liên kết số điện thoại với user, contacts, listings, dữ liệu crawl và CRM, đồng thời cung cấp tín hiệu phục vụ resolve owner/broker/contact và tính toán trust_score.

Phạm vi

Trong phạm vi (In scope):

  • Ghi nhận một bản ghi định danh số điện thoại khi user đăng ký bằng số điện thoại.
  • Ghi nhận hoặc tái sử dụng bản ghi định danh số điện thoại khi crawler thu thập listing có contact_phone.
  • Ghi nhận hoặc tái sử dụng bản ghi định danh số điện thoại khi user thêm contact trong CRM.
  • Chuẩn hóa số điện thoại trước khi dùng để so khớp và chống trùng lặp.
  • Cho phép một số điện thoại tham chiếu tới user, contact, listing hoặc nguồn dữ liệu crawl phù hợp với ngữ cảnh nghiệp vụ.
  • Cung cấp tín hiệu về nguồn, mức độ tin cậy và trạng thái số điện thoại cho các luồng resolve và trust_score.

Ngoài phạm vi (Out of scope):

  • Thiết kế schema chi tiết, khóa unique, migration hoặc index database.
  • Endpoint, service nội bộ, queue hoặc workflow implementation.
  • UI quản trị dữ liệu số điện thoại.
  • Quy trình gọi điện, xác minh thủ công hoặc chấm điểm spam chi tiết.

User Stories

  • Là hệ thống xác thực, tôi muốn ghi nhận số điện thoại của user đã đăng ký để định danh user bằng nguồn dữ liệu đáng tin cậy.
  • Là hệ thống crawl listing, tôi muốn tái sử dụng số điện thoại đã biết khi gặp listing từ nguồn ngoài để tránh tạo trùng dữ liệu liên hệ.
  • Là user dùng CRM, tôi muốn contact mới được liên kết theo số điện thoại đã tồn tại nếu có để CRM không bị trùng contact theo số điện thoại.
  • Là hệ thống tính trust_score, tôi muốn biết nguồn và lịch sử xuất hiện của số điện thoại để đánh giá độ tin cậy của listing/contact liên quan.

Luồng chức năng

sequenceDiagram
    actor User
    participant App
    participant Crawler
    participant CRM
    participant Registry as Phone Registry

    User->>App: Đăng ký bằng số điện thoại
    App->>Registry: Tạo hoặc cập nhật số điện thoại và gắn user
    Registry-->>App: Trả về bản ghi đã chuẩn hóa

    Crawler->>Registry: Gửi contact_phone từ listing nguồn ngoài
    Registry-->>Crawler: Tái sử dụng hoặc tạo bản ghi số điện thoại

    User->>CRM: Thêm contact mới
    CRM->>Registry: Tìm hoặc tạo bản ghi số điện thoại
    Registry-->>CRM: Trả về bản ghi để liên kết contact

Acceptance Criteria

  • AC-1: Khi user đăng ký bằng số điện thoại hợp lệ, hệ thống tạo hoặc cập nhật một bản ghi trong phone_registries và gắn với user_id.
  • AC-2: Khi user đăng ký bằng số điện thoại đã tồn tại trong phone_registries, hệ thống không tạo bản ghi trùng mà cập nhật liên kết với user phù hợp.
  • AC-3: Khi crawler thu thập listing có contact_phone, hệ thống tạo hoặc cập nhật phone_registries theo số điện thoại đã chuẩn hóa.
  • AC-4: Khi contact_phone từ listing crawl đã tồn tại, hệ thống tái sử dụng bản ghi cũ để liên kết với dữ liệu crawl/listing liên quan.
  • AC-5: Khi listing crawl không có số điện thoại, hệ thống không tạo phone_registries cho listing đó và áp dụng rule loại bỏ hoặc không xử lý tiếp theo quy định của crawler.
  • AC-6: Khi user thêm contact trong CRM với số điện thoại chưa tồn tại, hệ thống tạo mới bản ghi phone_registries để contact tham chiếu.
  • AC-7: Khi user thêm contact trong CRM với số điện thoại đã tồn tại, contact được liên kết với bản ghi phone_registries hiện có.
  • AC-8: Các luồng đăng ký, crawl và CRM đều sử dụng cùng nguyên tắc chuẩn hóa số điện thoại trước khi so khớp.
  • AC-9: Thông tin nguồn và mức độ tin cậy của số điện thoại có thể được dùng làm tín hiệu cho resolve user/contact/property/listing và tính toán trust_score.

Quy tắc nghiệp vụ

  • Một số điện thoại sau khi chuẩn hóa chỉ nên có một bản ghi định danh trung tâm trong phone_registries.
  • Số điện thoại từ user đã đăng ký là nguồn dữ liệu có độ tin cậy cao hơn số điện thoại chỉ xuất hiện từ dữ liệu crawl hoặc CRM.
  • Khi số điện thoại đã tồn tại, các luồng nghiệp vụ phải ưu tiên tái sử dụng bản ghi hiện có thay vì tạo bản ghi trùng.
  • Bản ghi tạo từ đăng ký tài khoản phải gắn với user_id tương ứng.
  • Bản ghi tạo từ crawl có thể chưa gắn với user_id, nhưng vẫn có thể liên kết với contacts, listings và phục vụ resolve owner/broker sau này.
  • Bản ghi tạo từ CRM phải hỗ trợ liên kết contact với số điện thoại đã tồn tại để giảm trùng lặp contact theo số điện thoại.
  • Nếu listing crawl không có số điện thoại, crawler có thể loại bỏ hoặc không xử lý tiếp listing đó theo rule của luồng crawl.
  • Các nguồn xuất hiện của một số điện thoại cần được ghi nhận ở mức nghiệp vụ để hỗ trợ đánh giá độ tin cậy và phát hiện trùng lặp.
  • phone_registries không tự quyết định user là owner, broker hay contact; nó cung cấp tín hiệu để các luồng resolve đưa ra kết luận.

Dữ liệu & Trạng thái

Entity nghiệp vụ:

  • PhoneRegistry: số điện thoại gốc, số điện thoại đã chuẩn hóa, nguồn tạo/cập nhật, liên kết user nếu có, liên kết contact/listing nếu có, tín hiệu độ tin cậy, trạng thái sử dụng.
  • RegisteredUserPhone: số điện thoại đến từ user đã đăng ký và đã gắn với user_id.
  • CrawledContactPhone: số điện thoại lấy từ listing nguồn ngoài như Muaban.net, Nhà Tốt, Batdongsan.com.vn.
  • CrmContactPhone: số điện thoại do user nhập khi quản lý khách hàng, chủ nhà, môi giới hoặc contact trong CRM.

Trạng thái user-facing:

  • registered_user_phone — số điện thoại đã gắn với user đăng ký.
  • crawled_phone — số điện thoại được phát hiện từ dữ liệu crawl, có thể chưa gắn user.
  • crm_contact_phone — số điện thoại được dùng cho contact trong CRM.
  • reused_phone_registry — số điện thoại đã tồn tại và được tái sử dụng cho liên kết mới.
  • missing_phone — listing/contact không có số điện thoại hợp lệ để tạo hoặc liên kết registry.

Liên quan