diff --git a/PROJECT_STRUCTURE.md b/PROJECT_STRUCTURE.md new file mode 100644 index 0000000..1838b87 --- /dev/null +++ b/PROJECT_STRUCTURE.md @@ -0,0 +1,257 @@ +# 📁 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` | + +--- + +
+ +**✅ Đọc `README.md` để biết chi tiết hơn!** + +