SC-023 機種増台前後差枚比較ショートコード

概要

• 指定ホール・機種・対象期間について、対象期間全体 / 増台前 / 増台後 の累計差枚・台毎平均差枚・延べ台数を1表で比較表示する。
• 有料記事固定セクション #6（増台・減台の結果）で、台数変化一覧（SC-015）のあとに機種別結果として利用する。
• 集計は既存 SC-010 相当の PeriodSamaiSummaryService を期間分割して再利用する。
• 属性を受け取り、Converter でバリデーション・DTO 変換後、Controller → Service 経由でデータを取得し、View（Twig）で HTML にレンダリングする。

ワイヤーフレーム

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

ブロック一覧

ブロックID	ブロック名	表示内容	初期値	ユーザー操作	アクション
B-0	比較テーブル	期間行（全体／増台前／増台後）× 累計差枚・平均差枚・台数	全体期間にデータあり	なし	-
B-1	0 件メッセージ	対象期間全体に該当データなしのときの文言	全体が 0 件のとき	なし	-
B-2	期間注記	表直下に各行の集計期間を小さくグレーで列挙	period_label あり	なし	-

表示条件・注記

• 属性: hall / kishu / period_start / period_end / change_date 必須。before_period_start は任意。
• 増台前が空: change_date の前日が before_period_start より前になるとき（増台前期間が成立しない場合）、増台前行は「—」。
• 増台前の開始: before_period_start を指定。未指定時は対象期間（period_start の属する月）の 前暦月1日（例: period_start=20260801 → 既定 20260701）。
• テンプレートパス: Twig core_src/View/templates/kishu_count_change_samai_summary/kishu_count_change_samai_summary.twig。

外部インターフェース

ショートコードタグ

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

  [kishu_count_change_samai_summary hall="アイランド秋葉原" kishu="ソードアート・オンラインⅡ" period_start="20260801" period_end="20260831" change_date="20260803" before_period_start="20260701"]

属性一覧

属性	役割	必須
hall	対象ホール名（HallEnum 対応の日本語名またはスラッグ）	○
kishu	対象機種名（表示名。SC-010 と同じ方針）	○
period_start	対象期間の開始日（YYYYMMDD / YYYY-MM-DD / YYYY/MM/DD）	○
period_end	対象期間の終了日（同上、period_start 以降・366 日以内）	○
change_date	増台（台数変化）日。period_start〜period_end の範囲内であること	○
before_period_start	増台前集計の開始日（同上形式）。未指定時は period_start の前暦月1日。指定時は change_date より前であること・増台前期間は366日以内	×

集計仕様

項目	内容
対象期間全体	period_start〜period_end を SC-010 相当で集計
増台前	before_period_start（未指定時は前暦月1日）〜change_date の前日。期間が成立しない場合は「—」
増台後	change_date〜period_end
累計差枚	SC-010 total_coins と同定義
平均差枚	SC-010 avg_coins_per_unit と同定義（台毎平均）
台数	SC-010 aggregated_count（延べ台数）と同定義
データ取得	PeriodSamaiSummaryServiceInterface::get_summary を期間ごとに呼ぶ

表示仕様

列	内容
期間	「対象期間全体」「増台前」「増台後」の行ラベルのみ
累計差枚	数値＋枚。差枚水準クラス。データ無しは「—」
平均差枚	小数第 1 位＋枚。データ無しは「—」
台数	延べ台数＋台。データ無しは「—」

各行の集計期間（YYYY-MM-DD〜YYYY-MM-DD）は表直下に小さくグレー文字で「行ラベル：期間」形式で列挙する（period_label が無い行は出さない）。

見た目は period_samai_summary / kishu_event_samai_summary と同系のパネル枠・ヘッダー背景を用いる。

有料記事 #6 連携方針

ブロック	連携先	内容
台数変化一覧	SC-015	従来どおり layout=merged
機種別結果	SC-023 × N	選択機種（または kishu_list）ごとに月間／増台前／増台後を1表表示

• 変化日: 管理画面の result_period_start（未入力時は対象月 period_start）を change_date に渡す。SC-015 の機種ごと最古 period_key を自動解決する拡張は将来課題とし、当面はメタの結果集計開始日を用いる。
• 期間: 対象月の period_start〜period_end。

エラー

条件	ユーザー向け挙動	メッセージ / ログ
hall 未指定または不正	ErrorHandler の返す文言	Validation
kishu 未指定または空	ErrorHandler の返す文言	Validation
period_* / change_date 未指定・形式不正・順序不正	ErrorHandler の返す文言	Validation
before_period_start 形式不正（任意。未指定は前暦月1日）	ErrorHandler の返す文言	Validation
change_date が対象期間外	ErrorHandler の返す文言	Validation
明示指定の before_period_start が change_date 以降、または増台前が366日超	ErrorHandler の返す文言	Validation
対象期間全体にデータなし	段落テキスト	no-data 定数
コントローラー・サービスの \Exception	ErrorHandler の返す文言	ErrorHandler

更新不可とみなすもの

• ショートコード名 kishu_count_change_samai_summary を変更しない
• 属性名 hall / kishu / period_start / period_end / change_date / before_period_start を変更しない（before_period_start は任意属性として追加）