「Driveからファイルを名前で探して画面に貼る」機能が実データで1件も当たらないのを潰す

業務アプリの画面上部に「見積書」「提案書」「図面」などのリンクを自動で出す機能はよく作る。 ところがこの手の機能は コードもテストも正しいのに、実データでは一度もリンクが出ない という 落ち方をする。しかも「実装済み」と報告されたまま何週間も気づかれない。

この指示書は、その3つの落ち方と、直したときに新しく作り込みがちな2つの事故を潰す手順。 Google Apps Script（Drive/Sheets）を前提に書くが、考え方は他のストレージAPIでも同じ。

---

1. まず「なぜ当たらないか」を実データで特定する（設計より先）

コードを読んで直そうとしない。実際のフォルダを1件ずつ辿って、そのファイルが どこに・何形式で・どんな名前で置かれているかを確認する。 典型的な原因は3つ。

(a) 索引テーブル依存で、人が作った物が入っていない

「アプリが生成物を記録する台帳シート」から URL を引く実装は、アプリが自分で作った物しか引けない。 人が手で作ったファイル、アプリ導入前のファイルは台帳に1行も無いので、常に空になる。

// これだけだと、人が作ったファイルには一生当たらない
var url = findArtifactUrlFromLedger(recordId, '見積');

→ 台帳を第一候補に残したまま、空だったらフォルダを実際に走査するフォールバックを足す。

(b) 探索の深さが足りない

root.getFiles() と「サブフォルダ1階層の getFiles()」だけ、という実装が多い。 実際の運用フォルダは 案件 > 制作 > 01企画・提案 > <テーマ名> > 提案書.pptx のように 3〜4階層下に置かれていることがある。

(c) 対象形式を絞りすぎている

application/vnd.google-apps.document と …presentation だけを見ていると、 pptx / ppt / xlsx / PDF が全部弾かれる。現場のファイルは Office 形式や PDF のことが多い。

// 実運用で当たる形式（提案書・資料系）
var ALLOWED = {
  'application/vnd.google-apps.document': true,
  'application/vnd.google-apps.presentation': true,
  'application/vnd.openxmlformats-officedocument.presentationml.presentation': true, // pptx
  'application/vnd.ms-powerpoint': true,                                             // ppt
  'application/pdf': true
};

同じアプリの中でも対象ごとに置き場所が違うことがある。 実例では、あるレコードは 起点フォルダの直下に、別のレコードは起点フォルダの 親 に目的のファイルがあった。 1件だけ見て「わかった」としないこと。

---

2. 走査は「純粋関数の選定」と「Driveアクセス」に割る

選定ルールをテストできる形にしないと、直したつもりで壊れ続ける。

/**
 * 候補から1件を選ぶ純粋関数。
 * @param {Array<{name:string, url:string, updatedAt:number}>} candidates
 * @return {string} 採用する URL（該当なしは ''）
 */
function pickFile(candidates, keyword, strongKeyword) {
  var excluded = /(テンプレ|ひな形|雛形|サンプル|ストック|コピー)/;
  var eligible = (candidates || []).filter(function (c) {
    var name = String(c && c.name || '');
    return name.indexOf(keyword) >= 0 && !excluded.test(name);
  });
  // 「強い一致」があればその中だけで選ぶ
  var strong = eligible.filter(function (c) {
    return String(c.name || '').indexOf(strongKeyword) >= 0;
  });
  var pool = strong.length > 0 ? strong : eligible;

  var picked = null;
  pool.forEach(function (c) {
    if (!picked || Number(c.updatedAt) > Number(picked.updatedAt)) picked = c; // 同着は先頭を維持
  });
  return picked ? String(picked.url || '') : '';
}

「更新日時が最新」だけで選ぶと事故る

実例: 提案書.pptx（古い・これが本物）と ご提案デザインのみ.pptx（新しい・断片）が同じフォルダにあり、 更新日時だけで選ぶと断片のほうを顧客向けの依頼文に載せてしまった。

→ 強いキーワード（提案書）を含むものを優先し、無いときだけ広いキーワード（提案）で選ぶ。

