ヒートマップ CSV エディタ設計

1. 目的

ヒートマップ島図を構成する CSV を WordPress 管理画面上で作成・確認・編集できるようにする。CSV のセルを直接編集するのではなく、公開画面に近いグリッドを見ながら台を操作し、ホールごとの台番号規則を適用して詳細 CSV と簡易 CSV を生成する。

画面仕様は ADM-012 ヒートマップ島図管理画面 を正本とする。

2. 対象範囲

2.1 対象

• 空のグリッドからのレイアウト新規作成
• 既存の詳細 CSV の読込とグリッド表示
• 登録済みレイアウトの読込と編集
• 台ペア、壁、空白の追加・移動・削除
• 台の採番順序の指定
• 複数の採番区間と採番ルールによる台番号の自動入力
• 詳細 CSV の生成と、詳細 CSV からの簡易 CSV 自動生成
• 既存の db_heatmap_layout への保存
• 生成した詳細 CSV・簡易 CSV のダウンロード

2.2 対象外

• 公開画面のヒートマップ表示仕様の変更
• 日別台データや機種マスタの編集
• ホールごとの採番設定の永続的なプリセット管理
• 複数管理者による同一レイアウトの同時編集
• CSV 以外の画像、PDF、表計算ファイルからのレイアウト生成

3. 用語

用語	定義
詳細 CSV	黒、白、台番号、Ndata を格納する正本レイアウト
簡易 CSV	詳細 CSV と同じ行列数を持ち、台番号セルを 白 に変換したレイアウト
台番号セル	数字だけで構成されるセル。例: 1178
データセル	台番号に data を付けたセル。例: 1178data
台ペア	同じ番号の台番号セルとデータセルを組み合わせた編集単位
台向き	台番号セルからデータセルへ向かう上下左右の方向。データセル側を通路側とする
採番順序	台番号を割り当てる台ペアの順序
採番区間	開始番号、終了番号、方向、除外ルールを持つ一つの採番設定
レイアウト値	CSV の各セルに格納する 黒、白、台番号、Ndata のいずれか

4. 機能要件

ID	要件
FR-01	空のグリッドを行数・列数を指定して作成できること
FR-02	既存の詳細 CSV を読み込み、CSV と同じ行列配置で表示できること
FR-03	登録済みレイアウトを編集グリッドへ読み込めること
FR-04	台ペアをドラッグ操作で移動でき、移動後も台向きが維持されること
FR-05	台ペアを追加・削除でき、通路側に合わせて台向きを上下左右から指定・変更できること
FR-06	壁セルと空白セルを配置できること
FR-07	台ペアを選択した順に採番順序へ追加し、順序を並べ替え・解除できること
FR-08	採番区間を複数作成し、一覧の上から順に採番順序へ適用できること
FR-09	採番区間ごとに開始番号、終了番号、昇順／降順、連番／末尾が4または9の番号を除外、を指定できること
FR-10	採番結果を保存前にグリッドと採番順序一覧へ反映し、番号を確認できること
FR-11	詳細 CSV を正本として、簡易 CSV を決定的に自動生成できること
FR-12	詳細 CSV と自動生成した簡易 CSV を既存の layout_detail、layout_simple に保存できること
FR-13	生成した詳細 CSV と簡易 CSV を個別にダウンロードできること
FR-14	従来の詳細 CSV・簡易 CSV の2ファイルアップロードによる登録を残し、既存運用を継続できること
FR-15	未保存の変更がある状態でページ遷移、再読込、別レイアウト読込を行う場合、破棄確認を表示すること
FR-16	操作履歴に対し、元に戻す・やり直すを実行できること
FR-17	CSV 読込エラーまたは検証エラーがあっても、読込可能なグリッドと編集内容を保持し、該当セル・採番区間から修正できること
FR-18	台向きに応じて、横配置では 台番号, データ または データ, 台番号、縦配置ではその上下順を正しく表現できること

5. 非機能要件

