# スプレッドシート集計業務を 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で<対象>を<件数>件<操作>してよい` の一文）。 ---