docs: add READMD.md

README.md

@@ -0,0 +1,35 @@
+# GeoPulse: Kafka 高併發資料寫入練習
+
+這是一個用於練習「高併發串流資料處理」與「非同步解耦」的實驗專案。
+
+專案的出發點是為了解決傳統 API 直連 PostgreSQL 時，面對瞬間大量設備回傳 GPS 座標（例如 5萬筆暴雨式請求）所產生的 I/O 瓶頸與阻塞問題。透過導入 Kafka 作為中介層，驗證系統吞吐量與穩定性的提升。
+
+## 系統架構與資料流
+
+本專案將寫入流程拆分為「接收 (Producer)」與「消化 (Consumer)」兩個獨立階段：
+
+1. **資料接收 (Minimal API + Kafka Producer)**
+   - 捨棄 API 端的資料庫連線。
+   - API 收到 JSON payload 後，僅作基本驗證，隨即將資料推入 Kafka 的 `telemetry-events` 主題中。
+   - **成果**：API 卸下資料庫 I/O 重擔，壓測下吞吐量可達 5000+ RPS。
+
+2. **背景消化 (BackgroundService + Kafka Consumer)**
+   - 在 API 專案中掛載 Hosted Service 作為背景消費者。
+   - 採用**微批次機制 (Micro-batching)**：設定 `BatchSize = 1000` 與 `MaxWaitTime = 2s` 雙重發車條件。
+   - 收集滿一定數量的資料後，使用 Npgsql 的 `DbBatch` 一次性打包 `INSERT` 指令寫入 PostgreSQL。
+
+3. **資料儲存 (PostgreSQL + PostGIS)**
+   - 結合 PostGIS 處理 `ST_MakePoint` 空間幾何資料轉換。
+   - 實作**日期分區表 (Table Partitioning)**，優化時序型軌跡資料的後續查詢與維護效能。
+
+## 執行環境
+
+* **語言與框架**: C# (.NET 8), Web API.
+* **中介軟體**: Apache Kafka (KRaft), Confluent.Kafka 
+* **壓力測試軟體**: ApacheBench
+* **資料庫**: PostgreSQL, PostGIS, Npgsql
+* **部署**: Docker Compose
+
+## 優化結果
+
+透過導入 Kafka 緩衝層，系統在處理 600 併發的暴雨式請求時，表現出驚人的穩定性。與直連資料庫相比，吞吐量從 400 RPS 提升至 8,000 RPS ，大幅降低了後端寫入壓力對前端響應速度的影響。