Crawl listings từ nguồn ngoài (Muaban, Nhà Tốt, Batdongsan)

Feature URL

Module

crawler

Status

draft

Priority

Platforms

fe · be

AC progress

0 / 25

Last reviewed

2026-05-29

Mục tiêu

Thu thập tin đăng BĐS từ 3 nguồn bên thứ ba (Muaban.net, Nhà Tốt, Batdongsan.com.vn), chuẩn hóa về một format chung để tái dùng đúng các endpoint hiện có POST /properties và POST /listings nhằm tạo property + listing chính thức trong V-Nexus. Sau khi crawl, dữ liệu được chuẩn hóa thành 4 nhóm: thông tin property, thông tin listing, thông tin contact, thông tin nguồn crawl. Pipeline: chống trùng listing theo source + source_id (đã có thì bỏ qua, không tạo property/contact, không gọi POST /listings); tái dùng property nếu khớp address + area_m2 + property_type_id, nếu chưa có thì gọi POST /properties; resolve liên hệ theo số điện thoại (tra/tạo phone_registries rồi tra/tạo contacts); rồi map sang CreateListingRequest và gọi POST /listings. Tin crawl đi chung luồng với tin tạo từ app — không dùng chế độ ingest, không bỏ qua validate user-facing; Backend tính trust_score, route tin trust_score < 80 vào Data Marketplace (public) và tin trust_score ≥ 80 vào kho lưu trữ Admin, đồng thời push realtime qua WebSocket như mọi listing thường. Các trường nguồn (source, source_id, source_url) lưu trực tiếp trên bảng listings; thông tin liên hệ lưu ở bảng contacts mới (tham chiếu qua listings.contact_id), còn số điện thoại liên hệ lưu ở phone_registries — contacts trỏ tới qua khóa ngoại phone_registry_id. Bỏ hoàn toàn bảng staging data_sources, chế độ ingest, và logic resolve user/owner theo số điện thoại (không resolve users; phone_registries chỉ là nơi lưu số điện thoại, không suy ra owner).

Phạm vi

Trong phạm vi (In scope):

Crawl tin đăng từ 3 nguồn: Muaban.net, Nhà Tốt, Batdongsan.com.vn; crawl chạy liên tục — xong lượt nào bắt đầu lượt kế tiếp ngay, không chờ interval cố định
Mỗi lượt crawl lấy tin trong time_windows = 2 phút lùi từ thời điểm hiện tại ([now − 2 phút, now])
Chuẩn hóa dữ liệu crawl thành 4 nhóm: property, listing, contact, thông tin nguồn — khớp với request của POST /properties và POST /listings
Chống trùng listing: trước khi xử lý, tra bảng listings theo cặp source + source_id; nếu đã tồn tại → bỏ qua tin đó (không tạo property, không tạo contact, không gọi POST /listings)
Loại tin thiếu số điện thoại: sau khi lấy chi tiết, nếu số điện thoại liên hệ null/rỗng/không hợp lệ → drop tin tại crawl, không tạo phone_registries/contact/property/listing
Tái dùng property: tra property theo address + area_m2 + property_type_id; khớp → dùng property_id hiện có; không khớp → gọi POST /properties rồi lấy property_id vừa tạo
Resolve liên hệ: tra/tạo bản ghi phone_registries theo số điện thoại, rồi tra/tạo contacts trỏ tới phone_registry_id đó; đã có → dùng contact_id hiện có
Tạo bảng contacts lưu thông tin liên hệ (một-nhiều với listings); thêm khóa ngoại contact_id vào listings; contacts có khóa ngoại phone_registry_id → phone_registries (nơi lưu số điện thoại)
Lưu các trường nguồn (source, source_id, source_url) trực tiếp trên listings
Map dữ liệu sang CreateListingRequest (kèm property_id, contact_id, source, source_id, source_url) và gọi POST /listings — đi chung luồng tin app, validate đầy đủ, không ingest
Backend tính trust_score, route trust_score < 80 → Data Marketplace (public), trust_score ≥ 80 → kho lưu trữ Admin; push event WebSocket khi listing trong Data Marketplace mới / cập nhật / đổi trust_score
Frontend nhận event và phản ánh thay đổi listing trên giao diện

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

