ADM-017 機種マスタ管理画面

概要

• db_kishu_master の一覧・新規登録・名称変更・統合（merge）・無効化・ヒートマップ略称・メーカー（maker_id）選択を行う専用管理画面。
• WordPress 設定サブメニューとして登録。操作はすべて 同一 URL への POST（リダイレクト＋クエリ通知）。admin-ajax は使用しない。
• rename / merge / 無効化は確認ダイアログ必須。merge 実行前に影響件数プレビュー（ドライラン）を表示できる。
• メーカーは db_maker_master を参照する（ADM-031）。未設定は空選択（maker_id NULL）。

外部インターフェース

管理画面 URL

項目	値
URL	/wp-admin/options-general.php?page=kishu-master-admin
メニュー名	機種マスタ
権限	manage_options

フォーム POST（同期 CRUD / merge）

POST options-general.php?page=kishu-master-admin。

kishu_master_action 値	処理
add	新規登録（upsert_by_names、重複は uk_name で拒否）
rename	名称変更（update_name、確認ダイアログ必須）
deactivate	無効化（is_active = 0、確認ダイアログ必須）
merge_preview	統合の影響件数プレビュー（ドライラン）
merge	統合実行（業務4テーブルの kishu_id 差し替え＋旧行 DELETE、確認必須）
update_abbreviation	ヒートマップ略称の更新（編集フォーム）
update_maker	メーカー（maker_id）の更新（編集フォーム）
update_row	一覧のインライン更新（機種名・ヒートマップ略称・メーカー）

Nonce フィールド: kishu_master_nonce（検証アクション: kishu_master_admin）

主な POST パラメータ

フィールド	操作	説明
kishu_master_id	rename / deactivate / update_*	対象 ID
kishu_master_name	add / rename / update_row	機種名（必須、最大 255 文字）
kishu_master_heatmap_abbreviation	update_abbreviation / update_row	ヒートマップ略称（任意）
kishu_master_maker_id	update_maker / update_row	メーカーマスタ ID（任意。空文字は NULL）
kishu_master_source_id	merge_preview / merge	統合元 ID
kishu_master_target_id	merge_preview / merge	統合先 ID

リダイレクト後クエリ（通知）

クエリ	内容
km_success	1 / 0
km_msg	表示文言（URL エンコード）

編集・プレビュー用 GET

GET パラメータ	説明
km_edit	名称変更・略称・メーカー編集対象 ID
km_search	機種名部分一致検索
km_merge_preview	1 のときプレビュー結果表示
km_source_id	プレビュー対象の統合元 ID
km_target_id	プレビュー対象の統合先 ID

一覧 URL のエンコード

ソートリンク・編集リンクとリダイレクト先はいずれも build_list_page_url() が組み立てる。add_query_arg() は値をエンコードしないため、AdminQueryUrl が渡された生値を 1 回だけ URL エンコードする（通知の km_msg も同じ扱い）。生値のままだと & や # を含む機種名で検索したときに条件や文言が途中で切れる。

既知の制約: 受け取り側の sanitize_text_field() は % + 16 進 2 桁を削除するため、A%2Bb のような検索語は往復で値が変わる。

データ

テーブル: db_kishu_master

カラム	説明
id	主キー
name	機種名（uk_name）
is_active	有効フラグ
heatmap_abbreviation	ヒートマップ表示用略称（任意）
maker_id	メーカーマスタ ID（任意。論理 FK）
created_at / updated_at	タイムスタンプ

ID（AUTO_INCREMENT）の飛び番

id は業務上の参照キーであり連番である必要はない。一覧で ID が大きく飛ぶ場合でも、無効行の隠れやデータ欠損を意味しない。

主な要因:

• 過去の一括登録経路: INSERT IGNORE は UNIQUE 衝突でも InnoDB が AUTO_INCREMENT を進める。日次インポート等は未登録名だけ upsert する実装に揃えているが、過去に既存名へ繰り返し IGNORE した期間の消費分は残る
• 統合（merge）: 統合元マスタ行を物理 DELETE するため、その ID が空き番になる

既存 ID の振り直しは他テーブルの kishu_id との整合コストが大きいため行わない。

一覧の参照件数サマリ

列名	参照先
mapping	db_kishu_display_mapping.kishu_id 参照件数
db2023	db2023.kishu_id
summary	db_daily_article_kishu_single_day_summary.kishu_id
delta	db_daily_article_kishu_count_delta.kishu_id
birthday	db_birthday_kishu.kishu_id

merge 時の業務テーブル更新

KishuIdBackfillRepository::update_kishu_id_from_to により次の4テーブルを更新する。

• db2023
• db_daily_article_kishu_single_day_summary
• db_daily_article_kishu_count_delta
• db_birthday_kishu

db_daily_article_kishu_single_day_summary と db_daily_article_kishu_count_delta は UNIQUE (hall, period_key, kishu_id) を持つ。同一ホール×日付に統合元・統合先の両方の行がある場合は、数値列を加算して統合先行に寄せてから統合元行を DELETE する（delta の加算結果が 0 のときは行ごと削除）。summary の順位列は統合先の値を維持する。avg_kaiten は NULL を 0 にしない（両側ありは加重平均、片側のみは非 NULL 側、両側 NULL は更新しない）。旧文字列リネーム用 trait とは別経路（kishu_id 前提・上記差分あり）。不正な source 行は fail-fast で統合全体を中断する。

更新後、KishuMasterRepository::delete_by_id で統合元マスタ行を物理削除する。

プレビューでは summary / delta の hall×period 衝突件数も表示する。

エラー

条件	ユーザー向け挙動	メッセージ / ログ
nonce 不正	リダイレクト＋エラー	Messages::AUTH_FAILED
必須項目空・長さ超過	リダイレクト＋エラー	KishuMasterAdminMessages::*
名称重複	リダイレクト＋エラー	ADD_DUPLICATE
merge 同一 ID	リダイレクト＋エラー	MERGE_SAME_ID
merge DB 失敗	リダイレクト＋エラー	MERGE_FAILED（ErrorHandler にログ）
無効な maker_id	リダイレクト＋エラー	MAKER_INVALID