# Checklist Workflow Thông Báo (Alerts) theo Module

## Tổng quan
Hệ thống hiện có **4 loại alerts** được định nghĩa:
- `LowStock` - Cảnh báo tồn kho thấp
- `PMSchedule` - Cảnh báo lịch bảo trì
- `TicketSLA` - Cảnh báo SLA ticket
- `System` - Thông báo hệ thống

---

## ✅ Module ĐÃ CÓ Workflow Alerts

### 1. **Tickets (Sự cố)**
- **File**: `backend/src/controllers/tickets.controller.ts`
- **Workflow**: 
  - ✅ Tạo alert khi tạo ticket với priority = `Critical`
  - ✅ Tạo alert khi ticket sắp quá hạn SLA (trong createTicket và updateTicket)
  - ✅ Tạo alert khi ticket được assign (trong updateTicket)
- **Loại alert**: `TicketSLA`
- **Severity**: 
  - `Critical` khi priority = Critical hoặc SLA <= 4 giờ hoặc quá hạn
  - `Warning` khi SLA <= 8 giờ
  - `Info` khi được assign với priority thấp
- **Vị trí code**: 
  - Dòng 135-143: createTicket - tạo alert khi critical hoặc có SLA
  - Dòng 220-250: updateTicket - tạo alert khi assign hoặc check SLA
- **Service**: `alertService.createTicketSLAAlert()` và `alertService.createTicketAssignmentAlert()`

---

## ✅ Module ĐÃ CÓ Workflow Alerts (Đã bổ sung)

### 2. **Inventory (Kho & Vật tư)**
- **File**: `backend/src/controllers/inventory.controller.ts`
- **Workflow đã bổ sung**:
  - ✅ Tạo alert khi tạo item mới và `currentStock <= minStockLevel` (LowStock)
  - ✅ Tạo alert khi stock out và tồn kho còn lại <= minStockLevel
- **Loại alert**: `LowStock`
- **Severity**: 
  - `Warning` khi tồn kho <= minStockLevel
  - `Critical` khi tồn kho = 0 hoặc < minStockLevel * 0.5
- **Link**: `/inventory`
- **Service**: `alertService.createLowStockAlert()`

### 3. **PM Schedule (Lịch bảo trì)**
- **File**: `backend/src/controllers/pmSchedules.controller.ts`
- **Workflow đã bổ sung**:
  - ✅ Tạo alert khi tạo schedule mới và `nextDue` sắp đến
  - ✅ Tạo alert khi cập nhật schedule và `nextDue` sắp đến
  - ✅ Tạo alert trong `runScheduler` cho schedules sắp đến hạn
- **Loại alert**: `PMSchedule`
- **Severity**:
  - `Info` khi còn > 7 ngày
  - `Warning` khi còn <= 7 ngày
  - `Critical` khi còn <= 3 ngày hoặc đã quá hạn
- **Link**: `/maintenance-schedule`
- **Service**: `alertService.createPMScheduleAlert()`

### 4. **Work Orders (Lệnh công việc)**
- **File**: `backend/src/controllers/workOrders.controller.ts`
- **Workflow đã bổ sung**:
  - ✅ Tạo alert khi work order được assign
  - ✅ Tạo alert khi work order sắp quá hạn (scheduledEnd)
- **Loại alert**: `System`
- **Severity**: 
  - `Info` khi được assign
  - `Warning` khi còn <= 24 giờ
  - `Critical` khi còn <= 8 giờ
- **Link**: `/work-orders`
- **Service**: `alertService.createWorkOrderAlert()`

### 5. **Contracts (Hợp đồng)**
- **File**: `backend/src/controllers/contracts.controller.ts`
- **Workflow đã bổ sung**:
  - ✅ Tạo alert khi hợp đồng sắp hết hạn (30 ngày, 7 ngày)
  - ✅ Tạo alert khi hợp đồng đã hết hạn
- **Loại alert**: `System`
- **Severity**:
  - `Warning` khi còn <= 30 ngày
  - `Critical` khi còn <= 7 ngày hoặc đã hết hạn
- **Link**: `/contracts`
- **Service**: `alertService.createContractExpiryAlert()`