ID	要件
NFR-01	管理画面と保存処理は manage_options 権限および WordPress nonce で保護すること
NFR-02	CSV の文字コードは UTF-8、区切り文字はカンマ、囲み文字は二重引用符とすること
NFR-03	既存アップロードと同じく1ファイル2MBを上限とし、CSV 拡張子・MIME・内容を検証すること
NFR-04	ドラッグだけに依存せず、選択した台を方向ボタンまたはキーボードで移動できること
NFR-05	操作対象、採番順序、エラーセルを色だけで区別せず、枠線、番号、テキストを併用すること
NFR-06	保存前の詳細・簡易プレビューは、同じ正規化済みグリッドから生成し、保存内容との差異を生じさせないこと
NFR-07	行列数、台ペア数、検証エラー数を常時確認できること
NFR-08	ブラウザ内の編集中データはサーバーから受け取った未加工 CSV ではなく、後述の編集モデルに正規化して扱うこと
NFR-09	台向きはセルの並びだけに依存せず、選択中の台ペアに通路方向を示す矢印を表示して確認できること

6. 編集データモデル

6.1 グリッド

グリッドは0始まりの行・列座標を持つ長方形とする。CSV の各行の列数が異なる場合は、最大列数に合わせて不足セルを 白 で補完してから編集を開始する。

項目	型	制約
rows	integer	1以上
columns	integer	1以上
cells	二次元配列	rows × columns
cellType	wall / empty / unit / data / invalid	CSV 出力時にレイアウト値へ変換する
unitId	string または null	台ペアを識別する編集中限定 ID
number	integer または null	採番済みの unit と data に同じ値を保持する
rawValue	string または null	invalid の場合に元の CSV セル値を保持する
pairDirection	up / right / down / left または null	unit から対応する data へ向かう台向き

unitId は台番号とは独立させる。未採番の台ペアも移動・並べ替えでき、再採番しても同じ台ペアとして扱う。台ペアを構成する unit と data の両セルは同じ unitId と pairDirection を保持する。

不明セルは cellType: invalid とし、rawValue に読込時の値を失わず保持する。グリッドでは元の値とエラー表示を併記し、壁・空白への置換、または台ペアの配置によって正常セルへ変更した時点で rawValue を破棄してエラーを解消する。invalid のままでは採番適用、CSV 出力、保存を許可しない。

6.2 台ペア

• 台番号セルとデータセルは上下左右に隣接する。
• pairDirection は台番号セルを始点、データセルを終点とする。データセル側を通路側として扱う。
• 追加時は台番号セルを基準に、通路の位置に合わせて up、right、down、left から台向きを指定する。
• 横方向で right の場合は左から 台番号, データ、left の場合は左から データ, 台番号 と表示する。
• 縦方向で down の場合は上から 台番号, データ、up の場合は上から データ, 台番号 と表示する。
• 移動、削除、元に戻す、やり直すは2セルを一つの台ペアとして処理する。
• 台ペアの平行移動では pairDirection を変更しない。向きの変更は独立した回転操作として処理する。
• 回転操作は台番号セルを基準位置としてデータセルだけを指定方向へ移し、次項の競合判定に成功した場合だけ実行する。
• 平行移動と回転は原子的に処理する。移動対象自身の移動元セルは占有判定から除外し、それ以外の 白 でないセルまたはグリッド外と重なる場合だけ実行しない。
• 台番号だけ、データセルだけ、番号が異なる隣接セルは不正な台ペアとして表示し、保存を禁止する。

6.3 操作履歴

次の操作を履歴単位とする。

• 台ペアの追加・移動・削除
• 台向きの変更
• 壁・空白の配置
• 行・列の追加・削除
• 採番順序の追加・並べ替え・解除
• 採番区間の追加・更新・削除・並べ替え
• 採番結果の適用

7. CSV 入力仕様

7.1 許可するセル

入力	正規化後	備考
黒	wall	壁・表示範囲外
白	empty	通路・余白
1以上の整数	unit	台番号セル
1以上の整数 + data	data	対応するデータセル
空文字	empty	列数補完後は 白 として出力
上記以外	invalid	rawValue に元値を保持し、セル位置と入力値を表示して保存を禁止

数値は10進整数として解釈し、先頭ゼロを除いた表記へ正規化する。

7.2 台ペア検出

1. 台番号セルと同じ番号のデータセルを上下左右から検索する。
2. 一つだけ見つかった場合は同じ unitId を付与し、台番号セルからデータセルへの相対座標を pairDirection として復元する。
3. 見つからない場合、複数見つかった場合、同じ番号が別の台ペアでも使われている場合はエラーとする。
4. 全台番号セルの処理後、未使用のデータセルを孤立データセルエラーとする。

CSV 読込時の台番号は保持する。採番操作を実行した時点で、採番順序と採番区間に基づく番号へ置き換える。

7.3 読込結果

読込後に次を表示する。

• ファイル名、行数、列数
• 台ペア数、壁セル数、空白セル数
• 検証エラー数と、行・列・原因
• 既存番号の重複および孤立セル

