日別記事まわりの raw データと summary テーブル

目的

日別記事画面や関連機能では、台別の実績（raw）に加え、機種単位の合計・平均・順位などの集計結果が必要になる。Issue #2071 で整理したとおり、長期的には SQL や運用ツールから列単位で参照できる形への整理が望ましい。

本ドキュメントは、そのうち Issue #2072 で導入した 対象日（単一日付）単位の機種別サマリ用テーブルの位置づけと、既存ストレージとの関係を示す。集計の更新フローは Issue #2074。過去日の一括バックフィルやフロント表示の計算削除は別 Issue。

検索用（物理テーブル名・カンマ区切り）: db2023, slot_precomputed_ranking, db_daily_article_kishu_single_day_summary

データのレイヤ

レイヤ	代表テーブル / 保存形式	役割
台別 raw	db2023（DatabaseTableConstants::DAILY_DATA）	日×台×ホールの実績。アプリの一次ソースに近い粒度。
シリアライズ済みプレゼン載せ	slot_precomputed_ranking（DatabaseTableConstants::PRECOMPUTED_RANKING）	日別記事の表示短絡用。payload に PHP serialize() 済み DTO（Issue #2042）。画面表示には十分だが、列指向の分析には向かない。
機種別サマリ（列指向・単一日付スコープ）	db_daily_article_kishu_single_day_summary（DatabaseTableConstants::DAILY_ARTICLE_KISHU_SINGLE_DAY_SUMMARY）	対象日（period_key、DATE 型。アプリは日次キーをカレンダー日付に正規化して格納）・ホール・機種をキーに、台数・平均差枚・合計差枚・順位・平均回転などを列として保持（Issue #2072）。1行は単一の対象日に属する。命名は summary を主語とし、テーブル名に ranking を含めない。物理名の single_day は単一日付スコープを示す。

db_daily_article_kishu_single_day_summary のスキーマ概要

• キー: hall, period_key（対象日、DATE 型）, kishu（台別 raw と同系の機種名文字列）
• 指標列: `count`（台数。DailyDataGroupByKishuTitleDto::count と同一ソース。MySQL では予約語のためバッククォート付きで定義）、avg_samai, total_samai, avg_samai_rank, avg_kaiten, total_samai_rank（Issue #2074 のパイプラインで、台別 raw の機種別集計から算出して投入。インストール直後や対象日にデータが無いホールでは行が無い、またはインポート後に空クリアされる）
• メタ: created_at（インポート・Cron による hall×対象日の 全置換（DELETE 後 INSERT）のたびに新規行として付く時刻。SQL の UPDATE は行わないため updated_at は CREATE 定義に含めない。スキーマ変更は DailyArticleKishuSummaryInstaller の DB バージョンと dbDelta で段階的に反映する。別途 computed_at は持たない）

詳細な列定義の正本は docs/design/テーブル定義/custom-tables.dbml の Table db_daily_article_kishu_single_day_summary および DailyArticleKishuSummaryInstaller を参照。

集計の更新タイミングと役割分担（Issue #2074）

処理	保存先	タイミング	役割
PrecomputedRankingComputer	slot_precomputed_ranking	slot_kouryaku_daily_data_imported・PrecomputedRankingCronScheduler Cron	日別記事表示用に シリアライズ済みプレゼン DTO を書き込む（Issue #2042）。
DailyArticleKishuSingleDaySummaryComputer	db_daily_article_kishu_single_day_summary	同上フック（直列に実行）・同上 Cron（Precomputed ハンドラの次に実行）	列指向の機種別サマリ（台数・平均差枚・合計差枚・順位・平均回転）を、台別 raw と同じ集計 SQL（DailyDataPerUnitRepository::select_daily_data_group_by_day_and_hall_and_kishu）から算出して hall×対象日スコープで全置換（DELETE 後 INSERT）。

二重計算の扱い: 両方とも同じ raw（db2023）から派生するが、保存形式と用途が異なる（プレゼン用 blob と分析用の正規化列）。同一テーブルへの二重書き込みは行わない。Cron の再スケジュール・イベントモデル移行は PrecomputedRankingHookRegistrar に一本化し、サマリー側 Cron ハンドラは再計算のみ行う。

将来の利用例（予定）

• 誕生日・機種ピックアップ等: 台別 raw を都度スキャンせず、対象日・ホールを絞った db_daily_article_kishu_single_day_summary を参照して機種単位の並びを得る（実装は別 Issue）。
• BI / 検証: SELECT・WHERE で列参照可能なため、phpMyAdmin 等での可読性が payload 保存より高い。

関連 Issue

• #2071 — 永続化形式の見直し（親 Epic）
• #2072 — summary 用テーブル作成・ドキュメント（本テーブルの Installer・定数・DBML）
• #2074 — 台別データ投入フック／Cron からサマリー行を計算・全置換するパイプライン