RetailBrain README

消滅期限のある在庫（惣菜・施術枠）について「今いくらで売るべきか」を限界利益と機会費用から算出し、 現場の一律ルールとの利益差を比較する単一ページのシミュレータ。計算はすべてブラウザ側で完結する。 外部APIへの接続もデータベースもない。

1. 動作環境

2. セットアップと起動

npm install
npm run dev        # http://localhost:3000 を開く

環境変数は使わない。.env は不要で、APIキーの類も持たない。 データは data/units.ts（12商材の原価構造）と data/demand.ts（来店強度カーブと既定パラメータ）に 直接書かれている。

2-1. コードの置き場所

3. 画面の使い方

単一ページを上から下へ読むと結論に到達する構成になっている。7つの領域がある。

3-1. 領域1 — 結論バナー

エンジンが現場の一律ルールに対して純限界利益をどれだけ上回ったかを最初に出す。 差が小さいときは「ほぼ互角」と表示し、優位として語らない。

3-2. 領域2 — 商材選択

物販（STOCK。惣菜・弁当・刺身）とサービス枠（CAPACITY。施術枠・座席）をタブで切り替え、12商材から1つ選ぶ。 両者を同じ型で扱えること自体がこのシステムの主張なので、切り替えても画面の構造は変わらない。

3-3. 領域3 — 原価構造

定価・変動費・追加販売コスト・廃棄費用・初期在庫・消滅時刻。その場で編集できる。 数字を変えると以降の領域がすべて再計算される。

3-4. 領域4 — いま出す判断

選んだ時刻での推奨価格・値引率・動的下限・必要販売増加率と、日本語の根拠文。

動的下限は「今夜この1個をどうするか」を問う指標である。 STOCK で廃棄費用が追加販売コストを上回る商材では下限がマイナスになる。 処理費を払って捨てるより 0 円で配るほうが得な領域が存在する、という意味であり、表示上も握りつぶしていない。 ただしすべての商材で負になるわけではない。既定データでは、手作りコロッケは 8 − 8 = 0 円、 彩り野菜サラダは 8 − 7 = +1 円で、下限は負にならない。

必要販売増加率は「この商売として値引きが割に合うか」を問う別の時点の指標で、 仕入原価を含んだ変動費で計算する。限界利益率40%の商品を10%引きするなら 10 / (40 − 10) = 33% の販売増がなければ利益は減る。 下限と必要販売増加率は時点が違うので、同じ枠に並べて読まないこと。

3-5. 領域5 — 3ポリシーの比較グラフ

累積純限界利益と在庫推移を並べる。3ポリシーは同一シードの同一乱数系列で回しているので、 線の差はポリシーの差であって乱数の差ではない。

3-6. 領域6 — 感度分析（ORACLE と MISSPECIFIED）

弾力性・来店強度・廃棄費用をスライダーで動かし、エンジンが一律ルールを上回る領域と下回る領域の境界を出す。 「自分で決めた前提の下で自分のエンジンが勝った」では説得力がないため、前提が外れる範囲まで含めて示す。 モードの切り替えがこの領域の中心にある。

既定データの唐揚げ弁当では、ORACLE は観測した弾力性の全域で一律ルールを上回った。 MISSPECIFIED では、真の弾力性がおよそ −0.78 より弱くなると一律ルールを下回る （400シード×独立5ブロックで −0.768 〜 −0.812）。整体では MISSPECIFIED でも観測範囲の全域で上回った。 限界利益率が構造的に高く、値引きの下振れが小さいためである。

画面は境界のスカラー値だけでなく負けている区間も描く。 エンジンと一律ルールの差は軸に対して単調ではなく、一度負けてからまた勝ちに戻る形が実際に現れるため、 1つの数値だけでは「その先はずっと負け」という誤読を生む。

3-7. 領域7 — 前提の明示

需要モデルの式、使っている弾力性の値と出典、仮値であるパラメータのバッジ、主張しないと決めていることを常時表示する。 折りたたまない。隠すと疑われ、出すと確かめられる、という判断による。

4. パラメータの意味

