SC-017 機種差枚3ヶ月ランキングショートコード

概要

指定ホール・対象月の機種別累計差枚ランキングを、当月・先月・先々月の3列で静的テーブル表示する。
合計機種差枚ランキングと平均機種差枚ランキングの2テーブルを出力する。
hall（ホール名）・target_month（対象月 YYYY-MM）を属性で受け取り、KishuSamai3MonthsRankingConverter でバリデーション・DTO 変換後、KishuSamai3MonthsRankingController → KishuSamai3MonthsRankingService 経由でデータを取得、View で HTML にレンダリングする。
有料記事固定セクション #5（機種差枚数ランキング）で利用する。

ワイヤーフレーム

ブロック一覧

ブロックID	ブロック名	表示内容	初期値	ユーザー操作	アクション
`B-0`	ホールラベル	HallEnum アイコン（`title` / `aria-label` にホール名）	hall 属性どおり	なし	-
`B-1`	合計機種差枚ランキング	順位・機種名・当月／先月／先々月（上位行＋省略）	当月データがあるとき	なし	-
`B-2`	平均機種差枚ランキング	同上（平均差枚）	同上	なし	-

表示条件・注記

属性: hall / target_month 必須。
行数: 上位 10 +「...」+ 下位 10（21 行以下は全行）。本ワイヤーは省略ありケースのサンプル。欠損月は「—」。当月・先月・先々月とも上がり／下がり色分け。
0 件: no-data メッセージ。
実装参照: Twig core_src/View/templates/kishu_samai_3months_ranking/kishu_samai_3months_ranking.twig。mockup mockups/KishuSamai3MonthsRankingWireframe/。

外部インターフェース

ショートコードタグ

タグ名: [kishu_samai_3months_ranking]
入力例: [kishu_samai_3months_ranking hall="アイランド秋葉原" target_month="2026-06"]

属性一覧

属性	役割	必須
`hall`	対象ホール名（HallEnum 対応）	○
`target_month`	対象月（YYYY-MM 形式）	○

表示仕様

項目	内容
テーブル数	合計機種差枚ランキング / 平均機種差枚ランキング
カラム	順位 / 機種名 / 当月差枚 / 先月差枚 / 先々月差枚
ランキング順	当月の合計差枚（合計テーブル）/ 当月の平均差枚（平均テーブル）降順
行数	上位10行 + 省略行「...」 + 下位10行（21行以下は全行表示）
行の母集団	当月データがある機種のみ（先月・先々月のみ存在する機種は行に含めない）
データ欠損	当該月に機種データがない場合は「—」

エラー

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

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

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