Fun Now and Future - Backend

キャンパス内の混雑度リアルタイム可視化システム「Fun Now and Future」のバックエンド API です。 ESP32 から送信される BLE 検知データを処理し、Firestore への保存およびサイネージ・アプリ向けの混雑度データ提供を行います。

お約束

プログラムを書く上で

基本的に下記のサイトに書いてることに従います。
https://golang.org/doc/effective_go.html

Github

Branch命名規則

• master
  • プロダクトとしてリリースするためのブランチ. 基本触らない
• develop(default)
  • 開発ブランチ． コードが安定し,リリース準備ができたら master へマージする. リリース前はこのブランチが最新バージョンとなる.
• feature
  • 機能の追加. develop から分岐し, develop にマージする.
  • feature-{任意で詳細}
• fix
  • 現在のプロダクトのバージョンに対する変更・修正用.
  • fix-{任意で詳細}

コミットメッセージ

• add:新機能
• fix:バグ修正
• wip:作業中（WIP：Work In Progress）
• clean:整理（削除も含む）

issue,Pull Requestのラベル(主に使って欲しいものを明記)

• bug バグの内容、解決したいことについて記述
• documentation ドキュメントの更新
• enhancement 新機能の開発
• help wanted 助けて欲しいこと(基本わからないことがあったらこれ書いて)
• question 質問、議論(わからないことではなく「これであっているのか不安だな」ということについて書いてください)

技術構成

• Runtime - Node.js 24 / TypeScript
• Framework - Hono（@hono/node-serverでNode.jsのHTTPサーバーとして起動）
• Database - Firebase Firestore（firebase-admin経由でアクセス。Cloud Run上でもFirestore自体は独立して利用可能）
• Validation - Zod
• Testing - Jest / Hono app.request（Firestoreエミュレータを使用）
• Deploy - Docker → Cloud Run

アーキテクチャ（層構成）

src/
├── index.ts               # エントリーポイント（serve()でサーバー起動のみ）
├── app.ts                 # Honoアプリの組み立て（ルーティングの登録）
├── controllers/           # HTTPの受け口（リクエスト検証・レスポンス整形）
│   └── sensor.ts
│   └── signage.ts
├── services/              # ビジネスロジック（混雑度判定など）
│   └── congestion.ts
├── repositories/          # Firestoreへの読み書きのみ
│   └── firestore.ts
├── middlewares/           # 認証など横断的な処理
│   └── sensor_auth.ts
└── lib/
    └── firebase.ts        # Firebase Admin SDKの初期化

主な機能・エンドポイント

Base URL: まだデプロイしてない

1. GET /health

死活監視用のエンドポイント。

{ "status": "ok", "message": "Backend is running" }

2. POST /receiveSensorData

ESP32（センサー端末）から BLE 検知データを受信し、Firestore に保存。

• 認証 - ヘッダー x-api-key: <API_KEY>
• リクエストボディ

{
  "sensor_id": "esp32_cafeteria_01",
  "location": "cafeteria",
  "ble_advertising_raw_data": ["raw_packet_1", "raw_packet_2"],
  "timestamp": "2026-07-28T07:30:00.000Z",
  "ble_mac_addresses": ["AA:BB:CC:DD:EE:01", "AA:BB:CC:DD:EE:02"]
}

• レスポンス例 (200 OK)

{
  "status": "success",
  "message": "Data received successfully",
  "received_at": "2026-07-28T07:30:00.000Z",
  "data": { "sensor_id": "esp32_cafeteria_01", "location": "cafeteria", "...": "..." }
}

3. GET /getCongestion

指定したロケーションの最新の混雑度データを取得します。

• クエリパラメータ: location（必須）
• レスポンス例 (200 OK)

{
  "status": "success",
  "data": {
    "sensor_id": "esp32_cafeteria_01",
    "location": "cafeteria",
    "received_at": "2026-07-28T07:30:00.000Z",
    "congestion_level": "low",
    "congestion_label": "空いている"
  }
}

• congestion_level: low | medium | high（ble_device_countが20未満/50未満/50以上で判定）

4. GET /getCongestionHistory

指定したロケーションの混雑度の履歴データを取得。

• クエリパラメータ: location（必須）, limit（任意 / デフォルト50件, 最大50件）
• レスポンス例 (200 OK)

{
  "status": "success",
  "count": 2,
  "data": [
    {
      "sensor_id": "esp32_cafeteria_01",
      "location": "cafeteria",
      "received_at": "2026-07-28T07:30:00.000Z",
      "congestion_level": "low",
      "congestion_label": "空いている"
    }
  ]
}

ロケーションIDの一覧(location)

location (ID)	設置場所	対応するサイネージ表示	備考
cafeteria	学内食堂	左側「食堂の混雑状況」	食堂用の ESP32 から送信
bus_stop	バス停留所	右下「バス停の混雑状況」	バス停用の ESP32 から送信

---

ローカル開発・テスト手順

1. 依存パッケージのインストール

npm install

2. ビルド

npm run build

3. ローカルでサーバーを起動

npm start
# または
node lib/index.js

http://localhost:8080 で待ち受けます（PORT環境変数で変更可）。

4. 単体テストの実行

Firestoreエミュレータを自動起動してJestテストを実行します。

npm test

ローカルに firebase CLI（firebase-tools）が必要です。未インストールの場合は npm install -g firebase-tools するか、npx firebase-tools ... に置き換えてください。

Dockerでのビルド・起動

cd functions
docker build -t fun-now-and-future-backend .
docker run -p 8080:8080 fun-now-and-future-backend
curl http://localhost:8080/health

Cloud Runへのデプロイ

gcloud run deploy --source functions