# 「Driveからファイルを名前で探して画面に貼る」機能が実データで1件も当たらないのを潰す 業務アプリの画面上部に「見積書」「提案書」「図面」などのリンクを自動で出す機能はよく作る。 ところがこの手の機能は **コードもテストも正しいのに、実データでは一度もリンクが出ない** という 落ち方をする。しかも「実装済み」と報告されたまま何週間も気づかれない。 この指示書は、その3つの落ち方と、直したときに新しく作り込みがちな2つの事故を潰す手順。 Google Apps Script（Drive/Sheets）を前提に書くが、考え方は他のストレージAPIでも同じ。 --- ## 1. まず「なぜ当たらないか」を実データで特定する（設計より先） コードを読んで直そうとしない。**実際のフォルダを1件ずつ辿って、そのファイルが どこに・何形式で・どんな名前で置かれているかを確認する。** 典型的な原因は3つ。 ### (a) 索引テーブル依存で、人が作った物が入っていない 「アプリが生成物を記録する台帳シート」から URL を引く実装は、**アプリが自分で作った物しか引けない**。 人が手で作ったファイル、アプリ導入前のファイルは台帳に1行も無いので、常に空になる。 ```js // これだけだと、人が作ったファイルには一生当たらない 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 のことが多い。 ```js // 実運用で当たる形式（提案書・資料系） 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アクセス」に割る 選定ルールをテストできる形にしないと、直したつもりで壊れ続ける。 ```js /** * 候補から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: 親フォルダ走査が「マイドライブのルート」を掴む 「目的のファイルが起点の親にあることがある」と分かって親走査を足すと、 **起点フォルダがドライブ直下に置かれているケースで、親＝マイドライブ（または共有ドライブのルート）** になる。 - 遅い（ドライブ全体を列挙する）だけではない - **他レコードのファイルを拾って、そのレコードの物として表示する**。これが本当の被害 ```js /** 親として走査してよいフォルダか。ルート相当は走査しない。 */ 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件） - 描画先の行数が足りないと `範囲の座標がシートのサイズから外れています` で落ちる。 **描き直しの冒頭で必要行数を確保する** ```js 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本足すと、何度でも安全に回せる。 ```js // 書き込みを一切しない。どの経路で何が取れているかだけ返す 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件**で見る - 「遅くなっただけ」→ 走査範囲が広がったときは、**誤検出（他レコードの物を拾う）を必ず疑う** ---