SC-010 期間差枚サマリーショートコード

概要

• 指定期間・ホール・機種の合計差枚数・台毎平均・集計台数をページ内に表示する。
• period_start・period_end（期間）・hall（ホール名）・kishu（機種名）を属性で受け取り、PeriodSamaiSummaryConverter でバリデーション・DTO 変換後、PeriodSamaiSummaryController → PeriodSamaiSummaryService 経由でデータを取得、View で HTML にレンダリングする。
• 期間は最大 366 日（period_start ≤ period_end かつ差が 366 日以内）。

ワイヤーフレーム

本番 UI は period_samai_summary.twig（キャプション＋機種／合計／平均／集計台数テーブル）に対応する。

ブロック一覧

ブロックID	ブロック名	表示内容	初期値	ユーザー操作	アクション
B-0	コンテナ	.period-samai-summary 全体枠	常時表示	なし	-
B-1	キャプション	ホールアイコン／期間ラベル（hall / period_label）	常時表示	なし	-
B-2	サマリー表	機種・合計差枚数・台毎平均・集計台数の 1 行テーブル	データあり時	なし	-

表示条件・注記

• 属性: period_start / period_end / hall / kishu 必須。期間最大 366 日。
• データ無し: no-data メッセージ表示。
• ワイヤーフレーム: データありの通常ケースをサンプル表示。
• B-1 / B-2 分割: ブロック識別のためキャプション（本番は <table><caption>）を table 外に配置している。DOM 忠実度より B-* 分割を優先。

外部インターフェース

ショートコードタグ

• タグ名: [period_samai_summary]
• 入力例: [period_samai_summary period_start="20240101" period_end="20240131" hall="アイランド秋葉原" kishu="犬夜叉"]

属性一覧

属性	役割	必須
period_start	集計開始日（YYYY-MM-DD / YYYY/MM/DD / YYYYMMDD 形式、2020年〜当年）	○
period_end	集計終了日（同上、period_start 以降かつ 366 日以内）	○
hall	対象ホール名（HallEnum 対応）	○
kishu	対象機種名（単一機種名）	○

エラー

条件	ユーザー向け挙動	メッセージ / ログ
period_start / period_end 未指定または空	ErrorHandler の返す文言	ValidationException（Messages::VALIDATION_DATE_REQUIRED）
日付が不正な形式・範囲外	ErrorHandler の返す文言	ValidationException（Messages::VALIDATION_DATE_INVALID_*）
period_start > period_end	ErrorHandler の返す文言	ValidationException（PeriodSamaiSummaryMessages::PERIOD_ORDER）
期間が 366 日超	ErrorHandler の返す文言	ValidationException（PeriodSamaiSummaryMessages::PERIOD_MAX_DAYS）
hall 未指定または不正値	ErrorHandler の返す文言	ValidationException（HallEnum 照合失敗）
kishu 未指定または空	ErrorHandler の返す文言	ValidationException（PeriodSamaiSummaryMessages::KISHU_REQUIRED）
コントローラー・サービスの \Exception	ErrorHandler の返す文言	ErrorHandler::handle_error() 経由

更新不可とみなすもの（git管理外の内容に依存し、リポジトリだけでは追従できない依存）

• ショートコード名 period_samai_summary を変更しない
  • 理由: 既存投稿本文にショートコードタグが直書きされているため
• 属性名 period_start / period_end / hall / kishu を変更しない
  • 理由: 既存投稿本文に属性名が直書きされているため