Eco-Track 🌿

Hệ Thống Theo Dõi & Dự Đoán Chất Lượng Không Khí TP.HCM

"Theo dõi hôm nay để bảo vệ bầu trời ngày mai."

📖 API Docs • 🗺 Bản đồ AQI • 📊 Dashboard Admin • 🚀 Release Guide • 🤝 Đóng Góp 📝 Changelog

Eco-Track thu thập, chuẩn hoá và lưu trữ dữ liệu chỉ số ô nhiễm không khí (AQI) và thông tin thời tiết theo quận/huyện tại TP. Hồ Chí Minh.
Dữ liệu thời gian thực được lấy từ OpenAQ API v3 và lưu vào MongoDB để phân tích, trực quan hoá và dự đoán.

Hệ thống cho phép:

• Hiển thị dashboard trực quan (biểu đồ, bản đồ, heatmap)
• Truy vấn dữ liệu theo thời gian và khu vực
• Phân tích xu hướng chất lượng không khí
• Dự đoán AQI ngắn hạn (24 giờ) bằng mô hình ML

• Backend: Node.js + Express
• Database: MongoDB + Mongoose
• Views: Pug (client & admin)
• Frontend libs: Bootstrap 5, Leaflet.js, Chart.js
• Scheduler: node-cron (thu thập OpenAQ theo giờ)
• ML: Python (NumPy, Pandas, scikit-learn, PyTorch) gọi qua Node

Tham chiếu mã nguồn:

• Cấu hình DB: config/database.js
• Mô hình dữ liệu AQI: models/index.js, các model quận như models/district1.model.js, models/hcmc.model.js
• Dữ liệu theo giờ OpenAQ: models/hcmcAirHour.model.js, models/hcmcAirindex.model.js
• Thu thập OpenAQ: scripts/fetch-openaq-hours.js
• Đồng bộ AQI sang các quận: services/aqiSyncService.js, scripts/sync-openaq-to-districts.js
• API AQI client: controllers/client/aqi.controller.js
• API Dự đoán: controllers/api/prediction.controller.js, Python runner helpers/pythonRunner.js, script ML predict_from_json.py
• Giao diện: Client views/client/pages/home/index.pug, Docs views/client/pages/docs/index.pug, Admin AQI views/admin/pages/aqi/index.pug, Admin Weather views/admin/pages/weather/index.pug

Lưu ý: Mọi tham chiếu AirVisual đã bị loại bỏ. Script cũ scripts/fetch-and-save.js không còn được khuyến nghị sử dụng.

• Lấy dữ liệu cảm biến theo giờ của TP.HCM từ OpenAQ
• Lưu raw giờ vào collection HCMCAirHour
• Map và chuẩn hoá AQI cho từng quận

Script:

• Thu thập: scripts/fetch-openaq-hours.js
• Chuyển đổi/quy đổi AQI: services/aqiSyncService.js
• Kiểm tra dữ liệu mới nhất: scripts/check-latest-openaq.js

• Schema chuẩn: current.pollution (AQI US, mainus) và current.weather (tp, hu, pr, ws, wd)
• Model mỗi quận: ví dụ models/district3.model.js
• Thành phố: models/hcmc.model.js

• Client:
  • Trang chủ: views/client/pages/home/index.pug
  • API docs: views/client/pages/docs/index.pug
  • JS bản đồ/heatmap: public/client/js/script.js
• Admin:
  • AQI: views/admin/pages/aqi/index.pug
  • Weather: views/admin/pages/weather/index.pug

• LSTM parameters (JSON) trong model_params/
• Dự đoán qua Python: predict_from_json.py
• Gọi từ Node: controllers/api/prediction.controller.js, helpers/pythonRunner.js
• UI dự báo: public/client/js/forecast.js

• AQI Client Endpoints: xem controllers/client/aqi.controller.js
• Prediction Endpoints: xem controllers/api/prediction.controller.js
• API Docs giao diện: views/client/pages/docs/index.pug

• Node.js >= 16.x, npm/yarn
• MongoDB (local/Atlas)
• Python 3.9+ nếu dùng dự đoán
• Git

Biến môi trường (.env) mẫu:

PORT=3000
MONGODB_URL=<your-mongodb-url>

# OpenAQ API
OPENAQ_API_BASE=https://api.openaq.org/v3
OPENAQ_API_KEY=<your-openaq-api-key>
OPENAQ_FETCH_INTERVAL=0 * * * *
SYNC_INTERVAL_MINUTES=30

# Session
SESSION_SECRET=<your-secret>

# SMTP Email
EMAIL_USER=<your-email>
EMAIL_PASS=<your-app-password>

git clone https://github.com/<your-username>/Eco-Track.git
cd Eco-Track
npm install

npm run dev
# hoặc
npm start

Mặc định: http://localhost:3000

• Cập nhật MONGODB_URL trong .env
• Kết nối tại config/database.js

node scripts/fetch-openaq-hours.js

node scripts/seed-72h-data.js

• config/ – Cấu hình hệ thống
• controllers/ – Logic client, admin, api
• models/ – Schema Mongoose (AQI, thời tiết, giờ, index)
• routers/ – Định tuyến
• views/ – Giao diện Pug
• public/ – Tài nguyên tĩnh
• scripts/ – Cron, seed, tiện ích
• helpers/ – Python runner, kiểm tra deps

• Hướng dẫn chi tiết: xem RELEASE_GUIDE.md
• Lịch sử thay đổi: xem CHANGELOG.md
• Quick steps phát hành:
  1. Tăng version trong package.json và cập nhật CHANGELOG.md
  2. Commit: chore: release vX.Y.Z
  3. Tạo tag và đẩy lên Git:

     git tag vX.Y.Z
     git push origin vX.Y.Z

  4. Tạo GitHub Release, đính kèm nội dung từ CHANGELOG.md

git checkout -b feat/<ten-tinh-nang>
git commit -m "feat: <mo-ta-ngan-gon>"
git push -u origin feat/<ten-tinh-nang>

• Tạo issue: https://github.com//Eco-Track/issues

Phân phối theo GNU GPL v3.0. Xem LICENSE.

© 2025 Eco-Track – Cùng xây dựng bầu không khí trong lành cho TP. Hồ Chí Minh 🌿