# HQLAND - ĐÁNH GIÁ HIỆN TRẠNG & ĐỀ XUẤT PHÁT TRIỂN

> Đánh giá khách quan sau phiên làm việc 28/04/2026  
> Ngườ đánh giá: AI Assistant (Kimi)  
> **Lưu ý:** Đây là đánh giá tự phê bình để cải thiện chất lượng hệ thống

---

## I. ĐIỂM MẠNH (Đã hoàn thành tốt)

### 1. Kiến trúc kỹ thuật
- **Schemas Architecture:** Tách biệt Form/Table ra khỏi Resource → code gọn gàng, dễ bảo trì
- **UUID 100%:** Phù hợp với hệ thống phân tán, khó đoán ID
- **PostgreSQL + JSONB:** Tận dụng tốt khả năng lưu trữ linh hoạt của Postgres
- **Testing:** PHPUnit cấu hình đúng PostgreSQL, test tự động chạy được

### 2. Nghiệp vụ tài chính
- **Calculation Pipeline:** Tính toán step-by-step có làm tròn tại mỗi bước → đúng chuẩn kế toán
- **PaymentObserver:** Tự động tính công nợ + khấu trừ dư → giảm sai sót thủ công
- **Lịch thanh toán:** Tạo từ template, hỗ trợ nhiều đợt với ngày đến hạn linh hoạt
- **Form Templates:** Mail Merge Engine cho phép admin tự tạo mẫu in → giảm phụ thuộc dev

### 3. Import dữ liệu
- Import Excel cho Products, Customers, Contracts đều hoạt động
- Xử lý được ngày tháng Excel (serial number), số điện thoại phức tạp
- Logic "bắc cầu" 2 file hợp đồng khá thông minh

---

## II. ĐIỂM YẾU & LỖI TIỀM ẨN (Cần sửa gấp)

### 🔴 Nghiêm trọng - Có thể crash/mất dữ liệu

| # | Vấn đề | Mô tả | Hệ quả |
|---|--------|-------|--------|
| 1 | **~~MailMergeService dùng `eval()`~~ [ĐÃ SỬA]** | `safeEval()` execute string bằng `eval('return ' . $expression)` | Nếu sanitize lỗi → Remote Code Execution. Hiện filter regex chưa đủ chặt |
| 2 | **~~`Contract::saved()` gọi `saveQuietly()`~~ [ĐÃ SỬA]** | Sau khi save HĐ, trigger tính toán rồi save lại | Nếu logic thay đổi → infinite loop. Hiện tại may mắn không loop vì chỉ update `calculation_log` nhưng rủi ro cao |
| 3 | **~~Không có Transaction~~ [ĐÃ SỬA]** | `ImportContractsComplex` dùng `DB::beginTransaction` nhưng các service khác không | Nếu tạo HĐ thành công nhưng tạo lịch TT lỗi → dữ liệu lệch |
| 4 | **~~Không có Soft Delete~~ [ĐÃ SỬA]** | Đã thêm SoftDeletes cho Contract, Payment, Customer + Restore/ForceDelete UI | Xóa nhầm → có thể khôi phục, audit được |

### 🟡 Trung bình - Ảnh hưởng trải nghiệm

| # | Vấn đề | Mô tả |
|---|--------|-------|
| 5 | **Chưa có phân quyền** | Chỉ có 1 loại user, ai cũng vào được mọi chức năng | Nhân viên thu ngân có thể xóa HĐ, sửa giá |
| 6 | **Chưa có API** | Hiện chỉ có Filament Admin Panel | Không làm app mobile, không tích hợp với website bán hàng |
| 7 | **ContractForm chưa hiển thị `calculation_log` đúng** | Khi create HĐ mới, `final_value_display` dùng `DiscountEngine` cũ thay vì Pipeline | Giá trị hiển thị có thể khác với giá trị lưu DB |
| 8 | **~~Payment chưa liên kết ngườ thu~~ [ĐÃ SỬA]** | Đã thêm `collected_by` (foreign key → users) + hiển thị trong Form/Table | Ghi nhận rõ ngườ thu tiền |
| 9 | **Chưa có sổ quỹ** | Thu tiền nhưng không ghi nhận vào quỹ tiền mặt/ngân hàng | Không đối soát được thực thu với ngân hàng |

### 🟢 Thấp - Cần cải thiện lâu dài

| # | Vấn đề | Mô tả |
|---|--------|-------|
| 10 | **Chưa có CRM Pipeline** | Không quản lý khách hàng tiềm năng (Lead) | Mất dữ liệu khách hàng đến xem nhà nhưng chưa mua |
| 11 | **~~Không có đợt mở bán~~ [ĐÃ SỬA]** | Sản phẩm chỉ có status "Đang mở bán", không có đợt/bLOCK mở bán riêng | Không áp dụng chính sách giá khác nhau theo đợt |
| 12 | **Chưa có báo cáo BCTC** | Chỉ có Dashboard widget đơn giản | Kế toán không lấy được báo cáo theo quý/năm để nộp thuế |
| 13 | **Không có quản lý hạ tầng sau bán** | `infrastructure_status` chỉ là JSONB tĩnh | Không theo dõi bảo hành đường, điện, nước |

