Appearance
SC-016 期間機種別差枚ランキングショートコード
概要
- 指定期間・ホールの 機種別差枚ランキング（合計 / 平均タブ切替）と 折れ線グラフ（累計 / 単日切替、チェックボックスで系列 ON/OFF）を出力する。
- PUB-005 では 専用ページテンプレート を正とし、固定ページ本文にショートコードを置く必要はない。タグ
[period_kishu_samai_ranking]は埋め込み・後方互換用（広告なし・結果エリア一体型）。 - 期間・ホール・台数条件は ページ上フォーム で変更する。初回 HTML はフォーム + プレースホルダ。データ本体は API-001-15 で取得する。
- 日別記事（PUB-003 機種別ランキング / SC-009 kishudata）からクエリ付きリンクで遷移し、記事日の 月・ホール・任意 kishu を初期状態に反映する。
ワイヤーフレーム
PUB-005 のワイヤーフレーム と同一: <PeriodKishuSamaiRankingWireframeReactHost />
外部インターフェース
ショートコードタグ
- タグ名:
[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 |