Files
minicrm/ai_instructions/AI_03_DATA_IMPORT_PIPELINE.md
2026-05-01 04:33:00 +00:00

1.9 KiB

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().
  • 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ì.