### 6. **Compliance (Tuân thủ)**
- **File**: `backend/src/controllers/compliance.controller.ts`
- **Workflow đã bổ sung**:
  - ✅ Tạo alert khi văn bản tuân thủ sắp hết hạn
  - ✅ Tạo alert khi văn bản đã hết hạn
- **Loại alert**: `System`
- **Severity**: 
  - `Warning` khi còn <= 30 ngày
  - `Critical` khi còn <= 7 ngày hoặc đã hết hạn
- **Link**: `/compliance`
- **Service**: `alertService.createComplianceExpiryAlert()`

### 7. **Assets (Tài sản)**
- **File**: `backend/src/controllers/assets.controller.ts`
- **Workflow đã bổ sung**:
  - ✅ Tạo alert khi asset có status = `faulty`
  - ✅ Tạo alert khi asset sắp hết bảo hành (warrantyEndDate)
- **Loại alert**: `System`
- **Severity**: 
  - `Critical` khi status = faulty
  - `Warning` khi bảo hành còn <= 30 ngày
  - `Critical` khi bảo hành còn <= 7 ngày
- **Link**: `/assets`
- **Service**: `alertService.createAssetAlert()`

### 8. **Projects (Dự án)**
- **File**: `backend/src/controllers/projects.controller.ts`
- **Workflow đã bổ sung**:
  - ✅ Tạo alert khi project status thay đổi thành `decommissioned`
- **Loại alert**: `System`
- **Severity**: `Warning`
- **Link**: `/projects`
- **Service**: `alertService.createAlert()`

---

## 📋 Tóm tắt

| Module | Có Alerts | Loại Alert | Mức độ ưu tiên | Trạng thái |
|--------|-----------|------------|----------------|------------|
| Tickets | ✅ Có | TicketSLA | Đã hoàn thành | ✅ Hoàn thành |
| Inventory | ✅ Có | LowStock | **Cao** - Quan trọng | ✅ Đã bổ sung |
| PM Schedule | ✅ Có | PMSchedule | **Cao** - Quan trọng | ✅ Đã bổ sung |
| Work Orders | ✅ Có | System | Trung bình | ✅ Đã bổ sung |
| Contracts | ✅ Có | System | Trung bình | ✅ Đã bổ sung |
| Compliance | ✅ Có | System | Trung bình | ✅ Đã bổ sung |
| Assets | ✅ Có | System | Thấp | ✅ Đã bổ sung |
| Projects | ✅ Có | System | Thấp | ✅ Đã bổ sung |

---

## 🔧 API Endpoints

### ✅ GET `/api/alerts`
- **Status**: ✅ Đã có trong backend (`routes/alerts.routes.ts`)
- **Controller**: `alerts.controller.ts` - `getAlerts()`
- Lấy danh sách alerts (limit 100, sort by createdAt desc, filter by userId)

### ✅ POST `/api/alerts`
- **Status**: ✅ Đã bổ sung
- **Controller**: `alerts.controller.ts` - `createAlert()`
- **Body**: `{ type, message, severity, link?, userId? }`
- **Authentication**: Required

### ✅ PUT `/api/alerts/:id`
- **Status**: ✅ Đã bổ sung
- **Controller**: `alerts.controller.ts` - `updateAlert()`
- **Body**: `{ isRead: true }`
- **Authentication**: Required

### ✅ DELETE `/api/alerts/:id`
- **Status**: ✅ Đã bổ sung
- **Controller**: `alerts.controller.ts` - `deleteAlert()`
- **Authentication**: Required

---

## 💡 Gợi ý triển khai

### 1. ✅ Tạo Alert Service
**Status**: ✅ Đã hoàn thành
- File: `backend/src/services/alertService.ts`
- Các hàm đã có:
  - ✅ `createAlert()` - Generic function
  - ✅ `createLowStockAlert()` - Cho Inventory
  - ✅ `createPMScheduleAlert()` - Cho PM Schedule
  - ✅ `createTicketSLAAlert()` - Cho Tickets
  - ✅ `createTicketAssignmentAlert()` - Cho Ticket assignment
  - ✅ `createContractExpiryAlert()` - Cho Contracts
  - ✅ `createComplianceExpiryAlert()` - Cho Compliance
  - ✅ `createWorkOrderAlert()` - Cho Work Orders
  - ✅ `createAssetAlert()` - Cho Assets