8. レイアウト編集仕様

8.1 新規グリッド

• 行数・列数を入力して全セル 白 のグリッドを作成する。
• 作成後は外周を含め、壁・空白・台ペアを自由に配置できる。
• 行・列は末尾へ追加できる。
• 行・列の削除対象に台ペアまたは壁がある場合は削除確認を行う。

8.2 選択と移動

• 台ペアのどちらのセルを選択しても台ペア全体を選択する。
• 単一台はドラッグ、方向ボタン、矢印キーで移動できる。
• 単一台の移動では台番号セルとデータセルの相対位置および pairDirection を維持する。
• 複数選択した台は各台の相対位置と台向きを維持してドラッグ移動できる。
• 複数選択時は選択集合の全移動元セルを占有判定から除外する。全移動先を検証した後、移動元の消去と移動先への配置を一括反映する。
• 移動対象外のセルと競合する場合は上書きせず、競合セルを示して操作全体を取り消す。

8.3 追加・向き変更・削除

• 台追加では台番号セルの配置座標と通路側を表す台向きを指定する。
• 追加直後の台は未採番とし、採番順序の末尾へ追加する。
• 台向きは「縦向き」「横向き」の2ボタンで切り替える。ボタンは新規追加時の台向きを兼ね、選択中の台があれば同時にその向きへ変更する。
• 向き変更では台番号セルを基準に保ち、データセルだけを指定方向へ移す。選択集合の現在セルを空きとして扱い、1台でも移せない場合は操作全体を取り消す。
• 逆向き（上下・左右）への変更は反転操作で行う。反転は台番号セルとデータセルの座標を入れ替えるため、占有セルが変わらず隣接する空きセルを必要としない。反転軸と一致しない台向きの台は対象外とする。
• 台ペアの削除後は2セルとも 白 にする。
• 壁ツールは対象セルを 黒、消去ツールは対象セルを 白 にする。
• 台ペアの片方を壁または空白へ変更する操作は許可せず、台ペア削除を案内する。

9. 採番仕様

9.1 採番順序

• 台ペアをクリックした順、またはドラッグ範囲内の左上から行優先順で採番順序へ追加する。
• すでに追加済みの台ペアは重複追加しない。
• 採番順序一覧はドラッグまたは上下ボタンで並べ替えられる。
• 採番順序から解除しても台ペア自体は削除しない。
• 全台ペアがちょうど1回ずつ採番順序に含まれることを保存条件とする。

9.2 採番区間

項目	内容
開始番号	区間で最初に採用を試みる1以上の整数
終了番号	区間で最後に採用できる1以上の整数
方向	昇順 または 降順
採番ルール	連番 または 末尾が4または9の番号を除外
適用台数	区間から生成された有効番号数。画面で自動表示する

• 昇順では開始番号が終了番号以下、降順では開始番号が終了番号以上でなければならない。
• 連番 は開始番号から終了番号まで1ずつ増減する。
• 末尾が4または9の番号を除外 は、10進表記の一の位が 4 または 9 の番号を除外する。
• 採番区間は一覧の上から順に番号列を生成し、連結した番号列を採番順序へ先頭から割り当てる。
• 階や同一階内で番号が飛ぶ場合は採番区間を分け、次の開始番号から採番を継続する。

9.3 採番例

区間	開始	終了	方向	ルール	生成番号
1	1001	1008	昇順	末尾が4または9の番号を除外	1001, 1002, 1003, 1005–1008
2	1100	1103	昇順	連番	1100–1103
3	2010	2006	降順	末尾が4または9の番号を除外	2010, 2008, 2007, 2006

9.4 採番検証

条件	扱い
有効番号数が台ペア数より少ない	範囲不足。未採番台数を表示し、適用・保存を禁止
有効番号数が台ペア数より多い	範囲超過。余剰番号数を表示し、適用・保存を禁止
区間間で番号が重複	重複番号と区間を表示し、適用・保存を禁止
採番順序に未登録の台がある	未登録台を強調し、適用・保存を禁止
同じ台が順序に重複している	重複位置を表示し、適用・保存を禁止
除外後に番号が0件	対象区間をエラー表示し、適用・保存を禁止

採番プレビューでは区間ごとの対象台範囲と生成番号を表示する。検証成功時のみ「採番を適用」を有効にする。

10. CSV 出力仕様

10.1 詳細 CSV

