Hướng Dẫn Sử Dụng Google Antigravity Tự Động Hóa Sắp Xếp & Dọn Dẹp Thư Mục Máy Tính: Phân Loại Tệp Thông Minh Bằng AI Agents & Python 2026

# -*- coding: utf-8 -*-
"""
Smart Folder Organizer & Cleaner (Powered by Google Antigravity & Python)
Công cụ tự động hóa sắp xếp, dọn dẹp thư mục máy tính thông minh & an toàn 100%
Phiên bản: 2026.1 - Ban Biên Tập Công Nghệ NIE.vn
"""

import os
import sys
import shutil
import hashlib
import json
from pathlib import Path
from datetime import datetime

# Đảm bảo in tiếng Việt chuẩn trên Windows Command Prompt / PowerShell
if sys.platform.startswith('win'):
    try:
        sys.stdout.reconfigure(encoding='utf-8', errors='replace')
        sys.stderr.reconfigure(encoding='utf-8', errors='replace')
    except Exception:
        pass

# Bảng phân loại 9 họ tệp tin thông dụng
FILE_EXTENSIONS_MAP = {
    "1_Tai_Lieu_Van_Ban": [".pdf", ".docx", ".doc", ".txt", ".rtf", ".odt", ".epub"],
    "2_Bang_Tinh_So_Lieu": [".xlsx", ".xls", ".csv", ".tsv"],
    "3_Trinh_Chieu_Giao_An": [".pptx", ".ppt", ".key"],
    "4_Hinh_Anh": [".jpg", ".jpeg", ".png", ".gif", ".webp", ".svg", ".bmp", ".ico", ".psd", ".ai"],
    "5_Video_Phim": [".mp4", ".mkv", ".mov", ".avi", ".flv", ".wmv", ".webm"],
    "6_Am_Thanh_Ghi_Am": [".mp3", ".wav", ".aac", ".flac", ".m4a", ".ogg"],
    "7_Tep_Nen_Giai_Nen": [".zip", ".rar", ".7z", ".tar", ".gz", ".iso"],
    "8_Bo_Cai_Dat_Phan_Mem": [".exe", ".msi", ".apk", ".dmg"],
    "9_Ma_Nguon_Lap_Trinh": [".py", ".html", ".css", ".js", ".json", ".sql", ".php", ".cpp", ".java"]
}

def get_category_for_file(ext):
    """Xác định danh mục thư mục dựa theo đuôi mở rộng"""
    ext = ext.lower()
    for cat, exts in FILE_EXTENSIONS_MAP.items():
        if ext in exts:
            return cat
    return "10_Tap_Tin_Khac"

def get_file_hash(file_path, block_size=65536):
    """Tính mã băm SHA-256 để phát hiện tệp trùng lặp nội dung chính xác 100%"""
    hasher = hashlib.sha256()
    try:
        with open(file_path, 'rb') as f:
            buf = f.read(block_size)
            while len(buf) > 0:
                hasher.update(buf)
                buf = f.read(block_size)
        return hasher.hexdigest()
    except Exception:
        return None

def scan_directory(target_dir, group_by="type_and_date"):
    """Quét sâu thư mục gốc và lập kế hoạch phân loại tệp tin"""
    target_path = Path(target_dir).resolve()
    if not target_path.exists() or not target_path.is_dir():
        print(f"❌ Thư mục không tồn tại: {target_path}")
        return None, None

    plan = []
    seen_hashes = {}
    duplicates = []

    print(f"\n🔍 Đang quét sâu thư mục: {target_path}")
    
    # Chỉ quét tệp ở thư mục gốc (không quét đệ quy vào các thư mục đã phân loại)
    for entry in os.scandir(target_path):
        if entry.is_file():
            file_path = Path(entry.path)
            # Bỏ qua tệp hệ thống và tệp lịch sử hoàn tác
            if file_path.name.startswith(".") or file_path.name in ["desktop.ini", "organizer_history.json"]:
                continue

            file_stat = file_path.stat()
            mod_time = datetime.fromtimestamp(file_stat.st_mtime)
            year_month = mod_time.strftime("%Y-%m")
            category = get_category_for_file(file_path.suffix)
            size_kb = round(file_stat.st_size / 1024, 1)

            # Tính toán đường dẫn thư mục đích
            if group_by == "type":
                dest_subdir = target_path / category
            elif group_by == "date":
                dest_subdir = target_path / year_month
            else: # type_and_date (kết hợp Họ tệp / Năm-Tháng)
                dest_subdir = target_path / category / year_month

            dest_path = dest_subdir / file_path.name

            # Kiểm tra tệp trùng lặp bằng SHA-256 cho các tệp < 100MB
            f_hash = get_file_hash(file_path) if file_stat.st_size < 100 * 1024 * 1024 else None
            if f_hash and f_hash in seen_hashes:
                original_file = seen_hashes[f_hash]
                duplicates.append({
                    "duplicate": str(file_path),
                    "original": str(original_file),
                    "size_kb": size_kb
                })
            elif f_hash:
                seen_hashes[f_hash] = file_path

            plan.append({
                "source": str(file_path),
                "filename": file_path.name,
                "category": category,
                "dest_folder": str(dest_subdir),
                "dest_path": str(dest_path),
                "size_kb": size_kb,
                "modified": mod_time.strftime("%Y-%m-%d %H:%M")
            })

    return plan, duplicates

