Bỏ qua nội dung
VNexus VNexus Requirement

Properties - tạo bất động sản

Feature URL
Module
properties
Status
shipped
Priority
P0
Platforms
fe · be
AC progress
8 / 8
Last reviewed
2026-05-29

Mục tiêu

Cho phép user đã đăng nhập tạo một bản ghi bất động sản (property) — lớp dữ liệu vật lý của BĐS, tách khỏi tin đăng. Nhờ tách property khỏi listing, mỗi BĐS chỉ lưu một lần và được nhiều tin đăng cũng như luồng crawl tái sử dụng qua property_id.

Phạm vi

Trong phạm vi (In scope):

  • Tạo property qua POST /properties, gắn owner là user đang đăng nhập.
  • Nhập thông tin vị trí: số nhà, hẻm, đường, phường, tỉnh, địa chỉ và toạ độ (longitude, latitude).
  • Nhập thông tin vật lý: diện tích, chiều rộng/dài, hướng nhà, hướng ban công, số phòng ngủ, số phòng tắm, số tầng, nội thất và các thông số liên quan.
  • Chọn loại BĐS qua propertyTypeCode; server tra cứu thành PropertyType.
  • Đính kèm hồ sơ pháp lý (LegalDocument) tuỳ chọn ngay khi tạo.
  • Mặc định trạng thái ACTIVE khi tạo.

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

  • Cập nhật hoặc xoá property, xem properties-update và properties-delete.
  • Tạo tin đăng/listing, xem listing-create.
  • Thuật toán chuẩn hoá địa chỉ và rule match/tái dùng property (Dev quyết ở repo BE).
  • Quản lý danh mục PropertyType (đã seed sẵn).
  • Chi tiết schema vật lý, index hoặc migration.

User Stories

  • Là user đã đăng nhập, tôi muốn tạo property cho BĐS của mình, để tái dùng cho nhiều tin đăng mà không nhập lại thông tin.
  • Là user, tôi muốn đính kèm hồ sơ pháp lý khi tạo property, để lưu giấy tờ liên quan tập trung một chỗ.
  • Là hệ thống crawl, tôi muốn tạo property mới qua POST /properties khi chưa có BĐS tương ứng, để mỗi BĐS chỉ tồn tại một property.

Luồng chức năng

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

    User->>App: Nhập thông tin bất động sản
    App->>BE: Gửi yêu cầu tạo property
    BE->>Types: Tra propertyTypeCode
    Types-->>BE: Property type hợp lệ
    BE->>PropertySvc: Tạo property status ACTIVE
    alt Có hồ sơ pháp lý
        BE->>PropertySvc: Tạo legal document đính kèm
    end
    PropertySvc-->>BE: Trả property id
    BE-->>App: Trả property đã tạo

Acceptance Criteria

  • AC-1: POST /properties yêu cầu user đã đăng nhập và quyền property:create.
  • AC-2: Body nhận các trường vị trí và vật lý của BĐS; propertyTypeCode bắt buộc để xác định loại.
  • AC-3: propertyTypeCode phải khớp một PropertyType tồn tại; không khớp thì hệ thống từ chối tạo.
  • AC-4: Property tạo thành công thuộc sở hữu của user đang đăng nhập (createdBy).
  • AC-5: status mặc định là ACTIVE khi client không truyền.
  • AC-6: Nếu request có hồ sơ pháp lý, hệ thống tạo LegalDocument quan hệ 1-1 và gắn vào property.
  • AC-7: fileUrls của hồ sơ pháp lý nhận tối đa 20 đường dẫn.
  • AC-8: Response trả property vừa tạo gồm id, loại, các trường vị trí/vật lý, status và hồ sơ pháp lý nếu có.

Quy tắc nghiệp vụ

  • Mỗi property thuộc đúng một user owner xác định qua createdBy.
  • propertyTypeCode được tra ở server thành PropertyType; client không tự gán id loại.
  • allowedFields của mỗi PropertyType là whitelist các trường hợp lệ cho loại đó (ví dụ đất nền không có số phòng ngủ).
  • Property là lớp dữ liệu vật lý tách khỏi listing; một property có thể gắn nhiều listing.
  • Toạ độ longitude và latitude theo chuẩn WGS-84.
  • Hồ sơ pháp lý quan hệ 1-1 với property; documentType bắt buộc khi có hồ sơ.

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

Entity nghiệp vụ:

  • Property: BĐS vật lý gồm vị trí, toạ độ, thông số vật lý, loại, owner và hồ sơ pháp lý.
  • PropertyType: danh mục loại BĐS gồm code, name và allowedFields.
  • LegalDocument: hồ sơ pháp lý quan hệ 1-1 với property (loại giấy tờ, số, thửa, tờ bản đồ, hình thức và thời hạn sử dụng đất, ngày cấp, nơi cấp, danh sách file, ghi chú).
  • CreatePropertyRequest: payload tạo property gồm các trường vị trí/vật lý, propertyTypeCode và LegalDocumentRequest tuỳ chọn.
  • PropertyResponse: property trả về cho client.

Trạng thái user-facing:

  • ACTIVE — property đang hoạt động, có thể gắn listing và xuất hiện trong tìm kiếm public.
  • INACTIVE — property ngừng hoạt động (do owner ngưng hoặc đã soft-delete).

Loại BĐS (PropertyType, seed sẵn):

  • căn hộ chung cư, chung cư mini, nhà ở, nhà biệt thự độc lập, biệt thự liền kề, shophouse, penthouse, đất thổ cư, đất nền dự án, đất nông nghiệp, trang trại/khu nghỉ dưỡng, kho/nhà xưởng, loại khác.

Endpoint BE hiện có:

  • POST /properties — tạo property (quyền property:create).

Liên quan