Bỏ qua nội dung
VNexus VNexus Requirement

Properties - cập nhật 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 owner cập nhật toàn bộ thông tin một property theo cơ chế full-replace, đồng thời upsert hoặc gỡ hồ sơ pháp lý kèm theo, mà không làm mất liên kết với các tin đăng đang tham chiếu. Admin có thể chỉnh sửa property của bất kỳ user nào để xử lý sai lệch dữ liệu.

Phạm vi

Trong phạm vi (In scope):

  • Cập nhật property qua PUT /properties/{id} cho owner (quyền property:update:own), thay thế toàn bộ trường của property.
  • Upsert hồ sơ pháp lý: có trong request thì tạo mới hoặc cập nhật; không có thì gỡ hồ sơ cũ.
  • status là trường bắt buộc trong request cập nhật.
  • Giữ nguyên property_id và liên kết với các listing đang tham chiếu.
  • Admin force-edit qua PUT /admin/properties/{id} (tham chiếu, quyền admin).

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

  • Tạo hoặc xoá property.
  • Đổi owner (createdBy) của property.
  • Sửa property gián tiếp qua endpoint listing (listing-update không đổi property).
  • Quản lý danh mục PropertyType.

User Stories

  • Là owner, tôi muốn cập nhật thông tin BĐS, để dữ liệu luôn đúng cho mọi tin đăng đang dùng property đó.
  • Là owner, tôi muốn cập nhật hoặc gỡ hồ sơ pháp lý, để hồ sơ luôn phản ánh giấy tờ hiện tại.
  • Là admin, tôi muốn chỉnh sửa property của bất kỳ user nào, để xử lý dữ liệu sai lệch hoặc vi phạm.

Luồng chức năng

sequenceDiagram
    actor Owner
    participant App as FE/Mobile
    participant BE
    participant PropertySvc as Properties

    Owner->>App: Chỉnh sửa bất động sản
    App->>BE: Gửi yêu cầu cập nhật property
    BE->>PropertySvc: Kiểm tra quyền owner
    alt Có hồ sơ pháp lý trong request
        BE->>PropertySvc: Upsert legal document
    else Không có hồ sơ pháp lý
        BE->>PropertySvc: Gỡ legal document cũ
    end
    BE->>PropertySvc: Cập nhật property full-replace
    PropertySvc-->>BE: Property sau cập nhật
    BE-->>App: Trả property đã cập nhật

Acceptance Criteria

  • AC-1: PUT /properties/{id} chỉ cho owner của property (quyền property:update:own).
  • AC-2: Cập nhật theo full-replace; trạng thái property sau cập nhật phản ánh đúng dữ liệu trong request.
  • AC-3: status là trường bắt buộc trong request cập nhật.
  • AC-4: Nếu request có hồ sơ pháp lý, hệ thống tạo mới hoặc cập nhật LegalDocument; nếu không có, hồ sơ pháp lý hiện tại bị gỡ.
  • AC-5: Cập nhật không thay đổi property_id và không phá vỡ liên kết với các listing đang tham chiếu.
  • AC-6: Nếu đổi propertyTypeCode, giá trị mới phải khớp một PropertyType tồn tại.
  • AC-7: Admin cập nhật được property của bất kỳ user nào qua PUT /admin/properties/{id}.
  • AC-8: Người không phải owner và không phải admin bị từ chối cập nhật.

Quy tắc nghiệp vụ

  • Chỉ owner (hoặc admin) được cập nhật một property.
  • Cập nhật là full-replace: client phải gửi đầy đủ trạng thái mong muốn của property.
  • Hồ sơ pháp lý theo cơ chế upsert hoặc gỡ dựa trên sự hiện diện trong request.
  • Không đổi createdBy qua luồng cập nhật.
  • Listing đang gắn property giữ nguyên liên kết sau khi cập nhật.

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

Entity nghiệp vụ:

  • Property: bản ghi được cập nhật nhưng giữ nguyên định danh property_id.
  • LegalDocument: hồ sơ pháp lý được upsert hoặc gỡ theo request.
  • UpdatePropertyRequest: payload cập nhật (full-replace), trong đó status bắt buộc.
  • PropertyResponse: property sau cập nhật trả cho client.
  • AdminPropertyResponse: property trả cho luồng admin.

Trạng thái user-facing:

  • updated — property cập nhật thành công.
  • invalid — dữ liệu cập nhật không đạt rule nghiệp vụ tối thiểu.
  • forbidden — người gọi không phải owner và không phải admin.
  • not_found — property không tồn tại hoặc đã bị xoá.

Endpoint BE hiện có:

  • PUT /properties/{id} — owner cập nhật full-replace (quyền property:update:own).
  • PUT /admin/properties/{id} — admin cập nhật bất kỳ property (quyền admin).

Liên quan