75 lines
4.7 KiB
Markdown
75 lines
4.7 KiB
Markdown
# 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.*
|