Issue #2070 設計: 新台入れ替え時の台数変化（前日比の永続化）

目的

新台入れ替えなどで、**同一ホール・同一機種名キー（kishu）について「台数（count）が前日からどう変わったか」**を後続の画面やテンプレートから参照できるようにする。親 Issue の方針どおり、サマリ再計算時に前日との差分を算出し、専用テーブルに保存する。

登録方針: 台数に変化があった場合のみ行を保存する（count_delta !== 0）。前後同数は行を持たない。前日ホール欠損（カレンダー前日に当該ホールのサマリが1件も無い）ときのみ delta を作らない。

本ドキュメントは 設計の正本（スキーマ・PHP 実装は #2109 / 表示は #2110）。

DBML 正本への反映

差分データはリポジトリ正本の custom-tables.dbml 内 Table db_daily_article_kishu_count_delta に定義する。db_daily_article_kishu_single_day_summary には前日比列を持たない。

日別記事メタ系サブセットは npm run docs:generate-dbml-subsets で正本から再生成する。

関連 Issue

種別	Issue
親（要件）	#2070
子: データ層・管理画面	#2109
子: 表示	#2110
テーブル導入	#2072
フック連携	#2074
バックフィル	#2075
summary 参照の読み経路	#2076

現状のデータフロー

• サマリテーブル: db_daily_article_kishu_single_day_summary — 台数・差枚・順位（Issue #2072）
• 前日比テーブル: db_daily_article_kishu_count_delta — 変化検出時のみの符号付き差分
• 集計: DailyArticleKishuSingleDaySummaryComputer が raw からサマリ行を組み立て、前日 count と比較して変化行のみ delta テーブルへ書き込む
• トリガー: DailyArticleKishuSingleDaySummaryHookHandler（インポート / Cron）

前日の定義

• 比較基準日: period_key のカレンダー直前日（営業日スキップや「直近サマリ存在日」ではない）
• 比較キー: 同一 hall、同一 kishu
• 参照元: サマリテーブル上の (hall, period_key - 1 day, kishu) の `count`
• 前日ホール欠損: カレンダー前日に当該 hall のサマリが0件のときは delta を作らない
• 新台（初出 kishu）: 前日ホールにサマリ≥1件かつ当該 kishu の前日行なし → delta = +当日 count
• 撤去: 前日ホールにサマリ≥1件かつ前日 kishu あり・当日 raw なし → delta = -前日 count

保存する値

列	型	意味
count_delta_vs_previous_day	INT signed NOT NULL	既存機種は 当日 count − 前日 count、新台は +当日 count、撤去は -前日 count（登録時は 0 以外のみ）

登録条件（DB 行の有無）

算出結果	DB への登録
前日ホール欠損（前日サマリ0件）	行なし
前後同数（delta = 0）	行なし
台数変化あり（既存増減・新台・撤去、≠ 0）	行あり

0 と「行なし」: 前日行が存在し count = 0、当日 count = N のときは delta = N で登録。前後で台数が同じときは 行を作らない。

エッジケース

状況	前日行（同一 hall/kishu）	delta テーブル
通常・変化あり	あり	行あり（当日 − 前日）
前後同数	あり	行なし
新規導入（前日ホールサマリ≥1）	なし（当該 kishu）	行あり（+当日 count）
前日ホール欠損	ホール全体で前日サマリ0件	行なし
撤去（当日 raw に機種行なし）	あり（前日 summary に count あり）	行あり（-前日 count、count=0除く）

書き込みタイミング（再計算）

対象 (hall, period_key) ごとに:

1. サマリテーブルを従来どおり全置換（delta 列なし）
2. delta テーブルから当該 hall×日の行を すべて DELETE
3. delta !== 0 の kishu（既存増減・新台・撤去）を INSERT

管理画面（ADM-016）

誤検知の修正用。設定 → 機種台数変化（前日比）（slug: kishu-count-delta-admin）。

機能	内容
一覧	hall / period_key / kishu / count_delta / 更新日時。ホール・日付範囲・機種名でフィルタ
編集	count_delta_vs_previous_day を整数で修正（0 は不可 — 誤検知・「変化なしに直したい」場合は削除を利用）
削除	確認付き DELETE

再計算との関係: 次回のサマリ自動再計算時、当該 hall×日の delta 行はすべて差し替えされる。手動修正は消えうる（運用で再修正）。

スキーマ変更手順（Issue #2109）

1. custom-tables.dbml: summary から delta 列削除、新テーブル追加
2. custom-application-tables.md 一覧同期
3. npm run docs:generate-dbml-subsets
4. DailyArticleKishuCountDeltaInstaller（新規）
5. DailyArticleKishuSummaryInstaller: v4 で追加した列があれば DROP し v3 相当に戻す
6. DailyArticleKishuCountDeltaRepository / Computer 連携
7. 管理画面 ADM-016

下流（Issue #2110）

表示層は delta テーブルを参照（行が存在する機種＝変化あり）。summary 行への delta 埋め込みは行わない。

• 公開 UI: SC-015 機種台数変化一覧ショートコード（kishu_count_delta_list）

参照ファイル

• docs/design/テーブル定義/custom-tables.dbml
• core_src/Infrastructure/Database/DailyArticleKishuCountDeltaInstaller.php
• core_src/Service/daily_article_kishu_single_day_summary/DailyArticleKishuSingleDaySummaryComputer.php
• core_src/Model/Repository/daily_article_kishu_count_delta_repository/DailyArticleKishuCountDeltaRepository.php
• core_src/Admin/kishu_count_delta/KishuCountDeltaAdminPage.php