ken_nogi/dbbackup/HANDOFF.md

引き継ぎメモ (サーバー設置作業用)

このメモは、開発機(Windows)でのやり取りを踏まえて、サーバー上のClaudeに引き継ぐための現状整理です。設計の詳細は SPEC.md を参照してください。ここでは 「今どこまで終わっていて、次に何をすべきか」 に絞って書きます。

現状ステータス(結論から)

• コードは一式実装済み・構文チェック済み(Windows開発機で node --check 全ファイルOK)。
• 未完了・最大のブロッカー: LINE WORKSの共有ドライブAPIは Service Account認証(JWT)では利用できないことが判明した(公式ドキュメント明記 + 実機検証で確認)。そのため、共有ドライブ操作(backup.jsのアップロード/フォルダ作成/削除/一覧)には User Account認証(OAuth 2.0 認可コードフロー) が必須で、これは人間が一度だけブラウザでログイン・同意する手順が必要。この手順がまだ実施されていない(.env の LW_USER_REFRESH_TOKEN が空)。
• pg_dump / createdb / dropdb は開発機(Windows)には存在しないため未検証。実サーバー(Linux、PostgreSQL稼働環境)で初めて実地検証できる。
• コード一式はまだgitにコミットされていない(ローカルファイルのみ)。.env と秘密鍵ファイルは .gitignore 済みなのでgit経由では転送されない → サーバーへは別途安全な方法で転送する必要がある。

サーバーでまずやること(優先順)

1. リポジトリ配置: dbbackup/ フォルダ一式をサーバーに配置(gitで転送する場合、.env と private_*.key は .gitignore 対象のため別送が必要)。
2. Node.jsバージョン確認: node -v が 18.13.0 以上であること(fs.openAsBlob を使用しているため)。
3. .env の内容確認・上書き:
   • PostgreSQL接続系(PG_DUMP_BIN, PGHOST, PGPORT, PGUSER, PGPASSWORD, PGDATABASE)をサーバーの実環境に合わせて確認・修正。特に PG_DUMP_BIN=/usr/bin/pg_dump のパスが実際に存在するか確認。
   • BACKUP_LOCAL_DIR=/var/lib/pgsql/backup/dmp/ が書き込み可能なディレクトリか確認。
   • LINE WORKS認証情報は現在下記の新しいService Accountが設定済み(旧アカウントから切り替え済み):
     • LW_CLIENT_ID=LFE8mn9WwDXOfESHLGha
     • LW_SERVICE_ACCOUNT=dxkz7.serviceaccount@next-hd.co.jp
     • LW_PRIVATE_KEY_FILE=./private_20260711105832.key(このファイルもサーバーへ配置必須)
4. User Account認証のセットアップ(最重要・未完了):
   • Developer Consoleの「User Account認証」欄のRedirect URLに、.env の LW_REDIRECT_URI(現状 https://example.com/callback)と完全一致する値を登録する。サーバー環境でこの値を変える場合は .env も同時に書き換えること。
   • サーバー上(またはブラウザ操作可能な端末)で node lineworks-authorize.js を実行し、対話プロンプトの指示に従って:
     1. 表示された認可URLをブラウザで開く
     2. kenichiro.nogi@next-hd.co.jp でログイン・同意(パスワードはブラウザのLINE WORKSログイン画面のみに入力し、スクリプトやAIには絶対に渡さない)
     3. リダイレクト後のURL(または code= の値)をターミナルに貼り付け
   • 成功すると refresh_token が .env の LW_USER_REFRESH_TOKEN に自動保存される。Refresh Token Rotationが有効なため、以後 backup.js 実行のたびに新しい refresh_token が自動で書き戻される(手動操作は初回のみでよい)。
5. 動作確認:

   node backup.js create-test-db
   node backup.js run --database=pleasanter_backup_test
   node backup.js drop-test-db
   

   SPEC.md の「動作確認方法」セクションに詳細な確認観点あり(共有ドライブへのフォルダ作成、ログアップロード、.envへのLW_SHAREDRIVE_ID書き込み等)。
6. 問題なければ、.env の PGDATABASE を実データベース名(既定 Implem.Pleasanter)に戻して本番実行、その後cron等への登録を検討。

これまでの重要な調査結果(繰り返し確認しないための記録)

• 「Not allowed api」エラーの原因はスコープ不足ではない。file/file.readスコープを正しく要求してもService Account認証では共有ドライブAPIが403になる。スコープが本当に不足している場合は別のエラーメッセージ(has not permission api scope)が返ることを、boardスコープで意図的に間違えた検証で確認済み。
• 新しいService Accountを発行して再検証しても同じ結果(403 Not allowed api)だった → アカウント固有の設定漏れではなく、Service Account認証という方式自体の制約と判断。
• 根拠ドキュメント: https://developers.worksmobile.com/jp/docs/drive に「Drive API は、User Account 認証で取得した Access Token で利用できます。Service Account 認証 (JWT) で取得した Token では利用できません。」と明記(マイドライブ・共有ドライブ・組織/グループフォルダ全てに適用される全体制約として記載)。
• 掲示板(board)APIは引き続きService Account認証で問題なく動作する(get-token.js で確認済み)。今回の制約はDrive/共有ドライブ系APIのみ。

ファイル構成の要点

ファイル	役割
backup.js	メインのバックアップ実行エントリポイント。run/create-test-db/drop-test-db サブコマンド
lineworks-authorize.js	User Account認証の一回限りのセットアップ(対話式、人間の操作が必須)
get-token.js	Service Account認証の動作確認用CLI(掲示板等、Drive以外の用途)
lib/lineworksUserAuth.js	backup.jsが使うUser Account認証(OAuth)。refresh_token管理
lib/lineworksAuth.js	get-token.jsが使うService Account認証(JWT)
lib/lineworksDrive.js	共有ドライブAPI呼び出しラッパー(フォルダ作成・アップロード・削除・一覧)
lib/pgDump.js	pg_dump実行・分割書き出し
lib/env.js	.env読み込み(常にファイルが正)・書き戻し
lib/logger.js	月次ローテーションするログ(INFO/WARN/ERROR)
lib/testDb.js	テスト用DB作成・削除
SPEC.md	詳細設計書(全体像・APIエンドポイント一覧・処理フロー)
sftp.sh	旧手段。使用しない・参照しない(ユーザー指定)

未解決・要判断事項

• LW_REDIRECT_URI を https://example.com/callback(プレースホルダー)のまま使うか、実際に管理下のURLに変更するか未確定。プレースホルダーのままでも動作上は問題ない(ブラウザのアドレスバーからcodeを手動コピーする運用のため)が、気になる場合はDeveloper Console側の登録値と .env を揃えて変更可能。
• cron等への自動実行登録はまだ未着手(今回のスコープ外、動作確認後の話)。
• BACKUP_RETENTION_COUNT(既定100)や PG_DUMP_SPLIT_SIZE_MB(既定3072)は初期値のままなので、必要に応じてサーバー側で調整。