# Chức năng Tra cứu Chấm công

## Tổng quan

Hệ thống tra cứu chấm công bao gồm 3 trang chính:

1. **Quản lý chấm công** (`/cham-cong`) - Trang hiện có để xem lịch sử chấm công chi tiết
2. **Báo cáo chấm công** (`/bao-cao-cham-cong`) - Trang mới: Báo cáo tổng hợp số công theo tháng
3. **Chi tiết chấm công** (`/chi-tiet-cham-cong/:userId`) - Trang mới: Chi tiết chấm công từng ngày của nhân viên

## 1. Báo cáo chấm công (AttendanceReport.vue)

### Chức năng
- Hiển thị danh sách tất cả nhân viên với tổng số công trong tháng
- Tìm kiếm theo tháng và năm
- Xuất báo cáo Excel/CSV
- Click vào nhân viên để xem chi tiết

### API sử dụng
- **Endpoint**: `GET /api/Attendance/GetMonthlySummary`
- **Parameters**: 
  - `month` (1-12)
  - `year` (ví dụ: 2025)

### Thông tin hiển thị
| Cột | Mô tả |
|-----|-------|
| STT | Số thứ tự |
| Họ và tên | Tên đầy đủ của nhân viên |
| Tên đăng nhập | Username |
| Số ngày làm | Tổng số ngày có chấm công |
| Tổng giờ làm | Tổng số giờ làm việc |
| Tổng công | Tổng số công được tính |
| Thao tác | Nút xem chi tiết |

### Tính năng đặc biệt
- **Tổng kết**: Hiển thị tổng số nhân viên, tổng công, tổng giờ
- **Xuất Excel**: Xuất danh sách dưới dạng CSV với encoding UTF-8 (có BOM)
- **Navigation**: Click "Xem chi tiết" để chuyển sang trang chi tiết

### Route
```javascript
{
  name: "hr-attendance-report",
  path: "/bao-cao-cham-cong",
  component: AttendanceReportView,
  meta: {
    title: "Báo cáo chấm công",
  },
}
```

## 2. Chi tiết chấm công (AttendanceDetail.vue)

### Chức năng
- Hiển thị chi tiết chấm công từng ngày của một nhân viên
- Xem thông tin check-in, check-out, số giờ làm, số công
- Hiển thị ODO đầu, cuối, tổng quãng đường
- Xuất chi tiết Excel/CSV

### API sử dụng
- **Endpoint**: `GET /api/Attendance/GetUserAttendanceDetail`
- **Parameters**:
  - `month` (1-12)
  - `year` (ví dụ: 2025)
  - `userId` (ID nhân viên)

### Thông tin hiển thị

#### Thẻ thông tin tổng quan
- Tên nhân viên
- Tháng/Năm
- Tổng công (màu xanh)
- Tổng giờ (màu vàng)
- Tổng km (màu đỏ) - Tổng quãng đường di chuyển

#### Bảng chi tiết từng ngày
| Cột | Mô tả |
|-----|-------|
| STT | Số thứ tự |
| Ngày làm việc | Ngày và thứ |
| Giờ vào | Thời gian check-in |
| Giờ ra | Thời gian check-out |
| Số giờ làm | Tổng giờ làm việc |
| Số công | Công được tính (có màu sắc) |
| ODO đầu | Số ODO khi check-in |
| ODO cuối | Số ODO khi check-out |
| Tổng ODO | Quãng đường đi (km) |

### Màu sắc Badge số công
- 🟢 **Xanh lá** (≥ 1.0): Full công (> 8 giờ)
- 🟡 **Vàng** (0.5-0.99): Nửa công (3-8 giờ)
- ⚪ **Xám** (< 0.5): 1/4 công hoặc không tính (≤ 3 giờ)

### Quy tắc tính công
```
> 8 giờ    → 1.0 công (Full công)
3-8 giờ    → 0.5 công (Nửa công)
2-3 giờ    → 0.25 công (1/4 công)
≤ 2 giờ    → 0 công (Không tính)
```

### Route
```javascript
{
  name: "hr-attendance-detail",
  path: "/chi-tiet-cham-cong/:userId",
  component: AttendanceDetailView,
  props: true,
  meta: {
    title: "Chi tiết chấm công",
  },
}
```

### Navigation
- Từ trang Báo cáo: Click "Xem chi tiết" trên từng nhân viên
- Query params được truyền:
  - `month`: Tháng hiện tại
  - `year`: Năm hiện tại
  - `fullName`: Tên nhân viên (hiển thị trên header)

