minicrm/PROGRESS.md

# 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ý)

---

## 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