スプレッドシートの行を「内容」で特定する仕組みが、ある日から書き戻せなくなる

これは何の指示書か

既存スプレッドシートを正本にした業務アプリでよくある設計—— 行番号ではなく「内容の組み合わせ（タイムスタンプ＋依頼者＋日付＋品名の先頭N字）」で行を特定する——が、 ある種の入力値でだけ永久に一致しなくなるという不具合の見つけ方と直し方。

症状は「登録はできるのにスプレッドシートに反映されない」。ユーザーからは 「反映されません」としか報告されないので、原因に辿り着くまでが長い。

対象読者: 内容アンカー（row anchor）方式で SS へ書き戻すアプリを保守している人。

---

手順 0: ユーザー報告から本番ログへ

「〜が反映されない」「〜が失敗する」だけの報告は、本番のサーバログを見るまで推測しない。

# Vercel の場合
vercel logs https://<本番ホスト> --json \
  | grep -iE "\"level\":\"error\"" | head -5

見るべきはエラーコード。この不具合なら例えば:

[<サービス名>] SS write-back failed  code: 'ROW_MISMATCH', statusCode: 409
「依頼の内容が変更されました。再読込してください。」

409 と「変更されました」という文言に騙されないこと。実際には誰も変更していない。 全行を走査して1行も一致しなかった、というだけの意味であることが多い。

---

手順 1: 保存されているアンカーと、実シートの行を突き合わせる

推測で直さない。DB に保存されたアンカーと、実シートの該当行を並べて見る。

// DB から（例）
{
  "timestamp": "2026/08/10 22:40:39",
  "requester": "<依頼者名>",
  "deadline":  "2026/08/16",
  "itemHead":  "液晶モニターまとめ売り 18.5インチ "   // ← 20字・末尾が空白
}
// シートの生の品名
"液晶モニターまとめ売り　18.5インチ　５だい"           // ← 全角空白

itemHead の末尾が空白かどうかを必ず見る。 ここが今回の犯人。

---

手順 2: 真因 —— normalize の trim と slice の順序

典型的な実装はこうなっている:

function normalize(s) {
  return s.replace(/　/g, ' ').trim();   // 全角空白→半角、前後をtrim
}

function buildRowAnchor(input) {
  const itemHead = normalize(input.itemName).slice(0, 20);   // ← normalize してから切る
  ...
  const hash = sha256([ts, requester, deadline, itemHead].join('|'));
  return { timestamp, requester, deadline, itemHead, hash };
}

function matchesAnchor(anchor, candidate) {
  return anchor.itemHead === normalize(candidate.itemHead).slice(0, 20);
}

一見正しい。しかし 20字目がちょうど空白になる文字列で壊れる。

1. 同期時: normalize(品名).slice(0,20) → "…18.5インチ "（末尾が空白の20字）が DB に保存される
2. 書き戻し時: 保存値から anchor を復元するのに、同じ buildRowAnchor に itemName: 保存された itemHead を渡す → normalize の trim が末尾の空白を落として19字になる
3. 一方シート側の candidate は normalize(生の品名).slice(0,20) で20字のまま
4. 19字 ≠ 20字 → 永久に一致しない

日本語の入力は全角空白で区切られることが多いので、これは珍しいケースではない。 「特定の依頼だけ書き戻せない」という形で現れ、再現条件が分からず放置されやすい。

一般化した教訓

「正規化してから切る」処理は、その出力をもう一度同じ関数に通すと結果が変わることがある。 保存した値を復元して再計算する設計では、変換が冪等（idempotent）でなければならない。

trim を含む正規化と slice を組み合わせたら、必ず往復テストを書く: f(f(x)) === f(x) を確かめる。

---

手順 3: 直し方 —— 比較キーだけを冪等にする

slice の後でもう一度 trim する。これで20字（空白付き）でも19字でも同じキーになる。

function itemHeadKey(value) {
  return normalize(value).slice(0, 20).trim();   // slice → trim の順にする
}

function matchesAnchor(anchor, candidate) {
  return itemHeadKey(anchor.itemHead) === itemHeadKey(candidate.itemHead);
}

⚠ ハッシュを一緒に変えてはいけない

buildRowAnchor が返す hash を、同期処理が**重複判定キー（unique 制約）**として DB に保存している場合が多い。itemHead の作り方を変えて hash がずれると、

次回の同期で既存レコードを「新規」と誤認 → 重複行が大量に生まれる

直すのは「照合の寛容化」だけにする。保存値のフォーマットと hash 計算には触らない。 既存データはそのまま救われる（20字・空白付きの保存値も、trim 後は新しいキーと一致するため）。

---

手順 4: テスト（この3本を必ず入れる）

// 1. 実障害の入力で往復して一致すること
const saved = buildRowAnchor({ ...meta, itemName: '<20字目が空白になる実データ>' });
const restored = buildRowAnchor({ ...meta, itemName: saved.itemHead });  // 復元経路を再現
expect(matchesAnchor(restored, { ...meta, itemHead: '<シートの生の品名>' })).toBe(true);
// 修正前はここが false だった、とコメントで残す

// 2. hash と itemHead の保存形式が変わっていないこと（固定値で pin する）
expect(saved.itemHead).toBe('<現在の値>');
expect(saved.hash).toBe('<現在の値>');
// 将来 hash 計算を変えたらこのテストが落ちる＝重複行事故の予防線

// 3. 冪等性そのもの
expect(itemHeadKey(itemHeadKey(x))).toBe(itemHeadKey(x));

---

手順 5: 検証は「本番の実データ」で締める

単体テストが緑でも、本番のシートで実際に1行だけ特定できるかを確認するまで直ったと言わない。 読み取り専用のスクリプトで十分:

// 本番の認証情報で実シートを全行読み、修正後の matchesAnchor で走査する
const hits = [];
rows.forEach((r, i) => {
  if (matchesAnchor(anchor, {
    timestamp: r[col('C')], requester: r[col('D')],
    deadline: r[col('O')], itemHead: r[col('G')],
  })) hits.push(i + dataStartRow);
});
console.log(hits.length === 1 ? 'OK（1行だけ特定できた）' : 'NG: ' + hits.length + '件');

0件なら直っていない。2件以上なら別の危険（誤った行を上書きする）。1件であることを確認する。

---

つまずきポイントまとめ

症状	疑うところ
「登録できるのに反映されない」	書き戻しの例外が握り潰されていないか。まず本番ログのエラーコード
409 / ROW_MISMATCH なのに誰も編集していない	全行走査で0件ヒット。アンカーの照合ロジック
特定の依頼だけ失敗する	アンカー構成要素に空白・全角空白・日付書式が混ざっていないか
直したら重複行が増えた	hash を変えてしまった。保存値と hash は不変に保つ
単体テストは緑なのに直らない	実データで往復していない。本番シートに対する読み取り検証を足す

応用: 同型の罠

• 日付を 2026/08/16 と 2026-08-16 で持ち替えている（正規化が片側にしか無い）
• 大文字小文字・全角英数の正規化が build 側にしか無い
• 「読み取りは列名で解決、書き込みは列レターで固定」で別の列を見ている （同名の列が2つあるシートで特に危険）