Appearance
API-001-15 期間機種別差枚ランキング取得
概要
PUB-005 期間機種別差枚ランキング / SC-016 のフォーム送信・ディープリンク初回自動検索（A-1 / A-4）で、期間・ホール・台数条件に応じた機種別ランキングと日次系列 JSON を返す。契約は IF-002 を正とする。
入力（リクエスト）
| param | 必須 | 型・制約 | 説明 |
|---|---|---|---|
period_start | はい | 非空。YYYY-MM-DD / YYYY/MM/DD / YYYYMMDD。2020年〜当年 | 集計開始日 |
period_end | はい | 同上。period_start 以降かつ 366 日以内 | 集計終了日 |
hall | はい | 非空。HallEnum 対応の日本語ホール名 | 対象ホール |
unit_count | 任意 | 整数 ≧ 0。未指定時フィルタなし | 終了日台数フィルタ閾値 |
unit_count_operator | 任意 | gte（以上） / lte（以下）。unit_count 指定時は 必須 | 終了日台数の不等号 |
chart_top_n | 任意 | 整数 1〜10。未指定時 5（SC-016 属性 chart_top_n をサーバー側で参照可） | クライアント初期グラフチェック ON 件数 |
highlight_kishu | 任意 | 非空文字列 | ハイライト機種名（URL クエリ kishu からマッピング） |
台数フィルタ
- 判定に使う台数は
period_end当日 の当該機種台数（count_on_period_end）。 unit_count未指定時は台数フィルタを適用しない。unit_count指定時にunit_count_operator未指定 → 400 バリデーションエラー。
出力（レスポンス）
成功時 data
IF-002 の PeriodKishuSamaiRankingPresentationDto 相当。
| field | 型 | 説明 |
|---|---|---|
success | boolean | 常に true |
hall | string | 対象ホール |
period_start | string | YYYY-MM-DD |
period_end | string | YYYY-MM-DD |
ranking_rows | array | PeriodKishuRankingRowDto[]（フィルタ後） |
daily_series_by_kishu | object | 機種名 → DailyCumulativePointDto[]（全 ranking 行分） |
chart_top_n | int | 適用された初期チェック ON 件数 |
highlight_kishu | string | null | 反映されたハイライト機種（未指定時 null） |
HTTP ステータス: 200
0 件の場合も success: true とし、ranking_rows: [] / daily_series_by_kishu: {} を返す（空状態はクライアント B-5 で表示）。
失敗・エラー条件
| 条件 | レスポンス形式 |
|---|---|
| バリデーションエラー | { "success": false, "error": { "message": "..." } }（400） |
| nonce 不正 / レート制限超過 | WordPress REST 標準（403 等） |
| サーバー内部エラー | { "success": false, "error": { "message": "..." } }（500） |
権限・nonce
名前空間共通事項は API-一覧 を参照。本エンドポイントは API-001-14 等と同様、AsyncLoadingHandler + WordPressAsyncLoadingPermissionChecker（nonce + IP レート制限）を使用する。差分はなし（共通のみ）。
データ源
DailyDataPerUnitRepositoryInterface::select_daily_data_group_by_day_and_hall_and_kishu_by_ymdによりDailyDataGroupByKishuTitleDtoを取得し、期間・ホールでフィルタ後に機種単位で集約する（SC-010 / PeriodSamaiSummaryService と同系）。count_on_period_endはperiod_end日のDailyDataGroupByKishuTitleDto.count（データ無し日は 0）。
処理順序
- 期間・ホールで機種集計
- 各機種の
count_on_period_endを算出 unit_count+ operator 指定時、該当行を除外- 残りを
ranking_rowsおよびdaily_series_by_kishuとして返却