Crawl nguồn khác ngoài 3 website trên (phase sau)
Thiết kế chi tiết màn hình listing trên Frontend (feature FE riêng nếu cần)
Công thức/trọng số chính xác tính trust_score (Dev quyết ở repo BE)
Thuật toán/threshold normalization để match property khi resolve (Dev quyết ở repo BE)
Thiết kế schema DB chi tiết (kiểu cột, index), API contract kỹ thuật, lựa chọn tech stack crawler (thuộc repo source code)
Logic xử lý nội bộ của POST /properties và POST /listings (thuộc feature/endpoint tương ứng ở repo source)
Kiểm duyệt thủ công listing crawl trước khi publish
Giao diện admin xem kho lưu trữ Admin (feature admin riêng)
Resolve user/owner, tài khoản shadow, claim tài khoản — đã loại khỏi luồng crawl (số điện thoại lưu ở phone_registries nhưng không dùng để suy ra owner)

User Stories

Là hệ thống, tôi muốn crawl tin đăng từ Muaban.net, Nhà Tốt, Batdongsan.com.vn để có nguồn dữ liệu listing bên ngoài.
Là hệ thống, tôi muốn chuẩn hóa tin crawl thành property/listing/contact/nguồn để tái dùng đúng POST /properties và POST /listings hiện có, không cần endpoint riêng.
Là hệ thống, tôi muốn trước khi xử lý kiểm tra listings theo source + source_id; nếu đã có thì bỏ qua để không tạo trùng property/contact/listing.
Là hệ thống, tôi muốn tái dùng property đã tồn tại (theo address + area_m2 + property_type_id) hoặc tạo mới qua POST /properties để mỗi BĐS chỉ có một property.
Là hệ thống, tôi muốn lưu số điện thoại liên hệ ở phone_registries và gắn contacts tới đó qua phone_registry_id, gom các tin cùng số điện thoại về một contact, để quản lý liên hệ tập trung mà không định danh user.
Là Backend, tôi muốn nhận CreateListingRequest kèm property_id, contact_id, source, source_id, source_url và xử lý như một request tạo listing bình thường (validate đầy đủ).
Là Backend, tôi muốn tính trust_score rồi route tin trust_score < 80 vào Data Marketplace, tin trust_score ≥ 80 vào kho lưu trữ Admin — như mọi listing khác.
Là user trên Frontend, tôi muốn thấy listing mới hoặc cập nhật trong Data Marketplace ngay khi hệ thống xử lý xong, không cần refresh trang.
Là admin, tôi muốn tin có trust_score ≥ 80 tự động vào kho lưu trữ Admin để bảo vệ khỏi phân phối đại trà.

Luồng chức năng

sequenceDiagram
    participant Source as Nguồn ngoài<br/>(Muaban / Nhà Tốt / Batdongsan)
    participant Crawler as Crawler
    participant Normalizer as Normalizer
    participant BE as Backend
    participant DM as Data Marketplace
    participant AA as Kho lưu trữ Admin
    participant WS as WebSocket
    participant FE as Frontend

    loop Crawl liên tục (window now lùi 2 phút)
        Crawler->>Source: Liệt kê tin trong window
        Source-->>Crawler: Danh sách tin ứng viên
        Crawler->>Crawler: Tra listings theo source + source_id
        alt source + source_id đã tồn tại
            Crawler->>Crawler: Bỏ qua tin (không xử lý tiếp)
        else chưa tồn tại
            Crawler->>Source: Lấy chi tiết tin
            Source-->>Crawler: Dữ liệu gốc
            Crawler->>Normalizer: Payload thô theo nguồn
            Normalizer->>Normalizer: Chuẩn hóa thành property, listing, contact, nguồn
            alt số điện thoại trống hoặc không hợp lệ
                Normalizer->>Normalizer: Bỏ tin (không gửi Backend)
            else có số điện thoại hợp lệ
                Normalizer->>BE: Tra property theo address + area_m2 + property_type_id
                alt property đã tồn tại
                    BE-->>Normalizer: property_id hiện có
                else chưa tồn tại
                    Normalizer->>BE: POST /properties
                    BE-->>Normalizer: property_id mới tạo
                end
                Normalizer->>BE: Tra phone_registries theo số điện thoại
                alt số điện thoại đã có trong phone_registries
                    BE-->>Normalizer: phone_registry_id hiện có
                else chưa có
                    Normalizer->>BE: Tạo phone_registries lưu số điện thoại
                    BE-->>Normalizer: phone_registry_id mới tạo
                end
                Normalizer->>BE: Tra contact theo phone_registry_id
                alt contact đã tồn tại
                    BE-->>Normalizer: contact_id hiện có
                else chưa tồn tại
                    Normalizer->>BE: Tạo contact gắn phone_registry_id
                    BE-->>Normalizer: contact_id mới tạo
                end
                Normalizer->>BE: POST /listings (property_id, contact_id, source, source_id, source_url)
            end
        end
    end

    Note over BE: POST /listings (auth tài khoản broker tạo sẵn) xử lý như tin thường

    BE->>BE: Tạo listing gắn property_id + contact_id
    BE->>BE: Tính trust_score + bổ sung field hệ thống

    alt trust_score < 80
        BE->>DM: Lưu vào Data Marketplace (public)
        BE->>WS: LISTING_CREATED hoặc LISTING_UPDATED
        WS->>FE: Push realtime
        FE->>FE: Cập nhật listing trên UI
    else trust_score ≥ 80
        BE->>AA: Lưu vào kho lưu trữ Admin (admin-only)
        BE->>WS: Event nội bộ admin (Dev quyết)
    end

    alt trust_score thay đổi
        BE->>WS: LISTING_TRUST_SCORE_UPDATED
    end

