BKK Transit — Bangkok Open Transit Platform

แพลตฟอร์มข้อมูลขนส่งสาธารณะและระบบวางแผนการเดินทาง กรุงเทพฯ และปริมณฑล
Open Transit Data Platform, Routing Engine, and Real-Time Tracking for the Bangkok Metropolitan Region

คุณสมบัติเด่น • ภาพตัวอย่างหน้าจอ • เริ่มต้นใช้งานใน 3 นาที • ระบบ GPS และแผนที่ • การรับมือเหตุฉุกเฉิน / API ดับ • สถาปัตยกรรม • API Reference • เอกสารประกอบ

📸 ภาพตัวอย่างหน้าจอ (Screenshots Showcase)

Related MCP server: TFL MCP Server for Poke

📌 บทนำและที่มาของโครงการ (Why BKK Transit?)

ข้อเท็จจริงในปัจจุบัน:
ระบบขนส่งสาธารณะของกรุงเทพฯ มีความซับซ้อนสูง ประกอบด้วยรถเมล์ (ขสมก. และรถร่วมเอกชน เช่น Thai Smile Bus), รถไฟฟ้าหลากสี (BTS, MRT, ARL, SRTET), เรือด่วนเจ้าพระยา และเรือคลองแสนแสบ ทว่ายังไม่มี Public API ทางการที่เปิดเผยข้อมูลตำแหน่งรถแบบ Real-time สาธารณะ ข้อมูลส่วนใหญ่กระจายตัวอยู่ในแอปพลิเคชันเอกชนหรือระบบปิดภายใน

สิ่งที่มีและใช้งานได้ถูกต้องตามกฎหมาย:
สำนักงานนโยบายและแผนการขนส่งและจราจร (สนข.) กระทรวงคมนาคม ได้เผยแพร่ชุดข้อมูล GTFS Static ของกรุงเทพฯ และปริมณฑล (สายรถเมล์, เรือ, รถไฟฟ้า, สถานี/ป้าย, เส้นทาง shape, ตารางความถี่) ภายใต้สัญญาอนุญาตเปิด Creative Commons CC-BY 4.0 ผ่านระบบ "นำทาง (Namtang)"

พันธกิจของโครงการ:
BKK Transit ถูกสร้างขึ้นเพื่อเป็นโครงสร้างพื้นฐานข้อมูลเปิด (Open Transit Infrastructure) ระดับมืออาชีพ:

1. นำเข้าข้อมูล GTFS Static มาตรฐานสากลเข้าสู่ฐานข้อมูลประสิทธิภาพสูง (SQLite สำหรับพัฒนา / PostGIS สำหรับ Production)

2. ให้บริการผ่าน REST API มาตรฐาน พร้อมเอกสาร Interactive Swagger/OpenAPI

3. มีหน้าจอแผนที่ Interactive Web Map (Leaflet.js) รองรับ GPS ระบุตำแหน่งตนเอง แบบเรดาร์ ค้นหาป้ายรอบตัว และวางแผนการเดินทาง

4. ออกแบบเลเยอร์ Real-time เป็นสถาปัตยกรรมแบบ Pluggable เพื่อรองรับการ "เสียบ" GTFS-RT ของจริงได้ทันทีเมื่อเจรจาข้อมูลกับหน่วยงานสำเร็จ โดยไม่ต้องรื้อระบบ

5. มี ความทนทานต่อความล้มเหลว (Fault Tolerance & Resilience) สูงสุด หาก API ภายนอกหรือระบบ Realtime ขัดข้อง ระบบจะตัดวงจรและทำงานต่อด้วยข้อมูลแคช/ตารางเดินรถได้ทันที 100%

✨ คุณสมบัติเด่น (Features)

🚀 เริ่มต้นใช้งานใน 3 นาที (Quick Start)

วิธีที่ 1: โหมดพัฒนาเบาพิเศษ (Zero-Dependency Dev Server)

ใช้เพียง Python มาตรฐาน (stdlib) ไม่ต้องติดตั้งไลบรารีภายนอก:

# 1. โคลนคลังโค้ด
git clone https://github.com/your-org/bkk-transit.git
cd bkk-transit