def display_plan(plan, duplicates):
    """Hiển thị bảng tổng hợp kế hoạch phân loại (Dry-Run Preview)"""
    print("\n" + "=" * 75)
    print("📊 BẢNG TỔNG HỢP KẾ HOẠCH PHÂN LOẠI (DRY-RUN PREVIEW)")
    print("=" * 75)
    print(f"Tổng số tệp phát hiện: {len(plan)} tệp")
    if duplicates:
        print(f"⚠️ Cảnh báo: Phát hiện {len(duplicates)} tệp trùng lặp 100% nội dung (SHA-256)")

    cat_counts = {}
    for item in plan:
        cat = item['category']
        cat_counts[cat] = cat_counts.get(cat, 0) + 1

    print("\nPhân bổ tệp theo nhóm danh mục đích:")
    for cat, count in sorted(cat_counts.items()):
        print(f"  📁 {cat:<26}: {count:>3} tệp")

    print("\nTrích xuất 10 tệp tiêu biểu sẽ được di chuyển:")
    for item in plan[:10]:
        dest_rel = Path(item['dest_path']).parent.name + "/" + item['filename']
        print(f"  📄 {item['filename'][:30]:<32} ➔ 📂 {dest_rel}")

    if len(plan) > 10:
        print(f"  ... và còn {len(plan) - 10} tệp khác.")
    print("=" * 75)

def execute_plan(plan, target_dir):
    """Thực thi di chuyển tệp tin với cơ chế ghi log hoàn tác JSON"""
    history_file = Path(target_dir) / "organizer_history.json"
    history_entries = []

    print("\n🚀 Bắt đầu quá trình di chuyển an toàn...")
    moved_count = 0

    for item in plan:
        src = Path(item['source'])
        dst = Path(item['dest_path'])
        
        # Tự động tạo thư mục đích nếu chưa có
        dst.parent.mkdir(parents=True, exist_ok=True)

        # Xử lý an toàn nếu đã có tệp cùng tên ở đích
        final_dst = dst
        counter = 1
        while final_dst.exists() and final_dst.resolve() != src.resolve():
            stem = dst.stem
            suffix = dst.suffix
            final_dst = dst.parent / f"{stem}_{counter}{suffix}"
            counter += 1

        if src.resolve() != final_dst.resolve():
            shutil.move(src, final_dst)
            history_entries.append({
                "original": str(src),
                "moved_to": str(final_dst)
            })
            moved_count += 1

    # Lưu lịch sử để phục vụ hoàn tác (Rollback)
    with open(history_file, 'w', encoding='utf-8') as f:
        json.dump(history_entries, f, ensure_ascii=False, indent=2)

    print(f"\n🎉 HOÀN TẤT! Đã phân loại an toàn {moved_count}/{len(plan)} tệp tin.")
    print(f"💾 Lịch sử hoàn tác đã lưu tại: {history_file.name}")
    print("👉 Khi cần khôi phục về vị trí cũ, chạy lệnh: python smart_folder_organizer.py --rollback <thư_mục>")

def rollback(target_dir):
    """Đưa toàn bộ tệp tin đã di chuyển trở lại chính xác vị trí gốc"""
    history_file = Path(target_dir) / "organizer_history.json"
    if not history_file.exists():
        print(f"❌ Không tìm thấy tệp nhật ký lịch sử: {history_file}")
        return

    with open(history_file, 'r', encoding='utf-8') as f:
        history = json.load(f)

    print(f"\n🔄 Bắt đầu hoàn tác {len(history)} tệp tin...")
    restored = 0
    for item in history:
        moved_file = Path(item['moved_to'])
        orig_file = Path(item['original'])
        if moved_file.exists():
            orig_file.parent.mkdir(parents=True, exist_ok=True)
            shutil.move(moved_file, orig_file)
            restored += 1

    print(f"✅ Đã khôi phục hoàn chỉnh {restored}/{len(history)} tệp tin về nguyên trạng!")
    history_file.unlink() # Xóa tệp lịch sử sau khi hoàn tất đảo ngược

if __name__ == "__main__":
    import argparse
    parser = argparse.ArgumentParser(description="Google Antigravity Smart Folder Organizer 2026")
    parser.add_argument("folder", nargs="?", default=".", help="Đường dẫn thư mục cần dọn dẹp")
    parser.add_argument("--dry-run", action="store_true", help="Chế độ chạy thử mô phỏng")
    parser.add_argument("--execute", action="store_true", help="Thực thi di chuyển thật")
    parser.add_argument("--group-by", choices=["type", "date", "type_and_date"], default="type", help="Quy chuẩn phân nhóm")
    parser.add_argument("--rollback", action="store_true", help="Hoàn tác trạng thái trước khi dọn dẹp")

    args = parser.parse_args()

    if args.rollback:
        rollback(args.folder)
    else:
        plan, dupes = scan_directory(args.folder, group_by=args.group_by)
        if plan is not None and len(plan) > 0:
            display_plan(plan, dupes)
            if args.execute:
                execute_plan(plan, args.folder)
            elif not args.dry_run:
                print("\n💡 Mẹo: Chạy với cờ `--execute` để di chuyển thật, hoặc `--dry-run` để chỉ xem trước.")
        elif plan is not None:
            print("✨ Thư mục hiện tại đã hoàn toàn sạch sẽ, không có tệp rời cần phân loại!")