テンプレ除外は必須

見積テンプレ 見積テンプレストック 提案書サンプル が業務フォルダに同居しているのは普通のこと。 名前で除外しないと、全レコードが同じテンプレのURLを指す。

---

3. 直したときに作り込みがちな事故 2つ

事故1: 親フォルダ走査が「マイドライブのルート」を掴む

「目的のファイルが起点の親にあることがある」と分かって親走査を足すと、 起点フォルダがドライブ直下に置かれているケースで、親＝マイドライブ（または共有ドライブのルート） になる。

• 遅い（ドライブ全体を列挙する）だけではない
• 他レコードのファイルを拾って、そのレコードの物として表示する。これが本当の被害

/** 親として走査してよいフォルダか。ルート相当は走査しない。 */
function isScannableParent(folder) {
  try {
    if (!folder) return false;
    if (folder.getId() === DriveApp.getRootFolder().getId()) return false;
    return folder.getParents().hasNext(); // 自分の親を持たない = ルート相当（共有ドライブのルート含む）
  } catch (e) { return false; }
}

事故2: 実行時間・行数の上限で、画面が空のまま残る

画面を sheet.clear() してから描き直す実装は、途中で例外が出ると空の画面がユーザーに残る。

• 走査するファイル数・フォルダ数に上限を持たせる（例: ファイル400〜800件、フォルダ60件）
• 描画先の行数が足りないと 範囲の座標がシートのサイズから外れています で落ちる。 描き直しの冒頭で必要行数を確保する

try {
  var needRows = 120;
  if (sheet.getMaxRows() < needRows) sheet.insertRowsAfter(sheet.getMaxRows(), needRows - sheet.getMaxRows());
} catch (e) { console.warn('ensure rows failed: ' + e); }
sheet.clear();

---

4. 副作用ゼロで検証できる診断コマンドを足す

「本番の生成処理を実行して確かめる」は、通知が飛んだり台帳に行が増えたりして現場に実害が出る。 読み取り専用の診断関数を1本足すと、何度でも安全に回せる。

// 書き込みを一切しない。どの経路で何が取れているかだけ返す
function debugLinks(recordId) {
  var rec = loadRecord(recordId);
  if (!rec) return { error: 'not found: ' + recordId };
  var out = { recordId: recordId, root: '' };
  try { out.root = resolveRootFolder(rec); } catch (e) {}
  try { out.fromLedger = findArtifactUrlFromLedger(recordId, '見積'); } catch (e) { out.fromLedger = 'ERROR ' + e; }
  try { out.fromFolder = findEstimateInFolder(rec); } catch (e) { out.fromFolder = 'ERROR ' + e; }
  try { out.proposal = findProposalUrl(rec); } catch (e) { out.proposal = 'ERROR ' + e; }
  return out;
}

これで「台帳は空だがフォルダ走査で取れている」「提案書は3階層下の pptx から取れた」ことを 実データで確認してから完了と言える。

---

5. 完了の判定基準（これを満たすまで「直った」と言わない）

1. ユニットテストが緑（選定ルールの純粋関数）
2. 本番へ反映した後、デプロイ元と本番のソースに差分が無いことを確認した
3. 性質の違う実データ2件以上で、実際に画面へ出ることを確認した （例: ファイルが起点直下にあるケースと、起点の親にあるケース）
4. 画面を作り直す系なら、全レコード分を作り直し、取り残しゼロを棚卸しコマンドで確認した
5. 棚卸しコマンドは再構築中に走らせると古い値を返す。欠落が出たら実行中でないか確かめてから取り直す

---

6. よくある勘違い

• 「テストが緑だから直った」→ 選定ルールは正しくても、候補が1件も集まっていないことがある
• 「コードを読んだら正しい」→ 落ちているのは探索の届く範囲と現実の階層のズレ
• 「1件で確認した」→ レコードごとに置き場所が違う。2件以上、できれば構造の違う2件で見る
• 「遅くなっただけ」→ 走査範囲が広がったときは、誤検出（他レコードの物を拾う）を必ず疑う