# HQLAND PROJECT BLUEPRINT (V1.0)
## Project Memory & Implementation Guide for AI Agents

### 1. TỔNG QUAN DỰ ÁN
- **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.

---

### 2. KIẾN TRÚC KỸ THUẬT (TECH STACK)
- **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**.

---

### 3. CẤU TRÚC DỮ LIỆU CỐT LÕI (CORE DATA SCHEMA)

#### 3.1. Warehouse (Kho hàng)
- **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...).

#### 3.2. CRM (Khách hàng)
- **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ụ).

#### 3.3. Contracts (Hợp đồng & Tài chính)
- **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...).

---

### 4. LOGIC NGHIỆP VỤ ĐÃ CÀI ĐẶT
1. **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.
2. **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.
3. **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.
4. **Surplus Logic:** (Đã thiết kế) Tiền nộp thừa sẽ lưu vào `excess_amount` để khấu trừ cho đợt sau.

---

### 5. BÀI HỌC KINH NGHIỆM & QUY TẮC PHÁT TRIỂN (CRITICAL)
1. **UI Consistenty:** LUÔN sử dụng `Schemas` class. KHÔNG định nghĩa inline trong Resource.
2. **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`.
3. **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ỏ.
4. **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`).
5. **Data Casting:** Mọi trường JSONB trong Model phải được khai báo trong `$casts = ['field' => 'array']`.

---

### 6. LỘ TRÌNH PHÁT TRIỂN TIẾP THEO (NEXT STEPS)
1. **Module Chiết khấu (Discounts):** Xây dựng engine tính toán dựa trên `discount_details`.
2. **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`.
3. **Module Thu tiền (Payments):** Ghi nhận phiếu thu và tự động đối soát công nợ từng đợt.
4. **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.*
