UP README.md by Sazwanismail · Pull Request #232 · Visual-Studio-Code/.github
Saya akan kemas kini **README.md** untuk projek Fairbase agar merangkumi semua komponen terkini, termasuk skrip pemasangan .NET, dokumentasi `rare-hounds-behave.md`, konfigurasi `devcontainer.json`, serta integrasi penuh dengan BigQuery, MongoDB, React, Node.js, dan GitHub Actions. ```markdown # Fairbase **Fairbase** ialah platform data digital dan cryptocurrency yang menggabungkan analisis data berskala besar dengan BigQuery, storan fleksibel dengan MongoDB, dan antara muka pengguna moden dengan React. Projek ini dibangunkan untuk memudahkan pengurusan aset digital dan data coin dengan automasi penuh melalui GitHub Actions. Ia juga dilengkapi dengan persekitaran pembangunan konsisten menggunakan Development Container dan dokumentasi teknikal untuk menangani situasi luar biasa. --- ## 🧰 Teknologi Utama | **Bahagian** | **Teknologi** | |----------------|---------------------------------------------------------------------------------------------------| | Frontend | React, HTML, CSS, JavaScript | | Backend | Node.js, Express | | Database | BigQuery (Google Cloud), MongoDB (Atlas/Self-hosted) | | DevOps | GitHub Actions, Git, GitHub Pages (dokumentasi) | | Pembangunan | Development Container (VS Code / GitHub Codespaces) | | Lain-lain | Python (skrip ETL), Bash/PowerShell (pemasangan .NET, utiliti) | --- ## 📁 Struktur Direktori (Kemas Kini) ``` Fairbase/ ├── .github/ │ └── workflows/ # GitHub Actions CI/CD pipelines │ ├── deploy-all.yml # Build dan deploy frontend/backend │ └── data-pipeline.yml # Kemas kini data berkala ke BigQuery & MongoDB ├── .devcontainer/ │ └── devcontainer.json # Konfigurasi Development Container ├── BigQuery&DataCoin/ # Skrip berkaitan BigQuery │ ├── setup_bigquery.py │ └── load_to_bigquery.py ├── Data&Digital/ # Data mentah dan terproses │ ├── raw_data/ # Data CSV/JSON asal │ └── processed/ # Data selepas pemprosesan ├── Python All Language/ # Skrip Python pelbagai guna │ ├── setup_mongodb.py │ └── load_to_mongodb.py ├── backend/ # Node.js/Express backend │ ├── routes/ │ │ ├── bigquery.js │ │ └── mongodb.js │ ├── models/ │ │ └── DigitalAsset.js │ ├── server.js │ └── package.json ├── codespaces-react/ # React frontend │ ├── public/ │ ├── src/ │ │ ├── components/ │ │ ├── services/ │ │ └── App.js │ └── package.json ├── scripts/ # Skrip pembantu (pemasangan, utiliti) │ ├── dotnet-install.sh # Pemasangan .NET (Linux/macOS) │ └── dotnet-install.ps1 # Pemasangan .NET (Windows) ├── docs/ # Dokumentasi tambahan │ └── rare-hounds-behave.md # Dokumentasi tingkah laku jarang berlaku ├── .gitignore ├── LICENSE # Lesen MIT └── README.md # Fail ini ``` --- ## ⚙️ Keperluan Sistem - **Node.js** 18 atau lebih baru - **Python** 3.10 atau lebih baru - **Git** - **Docker** (jika menggunakan devcontainer) - **Akaun Google Cloud** (dengan BigQuery API diaktifkan) - **Akaun MongoDB Atlas** (pilihan, jika menggunakan cloud) - **.NET SDK 9.0** (jika ingin menjalankan komponen .NET; boleh dipasang menggunakan skrip dalam `scripts/`) --- ## 🚀 Panduan Persediaan ### 1. Klon Repositori ```bash git clone https://github.com/Sazwanismail/Fairbase.git cd Fairbase ``` ### 2. Persediaan Backend ```bash cd backend npm install cp .env.example .env # Isi pemboleh ubah persekitaran (lihat di bawah) ``` **Pemboleh Ubah Persekitaran (`.env`)**: ``` GOOGLE_PROJECT_ID=sazwan-fairbase GOOGLE_APPLICATION_CREDENTIALS=./path/to/service-account.json MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/fairbase PORT=5000 ``` ### 3. Persediaan Frontend ```bash cd ../codespaces-react npm install cp .env.example .env ``` **Pemboleh Ubah Persekitaran Frontend**: ``` REACT_APP_API_URL=http://localhost:5000 ``` ### 4. Persediaan Database #### BigQuery - Pastikan projek Google Cloud anda aktif dan API BigQuery diaktifkan. - Muat naik kredential akaun perkhidmatan ke fail yang dirujuk dalam `GOOGLE_APPLICATION_CREDENTIALS`. - Jalankan skrip setup: ```bash cd BigQuery&DataCoin pip install -r requirements.txt # Anda perlu buat requirements.txt python setup_bigquery.py ``` #### MongoDB - Sediakan kluster MongoDB (Atlas atau lokal). - Dapatkan connection string dan masukkan ke `MONGODB_URI`. - Jalankan skrip setup: ```bash cd "../Python All Language" pip install pymongo python setup_mongodb.py ``` ### 5. Menjalankan Aplikasi Secara Lokal **Terminal 1 – Backend**: ```bash cd backend npm start # Server akan berjalan di http://localhost:5000 ``` **Terminal 2 – Frontend**: ```bash cd codespaces-react npm start # Aplikasi akan dibuka di http://localhost:3000 ``` ### 6. Mengisi Data Contoh (Pilihan) Jika anda ingin mengisi data contoh ke dalam BigQuery dan MongoDB, jalankan: ```bash python BigQuery&DataCoin/load_to_bigquery.py python "Python All Language/load_to_mongodb.py" ``` ### 7. Pemasangan .NET (Jika Diperlukan) Projek ini menyediakan skrip untuk memasang .NET SDK versi 9.0 (atau terkini) di pelbagai platform: - **Linux/macOS**: ```bash chmod +x scripts/dotnet-install.sh ./scripts/dotnet-install.sh ``` - **Windows (PowerShell)**: ```powershell .\scripts\dotnet-install.ps1 ``` --- ## 🤖 GitHub Actions Projek ini menggunakan GitHub Actions untuk automasi: - **Deploy All Components** (`.github/workflows/deploy-all.yml`): Diaktifkan setiap kali push ke `main`. Membina frontend dan backend, kemudian deploy ke Firebase Hosting dan Cloud Run (jika dikonfigurasi). - **Data Pipeline** (`.github/workflows/data-pipeline.yml`): Dijadualkan setiap hari jam 2 pagi untuk mengemas kini data di BigQuery dan MongoDB. Untuk melihat status workflow, pergi ke tab **Actions** repositori GitHub anda. --- ## 📊 Penggunaan API Backend menyediakan endpoint berikut: | **Endpoint** | **Kaedah** | **Penerangan** | |----------------------------------|------------|------------------------------------------| | `/api/health` | GET | Memeriksa kesihatan server | | `/api/bigquery/data-coin` | GET | Mendapat data coin dari BigQuery | | `/api/bigquery/digital-assets` | GET | Mendapat aset digital dari BigQuery | | `/api/mongodb/assets` | GET | Mendapat aset digital dari MongoDB | | `/api/mongodb/assets` | POST | Menambah aset digital baru ke MongoDB | Contoh respons: ```json [ { "coin_id": "bitcoin", "coin_name": "Bitcoin", "price_usd": 50000.00, "volume_24h": 1000000, "market_cap": 1000000000, "timestamp": "2025-01-01T00:00:00Z" } ] ``` --- ## 🧪 Pembangunan dengan Dev Container Projek ini menyertakan konfigurasi **Development Container** (`.devcontainer/devcontainer.json`). Ia membolehkan anda menggunakan persekitaran pembangunan yang konsisten dalam VS Code atau GitHub Codespaces. 1. Pasang **Docker** dan **Remote - Containers** extension dalam VS Code. 2. Buka projek, kemudian `Ctrl+Shift+P` → **"Remote-Containers: Reopen in Container"**. 3. Tunggu sehingga container siap, dan anda boleh mula membangun tanpa perlu memasang dependensi secara manual. Container ini dilengkapi dengan Node.js 18, Python 3, Git, dan pelbagai extension VS Code yang berguna (ESLint, Prettier, React snippets, dll.). --- ## 📚 Dokumentasi Tambahan: Rare Hounds Behave Fail [`docs/rare-hounds-behave.md`](docs/rare-hounds-behave.md) mengandungi dokumentasi tentang tingkah laku jarang berlaku (*rare hounds*) yang mungkin timbul dalam sistem, seperti data pendua, kegagalan sambungan MongoDB secara rawak, atau workflow GitHub Actions yang ganjil. Ia bertujuan membantu pasukan menyelesaikan masalah luar biasa dengan cepat. Sila rujuk fail tersebut jika anda menghadapi situasi yang tidak dijangka. --- ## 🤝 Cara Menyumbang Kami mengalu-alukan sumbangan daripada komuniti! Sila ikuti langkah berikut: 1. Fork repositori ini. 2. Buat branch baru (`git checkout -b fitur-anda`). 3. Lakukan perubahan dan commit (`git commit -m 'Tambah fitur X'`). 4. Push ke branch (`git push origin fitur-anda`). 5. Buka Pull Request. Pastikan anda mengikuti panduan gaya kod dan menulis ujian jika perlu. --- ## 📄 Lesen Projek ini dilindungi di bawah **Lesen MIT**. Sila lihat fail [LICENSE](LICENSE) untuk maklumat lanjut. --- ## 📞 Hubungi - **Pengarang**: Sazwanismail - **GitHub**: [@Sazwanismail](https://github.com/Sazwanismail) - **Laman Projek**: [https://sazwan-fairbase.web.app](https://sazwan-fairbase.web.app) (jika sudah di-deploy) --- *Terima kasih kerana menggunakan Fairbase! Versi terkini: 2026* ``` **Nota**: README ini sudah mencerminkan semua penambahan terkini. Jika ada sebarang perubahan lanjut (contoh: URL deployment sebenar, maklumat pasukan, dll.), sila ubah suai mengikut keperluan.