<p align="center"> <img src="docs/assets/econet-nan-banner.png" alt="EcoNet - NaN Header Banner" width="100%" /> </p>

NaN-EcoNet: The Agentic Green Ecosystem

Autonomous Waste Logistics, Citizen Bulky Recycling & Circular 4-Win Economy

<p align="center"> <a href="https://github.com/chinhanxt/NaN-EcoNet/actions/workflows/ci.yml"><img src="https://github.com/chinhanxt/NaN-EcoNet/actions/workflows/ci.yml/badge.svg" alt="CI Monorepo Build" /></a> <a href="docs/testing/coverage-report.md"><img src="https://img.shields.io/badge/Test_Coverage-100%25_(148%2F148)-success.svg?style=for-the-badge&logo=pytest" alt="Test Coverage 100%" /></a> <a href="https://github.com/chinhanxt/NaN-EcoNet/releases"><img src="https://img.shields.io/github/v/release/chinhanxt/NaN-EcoNet?style=for-the-badge&color=3b82f6&logo=github" alt="Release v1.0.0" /></a> <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg?style=for-the-badge&logo=apache" alt="License Apache 2.0" /></a> <a href="#monorepo-ports"><img src="https://img.shields.io/badge/Architecture-Multi--Service_Monorepo-059669.svg?style=for-the-badge&logo=monorepo" alt="Architecture Monorepo" /></a> <a href="#smart-collection"><img src="https://img.shields.io/badge/Route_Engine-3D--PACO_%26_OR--Tools-f97316.svg?style=for-the-badge&logo=speedtest" alt="Route Engine" /></a> <a href="#citizen-bulky"><img src="https://img.shields.io/badge/Vision_AI-Gemini_2.5_Flash-8b5cf6.svg?style=for-the-badge&logo=google" alt="Vision AI" /></a> <a href="#ecopass-enterprise"><img src="https://img.shields.io/badge/Agent_Protocol-MCP_Server-0ea5e9.svg?style=for-the-badge&logo=anthropic" alt="MCP Server" /></a> <a href="https://drive.google.com/file/d/1pFIl_UKL5z9TQ8UQB4PyLLOEf1ttDoX8/view?usp=sharing"><img src="https://img.shields.io/badge/Live_Demo-Google_Drive-ea4335.svg?style=for-the-badge&logo=google-drive" alt="Demo Video" /></a> <a href="https://github.com/chinhanxt/NaN-EcoNet/pulls"><img src="https://img.shields.io/badge/PRs-Welcome-brightgreen.svg?style=for-the-badge&logo=github" alt="PRs Welcome" /></a> </p>

🎬 Video Demo Trình Diễn Hệ Thống Thực Tế: Xem trực tiếp tại Google Drive (Trình diễn đồng thời 3 phân hệ: App Flutter Cư dân, Bản đồ Dual-Map 8502, BI Copilot 3011 và MMO Automation).

---

📑 Mục lục (Table of Contents)

1. Tổng quan Dự án (Executive Summary)
2. Kiến trúc Hợp nhất & Luồng Vận hành (Unified Architecture & Sequence)
3. Phân hệ 1: Chí Nhân — EcoPass Enterprise & Omni-Channel Hub
4. Phân hệ 2: Công Nghiệp — Smart Collection & 3D-PACO Routing Engine
5. Phân hệ 3: Quốc Anh — Citizen Bulky Waste & AI Vision Platform
6. Cấu trúc Monorepo & Tra cứu Cổng Dịch vụ (Topology & Port Mapping)
7. Hướng dẫn Khởi chạy Nhanh (Quick Start)
8. Đối sánh Hiệu năng Thực nghiệm (Empirical Benchmarks)
9. Bản quyền & Trích dẫn Nghiên cứu (Citation)

---

<a id="executive-summary"></a>

🌍 1. Tổng Quan Dự Án (Executive Summary)

Tại các siêu đô thị đang phát triển nhanh như TP. Hồ Chí Minh và Hà Nội, tốc độ đô thị hóa nhanh chóng tạo ra hơn 64.000 tấn rác sinh hoạt mỗi ngày. Hệ sinh thái NaN-EcoNet tập trung giải quyết dứt điểm 4 điểm nghẽn đô thị cốt lõi:

• 🛋️ Rác cồng kềnh quá tải: Đồ nội thất cũ (sofa, nệm, tủ gỗ) bị xả bừa bãi ra vỉa hè do thiếu kênh đặt lịch thu gom chính thống và chi phí phát sinh tùy tiện tại hiện trường.
• 🚛 Logistics thu gom kém hiệu quả: Xe rác chạy tuyến cố định gây lãng phí nhiên liệu Diesel, luồn lách vào ngõ hẹp gây ùn tắc giao thông và xả khí thải $\text{CO}_2$.
• 🌿 Thiếu động lực kinh tế tuần hoàn: Người dân chưa có thói quen phân loại rác tại nguồn; doanh nghiệp FMCG đối mặt áp lực kiểm toán định mức tái chế bắt buộc (EPR - Nghị định 08/2022/NĐ-CP).
• 📢 Truyền thông xanh thủ công, tốn kém & rời rạc: Các chiến dịch vận động môi trường hiện nay phụ thuộc hoàn toàn vào nhân sự viết bài thủ công, chi phí thiết kế đồ họa đắt đỏ, nội dung khô khan khó lan tỏa, không duy trì được tần suất xuất bản đều đặn trên đa nền tảng mạng xã hội.

