eMoBi向け実装ガイド(ポート共有MQTT)

eMoBi開発チームが最初に読むドキュメントです。詳細仕様に入る前に、何を・どの順で作ればよいかをまとめています。仕様の正は接続仕様書。

🤖 AIで実装する場合: AIコーディングアシスタント(Claude / Copilot等)には llms.md(自己完結の実装指示書)と event.schema.json(ペイロードのJSON Schema)のURLをそのまま渡してください。外部参照なしで実装・テスト生成に必要な情報がすべて入っています。

作るものは1つだけ

自社ポートの在庫(貸出可能台数・返却可能ドック数)が変わったら、JSONを1件MQTTでpublishする。

受信(subscribe)の実装は任意(他社在庫を使わないなら不要)
1台毎の車両状態(車両ID・バッテリー等)は送りません(仕様書§0.1。車両特定はREST標準API側の担当)
送るJSONは1種類(station.status_updated)。形は仕様書§4のとおり

事前に受け取るもの

STG接続情報	ホスト `gogo-cycle-mqtt-stg.fly.dev` / ポート `8883`(mqtts)— 仕様書§1
資格情報	ユーザー名/パスワードは別経路で共有(本サイトには記載しない)
partner_id	`emobi`(仕様書§2)

Step 1.接続確認(30分)

mosquitto_sub -h gogo-cycle-mqtt-stg.fly.dev -p 8883 \
  --capath /etc/ssl/certs -u emobi -P <password> \
  -i emobi-stg-test -t 'jp/events/#' -v

TLS必須(8883)。平文1883は閉じています
Node.jsの場合はリポジトリの mqtt/examples/node-publisher/subscribe.js がそのまま使えます

Step 2.テストpublish(30分)

mosquitto_pub -h gogo-cycle-mqtt-stg.fly.dev -p 8883 \
  --capath /etc/ssl/certs -u emobi -P <password> \
  -i emobi-stg-pub -q 1 -r \
  -t 'jp/events/emobi/stations/test-001/status' \
  -m '{"event_id":"emobi-017f22e2-79b0-8cc3-98c4-dc0c0c073001","event_type":"station.status_updated","source_partner_id":"emobi","timestamp":"2026-08-18T10:30:00Z","payload":{"station_id":"test-001","num_vehicles_available":5,"num_docks_available":10,"reason_code":"VEHICLE_RETURNED"}}'

-q 1 -r(QoS 1 / retain)を忘れないこと(仕様書§3の規約)
publishできるのは自社プレフィックス jp/events/emobi/# のみ(ACL)。他は拒否されます

Step 3.ダッシュボードで目視確認(5分)

ダッシュボードに同じ資格情報でログインすると、Step 2で送ったポートが表に出ます。以後の開発中の動作確認にも使えます。

Step 4.本実装

自社システムの在庫変動イベントに、publishを組み込みます。

発火タイミング(仕様書§3・§4.2)

自社システムのできごと	reason_code
ユーザーが車両を返却した	`VEHICLE_RETURNED`
再配置で車両を置いた	`REBALANCE_DROP_OFF`
再配置で車両を回収した	`REBALANCE_PICK_UP`
故障対応等で回収した	`MAINTENANCE_OUT`
ユーザーが車両を借りた(貸出)	`VEHICLE_RENTED`(本事業の拡張値・仕様書 v1.5。省略も可)

実装チェックリスト

状態変化時に即時(数秒以内)publish。変化がないときの定期再送は不要
QoS 1 / retain true
event_id は毎回一意(UUID推奨)
timestamp はUTC(RFC3339)。JSTのまま送らない
event_id は {自社partner_id}-{UUID v8} 形式(仕様書§4.3)
トピックの station_id・source_partner_id とJSON内の値を一致させる
クライアントIDは emobi-stg-<プロセス毎に一意>(同一IDの同時接続は後勝ちで切断)
切断時の自動再接続(推奨5秒間隔)+ 未送信イベントの再送
1メッセージ64KB以内(在庫イベントは通常1KB未満なので実質問題なし)

参考実装: リポジトリの mqtt/examples/node-publisher/(publish.js=単発送信 / simulate.js=連続送信の例)

Step 5.結合確認 → 本番へ

実ポートの一部でSTGにpublishし、gogoshare側で受信確認(ダッシュボード+在庫保持サーバー)
問題なければ本番の資格情報を発行(接続先を gogo-cycle-mqtt.fly.dev に変えるだけ。実装変更は不要)

よくある質問

Q	A
1台毎の状態(車両ID・バッテリー)は送る?	送らない。本IFはポート単位の集計のみ(仕様書§0.1)。車両の特定・予約・解錠はREST標準API側で別途
受信(subscribe)は実装必要?	任意。他社在庫を自社サービスで使う場合のみ(その際は仕様書§5に従う)
全ポートの初期値はどう送る?	接続後に全ポート分を1回publishすればよい(retainされ、以後は変化分のみ)
テストで送ったデータを消したい	同じトピックに空ペイロードをretainでpublishすると消える
ブローカーが落ちていたら?	クライアントの自動再接続で復旧。retainにより受信側の状態も自動回復(仕様書§5.5)
順番が前後したら?	受信側が `timestamp` で新旧判定する規約(仕様書§5.3)。送信側は正しいUTC時刻を入れることだけ守る

スケジュール(2026-08-04打合せ合意)

8月後半	eMoBi: 在庫publish実装(このガイドの範囲)・STG結合
9月前半	eMoBi: 施錠・解錠API(非公開API)の開発・仕様書アウトプット ※本ガイド範囲外
9月後半〜	gogoshare: アプリ組み込み。11月: 結合テスト・実証