TTMT.ManageWebGUI/SERVICES_GUIDE.md

API Services Documentation

Tất cả logic gọi API đã được tách riêng vào folder services. Mỗi service tương ứng với một nhóm API.

Cấu trúc Services

src/services/
  ├── index.ts                 # Export tất cả services
  ├── auth.service.ts          # API xác thực
  ├── app-version.service.ts   # API quản lý phần mềm
  ├── device-comm.service.ts   # API thiết bị
  ├── command.service.ts       # API lệnh
  └── device.service.ts        # Helper functions

Cách Sử Dụng

1. Auth Service (Xác thực)

import { authService } from '@/services'

// Đăng nhập
const response = await authService.login({
  username: 'user',
  password: 'pass'
})

// Đăng xuất
await authService.logout()

// Kiểm tra session
const pingResult = await authService.ping(token)

// Thay đổi mật khẩu
await authService.changePassword({
  currentPassword: 'old',
  newPassword: 'new'
})

// Tạo tài khoản mới (admin)
await authService.createAccount({
  userName: 'newuser',
  password: 'pass',
  name: 'John Doe',
  roleId: 1,
  accessBuildings: [1, 2, 3]
})

2. App Version Service (Quản lý phần mềm)

import { appVersionService } from '@/services'

// Lấy danh sách agent
const agents = await appVersionService.getAgentVersion()

// Lấy danh sách phần mềm
const software = await appVersionService.getSoftwareList()

// Upload file
const formData = new FormData()
formData.append('file', fileInput.files[0])
await appVersionService.uploadSoftware(formData, (progressEvent) => {
  console.log(`Progress: ${progressEvent.loaded}/${progressEvent.total}`)
})

// Lấy blacklist
const blacklist = await appVersionService.getBlacklist()

// Thêm vào blacklist
await appVersionService.addBlacklist({ appId: 1, reason: 'virus' })

// Xóa khỏi blacklist
await appVersionService.deleteBlacklist(1)

3. Device Comm Service (Thiết bị)

import { deviceCommService } from '@/services'

// Lấy tất cả thiết bị
const allDevices = await deviceCommService.getAllDevices()

// Lấy danh sách phòng
const rooms = await deviceCommService.getRoomList()

// Lấy thiết bị trong phòng
const devices = await deviceCommService.getDeviceFromRoom('Room A')

// Gửi lệnh
await deviceCommService.sendCommand('Room A', {
  command: 'dir'
})

// Cập nhật agent
await deviceCommService.updateAgent('Room A', { version: '1.0.0' })

// Cài đặt MSI
await deviceCommService.installMsi('Room A', { msiFileId: 1 })

4. Command Service (Lệnh)

import { commandService } from '@/services'

// Lấy danh sách lệnh
const commands = await commandService.getCommandList()

// Thêm lệnh
await commandService.addCommand({ name: 'cmd1', command: 'echo hello' })

// Cập nhật lệnh
await commandService.updateCommand(1, { name: 'cmd1 updated' })

// Xóa lệnh
await commandService.deleteCommand(1)

Sử dụng với React Query/Hooks

Cách cũ (trực tiếp gọi từ component):

const { data } = useQueryData({
  queryKey: ["software-version"],
  url: API_ENDPOINTS.APP_VERSION.GET_SOFTWARE,
})

Cách mới (tách biệt logic):

Có thể tạo custom hooks bao quanh services:

// hooks/useGetSoftware.ts
import { useQuery } from '@tanstack/react-query'
import { appVersionService } from '@/services'

export function useGetSoftware() {
  return useQuery({
    queryKey: ['software-version'],
    queryFn: () => appVersionService.getSoftwareList(),
    staleTime: 60 * 1000,
  })
}

Sau đó sử dụng trong component:

function AppsComponent() {
  const { data, isLoading } = useGetSoftware()
  // ...
}

Lợi ích của cách sử dụng mới

1. Tách biệt logic - Logic API nằm riêng, dễ bảo trì
2. Tái sử dụng - Có thể sử dụng service từ bất kỳ nơi
3. Dễ test - Dễ mock services khi viết unit tests
4. Centralized error handling - Có thể xử lý lỗi chung
5. Type safety - TypeScript types cho tất cả API requests/responses

Cải tiến trong tương lai

Có thể thêm:

• Global error handling middleware trong axios
• Request/response interceptors cho authentication
• Retry logic cho failed requests
• Request cancellation