TỔNG KHO DỮ LIỆU & CƠ CHẾ VẬN HÀNH CHI TIẾT (ADMIN SYSTEM REFERENCE)

Tài liệu kỹ thuật và vận hành chuyên sâu về mọi khía cạnh của hệ thống Quản trị Nhà Cộng.

CURRENT IMPLEMENTATION NOTES (CODEBASE VERIFIED)

Last Updated: 2026-04-07

✅ Verified UI Routes (Frontend)

• Admin dashboard, users, roles/permissions, moderation (apartment/community/CTV requests).
• CTV approval + management:
  DOCUMENTATION CODECOPY

  /admin/duyet-ctv

  ,
  DOCUMENTATION CODECOPY

  /admin/moderation/ctv-requests

  ,
  DOCUMENTATION CODECOPY

  /admin/quan-ly-cong-tac-vien

  .
• Audit logs, media library, ads, support center, short review, jobs/news/blog.

✅ Verified Admin APIs (Backend)

• Impersonation:
  DOCUMENTATION CODECOPY

  POST /admin/impersonate

  (admin only). Tạo JWT impersonate, ghi log audit + impersonation.
• Audit logs:
  DOCUMENTATION CODECOPY

  GET /admin/audit-logs

  (admin only), có filter
  DOCUMENTATION CODECOPY

  userId

  ,
  DOCUMENTATION CODECOPY

  action

  ,
  DOCUMENTATION CODECOPY

  module

  , phân trang.