Phân vai nghiệp vụ:

Vai trò	Trách nhiệm
Crawler	Crawl liên tục từng nguồn; tra `listings` theo `source + source_id` trước khi xử lý, bỏ qua tin đã có; loại tin thiếu số điện thoại; xử lý lỗi kết nối/parse cơ bản
Normalizer	Chuẩn hóa dữ liệu thành 4 nhóm (property, listing, contact, nguồn); orchestrate: tra/tạo property qua `POST /properties`, tra/tạo `phone_registries` theo số điện thoại + tra/tạo `contacts`, map `CreateListingRequest` rồi gọi `POST /listings`
Backend	Cung cấp `POST /properties`, `POST /listings`, logic contact + `phone_registries`; validate đầy đủ như tin app; tính `trust_score`; route Data Marketplace / kho Admin; lưu DB + phát event
WebSocket	Đẩy event realtime tới Frontend (public Data Marketplace) hoặc admin channel (kho Admin)
Frontend	Subscribe event, cập nhật UI listing trong Data Marketplace

Acceptance Criteria

Quy tắc nghiệp vụ

Mỗi tin từ nguồn ngoài định danh duy nhất bởi cặp source + source_id; source chỉ nhận MUABAN / NHATOT / BATDONGSAN.
Crawl liên tục: xong lượt nào bắt đầu lượt kế tiếp ngay (không chờ interval cố định). time_windows = [now − 2 phút, now] — chỉ lấy tin có thời điểm đăng/cập nhật tại nguồn trong khung này.
Chống trùng (tại crawl, lớp duy nhất): trước khi lấy chi tiết/xử lý, tra listings theo source + source_id; đã có → bỏ qua tin (không fetch tiếp, không tạo property/contact, không gọi POST /listings). Không đặt unique constraint (source, source_id) ở DB làm chốt cuối — chống trùng chỉ ở lớp crawl này.
Loại tin thiếu liên hệ: số điện thoại null/rỗng/không hợp lệ → drop tại crawl (tin không liên hệ được coi là rác).
Chuẩn hóa 4 nhóm: property, listing, contact, thông tin nguồn — map trực tiếp vào request POST /properties và POST /listings; không qua staging.
Tái dùng property: tra theo address + area_m2 + property_type_id. Khớp → dùng property_id hiện có, không tạo mới và không ghi đè. Không khớp → POST /properties → lấy property_id mới. Thuật toán normalization địa chỉ/threshold match do Dev quyết ở repo BE.
Số điện thoại lưu ở phone_registries: số điện thoại liên hệ không lưu trên contacts mà ở phone_registries; contacts có khóa ngoại phone_registry_id → phone_registries.id. phone nên là khóa tra duy nhất trong phone_registries.
Resolve liên hệ theo số điện thoại: tra/tạo phone_registries theo số điện thoại → tra/tạo contacts theo phone_registry_id. Đã có → dùng lại; chưa có → tạo mới. Cùng số điện thoại ở nhiều tin → cùng một phone_registry → cùng một contact.
Quan hệ contact–listing là một-nhiều: khóa ngoại contact_id đặt trực tiếp trên listings; không tạo bảng trung gian listing_contacts. Một contact có nhiều listings, một listing gắn đúng một contact.
Contact chỉ để hiển thị/liên hệ: không dùng contact/số điện thoại để resolve users/owners; không xác định user sở hữu listing qua contact.
Không resolve user/owner theo số điện thoại: phone_registries được tái dùng làm nơi lưu số điện thoại (contacts trỏ tới qua phone_registry_id), không dùng để xác định user/owner của listing; không đi từ phone_registries.user_id để gán owner.
Tạo listing qua POST /listings (luồng thường): CreateListingRequest nhận property_id, contact_id, source, source_id, source_url. Validate đầy đủ như tin app; không ingest, không bỏ qua validate. Vì dùng chung validate user-facing, payload crawl phải đáp ứng ràng buộc của tin app (field bắt buộc, property_id hợp lệ, ảnh theo chuẩn hệ thống) — cách đáp ứng ràng buộc ảnh cho tin crawl (vd re-host) do Dev quyết.
Owner tin crawl = tài khoản broker tạo sẵn: POST /listings được gọi bằng một tài khoản broker (seed) đã tạo trước; owner của listing crawl là tài khoản broker này (gắn theo JWT như tin app). Vẫn không resolve user/owner theo SĐT — owner đến từ tài khoản broker, không suy ra từ phone_registries.
Trường nguồn trên listings: source (tên nguồn crawl), source_id (id gốc tin tại nguồn), source_url (link gốc tin).
Bỏ bảng data_sources: không lưu staging; thông tin nguồn → listings, thông tin liên hệ → contacts (listing tham chiếu qua listings.contact_id), số điện thoại → phone_registries.
Thứ tự pipeline: source + source_id (bỏ nếu đã có) → kiểm tra số điện thoại (bỏ nếu thiếu) → property (tái dùng/tạo) → phone_registries (tra/tạo theo số điện thoại) → contact (tra/tạo theo phone_registry_id) → POST /listings.
trust_score + routing (giữ — chạy trong luồng POST /listings thường): Backend tính trust_score; trust_score < 80 → Data Marketplace (public, auto-publish, không moderation thủ công); trust_score ≥ 80 → kho lưu trữ Admin (admin-only, không public). Phía crawl không gán trust_score.
3 nguồn bắt buộc gồm Batdongsan (nguồn mới bổ sung) — backend phải chấp nhận source = BATDONGSAN đầy đủ như 2 nguồn còn lại; backend hiện mới nhận nhatot/muaban nên cần mở rộng (cách hiện thực do Dev quyết ở repo BE).
Đã có sự cho phép crawl từ 3 nguồn (Muaban.net, Nhà Tốt, Batdongsan.com.vn); vận hành phải tuân thủ điều khoản đã thỏa thuận.
Listings trong kho lưu trữ Admin không phát event công khai; event nội bộ admin do Dev quyết.
Thông tin liên hệ tuân thủ chính sách masking/permission hiện có của hệ thống (tham chiếu RBAC listing).

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

