スロット攻略 プロジェクトドキュメント

Appearance

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 に非表示でない行が存在し、かつ導入日（release_date）が period_end の年月またはその 1 ヶ月前の機種に表示。kishu_id 紐付け済みは ID 一致、未紐付けは machine_name と機種マスタ表示名の一致で判定する。release_date が NULL（未定。旧 0000-00-00 は NULL 扱い）の行はマーク対象外。

ワイヤーフレーム ​

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

ブロック一覧 ​

ブロックIDブロック名表示内容初期値ユーザー操作アクション
B-0機種台数変化一覧日付・機種名（新台マーク）・前日比テーブル＋「さらに表示」（layout=single）変化検出済み行があるときのみさらに表示-
B-1台数変化一覧（merged）ホール列×N。折りたたみ時は増台行のみ。「すべて表示」で全件モーダル（layout=merged）変化検出済み行があるときのみすべて表示（減台があるとき）全件モーダル

表示条件・注記 ​

  • 属性: period_start / period_end / hall 必須。layout は任意（未指定時 single）。
  • layout=single: 初期 3 件。「さらに表示」で超過行を展開（本ワイヤーの主サンプル）。
  • layout=merged: ホール列×N。折りたたみ時は増台行のみ表示し、減台行があるとき「すべて表示」で全件モーダル（有料記事 #6）。増台 0 件・減台のみのときは全行表示でボタンなし。
  • 台数セルの背景色: 増台（正）はシアン系、減台（負）はアンバー系（日付・機種名セルは塗らない）。表下に増台／減台の凡例。
  • 0 件: 空状態メッセージ（Messages::KISHU_COUNT_DELTA_LIST_NO_DATA）。
  • 新台マーク: db_new_machine_info に非表示でない行が存在し、導入日が period_end の年月またはその前月の機種に表示（導入日未設定は対象外）。
  • 強調: |前日比| ≧ 10 のセルは太字（本サンプルの +12）。
  • 実装参照: Twig core_src/View/templates/kishu_count_delta_list/kishu_count_delta_list.twig / kishu_count_delta_list_merged.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。新台マーク条件を満たす機種は「新台」マークを機種名の隣に表示（導入日が period_end の月または前月）
前日比符号付き差分（例: +2台）
  • ソート: period_key DESC → 前日比の絶対値 DESC → kishu ASC（View 層で並べ替え）
  • 前日比が 10 台以上（絶対値）のセルは太字表示
  • 表示件数: 初期 3 件。4 件目以降は「さらに表示」ボタンで展開
  • 台数（前日比）セル背景: 増台（正）はシアン系、減台（負）はアンバー系

出力（layout=merged） ​

列内容
日付period_key（n/j 形式）。同一ホール・同一機種の複数日統合時のみ改行（新しい日付が上）
機種名kishu。新台マーク条件を満たす機種は「新台」マークを機種名の隣に表示（導入日が period_end の月または前月）
ホール列 × NHallEnum::to_icon() を列ヘッダーに表示。符号付き差分（例: +2台）。該当ホールに変化がなければ -
  • 同一 kishu の複数日変化は、変化があるホールが 1 つのときのみ 1 行に統合する（日付列・該当ホール列を改行表示、新しい日付が上）
  • 変化があるホールが複数にまたがる場合は、従来どおり (period_key, kishu) ごとに 1 行（同一日・同一機種はホール列で統合）
  • ソート: 行の最新 period_key DESC → 行内の最大 |前日比| DESC → kishu ASC
  • ホール列の前日比が 10 台以上（絶対値）の行は太字表示
  • 折りたたみ: いずれかのホール列に正の前日比がある行を増台行、変化がすべて負の行を減台行とする。増台行のみ初期表示し、減台行が 1 件以上あるとき「すべて表示（全N件）」で全件をモーダル表示（ホール差枚数ランキングと同型の .data-detail-modal）。増台が 0 件で減台のみのときは全行表示・ボタンなし
  • 台数セル背景: 各ホール列の前日比が正ならシアン系、負ならアンバー系（日付・機種名は塗らない）。テーブル直下に増台／減台の凡例
  • テーブル直下にアイコンとホール名の注釈を表示（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）
コントローラー・サービスの \ExceptionErrorHandler の返す文言ErrorHandler::handle_error() 経由

利用元 ​

画面処理番号呼び出しパターン備考
PUB-001 日別記事（シングル）P-16プレースホルダー + GET /async-kishu-count-delta-list（HTML 断片は本 SC と同じ Controller）日別記事では同期ショートコードを埋め込まない（Issue #2340）。period_end = 考察日、period_start = 考察日 − 6 日。standalone 利用は下記ショートコードのまま同期。

日別記事（PUB-001 P-16）: Twig は .kishu-count-delta-list-placeholder（data-hall / data-period-start / data-period-end）を SSR し、orchestrator が REST で HTML を差し込む。standalone / 手置きの同期ショートコード例:

[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 を変更しない