## Cấu trúc File

```
src/
├── infrastructure/
│   └── apiPaths/
│       └── hrPath.js              # Đã thêm 2 endpoints mới
├── services/
│   └── hr/
│       └── attendanceService.js   # Đã thêm getMonthlySummary, getUserAttendanceDetail
├── views/
│   └── hr/
│       └── attendance/
│           ├── index.vue          # Trang quản lý chấm công (hiện có)
│           ├── AttendanceReport.vue   # Trang báo cáo tổng hợp (MỚI)
│           ├── AttendanceDetail.vue   # Trang chi tiết nhân viên (MỚI)
│           └── README.md          # File này
└── routers/
    └── hr.js                      # Đã thêm 2 routes mới
```

## API Service

### attendanceService.js

```javascript
// Lấy tổng hợp công theo tháng (tất cả nhân viên)
async getMonthlySummary(month, year)

// Lấy chi tiết công theo ngày (1 nhân viên)
async getUserAttendanceDetail(month, year, userId)

// Tìm kiếm chấm công (API cũ, vẫn giữ nguyên)
async search(searchModel)
```

## Cách sử dụng

### 1. Truy cập trang Báo cáo chấm công
```
URL: /bao-cao-cham-cong
```

### 2. Chọn tháng/năm và tìm kiếm
- Chọn tháng từ dropdown (1-12)
- Chọn năm (hiển thị 5 năm: current ±2)
- Click "Tìm kiếm"

### 3. Xem danh sách và tổng kết
- Danh sách nhân viên hiển thị với số công, giờ làm
- Phía dưới bảng có tổng kết: số nhân viên, tổng công, tổng giờ

### 4. Xem chi tiết nhân viên
- Click nút "Xem chi tiết" trên hàng nhân viên
- Trang chi tiết hiển thị từng ngày làm việc

### 5. Xuất Excel
- Trang Báo cáo: Xuất danh sách tổng hợp
- Trang Chi tiết: Xuất chi tiết từng ngày (có dòng tổng cộng)

## Lưu ý kỹ thuật

### 1. Error Handling
- Cả 2 trang đều có error handling đầy đủ
- Hiển thị thông báo lỗi từ API (400 Bad Request)
- Toast notification cho thành công/lỗi

### 2. Loading States
- Spinner hiển thị khi đang tải dữ liệu
- Disable buttons khi đang loading

### 3. Empty States
- Thông báo khi không có dữ liệu
- Toast info khi không tìm thấy bản ghi

### 4. Data Validation
API đã validate:
- Tháng: 1-12
- Năm: 2000-2100
- UserId: > 0

### 5. Export Excel
- Format: CSV với BOM (UTF-8)
- Filename: `BaoCaoCong_[month]_[year].csv` hoặc `ChiTietChamCong_[userId]_[month]_[year].csv`
- Hỗ trợ tiếng Việt đầy đủ

## Dependencies

Các packages sử dụng:
- `vue` (3.x) - Framework chính
- `vue-router` (4.x) - Routing
- `vue-toastification` - Toast notifications
- `axios` (via apiClient) - HTTP requests

## Testing

### Test Flow
1. Vào trang báo cáo: `/bao-cao-cham-cong`
2. Chọn tháng/năm có dữ liệu
3. Kiểm tra danh sách hiển thị đúng
4. Click "Xem chi tiết" một nhân viên
5. Kiểm tra trang chi tiết hiển thị đúng
6. Click "Quay lại" hoặc breadcrumb
7. Test xuất Excel ở cả 2 trang

### Test Cases
- ✅ Tìm kiếm tháng có dữ liệu
- ✅ Tìm kiếm tháng không có dữ liệu
- ✅ Navigation giữa 2 trang
- ✅ Xuất Excel
- ✅ Error handling (tháng/năm không hợp lệ)
- ✅ Loading states
- ✅ Responsive design

## Tương lai

Các tính năng có thể mở rộng:
- [ ] Filter theo phòng ban
- [ ] Filter theo trạng thái (full công, nửa công)
- [ ] Export PDF
- [ ] Chart/biểu đồ thống kê
- [ ] So sánh giữa các tháng
- [ ] Gửi email báo cáo

---

**Ngày tạo**: 07/11/2025  
**Version**: 1.0  
**Author**: AI Assistant