---

## III. SO SÁNH VỚI CHUẨN NGÀNH BĐS VIỆT NAM

| Tiêu chí | HQLand hiện tại | Phần mềm BĐS chuyên nghiệp (Landsoft, REE) | Khoảng cách |
|----------|----------------|------------------------------------------|-------------|
| **CRM Lead** | Không có | Quản lý khách đến từ Facebook, sàn... | 🔴 Thiếu |
| **Pipeline bán hàng** | Không có | Lead → Chăm sóc → Giữ chỗ → HĐMB | 🔴 Thiếu |
| **Đợt mở bán** | ✅ Có - SalesPhase module | Mở bán Phase 1, 2, 3 với giá/chính sách khác nhau | 🟢 Tương đương |
| **Chính sách giá động** | Chiết khấu tĩnh | Chiết khấu theo đợt, theo khách hàng VIP, theo số lượng | 🟡 Cơ bản |
| **Tài chính** | Thu tiền + công nợ | BCTC, dòng tiền, đối soát ngân hàng | 🟡 Cơ bản |
| **In ấn** | Form Template | In HĐ, phiếu thu, phiếu tính giá | 🟢 Tương đương |
| **Phân quyền** | Không có | Role: Admin, Sales, Kế toán, Thu ngân... | 🔴 Thiếu |
| **Mobile App** | Không có | App cho sales, app cho khách hàng | 🔴 Thiếu |

**Nhận xét:** HQLand hiện tại mới đạt **30-40%** so với phần mềm BĐS chuyên nghiệp. Phù hợp làm **hệ thống nội bộ quản lý dữ liệu + thu tiền**, nhưng chưa đủ để làm **phần mềm bán hàng toàn diện**.

---

## IV. ĐỀ XUẤT LỘ TRÌNH PHÁT TRIỂN

### Giai đoạn 1: Sửa lỗi & An toàn (ĐÃ HOÀN THÀNH)
1. **~~Thay thế `eval()`~~ [DONE]** - Dùng shunting yard + bcmath trong MailMergeService
2. **~~Thêm `DB::transaction`~~ [DONE]** - `ContractScheduleService::generateFromTemplate()` đã có transaction
3. **~~Thêm Soft Delete~~ [DONE]** - Contract, Payment, Customer + Restore/ForceDelete UI
4. **~~Thêm `collected_by`~~ [DONE]** - Bảng `payments` + Form/Table hiển thị ngườ thu
5. **~~Fix `Contract::saved()`~~ [DONE]** - Dùng `self::$calculating` guard flag + `updateQuietly()`

### Giai đoạn 2: Quyền hạn & Báo cáo (2 tuần)
6. **Cài Spatie Permission** - Phân quyền: Admin, Sales Manager, Sales, Kế toán, Thu ngân
7. **Báo cáo công nợ chi tiết** - Theo khách hàng, theo dự án, theo đợt TT
8. **Báo cáo thu chi** - Sổ quỹ tiền mặt, sổ quỹ ngân hàng
9. **Export Excel báo cáo** - Báo cáo doanh thu, công nợ cho kế toán

### Giai đoạn 3: Mở rộng nghiệp vụ (Đang làm)
10. **CRM Pipeline** - Lead → Opportunity → Contract với các stage tùy chỉnh
11. **~~Quản lý đợt mở bán~~ [DONE]** - SalesPhase module với giá bán và chiết khấu riêng theo đợt
12. **Chính sách bán hàng động** - Chiết khấu theo thờ điểm, theo số lượng, theo CTV
13. **Notification đợt TT** - Email/SMS nhắc thanh toán tự động

### Giai đoạn 4: Tích hợp & Tối ưu (2 tháng)
14. **API REST** cho mobile app / website bán hàng
15. **Đối soát ngân hàng** - Import sao kê ngân hàng, tự động match với phiếu thu
16. **Quản lý bảo hành** - Theo dõi sửa chữa hạ tầng, bàn giao nhà
17. **Báo cáo BCTC** - Theo chuẩn kế toán Việt Nam, có thể xuất cho thuế

---

## V. KHUYẾN NGHỊ CHO BẠN

### Nên làm NGAY (tuần tới):
> Sửa lỗi nghiêm trọng #1, #2, #3. Không sửa → hệ thống có thể crash hoặc mất dữ liệu khi dữ liệu lớn lên.

### Nên làm TIẾP THEO (tháng tới):
> Phân quyền + Báo cáo tài chính. Đây là yêu cầu tối thiểu để kế toán và ban giám đốc sử dụng được.

### Có thể ĐỂ SAU:
> Mobile app, CRM Pipeline, đối soát ngân hàng. Các tính năng này tốn nhiều thời gian nhưng chưa ảnh hưởng đến vận hành cơ bản.

---

*Đánh giá này dựa trên code review thực tế và so sánh với best practices trong ngành BĐS Việt Nam. Cần cập nhật định kỳ.*