Bảng contacts (mới) — lưu thông tin liên hệ, quan hệ một-nhiều với listings; số điện thoại nằm ở phone_registries:

Field	Mô tả	Bắt buộc
`id`	ID contact	✓
`contact_name`	Tên người liên hệ	✓ (tối thiểu)
`phone_registry_id`	FK → `phone_registries.id` — nơi lưu số điện thoại liên hệ	✓
`status`	Trạng thái contact	optional
`source`	Nguồn của contact (vd CRAWL)	optional
`note`	Ghi chú	optional
`created_at`	Thời điểm tạo	✓
`updated_at`	Thời điểm cập nhật	✓

contact_name = tên người liên hệ; số điện thoại không lưu trên contacts mà truy cập qua phone_registry_id → phone_registries.phone.
Contact chỉ phục vụ hiển thị/liên lạc; không dùng để resolve users/owners.

Bảng phone_registries (tái dùng) — nơi lưu số điện thoại mà contacts tham chiếu:

Field	Mô tả
`id`	ID bản ghi
`phone`	Số điện thoại liên hệ (khóa tra, nên unique)
`user_id`	(cột hệ thống hiện có) không dùng để resolve owner trong luồng crawl
`is_blocked` / `block_reason`	(cột hệ thống hiện có) tuỳ chính sách
`created_at` / `updated_at`	Thời điểm tạo / cập nhật

Trong luồng crawl, phone_registries chỉ đóng vai kho lưu số điện thoại; không đi từ phone_registries.user_id để xác định user/owner của listing.

Bảng listings — field bổ sung/liên quan luồng crawl (các field khác giữ như tin tạo từ app):

