Properties - tìm kiếm và xem chi tiết bất động sản

Feature URL

Module

properties

Status

shipped

Priority

Platforms

fe · be

AC progress

7 / 7

Last reviewed

2026-05-29

Mục tiêu

Cho phép tìm kiếm bất động sản công khai theo nhiều bộ lọc, cho user xem danh sách property do chính mình tạo, và mở chi tiết một property kèm các tin đăng liên quan. Đây là cửa đọc dữ liệu của lớp property dùng chung cho luồng listing.

Phạm vi

Trong phạm vi (In scope):

Tìm kiếm public qua GET /properties với bộ lọc và phân trang; public chỉ thấy property ACTIVE.
Liệt kê property của user qua GET /properties/me (quyền property:read).
Xem chi tiết một property qua GET /properties/{id}.
Chi tiết kèm danh sách tin đăng liên quan và thông tin người tạo.
Bộ lọc: từ khoá, tỉnh, phường, loại BĐS, diện tích tối thiểu/tối đa, số phòng ngủ, số phòng tắm, hướng nhà, hướng ban công, loại giấy tờ, nội thất và cờ có hồ sơ pháp lý.

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

Tạo, cập nhật hoặc xoá property.
Tìm kiếm toàn trạng thái của admin qua /admin/properties — chỉ tham chiếu.
Thuật toán xếp hạng/sort nâng cao (Dev quyết ở repo BE).

User Stories

Là người dùng/khách, tôi muốn tìm BĐS theo địa bàn, loại, diện tích và đặc điểm, để lọc nhanh đúng nhu cầu.
Là user, tôi muốn xem danh sách property của mình, để quản lý và chọn property khi tạo tin đăng.
Là user, tôi muốn mở chi tiết một property kèm các tin đăng liên quan, để biết BĐS đang được rao như thế nào.

Luồng chức năng

sequenceDiagram
    actor User
    participant App as FE/Mobile
    participant BE
    participant PropertySvc as Properties
    participant Listings

    User->>App: Tìm bất động sản theo bộ lọc
    App->>BE: Gửi yêu cầu tìm kiếm property
    BE->>PropertySvc: Lấy property ACTIVE theo filter
    PropertySvc-->>BE: Danh sách property
    BE-->>App: Trả danh sách phân trang
    User->>App: Mở chi tiết property
    App->>BE: Gửi yêu cầu xem chi tiết property
    BE->>Listings: Lấy listing liên quan
    BE-->>App: Trả chi tiết property kèm listing

Acceptance Criteria

AC-1: GET /properties trả về property đang ACTIVE cho public, hỗ trợ bộ lọc và phân trang.
AC-2: GET /properties/me yêu cầu quyền property:read và chỉ trả property do user đang đăng nhập tạo.
AC-3: GET /properties/{id} trả chi tiết một property tồn tại và chưa bị xoá.
AC-4: Owner và admin xem được hồ sơ pháp lý đầy đủ; người xem khác chỉ thấy bản tóm tắt hồ sơ pháp lý.
AC-5: Chi tiết property hiển thị danh sách tin đăng liên quan và thông tin người tạo.
AC-6: Bộ lọc hỗ trợ từ khoá, tỉnh, phường, loại BĐS, diện tích, số phòng, hướng, loại giấy tờ, nội thất và cờ có hồ sơ pháp lý.
AC-7: Property INACTIVE hoặc đã soft-delete không xuất hiện trong tìm kiếm public.

Quy tắc nghiệp vụ

Tìm kiếm public chỉ trả property ACTIVE; property INACTIVE và đã soft-delete bị ẩn khỏi luồng public.
Hồ sơ pháp lý có hai mức hiển thị: bản tóm tắt cho người xem thường và bản đầy đủ cho owner hoặc admin.
GET /properties/me chỉ trả property thuộc về chính user đang đăng nhập.
Chi tiết property hiển thị các tin đăng liên quan nếu BĐS đó đang được rao.

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

Entity nghiệp vụ:

Property: bản ghi BĐS được liệt kê và xem chi tiết.
PropertyType: loại BĐS dùng để lọc và hiển thị.
LegalDocument: hồ sơ pháp lý hiển thị theo mức tóm tắt hoặc đầy đủ.
Listing: tin đăng liên quan, tham chiếu property qua property_id.
PropertySearchRequest: bộ lọc tìm kiếm property.
PropertyResponse: property trong danh sách (dạng phẳng).
PropertyDetailResponse: chi tiết property kèm người tạo và danh sách tin đăng liên quan.

Trạng thái user-facing:

empty — không có property nào khớp phạm vi xem.
has_results — có property khớp danh sách hoặc tìm kiếm.
not_found — property không tồn tại, đã xoá hoặc người xem không có quyền.

Endpoint BE hiện có:

GET /properties — tìm kiếm public property ACTIVE, bộ lọc và phân trang.
GET /properties/me — danh sách property của user (quyền property:read).
GET /properties/{id} — chi tiết property, mức hiển thị hồ sơ pháp lý theo người xem.

Liên quan

Phụ thuộc: properties-create
Ảnh hưởng: Chưa có