# 📁 Cấu Trúc Project - Tóm Tắt

## 🎯 Tổng Quan Nhanh

**Mục đích:** Dự đoán số nhân sự cần thiết cho mỗi ca làm việc dựa trên đặc điểm tòa nhà và công việc.

---

## 📊 Luồng Dữ Liệu

```
data_raw/
├── Link LLV 1_5_2025.json          → Thông tin ca làm việc, công việc
└── Link LLV 2025_clean.json        → Đặc điểm vật lý tòa nhà (diện tích TỔNG các tầng)
                ↓
        [Tiền xử lý & Feature Engineering]
                ↓
         final_2.csv/xlsx             → Dataset training (đã có text features)
                ↓
        [ML Training Pipeline]
                ↓
            artifacts/                → Models đã train
            outputs/                  → Kết quả validation
```

---

## 🔄 Luồng Prediction

```
input.json (1 ca làm việc)
        ↓
all_predict.py
        ├── Gọi predict.py → Trích xuất keyword features từ text
        ├── Tiền xử lý các trường diện tích, đặc điểm tòa nhà
        ├── Kết hợp tất cả features
        ├── Load model từ artifacts/
        └── Dự đoán
        ↓
Output: Số nhân sự cần thiết
```

---

## 📂 Cấu Trúc Thư Mục

### 📁 **data_raw/** - Dữ liệu gốc
- `Link LLV 1_5_2025.json` - Ca làm việc, công việc normal + dinhky
- `Link LLV 2025_clean.json` - Diện tích tòa nhà (⚠️ TỔNG các tầng)

### 📁 **artifacts/** - Models
- `extratrees_log1p.joblib` - Model chính
- `extratrees_staff_model.joblib` - Model dự đoán nhân sự
- `model_meta.joblib` - Metadata
- `X_proc_columns.joblib` - Danh sách features

### 📁 **outputs/** - Kết quả
- `val_predictions_extratrees.csv` - So sánh y_true vs y_pred trên validation set

### 📁 **models/** - Models cũ
- Các models từ thử nghiệm trước

---

## 🔧 Files Script Chính

### 1. **predict.py** 🔤
**Vai trò:** Trích xuất keyword features từ text công việc

**Input:**
- `task_normal` (str): Công việc hằng ngày
- `task_dinhky` (str): Công việc định kỳ tuần/tháng

**Output:**
- JSON string chứa 18 text features

**Được gọi bởi:** `all_predict.py`

---

### 2. **all_predict.py** 🎯
**Vai trò:** Script chính để dự đoán

**Workflow:**
1. Đọc `input.json`
2. **Gọi `predict.py`** để trích xuất keyword features
3. Tiền xử lý các trường khác (diện tích, đặc điểm tòa nhà)
4. Kết hợp tất cả features
5. Load model từ `artifacts/`
6. Dự đoán và trả về kết quả

**Input:** `input.json` (1 ca làm việc)
**Output:** Số nhân sự dự đoán

---

### 3. **extract_25_features_new.py** 📊
**Vai trò:** Trích xuất features từ text (phiên bản đầy đủ)

Tương tự `predict.py` nhưng với nhiều features hơn

---

### 4. **merge_all_features.py** 🔗
**Vai trò:** Gộp features từ nhiều nguồn

Tạo dataset hoàn chỉnh cho training

---

## 📄 Files Dữ Liệu

### **final_2.csv / final_2.xlsx** 📈
**Vai trò:** Dataset chính để training model

**Nguồn:**
- Ca làm việc ← `Link LLV 1_5_2025.json`
- Diện tích tòa nhà ← `Link LLV 2025_clean.json` (⚠️ TỔNG các tầng)
- Text features ← Trích xuất từ `all_task_normal` + `all_task_dinhky`

**Features:**
- Thông tin ca: `ca_sang`, `ca_chieu`, `ca_toi`, `ca_dem`
- Diện tích: `dien_tich_hanh_lang`, `dien_tich_wc`, v.v.
- Text features: `num_cleaning_tasks`, `cleaning_ratio`, v.v.
- Target: `so_nhan_su`

---

### **input.json** 🎯
**Vai trò:** File input mẫu cho prediction

**Nội dung:**
- Thông tin tòa nhà: `ma_dia_diem`, `so_tang`, `so_cua_thang_may`
- Thông tin ca: `loai_ca`, `bat_dau`, `ket_thuc`, `tong_gio_lam`
- Công việc:
  - `all_task_normal` - Công việc **HẰNG NGÀY**
  - `all_task_dinhky` - Công việc **ĐỊNH KỲ (tuần/tháng)**
- Diện tích: `dien_tich_*` (⚠️ TỔNG các tầng)
- Đặc điểm: `doc_ham`, `op_tuong`, v.v.

---

### **input_explained.jsonc** 📚
**Vai trò:** File giải thích chi tiết các trường trong input.json

Có comments đầy đủ (file JSONC)

---

## 📓 Notebooks

### **All_feature_Readme.ipynb**
Chi tiết về text features

### **ML_Training_Pipeline_Complete.ipynb**
Pipeline training model hoàn chỉnh

### **ML_Training_Pipeline.ipynb**
Pipeline training cơ bản

---

## 📖 Documentation

### **README.md** 📘
Tài liệu chính của project

### **TASK_TYPES_GUIDE.md** 📋
Hướng dẫn phân biệt 2 loại công việc:
- `all_task_normal` (hằng ngày)
- `all_task_dinhky` (định kỳ tuần/tháng)

### **COMPLETE_25_FEATURES.md** 📝
Giải thích 25 features được trích xuất

### **ML_PIPELINE_PLAN.md** 🗺️
Kế hoạch pipeline ML

---

## ⚠️ Lưu Ý Quan Trọng

### 1. Về Diện Tích
> **Tất cả diện tích là TỔNG của TẤT CẢ các tầng!**
> 
> Ví dụ: 12 tầng × 150m²/tầng = 1800m²
> 
> KHÔNG PHẢI 150m²!

### 2. Về Công Việc
- `all_task_normal`: Làm **MỖI NGÀY**
- `all_task_dinhky`: Làm **THEO TUẦN/THÁNG**
- Model **GỘP CẢ 2** để phân tích

### 3. Về Pipeline Prediction
```
input.json → all_predict.py → predict.py → features → model → output
                      ↓
              [Tiền xử lý các trường khác]
                      ↓
              [Kết hợp features]
                      ↓
              [Load model]
                      ↓
              [Predict]
```

---

## 🚀 Quick Start

### Dự đoán cho 1 ca:
```bash
# 1. Chuẩn bị input.json
# 2. Chạy prediction
python all_predict.py

# 3. Xem kết quả
```

### Xem kết quả validation:
```bash
# Mở file outputs/val_predictions_extratrees.csv
# Cột: y_true (thực tế), y_pred (dự đoán), error
```

### Test keyword extraction:
```python
from predict import extract_text_features_to_json

json_result = extract_text_features_to_json(
    "Lau sàn WC; Thu rác",
    "Cọ bồn cầu; Đánh sàn"
)
print(json_result)
```

---

## 📞 Tài Liệu Tham Khảo

| Thắc mắc về... | Xem tài liệu |
|----------------|--------------|
| Tổng quan project | `README.md` |
| Phân loại công việc | `TASK_TYPES_GUIDE.md` |
| Text features | `All_feature_Readme.ipynb` |
| Input format | `input_explained.jsonc` |
| Pipeline | `README.md` → Pipeline Dự Đoán |
| Validation | `outputs/val_predictions_extratrees.csv` |

---

<div align="center">

**✅ Đọc `README.md` để biết chi tiết hơn!**

</div>