Field	Mô tả	Ai điền
`id`	ID listing	Backend
`property_id`	FK → `properties` (tái dùng nếu khớp)	Crawl resolve
`contact_id`	FK → `contacts.id` (một-nhiều) — mới	Crawl resolve
`title`, `description`, `price`	Nội dung tin	Crawl
`listing_types`	bán / cho thuê	Crawl
`image_urls`	Danh sách URL ảnh	Crawl
`status`	Trạng thái listing	Backend
`source`	Nguồn crawl: MUABAN / NHATOT / BATDONGSAN — mới (trên listings)	Crawl
`source_id`	ID tin tại nguồn gốc — mới	Crawl
`source_url`	Link tin gốc — mới	Crawl
`posted_at`	Thời điểm đăng tại nguồn	Crawl
`scraped_at`	Thời điểm crawl về	Backend/Crawl
`trust_score`	Điểm uy tín (0–100)	Backend
`trust_score_breakdown`	Chi tiết thành phần điểm	Backend
`trust_score_calculated_at`	Thời điểm tính `trust_score`	Backend
`published_at`	Thời điểm publish Data Marketplace (chỉ `trust_score < 80`)	Backend
`created_at` / `updated_at`	Thời điểm tạo / cập nhật	Hệ thống

Không lưu contact_name / số điện thoại trên listings; liên hệ truy cập qua contact_id → contacts → phone_registries.
Các field hệ thống khác của listing (counters, exclusive, expired_at, …) giữ như tin tạo từ app.

Property — resolve qua endpoint hiện có:

Match theo address + area_m2 + property_type_id: khớp → tái dùng property_id; không khớp → POST /properties.
Schema/payload đầy đủ của property thuộc endpoint POST /properties (feature properties) — requirement này chỉ dùng property_id trả về. Thuật toán normalization/threshold match do Dev quyết.

Quan hệ dữ liệu:

contacts.id 1 — N listings.contact_id (một contact, nhiều listings).
contacts.phone_registry_id → phone_registries.id (số điện thoại lưu ở phone_registries; phone nên unique nên mỗi số ↔ một phone_registry ↔ một contact).
listings.property_id → properties.id (tái dùng nếu khớp address + area_m2 + property_type_id).
listings lưu source, source_id, source_url.

Đã loại khỏi luồng crawl: resolve user/owner theo số điện thoại (không resolve users), bảng staging data_sources. (phone_registries được tái dùng làm nơi lưu số điện thoại, không dùng resolve owner.)

Trạng thái listing (status):

Backend quản lý vòng đời listing (vd draft, published, archived, expired… — giá trị cụ thể do Dev quy ước ở repo source).
trust_score < 80 → public trong Data Marketplace (auto-publish, ghi published_at).
trust_score ≥ 80 → archived trong kho lưu trữ Admin, không ghi published_at public.

Event WebSocket:

Event	Khi nào phát	Channel
`LISTING_CREATED`	Listing mới (`trust_score < 80`) trong Data Marketplace	Public
`LISTING_UPDATED`	Listing (`trust_score < 80`) được cập nhật	Public
`LISTING_TRUST_SCORE_UPDATED`	`trust_score` thay đổi sau xử lý Backend	Public (nếu listing đang trong Data Marketplace)
Admin event (Dev quyết)	Listing route vào kho lưu trữ Admin (`trust_score ≥ 80`)	Admin-only

Trạng thái xử lý pipeline crawl:

normalized — đã chuẩn hóa 4 nhóm
skipped_duplicate — source + source_id đã có, bỏ qua
dropped_no_contact — thiếu số điện thoại, bỏ tin
submitted — đã gọi POST /listings
published_marketplace — trust_score < 80, vào Data Marketplace
admin_archived — trust_score ≥ 80, vào kho lưu trữ Admin
failed — lỗi crawl hoặc chuẩn hóa

Liên quan

Phụ thuộc: Chưa có
Ảnh hưởng: broker-daily-listing-distribution — Data Marketplace (tin trust_score < 80) là pool cho Auto Distribution paid tier; routing trust_score ≥ 80 ảnh hưởng pool có sẵn cho broker. Lưu ý: số điện thoại tin crawl nay nằm ở phone_registries.phone, truy cập qua listings.contact_id → contacts.phone_registry_id → phone_registries (không qua users/owner) — feature đó cần điều chỉnh cách lấy phone_full cho tin crawl theo đường này.