編集グリッドを行・列順に次の値へ変換する。

編集セル	CSV 値
wall	黒
empty	白
unit	採番済み台番号
data	{台番号}data

• 全行を同じ列数で出力する。
• 全セルを二重引用符で囲み、カンマ区切り、改行コード LF、UTF-8 BOM なしとする。
• 末尾に改行を一つ付与する。
• pairDirection 自体は CSV に追加せず、台番号セルとデータセルの相対座標として表現する。再読込時は同じ相対座標から台向きを復元する。

10.2 簡易 CSV

簡易 CSV は詳細 CSV と同じ正規化済みグリッドから生成し、次の変換だけを行う。

詳細 CSV 値	簡易 CSV 値
黒	黒
白	白
台番号	白
Ndata	Ndata

行や列を削除せず、詳細 CSV と同じ行数・列数・データセル座標を維持する。同じ編集状態からは常に同じ詳細 CSV と簡易 CSV を生成する。

10.3 出力前検証

次のレイアウト条件をすべて満たす場合だけダウンロードを許可する。

• 許可されないセルがない
• すべての台番号セルとデータセルが一対一の台ペアになっている
• すべての台ペアが採番済みである
• 台番号が重複していない
• 詳細 CSV と簡易 CSV の行数・列数が一致する

保存には上記に加え、次の基本情報条件を必須とする。

• ホール、開始日、終了日が入力され、開始日が終了日以前である

11. 保存と互換性

11.1 保存先

既存の db_heatmap_layout を継続利用し、テーブル変更は行わない。

カラム	保存内容
hall	対象ホール
start_date	適用開始日
end_date	適用終了日
layout_detail	エディタから生成した詳細 CSV
layout_simple	詳細 CSV から自動生成した簡易 CSV

11.2 既存データ

• 既存行の layout_detail を正本としてエディタへ読み込む。
• 既存行の layout_simple は読込時の編集モデルには使用しない。
• 従来の簡易 CSV は詳細 CSV と独立して作成されており、行列数やデータセル座標が詳細 CSV と異なる場合がある。
• 保存前に自動生成した簡易 CSV と既存 layout_simple が異なる場合は、行列数を含む差異と更新後の見え方を簡易プレビューへ表示し、保存時に自動生成結果で更新する。
• 編集せず期間だけを更新する既存操作では、詳細 CSV と簡易 CSV を変更しない。

11.3 従来アップロード

• 詳細・簡易の2ファイルを直接登録する従来フォームを残す。
• 従来アップロードでは詳細・簡易を独立したレイアウトとして扱い、両者の行列数一致を要求しない。
• 従来アップロードで登録したデータも、後から詳細 CSV を正本としてエディタで編集できる。

12. エラーと復旧

エラー	画面の挙動
CSV の形式・サイズ不正	読込を開始せず、ファイル入力付近に理由を表示
不明なセル値	読込可能なセルは表示し、不明セルを強調して保存を禁止
台ペア不正	孤立・重複・番号不一致のセルを強調し、修正方法を表示
移動先競合	グリッドを変更せず、競合位置を一時的に強調
採番設定不正	区間行と採番プレビューに理由を表示し、採番適用を禁止
保存時の検証不一致	編集状態を保持したまま、エラー一覧の先頭へフォーカス
通信・DBエラー	編集状態を保持し、再保存または CSV ダウンロードを選択できるようにする
未保存状態での画面離脱	ブラウザ離脱確認を表示し、キャンセル時は編集を継続

13. 受け入れ条件

1. 既存の詳細 CSV を読み込むと、元 CSV と同じ行列およびセル配置が表示される。
2. 台ペアの移動・追加・削除後も、台番号セルとデータセルの対応および台向きが維持される。
3. 通路の向きに応じて 台番号, データ と データ, 台番号 の両方の並びを作成でき、既存 CSV 読込時も台向きが復元される。
4. 複数の採番区間を上から順に適用し、階または島の境界で任意の開始番号へ切り替えられる。
5. 連番と「末尾が4または9の番号を除外」の両方が昇順・降順で正しく生成される。
6. 採番数と台数が一致しない場合、重複がある場合、未採番台がある場合は保存できない。
7. 詳細 CSV の台番号セルを 白 に変換した簡易 CSV が自動生成され、行列数とデータセル座標が維持される。
8. エディタから保存したレイアウトを既存の公開画面が読み込める。
9. 従来の詳細・簡易 CSV アップロードによる登録と、適用期間だけの更新を継続できる。