• Database management:
  DOCUMENTATION CODECOPY

  GET/POST /admin/database/*

  (admin only) cho backup/restore/settings/check tools và ghi audit log.
• CTV moderation:
  DOCUMENTATION CODECOPY

  GET/POST /admin/ctv-requests/*

  (admin only) duyệt/khước từ CTV.
• CTV payouts:
  DOCUMENTATION CODECOPY

  GET/POST /admin/ctv-payouts/*

  (admin only) duyệt/hoàn tất/batch/export/auto-match.

✅ RBAC & Permissions (Hiện trạng triển khai)

• RolesGuard: dùng
  DOCUMENTATION CODECOPY

  @Roles(...)

  , admin bypass toàn bộ; so khớp role theo chuỗi (case-insensitive).
• PermissionsGuard: có sẵn, dựa vào
  DOCUMENTATION CODECOPY

  roles.permissions

  (JSON) nhưng không thấy controller dùng
  DOCUMENTATION CODECOPY

  @Permissions(...)

  .
• Hệ quả: phân quyền theo permission keys chưa được enforce ở API; hiện phụ thuộc chủ yếu vào
  DOCUMENTATION CODECOPY

  @Roles

  .

✅ Role Model & Permission Catalog

• Bảng
  DOCUMENTATION CODECOPY

  roles

  lưu
  DOCUMENTATION CODECOPY

  name

  ,
  DOCUMENTATION CODECOPY

  permissions

  (JSON string),
  DOCUMENTATION CODECOPY

  ownerId

  .
• Danh mục permission keys đã định nghĩa theo 14 nhóm (Overview, Properties, Finance, Moderation, Ads, ...).

⚠️ Needs Verification (Backend/API)

• RBAC enforcement on API + admin route guards.
• Ticket system SLA + FAQ CMS behavior.
• Ads placement rules/tracking and media optimization pipelines.
• Audit log coverage for sensitive actions.
• Luồng kết thúc impersonation (service có
  DOCUMENTATION CODECOPY

  endImpersonation

  nhưng chưa thấy public endpoint).

1. QUẢN LÝ TÀI KHOẢN & NGƯỜI DÙNG (USER & IDENTITY)

Hệ thống xử lý hàng ngàn tài khoản với 4 vai trò chính:

Admin

Host

CTV

Resident

1.1. Thực thể Người dùng (User Entity)

• Thông tin định danh: Email, SĐT, Password (Hashed), Nickname (Hiển thị cộng đồng), Cấp độ xác minh (KYC).
• Trạng thái tài khoản:
  • DOCUMENTATION CODECOPY

    Active

    : Hoạt động bình thường.
  • DOCUMENTATION CODECOPY

    Blocked

    : Bị khóa do vi phạm chính sách (không thể đăng nhập).
  • DOCUMENTATION CODECOPY

    Unverified

    : Cần xác minh Email/SĐT để sử dụng tính năng đăng tin.
• Xác thực đa tầng: Tích hợp JWT (JSON Web Token) với thời gian hết hạn an toàn.

1.2. Phân quyền chi tiết (RBAC Engine)

Hệ thống sử dụng bảng

Role

• Phân nhóm theo module chính (14 Nhóm):
  1. Tổng Quan: Xem doanh thu, tỷ lệ tăng trưởng User theo thời gian thực (Dashboard).
  2. Căn Hộ: Thêm tòa nhà mới, cấu hình từng phòng (Studio, Duplex, 1PN...).
  3. Khách Hàng: Quản lý phễu Lead (Khách hẹn -> Khách cọc -> Hợp đồng).
  4. Tài Chính: Quyền truy cập vào bảng ghi chỉ số điện nước, tạo hóa đơn tự động và quản lý nợ quá hạn.
  5. Tài Sản: Quản lý kho vật tư, thiết bị. Ghi nhận nhật ký bảo trì cho từng món đồ.
  6. Công Việc: Giao việc cho Fixer (Kỹ thuật) hoặc Helper (Vệ sinh). Theo dõi ảnh chụp "trước và sau" khi hoàn thành.
  7. Báo Cáo: Xuất file Excel báo cáo thuế, báo cáo chi phí vận hành toà nhà.
  8. Tiện Ích: Duyệt bài chợ cư dân, chỉnh sửa cẩm nang số, quản lý điểm tín nhiệm Resident.
  9. Cài Đặt: Cấu hình mẫu hợp đồng, mẫu bàn giao tài sản.
  10. Quản trị Admin: Duyệt hồ sơ Chủ nhà và CTV mới tham gia hệ thống.
  11. Kiểm Duyệt: Action Phê duyệt/Từ chối tin đăng bất động sản (phòng tránh tin ảo).
  12. Vận Hành: Đăng tin khuyến mãi, tin tức thị trường lên trang chủ.
  13. Đối Tác: Quản lý danh sách quán Cafe, Gym liên kết (giảm giá cho Resident).
  14. Quảng Cáo: Quản lý Banner Carousel trang chủ và ghim tin VIP (Featured Listings).

2. QUY TRÌNH KIỂM DUYỆT BẤT ĐỘNG SẢN (LISTING MODERATION)

Để đảm bảo chất lượng tin đăng, Admin thực hiện quy trình 3 bước:

1. Bước 1: Tiếp nhận (Queue): Tin đăng mới từ Host sẽ vào hàng chờ
   DOCUMENTATION CODECOPY

   admin.moderation.apartment

   .
2. Bước 2: Đối soát (Verification):
   • Hình ảnh: Phải thực tế, không dính logo bên thứ 3, chụp đủ các góc.
   • Vị trí: Tọa độ Map phải chính xác (được định vị qua Google Maps API).
   • Tiện ích: Kiểm tra các checkbox (エアコン, Wi-Fi, Thang máy...) có khớp với mô tả.
3. Bước 3: Công bố (Publish):
   • Approved: Tin hiển thị lên bản đồ tìm kiếm toàn quốc.
   • Rejected: Host nhận thông báo lỗi kèm lý do cụ thể để sửa lại.

3. CỘNG TÁC VIÊN & CHIẾN LƯỢC TĂNG TRƯỞNG (CTV & GROWTH)

Hệ thống Affiliate (Tiếp thị liên kết) là động cơ tăng trưởng chính của Nhà Cộng.

3.1. Cơ chế Cookie & Attribution

• Thời gian lưu Cookie: 30 ngày (Khách click link CTV, trong 30 ngày sau đó nếu quay lại thuê thì CTV vẫn được tính hoa hồng).
• Link Generator: Tự động gán mã
  DOCUMENTATION CODECOPY

  aff_id

  vào URL khi CTV chia sẻ tin đăng từ trang Admin.

3.2. Cấp bậc & Hoa hồng (Tiers)

• Cấp Starter: Hoa hồng tính theo mỗi deal thành công (Ví dụ: 1 triệu/deal).
• Cấp Pro: Thưởng thêm % doanh thu khi đạt ngưỡng 5 deal/tháng.
• Cấp Partner (Môi giới chuyên nghiệp): Hưởng hoa hồng trọn đời từ các Resident mà họ đã giới thiệu khi Resident gia hạn hợp đồng.

3.3. Duyệt rút tiền (Payouts)

• Ngưỡng rút: Tối thiểu 500,000 VND.
• Trạng thái Payout:
  DOCUMENTATION CODECOPY

  Pending

  (Chờ duyệt) ->
  DOCUMENTATION CODECOPY

  Bank Transferring

  ->
  DOCUMENTATION CODECOPY

  Completed

  .
• Báo cáo thuế: Tự động trích xuất dữ liệu để nộp thuế TNCN cho CTV nếu vượt ngưỡng.

4. QUẢN LÝ MEDIA & QUẢNG CÁO (ADS CMS)

4.1. Media Library

Admin quản lý toàn bộ kho ảnh/video được tải lên hệ thống.

• Optimize: Ảnh được tự động nén và resize để tăng tốc độ tải trang.
• Storage: Lưu trữ trên Cloud (AWS S3 / Firebase) đảm bảo dữ liệu không bao giờ mất.

4.2. Ad Placement (Bán vị trí)

Hệ thống cho phép cấu hình các vị trí quảng cáo "đắc địa":

• Home Carousel: Banner lớn tại trang đầu.
• Featured Sidebar: Hiển thị tại các trang danh sách phòng.
• Sticky Search: Hiển thị gợi ý phòng nổi bật ngay khi User bắt đầu tìm kiếm.

5. HỆ THỐNG HỖ TRỢ & FAQ (TICKET SYSTEM)

Module Trung tâm hỗ trợ giúp kết nối User với Admin Nhà Cộng:

• Phân loại Ticket: Lỗi kỹ thuật, Khiếu nại chủ nhà, Hỗ trợ CTV, thắc mắc tài chính.
• SLA (Service Level Agreement): Admin giám sát thời gian phản hồi (Ví dụ: Phải trả lời trong 4h làm việc).
• FAQ CMS: Cho phép Admin cập nhật nhanh các câu hỏi thường gặp để giảm tải cho bộ phận Support.

6. NHẬT KÝ HỆ THỐNG (AUDIT LOGS)

Bảo mật tuyệt đối thông qua việc ghi lại mọi hành vi nhạy cảm:

• Dữ liệu log: ID người dùng, Loại hành động (CREATE/UPDATE/DELETE), Thời gian, ID thực thể bị tác động, Dữ liệu trước và sau khi thay đổi (JSON Diff).
• Mục tiêu: Truy vết khi có sự cố dữ liệu hoặc gian lận tài chính.

7. QUẢN LÝ TUYỂN DỤNG & SHORT REVIEW

7.1. Job Portal

• Quản lý các tin tuyển dụng Môi giới, Kỹ thuật, Helper.
• Host có thể đăng tin thuê CTV thông qua module này.

7.2. Short Review (Nội dung cộng đồng)

• Duyệt và quản lý các video/ảnh đánh giá từ cộng đồng cư dân.
• Xóa các bài đăng có dấu hiệu hạ uy tín đối thủ hoặc thông tin sai lệch.