System Draft: Core API System

NOTE

Đây là trang nháp tài liệu kỹ thuật dành cho backend API để kiểm tra khả năng hiển thị của VitePress.

---

1. Subsystem Introduction

Phân hệ hanoi-core đóng vai trò là xương sống (backbone) cho toàn bộ hệ thống Hanoi Smart City Connect. Nó chịu trách nhiệm giao tiếp cơ sở dữ liệu, quản lý xác thực và cung cấp API cho ứng dụng frontend client.

---

2. API Endpoints (Draft)

Dưới đây là một số API mẫu phục vụ tra cứu thông tin xe buýt và gửi phản ánh đô thị:

2.1. Lấy danh sách tuyến xe buýt

• Endpoint: /api/v1/bus/routes
• Method: GET
• Query Parameters:
  • query (optional): Tìm kiếm tên tuyến hoặc mã tuyến (ví dụ: 09A).
• Response Mẫu (200 OK):

  [
    {
      "id": "route-09a",
      "code": "09A",
      "name": "Bờ Hồ - Cầu Giấy - Bến xe Mỹ Đình",
      "status": "active",
      "frequency": "10-15 phút/chuyến"
    }
  ]

2.2. Gửi phản ánh hạ tầng đô thị

• Endpoint: /api/v1/reports
• Method: POST
• Headers: Content-Type: multipart/form-data
• Body:
  • title: Tiêu đề phản ánh.
  • description: Chi tiết phản ánh.
  • latitude, longitude: Tọa độ nơi xảy ra sự cố.
  • image: File ảnh đính kèm.
• Response Mẫu (201 Created):

  {
    "id": "report-9982",
    "status": "pending",
    "created_at": "2026-07-13T12:00:00Z",
    "message": "Phản ánh đã được ghi nhận thành công và chuyển giao cho bộ phận xử lý."
  }

---

3. Environment Variables Configuration (.env)

Để khởi chạy backend cục bộ, bạn cần chuẩn bị file .env với các cấu hình tối thiểu sau:

PORT=3000
DATABASE_URL=postgresql://db_user:db_password@localhost:5432/hanoi_smartcity
MQTT_BROKER_URL=mqtt://localhost:1883
JWT_SECRET=super_secret_key_hackathon_2026