# 2. นำเข้าข้อมูลตัวอย่าง GTFS เข้า SQLite (data/transit.db)
python -m app.gtfs_loader --path data/gtfs_sample --report reports/gtfs_report.json
# หรือใช้ make sample

# 3. สตาร์ท Dev Server
python -m app.devserver --port 8000
# หรือใช้ make dev

# 4. เปิดเบราว์เซอร์: http://localhost:8000

วิธีที่ 2: โหมด FastAPI + Uvicorn (พร้อม Interactive Swagger Docs)

เหมาะสำหรับการพัฒนา API และทดสอบ Endpoint:

# 1. สร้าง Virtual Environment
python -m venv .venv
source .venv/bin/activate  # บน Windows: .venv\Scripts\activate

# 2. ติดตั้ง Dependencies
pip install -r requirements.txt

# 3. รันเซิร์ฟเวอร์แบบ Hot-Reload
python -m uvicorn app.api.main:app --reload --port 8000
# หรือใช้ make api

# เข้าใช้งาน:
# - หน้าเว็บแผนที่: http://localhost:8000
# - API Swagger Docs: http://localhost:8000/docs
# - API Redoc: http://localhost:8000/redoc

วิธีที่ 3: โหมด Production ด้วย Docker Compose + PostGIS

เหมาะสำหรับ Production ที่ต้องการดาวน์โหลดข้อมูล GTFS ฉบับเต็มจาก สนข. และเปิดใช้ Spatial Database:

cp .env.example .env     # ปรับตั้งค่ารหัสผ่านฐานข้อมูลใน .env
docker compose up -d db  # สตาร์ท PostgreSQL + PostGIS
docker compose run --rm loader  # ดาวน์โหลด GTFS ฉบับเต็มจาก สนข. และโหลดเข้า DB
docker compose up -d api # สตาร์ท FastAPI Service

📍 ระบบ GPS และแผนที่ระบุพิกัด (GPS & Geolocation)

ระบบมีฟังก์ชันระบุตำแหน่งผู้ใช้บนแผนที่อย่างสมบูรณ์แบบ:

1. ปุ่มค้นหาตำแหน่งลอย (Floating GPS Control): ไอคอนเป้าเล็ง 🎯 อยู่มุมขวาบนของแผนที่ สามารถกดเรียกพิกัดได้ตลอดเวลา

2. หมุดระบุตำแหน่งเรดาร์ (Pulsing Location Pin): เมื่อได้พิกัด แผนที่จะแสดงจุดวงกลมสีน้ำเงินพร้อมแอนิเมชันคลื่นเรดาร์ขยายตัว (Wave Ripple Effect)

3. วงแหวนความแม่นยำ (Accuracy Radius): วาดวงกลมรัศมีความคลาดเคลื่อนจริงตามที่ดาวเทียม GPS รายงาน

4. ค้นหาป้ายรอบตัวอัตโนมัติ (Auto-Discovery): ซูมแผนที่เข้าสู่ตำแหน่งปัจจุบัน (map.flyTo) และค้นหาป้าย/สถานีรถไฟฟ้า/ท่าเรือในรัศมี 500 เมตร พร้อมคำนวณระยะเดินให้ทันที

5. ความปลอดภัยและข้อกำหนด (HTTPS Requirement):
   ตามมาตรฐาน W3C Geolocation API เบราว์เซอร์จะอนุญาตให้ใช้งาน GPS ได้เฉพาะบน HTTPS หรือ http://localhost เท่านั้น หากรันบน IP ภายนอกต้องติดตั้ง Reverse Proxy SSL เสมอ
   (อ่านคู่มือการตั้งค่าและการแก้ปัญหาโดยละเอียดได้ที่ docs/GPS_GEOLOCATION_GUIDE.md)

🛡️ การรับมือเหตุฉุกเฉิน และการป้องกันเมื่อ API โดนตัด (Resilience & Disaster Recovery)

โครงการนี้ถูกออกแบบโดยคำนึงถึงปัญหาความเสถียรของแหล่งข้อมูลภายนอก (Upstream Outage) และสถานการณ์ฉุกเฉินในระบบ Production อย่างรัดกุม:

1. ถ้า API หรือ Feed ของ สนข. / ขสมก. โดนตัดหรือหยุดให้บริการ เราจะรู้ได้อย่างไร และป้องกันอย่างไร?

• การตรวจจับล่วงหน้า (Proactive Synthetic Monitoring): มีสคริปต์ตรวจเช็คความพร้อมของ Feed ต้นทางเป็นระยะ (HTTP HEAD, ETag, Content-Length) และตรวจสอบวันหมดอายุของข้อมูล (feed_end_date) ล่วงหน้า 30 วัน พร้อมส่งแจ้งเตือนผ่าน Discord / LINE / Slack Webhook

• สถาปัตยกรรมตัดขาด Upstream (Ingestion Architecture): เซิร์ฟเวอร์ ไม่ได้เรียก API ไปยัง สนข. สดๆ ทุก Request แต่ใช้วิธี Ingestion เข้าฐานข้อมูล Local Snapshot (PostGIS/SQLite) ไว้ล่วงหน้า ดังนั้น แม้เว็บ สนข. จะล่ม ระบบ BKK Transit ก็ยังให้บริการได้ 100%

• Circuit Breaker สำหรับ Realtime Feed: หาก Feed ตำแหน่งรถ (GTFS-RT) ล่มหรือ Timeout ติดต่อกันเกิน 3 ครั้ง วงจรจะตัดทันทีเพื่อป้องกันเซิร์ฟเวอร์ค้าง และสลับไปใช้ ตารางเดินรถปกติ (Schedule Fallback) พร้อมติดป้ายแจ้งสถานะให้ผู้ใช้ทราบอย่างโปร่งใส

2. ถ้าเซิร์ฟเวอร์หรือฐานข้อมูล Crash จะรับมืออย่างไร?

• Docker Auto-Recovery: กำหนด restart: unless-stopped และมี Docker Healthcheck Probe คอยตรวจจับสถานะ

• SQLite WAL Mode: เปิดใช้งาน Write-Ahead Logging เพื่อรองรับการอ่านข้อมูลพร้อมกันได้ไม่จำกัด โดยไม่เกิดปัญหา Database Lock

• PostgreSQL Connection Pool: ควบคุม Connection ผ่าน psycopg 3 และป้องกัน Memory Leak ด้วยการสตรีมข้อมูล

• RTO < 3 นาที: สามารถสร้างฐานข้อมูลใหม่จากไฟล์ตัวอย่างหรือ Snapshot สำรองได้ภายในไม่กี่นาที

(อ่านรายละเอียดขั้นตอนปฏิบัติการฉุกเฉินและ Runbook ทั้งหมดได้ที่ docs/OPERATIONS_AND_RESILIENCE.md)

🤖 การเชื่อมต่อกับ AI และ Model Context Protocol (MCP)

ในยุคปัจจุบัน ผู้ใช้งานส่วนใหญ่นิยมพิมพ์สอบถามเส้นทางรถเมล์และการเดินทางผ่าน AI เช่น ChatGPT, Gemini, หรือ Claude ทว่าโมเดลภาษาทั่วไปมัก ตอบข้อมูลเก่าก่อนปฏิรูปสาย หรือมโน (Hallucinate) ลำดับป้ายจอด

BKK Transit จึงถูกออกแบบให้เป็น ฐานข้อมูลความจริง (Ground-Truth Knowledge Base) สำหรับ AI:

1. รองรับ Model Context Protocol (MCP):
   มีเซิร์ฟเวอร์ MCP ในตัว (app/mcp_server.py) ที่รองรับ Claude Desktop, Cursor IDE, Antigravity และ AI Agents ทุกค่าย โดยมี Tools ให้ AI เรียกใช้งาน:

   • search_transit_routes — ค้นหาสายรถเมล์ เรือ รถไฟฟ้า

   • get_route_details — ดึงลำดับป้ายและทิศทางเดินรถที่ถูกต้อง 100%

   • search_stops — ค้นหาป้ายรถเมล์หรือสถานี BTS/MRT

   • find_nearby_stops — ค้นหาป้ายรอบพิกัด GPS

   • get_next_departures — ตรวจสอบเวลารถออกถัดไปและความถี่

   • plan_transit_journey — วางแผนการเดินทางระหว่างป้าย

