phuongtc/minicrm
0
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

update DOC

Browse Source
This commit is contained in:
phuongtc
2026-05-12 07:18:09 +00:00
parent efa97b6c71
commit f2bc048219
14 changed files with 549 additions and 219 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
luutru/AI_01_BUSINESS_LOGIC_AND_POLICIES.md Normal file
View File

@@ -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ộ.

41
luutru/AI_02_DATABASE_SCHEMA_UPGRADE.md Normal file
View File

@@ -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`.

36
luutru/AI_03_DATA_IMPORT_PIPELINE.md Normal file
View File

@@ -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ì.

185
luutru/CHANGELOG.md Normal file
View File

@@ -0,0 +1,185 @@
# Release Notes
## [Unreleased](https://github.com/laravel/laravel/compare/v13.2.0...13.x)
## [v13.2.0](https://github.com/laravel/laravel/compare/v13.1.2...v13.2.0) - 2026-04-09
* Remove axios and enable ignore-scripts by [@WendellAdriel](https://github.com/WendellAdriel) in https://github.com/laravel/laravel/pull/6778
* Add /.cursor/ to .gitignore by [@workwithbinu](https://github.com/workwithbinu) in https://github.com/laravel/laravel/pull/6782
* Remove '.fleet' from .gitignore by [@dominiq007](https://github.com/dominiq007) in https://github.com/laravel/laravel/pull/6783
* Support all compose file naming conventions in editorconfig by [@mmachatschek](https://github.com/mmachatschek) in https://github.com/laravel/laravel/pull/6786
## [v13.1.2](https://github.com/laravel/laravel/compare/v13.1.1...v13.1.2) - 2026-03-31
* Prevents installed package from executing malicious code via `postinstall` by [@crynobone](https://github.com/crynobone) in https://github.com/laravel/laravel/pull/6777
* Add missing comma in axios by [@aziyan99](https://github.com/aziyan99) in https://github.com/laravel/laravel/pull/6779
## [v13.1.1](https://github.com/laravel/laravel/compare/v13.1.0...v13.1.1) - 2026-03-31
* Update .gitignore by [@Cegem-360](https://github.com/Cegem-360) in https://github.com/laravel/laravel/pull/6774
* [security] pin axios version by [@NickSdot](https://github.com/NickSdot) in https://github.com/laravel/laravel/pull/6776
## [v13.1.0](https://github.com/laravel/laravel/compare/v12.12.2...v13.1.0) - 2026-03-18
* Change back minimum-stability to stable by [@jnoordsij](https://github.com/jnoordsij) in https://github.com/laravel/laravel/pull/6766
* Vite 8 support
## [v12.12.2](https://github.com/laravel/laravel/compare/v12.12.1...v12.12.2) - 2026-03-14
* [12.x] Add `APP_NAME` fallback in Slack log channel username by [@hamedelasma](https://github.com/hamedelasma) in https://github.com/laravel/laravel/pull/6762
## [v12.12.1](https://github.com/laravel/laravel/compare/v12.12.0...v12.12.1) - 2026-03-10
* [12.x] Makes imports consistent by [@nunomaduro](https://github.com/nunomaduro) in https://github.com/laravel/laravel/pull/6760
## [v12.12.0](https://github.com/laravel/laravel/compare/v12.11.2...v12.12.0) - 2026-03-09
* Update phpunit version to ^11.5.50 to address CVE by [@PerryvanderMeer](https://github.com/PerryvanderMeer) in https://github.com/laravel/laravel/pull/6746
* [12.x] Add `APP_NAME` fallback in mail config by [@apoorvdarshan](https://github.com/apoorvdarshan) in https://github.com/laravel/laravel/pull/6755
* [12.x] Neutralize DB_URL in default phpunit.xml by [@Husseinadq](https://github.com/Husseinadq) in https://github.com/laravel/laravel/pull/6761
## [v12.11.2](https://github.com/laravel/laravel/compare/v12.11.1...v12.11.2) - 2026-01-19
* [12.x] Update composer dev script to ensure no timeout by [@jackbayliss](https://github.com/jackbayliss) in https://github.com/laravel/laravel/pull/6735
* [12.x] Update jobs/cache migrations by [@jackbayliss](https://github.com/jackbayliss) in https://github.com/laravel/laravel/pull/6736
* [12.x] Remove failed jobs indexes by [@jackbayliss](https://github.com/jackbayliss) in https://github.com/laravel/laravel/pull/6739
* [12.x] Add `APP_URL` fallback in filesystems config by [@KentarouTakeda](https://github.com/KentarouTakeda) in https://github.com/laravel/laravel/pull/6742
* chore: Update outdated GitHub Actions version by [@pgoslatara](https://github.com/pgoslatara) in https://github.com/laravel/laravel/pull/6743
## [v12.11.1](https://github.com/laravel/laravel/compare/v12.11.0...v12.11.1) - 2025-12-23
* Use environment variable for `DB_SSLMODE` - Postgres by [@robsontenorio](https://github.com/robsontenorio) in https://github.com/laravel/laravel/pull/6727
* fix: ensure APP_URL does not have trailing slash in filesystem by [@msamgan](https://github.com/msamgan) in https://github.com/laravel/laravel/pull/6728
## [v12.11.0](https://github.com/laravel/laravel/compare/v12.10.1...v12.11.0) - 2025-11-25
* fix: cookies are not available for subdomains by default by [@joostdebruijn](https://github.com/joostdebruijn) in https://github.com/laravel/laravel/pull/6705
* Fix PHP 8.5 PDO Driver Specific Constant Deprecation by [@RyanSchaefer](https://github.com/RyanSchaefer) in https://github.com/laravel/laravel/pull/6710
* Ignore Laravel compiled views for Vite by [@QistiAmal1212](https://github.com/QistiAmal1212) in https://github.com/laravel/laravel/pull/6714
## [v12.10.1](https://github.com/laravel/laravel/compare/v12.10.0...v12.10.1) - 2025-11-06
* Update schema URL in package.json by [@robinmiau](https://github.com/robinmiau) in https://github.com/laravel/laravel/pull/6701
## [v12.10.0](https://github.com/laravel/laravel/compare/v12.9.1...v12.10.0) - 2025-11-04
* Add background driver by [@barryvdh](https://github.com/barryvdh) in https://github.com/laravel/laravel/pull/6699
## [v12.9.1](https://github.com/laravel/laravel/compare/v12.9.0...v12.9.1) - 2025-10-23
* [12.x] Replace Bootcamp with Laravel Learn by [@AhmedAlaa4611](https://github.com/AhmedAlaa4611) in https://github.com/laravel/laravel/pull/6692
* [12.x] Comment out CLI workers for fresh applications by [@timacdonald](https://github.com/timacdonald) in https://github.com/laravel/laravel/pull/6693
## [v12.9.0](https://github.com/laravel/laravel/compare/v12.8.0...v12.9.0) - 2025-10-21
**Full Changelog**: https://github.com/laravel/laravel/compare/v12.8.0...v12.9.0
## [v12.8.0](https://github.com/laravel/laravel/compare/v12.7.1...v12.8.0) - 2025-10-20
* [12.x] Makes test suite using broadcast's `null` driver by [@nunomaduro](https://github.com/nunomaduro) in https://github.com/laravel/laravel/pull/6691
## [v12.7.1](https://github.com/laravel/laravel/compare/v12.7.0...v12.7.1) - 2025-10-15
* Added `failover` driver to the `queue` config comment. by [@sajjadhossainshohag](https://github.com/sajjadhossainshohag) in https://github.com/laravel/laravel/pull/6688
## [v12.7.0](https://github.com/laravel/laravel/compare/v12.6.0...v12.7.0) - 2025-10-14
**Full Changelog**: https://github.com/laravel/laravel/compare/v12.6.0...v12.7.0
## [v12.6.0](https://github.com/laravel/laravel/compare/v12.5.0...v12.6.0) - 2025-10-02
* Fix setup script by [@goldmont](https://github.com/goldmont) in https://github.com/laravel/laravel/pull/6682
## [v12.5.0](https://github.com/laravel/laravel/compare/v12.4.0...v12.5.0) - 2025-09-30
* [12.x] Fix type casting for environment variables in config files by [@AhmedAlaa4611](https://github.com/AhmedAlaa4611) in https://github.com/laravel/laravel/pull/6670
* Fix CVEs affecting vite by [@faissaloux](https://github.com/faissaloux) in https://github.com/laravel/laravel/pull/6672
* Update .editorconfig to target compose.yaml by [@fredikaputra](https://github.com/fredikaputra) in https://github.com/laravel/laravel/pull/6679
* Add pre-package-uninstall script to composer.json by [@cosmastech](https://github.com/cosmastech) in https://github.com/laravel/laravel/pull/6681
## [v12.4.0](https://github.com/laravel/laravel/compare/v12.3.1...v12.4.0) - 2025-08-29
* [12.x] Add default Redis retry configuration by [@mateusjatenee](https://github.com/mateusjatenee) in https://github.com/laravel/laravel/pull/6666
## [v12.3.1](https://github.com/laravel/laravel/compare/v12.3.0...v12.3.1) - 2025-08-21
* [12.x] Bump Pint version by [@AhmedAlaa4611](https://github.com/AhmedAlaa4611) in https://github.com/laravel/laravel/pull/6653
* [12.x] Making sure all related processed are closed when terminating the currently command by [@AhmedAlaa4611](https://github.com/AhmedAlaa4611) in https://github.com/laravel/laravel/pull/6654
* [12.x] Use application name from configuration by [@AhmedAlaa4611](https://github.com/AhmedAlaa4611) in https://github.com/laravel/laravel/pull/6655
* Bring back postAutoloadDump script by [@jasonvarga](https://github.com/jasonvarga) in https://github.com/laravel/laravel/pull/6662
## [v12.3.0](https://github.com/laravel/laravel/compare/v12.2.0...v12.3.0) - 2025-08-03
* Fix Critical Security Vulnerability in form-data Dependency by [@izzygld](https://github.com/izzygld) in https://github.com/laravel/laravel/pull/6645
* Revert "fix" by [@RobertBoes](https://github.com/RobertBoes) in https://github.com/laravel/laravel/pull/6646
* Change composer post-autoload-dump script to Artisan command by [@lmjhs](https://github.com/lmjhs) in https://github.com/laravel/laravel/pull/6647
## [v12.2.0](https://github.com/laravel/laravel/compare/v12.1.0...v12.2.0) - 2025-07-11
* Add Vite 7 support by [@timacdonald](https://github.com/timacdonald) in https://github.com/laravel/laravel/pull/6639
## [v12.1.0](https://github.com/laravel/laravel/compare/v12.0.11...v12.1.0) - 2025-07-03
* [12.x] Disable nightwatch in testing by [@laserhybiz](https://github.com/laserhybiz) in https://github.com/laravel/laravel/pull/6632
* [12.x] Reorder environment variables in phpunit.xml for logical grouping by [@AhmedAlaa4611](https://github.com/AhmedAlaa4611) in https://github.com/laravel/laravel/pull/6634
* Change to hyphenate prefixes and cookie names by [@u01jmg3](https://github.com/u01jmg3) in https://github.com/laravel/laravel/pull/6636
* [12.x] Fix type casting for environment variables in config files by [@AhmedAlaa4611](https://github.com/AhmedAlaa4611) in https://github.com/laravel/laravel/pull/6637
## [v12.0.11](https://github.com/laravel/laravel/compare/v12.0.10...v12.0.11) - 2025-06-10
**Full Changelog**: https://github.com/laravel/laravel/compare/v12.0.10...v12.0.11
## [v12.0.10](https://github.com/laravel/laravel/compare/v12.0.9...v12.0.10) - 2025-06-09
* fix alphabetical order by [@Khuthaily](https://github.com/Khuthaily) in https://github.com/laravel/laravel/pull/6627
* [12.x] Reduce redundancy and keeps the .gitignore file cleaner by [@AhmedAlaa4611](https://github.com/AhmedAlaa4611) in https://github.com/laravel/laravel/pull/6629
* [12.x] Fix: Add void return type to satisfy Rector analysis by [@Aluisio-Pires](https://github.com/Aluisio-Pires) in https://github.com/laravel/laravel/pull/6628
## [v12.0.9](https://github.com/laravel/laravel/compare/v12.0.8...v12.0.9) - 2025-05-26
* [12.x] Remove apc by [@AhmedAlaa4611](https://github.com/AhmedAlaa4611) in https://github.com/laravel/laravel/pull/6611
* [12.x] Add JSON Schema to package.json by [@martinbean](https://github.com/martinbean) in https://github.com/laravel/laravel/pull/6613
* Minor language update by [@woganmay](https://github.com/woganmay) in https://github.com/laravel/laravel/pull/6615
* Enhance .gitignore to exclude common OS and log files by [@mohammadRezaei1380](https://github.com/mohammadRezaei1380) in https://github.com/laravel/laravel/pull/6619
## [v12.0.8](https://github.com/laravel/laravel/compare/v12.0.7...v12.0.8) - 2025-05-12
* [12.x] Clean up URL formatting in README by [@AhmedAlaa4611](https://github.com/AhmedAlaa4611) in https://github.com/laravel/laravel/pull/6601
## [v12.0.7](https://github.com/laravel/laravel/compare/v12.0.6...v12.0.7) - 2025-04-15
* Add `composer run test` command by [@crynobone](https://github.com/crynobone) in https://github.com/laravel/laravel/pull/6598
* Partner Directory Changes in ReadME by [@joshcirre](https://github.com/joshcirre) in https://github.com/laravel/laravel/pull/6599
## [v12.0.6](https://github.com/laravel/laravel/compare/v12.0.5...v12.0.6) - 2025-04-08
**Full Changelog**: https://github.com/laravel/laravel/compare/v12.0.5...v12.0.6
## [v12.0.5](https://github.com/laravel/laravel/compare/v12.0.4...v12.0.5) - 2025-04-02
* [12.x] Update `config/mail.php` to match the latest core configuration by [@AhmedAlaa4611](https://github.com/AhmedAlaa4611) in https://github.com/laravel/laravel/pull/6594
## [v12.0.4](https://github.com/laravel/laravel/compare/v12.0.3...v12.0.4) - 2025-03-31
* Bump vite from 6.0.11 to 6.2.3 - Vulnerability patch by [@abdel-aouby](https://github.com/abdel-aouby) in https://github.com/laravel/laravel/pull/6586
* Bump vite from 6.2.3 to 6.2.4 by [@thinkverse](https://github.com/thinkverse) in https://github.com/laravel/laravel/pull/6590
## [v12.0.3](https://github.com/laravel/laravel/compare/v12.0.2...v12.0.3) - 2025-03-17
* Remove reverted change from CHANGELOG.md by [@AJenbo](https://github.com/AJenbo) in https://github.com/laravel/laravel/pull/6565
* Improves clarity in app.css file by [@AhmedAlaa4611](https://github.com/AhmedAlaa4611) in https://github.com/laravel/laravel/pull/6569
* [12.x] Refactor: Structural improvement for clarity by [@AhmedAlaa4611](https://github.com/AhmedAlaa4611) in https://github.com/laravel/laravel/pull/6574
* Bump axios from 1.7.9 to 1.8.2 - Vulnerability patch by [@abdel-aouby](https://github.com/abdel-aouby) in https://github.com/laravel/laravel/pull/6572
* [12.x] Remove Unnecessarily [@source](https://github.com/source) by [@AhmedAlaa4611](https://github.com/AhmedAlaa4611) in https://github.com/laravel/laravel/pull/6584
## [v12.0.2](https://github.com/laravel/laravel/compare/v12.0.1...v12.0.2) - 2025-03-04
* Make the github test action run out of the box independent of the choice of testing framework by [@ndeblauw](https://github.com/ndeblauw) in https://github.com/laravel/laravel/pull/6555
## [v12.0.1](https://github.com/laravel/laravel/compare/v12.0.0...v12.0.1) - 2025-02-24
* [12.x] prefer stable stability by [@pataar](https://github.com/pataar) in https://github.com/laravel/laravel/pull/6548
## [v12.0.0 (2025-??-??)](https://github.com/laravel/laravel/compare/v11.0.2...v12.0.0)
Laravel 12 includes a variety of changes to the application skeleton. Please consult the diff to see what's new.

202
luutru/PROGRESS.md Normal file
View File

@@ -0,0 +1,202 @@
# AfterSales CRM - Tiến độ
## Trạng thái: Hoàn thành SOP + 6/7 AI Instructions (85%)
Đã test: Tất cả routes HTTP 200, Pest 8/8 tests (21 assertions) pass ✓
Tham chiếu: `SOP_des.md` — Bản đặc tả hệ thống After-Sale CRM
**Data import:** `php artisan app:import-cskh ai_instructions/CSKH.xlsx` — 3658 rows imported successfully
## Công nghệ
- Laravel 13.6.0 + Filament 5.6.1 + SQLite
- PHP 8.3
- Spatie laravel-permission (RBAC)
- Pest PHP (testing)
## Tài khoản test
| Role | Email | Password |
|------|-------|----------|
| admin | admin@minicrm.local | password |
| manager | manager@minicrm.local | password |
| staff | staff@minicrm.local | password |
---
## ĐÃ HOÀN THÀNH
### Giai đoạn 1: Mở rộng CSDL
- [x] Bảng `departments` (id, name, manager_id → users)
- [x] Bổ sung `feedback`: current_department_id, is_escalated
- [x] Bảng `ticket_transfer_logs` (feedback_id, from/to department, sender, reason)
- [x] Nâng cấp `feedback_attachments`: uuid, disk, collection
- [x] Cài Spatie laravel-permission
### Giai đoạn 2: Services & Logic
- [x] `FileService`: upload, validation (jpg/png/pdf/mp4/mov ≤20MB), collection query, temporary URL
- [x] `TransferService`: transfer department + reason required + notification
- [x] `ClosingService`: role-gated close + proof_of_resolution check
- [x] Policies cập nhật dùng Spatie `hasRole()`
- [x] Custom Rule `RequireProofOfResolution`
### Giai đoạn 3: Notifications
- [x] `TicketTransferred` (Database + Mail)
- [x] `TicketClosed` (Database + Mail)
### Giai đoạn 4: Filament UI
- [x] `TransferDepartment` Action trên Edit Feedback (modal: department + reason + attachment)
- [x] `CloseTicket` Action (visible: admin/manager, status ≠ closed, requires confirmation)
- [x] InteractionsRelationManager: role-aware status options (staff: no "closed"), department field
- [x] FeedbackForm: current_department_id, is_escalated, attachment_collection
### Giai đoạn 5: Dashboard Widgets
- [x] `ResolvedTicketsWidget`: bảng ticket resolved chờ đóng (manager lọc theo phòng quản lý)
- [x] `AvgProcessingTimeWidget`: 4 stats (resolved count, avg time, pending, escalated)
### Giai đoạn 6: Testing
- [x] Pest cài đặt + 6 test scenarios
- [x] `ClosingPermissionTest`: 4 tests (staff 403, no evidence 422, with evidence OK, cross-department 403)
- [x] `TransferFlowTest`: 2 tests (success + missing reason)
### Giai đoạn 7: Seeder
- [x] 4 departments (CSKH, Kỹ thuật, Kế toán, Pháp lý)
- [x] 1 ticket_transfer_log mẫu
- [x] 3 feedback_attachments (2 proof_of_resolution, 1 customer_evidence)
### Giai đoạn 8: Polish
- [x] AGENTS.md cập nhật đầy đủ
### Bug Fix
- [x] Dashboard widget lọc Manager dùng `Department::where('manager_id')` thay vì `auth()->id()`
- [x] Migration default disk `private` → `local`
- [x] File upload trong Interaction/Create/Edit dùng lưu thẳng FeedbackAttachment, không tạo UploadedFile giả
### PM (Improvements)
- [x] FeedbackTable: thêm cột Department, Escalated icon, Department filter
- [x] EditFeedback: validation `proof_of_resolution` khi đổi status sang `closed` từ form
### PASS 3 — Hoàn thiện SOP
- [x] `HandlerPerformanceWidget`: biểu đồ bar chart thời gian xử lý trung bình theo từng nhân viên
- [x] Department_Head: Manager chỉ đóng được ticket phòng mình quản lý (kèm test)
- [x] Temporary URL tích hợp vào UI: nút "View Attachments" trong Interaction History với download link
- [x] Cho phép upload attachment trong status_change interaction
- [x] Docker sẵn sàng production: Dockerfile, docker-compose, entrypoint
- [x] Migration `notifications` table
### AI Instructions — Phase A: Module Hợp đồng (Contract)
- [x] Migration `contracts`: product_id, customer_id, type (sale/lease/bcc), dates, status, signed_status
- [x] Enum `ContractType` (SALE/LEASE/BCC) + `ContractStatus` (ACTIVE/EXPIRED/LIQUIDATED)
- [x] Model `Contract`: relationships product(), customer(), feedbacks()
- [x] Filament Resource `Contracts` (CRUD) + `ContractPolicy`
- [x] RelationManager `ContractsRelationManager` trên ProductResource
- [x] Model `Product` thêm `contracts()` HasMany
- [x] Seeder: 5 contracts mẫu
### AI Instructions — Phase B: Snapshot Hợp đồng
- [x] Migration thêm `contract_id` FK nullable vào `feedback`
- [x] Model `Feedback`: thêm `contract_id` fillable + `contract()` BelongsTo
- [x] FeedbackForm: auto-select active contract khi chọn sản phẩm, cho phép chọn lại thủ công
- [x] FeedbackTable: cột "Contract" hiển thị loại HĐ dạng badge
- [x] Seeder: gán contract_id cho 5 feedback mẫu
### AI Instructions — Phase C: Module Bàn giao (Handover)
- [x] Migration `handovers`: product_id, customer_id, handover_date, status, remark
- [x] Enum `HandoverStatus` (NOT_READY/READY/SCHEDULED/HANDED_OVER)
- [x] Model `Handover`: relationships product(), customer()
- [x] RelationManager `HandoversRelationManager` trên ProductResource
- [x] Model `Product` thêm `handovers()` HasMany
- [x] Seeder: 5 handovers mẫu
### AI Instructions — Phase D: Module Dịch vụ (ProductService)
- [x] Migration `product_services`: product_id, service_type, status, actual_collection_date, remark
- [x] Enum `ServiceType` (MANAGEMENT_FEE/GRATITUDE/SELF_BUSINESS)
- [x] Model `ProductService`: relationship product()
- [x] RelationManager `ProductServicesRelationManager` trên ProductResource
- [x] Model `Product` thêm `productServices()` HasMany
- [x] Seeder: 5 services mẫu
### AI Instructions — Phase E: Enhancement ProductResource
- [x] ProductResource có 3 tabs: Contracts + Handovers + Services
### AI Instructions — Phase G: Data Import Pipeline
- [x] Cài `spatie/simple-excel` (Lazy Collection, chống OOM)
- [x] Command `app:import-cskh {file_path} --dry-run` với ProgressBar
- [x] Pipeline: Product/Customer firstOrCreate → customer_product pivot → Contract → Handover → Service → Feedback + Interactions
- [x] Xử lý DateTimeImmutable object từ Excel, skip meta rows
- [x] Đã test thành công với CSKH.xlsx: 3658 rows → 3299 products, 2089 customers, 2637 contracts, 2077 handovers, 159 services, 71 feedbacks, 226 interactions
### Còn lại (Optional)
- [ ] Auto-suggest chuyển phòng ban dựa trên loại hợp đồng (Ticket BCC → gợi ý Pháp lý)
### Granular Permissions + Export Backup + User/Role Management
- [x] PermissionSeeder: 29 permissions (view/create/update/delete per module + close-ticket, transfer-department, export-data)
- [x] Role → Permission mapping: admin (all), manager (no delete/export), staff (view + limited write)
- [x] Policies updated to use `hasPermissionTo()` instead of `hasRole()`
- [x] Widgets/Filament updated to use permission-based checks
- [x] ExportBackup command: `app:export-backup` (JSON, per-table, chunk 500, manifest.json)
- [x] UserResource: admin can create/edit/delete users + assign roles
- [x] RoleResource: admin can create/edit/delete roles + assign permissions
- [x] UserPolicy + RolePolicy (admin-only)
- [x] Tests updated: 8 tests, 21 assertions pass
### Internationalization (i18n) — Vietnamese + English
- [x] Config: `APP_LOCALE=vi`, `APP_FALLBACK_LOCALE=en` in `.env`
- [x] Created `lang/en/` and `lang/vi/` with 3 files each: `app.php`, `feedback.php`, `enums.php`
- [x] ~120 translation keys covering: navigation, labels, status, widgets, services, notifications, enums
- [x] All Resources: override `getPluralLabel()` + `getNavigationGroup()` with `__()` calls
- [x] All Form fields: explicit `->label(__('key'))` on TextInput, Select, Textarea, etc.
- [x] All Table columns: explicit `->label(__('key'))` on TextColumn, IconColumn
- [x] All RelationManagers: `$title` property uses translation key
- [x] All Widgets: `getHeading()`/`getDescription()` methods return translated strings
- [x] Enums: `ContractType`, `ContractStatus`, `HandoverStatus`, `ServiceType` use `__()` in `label()`
- [x] Services/Notifications: all user-facing strings use translation keys
- [x] Blade views: all hardcoded strings replaced with `__()` calls
- [x] Filament vendor translations (57 Vietnamese files) auto-activated for UI chrome
- [x] Tests: 8/8 pass (21 assertions)
### UI Polish & Bug Fixes
- [x] File upload: Fixed disk('local') → disk('public') across all components
- [x] File upload: Added exists() check before getting metadata
- [x] File upload: Fixed dehydrated(false) issue - use property to store paths
- [x] Tailwind CSS: Added ~200 utility classes to filament-custom.css
- [x] SVG icons: Use inline width/height attributes instead of Tailwind classes
- [x] GlobalSearch: Customized for all 6 Resources with multi-field search
- [x] RelationManager titles: Override getTitle() for proper translation
- [x] Enum refactoring: Added color() method, static options(), developer comments
- [x] Documentation: Created docs/I18N_GUIDE.md and docs/ENUM_GUIDE.md
---
## Database Schema (final — 23 migrations)
```
products customers customer_product (pivot)
feedback_channels feedback feedback_interactions
feedback_attachments feedback_tags feedback_feedback_tag (pivot)
users departments ticket_transfer_logs
permissions roles model_has_roles (spatie)
notifications sessions cache
contracts handovers product_services
```
## Data Import
```bash
# Dry-run (phân tích trước, an toàn)
php artisan app:import-cskh ai_instructions/CSKH.xlsx --dry-run
# Import thật
php artisan app:import-cskh ai_instructions/CSKH.xlsx
```
## Local Dev
```bash
cd /home/phuongtc/vibecode/minicrm
php artisan migrate:fresh --seed
php artisan serve
# Mở http://localhost:8000/admin
php artisan test # 8 tests (21 assertions)
```
## Hướng dẫn cho AI Agent khác
- `CODEBASE_SNAPSHOT.md` — Toàn bộ cấu trúc codebase (đọc thay vì scan code)
- `TASKS_ROADMAP.md` — Roadmap: đã làm, đang làm, sẽ làm
- `AGENTS.md` — Hướng dẫn chạy, workflow, RBAC, gotchas
- `docs/I18N_GUIDE.md` — Hướng dẫn đa ngôn ngữ chi tiết
- `docs/ENUM_GUIDE.md` — Hướng dẫn thêm Enum mới

58
luutru/README.md Normal file
View File

@@ -0,0 +1,58 @@
<p align="center"><a href="https://laravel.com" target="_blank"><img src="https://raw.githubusercontent.com/laravel/art/master/logo-lockup/5%20SVG/2%20CMYK/1%20Full%20Color/laravel-logolockup-cmyk-red.svg" width="400" alt="Laravel Logo"></a></p>
<p align="center">
<a href="https://github.com/laravel/framework/actions"><img src="https://github.com/laravel/framework/workflows/tests/badge.svg" alt="Build Status"></a>
<a href="https://packagist.org/packages/laravel/framework"><img src="https://img.shields.io/packagist/dt/laravel/framework" alt="Total Downloads"></a>
<a href="https://packagist.org/packages/laravel/framework"><img src="https://img.shields.io/packagist/v/laravel/framework" alt="Latest Stable Version"></a>
<a href="https://packagist.org/packages/laravel/framework"><img src="https://img.shields.io/packagist/l/laravel/framework" alt="License"></a>
</p>
## About Laravel
Laravel is a web application framework with expressive, elegant syntax. We believe development must be an enjoyable and creative experience to be truly fulfilling. Laravel takes the pain out of development by easing common tasks used in many web projects, such as:
- [Simple, fast routing engine](https://laravel.com/docs/routing).
- [Powerful dependency injection container](https://laravel.com/docs/container).
- Multiple back-ends for [session](https://laravel.com/docs/session) and [cache](https://laravel.com/docs/cache) storage.
- Expressive, intuitive [database ORM](https://laravel.com/docs/eloquent).
- Database agnostic [schema migrations](https://laravel.com/docs/migrations).
- [Robust background job processing](https://laravel.com/docs/queues).
- [Real-time event broadcasting](https://laravel.com/docs/broadcasting).
Laravel is accessible, powerful, and provides tools required for large, robust applications.
## Learning Laravel
Laravel has the most extensive and thorough [documentation](https://laravel.com/docs) and video tutorial library of all modern web application frameworks, making it a breeze to get started with the framework.
In addition, [Laracasts](https://laracasts.com) contains thousands of video tutorials on a range of topics including Laravel, modern PHP, unit testing, and JavaScript. Boost your skills by digging into our comprehensive video library.
You can also watch bite-sized lessons with real-world projects on [Laravel Learn](https://laravel.com/learn), where you will be guided through building a Laravel application from scratch while learning PHP fundamentals.
## Agentic Development
Laravel's predictable structure and conventions make it ideal for AI coding agents like Claude Code, Cursor, and GitHub Copilot. Install [Laravel Boost](https://laravel.com/docs/ai) to supercharge your AI workflow:
```bash
composer require laravel/boost --dev
php artisan boost:install
```
Boost provides your agent 15+ tools and skills that help agents build Laravel applications while following best practices.
## Contributing
Thank you for considering contributing to the Laravel framework! The contribution guide can be found in the [Laravel documentation](https://laravel.com/docs/contributions).
## Code of Conduct
In order to ensure that the Laravel community is welcoming to all, please review and abide by the [Code of Conduct](https://laravel.com/docs/contributions#code-of-conduct).
## Security Vulnerabilities
If you discover a security vulnerability within Laravel, please send an e-mail to Taylor Otwell via [taylor@laravel.com](mailto:taylor@laravel.com). All security vulnerabilities will be promptly addressed.
## License
The Laravel framework is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).

121
luutru/SOP_des.md Normal file
View File

@@ -0,0 +1,121 @@
# BẢN ĐẶC TẢ HỆ THỐNG AFTER-SALE CRM (PHIÊN BẢN NÂNG CAO)
## 1. Cấu trúc dữ liệu mở rộng (Extended Database Schema)
AI Agent cần bổ sung các bảng và trường dữ liệu sau để phục vụ việc luân chuyển và lưu trữ bằng chứng:
### A. Quản lý Tài liệu & Bằng chứng (Attachment Management)
- **`media_attachments`**:
- `id`, `uuid`, `disk`, `file_path`, `file_name`, `mime_type`, `file_size`.
- `model_type` (Ticket hoặc Interaction), `model_id`.
- `collection`: (Ví dụ: 'proof_of_resolution' - bằng chứng xử lý, 'customer_evidence' - khách hàng cung cấp).
- `uploader_id` (User ID của người tải lên).
### B. Luồng điều phối đa bộ phận (Cross-department Routing)
- **`departments`**: `id`, `name` (Kỹ thuật, Kế toán, Chăm sóc khách hàng, Pháp lý), `manager_id`.
- **`tickets` (Bổ sung)**:
- `current_department_id`: Phòng ban đang thụ lý.
- `handler_id`: Nhân viên cụ thể đang xử lý.
- `is_escalated`: Boolean (Đánh dấu nếu bị khiếu nại vượt cấp).
- **`ticket_transfer_logs`**: (Theo dõi lịch sử chuyển giao)
- `id`, `ticket_id`, `from_department_id`, `to_department_id`, `sender_id`, `reason`, `created_at`.
---
## 2. Logic luồng xử lý (Workflow Engine Logic)
AI Agent phải triển khai logic xử lý theo các ràng buộc sau:
### A. Quy tắc Chuyển tiếp (Transfer Logic)
- Khi nhân viên A (Phòng CSKH) chuyển Ticket cho Phòng Kỹ thuật:
- Hệ thống yêu cầu nhập `reason` và đính kèm tài liệu liên quan (nếu có).
- `current_department_id` cập nhật sang ID Phòng Kỹ thuật.
- `handler_id` sẽ được reset về `null` (chờ Trưởng phòng Kỹ thuật chỉ định nhân viên mới) hoặc tự động gán cho Trưởng phòng đó.
### B. Quy tắc Đóng Ticket (Closing Permissions)
- **Status: `closed`** là trạng thái cuối cùng.
- **Ràng buộc (Constraint):** * Nếu `user_role` là 'Staff', hệ thống chỉ được phép chuyển trạng thái sang `resolved` (Đã xử lý xong - chờ kiểm duyệt).
- Trạng thái `closed` chỉ khả dụng (Visible/Actionable) khi `user_role` là 'Manager' hoặc 'Department_Head'.
- Trước khi chuyển sang `closed`, hệ thống kiểm tra bắt buộc phải có ít nhất 01 tệp tin thuộc collection `proof_of_resolution`.
---
## 3. Quản lý tệp tin (Document & File Handling)
AI Agent cần thiết lập một Service Layer riêng cho việc xử lý File:
1. **Validation:** Chỉ cho phép định dạng ảnh (jpg, png), PDF và Video ngắn (<20MB).
2. **Versioning:** Nếu tải tài liệu mới lên cùng một Ticket, không được xóa tài liệu cũ, phải lưu trữ theo dạng danh sách để làm căn cứ đối chiếu.
3. **Security:** File tải lên phải được lưu trữ trong `private disk` và chỉ những người có quyền truy cập Ticket đó mới có thể Generate Temporary URL để xem.
---
## 4. Kịch bản kiểm thử cho AI Agent (Test Scripts)
### Kịch bản 1: Kiểm tra quyền Đóng Ticket (Permission Check)
- **Input:** User có role `staff` gửi request `PATCH /api/tickets/{id}` với `status: 'closed'`.
- **Expectation:** Trả về lỗi `403 Forbidden`. Thông báo: "Chỉ lãnh đạo cấp phòng mới có quyền đóng phiếu."
### Kịch bản 2: Kiểm tra bắt buộc bằng chứng (Mandatory Evidence)
- **Input:** Manager thực hiện đóng Ticket nhưng chưa tải lên bất kỳ tài liệu nào trong collection `proof_of_resolution`.
- **Expectation:** Trả về lỗi `422 Unprocessable Entity`. Thông báo: "Yêu cầu cung cấp tài liệu bằng chứng để hoàn tất quy trình."
### Kịch bản 3: Kiểm tra luồng chuyển tiếp (Transfer Flow)
- **Input:** Thực hiện `transfer` Ticket từ Phòng CSKH sang Phòng Pháp lý.
- **Expectation:** * Bản ghi mới trong `ticket_transfer_logs` được tạo.
- `current_department_id` của Ticket thay đổi thành ID Phòng Pháp lý.
- Gửi Notification (Database & Mail) cho Manager của Phòng Pháp lý.
---
## 5. Chỉ dẫn triển khai (Implementation Prompt cho AI Agent)
> "Sử dụng **Laravel 13.x** và **Filament v5.5**, hãy thực hiện:
>
> 1. Thiết lập **Spatie Media Library** (hoặc Custom File Service) để quản lý tài liệu gắn với Ticket và Interaction. Phân loại rõ collection 'evidence' và 'resolution_proof'.
>
> 2. Tại `TicketResource` của Filament:
>
> - Tạo một Action `Transfer Department`: Hiển thị Modal cho phép chọn Phòng ban và nhập lý do chuyển. Lưu lịch sử vào bảng `ticket_transfer_logs`.
>
> - Tạo logic ẩn/hiện nút `Close Ticket`: Chỉ hiển thị nếu User có role 'Manager'.
>
> - Sử dụng **Validation Rule** tùy chỉnh: Khi status chuyển sang `closed`, kiểm tra sự tồn tại của file trong media collection.
>
> 3. Xây dựng trang Dashboard cho Lãnh đạo phòng:
>
> - Hiển thị danh sách Ticket đang ở trạng thái `resolved` (chờ đóng).
>
> - Biểu đồ thời gian xử lý trung bình của từng nhân viên trong phòng.
>
> 4. Viết **Pest Test** bao phủ toàn bộ logic phân quyền và chuyển tiếp bộ phận."

56
luutru/SYSTEM_ASSESSMENT_PROPOSALS.md Normal file
View File

@@ -0,0 +1,56 @@
# AfterSales CRM - System Assessment & Proposals (Draft)
> **Ngày ghi nhận:** Monday, May 4, 2026
> **Người thực hiện:** Gemini CLI Agent
> **Mục đích:** Ghi lại các nhận định về hệ thống, rủi ro bảo mật và đề xuất nâng cấp để thảo luận sau.
---
## 1. Nhận định Hệ thống (Current Understanding)
- **Kiến trúc:** Laravel 13.6 + Filament 5.6, PHP 8.3. Sử dụng Spatie Permissions cho RBAC.
- **Dữ liệu:** Đã import ~3600 records từ Excel thành công. Sử dụng SQLite làm database.
- **Workflow:** Quy trình Feedback -> Transfer -> Resolve -> Close đã được thiết lập chặt chẽ với các Service chuyên biệt (`ClosingService`, `TransferService`).
- **Tài liệu:** Đã có `AGENTS.md`, `PROGRESS.md`, `TASKS_ROADMAP.md` và `CODEBASE_SNAPSHOT.md` giúp nắm bắt nhanh trạng thái dự án.
## 2. Rủi ro Bảo mật & An toàn (Security & Safety Risks)
### 2.1. Phạm vi truy cập dữ liệu (Data Visibility)
- **Vấn đề:** `FeedbackPolicy` hiện tại cho phép mọi User có quyền `view-feedback` xem được toàn bộ các phản hồi của tất cả phòng ban.
- **Rủi ro:** Lộ thông tin nhạy cảm giữa các phòng ban.
- **Đề xuất:** Áp dụng Global Scope hoặc Scoping trong Resource để nhân viên chỉ thấy phiếu thuộc phòng ban mình hoặc được giao cho mình.
### 2.2. Bảo mật Backup
- **Vấn đề:** Command `app:export-backup` lưu file JSON (bao gồm hash mật khẩu và thông tin khách hàng) trực tiếp trong `storage/app/backups`.
- **Rủi ro:** Dễ bị đánh cắp nếu folder này bị lộ hoặc server bị chiếm quyền user.
- **Đề xuất:** Mã hóa file backup hoặc đẩy thẳng lên S3 với chính sách bảo mật nghiêm ngặt.
### 2.3. Signed URL trên Local Disk
- **Vấn đề:** `FileService` dùng `temporaryUrl` trên driver `local`.
- **Rủi ro:** Laravel mặc định không hỗ trợ URL tạm thời cho local driver trừ khi được cấu hình thêm. Có thể gây lỗi không xem được ảnh/file trong thực tế.
### 2.4. Tính nhất quán của Logic Đóng phiếu
- **Vấn đề:** Logic kiểm tra `proof_of_resolution` đang nằm rải rác ở Service và một số chỗ trong Filament UI.
- **Rủi ro:** Khó bảo trì và dễ xảy ra sai sót khi cập nhật quy trình.
## 3. Đề xuất Nâng cấp (Proposed Upgrades)
### 3.1. Audit Trail (Lịch sử chi tiết)
- **Mô tả:** Ghi lại chi tiết ai đã sửa cái gì, từ giá trị cũ sang giá trị mới cho tất cả các Model quan trọng (Contract, Feedback, Customer).
- **Công cụ gợi ý:** `spatie/laravel-activitylog`.
### 3.2. Mã hóa dữ liệu (PII Encryption)
- **Mô tả:** Mã hóa các trường thông tin cá nhân (Số điện thoại, Email) trong Database để đảm bảo an toàn nếu database bị leak.
### 3.3. Theo dõi SLA (SLA Tracking)
- **Mô tả:** Thiết lập thời hạn xử lý cho từng loại phản hồi. Cảnh báo (Email/Notification) khi sắp đến hạn hoặc quá hạn.
### 3.4. Gợi ý chuyển phòng thông minh (Smart Suggestion)
- **Mô tả:** Tự động phân tích loại Hợp đồng hoặc Tag để gợi ý "Nên chuyển cho phòng Pháp lý/Kế toán".
### 3.5. Cải tiến Bulk Actions
- **Mô tả:** Cho phép xử lý hàng loạt (Chuyển phòng, Phân công nhân viên) để tối ưu năng suất cho Manager.
## 4. Các câu hỏi thảo luận sau
1. Quy tắc phân quyền xem chéo giữa các phòng ban cụ thể là gì?
2. Hệ thống sẽ chạy Production trên SQLite hay chuyển sang MySQL/PostgreSQL?
3. Có cần tích hợp Chat trực tuyến (Zalo/Messenger) vào hệ thống không?

0
luutru/mota.md Normal file
View File