# 「送らなかった行はゼロ」で在庫が消える事故を防ぐ — 全件置換APIに部分入力を通す前の設計 在庫・棚卸・名簿・シフトなど「全件を書き直す」APIに、現場が**一部だけ**入力したデータを渡すと、**入力しなかった行が静かにゼロ（または空）で上書きされる**。実際に起きた事故と、その復旧・恒久対策・回帰テストまでを型にしたもの。 対象読者は、業務システムのバックエンドに「実数を確定する」系のエンドポイントを持たせている人。フレームワーク・言語は問わない（例は表計算をデータストアにした構成だが、RDB でも同型）。 --- ## 1. 事故の形（まずこれを自分のコードで探す） 事故は次の3つが揃うと起きる。 1. **サーバ側**: 確定APIが「有効な拠点 × 全カテゴリ」を必ず書き、リクエストに含まれなかった組み合わせを `0` で埋める 2. **画面側**: 入力フォームが全拠点分の行を一度に表示し、まとめて送信する 3. **現場**: 担当者は自分の拠点だけを数え、他拠点の行は**触らずに既定値のまま**送信する 担当者にとって他拠点の行は「触っていない空欄」でしかないが、サーバから見ると `0` と区別できない。結果、数えていない拠点の在庫が全部消える。 **この事故は単体テストに出ない。** テストは「送った行が正しく保存されるか」を見るので、「送らなかった行がどうなるか」を誰も書いていない。 ### 自分のコードで探すときの目印 ``` // 危険: 入力に無いキーを 0 で埋めている activeSites.forEach(site => { categories.forEach(cat => { const qty = input[key(site, cat)] || 0; // ← ここ rows.push([id, date, site, cat, qty]); }); }); ``` `|| 0` / `?? 0` / `get(key, 0)` / `COALESCE(x, 0)` のように、**「キーが無い」と「値がゼロ」を同じに扱っている箇所**が該当する。 --- ## 2. 設計の原則 **書き込みAPIを作るときは「送られてこなかったものをどう扱うか」を必ず決めて、コードに書き残す。** 省略＝ゼロは、暗黙のまま放置すると必ず事故になる。選択肢は3つ。 | 方針 | 挙動 | 向く場面 | |---|---|---| | A. 据え置き | 送られなかったキーは**現在の値をそのまま**書く | 部分入力が前提の業務（拠点ごとの棚卸） | | B. 明示必須 | 全キーが揃っていなければ **400 で拒否** | 全件を一度に確定する運用（月次締め） | | C. 部分更新に分ける | 全件置換APIと部分更新APIを**別エンドポイント**にする | 両方の運用が併存する場合 | 現場が一部だけ数える運用なら **A** が正解。以下は A の実装。 ### A の実装で外してはいけない点 ``` // 送られてきたキーを記録する const submitted = {}; input.rows.forEach(r => { submitted[key(r.site, r.category)] = true; }); // ★ 現在値の算出は「書き込む前」に行う // 書いた後に読むと、書いたばかりの自分自身を基準点にしてしまう const current = estimateCurrentState(data, input.date); // 送られなかったキーは現在値を据え置く activeSites.forEach(site => { categories.forEach(cat => { if (submitted[key(site, cat)]) return; rows.push({ site, category: cat, qty: clampToValid(current[site][cat]) }); }); }); ``` **落とし穴が2つある。** 1. **現在値の算出タイミング**。確定処理の中で「今の在庫」を求める関数を呼ぶ場合、**書き込みより前**に呼ぶこと。後で呼ぶと、いま書いた行を基準点にして値が固定され、据え置きが機能しない。 2. **推定値がバリデーションを通らないことがある**。在庫推定は「実績が入力過多で負になる」ことを意図的に許す設計になっていることが多い。一方で書き込み側は「0以上の整数」を要求する。据え置き値は書き込み側の制約に合わせて丸める（`max(0, round(x))`）。丸めが起きたことを警告として返すかは運用次第。 --- ## 3. 事故後の復旧手順（データを消してしまってから読む人向け） **元の行を消したり直接書き換えたりする前に、次の順でやる。** ### 3-1. まず「保存されたのか」を本番データで確認する 現場からの報告は「反映されていない」という形で来ることが多い。これを**保存の失敗**と読むと、正常なデータを触って壊す。**先に本番の実データを read-back して、保存の有無を確定させる。** このとき、報告の文面（「反映されない」）と実際の障害（「他拠点が消えた」）が**別物**であることがよくある。読んだデータを全部見て、報告されていない異常も探すこと。 ### 3-2. 履歴が追記型なら「正しい値でもう1本入れる」 棚卸のように「最新の1件を基準点にする」設計なら、**行を消さずに正しい実数でもう1件登録するだけで復旧できる**。同じ日付でも、レコードIDに時刻を含めていれば新しい方が最新として採用される。 - 数えた拠点 → 実測値をそのまま - 数えていない拠点 → 事故前の最新値をそのまま この方法は**元の行を触らない**ので、間違えてもやり直せる。行の物理削除は最後の手段。 ### 3-3. 派生パラメータの汚染を確認する 確定処理が**副作用として学習パラメータを更新している**ことがある（棚卸から消費比率を逆算する等）。在庫を戻しても、比率は事故時の値のまま残る。設定保存APIで明示的に戻すこと。**戻したあと、パラメータの「出典」表示が実態と合っているかも確認する**（「実測由来」と表示されたまま手動値が入っていると、次に読む人が誤解する）。 ### 3-4. 誤登録行を消すなら、消す機能を先に作る 管理コンソールから手で行を消させるのは事故の元。**IDを指定して削除するコマンドを1つ実装し、それを通して消す。** 最低限のガードを入れる。 ``` if (!targetId) throw new Error("IDを指定してください"); const remain = rows.filter(r => r.id !== targetId); if (remain.length === rows.length) throw new Error("見つかりません: " + targetId); if (remain.length === 0) throw new Error("全件削除はできません"); ``` 削除後は必ず read-back して、**削除によって他の値が変わっていないこと**を確認する。 --- ## 4. 画面側の恒久対策 サーバを直しても、**入力する人が拠点を取り違える**リスクは残る。 1. **一度に確定するのは1拠点だけにする**。フォームの先頭で拠点を1つ選ばせ、その拠点の行だけを表示・送信する。他拠点の行を DOM に置かない（置くと、送信時のセレクタが拾ってしまう事故が起きる） 2. **選択中の拠点を、色と文字の両方で示す**。拠点ごとに色を割り当て、①プルダウン本体 ②その下の帯 ③表の各行の拠点名 ④表全体の縁 を同じ色で揃える 3. **色は「そのデータが扱っている色」と被らせない**。商品の色や状態色（赤=危険/緑=正常）を画面が既に使っているなら、拠点にはそれ以外の色相を使う。同系色を当てると区別の役に立たず、かえって取り違えが増える 4. **色だけに意味を持たせない**。「いま入力しているのは ○○拠点 です。他の拠点の在庫は変更されません。」のように、選択中の対象を必ずテキストで出す（色覚特性への配慮でもあり、思い込みの防止でもある） 5. **拠点の色は設定項目にしない**。拠点リストの並び順からパレットを機械的に割り当てる。設定項目を増やすと、そこ自体が新しい間違いの種になる 6. **確認ダイアログに対象名と影響範囲を書く**。「『○○拠点』の在庫をこの内容で確定します。他の拠点の在庫は変更しません。」 ### 保存後に画面を更新し忘れない **同じ画面内に「保存後に再読込するボタン」と「しないボタン」が混在すると、しない方が「保存できていない」と報告される。** 実際は保存されているのに、画面が保存前のスナップショットを表示し続けるだけ。書き込み系のハンドラを追加したら、再読込をセットで入れる。レンダリングだけを見るテストではこの抜けは検出できないので、レビューで「保存後に画面はどう変わるか」を必ず問うこと。 --- ## 5. 回帰テスト（ここまでやって初めて再発が止まる） ### サーバ側（単体テスト） **「送らなかったキーがどうなるか」を書く。** これが無いと同じ事故が戻ってくる。 ``` // 2拠点を有効にし、拠点Bにだけ在庫がある状態を作る // 拠点Aだけを数えて確定する const sent = captureWritePayload(() => submitCount({ date: "...", rows: [{ site: "A", category: "X", qty: 50 }] }) ); const b = sent.rows.find(r => r.site === "B" && r.category === "X"); assert.ok(b, "数えていない拠点の行も書かれること"); assert.equal(b.qty, 500, "数えていない拠点は据え置き、0にしない"); // ← 事故の再現 assert.equal(sent.rows.find(r => r.site === "A").qty, 50); assert.equal(result.breakdown.length, 1, "内訳は数えた拠点だけ"); ``` ### 画面側（DOM を実際に描いて判定） ヘッドレスDOMでフォームを描画し、次を判定する。 - 表の行数が**選択中の1拠点分だけ**であること - 全行の `data-site` が選択中の拠点と一致すること（他拠点の行が紛れていない） - 拠点を切り替えると、行がその拠点のものだけに入れ替わること - プルダウン・帯・表の縁に**同じ拠点色クラス**が付き、切り替えで**まとめて入れ替わり、切替前のクラスが残らない**こと - 帯のテキストに選択中の拠点名が含まれること 「切替前のクラスが残らない」を明示的に見ること。クラスを add するだけで remove を忘れる実装が通ってしまう。 --- ## 6. チェックリスト - [ ] 書き込みAPIで「入力に無いキー」と「値がゼロ」を同じに扱っていないか（`|| 0` を全部見る） - [ ] 省略時の方針（据え置き / 拒否 / 別API）をコードのコメントに書いたか - [ ] 現在値の算出は書き込みの**前**に行っているか - [ ] 据え置き値は書き込み側のバリデーションを通る形に丸めているか - [ ] 一度に確定する対象を1つに絞り、他の対象を DOM に置かない作りか - [ ] 選択中の対象を色**と**テキストの両方で示しているか。その色は既存の意味色と被っていないか - [ ] 書き込み後に画面を再読込しているか - [ ] 「送らなかったキー」のテストと、DOM の切り替えテストがあるか - [ ] 誤登録を消す手順が、手作業ではなくコマンドとして存在するか ---