💡 Điểm Đột Phá (The Game Changer): NaN-EcoNet tích hợp Omni-Channel Agentic Media Hub do AI làm chủ 100%: Tự động tạo ảnh poster thẩm mỹ cao qua đa mô hình SOTA (apps/ecopass-enterprise/agy-image-gateway: FLUX / Imagen / Qwen), tự động dựng video ngắn 9:16 bằng FFmpeg, viết caption bắt trend và tự động đăng tải đa kênh lên Facebook Page, TikTok và YouTube Shorts với chi phí vận hành gần như bằng 0.

graph LR
  A["📱 Quốc Anh\nCitizen Bulky App\n• Gemini AI Vision\n• Báo giá 4 thành phần\n• Khóa giá 15 phút"] -->|Đẩy đơn gom rác| B["🚛 Công Nghiệp\nSmart Collection\n• 3D-PACO C++ Core\n• Google OR-Tools\n• Local OSRM đường bộ"]
  B -->|Dữ liệu thu gom & GPS| C["🌿 Chí Nhân\nEcoPass Enterprise\n• MCP BI Copilot & EPR\n• AI Media Hub Auto-Post\n• Mô hình tuần hoàn 4-WIN"]
  C -->|Điểm thưởng voucher F&B| A
  C -->|Auto-post ảnh & video 9:16| D["📢 Viral Đa Nền Tảng\n• Facebook Page\n• TikTok Studio\n• YouTube Shorts"]
  D -.->|Lan tỏa & thu hút cư dân| A

---

<a id="unified-architecture"></a>

🏗️ 2. Kiến Trúc Hợp Nhất & Luồng Vận Hành Khép Kín

<p align="center"> <img src="docs/assets/diagrams/system-topology.png" alt="NaN-EcoNet System Topology" width="95%" /> </p> <p align="center"><i>Hình 1: Kiến trúc Monorepo phân tầng và luồng dữ liệu liên phân hệ</i></p> <p align="center"> <img src="docs/assets/diagrams/sequence-flow.png" alt="NaN-EcoNet End-to-End Sequence Loop" width="95%" /> </p> <p align="center"><i>Hình 2: Quy trình 5 bước khép kín từ lúc quét ảnh AI đến khi thu gom và cấp voucher</i></p>

Tóm Tắt 5 Bước Vận Hành:

1. Quét ảnh & Báo giá tức thời: Cư dân chụp ảnh đồ cũ qua camera app; Gemini 2.5 Flash phân tích Bounding Box và kích thước $L \times W \times H$; Pricing Engine khóa báo giá trong 15 phút.
2. Đặt lịch & Chốt cọc: Cư dân xác nhận khung giờ hẹn; đơn hàng được đóng gói theo schema chuẩn BulkyOrderPayload.
3. Tối ưu định tuyến 3D-PACO: Động cơ VRP gộp đơn rác cồng kềnh cùng các thùng rác công cộng, tự động phân loại hình thức (xe vào tận nơi vs nhân viên gom bộ đầu hẻm).
4. Thu gom & Giám sát hiện trường: Tài xế di chuyển theo lộ trình OSRM; cam kết không phát sinh phụ phí nếu sai lệch thực tế $\le \pm 10%$.
5. Cấp điểm thưởng, Kiểm toán EPR & AI Đăng bài: Hệ thống cấp voucher Highlands Coffee/căn tin cho người dân; xuất dữ liệu tái chế sạch định vị GPS cho doanh nghiệp FMCG qua MCP Server; kích hoạt AI tự động tạo ảnh/video tổng kết thành quả và xuất bản lên mạng xã hội.

---

<a id="ecopass-enterprise"></a>

🌿 3. Phân Hệ 1: Chí Nhân — EcoPass Enterprise & Omni-Channel Hub

Thư mục: apps/ecopass-enterprise • Kỹ sư phụ trách: Nguyễn Chí Nhân (chinhanxt)

<p align="center"> <img src="docs/assets/diagrams/ecopass-enterprise-arch.png" alt="EcoPass Enterprise 4 Pillars Architecture" width="95%" /> </p> <p align="center"><i>Hình 3: Kiến trúc phân hệ Enterprise tích hợp MCP Server, BI Copilot và AI Gateway</i></p>

Điểm Nhấn Công Nghệ Cốt Lõi:

