|
| 1 | +# Trash Sorter Pro — Project Showcase |
| 2 | + |
| 3 | +Tài liệu này dùng để giới thiệu dự án trên GitHub/portfolio và làm checklist |
| 4 | +nhanh khi bàn giao cho người vận hành. Ảnh minh hoạ trong file được chụp trực |
| 5 | +tiếp từ desktop app và web production. |
| 6 | + |
| 7 | +## GitHub About nên điền |
| 8 | + |
| 9 | +Ảnh người dùng gửi cho thấy phần **About** của repository còn trống. Nội dung đề |
| 10 | +xuất: |
| 11 | + |
| 12 | +- **Description:** AI-powered waste sorting system with YOLO, PySide6 desktop control, Next.js dashboard, UART/Arduino hardware bridge, Supabase and EcoPet AI. |
| 13 | +- **Website:** `https://trash-sorter-v2.vercel.app` |
| 14 | +- **Topics:** `yolo`, `computer-vision`, `waste-sorting`, `pyside6`, `nextjs`, `fastapi`, `arduino`, `uart`, `iot`, `supabase`, `deepseek`, `vercel` |
| 15 | +- **README:** giữ ảnh desktop/web ở đầu README để GitHub About trỏ vào trang giới thiệu có hình ngay. |
| 16 | +- **Releases:** khi chốt bản demo, tạo release theo mẫu `vYYYY.MM.DD-demo` và gắn các ghi chú: desktop build, web URL, model runtime, phần cứng đã test. |
| 17 | + |
| 18 | +## Ảnh minh hoạ |
| 19 | + |
| 20 | +### Desktop app |
| 21 | + |
| 22 | + |
| 23 | + |
| 24 | +Desktop app là bề mặt vận hành trực tiếp tại máy phân loại. Màn hình Live cho |
| 25 | +Admin bật/tắt camera, chọn chế độ chỉ nhận diện hoặc tự động phân loại, xem |
| 26 | +camera stream, kết quả hiện tại, trạng thái UART/model/FPS và cấu hình loa. |
| 27 | + |
| 28 | +### Web dashboard |
| 29 | + |
| 30 | + |
| 31 | + |
| 32 | +Web dashboard cho User tổng hợp dữ liệu đã phân quyền: tổng lượt phân loại, tỷ |
| 33 | +lệ tái chế, độ tin cậy AI, Eco Score, biểu đồ theo ngày, trạng thái thùng, cảnh |
| 34 | +báo và lịch sử gần đây. |
| 35 | + |
| 36 | +### EcoPet AI |
| 37 | + |
| 38 | + |
| 39 | + |
| 40 | +EcoPet AI trả lời bằng tiếng Việt có dấu, dùng context đã scope theo quyền tài |
| 41 | +khoản và không gửi secret, token, raw log, ảnh camera hoặc dữ liệu của tài khoản |
| 42 | +khác lên AI provider. |
| 43 | + |
| 44 | +## Kiến trúc tổng quan |
| 45 | + |
| 46 | +```mermaid |
| 47 | +flowchart LR |
| 48 | + Camera["USB camera"] --> Desktop["Desktop app PySide6"] |
| 49 | + Desktop --> YOLO["YOLO runtime model"] |
| 50 | + YOLO --> ThreeBin["3-bin classifier"] |
| 51 | + ThreeBin --> UART["UART / Arduino / Servo"] |
| 52 | + Desktop --> LocalAgent["FastAPI local agent"] |
| 53 | + LocalAgent --> LocalDB["History + operations DB"] |
| 54 | + LocalDB --> Web["Next.js web dashboard"] |
| 55 | + Web --> Supabase["Supabase/PostgreSQL cloud data"] |
| 56 | + Web --> DeepSeek["DeepSeek server-side chatbot"] |
| 57 | +``` |
| 58 | + |
| 59 | +## Thành phần chính |
| 60 | + |
| 61 | +| Thành phần | Công nghệ | Vai trò | |
| 62 | +| --- | --- | --- | |
| 63 | +| Desktop app | Python, PySide6 | Điều khiển camera, live detection, mapping, data review, training, settings | |
| 64 | +| AI runtime | YOLO + 3-bin classifier | Nhận diện class chi tiết và gom về Hữu cơ/Vô cơ/Tái chế | |
| 65 | +| Hardware | USB camera, UART, Arduino/ESP32, servo, loa | Phân loại vật lý và phản hồi âm thanh | |
| 66 | +| Local agent | FastAPI | API cho web local, auth, history, dataset, model, hardware bridge | |
| 67 | +| Web dashboard | Next.js, TypeScript | UI Admin/User, báo cáo, bản đồ, cảnh báo, EcoPet | |
| 68 | +| Cloud data | Supabase/PostgreSQL | Lưu auth/session, history scoped theo user, bin map, alerts, schedules | |
| 69 | +| AI assistant | DeepSeek server-side | Chatbot/Admin advisor với prompt role-safe và fallback tiếng Việt có dấu | |
| 70 | + |
| 71 | +## Luồng vận hành thực tế |
| 72 | + |
| 73 | +1. Camera USB đọc khay rác. |
| 74 | +2. YOLO nhận diện vật thể chi tiết. |
| 75 | +3. Runtime lọc bbox nhiễu, xử lý confidence và gom class về 3 nhóm. |
| 76 | +4. Desktop app hiển thị kết quả, ghi lịch sử và phát loa. |
| 77 | +5. Khi bật tự động, app gửi lệnh UART tới Arduino/ESP32 để điều khiển servo/thùng. |
| 78 | +6. Web dashboard đọc dữ liệu đã đồng bộ để User/Admin theo dõi. |
| 79 | +7. EcoPet/Admin chat dùng context đã sanitize để trả lời câu hỏi vận hành. |
| 80 | + |
| 81 | +## Phân quyền |
| 82 | + |
| 83 | +| Role | Được phép | Bị chặn | |
| 84 | +| --- | --- | --- | |
| 85 | +| User | Dashboard cá nhân, Eco Score, lịch sử của mình, bản đồ thùng được gán, cảnh báo, lịch thu gom, báo lỗi thiết bị, EcoPet | Camera, training, dataset, model, logs, settings, tài khoản khác | |
| 86 | +| Admin | Toàn bộ dashboard vận hành, camera, training, map, alerts, devices, roles, reports, AI knowledge | Không nhận secret/token/raw log trong chatbot | |
| 87 | + |
| 88 | +## Điểm nổi bật để đưa vào README/portfolio |
| 89 | + |
| 90 | +- End-to-end từ camera thật đến dashboard cloud, không chỉ là notebook model. |
| 91 | +- Desktop app vận hành được phần cứng: camera USB, UART, servo, loa, trạng thái model/FPS. |
| 92 | +- Web dashboard có phân quyền Admin/User và dữ liệu User được scope theo username. |
| 93 | +- EcoPet AI đã chạy production qua Vercel server-side, có quota và fallback tiếng Việt có dấu. |
| 94 | +- Supabase/PostgreSQL hỗ trợ cloud auth, operations map, alerts và lịch thu gom. |
| 95 | +- Tài liệu kiểm thử có unit/integration/e2e, Playwright và checklist phần cứng. |
| 96 | + |
| 97 | +## Link vận hành nhanh |
| 98 | + |
| 99 | +- Web production: [trash-sorter-v2.vercel.app](https://trash-sorter-v2.vercel.app) |
| 100 | +- Hướng dẫn web: [huong-dan-chay-web-app.md](huong-dan-chay-web-app.md) |
| 101 | +- Cloud readiness: [supabase-full-cloud-readiness.md](supabase-full-cloud-readiness.md) |
| 102 | +- Hardware checklist: [hardware_integration_checklist.md](hardware_integration_checklist.md) |
| 103 | +- Operations map: [operations-map-local-first.md](operations-map-local-first.md) |
| 104 | + |
| 105 | +## Checklist trước khi tạo GitHub Release |
| 106 | + |
| 107 | +- `npm run test:unit` |
| 108 | +- `npm run build` |
| 109 | +- Playwright smoke cho User/Admin critical paths. |
| 110 | +- Desktop app mở được Live, Settings, Mapping, History. |
| 111 | +- Camera USB ngoài được nhận; laptop webcam không được auto fallback. |
| 112 | +- UART chỉ bật khi cổng USB/Arduino thật sẵn sàng. |
| 113 | +- DeepSeek key nằm ở server-side env, không dùng `NEXT_PUBLIC_*`. |
| 114 | +- Ảnh README đã cập nhật sau khi UI thay đổi lớn. |
| 115 | + |
0 commit comments