nang cap san sang import

ai_instructions/AI_01_BUSINESS_LOGIC_AND_POLICIES.md

@@ -0,0 +1,19 @@
+# Kiến trúc Nghiệp vụ & Chính sách hệ thống AfterSales CRM
+
+# Tham chiếu: AGENTS.md, PROGRESS.md
+
+## 1. Cơ chế Snapshot Hợp đồng (Neo dữ liệu)
+
+- **Bối cảnh:** Một sản phẩm (Căn hộ) sẽ trải qua nhiều loại hợp đồng theo thời gian (HĐ Mua bán -> HĐ Thuê -> HĐ Hợp tác kinh doanh BCC). 
+- **Quy tắc:** Mọi tương tác/khiếu nại (`Feedback`) phải được gắn cứng với hợp đồng đang có hiệu lực tại thời điểm đó. 
+- **Thực thi:** Bổ sung trường `contract_id` (nullable) vào bảng `feedback`. Khi tạo mới một Ticket, hệ thống ưu tiên tự động chọn hợp đồng đang Active của căn hộ đó (có thể cho phép nhân viên chọn lại thủ công). Lịch sử của Ticket sẽ vĩnh viễn thuộc về hợp đồng này, không bị thay đổi ngay cả khi căn hộ chuyển sang hợp đồng khác trong tương lai.
+
+## 2. Chính sách Luân chuyển (Ticket Transfer Policy)
+
+- **Quy tắc Tối thượng:** KHÔNG CÓ BẤT KỲ CƠ CHẾ TỰ ĐỘNG TRANSFER NÀO.
+- **Thực thi:** Việc chuyển Ticket (Feedback) giữa các phòng ban (ví dụ: từ CSKH sang Kỹ thuật, Pháp lý) phải được thực hiện hoàn toàn thủ công bởi nhân viên hoặc quản lý (thông qua `TransferService` đã có). 
+- **Tính năng mở rộng (Tùy chọn):** Trên giao diện Filament, có thể hiển thị Text/Badge gợi ý: "Ticket này thuộc mảng BCC, khuyến nghị chuyển cho phòng Pháp lý" nhưng hành động chuyển (submit) là do con người quyết định.
+
+## 3. Tách bạch Module Bàn giao (Handover)
+
+- Việc bàn giao không phải là một "Feedback", mà là một mốc trạng thái cốt lõi của sản phẩm. Nó cần một bảng riêng (`handovers`) và quản lý bằng một Tab riêng biệt trên giao diện chi tiết Căn hộ.

ai_instructions/AI_02_DATABASE_SCHEMA_UPGRADE.md

@@ -0,0 +1,41 @@
+# TASK: Nâng cấp Database Schema từ Dữ liệu Excel
+
+# Context: Đọc quy tắc tại `AI_01_BUSINESS_LOGIC_AND_POLICIES.md`
+
+Hãy tạo các file Migration và cập nhật các Model tương ứng trong Laravel 13 cho các thực thể sau:
+
+## 1. Bảng `handovers` (Module Bàn giao)
+
+- `product_id` (foreignId, constrained)
+- `customer_id` (foreignId, constrained - người nhận bàn giao)
+- `handover_date` (date - Ngày nhận BG)
+- `status` (string - Tình trạng BG: Chưa đủ điều kiện, Đủ ĐK, Đã BG trực tiếp...)
+- `remark` (text, nullable - Ghi chú hồ sơ BG)
+
+## 2. Bảng `contracts` (Module Hợp đồng)
+
+- `product_id` (foreignId, constrained)
+- `customer_id` (foreignId, constrained)
+- `type` (string - Enum/Const: LEASE, BCC, SALE)
+- `start_date` (date, nullable - Ngày bắt đầu)
+- `end_date` (date, nullable - Ngày kết thúc/Thời hạn thanh lý)
+- `status` (string - Tình trạng HĐ: Active, Expired, Liquidated...)
+- `printed_at` (date, nullable - Ngày in HĐ)
+- `signed_status` (string - Tình trạng ký)
+
+## 3. Bảng `product_services` (Dịch vụ phụ trợ / Tự doanh / Phí QL / Tri ân)
+
+- `product_id` (foreignId, constrained)
+- `service_type` (string - Enum/Const: MANAGEMENT_FEE, GRATITUDE, SELF_BUSINESS)
+- `status` (string - Tình trạng)
+- `actual_collection_date` (date, nullable - Thời hạn thu thực tế)
+- `remark` (text, nullable)
+
+## 4. Cập nhật Bảng `feedback` (Cốt lõi)
+
+- Tạo migration bổ sung cột: `table->foreignId('contract_id')->nullable()->constrained('contracts')->nullOnDelete();`
+
+## Yêu cầu cho AI:
+
+- Khai báo đầy đủ các Relationships (`hasMany`, `belongsTo`) trong tất cả các Models.
+- Chuẩn bị sẵn các `RelationManager` cho Filament 5.6 để gắn vào `ProductResource`.

ai_instructions/AI_03_DATA_IMPORT_PIPELINE.md

@@ -0,0 +1,36 @@
+# TASK: Xây dựng Command Import Dữ liệu lớn (CSV/Excel)
+
+# Context: Import file CSKH "phẳng" vào cấu trúc Database Relational mới.
+
+## Yêu cầu Kỹ thuật
+
+- Sử dụng package `spatie/simple-excel` với cơ chế **Lazy Collection** (Generator) để chống tràn bộ nhớ (OOM).
+- Tạo command: `php artisan app:import-cskh {file_path}`.
+- Bọc logic xử lý mỗi chunk (ví dụ 100 dòng) bằng `DB::transaction()`.
+- Có `ProgressBar` của Symfony Console để theo dõi.
+
+## Luồng xử lý Data (Per Row)
+
+Mỗi `$row` từ file CSV sẽ chạy qua Pipeline sau:
+
+1. **Định danh Base Entities:**
+   
+   - Tìm hoặc tạo mới `Product` bằng `$row['Mã căn hộ']`.
+   - Tìm hoặc tạo mới `Customer` bằng `$row['Họ tên KH']`.
+
+2. **Khởi tạo Hợp đồng (Contracts) & Bàn giao (Handovers):**
+   
+   - Đọc các cột liên quan đến Bàn Giao, nếu có -> Insert/Update `handovers`.
+   - Đọc các cột HĐ BCC, HĐ THUÊ, nếu có -> Insert `contracts`.
+
+3. **Xử lý Feedback & Interactions (Tách dòng lịch sử):**
+   
+   - Lấy chuỗi text tại cột `Nội dung` (hoặc `Lịch Sử khách hàng`).
+   - Sử dụng `explode("\n", $text)` để tách thành mảng các interactions. Loại bỏ các chuỗi rỗng.
+   - Tìm hợp đồng `Active` gần nhất của Product này để lấy `$contract_id` (nếu có).
+   - `firstOrCreate` một `Feedback` (Ticket) gắn với `Product`, `Customer`, và `Contract` vừa tìm được. (Tiêu đề mặc định: "Ticket từ dữ liệu lịch sử").
+   - Lặp qua mảng interactions vừa tách, tạo các record trong `feedback_interactions` nối với Ticket trên.
+
+## Lưu ý cho AI:
+
+- Viết code có cấu trúc rõ ràng, tách các khối logic (Process Product, Process Contract, Process Interactions) thành các private methods trong Command class để dễ bảo trì.