2. สร้าง Custom GPTs บน ChatGPT ผ่าน Actions:
   นำ URL http://localhost:8000/openapi.json ไปใส่ใน Custom GPT Action เพื่อสร้าง AI ผู้ช่วยนำทางรถเมล์ไทยได้ทันที

3. มาตรฐาน /llms.txt สำหรับ AI Web Search:
   มี Endpoint /llms.txt ตามมาตรฐานสากล เพื่อให้ Search Engine AI (เช่น Perplexity หรือ SearchGPT) ดึงข้อมูลไปตอบได้อย่างแม่นยำ

(อ่านคู่มือการเชื่อมต่อ AI ทุกแพลตฟอร์มโดยละเอียดได้ที่ docs/AI_INTEGRATION_GUIDE.md)

🏗 สถาปัตยกรรมระบบ (Architecture)

flowchart LR
  subgraph Sources["แหล่งข้อมูลภายนอก"]
    G["GTFS Static<br/>สนข. Namtang · CC-BY 4.0"]
    RT[("Realtime Feeds<br/>GTFS-RT: NECTEC / ขสมก.")]
  end

  subgraph Ingestion["การนำเข้าและตรวจสอบข้อมูล"]
    L["gtfs_loader.py<br/>Stream Ingestion · ValidationReport"]
  end

  subgraph Storage["การจัดเก็บข้อมูล"]
    DB[("SQLite dev / PostgreSQL + PostGIS prod")]
  end

  subgraph Core["บริการหลัก (Services)"]
    S["Stops · Routes · Departures · Planner · Geo · Calendar"]
    P["Realtime Provider<br/>Null · Mock · GTFS-RT"]
  end

  subgraph API_Layer["ชั้น API และการส่งข้อมูล"]
    H["api/handlers.py<br/>Framework-agnostic Logic"]
    F["FastAPI Backend<br/>/api/* · /docs"]
    D["devserver.py<br/>Python Stdlib"]
    B["scripts/build_demo.py<br/>Standalone Snapshot Builder"]
  end

  subgraph Clients["ส่วนแสดงผล"]
    UI["Web Map UI<br/>Leaflet.js + GPS Radar Pin"]
    Demo["dist/demo.html<br/>Single-file Offline Demo"]
  end

  G --> L
  L --> DB
  DB --> S
  RT -.-> P
  S --> H
  P --> H
  H --> F
  H --> D
  H --> B
  F --> UI
  B --> Demo

🔌 API Reference

Base URL สำหรับการทดสอบในเครื่อง: http://localhost:8000
ทุก Endpoint ทำงานผ่าน HTTP Method GET และตอบกลับเป็น JSON UTF-8

⚙️ ตัวแปรสภาพแวดล้อม (Environment Variables)

กำหนดค่าได้ผ่านไฟล์ .env หรือส่งผ่าน Environment ของ Container:

🧪 การทดสอบและควบคุมคุณภาพ (Testing & Quality)

โครงการนี้มี Unit Test ครอบคลุมทั้ง Ingestion Loader, Geo Math, Routing Planner, Realtime Provider และ HTTP Endpoints:

# รันชุดทดสอบทั้งหมด
make test
# หรือ: python -m unittest -v

# ตรวจสอบรูปแบบโค้ด (Linting)
make lint
# หรือ: ruff check app tests

📚 เอกสารประกอบ (Documentation)

📄 สัญญาอนุญาตและลิขสิทธิ์ (License & Attribution)

• Source Code: เผยแพร่ภายใต้สัญญาอนุญาต MIT License © 2026 Synergy Technology Co., Ltd. (SynTech)

• Transit Data: ข้อมูลการเดินรถและเส้นทางขนส่งมวลชน เผยแพร่ภายใต้สัญญาอนุญาต Creative Commons Attribution 4.0 International (CC-BY 4.0) โดย สำนักงานนโยบายและแผนการขนส่งและจราจร (สนข.) กระทรวงคมนาคม ผ่านระบบ "นำทาง (Namtang)"

• Basemap Tiles: แผนที่ฐาน © OpenStreetMap contributors