itsm-widget 1.0.5 → 1.0.6

package/ANGULAR-INSTALLATION.md

@@ -1,6 +1,59 @@
-# Hướng dẫn cài đặt ITSM Widget vào Angular Project
+# Hướng dẫn Tích hợp ITSM Widget vào Angular
 
-## 📋 Các bước cài đặt
+Tài liệu này hướng dẫn chi tiết cách tích hợp ITSM Widget vào ứng dụng Angular (mọi version).
+
+## 📋 Mục lục
+
+1. [Tổng quan](#tổng-quan)
+2. [Yêu cầu](#yêu-cầu)
+3. [Cài đặt](#cài-đặt)
+4. [Cấu hình](#cấu-hình)
+5. [Khởi tạo Widget](#khởi-tạo-widget)
+6. [Tích hợp với Auth Service](#tích-hợp-với-auth-service)
+7. [Troubleshooting](#troubleshooting)
+
+---
+
+## 📖 Tổng quan
+
+ITSM Widget là plugin JavaScript standalone cho phép người dùng tạo phiếu yêu cầu ITSM trực tiếp từ ứng dụng Angular. Widget hiển thị icon nổi ở góc màn hình và mở modal form khi được click.
+
+### Tính năng
+
+- ✅ Icon nổi ở góc màn hình (có thể tùy chỉnh vị trí, màu sắc)
+- ✅ Form tạo phiếu yêu cầu với các trường:
+  - Tiêu đề, Mô tả (rich text editor)
+  - **Danh mục dịch vụ** (tải từ API, có filter tìm kiếm)
+  - **Dịch vụ con** (tải từ API theo danh mục, có filter tìm kiếm)
+  - **Chi tiết dịch vụ** (tải từ API theo dịch vụ con, có filter tìm kiếm)
+  - Mức độ ưu tiên, Loại hỗ trợ, Loại thiết bị
+  - Thông tin liên hệ, Tệp đính kèm
+- ✅ Tự động gọi Backend API để lấy dữ liệu categories/subcategories/items
+- ✅ Responsive, hỗ trợ mobile
+
+### Kiến trúc
+
+```
+Angular App → ITSM Widget → Backend API → ITSM API
+```
+
+- **Angular App**: Hiển thị widget và truyền JWT token
+- **ITSM Widget**: Xử lý UI và gọi Backend API
+- **Backend API**: Xử lý business logic và gọi ITSM API
+- **ITSM API**: Hệ thống ITSM thực tế
+
+---
+
+## ✅ Yêu cầu
+
+- Angular (bất kỳ version nào)
+- Modern browser (Chrome, Firefox, Edge, Safari)
+- Backend API đã được cấu hình và chạy
+- JWT token từ hệ thống authentication của bạn
+
+---
+
+## 📦 Cài đặt
 
 ### Cách 1: Cài đặt qua npm (Khuyến nghị)
 
@@ -36,26 +89,21 @@ Thêm vào `scripts` và `styles`:
 }
 ```
 
-**Bước 3:** Xem tiếp phần "Khởi tạo widget" bên dưới.
-
----
+**Lưu ý:** Thay `your-project-name` bằng tên project của bạn.
 
 ### Cách 2: Copy files thủ công
 
 **Bước 1: Copy files vào project**
 
-Copy 2 files sau từ `dist/` của widget vào Angular project:
+Copy các file sau từ `dist/` của widget vào Angular project:
 
 ```
 src/assets/
   ├── itsm-widget.min.js
-  └── itsm-widget.min.css
+  ├── itsm-widget.min.css
+  └── itsm-widget-config.json
 ```
 
-**Cách copy:**
-- Copy `dist/itsm-widget.min.js` → `src/assets/itsm-widget.min.js`
-- Copy `dist/itsm-widget.min.css` → `src/assets/itsm-widget.min.css`
-
 **Bước 2: Cập nhật `angular.json`**
 
 Thêm scripts và styles vào `angular.json`:
@@ -73,6 +121,10 @@ Thêm scripts và styles vào `angular.json`:
             "styles": [
               "src/styles.css",
               "src/assets/itsm-widget.min.css"
+            ],
+            "assets": [
+              "src/favicon.ico",
+              "src/assets"
             ]
           }
         }
@@ -82,39 +134,40 @@ Thêm scripts và styles vào `angular.json`:
 }
 ```
 
-**Lưu ý:** Thay `your-project-name` bằng tên project của bạn.
-
 ---
 
-## ⚙️ Cấu hình (Áp dụng cho cả 2 cách)
+## ⚙️ Cấu hình
 
-### Bước 3: Copy file config (BẮT BUỘC)
+### Bước quan trọng: Cấu hình `itsm-widget-config.json` (BẮT BUỘC)
 
-**File `itsm-widget-config.json` là BẮT BUỘC** để widget hoạt động. Bạn cần copy file này vào `src/assets/`:
+**⚠️ QUAN TRỌNG:** File `itsm-widget-config.json` là **BẮT BUỘC** để widget hoạt động. Widget sẽ tự động load `apiBaseUrl` từ file này.
 
 **Cách 1: Copy từ node_modules (nếu dùng npm install)**
+
 ```bash
 # Copy file config từ package vào assets
 cp node_modules/itsm-widget/dist/itsm-widget-config.json src/assets/itsm-widget-config.json
 ```
 
 **Cách 2: Copy thủ công**
+
 1. Lấy file `itsm-widget-config.json` từ `node_modules/itsm-widget/dist/` hoặc từ package
 2. Copy vào `src/assets/itsm-widget-config.json`
-3. Chỉnh sửa giá trị `apiBaseUrl` theo nhu cầu:
+3. **Chỉnh sửa giá trị `apiBaseUrl`** theo môi trường của bạn:
 
 ```json
 {
-  "apiBaseUrl": "http://localhost:9998"
+  "apiBaseUrl": "http://localhost:2411"
 }
 ```
 
-**⚠️ Lưu ý quan trọng:**
-- File config **BẮT BUỘC** phải có trong `src/assets/` để Angular có thể serve file này
-- Widget sẽ tự động tìm file ở: `/assets/itsm-widget-config.json` (ưu tiên nhất)
-- Sau khi copy, nhớ build lại project: `ng serve` hoặc `ng build`
+**Lưu ý:**
+- Thay `http://localhost:2411` bằng URL thực tế của Backend API
+- File config **PHẢI** nằm trong `src/assets/` để Angular có thể serve
+- Widget sẽ tự động tìm file ở: `/assets/itsm-widget-config.json`
+- **KHÔNG** truyền `apiBaseUrl` vào constructor - nó sẽ bị bỏ qua
 
-### Bước 4: Đảm bảo assets được copy vào build
+### Đảm bảo assets được copy vào build
 
 Kiểm tra `angular.json` có cấu hình assets đúng:
 
@@ -137,15 +190,16 @@ Kiểm tra `angular.json` có cấu hình assets đúng:
 }
 ```
 
-## 🚀 Khởi tạo widget
+---
+
+## 🚀 Khởi tạo Widget
 
 Có 2 cách để khởi tạo widget:
 
-#### Cách 1: Khởi tạo trong `app.component.ts` (Đơn giản)
+### Cách 1: Khởi tạo trong `app.component.ts` (Đơn giản)
 
 ```typescript
 import { Component, OnInit, OnDestroy } from '@angular/core';
-import { environment } from '../environments/environment';
 
 declare var ITSMWidget: any;
 
@@ -159,12 +213,15 @@ export class AppComponent implements OnInit, OnDestroy {
   private itsmWidgetInstance: any;
 
   ngOnInit() {
+    // Lấy JWT token từ auth service hoặc storage
+    const token = this.getAuthToken(); // Implement method này
+    
     // Khởi tạo ITSM Widget
-    if (typeof ITSMWidget !== 'undefined') {
+    if (token && typeof ITSMWidget !== 'undefined') {
       this.itsmWidgetInstance = new ITSMWidget({
-        // apiBaseUrl được load tự động từ file itsm-widget-config.json
-        // KHÔNG cần truyền apiBaseUrl vào đây
-        authToken: 'your-jwt-token-here', // JWT token từ đăng nhập thành công
+        // apiBaseUrl BẮT BUỘC phải có trong file itsm-widget-config.json
+        // KHÔNG truyền apiBaseUrl vào constructor - nó sẽ bị bỏ qua
+        authToken: token, // JWT token từ đăng nhập thành công
         position: 'bottom-right',
         iconText: '📝',
         iconColor: '#007bff',
@@ -174,12 +231,24 @@ export class AppComponent implements OnInit, OnDestroy {
         onSuccess: (response: any) => {
           console.log('ITSM Request submitted:', response);
           // Hiển thị thông báo thành công
-          alert('Phiếu yêu cầu đã được gửi thành công!');
+          const requestId = response?.request?.id || 'N/A';
+          alert(`Phiếu yêu cầu đã được gửi thành công!\nID: ${requestId}`);
+        },
+        onError: (error: any) => {
+          console.error('Error submitting request:', error);
+          alert('Có lỗi xảy ra khi gửi yêu cầu. Vui lòng thử lại!');
         }
       });
 
       // Lưu instance vào window để có thể access từ nơi khác
       (window as any).itsmWidgetInstance = this.itsmWidgetInstance;
+    } else {
+      if (!token) {
+        console.warn('ITSM Widget: JWT token not found');
+      }
+      if (typeof ITSMWidget === 'undefined') {
+        console.error('ITSM Widget: Script not loaded');
+      }
     }
   }
 
@@ -187,18 +256,27 @@ export class AppComponent implements OnInit, OnDestroy {
     // Cleanup widget khi component bị destroy
     if (this.itsmWidgetInstance) {
       this.itsmWidgetInstance.destroy();
+      this.itsmWidgetInstance = null;
     }
   }
+
+  private getAuthToken(): string {
+    // Lấy token từ auth service, localStorage, hoặc sessionStorage
+    // Ví dụ:
+    // return this.authService.getToken();
+    // return localStorage.getItem('jwt_token') || '';
+    return '';
+  }
 }
 ```
 
-#### Cách 2: Tạo Service riêng (Khuyến nghị cho project lớn)
+### Cách 2: Tạo Service riêng (Khuyến nghị cho project lớn)
 
 **1. Tạo service:** `src/app/services/itsm-widget.service.ts`
 
 ```typescript
 import { Injectable, OnDestroy } from '@angular/core';
-import { environment } from '../../environments/environment';
+import { AuthService } from './auth.service'; // Import auth service của bạn
 
 declare var ITSMWidget: any;
 
@@ -208,44 +286,81 @@ declare var ITSMWidget: any;
 export class ItsmWidgetService implements OnDestroy {
   private widgetInstance: any;
 
-  constructor() {
+  constructor(private authService: AuthService) {
     this.init();
   }
 
   private init(): void {
     if (typeof ITSMWidget !== 'undefined' && !this.widgetInstance) {
-      this.widgetInstance = new ITSMWidget({
-        // apiBaseUrl được load tự động từ file itsm-widget-config.json
-        // KHÔNG cần truyền apiBaseUrl vào đây
-        authToken: 'your-jwt-token-here', // JWT token từ đăng nhập thành công
-        position: 'bottom-right',
-        iconText: '📝',
-        iconColor: '#007bff',
-        title: 'Tạo phiếu yêu cầu ITSM',
-        requesterName: this.getCurrentUser(), // Lấy từ auth service
-        site: '', // Optional
-        onSuccess: (response: any) => {
-          console.log('ITSM Request submitted:', response);
-          // Có thể emit event hoặc hiển thị notification ở đây
-        }
-      });
+      const token = this.authService.getToken(); // Lấy token từ auth service
+      
+      if (token) {
+        this.widgetInstance = new ITSMWidget({
+          // apiBaseUrl BẮT BUỘC phải có trong file itsm-widget-config.json
+          // KHÔNG truyền apiBaseUrl vào constructor - nó sẽ bị bỏ qua
+          authToken: token,
+          position: 'bottom-right',
+          iconText: '📝',
+          iconColor: '#007bff',
+          title: 'Tạo phiếu yêu cầu ITSM',
+          requesterName: this.getCurrentUser(),
+          site: '', // Optional
+          onSuccess: (response: any) => {
+            console.log('ITSM Request submitted:', response);
+            // Có thể emit event hoặc hiển thị notification ở đây
+            this.showSuccessNotification(response);
+          },
+          onError: (error: any) => {
+            console.error('Error submitting request:', error);
+            this.showErrorNotification(error);
+          }
+        });
 
-      (window as any).itsmWidgetInstance = this.widgetInstance;
+        (window as any).itsmWidgetInstance = this.widgetInstance;
+      } else {
+        console.warn('ITSM Widget: Token not found');
+      }
     }
   }
 
   private getCurrentUser(): string {
-    // Lấy tên user từ auth service, localStorage, hoặc sessionStorage
-    // Ví dụ:
-    // return this.authService.getCurrentUser()?.name || '';
-    // return localStorage.getItem('userName') || '';
-    return '';
+    // Lấy tên user từ auth service
+    const user = this.authService.getCurrentUser();
+    return user?.name || user?.username || '';
+  }
+
+  private showSuccessNotification(response: any): void {
+    // Tích hợp với notification service của bạn
+    // Ví dụ: this.notificationService.showSuccess('Yêu cầu đã được gửi thành công!');
+    const requestId = response?.request?.id || 'N/A';
+    alert(`Phiếu yêu cầu đã được gửi thành công!\nID: ${requestId}`);
+  }
+
+  private showErrorNotification(error: any): void {
+    // Tích hợp với notification service của bạn
+    alert('Có lỗi xảy ra khi gửi yêu cầu. Vui lòng thử lại!');
+  }
+
+  /**
+   * Update token khi user login/logout
+   */
+  updateToken(token: string | null): void {
+    if (token && this.widgetInstance) {
+      this.widgetInstance.config.authToken = token;
+    } else if (!token && this.widgetInstance) {
+      this.destroy();
+    }
   }
 
   ngOnDestroy(): void {
+    this.destroy();
+  }
+
+  private destroy(): void {
     if (this.widgetInstance) {
       this.widgetInstance.destroy();
       this.widgetInstance = null;
+      (window as any).itsmWidgetInstance = null;
     }
   }
 }
@@ -273,83 +388,121 @@ export class AppComponent implements OnInit {
 }
 ```
 
-### Bước 5: Build và test
+**3. Update token khi login/logout:**
 
-```bash
-# Development
-ng serve
+```typescript
+// Trong AuthService hoặc LoginComponent
+import { ItsmWidgetService } from './services/itsm-widget.service';
+
+constructor(private itsmWidgetService: ItsmWidgetService) {}
 
-# Production build
-ng build --prod
+onLogin(token: string) {
+  // ... login logic
+  this.itsmWidgetService.updateToken(token);
+}
+
+onLogout() {
+  // ... logout logic
+  this.itsmWidgetService.updateToken(null);
+}
 ```
 
-## ⚙️ Cấu hình nâng cao
+---
 
-### Lấy thông tin user từ Auth Service
+## 🔐 Tích hợp với Auth Service
 
-Nếu bạn có Auth Service, có thể lấy thông tin user:
+### Ví dụ với Angular JWT
 
 ```typescript
-import { AuthService } from './services/auth.service';
+import { JwtHelperService } from '@auth0/angular-jwt';
+import { ItsmWidgetService } from './services/itsm-widget.service';
 
-constructor(
-  private itsmWidgetService: ItsmWidgetService,
-  private authService: AuthService
-) {}
+@Injectable({
+  providedIn: 'root'
+})
+export class AuthService {
+  private jwtHelper = new JwtHelperService();
+
+  constructor(private itsmWidgetService: ItsmWidgetService) {}
+
+  login(username: string, password: string): Observable<string> {
+    return this.http.post<{token: string}>('/api/auth/login', {username, password})
+      .pipe(
+        map(response => response.token),
+        tap(token => {
+          localStorage.setItem('jwt_token', token);
+          // Update widget token
+          this.itsmWidgetService.updateToken(token);
+        })
+      );
+  }
 
-ngOnInit() {
-  const user = this.authService.getCurrentUser();
-  
-  // Update widget với thông tin user
-  if ((window as any).itsmWidgetInstance && user) {
-    (window as any).itsmWidgetInstance.config.requesterName = user.name;
-    (window as any).itsmWidgetInstance.config.site = user.site || '';
+  logout(): void {
+    localStorage.removeItem('jwt_token');
+    // Destroy widget
+    this.itsmWidgetService.updateToken(null);
+  }
+
+  getToken(): string | null {
+    return localStorage.getItem('jwt_token');
+  }
+
+  isAuthenticated(): boolean {
+    const token = this.getToken();
+    return token != null && !this.jwtHelper.isTokenExpired(token);
   }
 }
 ```
 
 ### Tích hợp với Notification Service
 
-Có thể tích hợp với notification service của Angular:
-
 ```typescript
-import { NotificationService } from './services/notification.service';
+import { MatSnackBar } from '@angular/material/snack-bar'; // Angular Material
+// hoặc
+import { ToastrService } from 'ngx-toastr'; // ngx-toastr
 
-constructor(private notificationService: NotificationService) {}
+constructor(
+  private snackBar: MatSnackBar,
+  // hoặc
+  private toastr: ToastrService
+) {}
 
 // Trong widget config:
 onSuccess: (response: any) => {
-  this.notificationService.showSuccess('Phiếu yêu cầu đã được gửi thành công!');
+  const requestId = response?.request?.id || 'N/A';
+  this.snackBar.open(`Yêu cầu đã được gửi thành công! ID: ${requestId}`, 'Đóng', {
+    duration: 5000
+  });
+  // hoặc
+  this.toastr.success(`Yêu cầu đã được gửi thành công! ID: ${requestId}`);
 }
 ```
 
-### Custom UDF Fields
-
-Có thể thêm custom UDF fields:
-
-```typescript
-new ITSMWidget({
-  // ... other config
-  udf_fields: {
-    udf_pick_301: 'Value 1',
-    udf_pick_302: 'Value 2',
-    // ... other fields
-  }
-});
-```
+---
 
 ## 🐛 Troubleshooting
 
 ### Widget không hiển thị
 
-1. Kiểm tra `angular.json` đã add scripts và styles chưa
-2. Kiểm tra files đã copy đúng vào `src/assets/` chưa
-3. Kiểm tra console có lỗi JavaScript không
-4. Đảm bảo đã build lại project: `ng serve` hoặc `ng build`
+**Kiểm tra:**
+1. File JavaScript đã được load chưa? (Kiểm tra Network tab trong DevTools)
+2. File `itsm-widget-config.json` đã có trong `src/assets/` chưa?
+3. Có lỗi JavaScript trong Console không?
+4. Token có hợp lệ không?
 
-### Lỗi TypeScript: Cannot find name 'ITSMWidget'
+**Giải pháp:**
+```typescript
+// Thêm log để debug
+console.log('ITSM Widget loaded:', typeof ITSMWidget);
+console.log('Token:', token ? 'Found' : 'Not found');
+console.log('Config file:', await fetch('/assets/itsm-widget-config.json').then(r => r.json()));
+```
 
-Thêm declare vào đầu file:
+### Lỗi: Cannot find name 'ITSMWidget'
+
+**Giải pháp:**
+
+Thêm declare vào đầu file TypeScript:
 
 ```typescript
 declare var ITSMWidget: any;
@@ -361,29 +514,64 @@ Hoặc tạo file `src/typings.d.ts`:
 declare var ITSMWidget: any;
 ```
 
-### Widget không hoạt động sau khi build production
+### Lỗi: Cannot load itsm-widget-config.json
 
-Đảm bảo files đã được include trong `angular.json`:
+**Nguyên nhân:** File config không tìm thấy hoặc không đúng format.
 
-```json
-"assets": [
-  "src/favicon.ico",
-  "src/assets",
-  {
-    "glob": "**/*",
-    "input": "src/assets",
-    "output": "/assets"
-  }
-]
-```
+**Giải pháp:**
+1. Đảm bảo file `itsm-widget-config.json` nằm trong `src/assets/`
+2. Kiểm tra file có đúng format JSON không
+3. Kiểm tra `angular.json` có cấu hình assets đúng không
+4. Build lại project: `ng serve` hoặc `ng build`
+
+### Lỗi 401 Unauthorized
+
+**Nguyên nhân:** Token không hợp lệ hoặc đã hết hạn.
+
+**Giải pháp:**
+- Kiểm tra token có đúng format không
+- Kiểm tra token có hết hạn không
+- Đảm bảo token được gửi đúng trong header: `Authorization: Bearer {token}`
+
+### Lỗi 403 Forbidden
+
+**Nguyên nhân:** Token không có quyền truy cập.
+
+**Kiểm tra:**
+- Token có audience (`aud`) = "SPC.HTVTCNTT" hoặc "SPC.QLTK" không?
+- Token có đúng roles không?
+
+### Widget không load categories/subcategories/items
+
+**Nguyên nhân:** Backend API không accessible hoặc lỗi CORS.
+
+**Giải pháp:**
+1. Kiểm tra Backend API đang chạy không
+2. Kiểm tra `apiBaseUrl` trong `itsm-widget-config.json` đúng chưa
+3. Kiểm tra CORS đã được cấu hình trong Backend chưa
+4. Kiểm tra Network tab để xem API calls có thành công không
+
+---
 
 ## 📝 Ví dụ hoàn chỉnh
 
 Xem file [example.html](../example.html) để tham khảo cách sử dụng cơ bản.
 
+---
+
 ## 📚 Tài liệu thêm
 
 - [README.md](../README.md) - Tài liệu tổng quan
-- [INSTALLATION.md](../INSTALLATION.md) - Hướng dẫn cho các platform khác
+- [CONFIG.md](../CONFIG.md) - Hướng dẫn cấu hình chi tiết
 - [API-SERVICE.md](../API-SERVICE.md) - Tài liệu API Service
+- [MVC-INTEGRATION.md](../MVC-INTEGRATION.md) - Hướng dẫn cho ASP.NET MVC
+
+---
+
+## 💡 Tips
 
+1. **Performance**: Widget chỉ load khi cần thiết, không ảnh hưởng đến performance của trang chính
+2. **Security**: Luôn lưu JWT token một cách an toàn (HttpOnly cookie hoặc secure storage)
+3. **Error Handling**: Luôn xử lý lỗi trong callback `onError` để cung cấp feedback cho người dùng
+4. **Testing**: Test widget trên các browser khác nhau để đảm bảo tương thích
+5. **Token Management**: Update widget token khi user login/logout để đảm bảo widget luôn có token hợp lệ