SC-020 イベント差枚サマリーショートコード

概要

• 指定ホール・イベント・期間について、イベント別の日平均差枚・日単位勝率・対象日付（日別記事リンク付き）を表形式で表示する。
• 任意のピックアップ期間を指定すると、ピックアップ期間と累計期間（period_start〜period_end）を横並びで比較できる。
• event=all のときは、期間内の db_Link_day.event JSON に出現したイベント名ごとに 1 行を出力する（db_event_master は行の根拠にしない）。
• 属性を受け取り、Converter でバリデーション・DTO 変換後、Controller → Service 経由でデータを取得し、View（Twig）で HTML にレンダリングする。
• 有料記事固定セクション #9（イベント別成績）で利用する（生成属性は 固定セクション-ショートコード対応表）。

ワイヤーフレーム

本設計では Markdown のブロック一覧・表示仕様で比較テーブルを定義する。React *WireframeReactHost は作成しない。

ブロック一覧

ブロックID	ブロック名	表示内容	初期値	ユーザー操作	アクション
B-0	比較テーブル	イベント行 ×（ピックアップ列群 + 累計列群）。ピックアップ未指定時は累計列のみ	データあり時	対象日リンククリック	日別記事へ
B-1	0 件メッセージ	該当イベント日なしのときの文言	対象日が 0 件のとき	なし	-

表示条件・注記

• 属性: hall / event / period_start / period_end 必須。pickup_period_start / pickup_period_end は任意（両方そろったときのみピックアップ列を表示）。
• ピックアップ期間: 累計期間の部分集合を想定。ピックアップ期間を指定した場合は、ピックアップ期間内に該当日があるイベントのみ行を表示する。累計列の集計対象は従来どおり累計期間全体とする。
• event=all: 累計期間内に出現したイベントを 1 行ずつ。ピックアップ期間指定時は、さらにピックアップ期間内に該当日があるイベントに絞り込む。個別名指定時はそのイベントのみ。
• 0 件: 累計期間でも対象イベント日が無い場合、またはピックアップ期間指定時にピックアップ期間内の対象イベント日が無い場合は B-1。
• テンプレートパス: Twig core_src/View/templates/event_samai_summary/event_samai_summary.twig。

外部インターフェース

ショートコードタグ

• タグ名: [event_samai_summary]
• 入力例:

  [event_samai_summary hall="アイランド秋葉原" event="all" period_start="20250901" period_end="20260228" pickup_period_start="20260201" pickup_period_end="20260228"]

属性一覧

属性	役割	必須
hall	対象ホール名（HallEnum 対応の日本語名またはスラッグ）	○
event	イベント名、または all（期間内出現イベントを行分割）	○
period_start	累計期間の開始日（YYYYMMDD または互換形式）	○
period_end	累計期間の終了日（同上、period_start 以降）	○
pickup_period_start	ピックアップ期間の開始日（任意。指定時は pickup_period_end も必須）	—
pickup_period_end	ピックアップ期間の終了日（任意）	—

集計仕様

項目	内容
イベント日の抽出	LinkDayRepository::select_by_date_range で累計期間の db_Link_day を取得し、指定ホールの event JSON 配列からイベント名を抽出
行の根拠	Link_day 実データに出現したイベント名（マスタ未登録名も含む）。ピックアップ期間指定時は、ピックアップ期間内に開催実績があるイベント名のみ
ホール合計差枚	対象日×ホールの合計差枚（既存の日×ホール集計 Repository を流用）
平均差枚数（日平均）	対象イベント日のホール合計差枚の算術平均
勝率	日単位: ホール合計差枚 > 0 の日数 ÷ 対象日数
差枚未投入日	Link_day 上のイベント日でも日×ホール集計が無い場合は 差枚 0・非勝ち として平均・勝率の分母に含める（実差枚 0 日と同扱い）
対象日付	対象日のラベル一覧。各日は日別記事 URL（db_Link_day.url + #hall、DailyArticleLinkUtil）。差枚未投入日も url があれば出す
並び順	イベント名の辞書順（実装時に変更する場合は本設計を更新）

表示仕様（比較テーブル）

列（ピックアップあり）	内容
イベント名	イベント名文字列
ピックアップ期間列	ヘッダーは期間（n/j / 〜n/j の縦並び）。セルは平均差枚 → 勝率の縦並び
累計	同一セル内で縦並び: 平均差枚 → 勝率（累計期間）
対象日	先頭に件数（xx件）、続けて日付リンクを縦並び（新しい順・最大 3 件。超過時は ...）

ピックアップ未指定時は「イベント名 / 累計（平均差枚・勝率の縦並び） / 対象日」のみ。ピックアップ対象日列は出さない。

見た目は period_samai_summary と同系のパネル枠・ヘッダー背景（薄いグレー）を用いる。平均差枚には total-coin-* クラスで差枚水準に応じた背景色を付ける（colors.css の変数を利用）。table-layout: fixed で列幅を配分し、ピックアップあり時はイベント 24% / 差枚列各 28% / 対象日 20%（無し時はイベント 30% / 累計 48% / 対象日 22%）。平均差枚は white-space: nowrap で折り返さない。SP では字詰めも併用する。

エラー

条件	ユーザー向け挙動	メッセージ / ログ
hall 未指定または不正値	ErrorHandler の返す文言	ValidationException（HallEnum 照合失敗）
event 未指定または空	ErrorHandler の返す文言	ValidationException（必須属性）
period_start / period_end 未指定・形式不正・順序不正	ErrorHandler の返す文言	ValidationException（日付バリデーション）
ピックアップ属性の片方のみ指定	ErrorHandler の返す文言	ValidationException（ペア必須）
ピックアップが累計期間外（交差なし）	ErrorHandler の返す文言	ValidationException（期間整合）
該当データなし	段落テキスト	no-data メッセージ定数（実装時に定義）
コントローラー・サービスの \Exception	ErrorHandler の返す文言	ErrorHandler::handle_error() 経由

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

• ショートコード名 event_samai_summary を変更しない
  • 理由: 有料記事テンプレート生成がタグ名に依存するため
• 属性名 hall / event / period_start / period_end / pickup_period_start / pickup_period_end を変更しない
  • 理由: 有料記事 Generator および手動埋め込みが属性名に依存するため
• event=all の意味（全イベント日の 1 行合算ではなく、イベントごとの行分割）を変更しない
  • 理由: 有料記事 #9 の生成仕様がこの解釈を前提とするため