### 2. ✅ Scheduled Jobs
**Status**: ✅ Đã hoàn thành
- File: `backend/src/services/scheduledAlerts.ts`
- Tích hợp vào: `backend/src/server.ts`
- **Chức năng đã có**:
  - ✅ Kiểm tra PM schedules sắp đến hạn (chạy hàng ngày lúc 8:00 AM)
  - ✅ Kiểm tra contracts sắp hết hạn (chạy hàng ngày lúc 8:00 AM)
  - ✅ Kiểm tra compliance documents sắp hết hạn (chạy hàng ngày lúc 8:00 AM)
  - ✅ Kiểm tra ticket SLA sắp quá hạn (chạy mỗi 4 giờ)
- **Các hàm**:
  - `checkPMSchedules()` - Kiểm tra PM schedules
  - `checkContracts()` - Kiểm tra contracts
  - `checkComplianceDocs()` - Kiểm tra compliance documents
  - `checkTicketSLAs()` - Kiểm tra ticket SLAs
  - `runAllScheduledAlerts()` - Chạy tất cả checks

### 3. ✅ Event-driven Alerts
**Status**: ✅ Đã hoàn thành
- **Stock out → kiểm tra tồn kho → tạo alert**: ✅
  - File: `backend/src/controllers/inventory.controller.ts`
  - Vị trí: `stockOut()` function (dòng 130-135)
  - Tự động tạo alert khi stock out và tồn kho <= minStockLevel

- **Ticket created/updated → kiểm tra SLA → tạo alert**: ✅
  - File: `backend/src/controllers/tickets.controller.ts`
  - Vị trí: 
    - `createTicket()` (dòng 135-143)
    - `updateTicket()` (dòng 220-250)
  - Tự động tạo alert khi:
    - Ticket được tạo với priority Critical
    - Ticket có SLA deadline sắp quá hạn
    - Ticket được assign

- **Contract updated → kiểm tra ngày hết hạn → tạo alert**: ✅
  - File: `backend/src/controllers/contracts.controller.ts`
  - Vị trí:
    - `createContract()` (dòng 60-70)
    - `updateContract()` (dòng 110-120)
  - Tự động tạo alert khi hợp đồng sắp hết hạn (≤ 30 ngày)

---

## 📝 Notes

- ✅ **Tất cả 8 module** đã có workflow alerts hoàn chỉnh
- ✅ **API endpoints** đã được tạo đầy đủ (GET, POST, PUT, DELETE)
- ✅ **Alert Service** (`alertService.ts`) đã được tạo để tập trung logic tạo alerts
- ✅ **Tickets** đã được cập nhật để sử dụng `alertService` thay vì tạo trực tiếp

## 🎯 Các file đã tạo/cập nhật

### Files mới:
- `backend/src/controllers/alerts.controller.ts` - Controller cho alerts API
- `backend/src/routes/alerts.routes.ts` - Routes cho alerts API
- `backend/src/services/alertService.ts` - Service tập trung logic tạo alerts

### Files đã cập nhật:
- `backend/src/server.ts` - Thêm alerts routes
- `backend/src/controllers/inventory.controller.ts` - Bổ sung LowStock alerts
- `backend/src/controllers/pmSchedules.controller.ts` - Bổ sung PMSchedule alerts
- `backend/src/controllers/workOrders.controller.ts` - Bổ sung Work Order alerts
- `backend/src/controllers/contracts.controller.ts` - Bổ sung Contract expiry alerts
- `backend/src/controllers/compliance.controller.ts` - Bổ sung Compliance expiry alerts
- `backend/src/controllers/assets.controller.ts` - Bổ sung Asset alerts
- `backend/src/controllers/projects.controller.ts` - Bổ sung Project alerts
- `backend/src/controllers/tickets.controller.ts` - Cập nhật để sử dụng alertService