HQLAND PROJECT BLUEPRINT (V1.0)

Project Memory & Implementation Guide for AI Agents

Tên dự án: HQLand - Hệ thống quản lý Bất động sản tập trung.
Mục tiêu: Quản lý kho hàng (Warehouse), Khách hàng (CRM), Hợp đồng (Contracts) và Dòng tiền (Finance).
Đặc thù: Xử lý dữ liệu lớn từ Excel, quản lý lịch sử chuyển nhượng phức tạp (F0, F1, F2...), và tự động hóa lịch trình thanh toán.

Framework: Laravel 13.x.
PHP Version: 8.3 (Lưu ý: Một số thư viện Symfony v8.x yêu cầu PHP 8.4 nên đã được hạ cấp xuống v7.x để tương thích).
Admin Panel: Filament v5.5 (Mô phỏng release tương lai).
Kiến trúc UI: Schemas Architecture (Bắt buộc). Tách biệt định nghĩa Form/Table ra khỏi Resource.
Database: PostgreSQL.
Quy chuẩn Database:
- Khóa chính: UUID (100% các bảng).
- Naming: snake_case cho mọi bảng và cột.
- Chuẩn logic: Prisma Schema v2.3.

Project: Quản lý dự án (Mã dự án, Tên dự án).
Product: Lô đất hoặc Căn hộ.
- product_type: LAND, APARTMENT.
- infrastructure_status: JSONB lưu trạng thái (Đường, Điện, Nước...).
- custom_data: JSONB lưu thông số đặc thù (Mật độ xây dựng, block...).

Customer: Hỗ trợ 2 loại INDIVIDUAL (Cá nhân) và COMPANY (Pháp nhân).
- Logic Địa chỉ: Lưu "cứng" 2 cột permanent_address và contact_address (không dùng JSON cho địa chỉ chính).
- Logic Công ty: Sử dụng tự tham chiếu (Self-referencing) qua representative_id. Một Công ty sẽ liên kết với một Khách hàng cá nhân đóng vai trò người đại diện.
- Số điện thoại: phone (chính) và secondary_phones (JSONB - mảng số phụ).

Contract: Trung tâm của hệ thống.
- Logic Chuyển nhượng (transfer_order):
  - 0: Chủ sở hữu hiện tại (Đang hiệu lực).
  - 1: Hợp đồng gốc (F0).
  - 2+: Các đời tiếp theo (F1, F2...).
- Tài chính: Lưu snapshot giá trị tại thời điểm ký (land_value, foundation_value, total_value).
- Chiết khấu: discount_details (JSONB) lưu mọi loại ưu đãi (Bán sỉ, mở bán, CTV...).

Import Sản phẩm: Tự động bóc tách chuỗi hạ tầng phức tạp từ Excel thành JSON có cấu trúc.
Import Khách hàng: Tự động nhận diện 2 số điện thoại, định dạng ngày tháng Excel, và thiết lập quan hệ Công ty/Người đại diện.
Import Hợp đồng (Phức hợp): Logic "Bắc cầu" giữa 2 file Excel (hopdong.xlsx và Hd_kh.xlsx) để nối Khách hàng - Hợp đồng - Sản phẩm dựa trên mã lô đất.
Surplus Logic: (Đã thiết kế) Tiền nộp thừa sẽ lưu vào excess_amount để khấu trừ cho đợt sau.

UI Consistenty: LUÔN sử dụng Schemas class. KHÔNG định nghĩa inline trong Resource.
Filament Layout: Trong bản v5.5 này, Grid và Section nằm trong Filament\Schemas\Components, không phải Filament\Forms\Components.
Màu sắc UI: Khi render HTML động trong Form (như bảng hạ tầng), sử dụng Inline Styles thay vì Tailwind class để tránh bị PurgeCSS loại bỏ.
Database Safety: Tuyệt đối không dùng migrate:fresh trên môi trường đang có dữ liệu tài khoản người dùng (taikhoan.txt).
Data Casting: Mọi trường JSONB trong Model phải được khai báo trong $casts = ['field' => 'array'].

Module Chiết khấu (Discounts): Xây dựng engine tính toán dựa trên discount_details.
Tự động hóa Lịch trình: Viết lệnh chạy ngầm để tạo PaymentSchedule cho 139 hợp đồng vừa import dựa trên PaymentTemplate.
Module Thu tiền (Payments): Ghi nhận phiếu thu và tự động đối soát công nợ từng đợt.
Báo cáo (Reporting): Dashboard thống kê doanh thu theo Dự án, dòng tiền dự kiến trong tương lai.

Blueprint created on April 23, 2026. Sync this file to all sub-agents before proceeding.