Nhảy tới nội dung

🚀 Hướng dẫn Bắt đầu CivicTwin AI

"Từ lý thuyết sang thực hành — Triển khai CivicTwin AI ngay hôm nay"

📋 Yêu cầu Hệ thống​

Cài đặt Sơ bộ​

  • Node.js: v16+
  • npm hoặc yarn: v7+
  • PostgreSQL: v12+
  • PostGIS: v3.0+ (extension cho PostgreSQL)
  • Docker (tùy chọn, nhưng khuyến nghị)

Môi trường​

  • OS: Linux, macOS, hoặc Windows (WSL2)
  • RAM: Tối thiểu 8GB
  • Disk: 20GB (để chứa dữ liệu, model)

🔧 Cài đặt Nhanh (5 phút)​

Bước 1: Clone Repository​

git clone https://github.com/asean-ai/civic-twin.git
cd civic-twin

Bước 2: Cài đặt Dependencies​

npm install
# hoặc
yarn install

Bước 3: Cấu hình Môi trường​

Tạo file .env trong thư mục gốc:

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/civic_twin
POSTGIS_ENABLED=true

# AI Core
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=your_key
AWS_SECRET_ACCESS_KEY=your_secret

# API
PORT=3000
NODE_ENV=development

# Maps
MAPBOX_TOKEN=your_mapbox_token

Bước 4: Khởi tạo Database​

npm run migrate
npm run seed  # (nếu cần dữ liệu mẫu)

Bước 5: Chạy Ứng dụng​

npm start

Ứng dụng sẽ chạy tại http://localhost:3000

🐳 Cài đặt với Docker (Khuyến nghị)​

Bước 1: Xây dựng Docker Image​

docker-compose build

Bước 2: Chạy Container​

docker-compose up -d

Bước 3: Kiểm tra Trạng thái​

docker-compose ps

Tất cả dịch vụ sẽ chạy:

📊 Cấu trúc Dự án​

civic-twin/
├── src/
│   ├── services/           # Các microservice
│   │   ├── DigitalTwin/   # Digital Twin engine
│   │   ├── Prediction/    # AI prediction
│   │   ├── Simulation/    # What-If scenario
│   │   └── Dashboard/     # Decision support
│   ├── pages/              # Frontend pages
│   ├── css/                # Styling
│   └── api/                # API routes
├── docs/                   # Tài liệu
├── docker-compose.yml      # Docker configuration
├── package.json
└── README.md

✅ Kiểm tra Cài đặt​

1. Kiểm tra API​

curl http://localhost:3000/api/health
# Kết quả: {"status": "ok", "timestamp": "2026-03-31T..."}

2. Truy cập Frontend​

Mở trình duyệt: http://localhost:5173

3. Tạo Dự án Test​

  1. Đăng nhập với tài khoản demo
  2. Chọn "Tạo Kịch bản Mới"
  3. Vẽ một con đường trên bản đồ
  4. Xem kết quả dự báo

🚨 Khắc phục Sự cố​

Lỗi: "Connection refused" (PostgreSQL)​

# Kiểm tra PostgreSQL đang chạy
sudo service postgresql status

# Hoặc nếu dùng Docker
docker-compose ps postgres

Lỗi: "Port 3000 đã được sử dụng"​

# Tìm process sử dụng port 3000
lsof -i :3000

# Hoặc chỉ định port khác
PORT=3001 npm start

Lỗi: "AWS credentials not found"​

Kiểm tra file .env có chứa AWS_ACCESS_KEY_ID và AWS_SECRET_ACCESS_KEY không. Hoặc cấu hình AWS CLI:

aws configure

📚 Bước Tiếp theo​

💡 Mẹo Phát triển​

Hot Reload Frontend​

npm run dev  # Tự động reload khi code thay đổi

Debug Backend​

DEBUG=* npm start  # Xem log chi tiết

Reset Database​

npm run migrate:reset
npm run seed

🆘 Cần Giúp Đỡ?​

📞 Liên hệ & Hỗ trợ​

📄 Giấy phép​

Dự án này được phân phối dưới GNU General Public License v3.0. Xem file LICENSE để biết thêm chi tiết.

© 2025 CivicTwin AI – Được phát triển với ❤️ bởi Nhóm ASEAN-AI-DZ