「直したのに直らない」— 同じ画面に書き込む経路が2本あるのを見落とす

この文書が効く症状

• 利用者から報告された表示の不具合を直したのに、利用者の手元では直っていない
• テストは緑。コードを読む限り直っている。なのに再発する
• 「たまに正しく出る／たまに崩れる」という報告が続く

原因の定番は同じ場所に書き込むコードが2箇所以上あり、片方しか直していないこと。 UI を持つ業務ツールでは、人が押すボタン経由と、バッチ／API／キュー経由で、 別々の関数が同じセル・同じ行・同じ DOM を更新していることが珍しくない。

手順1: 直す前に「書き込む経路」を数える

修正対象の表示について、書き込んでいる箇所を全部列挙してから着手する。 1箇所直して終わりにしない。

# 対象の列/セル/要素に書いているコードを、関数単位で洗い出す
grep -rn "setValue\|setValues\|innerHTML\|textContent" src/ | grep -i "<対象を特定する語>"

# 「その表示を作っている定数・文言」から逆引きするのが確実
grep -rn "<画面に出ている固定文言>" src/

固定文言での逆引きが一番強い。 利用者は文言を報告してくるので、その文字列を grep すれば 書き込み箇所が全部出る。実例では、報告された文言が3ファイルに散らばっており、 そのうち主経路のほうを直し忘れていた（テストは通っていた）。

列挙したら、経路ごとに「誰が起動するか」を書き出す:

経路	起動する人・仕組み	直したか
画面のボタン	利用者が押す
ジョブキュー / ワーカー	バッチが拾う
外部からのコマンド投入	別システム・AI

利用者が報告してくる不具合は、たいてい「利用者が使う経路」で起きている。 開発者が叩きやすい経路だけ直すと、直った気になって再発する。

手順2: レイアウトの版数を、全部の経路が見ているか確かめる

画面のレイアウトを途中で変えた製品では、版数を判定して書き込み位置を変える分岐が入る。 このとき、片方の経路だけが版数を見ているという壊れ方をする。

実例（列を1つ増やした表）:

• 新レイアウト: 結果は5列目 / 状態は6列目
• 旧レイアウト: 結果は4列目 / 状態は5列目
• 版数は先頭行の隠しセルに書いたマーカーで判定する

一方の経路は正しく分岐していたが、もう一方は4列目固定で書いていた。 新レイアウトでは「説明文の列を結果で上書きし、結果の列には日時が入る」という壊れ方をする。 利用者からは「結果欄に日時しか出ない」「説明が消える」と別々の症状として報告される。

確認方法（版数判定の識別子で grep して、経路の数と一致するか数える）:

grep -c "<版数マーカーの定数名>" <経路A のファイル>
grep -c "<版数マーカーの定数名>" <経路B のファイル>

片方が 0 なら、そこが壊れている。

手順3: 分岐を1箇所に寄せる（同じ判定を2回書かない）

見つけた後、両方に同じ分岐をコピーしてはいけない。次に版数が増えたとき同じ事故が起きる。 共有ヘルパーを1つ作り、全経路をそこに通す。

/** 版数マーカーから書き込み位置を決める。判定はここにしか書かない。 */
function resolveLayout(container) {
  var marker = '';
  try { marker = String(container.readMarker()); } catch (e) {}
  var isNew = marker === '<新レイアウトのマーカー>';
  return { isNew: isNew, resultIndex: isNew ? 5 : 4, statusIndex: isNew ? 6 : 5 };
}

/** 結果・日時・状態の書き込みは必ずこの関数を通す。 */
function writeOutcome(container, row, text, timestamp, status, links) { /* ... */ }

旧レイアウトの挙動は1バイトも変えないことを回帰テストで固定する。 移行が終わっていない利用者がいる前提で直す。

手順4: 「別の場所を見ろ」と書く前に、そこに在ることを確認する

もう一つの定番バグ。処理の最後に

完了（詳細は ◯◯ の一覧を参照）

のような案内文を無条件で書く実装がある。しかし記録処理が失敗を握りつぶす作りだと、 記録されていないのに「見に行け」と書く。利用者は指示どおり見に行き、何も無い、と報告してくる。

直し方は文言の変更ではなく条件分岐の追加:

var url = resolveRecordUrl(recordId);   // 失敗時は空文字を返す。例外を投げない
if (url) {
  writeOutcome(container, row, '完了', [{ label: '◯◯を開く', url: url }]);
} else {
  // 存在しない場所へ案内しない
  writeOutcome(container, row, '完了（この処理は成果物リンクを返しません）', []);
}

あわせて、記録関数の戻り値に書き込んだ行番号を数値で返させると、 案内をその行への直リンクにできる。'appended' のような文字列を返す枝があると呼び出し側で使えない。

手順5: 直った証拠は「実データの読み戻し」で取る

テストが緑でも、利用者の画面が直った証拠にはならない。次まで実測する。

1. 変更を本番へ反映し、反映先から読み戻してその変更が入っていることを確認する （デプロイコマンドの成功出力は反映の証拠にならない）
2. 画面を再生成する処理を実際に起動し、戻り値が成功であることを確認する
3. 実際のセル・要素の値を読み戻し、期待した位置に期待した内容が入っているか突き合わせる
4. 可能なら2件以上で確認する。1件だと、たまたまその条件でしか通らない実装を見逃す （実例では、日付が単日の案件と期間の案件で表示分岐があり、2件見て初めて両方を確認できた）

手順6: 画面は自動では作り直されないことがある

新しい行や新しいボタンを足しても、既存の画面が自動で作り直されるとは限らない。 定期的な再生成の仕組みがあるか確認し、無ければ明示的に再生成を流す。

• 再生成が「1回の実行で N 件まで」という上限を持つことがある（実行時間制限の対策）。 全件に行き渡らせるには繰り返し起動する
• 戻り値の「残り」がグローバルな残数とは限らない。「今回処理しなかった数」であることがある。 ソースを読んで意味を確かめる。読まずに残数と解釈すると、終わっていないのに終わったと報告する
• 再生成の対象が絞り込まれていることがある（非表示のものを除く、現役の一覧に無いものを除く 等）。 総数と対象数が一致しないときは、差が何なのかを説明できるまで調べる

やってはいけないこと

• 報告された症状だけを見て、最初に見つけた1箇所を直して完了とする
• 両方の経路に同じ分岐をコピーする（次の版で必ず同じ事故が起きる）
• 案内文だけ書き換えて、条件分岐を入れない
• 「テストが N 件通った」を完了の根拠にする。通ったテストが、利用者の使う経路を通っていないことがある