Appearance
SC-017 機種差枚3ヶ月ランキングショートコード
概要
- 指定ホール・対象月の機種別累計差枚ランキングを、当月・先月・先々月の3列で静的テーブル表示する。
- 合計機種差枚ランキングと平均機種差枚ランキングをタブで切り替えて、同時に1つだけ表示する。
- 記事内の縦の占有領域を抑えるため、既定は上位5位 +「...」+ 下位5位 + 新台グループに圧縮し、全順位はモーダルで表示する。
hall（ホール名）・target_month（対象月 YYYY-MM）を属性で受け取り、KishuSamai3MonthsRankingConverterでバリデーション・DTO 変換後、KishuSamai3MonthsRankingController→KishuSamai3MonthsRankingService経由でデータを取得、View で HTML にレンダリングする。- 有料記事固定セクション #5（機種差枚数ランキング）で利用する。
ワイヤーフレーム
ブロック一覧
| ブロックID | ブロック名 | 表示内容 | 初期値 | ユーザー操作 | アクション |
|---|---|---|---|---|---|
B-0 | 合計／平均タブ | 「合計」「平均」のタブトリガー | 「合計」が選択状態 | タブをクリック | 対応パネルへ切り替え |
B-1 | ランキングパネル | 見出し（ホールアイコン + ランキング名）と圧縮テーブル | 当月データがあるとき | なし | - |
B-2 | すべて表示ボタン | 選択中タブの全機種数を添えたボタン | 圧縮表示のときのみ | ボタンをクリック | 全順位モーダルを開く |
B-3 | 全順位モーダル | 選択中タブの全順位テーブル（省略なし） | 非表示（圧縮時のみ出力） | 閉じる操作 | 閉じるボタン / 背景 / Escape |
表示条件・注記
- 属性:
hall/target_month必須。 - 見出し: ホールアイコンを見出しに統合し、
🏝️合計機種差枚ランキング/🏝️平均機種差枚ランキングとする（ホール名はaria-labelでタブリストに付与）。 - 行数: 上位 5 +「...」+ 下位 5 +「新台」グループ。省略行を挟んでも行数が減らない 11 行以下、および新台グループを足すと全行より長くなる場合は全行表示。欠損月は「—」。当月・先月・先々月とも上がり／下がり色分け。
- 新台: 対象月に導入された機種（
db_new_machine_info.release_dateが対象月内かつkishu_id紐付け済み）。該当行の機種名の前に新台バッジを付ける（長い機種名の省略記号でバッジが隠れないようにするため機種名より前に置く）。上位 5 / 下位 5 に既に出ている新台はバッジのみで、新台グループには重複表示しない。 - タブ:
core_src/View/templates/packages/Tabs/tabs.jsの BEM 版マークアップ（.tabs__trigger/.tabs__panel）を利用する。パネルの表示制御 CSS は SC-017 のブロック配下で定義する。非アクティブパネルは CSS でdisplay: noneにするため、タブの切り替えと全順位モーダルは JS が動く前提とする（有料記事では両アセットをサーバー側で enqueue する）。 - モーダル: 共通
.data-detail-modalシェルを利用し、非表示の全順位テーブルを複製して表示する。圧縮表示にならないタブでは「すべて表示」ボタンと複製元テーブル・モーダルを出力しない。 - 0 件: no-data メッセージ。
- 実装参照: Twig
core_src/View/templates/kishu_samai_3months_ranking/kishu_samai_3months_ranking.twig（パネルは_panel.twig、テーブルは_table.twig）。JSkishu-samai-3months-ranking-modal.js。mockupmockups/KishuSamai3MonthsRankingWireframe/。
外部インターフェース
ショートコードタグ
- タグ名:
[kishu_samai_3months_ranking] - 入力例:
[kishu_samai_3months_ranking hall="アイランド秋葉原" target_month="2026-06"]
属性一覧
| 属性 | 役割 | 必須 |
|---|---|---|
hall | 対象ホール名（HallEnum 対応） | ○ |
target_month | 対象月（YYYY-MM 形式） | ○ |
表示仕様
| 項目 | 内容 |
|---|---|
| テーブル数 | 合計機種差枚ランキング / 平均機種差枚ランキング（タブで切り替え、同時に1つだけ表示） |
| カラム | 順位 / 機種名 / 当月差枚 / 先月差枚 / 先々月差枚 |
| ランキング順 | 当月の合計差枚（合計テーブル）/ 当月の平均差枚（平均テーブル）降順 |
| 行数 | 上位5行 + 省略行「...」 + 下位5行 + 新台グループ（圧縮しても行数が減らないときは全行表示） |
| 新台グループ | 下位5行の下に「新台」見出し行を挟み、対象月導入で上位・下位に未登場の機種を順位昇順で並べる |
| 全順位表示 | 圧縮表示のタブにのみ「すべて表示」ボタンを出し、省略なしの全順位をモーダル表示 |
| 行の母集団 | 当月データがある機種のみ（先月・先々月のみ存在する機種は行に含めない） |
| データ欠損 | 当該月に機種データがない場合は「—」 |
エラー
| 条件 | ユーザー向け挙動 | メッセージ / ログ |
|---|---|---|
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を変更しない- 理由: 有料記事テンプレート生成が属性名に依存するため