# 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