From 050f118a4126e236058460af0c50756b46cd81a5 Mon Sep 17 00:00:00 2001 From: Muhamad Sazwan Bin Ismail Date: Mon, 16 Mar 2026 17:00:46 +0800 Subject: [PATCH] Update README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- README.md | 240 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 239 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index a46ae92d..58e51283 100644 --- a/README.md +++ b/README.md @@ -1 +1,239 @@ -# .github \ No newline at end of file +# .github +Saya akan hasilkan **README.md** yang lengkap dan profesional untuk projek **Fairbase** oleh **Sazwanismail**. README ini akan merangkumi semua komponen yang telah dibincangkan: BigQuery, MongoDB, React, Node.js, GitHub Actions, dan lain-lain. + +```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. + +--- + +## ๐Ÿงฐ 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) | +| Lain-lain | Python (skrip ETL), Bash/PowerShell (pemasangan .NET) | + +--- + +## ๐Ÿ“ Struktur Direktori + +``` +Fairbase/ +โ”œโ”€โ”€ .github/ +โ”‚ โ””โ”€โ”€ workflows/ # GitHub Actions CI/CD pipelines +โ”‚ โ”œโ”€โ”€ deploy-all.yml +โ”‚ โ””โ”€โ”€ data-pipeline.yml +โ”œโ”€โ”€ BigQuery&DataCoin/ # Skrip berkaitan BigQuery +โ”‚ โ”œโ”€โ”€ setup_bigquery.py +โ”‚ โ””โ”€โ”€ load_to_bigquery.py +โ”œโ”€โ”€ Data&Digital/ # Data mentah dan terproses +โ”‚ โ”œโ”€โ”€ raw_data/ +โ”‚ โ””โ”€โ”€ processed/ +โ”œโ”€โ”€ Python All Language/ # Skrip Python pelbagai guna +โ”‚ โ”œโ”€โ”€ setup_mongodb.py +โ”‚ โ””โ”€โ”€ load_to_mongodb.py +โ”œโ”€โ”€ backend/ # Node.js/Express backend +โ”‚ โ”œโ”€โ”€ routes/ +โ”‚ โ”œโ”€โ”€ models/ +โ”‚ โ”œโ”€โ”€ server.js +โ”‚ โ””โ”€โ”€ package.json +โ”œโ”€โ”€ codespaces-react/ # React frontend +โ”‚ โ”œโ”€โ”€ public/ +โ”‚ โ”œโ”€โ”€ src/ +โ”‚ โ””โ”€โ”€ package.json +โ”œโ”€โ”€ scripts/ # Skrip pembantu (pemasangan, dll.) +โ”‚ โ”œโ”€โ”€ dotnet-install.sh +โ”‚ โ””โ”€โ”€ dotnet-install.ps1 +โ”œโ”€โ”€ docs/ # Dokumentasi tambahan +โ”‚ โ””โ”€โ”€ rare-hounds-behave.md +โ”œโ”€โ”€ .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) + +--- + +## ๐Ÿš€ 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" +``` + +--- + +## ๐Ÿค– 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. + +--- + +## ๐Ÿค 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!* +``` + +**Nota**: Fail README ini anda boleh terus letak di root repositori Fairbase. Jika ada sebarang perubahan atau tambahan yang dikehendaki, sila beritahu.