# 🎯 PROJECT CONTEXT — MỤC TIÊU DỰ ÁN & Ý TƯỞNG GIẢI PHÁP

## 1. Tầm Nhìn & Định Vị Dự Án (Project Vision)

Dự án này là hệ sinh thái công nghệ tương tác không gian thế hệ mới trên macOS, bao gồm 2 phân hệ rõ ràng:

1. **Sản phẩm cốt lõi (Core Product): Handy**
   - **Định vị**: Spatial Gesture Control Engine for Mac — biến webcam FaceTime HD tích hợp hoặc iPhone (qua Continuity Camera) thành hệ thống theo dõi bàn tay không gian 3D tự do (free-hand spatial tracking) chuẩn visionOS.
   - **Mục tiêu**: Người dùng có thể điều khiển con trỏ chuột, click, kéo thả, kích hoạt Mission Control, chuyển Spaces ảo bằng các cử chỉ tay tự nhiên ngay trước màn hình máy tính mà **không cần đeo kính cồng kềnh hay găng tay cảm biến**.
   - **Tối ưu hóa phần cứng**: Chạy trực tiếp trên Apple Neural Engine (ANE) của chip Apple Silicon (M1/M2/M3/M4/M5), độ trễ < 8ms, tần số 60 FPS, khử rung nhiễu bằng bộ lọc EMA, và chế độ Zero-CPU tự ngắt camera khi nghỉ tay để bảo vệ pin máy Mac.

2. **Bản Demo Ứng Dụng (Killer Reference Showcase): Fulldy Warehouse 3D**
   - **Định vị**: Ứng dụng mô phỏng 3D Digital Twin trung tâm kho vận thông minh (Serious Game & Decision Sandbox) phát triển bằng Three.js WebGL và bitECS.
   - **Mục tiêu trong hệ sinh thái**: Đóng vai trò là **minh chứng thực tế (Reference Implementation)** cho thấy sức mạnh của Handy khi ứng dụng vào một bài toán nghiệp vụ phức tạp:
     - Dùng cử chỉ Air Pinch và Pointer để xoay camera 3D quanh kho hàng 40.000m².
     - Chỉ tay chọn pallet hàng, bấm nút dispatch robot AGV và giám sát băng chuyền tự động mà không cần chạm tay vào bàn phím hay chuột vật lý.
   - **Ranh giới**: Kho hàng Fulldy là bản demo độc lập nằm trong `demos/warehouse/`, không phải là sản phẩm cốt lõi của repo.

---

## 2. Bài Toán Thực Tế Cần Giải Quyết (Problem Statement)

1. **Hạn chế của thiết bị ngoại vi truyền thống**:
   - Chuột và bàn di chuột (trackpad) gây hội chứng ống cổ tay (RSI) khi làm việc liên tục.
   - Khi thuyết trình, hội họp từ xa, hoặc điều khiển từ khoảng cách 1-3 mét, việc phải với tới chuột là bất tiện.
2. **Rào cản đắt đỏ của kính AR/VR (Apple Vision Pro, Meta Quest)**:
   - Các kính thực tế ảo nặng nề, giá thành cao (\$3,500+), gây mỏi mắt và cô lập người dùng với thế giới xung quanh.
3. **Thách thức của các giải pháp nhận diện cử chỉ thông thường**:
   - Ngốn pin (20-40% CPU nếu chạy naive computer vision trên CPU).
   - Rung giật con trỏ chuột (jittering) khiến thao tác click trượt mục tiêu.
   - Thiếu phản hồi thị giác trực quan (visual feedback) khiến người dùng bối rối không biết hệ thống đã nhận cử chỉ hay chưa.

---

## 3. Ý Tưởng & Giải Pháp Kỹ Thuật Đột Phá Của Handy

### A. Động Cơ Cử Chỉ Không Gian (Spatial Gesture Matrix)
Handy chuẩn hóa 5 cử chỉ không gian tự nhiên theo triết lý Apple Human Interface Guidelines:
- 🤏 **Air Pinch (Ngón trỏ + cái chụm lại)**: Mô phỏng nhấp chuột trái (Left Click). Khi giữ chụm sẽ kích hoạt kéo thả (Mouse Drag).
- 👆 **Index Pointer (Ngón trỏ mở thẳng, các ngón khác gập)**: Điều khiển tọa độ con trỏ chuột toàn màn hình một cách mượt mà.
- 🖐 **Open Palm (5 ngón tay xòe rộng)**: Khóa vị trí chuột tạm thời hoặc ngưng nhận lệnh để người dùng nghỉ tay tự nhiên.
- ✌️ **Peace / V-Sign (2 ngón tay giơ chữ V)**: Kích hoạt Mission Control (`Control + Up Arrow`) để xem toàn bộ cửa sổ.
- 🫳 **Swipe Left / Right (Vung tay nhanh sang trái/phải)**: Chuyển đổi Spaces ảo trên macOS (`Control + Left/Right Arrow`).

### B. Vòng Đời Tiết Kiệm Năng Lượng Zero-CPU (Power State Machine)
- `ACTIVE (60 FPS)`: Bàn tay xuất hiện trong khung hình và đang tương tác. Tiêu thụ ~1.2% - 2.5% CPU trên Apple Silicon nhờ tận dụng phần cứng Vision & ANE chuyên dụng.
- `IDLE (3 FPS)`: Khi không phát hiện bàn tay trong 3 giây liên tục. Tần số quét giảm sâu xuống 3 FPS, tiêu thụ ~0.2% CPU.
- `DEEP SLEEP (0.0% CPU)`: Tự động ngắt hoàn toàn session camera khi người dùng hạ tay hoặc khóa màn hình. 0.0% CPU, không hao pin, bảo vệ quyền riêng tư người dùng.

### C. Giao Diện Chuẩn Apple Liquid Glass (visionOS Design)
- Ứng dụng chạy thường trực trên Menu Bar với icon monochrome thông minh.
- Cửa sổ Onboarding và Huấn luyện cử chỉ 4 bước được thiết kế với vật liệu kính mờ cao cấp (Liquid Glass / Ultra-thin Material), phản hồi thời gian thực với mô hình xương bàn tay 3D (Holographic Hand Skeleton).

---

## 4. Giá Trị Của Việc Tách Biệt Codebase (Architecture Separation)

- **Tránh nhầm lẫn vai trò**: Nhà phát triển và AI Agents không bị lẫn lộn giữa mã nguồn Swift native của hệ điều hành macOS với mã nguồn JavaScript 3D của bản demo kho hàng.
- **Quy trình build độc lập**: Handy có script đóng gói Swift Package Manager riêng (`macos-handy/Scripts/build-handy.sh`), bản demo kho hàng có pipeline Three.js và bitECS riêng.
- **Tiến hóa mở rộng**: Trong tương lai, Handy có thể hỗ trợ thêm nhiều demo khác (ví dụ: demo điều khiển nhạc, demo lướt web bằng cử chỉ, demo điều khiển slide thuyết trình Keynote) mà không ảnh hưởng đến lõi Handy engine.