Appearance
SC-019 ホール差枚数ランキングショートコード
概要
- 指定ホール群・対象月の日別ホール差枚数ランキングを表示する。
- ホール単体ランキング（ホールごと）と、複数ホール合算ランキングを1ショートコードで出力する。
- 各行に日付（曜日）、合計差枚数、平均差枚数（枚/台）、サムネイル（Cale2_MakeCalender と同じ解決ロジック）を表示する。
halls（カンマ区切りホール名）・target_month（対象月 YYYY-MM）を属性で受け取り、HallSamaiRankingConverterでバリデーション・DTO 変換後、HallSamaiRankingController→HallSamaiRankingService経由でデータを取得、View で HTML にレンダリングする。- 有料記事固定セクション #8（ホール差枚数ランキング）で利用する。
ワイヤーフレーム
ブロック一覧
| ブロックID | ブロック名 | 表示内容 | 初期値 | ユーザー操作 | アクション |
|---|---|---|---|---|---|
B-0 | ホール単体ランキング | ホール A の順位・日付・合計／平均差枚・サムネイル | halls 先頭ホール | サムネリンク、「すべて表示」 | 5件以上は全件モーダル |
B-1 | ホール単体ランキング | ホール B 以降（ホール数分。本サンプルは 2 ホール目） | halls に 2 件以上あるとき | 同上 | 同上 |
B-2 | 合算ランキング | 2 ホール以上の合算（平均差枚降順）。サムネはホール分並ぶ | halls が 2 件以上のときのみ | 同上 | 同上 |
表示条件・注記
- 属性:
halls/target_month必須。 - 合算: 2 ホール以上のときのみ表示。
- 行数制御: 5 件以上は上位 3 位 + 省略行「...」のみをテーブル本体に表示し、「すべて表示（全 N 件）」ボタンから全順位テーブルをモーダル表示する。4 件以下は圧縮せず、ボタンも表示しない。
- 0 件: no-data メッセージ。
- 実装参照: Twig
core_src/View/templates/hall_samai_ranking/hall_samai_ranking.twig。mockupmockups/HallSamaiRankingWireframe/。
外部インターフェース
ショートコードタグ
- タグ名:
[hall_samai_ranking] - 入力例:
[hall_samai_ranking halls="アイランド秋葉原,エスパス秋葉原" target_month="2026-06"]
属性一覧
| 属性 | 役割 | 必須 |
|---|---|---|
halls | 対象ホール名（HallEnum 対応、カンマ区切り） | ○ |
target_month | 対象月（YYYY-MM 形式） | ○ |
表示仕様
| 項目 | 内容 |
|---|---|
| ブロック数 | ホール単体ランキング（ホール数分）+ 合算ランキング（2ホール以上時） |
| ホール別並び順 | 合計差枚数の降順 |
| 合算並び順 | 平均差枚数（合計差枚 ÷ 合計台数）の降順 |
| 表示行 | 4件以下は全日。5件以上は上位3位 + 省略行を本体表示し、全件はモーダル表示 |
| サムネイル | pworld_hall_day_thumbnail 優先 → 静的 PNG フォールバック |
| サムネイルリンク | 日別記事 URL + #hall_slug アンカー（記事がある日のみ） |
全件モーダル
- 圧縮されたブロックにのみ「すべて表示（全 N 件）」ボタンを出す。
- ボタン押下時は、ブロックごとに保持した hidden の全順位テーブルを
.data-detail-modal__bodyに複製して表示する。 - モーダルの器は共通
.data-detail-modalを利用し、同一ページにホール別・合算ブロックが複数あってもinstance_idとブロック番号で対象テーブルを一意に解決する。
エラー
| 条件 | ユーザー向け挙動 | メッセージ / ログ |
|---|---|---|
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を変更しない- 理由: 有料記事テンプレート生成が属性名に依存するため