Appearance
SC-028 機種別月別差枚推移グラフショートコード
概要
- 指定機種について、月ごとの台あたり平均差枚（主系列）と合計差枚・集計日数（tooltip）を Chart.js で表示する（既定はグループ棒、
type="line"で折れ線）。 - 属性を
KishuMonthlySamaiGraphConverterでバリデーション・DTO 変換後、KishuMonthlySamaiGraphController→KishuMonthlySamaiGraphService経由で日次データを取得し、Service 内で月×ホール集計して View（Twig + JS）で描画する。 - データ取得は
DailyDataPerUnitRepository::select_daily_data_group_by_day_and_hall_and_kishu_by_ymd()を再利用する（新規 SQL なし）。
ワイヤーフレーム
本番 UI は kishu_monthly_samai_graph.twig（タイトル＋機種名＋グラフ canvas）に対応する。
ブロック一覧
| ブロックID | ブロック名 | 表示内容 | 初期値 | ユーザー操作 | アクション |
|---|---|---|---|---|---|
B-0 | コンテナ | .kishu-monthly-samai-graph 全体枠 | 常時表示 | なし | - |
B-1 | タイトル | title（未指定時は「{機種名} 月別差枚推移」） | 常時表示 | なし | - |
B-2 | 機種ラベル | 解決済み機種名 | 常時表示 | なし | - |
B-3 | チャート | 月別系列（系列=ホール）。軸値は台あたり平均差枚。type で棒/線 | データあり時 | なし | tooltip |
表示条件・注記
- 属性:
kishuまたはkishu_id（排他・いずれか必須）、months必須。halls/title/typeは任意。 - データ無し: no-data メッセージ表示。
- tooltip: 台あたり平均（主）、合計差枚、集計日数。欠損月は「データなし」。
外部インターフェース
ショートコードタグ
- タグ名:
[kishu_monthly_samai_graph] - 入力例:
[kishu_monthly_samai_graph kishu="化物語" halls="espasu" months="2026-03,2026-04,2026-05" type="line" title="化物語 月別差枚推移"]
属性一覧
| 属性 | 役割 | 必須 |
|---|---|---|
kishu | 機種名（マスタ解決。kishu_id と排他） | △ |
kishu_id | 機種マスタ ID（正の整数。kishu と排他） | △ |
halls | ホール slug または日本語名（カンマ区切り）。省略時は日別記事対象ホール | - |
months | 対象月（YYYY-MM カンマ区切り、最大12件、昇順正規化） | ○ |
title | グラフタイトル（省略時は「{機種名} 月別差枚推移」） | - |
type | bar（既定） / line | - |
kishu / kishu_id はいずれか一方が必須（同時指定不可）。
集計仕様
日次行（diff_coin / count）を (月 × ホール) で集約する。
| 指標 | 式 |
|---|---|
| 合計差枚 | Σ diff_coin |
| 集計台数合計 | Σ count |
| 台あたり平均 | round(合計差枚 / 集計台数合計, 1)（分母0のとき 0） |
| 集計日数 | データがある日付（Y-m-d）のユニーク数 |
系列の値は台あたり平均。tooltip に合計差枚・集計日数を併記する。欠損月は null（棒/点なし）。
エラー
| 条件 | ユーザー向け挙動 | メッセージ / ログ |
|---|---|---|
kishu と kishu_id を同時指定 | ErrorHandler の返す文言 | KishuMonthlySamaiGraphMessages::KISHU_XOR |
| いずれも未指定 | ErrorHandler の返す文言 | KishuMonthlySamaiGraphMessages::KISHU_REQUIRED |
months 未指定・形式不正・件数超過 | ErrorHandler の返す文言 | KishuMonthlySamaiGraphMessages::MONTHS_* |
halls に不正値 | ErrorHandler の返す文言 | KishuMonthlySamaiGraphMessages::HALL_INVALID |
type が許容外 | ErrorHandler の返す文言 | KishuMonthlySamaiGraphMessages::TYPE_INVALID |
| 機種名/ID がマスタに解決できない | ErrorHandler の返す文言 | KishudataKishuResolver 由来の ValidationException |
| 該当データなし | no-data 段落 | KishuMonthlySamaiGraphMessages::NO_DATA |
コントローラー・サービスの \Exception | ErrorHandler の返す文言 | ErrorHandler::handle_error() 経由 |
更新不可とみなすもの（git管理外の内容に依存し、リポジトリだけでは追従できない依存）
- ショートコード名
kishu_monthly_samai_graphを変更しない- 理由: 投稿本文・有料記事コメント欄にショートコードタグが直書きされるため
- 属性名
kishu/kishu_id/halls/months/title/typeを変更しない- 理由: 同上