Appearance
SC-016 期間機種別差枚ランキングショートコード
概要
- 指定期間・ホールの 機種別差枚ランキング（合計 / 平均タブ切替）と 折れ線グラフ（累計 / 単日切替、チェックボックスで系列 ON/OFF）を出力する。
- PUB-005 では 専用ページテンプレート を正とし、固定ページ本文にショートコードを置く必要はない。タグ
[period_kishu_samai_ranking]は埋め込み・後方互換用（広告なし・結果エリア一体型）。 - 期間・ホール・台数条件は ページ上フォーム で変更する。初回 HTML はフォーム + プレースホルダ。データ本体は API-001-15 で取得する。
- 日別記事（PUB-003 機種別ランキング / SC-009 kishudata）からクエリ付きリンクで遷移し、記事日の 月・ホール・任意 kishu を初期状態に反映する。
ワイヤーフレーム
PUB-005 と 同一 Host（PeriodKishuSamaiRankingWireframeReactHost）。新規 React は作らない。
ブロック一覧（要約）
正本の詳細は PUB-005 ブロック一覧 を参照。
| ブロックID | ブロック名 | 表示内容（要約） | SC 経路での差分 |
|---|---|---|---|
B-0 | 画面ヘッダ | ページタイトル・機能説明 | 埋め込み時は省略されうる |
B-1 | 検索フォーム | 期間・ホール・台数・不等号・表示ボタン | 同一 |
B-2 | 指標タブ | 合計差枚 / 平均差枚 | 同一 |
B-3 | ランキング表 | 順位・機種・指標・集計台数・グラフチェック | 同一 |
B-4 | 折れ線グラフ | 累計 / 単日切替 + Chart.js | 同一 |
B-5 | 状態表示 | ローディング / 0件 / エラー | 同一 |
B-6 | 機種ハイライト | URL kishu 時の行強調 + グラフチェック ON | 同一 |
B-7 | 広告 | B-3 と B-4 の間（[random_adsense_ad provider="a8"]） | SC 経路では出さない（PUB テンプレのみ） |
B-8 | グラフ見出し | 「機種別差枚 折れ線グラフ」 | PUB のみ常時表示の見出し。SC では結果エリア内（一体型） |
表示条件・注記
- 共有 Host: PUB-005 と同一。ブロック詳細・アクションは PUB-005 側が正本。
- SC 経路の差分: ショートコード埋め込みは 広告なし（PUB の
B-7はテンプレート配置のため SC では表示されない）。結果エリアは一体型。B-8も PUB テンプレ配置で常時表示。SC は一体型のため同等の常時見出しは出さない。 - 実装参照: mockup
mockups/PeriodKishuSamaiRankingWireframe/（または PUB-005 側 Host 登録）。部分 Twig・webpack は共有。エントリは SC 用 / PUB ページ用で分離（広告・見出し配置の差分はここに集約）。
外部インターフェース
ショートコードタグ
- タグ名:
[period_kishu_samai_ranking] - 入力例（最小）:
[period_kishu_samai_ranking] - 入力例（初期値指定）:
[period_kishu_samai_ranking default_hall="アイランド秋葉原" chart_top_n="5"]
属性一覧
| 属性 | 役割 | 必須 |
|---|---|---|
default_hall | フォーム初期ホール（HallEnum 対応）。URL hall がある場合は URL 優先 | 任意 |
default_period_start | フォーム初期開始日（YYYY-MM-DD / YYYY/MM/DD / YYYYMMDD） | 任意 |
default_period_end | フォーム初期終了日（同上） | 任意 |
chart_top_n | グラフチェックボックスの初期 ON 件数（既定 5、上限 10） | 任意 |
ranking_limit | 後方互換用（非推奨。クライアント側で初期 10 行 +「さらに読み込む」+10 行） | 任意 |
必須属性なし（フォーム駆動のため）。
URL クエリ（ディープリンク）
| クエリ | 役割 |
|---|---|
hall | フォーム初期ホール |
target_day | リンク元記事日 → 属する暦月を期間に展開 |
period_start | 明示開始日（target_day より target_day 優先） |
period_end | 明示終了日 |
kishu | ハイライト機種（表強調 + グラフチェック ON） |
後方互換: 旧
dayパラメータは読み取りのみサポート。新規リンクはtarget_dayを使用する。
出力
| ブロック | 内容 |
|---|---|
| フォーム | 期間・ホール・台数・不等号入力 + 表示ボタン + 注記 |
| タブ | 合計差枚 / 平均差枚 |
| 表 | 機種別ランキング + グラフ列チェックボックス |
| グラフ | Chart.js 折れ線（累計 / 単日切替、チェック ON 機種のみ描画） |
アセット
- SC-016 専用 webpack エントリ（Chart.js を daily-article-public バンドルと分離）
- CSS: BEM +
ranking-common.css再利用
エラー
| 条件 | ユーザー向け挙動 | メッセージ / ログ |
|---|---|---|
| 期間未入力・不正形式 | B-5 エラー表示 | ValidationException（SC-010 同等） |
period_start > period_end | 同上 | ValidationException |
| 期間が 366 日超 | 同上 | ValidationException |
hall 未選択または不正 | 同上 | ValidationException（HallEnum 照合失敗） |
| 台数のみ指定・不等号未指定 | 同上 | ValidationException |
unit_count が負数または非整数 | 同上 | ValidationException |
| API エラー | B-5 エラー表示 | REST エラーメッセージ |
| 0 件 | B-5 空状態メッセージ | データなし文言 |
今後の更新で崩してはいけないところ（互換性契約）
公開契約（Breaking change 扱い）
- ショートコード名
period_kishu_samai_rankingを変更しない - 属性名
default_hall/default_period_start/default_period_end/chart_top_n/ranking_limitを変更しない - URL クエリ名
hall/target_day/period_start/period_end/kishuを変更しない（日別記事リンクとの契約）。旧dayは読み取り互換として残す
関連設計書
| 種別 | 参照 |
|---|---|
| 公開画面 | PUB-005 |
| DTO | IF-002 |
| REST | API-001-15 |