Bỏ qua nội dung
VNexus VNexus Requirement

Admin xem và tìm kiếm danh sách property

Feature URL
Module
admin
Status
in-development
Priority
P1
Platforms
fe · be
AC progress
12 / 14
Last reviewed
2026-05-30

Mục tiêu

Cho phép admin xem toàn bộ property trong hệ thống trên màn quản trị, tìm kiếm theo keyword địa chỉ và lọc theo nhiều tiêu chí bao gồm cả bản ghi INACTIVE và đã soft-delete. Đây là màn entry để admin truy cập chi tiết, sửa hoặc xoá property bất kỳ.

Phạm vi

Trong phạm vi (In scope):

  • Admin truy cập trang /admin/properties.
  • API GET /api/v1/admin/properties trả property ở mọi status, kể cả bản ghi đã soft-delete.
  • Filter theo: keyword, province, ward, propertyTypeCode, status (ACTIVE/INACTIVE), ownerId, deleted (tri-state: null/true/false), minArea, maxArea, bedrooms, bathrooms, houseDirections, balconyDirections, legalDocumentType, interior, hasLegalDocument, createdFrom, createdTo.
  • Pagination/sort theo Spring Pageable, mặc định size=20, sort createdAt DESC.
  • Response dùng AdminPropertyResponse bọc PropertyDetailResponse và thêm metadata soft-delete.
  • FE hiển thị table/list, filter controls, pagination, loading/error/empty state.

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

  • Xem chi tiết property, xem feature admin-property-detail.
  • Sửa property, xem feature admin-property-edit.
  • Xoá property, xem feature admin-property-delete.
  • Export CSV hoặc bulk action.

User Stories

  • Là admin, tôi muốn xem toàn bộ property kể cả INACTIVE và đã xoá để giám sát dữ liệu bất động sản hệ thống.
  • Là admin vận hành, tôi muốn lọc property theo địa chỉ, trạng thái, chủ sở hữu, diện tích để phát hiện dữ liệu bất thường.
  • Là admin support, tôi muốn tìm property theo keyword địa chỉ để hỗ trợ người dùng nhanh chóng.

Luồng chức năng

sequenceDiagram
    actor Admin
    participant Web
    participant BE
    participant DB

    Admin->>Web: Mở /admin/properties
    Web->>BE: GET /api/v1/admin/properties?keyword=&status=&page=0&size=20
    BE->>BE: Kiểm tra role admin
    BE->>BE: Validate filters
    BE->>DB: Query property theo Specification mọi status và deleted
    BE->>DB: Batch load listings cho page hiện tại
    BE-->>Web: PageResponse AdminPropertyResponse
    Web->>Admin: Render danh sách property + filter + pagination

Acceptance Criteria

  • AC-1: Backend có GET /api/v1/admin/properties, class-level @PreAuthorize("hasRole('admin')").
  • AC-2: API trả property ở mọi status ACTIVE và INACTIVE, kể cả bản ghi đã soft-delete.
  • AC-3: keyword match case-insensitive trên address và normalizedAddress, tối đa 200 ký tự.
  • AC-4: status chỉ nhận ACTIVE hoặc INACTIVE; bỏ trống trả mọi status.
  • AC-5: deleted là tri-state: null trả tất cả, true chỉ soft-deleted, false chỉ chưa xoá.
  • AC-6: ownerId lọc theo UUID chủ property, optional.
  • AC-7: minArea/maxArea phải là số không âm.
  • AC-8: bedrooms/bathrooms phải là số không âm.
  • AC-9: houseDirections/balconyDirections nhận tối đa 8 giá trị, mỗi giá trị tối đa 100 ký tự.
  • AC-10: createdFrom/createdTo là OffsetDateTime dùng để filter theo createdAt.
  • AC-11: Backend batch-load listings theo danh sách property id để tránh N+1.
  • AC-12: Response item gồm PropertyDetailResponse (owner + listings + legalDocument đầy đủ) và thêm deleted, deletedAt, deletedByUserId.
  • AC-13: FE /admin/properties cần table/list với filter controls và pagination.
  • AC-14: FE xử lý loading/error/empty state.

Quy tắc nghiệp vụ

  • Chỉ admin được truy cập danh sách property quản trị.
  • Admin thấy cả ACTIVE, INACTIVE và bản ghi đã soft-delete; khác với endpoint public/owner chỉ trả ACTIVE chưa xoá.
  • Mặc định (không truyền deleted) trả tất cả hàng kể cả đã xoá.
  • Sort mặc định createdAt DESC; có thể sort theo updatedAt.
  • Backend batch-load listings để tránh N+1 query cho mỗi page.

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

Entity nghiệp vụ:

  • Property: bất động sản — nguồn dữ liệu danh sách.
  • AdminPropertySearchRequest: filter query params (keyword, status, ownerId, deleted, minArea, maxArea, bedrooms, bathrooms, houseDirections, balconyDirections, legalDocumentType, interior, hasLegalDocument, createdFrom, createdTo).
  • AdminPropertyResponse: row bọc PropertyDetailResponse và thêm deleted, deletedAt, deletedByUserId.
  • PageResponse<AdminPropertyResponse>: pagination contract.

Trạng thái user-facing:

  • list-loading — đang tải danh sách.
  • list-ready — có dữ liệu.
  • list-empty — không có property khớp filter.
  • filter-invalid — filter không hợp lệ (status/area không đúng định dạng).
  • list-error — lỗi tải danh sách.

Liên quan