需要モデルは次の形をしている。乱数はポアソン分布で、平均が下の q になる。

q(p, t) = arrivalCurve[t] × baseQty × (p / listPrice) ^ ε(t)
ε(t)    = elasticity × (1 + elasticityTimeAmp × (1 − 残スロット比))

5. 既知の限界

ここが最も重要な節である。以下はすべて実測に基づく。

5-1. 合成データである

実店舗のPOSデータではない。ただしこれは実データが手に入らないための代用ではない。 「同じ日に3つのポリシーを同時に試す」という反実仮想は実データでは原理的に取れないため、 ポリシー比較には合成データが必要になる。

したがって主張できるのはポリシー間の相対比較と、その比較が成立する条件範囲だけである。 廃棄ロスが何%減る、といった絶対的な効果量は主張の対象にしない。

5-2. 弾力性は推定していない

このシステムは弾力性を外部から与えられた値として受け取る。データから推定していない。 よって需要予測の精度は主張の対象外である。予測精度を評価指標に置いていないのも同じ理由による。 値引き・発注の意思決定は、欠品コストと過剰コストが非対称な構造をしており、 予測精度が上がっても利益が下がることが起こりうる。

5-3. 文献的裏付けのない仮値が2つある

サービス枠の結果はこの仮値に依存している。λ を 0 にすると時間に依存しないモデルに退化するので、 仮定の効き方はスライダーで確かめられる。

5-4. 平均では上回るが、1日単位では下回る日がある

これが最も誤解されやすい点である。既定の一律ルール（消滅120分前に一律30%引き）に対して、 400シードの対応のある差で測ると12商材すべてで95%信頼区間の下限が正になった。 それでも1日単位で見ると下回る日が一定の割合で存在する。

物販は 8.0〜15.3%、サービス枠は 9.3〜30.8% の日で一律ルールを下回った。 サービス枠のほうが高いのは、1日の枠数が少なく（4〜20枠）1件の売れ方の影響が大きいためである。 平日ランチ席が 9.3% と低いのは、20枠あり消滅時刻が早く、物販に近い挙動になるからである。

5-5. 感度分析の境界値そのものにばらつきがある

画面に出る境界は推定値であって確定値ではない。唐揚げ弁当の MISSPECIFIED で、 独立した乱数ブロックごとに境界を測り直すと次のように振れる。

落ち着く先はおよそ −0.78 だが、画面の既定シード数では境界が ±0.2 程度動く。 境界は「この辺りで勝敗が入れ替わる」という目安として読むもので、小数点以下2桁を根拠にした議論には使えない。

5-6. 「在庫が減るほど残す価値が上がる」は全域では成り立たない

エンジンは動的計画法で「この1個を残す価値」を求めている。傾向としては在庫が少ないほどこの価値は高い （唐揚げ弁当のあるスロットで、在庫1個なら609円、在庫40個なら272円）。 しかし隣り合う在庫数で比べると858点中31点（3.6%）で逆転する。 最大の逆転はスロット20・在庫38個で、74.23円から169.41円へ跳ねる。

これは数値誤差ではない。値引率が5%刻みの離散的な選択肢であるため、在庫が1個増えた瞬間に 最適な値引率が刻みの上で飛び、増分価値が不連続に変わることによる構造的な性質である。 画面で「在庫が減るほど残す価値が上がる」と単調に説明すると、在庫が多い領域で実際の数値と食い違う。

5-7. スコープ外

外部APIとの接続、公共データ基盤、機械学習による需要予測、顧客・スタッフ向けアプリ、EC機能、 外部メッセージング連携、認証・マルチテナント・データベース永続化は範囲外である。 固定費配賦は表示のみで、値引き判断のロジックには入れていない。 入れた時点で「全部原価を回収できる価格でしか売らない」という発想に戻り、消滅期限付き在庫を扱えなくなるためである。

6. テストの構成

テストの期待値は仕様として扱う。実装に合わせて期待値を書き換えることはしない。 期待値のほうが誤っていると判断した場合は、根拠を実測で示したうえで期待値を直す。