SC-019 ホール差枚数ランキングショートコード

概要

指定ホール群・対象月の日別ホール差枚数ランキングを表示する。
ホール単体ランキング（ホールごと）と、複数ホール合算ランキングを1ショートコードで出力する。
各行に日付（曜日）、合計差枚数、平均差枚数（枚/台）、サムネイル（Cale2_MakeCalender と同じ解決ロジック）を表示する。
halls（カンマ区切りホール名）・target_month（対象月 YYYY-MM）を属性で受け取り、HallSamaiRankingConverter でバリデーション・DTO 変換後、HallSamaiRankingController → HallSamaiRankingService 経由でデータを取得、View で HTML にレンダリングする。
有料記事固定セクション #8（ホール差枚数ランキング）で利用する。

ワイヤーフレーム

ブロック一覧

ブロックID	ブロック名	表示内容	初期値	ユーザー操作	アクション
`B-0`	ホール単体ランキング	ホール A の順位・日付・合計／平均差枚・サムネイル	halls 先頭ホール	サムネリンク	-
`B-1`	ホール単体ランキング	ホール B 以降（ホール数分。本サンプルは 2 ホール目）	halls に 2 件以上あるとき	同上	-
`B-2`	合算ランキング	2 ホール以上の合算（平均差枚降順）。サムネはホール分並ぶ	halls が 2 件以上のときのみ	同上	-

表示条件・注記

属性: halls / target_month 必須。
合算: 2 ホール以上のときのみ表示。
0 件: no-data メッセージ。
実装参照: Twig core_src/View/templates/hall_samai_ranking/hall_samai_ranking.twig。mockup mockups/HallSamaiRankingWireframe/。

外部インターフェース

ショートコードタグ

タグ名: [hall_samai_ranking]
入力例: [hall_samai_ranking halls="アイランド秋葉原,エスパス秋葉原" target_month="2026-06"]

属性一覧

属性	役割	必須
`halls`	対象ホール名（HallEnum 対応、カンマ区切り）	○
`target_month`	対象月（YYYY-MM 形式）	○

表示仕様

項目	内容
ブロック数	ホール単体ランキング（ホール数分）+ 合算ランキング（2ホール以上時）
ホール別並び順	合計差枚数の降順
合算並び順	平均差枚数（合計差枚 ÷ 合計台数）の降順
表示行	対象月のうちデータがある全日
サムネイル	`pworld_hall_day_thumbnail` 優先 → 静的 PNG フォールバック
サムネイルリンク	日別記事 URL + `#hall_slug` アンカー（記事がある日のみ）

エラー

条件	ユーザー向け挙動	メッセージ / ログ
`halls` 未指定または不正値	`ErrorHandler` の返す文言	`ValidationException`（HallEnum 照合失敗）
`target_month` 未指定または空	`ErrorHandler` の返す文言	`ValidationException`（`HallSamaiRankingMessages::TARGET_MONTH_REQUIRED`）
`target_month` 形式不正	`ErrorHandler` の返す文言	`ValidationException`（`HallSamaiRankingMessages::TARGET_MONTH_INVALID`）
該当データなし	段落テキスト	`HallSamaiRankingMessages::NO_DATA`
コントローラー・サービスの `\Exception`	`ErrorHandler` の返す文言	`ErrorHandler::handle_error()` 経由

更新不可とみなすもの（git管理外の内容に依存し、リポジトリだけでは追従できない依存）

ショートコード名 hall_samai_ranking を変更しない
- 理由: 有料記事本文にショートコードタグが自動生成されるため
属性名 halls / target_month を変更しない
- 理由: 有料記事テンプレート生成が属性名に依存するため