• Enterprise BI Copilot & MCP Tools: Hiện thực hóa chuẩn giao thức Model Context Protocol (MCP), cho phép AI Agent (apps/ecopass-enterprise/enterprise-bi-copilot) tự khám phá công cụ, thực thi truy vấn Text-to-SQL an toàn với bộ lọc bảo mật đa tầng AST & Whitelist và truy xuất dữ liệu kiểm toán EPR chuẩn JSON Schema v1.
• Dynamic Diagram Engine: Phân tích cú pháp hội thoại và tự động biên dịch trực tiếp sang sơ đồ Mermaid.js và PlantUML ngay trên màn hình chat của ban điều hành tại apps/ecopass-enterprise/enterprise-bi-copilot/.
• AI Visual Synthesis Gateway (agy-image-gateway): Proxy tập trung tích hợp các mô hình sinh ảnh SOTA (FLUX.1-Dev, Google Imagen 3, Alibaba Qwen-Image-2 Pro) kết hợp bộ nhớ đệm SHA-256 prompt cache tối ưu chi phí API.
• Tự Động Hóa Truyền Thông Đa Nền Tảng (nan-team/scripts): Kịch bản tự động hóa sản xuất và phân phối nội dung xanh đa kênh:
  • Facebook Page (facebook-page-upload.js): Tự động sinh caption chuẩn SEO và đăng tải poster / carousel qua Playwright automation.
  • TikTok Studio & YouTube Shorts (tiktok-creator-upload.js, youtube-studio-upload.js): Tự động dựng video dọc 9:16 với hiệu ứng Pan/Zoom & âm thanh qua FFmpeg pipeline, xuất bản tự động kèm hashtag xu hướng #SongXanh #EcoPass.
  • Session Resilience & Rate-Limiting: Tự động xoay vòng Cookie và giãn cách ngẫu nhiên (Exponential Backoff with Jitter) đảm bảo an toàn tài khoản và chống nghẽn mạng.

<p align="center"> <img src="docs/assets/diagrams/ecopass-4win.png" alt="EcoPass 4-Win Circular Economy Model" width="90%" /> </p> <p align="center"><i>Hình 4: Mô hình kinh tế tuần hoàn 4-WIN liên kết dòng tiền giữa 4 bên</i></p>

Ma Trận Lợi Ích Định Lượng 4-WIN:

| Bên Tham Gia | Giá Trị Nhận Được | Nếu Thiếu EcoNet | Lợi Ích Đo Lường Thực Tế | | :--- | :--- | :--- | :--- | | 1. Sinh Viên & Cư Dân | Tiết kiệm chi phí sinh hoạt qua voucher; xử lý đồ cũ văn minh. | Bị ép giá ba gác; không có động lực phân loại rác tại nguồn. | Thu nhập tích lũy: 150.000 – 350.000 VNĐ/tháng; bảo vệ giá dung sai $\le \pm 10%$. | | 2. Đội Thu Gom Rác | Tuyến xe thông minh; xe chạy đúng tải; bảo vệ an toàn công nhân. | Lộ trình chồng chéo; kẹt xe ngõ hẹp; bới rác thủ công độc hại. | Giảm 28.4% cự ly chạy xe ($3.87\text{ L Diesel/ca}$); tăng 35% năng suất phục vụ. | | 3. Cửa Hàng / Căn Tin | Đón tiếp dòng sinh viên đến đổi voucher; tăng doanh số bán kèm. | Chi phí quảng cáo kém hiệu quả; bàn ghế trống vào giờ thấp điểm. | Tỷ lệ chuyển đổi voucher 68.0%; tăng 18% doanh thu từ các món ăn/nước uống bán kèm. | | 4. Nhãn Hàng FMCG | Tuân thủ 100% Nghị định 08/2022/NĐ-CP; dữ liệu sạch phục vụ ESG. | Bị xử phạt hành chính; truy thu nộp Quỹ Bảo vệ Môi trường. | Tiết kiệm 35 – 45% chi phí tuân thủ EPR so với phương án nộp phạt hoặc thuê kiểm toán ngoài. |

---

<a id="smart-collection"></a>

🚛 4. Phân Hệ 2: Công Nghiệp — Smart Collection & 3D-PACO Routing Engine

Thư mục: apps/smart-collection-engine • Kỹ sư phụ trách: Bùi Nguyễn Công Nghiệp (congnghip)

<p align="center"> <img src="docs/assets/diagrams/smart-routing.png" alt="Smart Collection Engine 3D-PACO Routing Pipeline" width="95%" /> </p> <p align="center"><i>Hình 5: Pipeline thuật toán tối ưu hóa tuyến thu gom 3D-PACO kết hợp Google OR-Tools</i></p>

Điểm Nhấn Kỹ Thuật Cốt Lõi:

• Thuật Toán 3D-PACO (Bi-Modal Decision Parallel ACO): Mở rộng đồ thị kiến bằng chiều quyết định nhị phân $o \in {0, 1}$ ($o = 0$: xe tải vào tận nơi; $o = 1$: nhân viên đi bộ gom rác đầu ngõ hẹp). Khắc phục triệt để bài toán ngõ hẹp đô thị Việt Nam; chi tiết kiến trúc tại ADR-001 và bộ kiểm chứng bất biến tại tests/algorithms/test_vrp_invariants.py.
• *Song Song Hóa C++ OpenMP 8-Luồng: