IF-002 期間機種別差枚ランキング Presentation DTO

一覧・折りたたみサマリー: IF-一覧

概要

PUB-005 期間機種別差枚ランキング / SC-016 を表示するための DTO。
PHP → Twig / REST JSON の境界契約。REST の JSON 形状は本 IF を正とする（API-001-15 が返却）。

データ構造（概要）

DTO	受け取る内容の概要
`PeriodKishuSamaiRankingPresentationDto`（ルート）	集計期間・ホール、ランキング行一覧、機種別日次系列、グラフ設定
`PeriodKishuRankingRowDto`	1機種の期間集計（合計・平均・集計台数・終了日台数）
`DailyCumulativePointDto`	1日分の日次合計差枚と累計差枚（A-6 単日/累計切替に使用）

ルート（PeriodKishuSamaiRankingPresentationDto）

フィールド	型	主な用途
`hall`	string	対象ホール（日本語名）
`period_start`	string (`YYYY-MM-DD`)	集計開始日
`period_end`	string (`YYYY-MM-DD`)	集計終了日
`ranking_rows`	`PeriodKishuRankingRowDto[]`	ランキング表（B-3）
`daily_series_by_kishu`	`array<string, DailyCumulativePointDto[]>`	折れ線グラフ用系列（B-4。全 ranking 行分）
`chart_top_n`	int	初期グラフチェック ON 件数（SC-016 属性）
`highlight_kishu`	string \| null	ハイライト機種（B-6。未指定時 null）

PeriodKishuRankingRowDto

フィールド	型	説明
`kishu`	string	機種名
`total_samai`	int	期間合計差枚（`diff_coin` 合計）
`avg_samai`	float	期間平均差枚（台あたり、小数1桁表示）
`aggregated_count`	int	期間内集計台数（日次 count の合計）。B-3「集計台数」列に表示
`count_on_period_end`	int	`period_end` 当日の当該機種台数。台数フィルタ判定および参考表示

ソートはクライアント側タブに応じて total_samai または avg_samai 降順。DTO 配列は両キーを常に含む。

DailyCumulativePointDto

フィールド	型	説明
`date`	string (`YYYY-MM-DD`)	日付
`daily_samai`	int	当該日の合計差枚（データ無し日は 0）
`cumulative_samai`	int	期間開始から当該日までの累計差枚

A-6 単日差枚 モード: Y 軸に daily_samai を使用。
A-6 累計差枚 モード: Y 軸に cumulative_samai を使用。

グラフ系列の返却ルール

daily_series_by_kishu は 台数フィルタ適用後の全 ranking_rows について返す（最大 ranking_limit 件）。
サーバー側で top N のみ返却する選定は 行わない。B-4 に描画する系列はクライアントのグラフチェック（A-5）で決定する。
chart_top_n は A-1 成功時の初期チェック ON 件数 の参照値としてレスポンスに含める。
期間内の全日付について DailyCumulativePointDto を返す（データ無し日は daily_samai: 0、累計は前日累計 + 0）。

台数フィルタ（サーバー側）

unit_count + unit_count_operator が指定されたとき、count_on_period_end で行を除外する。

operator	意味	条件
`gte`	以上	`count_on_period_end >= unit_count`
`lte`	以下	`count_on_period_end <= unit_count`

関連設計書

種別	参照
公開画面	PUB-005
REST	API-001-15
ショートコード	SC-016