# スプレッドシートのボタンUIを「複数人×複数案件の同時利用」に耐えさせる（GAS ジョブキュー化） Google スプレッドシート上に「▶チェックを入れると処理が走る」パネルを作ると、単独利用では動くのに **複数人が同時に使った瞬間に壊れる**。この指示書は、その壊れ方の全パターンと、ジョブキュー化による直し方、 実装時に必ず踏む落とし穴（ロック・6分制限・API呼び出し回数）をまとめたもの。 対象: GAS + スプレッドシート製の社内ツール（実行パネル / 一括処理ボタン / 承認ボタン等）。 前提: 処理本体は別プロジェクト（またはコンテナ外）にあり、シートは「受付」だけを担う構成にできること。 --- ## 1. 共有UIが壊れる4パターン（先に理解する） | # | 壊れ方 | 症状 | |---|---|---| | 1 | 上部の「対象セレクタ」セルが全員共有 | A が対象を選んだ直後に B が切り替えると、**A の押下が B の対象で実行される**。エラーは出ない | | 2 | 機能行が全員共有 | 同じ機能を 2 人が押すと状態セルが上書きされ、**先の予約が黙って消える** | | 3 | 結果セルが共有 | 誰の・どの対象の結果か分からない。上書きされる | | 4 | 自由入力欄が共有 | 同時記入で内容が混ざる | 根本原因は **「セルの現在値」を暗黙の引数にしている**こと。onEdit は「押した瞬間のセル」を読むので、 選ぶ→押す の間に他人が変えられる時間帯が必ず存在する。 --- ## 2. 直し方（設計） ### 2.1 対象ごとにシートを分ける `▶パネル(対象を選ぶ索引)` + `▶パネル(対象A)` `▶パネル(対象B)` … の構成にする。 対象セレクタという操作自体を無くすのでパターン1,3,4 が消える。 **シートの識別はシート名でなく隠しセルのマーカーで行う**（人が改名しても壊れないため）: ``` G1 = 'PANEL_V2' // マーカー G2 = <対象ラベル> // 実行時の対象解決に使う唯一の正 G3 = <対象の物理位置> // 参考値。ズレても実行はG2から解決する G5 = <生成日時> ``` ### 2.2 1押下 = キュー1行（これが本体） 非表示シート `_ジョブキュー` に append する。ヘッダー固定・**行の削除と並べ替えをしない**（jobIdで追跡）: ``` jobId / 受付日時 / 依頼者 / パネルシート名 / パネル行 / 対象ラベル / 機能ラベル / command / argsJSON / システムフラグ / 状態 / 開始日時 / 終了日時 / 結果URL / メッセージ / ワーカー ``` - 状態は `待機 / 実行中 / 完了 / エラー / タイムアウト` - 依頼者は `Session.getActiveUser().getEmail()`。**取れない環境がある前提で、空でも全機能が動くようにする** - 同じ「パネル+行」に `待機`/`実行中` があれば**新規行を作らず**「既に実行中です（依頼: ○○ / HH:mm）」を toast。 同じ成果物への同時書き込みを防ぐ ### 2.3 claim ベースのワーカー 毎分トリガーのワーカーを 2 本（`worker1` / `worker2`）置き、1 実行 1 ジョブだけ処理する。 ```js function claimAndRun(workerId) { var lock = LockService.getDocumentLock(); // ← §3.1 参照。script lock を使わない if (!lock.tryLock(10000)) return null; var selected; try { // 1) 実行中で開始から15分超のものを「タイムアウト」に落とす（GASは6分で強制終了するため） // 2) 待機を受付日時昇順に並べ、次を除外して先頭を取る // - 同じパネル（=同じ対象）に実行中がある → 除外（同一対象は直列） // - 同じ依頼者に実行中がある → 除外（1人の連打で他人を待たせない） // - 全部除外されたら「同一対象に実行中が無い最古」を最後の砦として拾う // 3) 状態=実行中 / 開始日時 / ワーカーID を書いて flush } finally { lock.releaseLock(); // ← 本処理の前に必ず解放する } // 4) ロック外で本処理（数分かかる） // 5) 結果をキュー行とパネル行の両方へ書く } ``` **結果を書く直前に jobId で行番号を引き直す。** 掃除処理が行削除していると、保持していた行番号が 別ジョブを指し、**他人の結果欄に書き込む**サイレント混線が起きる。 ### 2.4 待ち状況を見せる 毎分の軽い処理で、`待機` 行のパネル状態セルに `⏳ 順番待ち (前に n 件)` を書く（1回20セルまで等の上限を付ける）。 「押したのに何も起きない」という問い合わせが消える。 --- ## 3. 実装時に必ず踏む落とし穴 ### 3.1 script lock は「操作経路」と共有してはいけない `LockService.getScriptLock()` はスクリプトに 1 個しかない。外部からの操作経路（例: ファイル投函型の コマンドキュー）が 1 実行の間ずっと script lock を持つ設計だと、そこにワーカーを足した瞬間に **両者が奪い合って操作経路が毎分 skip され、操作不能に見える**。 - ワーカーは `getDocumentLock()`（コンテナバインドなら使える）等に分離する - ロックは短く。claim だけ守り、本処理はロック外 - 症状の見分け方: 「投函したファイルは消費されているのに結果が返らない」 ### 3.2 重い書き込みは 6 分制限に届く（行ごと getRange が致命的） 数式（外部参照系）が多いシートでは 1 回の書き込みごとに再計算が走り、**1 枚のパネル生成で 100 回近い API 呼び出し**があると数分かかる。 - `insertCheckboxes()` / 背景色 / 値は**範囲一括**にする（`setBackgrounds` に二次元配列、 チェックボックスは列範囲へ一括後、対象外の行だけ `clearDataValidations()`） - 一覧描画で「行ごとに全シートを走査してリンク先を探す」のは **行数×シート数** になる。 先に `ラベル→gid` のマップを 1 回だけ作る - 一括生成は「1 実行 N 枚まで + 残りは自分をもう一度キューに積む」**自己継続方式**にする （キューのワーカーが 1 分ごとに 1 枚ずつ進めるので 6 分制限に当たらない） ### 3.3 ファイル投函型のコマンドキューに重い命令を同時投入しない 1 回の実行でフォルダ内の全命令を拾う実装が一般的なので、重い命令を複数投げると **まとめて 6 分制限で死に、後続の結果ファイルが書かれない**。重いものは 1 件ずつ。 ### 3.4 定義の二重管理をやめる 「受付側（シート）」と「実行側（別プロジェクト）」の両方に機能定義を置くと、手で同期する運用になり必ずズレる。 **定義は実行側に単一ソース化**し、受付側は「その行の隠し列（command / args / フラグ）を読んで積むだけ」にする。 受付側は追加権限を要求しない simple onEdit のみで完結する。 --- ## 4. 検証（ここまでやって初めて完了） ### 4.1 ユニット（実行環境の外で回す） 純関数に切り出して `node --test` で検証する: claim 候補選択（同一対象除外／同一依頼者除外／全除外時の フォールバック／受付日時昇順）・stale 判定の境界（14分59秒は継続 / 15分01秒でタイムアウト）・ 順番待ち件数・重複ガード・**依頼者が空文字でも壊れないこと**。 ### 4.2 実機（read-back で確認する） 検証専用のダミー命令（指定秒スリープして固定の結果を返すだけ）を用意し、キューに積んで確認する。 1. **別対象 2 件 → 並行**（開始〜終了が重なること・ワーカーIDが別） 2. **同一対象 2 件 → 直列**（2 件目は 1 件目の終了後に開始） 3. **依頼者が別 → それぞれ処理される** 4. 開始日時を過去に書き換えた行が**タイムアウトに落ちて再実行可能になる** **ダミーの秒数は長めにする（90〜120秒）**。毎分トリガーは同時刻に発火せず数十秒ずれるため、 短いジョブでは並行しても実行時間が重ならず「並列できていない」と誤判定する。 ### 4.3 結果の読み取りを速くする小技 索引シートを**先頭シート**にしておくと、スプレッドシートを CSV エクスポートするだけで 索引の中身をそのまま読める（read-back が一気に速くなる）。 --- ## 5. 移行時の注意 - 旧パネルのシート名を**変えずに中身を索引へ差し替える**と、既存の案内リンク・メニューが生きたまま移行できる - 受付側の onEdit を先に配ってから索引を作ると、**旧パネルの行を押した人が意図しないシートを生成する**空白期間ができる。 受付側の配布と索引の再構築は間を空けない。索引で解決できないラベルの行は**作らずに toast で止める** - 対象別シートは「使う人が開いたときだけ作る」+「終了した対象は N 日後に自動で非表示（削除はしない）」で タブの増殖を抑える ---