PUB-005 期間機種別差枚ランキング

概要

WordPress 固定ページ（スラッグ period-kishu-ranking）に 専用ページテンプレート「期間機種別差枚ランキング」（myCustom/myTemplate/page-period-kishu-samai-ranking-template.php）を割り当てて公開する画面。UI は SC-016 と同一機能をテンプレート層で出力する（固定ページ本文のショートコードブロックは不要）。
ユーザーが 期間・ホール・台数条件 をフォームで指定し、期間内の 機種別差枚ランキング（合計差枚 / 平均差枚のタブ切替）と 折れ線グラフ（累計差枚 / 単日差枚の切替、チェックボックスで系列 ON/OFF）を表示する。
PUB-001 日別記事（シングル）の機種別ランキング（PUB-003 B-2）および SC-009 kishudata から クエリ付きリンク で遷移可能。リンク元記事の日付が属する暦月を期間初期値とし、任意で kishu をハイライトする。
データ取得は初回 HTML 後に API-001-15（REST）経由。契約は IF-002 を正とする。
折れ線グラフ描画には Chart.js を新規導入する（リポジトリ内に既存の折れ線グラフ実装なし）。

ワイヤーフレーム

画面仕様

ブロック一覧

ブロックID	ブロック名	表示内容	初期値	ユーザー操作	アクション
`B-0`	画面ヘッダ	ページタイトル・機能説明（固定ページ見出しと重複しない短文）	固定文言	なし	-
`B-1`	検索フォーム	開始日・終了日・ホール・台数・不等号（以上/以下）・「表示」ボタン。注記を併記	URL クエリ > SC 属性 > デフォルト（直近7日・HallEnum 先頭）	条件変更、表示	A-1
`B-2`	指標タブ	「合計差枚」「平均差枚」タブ	「合計差枚」	タブクリック	A-2
`B-3`	ランキング表	順位・機種名・指標値（枚）・集計台数・グラフ（チェックボックス）。初期 10 行、「さらに読み込む」で +10 行（全件まで）	未検索時は非表示	グラフチェック ON/OFF、さらに読み込む	A-2, A-5, A-7
`B-4`	折れ線グラフ	累計差枚 / 単日差枚切替 + Chart.js。チェック ON の機種のみ描画	未検索時は非表示。グラフ種別 = 累計	グラフ種別切替	A-2, A-6
`B-5`	状態表示	ローディング / 0件 / バリデーションエラー	未検索時は「条件を指定して表示してください」	なし	-
`B-6`	機種ハイライト	URL `kishu` 指定時、該当行を強調表示。グラフチェックも ON（top N 外でも可）	クエリ `kishu` があるときのみ	なし	A-4
`B-7`	広告	B-3 と B-4 の間。常時表示。SC-003 `[random_adsense_ad provider="a8"]`（テンプレート Twig 配置）	常時	なし	-
`B-8`	グラフ見出し	「機種別差枚折れ線グラフ」セクション見出し（`id="chart-section"`）。常時表示	固定文言	なし	-

検索フォーム（B-1）— 台数フィルタ

要素	仕様
台数入力	整数 ≧ 0。空 = フィルタなし
不等号	セレクト「以上」「以下」。台数が空のときは無効化し API に送らない
注記	フォーム近傍に「台数は条件の終了日の台数とする」を常時表示

指標の定義

タブ	ソートキー	表示値
合計差枚	期間内 `diff_coin` 合計（降順）	合計差枚数（符号付き整数＋「枚」）
平均差枚	期間内台あたり平均差枚（降順）	平均差枚（小数1桁＋「枚」）

「集計台数」列は 期間内の台数合計（aggregated_count）。台数フィルタの判定値（count_on_period_end）とは別。

グラフ列チェックボックス（B-3）

項目	仕様
列位置	「集計台数」の右
初期 ON	A-1 成功時、現在タブのソート上位 `chart_top_n` 件 + `highlight_kishu` 行（top N 外でも ON）
タブ切替 A-2	表のソートのみ切替。チェック状態は機種名キーで保持（リセットしない）
再検索 A-1	チェック状態を初期状態にリセット
リアルタイム	A-5: ON/OFF 即時に B-4 を再描画（API 再取得なし）

折れ線グラフ（B-4）

項目	仕様
グラフ種別切替	累計差枚 / 単日差枚（ラジオまたはセグメント）。初期 = 累計
系列	B-3 でチェック ON の機種のみ
X軸	期間内の各日（`period_start` 〜 `period_end` の暦日すべて）
Y軸（累計）	`cumulative_samai`（累計差枚・枚）
Y軸（単日）	`daily_samai`（単日差枚・枚）
データ無し日	`daily_samai: 0`、累計は前日累計 + 0（横持ちしない）
種別切替 A-6	保持 JSON から Y 軸データを切替描画（API 不要）

ディープリンク（URL クエリ）

param	必須	説明
`hall`	△	ホール名（HallEnum 日本語名。URL エンコード）
`target_day`	△	リンク元日別記事の対象日。属する暦月を期間に展開（例: `20240315` → `2024-03-01`〜`2024-03-31`）
`period_start`	△	明示開始日。`target_day` より target_day を優先
`period_end`	△	明示終了日。`target_day` とセットで使用
`kishu`	任意	ハイライト対象機種名（B-6）。グラフチェックも ON

後方互換: 旧パラメータ day（Ymd）はクライアント側で読み取り可能だが、WordPress 予約クエリ変数と衝突するため新規リンクでは target_day を使用する。

初期値の優先順位: URL クエリ > ショートコード属性 > デフォルト

日別記事からのリンク（実装フェーズ）

リンク元	対象要素	付与パラメータ
PUB-003 ランキング `B-2`	機種名セル	`hall`, `target_day`, `kishu`
SC-009 kishudata	機種名見出し	`hall`, `target_day`, `kishu`

リンク先ベース URL: PHP 定数（1箇所管理）で固定ページのパーマリンクを参照
スタイル: colors.css の --color-link / --color-link-hover を踏襲

処理連携仕様

A-1 検索フォーム送信

フォームの「表示」ボタン押下、または Enter 確定時に API-001-15 を呼び出す。

リクエスト

requestParam	本画面の値（どの部品から何を送るか）
`period_start`	`B-1` 開始日入力（`YYYY-MM-DD`）
`period_end`	`B-1` 終了日入力（`YYYY-MM-DD`）
`hall`	`B-1` ホール選択値
`unit_count`	`B-1` 台数入力。空のときは送らない
`unit_count_operator`	`B-1` 不等号（`gte`=以上 / `lte`=以下）。台数指定時のみ必須
`chart_top_n`	SC-016 属性 `chart_top_n`（初期チェック件数の参照）
`highlight_kishu`	URL クエリ `kishu` が残っている場合のみ

レスポンス

項目	内容
成功時	IF-002 相当 JSON。`B-3`/`B-4` を描画
失敗時	`B-5` にエラーメッセージ表示
画面更新時の処理	ローディング → 成功時 `B-3`/`B-4` 更新、グラフチェックを初期状態にリセット、0件時 `B-5` 空状態

A-2 指標タブ切替

リクエスト

requestParam	本画面の値
なし	A-1 済みのレスポンスをクライアント保持

レスポンス

項目	内容
成功時	保持 JSON からタブに応じて `B-3` を再ソート。`B-4` は A-5/A-6 の状態を維持
失敗時	なし（クライアントのみ）
画面更新時の処理	ソートキーのみ切替。グラフチェック状態は機種名キーで保持

A-3 初回表示

リクエスト

requestParam	本画面の値
なし	URL / SC 属性から `B-1` を初期化のみ

レスポンス

項目	内容
成功時	フォーム初期値反映
失敗時	不正クエリは無視しデフォルトへフォールバック
画面更新時の処理	A-4 の条件を満たせば続けて A-1 を実行

A-4 ディープリンク初回自動検索

hall かつ（target_day または period_start+period_end）が有効なとき、DOMContentLoaded 後に A-1 を自動実行。kishu があれば B-6 を適用（行ハイライト + グラフチェック ON）。旧 day パラメータも読み取りのみサポート。

リクエスト

requestParam	本画面の値
（A-1 同様）	`B-1` 初期化後のフォーム値

レスポンス

項目	内容
成功時	A-1 成功 + B-6 ハイライト
失敗時	B-5 エラー表示（手動再検索可能）
画面更新時の処理	該当行 scrollIntoView（任意）

A-5 グラフチェック切替

リクエスト

requestParam	本画面の値
なし	`B-3` チェックボックスの ON/OFF

レスポンス

項目	内容
成功時	保持 JSON の `daily_series_by_kishu` から ON 機種のみ B-4 再描画
失敗時	なし
画面更新時の処理	Chart.js 系列を即時更新（API 再取得なし）

A-6 折れ線グラフ種別切替

リクエスト

requestParam	本画面の値
なし	B-4 の累計 / 単日切替 UI

レスポンス

項目	内容
成功時	累計 → `cumulative_samai`、単日 → `daily_samai` で B-4 再描画
失敗時	なし
画面更新時の処理	Y 軸ラベル・系列データを切替（API 再取得なし）

A-7 ランキング「さらに読み込む」

リクエスト

requestParam	本画面の値
なし	A-1 済みのレスポンスをクライアント保持

レスポンス

項目	内容
成功時	保持 JSON から B-3 を +10 行追加表示（API 再取得なし）
失敗時	なし
画面更新時の処理	初期 10 行 → ボタン押下で +10 行（全件まで）

外部インターフェース

画面 URL

項目	値
URL	WordPress 固定ページのパーマリンク（例: `/period-kishu-ranking/`）。テンプレート: `myCustom/myTemplate/page-period-kishu-samai-ranking-template.php`
種別	公開画面
権限	不要（公開ページ）

admin-ajax

endpoints

画面設計書

同一管理画面リクエスト

PUB-005 期間機種別差枚ランキング

概要

ワイヤーフレーム

画面仕様

ブロック一覧

検索フォーム（B-1）— 台数フィルタ

指標の定義

グラフ列チェックボックス（B-3）

折れ線グラフ（B-4）

ディープリンク（URL クエリ）

日別記事からのリンク（実装フェーズ）

処理連携仕様

A-1 検索フォーム送信

A-2 指標タブ切替

A-3 初回表示

A-4 ディープリンク初回自動検索

A-5 グラフチェック切替

A-6 折れ線グラフ種別切替

A-7 ランキング「さらに読み込む」

外部インターフェース

画面 URL

関連設計書

種別	参照
ショートコード	SC-016
Presentation DTO	IF-002
REST	API-001-15
リンク元	PUB-003 ランキング、SC-009

endpoints

PUB-005 期間機種別差枚ランキング ​

概要 ​

ワイヤーフレーム ​

画面仕様 ​

ブロック一覧 ​

検索フォーム（B-1）— 台数フィルタ ​

指標の定義 ​

グラフ列チェックボックス（B-3） ​

折れ線グラフ（B-4） ​

ディープリンク（URL クエリ） ​

日別記事からのリンク（実装フェーズ） ​

処理連携仕様 ​

A-1 検索フォーム送信 ​

A-2 指標タブ切替 ​

A-3 初回表示 ​

A-4 ディープリンク初回自動検索 ​

A-5 グラフチェック切替 ​

A-6 折れ線グラフ種別切替 ​

A-7 ランキング「さらに読み込む」 ​

外部インターフェース ​

画面 URL ​

関連設計書 ​

PUB-005 期間機種別差枚ランキング

概要

ワイヤーフレーム

画面仕様

ブロック一覧

検索フォーム（B-1）— 台数フィルタ

指標の定義

グラフ列チェックボックス（B-3）

折れ線グラフ（B-4）

ディープリンク（URL クエリ）

日別記事からのリンク（実装フェーズ）

処理連携仕様

A-1 検索フォーム送信

A-2 指標タブ切替

A-3 初回表示

A-4 ディープリンク初回自動検索

A-5 グラフチェック切替

A-6 折れ線グラフ種別切替

A-7 ランキング「さらに読み込む」

外部インターフェース

画面 URL

関連設計書