スプレッドシート集計業務を Next.js + Supabase アプリへ段階移行する設計指示書

運用中のスプレッドシート業務（見積・実施計画・案件管理・予実など）を、現場の業務を止めずに Web アプリ（DB 正データ）へ段階移行するための実装指示書。既存アプリがあれば拡張、なければ新規。「双方向同期の事故」と「集計値の水増し」を構造的に防ぐことに主眼を置く。

前提スタック

• Next.js 14 App Router + Supabase(Postgres) + Vercel。cron は GitHub Actions（Vercel Hobby の cron は信頼性不足）。
• Sheets 読み書きは サービスアカウント直（読み取り共有済みシート）または DwD impersonate（オーナー権限が要るシート。drive+spreadsheets のフルスコープ。readonly スコープは Workspace の DwD 認可対象外で unauthorized_client になりがち）。

移行の6原則（双方向同期を安全に保つ）

1. 同期は原則片方向。双方向にするのは1シートだけに限定。行の対応は行番号でなく隠しUUID列で追跡（行挿入・並替に不変）、書き込みは楽観ロック（読取時チェックサム不一致なら上書きせず conflict キューへ）。同期エージェント発の書き込みには origin マーカーを付け、取込側で echo 除外。
2. 警告より物理封鎖。アプリが正になった範囲のシートは API で保護（編集権を同期主体のみ）。「編集したら警告」方式はアラート疲れで必ず形骸化する。金額など重要セルは初日から protect。
3. 消さない。片方向書き出しも上書き前にシート現状をスナップショット。差分があれば上書きせず conflict キュー化。「最終書き込み勝ち」を禁止し衝突は人間の解決 UI へ。
4. 金銭系は二重台帳を作らない。給与・報酬・請求に直結する列は移行初日からアプリのみ入力可。切替前に最低2サイクルのパラレルラン（アプリ集計 vs 旧集計の自動突合）で差異ゼロを確認。
5. 差分を可視化し、差分ゼロが N 週続くことを Phase 完了条件にする。「いつまでも併走」を防ぐ。正データ所在をレコード単位のフラグ（sheet/db）で宣言。
6. 衝突通知は担当者本人へ（共有チャンネルでなく個人 DM）。金銭データの消失は本人が即日気付ける導線を必ず作る。

エコーループの罠（双方向同期で最頻の重大バグ）

アプリが新規レコードをシートの「追記用タブ」へ push する際、会社名列に「会社名 + 案件名」を連結して書くと、取込（pull）がその出力タブを読み戻したとき、連結文字列を新しい会社名として登録し、実在レコードと一致しない"影武者"レコードを毎サイクル量産する。数百件規模で汚染される。

根絶策（2点セット）:

• pull の対象タブ判定からアプリ自身の出力タブを必ず除外する（shouldSyncTab 相当で APP_OUTPUT_TAB を弾く。環境変数で明示指定されても弾く）。
• push で追記した直後に、そのレコードの sheet_row_id = "<出力タブ>!<追記行>" を DB へ書き戻す（append レスポンスの updatedRange から行番号を取る）。書き戻さないと毎サイクル再 append されて重複が増え続ける。

既存汚染の掃除スクリプト（dry-run 既定 / --apply で適用）:

• 影武者レコード（出力タブ由来 かつ 正規レコード名 + 余分トークン）を canonical へマージ。canonical 選定は「連絡先あり優先 → 最古」。曖昧なもの（正規候補が複数会社にまたがる/1件も無い）は触らず needs_review に退避。
• ぶら下がる子レコードは canonical へ付け替えてから影武者を削除（cascade で失わない）。影武者名にしか無い電話番号等は canonical に補完してから消す。
• レコード名の突合時は正規会社名プレフィックスを剥がしてから比較する（連結名がマッチしないと重複が統合されない）。--match=<部分文字列> で単一ケースを先に検証してから全件適用。

段階リリース手順（コード先行・スキーマ後追い）

全コードを「新テーブル/新列が無くても既存機能を壊さない防御実装」（DB アクセス層は console.error + null 返し）にしておくと、以下の順で安全に出せる:

1. コード先行デプロイ（migration 未適用でも中間状態が安全）。主要ページが 500 でなく空状態表示になることを確認。
2. migration を1本ずつ prod 適用 → 都度スモーク（テーブル/列/トリガーの存在確認）。冪等に書く（create table if not exists / drop policy if exists / add column if not exists / create or replace function）。
3. マスタ取込は既定 dry-run。scratch/*.preview.json を人がレビューしてから --apply（洗い替えは source='sheet_import' 等の同期由来行だけ delete→insert し、手入力行を消さない）。
4. デプロイ → 実データで書込経路を検証（テスト行を投入→検証→必ず削除）。

集計値の水増しを防ぐ（KPI/金額表示の鉄則）

• HR 評価用・仮置きのプレースホルダ列を金額として集計・表示しない。実測で桁が飛ぶ（1案件が年商超え、利益列が負値だらけ 等）。明細（DB の line items 合計）または会計データ（会計ソフトの仕訳）を正とする。
• パススルー請求（代行請求・成功報酬の合算請求など、自社売上でない金額）は集計から除外する。1行が全社年商を超えるような巨大レコードは要注意。
• 「受注時計上ベース」と「納品/会計計上ベース」は構造的に金額が異なる。目標（分母）と実績（分子）の計上基準を必ず揃え、画面にどのベースかを明記する。
• 同期由来の重複レコード（前金/残金の分割は正しい・二重ではない／同一案件が別経路で複数行になるのは重複）を区別する。

並行作業の事故防止

• 同一リポを複数のエージェント/セッションで同時に触るときは git worktree 隔離が必須（各自専用 worktree。共有 worktree で git checkout -b を奪い合うと未コミット作業が消える）。
• 隔離 worktree で build を通すときは、共有 node_modules のシンボリックリンクだと依存欠落で失敗する → pnpm install --frozen-lockfile --prefer-offline（共有ストアで高速）してから build。
• migration 番号・PR 番号は採番の直前に一覧取得して確認（並行セッションと番号衝突しやすい）。

検証の締め

• 変更後は必ず実行して確認（型/ビルド 0 エラー、実データで書込→読み戻し検証、UI は実描画）。「たぶん動く」で完了報告しない。
• 本番 DB への一括書き込み・大量削除は、対象を名指しした明示承認を得てから実行する（本番DBで<対象>を<件数>件<操作>してよい の一文）。