Appearance
ADM-012 ヒートマップ島図管理画面
概要
- ホール別のヒートマップ島図を管理画面上で作成・確認・編集し、適用期間とともに
db_heatmap_layoutへ保存する。 - 既存の詳細 CSV を読み込み、公開画面に近いグリッドで台の配置を確認できる。
- 詳細レイアウトを正本とし、保存時に簡易 CSV を自動生成する。
- 台の追加・移動・削除、通路側に合わせた台向きの指定、採番順序の指定、複数の採番区間による台番号の自動入力を提供する。
- 従来の詳細／簡易 CSV の2ファイルアップロード、適用期間更新、削除も継続して利用できる。
- CSV のデータ構造、編集規則、採番規則、変換仕様は ヒートマップ CSV エディタ設計 に従う。
ワイヤーフレーム
text
┌ ヒートマップ島図 ────────────────────────────────────────────┐
│ [新規作成] [詳細CSVを読込] [登録済みレイアウトを選択 ▼] [読込] │
├ 基本情報 ────────────────────────────────────────────────────┤
│ ホール [▼] 開始日 [YYYY-MM-DD] 終了日 [YYYY-MM-DD] │
├ ツール ──────────────────────────────────────────────────────┤
│ ツール[選択|台を追加|壁|空白] │
│ 台の向き[↑縦向き|→横向き|上下反転|左右反転] │
│ 移動[↑|→|↓|←] 編集[削除|元に戻す|やり直す] │
│ 行と列[行追加|列追加|末尾行を削除|末尾列を削除] 表示倍率[- + %]│
├ 編集グリッド ─────────────────────────────┬ 状態 ──────────────┤
│ │ 行×列: 42×51 │
│ 黒 黒 黒 黒 黒 │ 台: 380 │
│ 黒 白 1178 1180 ... │ 未採番: 0 │
│ 黒 白 1178data 1180data ... │ エラー: 0 │
│ （スクロール・拡大縮小） │ [エラー一覧] │
├───────────────────────────────────────────┴───────────────────┤
│ 採番順序 │ 採番区間 │
│ 1 [台A] ↑ ↓ × │ 1 開始[1001] 終了[1088] │
│ 2 [台B] ↑ ↓ × │ [昇順▼][末尾4・9除外▼]74台│
│ ... │ 2 開始[1100] 終了[1150] │
│ [選択順を追加] [全解除] │ [昇順▼][連番▼] 51台 │
│ │ [区間追加] [採番プレビュー]│
├ プレビュー ──────────────────────────────────────────────────┤
│ [詳細] [簡易] 採番結果・CSV変換後のレイアウト │
├───────────────────────────────────────────────────────────────┤
│ [採番を適用] [詳細CSV DL] [簡易CSV DL] [保存] │
└───────────────────────────────────────────────────────────────┘
┌ 従来のCSVアップロード ────────────────────────────────────────┐
│ ホール [▼] 開始日 [ ] 終了日 [ ] 詳細CSV [ ] 簡易CSV [ ] [登録]│
└───────────────────────────────────────────────────────────────┘
┌ 登録済みレイアウト一覧 ────────────────────────────────────────┐
│ ID | ホール | 開始日 | 終了日 | [エディタで編集] [期間編集] │
│ | [複製] [削除] │
└───────────────────────────────────────────────────────────────┘画面仕様
ブロック一覧
| ブロックID | ブロック名 | 表示内容 | 初期値 | ユーザー操作 | アクション |
|---|---|---|---|---|---|
B-1 | 読込方法 | 新規作成、詳細 CSV 読込、登録済みレイアウト選択 | 未選択 | 新規グリッド作成、CSV 選択、登録済み行選択 | A-1, A-2, A-3 |
B-2 | 基本情報 | ホール、開始日、終了日 | 新規時は空、編集時は保存値 | ホールと日付を入力 | - |
B-3 | 編集ツール | ツール、台の向き、移動、編集、行と列、表示倍率のグループ | 選択ツール | ツール選択、台向き変更・反転、元に戻す・やり直す、行列追加・削除 | A-4, A-5, A-6 |
B-4 | 編集グリッド | 詳細レイアウト、座標、選択状態、通路方向矢印、採番順序番号、機種名、エラー位置 | 読込前は未表示 | 台ペア選択、ドラッグ移動、向き変更、キーボード移動、セル配置、複数選択 | A-4, A-5, A-7 |
B-5 | レイアウト状態 | 行数、列数、台ペア数、未採番数、エラー数とエラー一覧 | すべて0 | エラーを選択して該当セルへ移動 | - |
B-6 | 採番順序 | 台ペアの順序、現在番号、所属区間 | CSV 読込時は行優先順で仮登録 | 選択順追加、ドラッグ・上下ボタンによる並べ替え、解除 | A-7 |
B-7 | 採番区間 | 開始番号、終了番号、昇降順、採番ルール、有効番号数 | 区間1件、昇順、連番 | 区間追加・更新・削除・並べ替え | A-8 |
B-8 | 採番プレビュー | 区間ごとの生成番号、対象台、余剰・不足・重複 | 未表示 | 採番設定を検証し、成功時に採番を適用 | A-8, A-9 |
B-9 | レイアウトプレビュー | 詳細／簡易切替、CSV 変換後のグリッド | 詳細 | 表示切替、スクロール、拡大縮小 | A-10 |
B-10 | 保存・ダウンロード | 詳細 CSV ダウンロード、簡易 CSV ダウンロード、保存 | 検証完了まで無効 | CSV ダウンロード、DB 保存 | A-11, A-12 |
B-11 | 従来の CSV アップロード | ホール、開始日、終了日、詳細 CSV、簡易 CSV | 空 | 2ファイルを選択して登録 | A-13 |
B-12 | 登録済みレイアウト一覧 | ID、ホール、開始日、終了日、エディタ編集、期間編集、複製、削除 | DB の全登録行 | 編集方法の選択、複製、削除 | A-3, A-14, A-15, A-16 |
B-13 | 通知 | 成功、入力エラー、CSV エラー、競合、保存失敗 | なし | メッセージから対象フィールドまたはセルへ移動 | - |
表示・入力規則
新規作成
- 行数・列数はいずれも1以上の整数を必須とする。
- 作成直後は全セルを
白とする。 - 未保存の編集状態がある場合、新規作成前に破棄確認を表示する。
CSV 読込
- 詳細 CSV 1ファイルをブラウザで読み込み、サーバーへ保存する前に編集モデルへ変換する。
- 読込可能な形式は UTF-8 の CSV、上限2MBとする。
- 行ごとに列数が異なる場合は、最大列数まで
白で補完する。 - 不明セルや台ペア不正がある場合も読込可能なセルを表示し、エラー解消まで保存を無効にする。
- 台番号セルから隣接する同番号のデータセルへの相対位置を台向きとして復元する。
- 詳細 CSV 読込時の採番順序は、台番号セルを上から下、同じ行では左から右の順で仮登録する。利用者は採番前に並べ替えられる。
登録済みレイアウト読込
- 一覧の「エディタで編集」は、対象行の
layout_detailを正本として同じ画面を再表示する。 - ホール、開始日、終了日と詳細 CSV を編集状態の初期値にする。
- 保存済みの
layout_simpleと自動生成結果が異なる場合、簡易プレビューに差異通知を表示する。 - 未保存の編集状態がある場合、別レイアウト読込前に破棄確認を表示する。
グリッド操作
- 台番号セルまたはデータセルを選択すると、同じ台ペアの2セルを選択する。
- 台ペア移動は原子的に扱い、移動対象自身の移動元セルは占有判定から除外する。複数選択時は選択集合の全移動元セルを除外し、それ以外の
白でないセルまたはグリッド外と重なる場合だけ移動せず競合位置を示す。 - 単一・複数選択の移動では、台番号セルとデータセルの相対位置および各台の台向きを維持する。
- 台追加時は配置座標と、台番号セルから通路側のデータセルへ向かう台向きを指定し、未採番の台ペアを採番順序末尾へ追加する。
- 台向きは上・右・下・左から選択する。右向きは左から
台番号, データ、左向きは左からデータ, 台番号と表示し、上下も同じ規則で並べる。 - 選択中の台ペアには、データセル側の通路方向を示す矢印を重ねて表示する。
- 台の向きは「↑縦向き」「→横向き」の2ボタンで切り替える。ボタンは新規追加時の台向きを兼ね、選択中の台ペアがあれば同時にその向きへ変更する。
- 向き変更では台番号セルを基準位置に保ち、データセルだけを選択方向へ移動する。選択集合の現在セルを除外して競合判定し、全件成功した場合だけ一括反映する。
- 「上下反転」「左右反転」は選択中の台ペアの台番号セルとデータセルの座標を入れ替える。占有セルが変わらないため隣接する空きセルを必要とせず、反転軸と一致しない台向きの台は対象外とする。
- 日付照合の実行後は、照合できた台番号セルに機種名を省略表示し、完全な機種名はセルの
titleとaria-labelで確認できる。 - 台削除では2セルを
白にし、採番順序からも削除する。 - 台ペアの片方だけを壁・空白へ変更できない。
- ドラッグと同じ操作を方向ボタンおよびキーボードでも実行できる。
採番
- 採番順序には全台ペアがちょうど1回含まれなければならない。
- 採番区間は一覧の上から順に連結して適用する。
- 採番ルールは
連番と末尾が4または9の番号を除外を選択できる。 - 採番区間の有効番号数の合計は台ペア数と一致しなければならない。
- 区間間の番号重複、範囲方向不正、未登録台、順序重複がある場合は採番を適用できない。
- 採番適用時に台番号セルを番号、データセルを同番号の
Ndataへ更新する。
プレビューと保存
- 詳細プレビューは正規化済み編集グリッド、簡易プレビューは詳細から自動生成したグリッドを表示する。
- 簡易プレビューでは台番号セルを
白として表示し、Ndataの位置を維持する。 - 編集と採番の検証が成功した場合にダウンロードを有効にする。CSV に含まれない基本情報はダウンロード条件にしない。
- 保存は、ダウンロード条件に加えて基本情報の検証も成功した場合だけ有効にする。
- 保存失敗時は編集状態を保持し、CSV ダウンロードを継続して利用できる。
- 未保存状態でページを離れる場合は離脱確認を表示する。
操作の可否
| 状態 | 編集 | 採番プレビュー | 採番適用 | CSVダウンロード | 保存 |
|---|---|---|---|---|---|
| グリッド未作成 | - | - | - | - | - |
| CSV 読込エラーあり | 可 | 条件付き | - | - | - |
| 台ペアエラーあり | 可 | - | - | - | - |
| 採番設定エラーあり | 可 | 可 | - | - | - |
| 採番済み・基本情報未入力 | 可 | 可 | 可 | 可 | - |
| 全検証成功 | 可 | 可 | 可 | 可 | 可 |
| 保存中 | - | - | - | - | - |
処理連携仕様
編集、移動、採番、プレビュー、CSV ダウンロードはブラウザ内で完結する。サーバー連携は初期表示、登録済み行の読込、保存、従来アップロード、期間更新、削除に限定する。
保存（新規・更新・複製・期間変更・削除）に成功したら、日別記事のフロントキャッシュ（簡易ヒートマップのブロック HTML・ページ HTML 等）の全体世代を上げ、次の表示から新しい島図を反映する（Issue #4075）。DB が実際に変わったときだけ上げ、no-op・競合・検証エラー・更新 0 件では上げない。処理は HeatmapLayoutAdminService が HeatmapLayoutFrontendCacheInvalidator（DailyArticleFrontendCacheGeneration::bump_global()）を呼んで行う。
アクション一覧
A-1 新規グリッドを作成する
行数・列数からブラウザ内に全セル 白 の編集モデルを作成する。サーバー通信は行わない。
入力
| 項目 | 必須 | 制約 |
|---|---|---|
| 行数 | 必須 | 1以上の整数 |
| 列数 | 必須 | 1以上の整数 |
出力
| 項目 | 内容 |
|---|---|
| 編集モデル | 指定行列数の空レイアウト |
| 編集状態 | 未保存 |
A-2 詳細 CSV を読み込む
選択された詳細 CSV をブラウザで解析し、編集モデルへ正規化する。サーバー通信は行わない。
入力
| 項目 | 必須 | 制約 |
|---|---|---|
| 詳細 CSV | 必須 | UTF-8、CSV、最大2MB |
出力
| 項目 | 内容 |
|---|---|
| 編集モデル | 長方形へ正規化したセルと台ペア |
| 採番順序 | 台番号セルの行優先順 |
| 読込結果 | 行列数、台数、エラー一覧 |
A-3 登録済みレイアウトを読み込む
hl_layout_edit を指定して管理画面を再表示し、対象行の詳細 CSV を初期編集モデルとして渡す。
リクエスト
| GET パラメータ | 必須 | 内容 |
|---|---|---|
hl_layout_edit | 必須 | 対象レイアウト ID |
レスポンス
| 項目 | 内容 |
|---|---|
layout_id | 対象 ID |
hall | ホールキー |
start_date | 開始日 |
end_date | 終了日 |
layout_detail | 詳細 CSV |
layout_simple | 差異表示に使用する既存の簡易 CSV |
updated_at | 編集開始時の更新日時 |
original_row_checksum | 更新競合検出用の行チェックサム |
CSV 本文を含む初期データは wp_json_encode 相当で安全に JSON 化して埋め込む。対象なしまたは権限不足の場合は編集データを渡さず、通知を表示する。
A-4 台ペアを追加・移動・向き変更する
台ペアを追加、ドラッグ・方向操作で平行移動、台番号セルを基準に向き変更、または台番号セルとデータセルの座標を入れ替えて反転する。平行移動では台向きを維持し、向き変更ではデータセルだけを指定した通路方向へ移す。サーバー通信は行わない。
入力
| 項目 | 内容 |
|---|---|
対象 unitId | 移動・向き変更・反転対象。追加時は新規生成 |
| 操作種別 | add / move / change_direction / flip |
| 移動先座標 | 台番号セルの行・列。向き変更・反転時は算出 |
pairDirection | 台番号セルから通路側のデータセルへ向かう上下左右 |
| 反転軸 | flip のみ。上下反転は縦向き、左右反転は横向きが対象 |
出力
| 項目 | 内容 |
|---|---|
| 編集モデル | 成功時のみ2セルと pairDirection を更新 |
| 操作履歴 | 元に戻す・やり直す対象として1操作を追加 |
| 競合情報 | 失敗時の座標と理由 |
移動・向き変更の競合判定では、対象台ペア（複数移動時は選択集合全体）の移動元セルを空きとして扱う。全移動先を先に検証し、対象外の占有セルとの競合がない場合だけ、移動元の消去と移動先への配置を一括反映する。
A-5 台ペアまたはセルを削除する
台ペアは2セル単位、壁は1セル単位で 白 へ変更する。台削除時は採番順序からも解除する。サーバー通信は行わない。
A-6 行・列を変更する
末尾への行・列追加、指定行・列の削除を行う。削除対象に 白 以外がある場合は確認後に実行する。サーバー通信は行わない。
A-7 採番順序を編集する
選択台の追加、順序変更、解除をブラウザ内で行い、全台の登録状態を再検証する。
A-8 採番をプレビューする
採番区間を一覧順に評価し、生成番号、対象台、重複、余剰、不足を表示する。サーバー通信は行わない。
入力
| 項目 | 内容 |
|---|---|
| 採番順序 | unitId の順序 |
| 採番区間 | 開始・終了・方向・ルールの配列 |
出力
| 項目 | 内容 |
|---|---|
| 生成番号 | 区間ごとの番号列 |
| 対応表 | unitId と台番号 |
| 検証結果 | 成否とエラー一覧 |
A-9 採番を適用する
検証済み対応表を台ペアへ反映し、台番号セルとデータセルの番号を同時に更新する。サーバー通信は行わない。
A-10 詳細・簡易をプレビューする
正規化済みグリッドから詳細・簡易の出力グリッドを生成して切り替え表示する。簡易では台番号セルだけを 白 に変換する。
A-11 CSV をダウンロードする
検証済みグリッドから UTF-8、LF、全セル二重引用符の CSV をブラウザで生成し、heatMap.csv または heatMapSimple.csv としてダウンロードする。
A-12 エディタのレイアウトを保存する
POST options-general.php?page=heatmap-layout-admin へ非同期送信し、検証成功後に新規登録または既存行を更新する。画面遷移を行わないため、入力エラー、競合、通信・DB エラーが発生しても、編集モデル、採番順序、採番区間、未適用の対応表、unitId、元に戻す・やり直す履歴をブラウザ内に保持する。
リクエスト
| POST フィールド | 必須 | 内容 |
|---|---|---|
heatmap_layout_nonce | 必須 | 検証アクション heatmap_layout_admin |
heatmap_layout_action | 必須 | 新規は insert_editor、更新は update_layout |
heatmap_layout_id | 更新時 | 対象 ID |
heatmap_layout_hall | 必須 | ホールキー |
heatmap_layout_start_date | 必須 | Y-m-d |
heatmap_layout_end_date | 必須 | Y-m-d |
layout_detail | 必須 | 生成済み詳細 CSV |
layout_simple | 必須 | 詳細 CSV から生成した簡易 CSV |
original_updated_at | 更新時 | 編集開始時の更新日時 |
original_row_checksum | 更新時 | 編集開始時の変更対象カラムのチェックサム |
レスポンス
| HTTP 状態 | 内容 |
|---|---|
200 | layout_id、新しい updated_at、新しい row_checksum を返し、保存完了通知を表示 |
400 | フィールド・CSV 検証エラーを返し、編集状態を変えず該当箇所を表示 |
403 | 権限・nonce エラーを返し、編集状態を変えず再認証を案内 |
409 | 更新競合を返し、編集状態を変えず再読込または CSV ダウンロードを案内 |
500 | 保存失敗を返し、編集状態を変えず再保存または CSV ダウンロードを案内 |
サーバー側でも CSV のセル、行列、台ペア、詳細・簡易の対応を再検証する。layout_simple は受信値を信頼せず、layout_detail から再生成した値と一致する場合だけ保存する。
更新時は、id、original_updated_at、original_row_checksum の比較と更新を一つの UPDATE で行う。チェックサムは編集開始時の hall、start_date、end_date、layout_detail、layout_simple からサーバー側で生成する。条件付き更新の更新件数が1件なら成功とする。
更新件数が0件の場合は現在行を再取得し、現在の更新日時と行チェックサムを編集開始時の値と比較する。両方が一致する場合は条件一致かつ保存内容に変更がない no-op として 200 を返し、一致しない場合だけ実競合として 409 を返す。no-op 成功時も現在の更新日時とチェックサムを返す。これにより同一内容の再保存を競合と誤判定せず、同一秒内の別更新は内容チェックサムで検出する。成功後はレスポンスの更新日時とチェックサムを次回保存条件として保持する。
A-13 従来の CSV をアップロードする
詳細・簡易 CSV の2ファイルを multipart/form-data で同期送信し、新規行を登録する。
リクエスト
| POST フィールド | 必須 | 内容 |
|---|---|---|
heatmap_layout_nonce | 必須 | 検証アクション heatmap_layout_admin |
heatmap_layout_action | 必須 | insert |
heatmap_layout_hall | 必須 | ホールキー |
heatmap_layout_start_date | 必須 | Y-m-d |
heatmap_layout_end_date | 必須 | Y-m-d |
file_detail | 必須 | 詳細 CSV、最大2MB |
file_simple | 必須 | 簡易 CSV、最大2MB |
レスポンス
| 結果 | 内容 |
|---|---|
| 成功 | 一覧へリダイレクトし、登録完了通知を表示 |
| 失敗 | 一覧へリダイレクトし、入力・CSV・DBエラーを表示 |
A-14 適用期間を更新する
既存の詳細・簡易 CSV を変更せず、開始日・終了日だけを同期 POST で更新する。
リクエスト
| POST フィールド | 必須 | 内容 |
|---|---|---|
heatmap_layout_nonce | 必須 | 検証アクション heatmap_layout_admin |
heatmap_layout_action | 必須 | update_dates |
heatmap_layout_id | 必須 | 対象 ID |
heatmap_layout_start_date | 必須 | Y-m-d |
heatmap_layout_end_date | 必須 | Y-m-d |
レスポンス
| 結果 | 内容 |
|---|---|
| 成功 | 一覧へリダイレクトし、更新通知を表示 |
| 失敗 | 一覧へリダイレクトし、エラーを表示 |
A-15 レイアウトを削除する
確認ダイアログ承認後、対象行を同期 POST削除する。
リクエスト
| POST フィールド | 必須 | 内容 |
|---|---|---|
heatmap_layout_nonce | 必須 | 検証アクション heatmap_layout_admin |
heatmap_layout_action | 必須 | delete |
heatmap_layout_id | 必須 | 対象 ID |
レスポンス
| 結果 | 内容 |
|---|---|
| 成功 | 一覧へリダイレクトし、削除通知を表示 |
| 失敗 | 一覧へリダイレクトし、エラーを表示 |
A-16 レイアウトを複製する
確認ダイアログ承認後、対象行のホール・適用期間・詳細 CSV・簡易 CSV をそのまま複写した行を同期 POST で新規登録する。適用期間は複製後に A-14 で調整する運用とする。
表示側は同一ホール・同一日付に複数行がある場合、開始日と ID の降順で先頭の1行だけを参照する。そのため複製直後は複製した行が優先表示となり、適用期間を調整する前に複製した行を編集すると既存期間の表示が入れ替わる。この点は複製の成功通知でも案内する。
リクエスト
| POST フィールド | 必須 | 内容 |
|---|---|---|
heatmap_layout_nonce | 必須 | 検証アクション heatmap_layout_admin |
heatmap_layout_action | 必須 | duplicate |
heatmap_layout_id | 必須 | 複製元 ID |
レスポンス
| 結果 | 内容 |
|---|---|
| 成功 | 一覧へリダイレクトし、適用期間の編集を促す複製通知を表示 |
| 失敗 | 一覧へリダイレクトし、対象なしまたは登録失敗のエラーを表示 |
外部インターフェース
管理画面
| 項目 | 値 |
|---|---|
| URL | /wp-admin/options-general.php?page=heatmap-layout-admin |
| メニュー名 | ヒートマップ島図 |
| 権限 | manage_options |
| 通信 | 初期表示・従来操作は同期、エディタ保存は非同期、編集とプレビューはブラウザ内 |
GET パラメータ
| パラメータ | 内容 |
|---|---|
hl_layout_edit | エディタで読み込むレイアウト ID |
hl_edit | 適用期間だけを編集するレイアウト ID |
hl_success | 通知の成功フラグ 1 / 0 |
hl_msg | 通知メッセージ |
テーブル: db_heatmap_layout
| カラム | 内容 |
|---|---|
id | 主キー |
hall | ホール |
start_date / end_date | 適用期間 |
layout_detail | 正本となる詳細 CSV |
layout_simple | 詳細 CSV から自動生成した簡易 CSV |
created_at / updated_at | 作成・更新日時。更新競合の検出にも使用 |
テーブル変更は行わない。
CSV 契約
| 種別 | セル値 | 生成方法 |
|---|---|---|
| 詳細 | 黒、白、台番号、Ndata | 編集グリッドから生成 |
| 簡易 | 黒、白、Ndata | 詳細の台番号セルを 白 へ変換 |
詳細は ヒートマップ CSV エディタ設計 を参照する。
エラー
| 条件 | ユーザー向け挙動 | ログ／制御 |
|---|---|---|
| 権限・nonce 不正 | 保存せず認証エラーを表示 | Messages::AUTH_FAILED |
| ホール・日付不正 | 編集状態を保持し、該当入力へエラー表示 | サーバー側で再検証 |
| CSV サイズ・形式不正 | 読込または保存を中止し、理由を表示 | ファイル名・位置を記録 |
| 不明セル・台ペア不正 | 該当セルを強調し、保存を無効化 | 行・列・理由を返す |
| 採番不正 | 区間と対象台を強調し、採番適用・保存を無効化 | ブラウザとサーバーで検証 |
| 更新競合 | 編集内容を保持し、再読込または CSV 保存を案内 | updated_at 不一致で更新しない |
| DB 例外 | 編集内容を保持し、保存失敗を表示 | 例外内容を管理ログへ記録 |