ディープリンクで短縮ID (?id=<code>) から経路を解決できるようにする

[TinyKitten]

背景

Route Builder で組み立てたユーザのカスタム経路を TrainLCD に渡すフローについて、現在提案している sids 形式（#6002）では経路の全駅 ID をクエリパラメータに直接並べる構造のため、長距離経路（数十駅以上）になると URL 長が肥大化する。結果として QR コードのバージョンが上がりスキャンしづらくなる、SMS 等での共有が難しくなる、といった課題がある。

これを解消する案として、Route Builder 側で sids をサーバに保存して短縮IDを発行し、TrainLCD は短縮IDから resolver 経由で sids を取得する形を検討している。本Issue は、TrainLCD 本体で ?id=<short-id> 形式のディープリンクを受信した際の受信側仕様の提案。

提案

新パラメータ id を useDeepLink に追加することを提案する。

trainlcd://route?id=<8〜16文字のID>

ID は base64url 文字 (A-Za-z0-9_-) の最大32文字を想定。

resolver URL

Route Builder のバックエンドが以下のエンドポイントを公開する想定。具体的なホスト名は別途共有 / 設定で渡す。

• GET <resolver-host>/api/routes/<id>
• 成功時レスポンス: { "sids": [<station.id>, ...] }
• 404 時: { "error": "not found" }
• 成功時の Cache-Control: public, s-maxage=31536000, stale-while-revalidate=86400（content-addressed なので長期キャッシュ可）

TrainLCD 側で resolver のホスト名を env / config で持つ形にしておくと、将来独自ドメインに切り替える際に差し替えが楽。

受信側の挙動

1. id がクエリに含まれている場合、id を経路解決の単独ソースとして扱う（他の経路指定系パラメータが同時に含まれていても経路解決の判断には用いない）
2. ID を validate (^[A-Za-z0-9_-]{1,32}$)、失敗なら何もしない
3. <resolver-host>/api/routes/<id> に GET（タイムアウト 5〜10秒）
4. 成功: 取得した sids を ?sids=... と同等に処理して stationState.stations に投入
5. 失敗（404 / 通信エラー / タイムアウト）: エラーをユーザに通知（failedToFetchStation 等の既存翻訳が流用可）

auto / theme 等の動作系オプションは上記分岐に関わらず通常通り解釈する。

URL長の比較

短縮前 (sids=...):

trainlcd://route?sids=1131211,1131310,2800217,2800218,...,1130103

50駅で約400文字、QR バージョン 4〜5。

短縮後 (id=...):

trainlcd://route?id=a1b2c3d4e5

任意の長さの経路でも約35文字、QR バージョン 1〜2。

後方互換性

• 既存の sgid / lid / lgid / sids ベースのリンク（id を含まないリンク）はそのまま従来通り解釈する
• 新パラメータ id を受け取った時のみ resolver にアクセスする
• iOS/Android のURLスキーム (trainlcd / trainlcd-canary) は変更なし
• auto / theme 等の既存パラメータは id と併用可能

受け入れ条件

• ?id=<code> 形式のリンクで resolver から取得した sids が stationState.stations に正しく投入される
• resolver 通信失敗時（404 / タイムアウト / ネットワークエラー）にユーザへエラー通知
• resolver 応答の Cache-Control を尊重（OS/フレームワークのHTTPキャッシュに乗る程度で十分）
• 自動モード（auto）／テーマ（theme）等の既存パラメータは併用可能
• 既存形式 (sgid/lid/dir/sids) のリンクは動作変化なし

関連

• 前提: ディープリンクで他路線直通・経路全体を表現できるようにする #6002（sids パラメータ提案）
• 実装側: TrainLCD/RouteBuilder