SC-015 機種台数変化一覧ショートコード

概要

• 指定期間・ホールにおいて、db_daily_article_kishu_count_delta に登録された台数前日比変化を一覧表示する。
• period_start・period_end（期間）・hall（ホール名）を属性で受け取り、KishuCountDeltaListConverter でバリデーション・DTO 変換後、KishuCountDeltaListController → KishuCountDeltaListService 経由でデータを取得、Twig で HTML にレンダリングする。
• 期間は最大 366 日（period_start ≤ period_end かつ差が 366 日以内）。SC-010 と同型。
• 表示対象は 変化検出済み行のみ（count_delta_vs_previous_day !== 0 で DB に存在する行）。前後同数・前日ホール欠損は行が無いため表示されない。新台・撤去（-N）・既存機種の増減は登録・表示される（機種台数変化バッチ 参照）。
• 新台マーク: db_new_machine_info に非表示でない行が存在する機種に表示。kishu_id 紐付け済みは ID 一致、未紐付けは machine_name と機種マスタ表示名の一致で判定する。

ワイヤーフレーム

同一 UI は PUB-001 の P-16（RecentKishuReplacementBlock）とブロック層で共有する。

ブロック一覧

ブロックID	ブロック名	表示内容	初期値	ユーザー操作	アクション
B-0	機種台数変化一覧	日付・機種名（新台マーク）・前日比テーブル＋「さらに表示」（layout=single）	変化検出済み行があるときのみ	さらに表示	-

表示条件・注記

• 属性: period_start / period_end / hall 必須。layout は任意（未指定時 single）。
• layout=single: 初期 3 件。「さらに表示」で超過行を展開（本ワイヤーの主サンプル）。
• layout=merged: ホール列×N・折りたたみなし。本サンプル外（有料記事 #6）。
• 0 件: 空状態メッセージ（Messages::KISHU_COUNT_DELTA_LIST_NO_DATA）。
• 新台マーク: db_new_machine_info に非表示でない行が存在する機種に表示。
• 強調: |前日比| ≧ 10 のセルは強調（本サンプルの +12）。
• 実装参照: Twig core_src/View/templates/kishu_count_delta_list/kishu_count_delta_list.twig。mockup mockups/KishuCountDeltaListWireframe/ / RecentKishuReplacementBlock。

外部インターフェース

ショートコードタグ

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

属性一覧

属性	役割	必須
period_start	集計開始日（YYYY-MM-DD / YYYY/MM/DD / YYYYMMDD 形式、2020年〜当年）	○
period_end	集計終了日（同上、period_start 以降かつ 366 日以内）	○
hall	対象ホール名（HallEnum 対応）。layout=merged 時はカンマ区切りで複数指定可	○
layout	表示レイアウト。未指定時 single（既定）。有料記事 #6 では merged	-

出力（layout 未指定または single）

列	内容
日付	period_key（表示は n/j 形式・年なし、例: 6/15）
機種名	kishu。db_new_machine_info に登録されている機種は「新台」マークを機種名の隣に表示
前日比	符号付き差分（例: +2台）

• ソート: period_key DESC → 前日比の絶対値 DESC → kishu ASC（View 層で並べ替え）
• 前日比が 10 台以上（絶対値）のセルは強調表示
• 表示件数: 初期 3 件。4 件目以降は「さらに表示」ボタンで展開
• Issue #2847: 初期 SSR は先頭 3 行のみ。超過行は HTML に出さず excess JSON（application/json）からクライアント展開（.hidden-row による初期隠しは廃止）

出力（layout=merged）

列	内容
日付	period_key（n/j 形式）。同一ホール・同一機種の複数日統合時のみ改行（新しい日付が上）
機種名	kishu。db_new_machine_info に登録されている機種は「新台」マークを機種名の隣に表示
ホール列 × N	HallEnum::to_icon() を列ヘッダーに表示。符号付き差分（例: +2台）。該当ホールに変化がなければ -

• 同一 kishu の複数日変化は、変化があるホールが 1 つのときのみ 1 行に統合する（日付列・該当ホール列を改行表示、新しい日付が上）
• 変化があるホールが複数にまたがる場合は、従来どおり (period_key, kishu) ごとに 1 行（同一日・同一機種はホール列で統合）
• ソート: 行の最新 period_key DESC → 行内の最大 |前日比| DESC → kishu ASC
• ホール列の前日比が 10 台以上（絶対値）の行は強調表示
• 折りたたみなし（全行表示）
• テーブル直下にアイコンとホール名の注釈を表示（HallEnum::to_japanese()）

共通

• 0 件: 空状態メッセージ（Messages::KISHU_COUNT_DELTA_LIST_NO_DATA）
• 読取上限: 2000 行（超過時は先頭 2000 行のみ表示。Repository 定数で制御）

エラー

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

利用元

画面	処理番号	呼び出しパターン	備考
PUB-001 日別記事（シングル）	P-16	[kishu_count_delta_list period_start="YYYY-MM-DD" period_end="YYYY-MM-DD" hall="…"]	period_end = 考察日、period_start = 考察日 − 6 日（直近 7 日間）。各ホールブロック内で常時出力。配置は P-9 の後・P-10 の前。セクション見出しは「最近の台入れ替え」（Issue #2251）

日別記事テンプレートからの呼び出し例（考察日が 2026-06-05、ホールが アイランド秋葉原 の場合）:

[kishu_count_delta_list period_start="2026-05-30" period_end="2026-06-05" hall="アイランド秋葉原"]

• テーブル列（日付・機種名・前日比）は SC-015 の出力仕様どおり。意味的には入れ替え日・機種・増減台数に対応する。
• 0 件時は KishuCountDeltaListMessages::NO_DATA を表示する。

今後の更新で崩してはいけないところ（互換性契約）

公開契約（Breaking change 扱い）

• ショートコード名 kishu_count_delta_list を変更しない
• 属性名 period_start / period_end / hall を変更しない