KURA — 要件定義書 兼 Claude Code 実装指示書

版数 2.0（RELATE 準拠構成 / DBレス / 記事埋め込み型デモ）／ 作成日 2026-08-24 ／ 発行 ソウゾウ合同会社 用途 SEO記事「【デモで試せる】Claude Codeで在庫管理システムを自作する方法と費用｜動画つき資料【2026年】」に組み込む実演デモ

このドキュメントの使い方（Claude Code へ）

これ1枚が、規約・仕様・タスクのすべて。リポジトリ直下に CLAUDE.md として置き、毎回読み込むこと。

• 実装は「12. 実装タスク」の順に進める。フェーズを飛ばさない。
• 各タスクの括弧内は要件ID。着手前に該当章を読むこと。
• 仕様がここに書かれていない場合は、推測で実装せず質問する。
• スコープ外（3章 Won't have）は、思いついても実装しない。
• 「デモだから」を理由に品質を落とす判断はしない。

姉妹プロジェクトとの関係 HIREBASE（求人）／ RELATE（顧客管理）／ CASTA（動画配信）／ FIELDPIN（位置情報）／ KANADE（音楽）／ MIWAKE（画像認識）／ KAMIWAZA（美容室予約）に続くシリーズ。並べて「同じテンプレ」と思われた時点で失敗。 **特に RELATE との差別化に注意。**どちらも「白背景・高密度・業務システム」だが、 RELATE＝罫線と等幅数字（Roboto Mono）で表を読ませる／藍 KURA＝表の各行に在庫の水位バーを描く／ティール＋アンバー、数値は縦長（Roboto Condensed） 8章のデザイン要件は意図的に別方向に振っている。トークンを流用しないこと。

目次

1. プロジェクト概要
2. アーキテクチャ方針
3. スコープ定義
4. ロールとデモ切替
5. 画面一覧とユーザーフロー
6. 機能要件
7. データ設計
8. デザイン要件
9. 技術要件・ディレクトリ構成
10. 非機能要件
11. 費用設計
12. 実装タスク
13. 受入基準

1. プロジェクト概要

背景と目的

「在庫管理システムを作りたい」という相談の背景は、ほぼ次のいずれか。

• Excelで在庫表を運用しているが、更新が追いつかず、誰も数字を信じていない
• 在庫はあるのに欠品する。倉庫にはあるのに売れない
• 棚卸のたびに大きな差異が出て、原因が追えない

この領域には、最初に共有すべき事実が2つある。

事実①：システムを入れても、理論在庫と実在庫は必ずズレる

記録漏れ、破損、誤出荷、紛失、返品の処理漏れ——ズレは必ず生まれる。「システムを入れれば在庫が合う」は嘘。

正しい目標は「ズレをゼロにする」ではなく、**「ズレを早く見つけて、原因を特定して、直せるようにする」**こと。だから在庫管理システムの本体は、在庫数を表示する画面ではなく、入出庫の履歴と棚卸の仕組みにある。

事実②：「在庫数」は1つではない。4つある

「欠品と過剰在庫が同時に起きている」会社は、ほぼこの4つを分けて持っていない。

KURA はこの2つの事実を前提に設計する。

プロダクト定義

プロダクトコンセプト

「在庫数を書き換えない。出来事を記録する。」

KURA は在庫数を直接更新しない。入庫・出庫・移動・調整という出来事（トランザクション）を積み上げ、その合計として在庫を算出する。だから「なぜこの数になったか」が常に遡れる。差異が出たとき、原因に辿り着ける。

デモとしての成功条件

1. 4つの在庫数が常に見える — 実在庫・引当済・有効在庫・入荷予定が、同じ画面に並んでいる
2. 在庫が「積み上がる」ことが分かる — 履歴を開くと、現在庫がどの取引の合計かが追える
3. 差異が体験できる — 棚卸で数を入れると差異が出て、原因を分類し、承認して初めて在庫が動く
4. ロールで見え方が変わる — 現場担当は自拠点だけ、原価は在庫管理者以上のみ
5. 速い — バーコードを連続で打っても止まらない
6. リセットできる — 誰が触った後でも初期状態に戻せる

2. アーキテクチャ方針

基本方針

バックエンドとデータベースを持たない。すべてブラウザ内で完結させる。

なぜこの構成にするか

• LPデモとして最適 — 訪問者は登録もログインもせずに、全機能を即座に触れる
• 自社の商品マスタをCSVで投入して試せる — データが外に出ないため、営業上かなり強い
• 開発速度 — 認証・APIの実装が不要になり、在庫ロジックとUIの作り込みに全時間を投下できる
• 運用コストゼロ — Vercel の静的配信のみ

在庫算出の原則（最重要の設計判断）

在庫数を保持しない。トランザクションから常に算出する。

在庫スナップショット = Σ トランザクション
  入庫      (+)
  出庫      (−)
  拠点間移動 (出荷元 −、到着先 +、その間は「移動中」)
  棚間移動   (棚Aから −、棚Bへ +)
  在庫調整   (± 理由コード付き)
  棚卸差異   (± 承認済みのみ)
  期首棚卸   (+ 初期在庫の投入)

この設計が、記事の技術パートの中核になる。 「在庫数を UPDATE する」設計との違いを説明できることが専門性になる。

差し替え可能性の担保

データアクセスは必ず lib/repo/ のリポジトリ層を経由すること。 コンポーネントからストアを直接触らない。

[ コンポーネント ]
        ↓  呼ぶのはこの層だけ
[ lib/repo/*.ts ]   ← 全メソッドを async にしておく
        ↓
[ lib/inventory/ ]  ← 在庫算出（純粋関数）
[ lib/store/*.ts ]  ← Zustand + persist（localStorage）
        ↓
[ lib/seed/*.ts ]   ← 初期データ

リポジトリの各メソッドは、中身が同期処理でも async で定義し、await で呼ぶ。実案件へ転用する際、リポジトリの実装だけをAPI呼び出しに差し替えれば、UI層は一行も変更せずに済む。

記事への組み込み

記事内で見せるのは「4つの在庫数が別々に動くこと」だけに絞る。 これが1章の事実②そのものであり、スクロール中に一目で伝わる唯一の絵になる。

永続化の範囲

擬似ディレイ は 150〜400ms。ただし在庫の再算出と一覧の絞り込みは 100ms以下とし、ディレイを入れない（業務システムで待たされる感覚は品質の低さとして受け取られる）。

3. スコープ定義

在庫照会・マスタ

入出庫・移動

棚卸

発注・ロット期限

分析・管理

共通・基盤

対象外（Won't have）

スコープリスク： 在庫管理は「うちはこうなんです」が最も多い領域。単位換算（ケース/ボール/バラ）・ロット規則・セット品・引当の優先順位は業種で大きく違い、在庫算出の根幹に影響する。後付けは大改修になるため、要件定義の段階で必ず洗い出す。資料PDFの「在庫要件チェックシート」はこの洗い出しのために作る。

4. ロールとデモ切替

ロール設計は、そのまま実案件での権限制御・RLS の設計根拠になる。「誰が・どのデータを・どの項目まで見られるか」を先に確定させる。

ロール定義

権限マトリクス

データスコープと項目スコープ（デモの見せ場）

在庫管理では「見える行」だけでなく「見える列」も権限で変わる。 現場担当に原価を見せない運用は一般的。

• 現場担当（東京倉庫）で在庫一覧 → 東京倉庫の 240 SKU。原価列と在庫金額列がそもそも存在しない
• 在庫管理者に切替 → 全拠点 620 SKU。原価・在庫金額・粗利が出現する
• 管理者に切替 → 設定メニューと操作ログが出現する

ロールを跨ぐ体験（必ず動くようにする）

1. 現場担当で出庫を打つ → 在庫管理者に切替 → 在庫が減り、履歴にその取引が並んでいる
2. 現場担当が棚卸で実数を入力 → 在庫管理者に切替 → 差異一覧に出る。承認するまで在庫は動かない → 承認 → 調整トランザクションが登録され、在庫が動く
3. 在庫管理者が発注を登録 → 入荷予定が増え、推奨発注リストからその商品が消える
4. 在庫管理者が引当を作る → 現場担当に切替 → 実在庫は変わらないが、有効在庫が減っている
5. 在庫管理者が発注点を変更 → 推奨発注リストの件数が変わる
6. 拠点間移動を起票 → 出荷元から減り「移動中」に計上され、入荷処理をするまで到着先に入らない

2番と4番が、このデモの核心。 1章の事実①②が体験として成立する瞬間。

デモ切替バー（F-C01）

画面上部に常時表示する固定バー。埋め込みモードでは非表示。

• 現在のロールと担当拠点の表示、3ロールの切替
• 現場担当ロール時：拠点の選択（東京／大阪の2拠点）
• 「デモをリセット」ボタン（確認ダイアログ付き）
• 元記事へ戻るリンク
• 「これはデモです。データは送信されません」の明示

デザイン上の扱い： プロダクト本体のUIとは意図的に別扱い（ダークな帯 + 小さめのタイポ）にし、「アプリの外側にある操作パネル」であることを視覚的に区別する。

5. 画面一覧とユーザーフロー

全32画面。画面IDはディレクトリ構成と 1:1 で対応させる。

在庫照会・マスタ

入出庫・移動

棚卸

発注・期限

分析・設定

主要フロー

フローA：記事の読者が「4つの在庫数」を理解する（最重要）

SEO記事を読んでいる
   ↓
記事内の埋め込み（SC-900）
   ┌────────────────────────────────────────────────┐
   │ SKU-1042 ステンレスボトル 500ml マット黒         │
   │                                                │
   │   実在庫 120 − 引当済 30 = 有効在庫 90          │
   │   入荷予定 60                                   │
   │                                                │
   │  ├─欠品─┼─発注点─┼──────適正──────┼─過剰─┤    │
   │  0      40      60             200   300      │
   │         ▓▓▓▓▓▓▓▓▓▓▓░░░ 120（うち斜線=引当30）   │
   │                    ▒▒▒▒▒ +60（入荷予定）        │
   │                                                │
   │  [ 入庫 +10 ] [ 出庫 -10 ] [ 引当 +10 ]         │
   └────────────────────────────────────────────────┘
   ↓
「引当 +10」を押す
   ↓  ★ 実在庫は 120 のまま、有効在庫だけが 90 → 80 に減る
   ★ 「棚にあるのに売れない在庫」が目で見える
   ↓
「出庫 -10」を押す
   ↓  ★ 実在庫が 110 に減り、水位バーの塗りが下がる
   ↓
「全画面で試す」→ 別タブ
   ↓
SC-010 在庫一覧 ── 620 SKU すべてに4つの在庫数と水位バーが並んでいる
   ↓
SC-012 在庫履歴 ── ★ 残高列があり、現在庫がどの取引の積み上げかが追える
   ↓
ロール切替「現場担当」→ ★ 原価と在庫金額の列が消え、拠点も絞られる
   ↓
資料ダウンロード or 元記事に戻る

フローB：棚卸で差異を見つけて直す（1章の事実①を体験に落とす）

【在庫管理者】SC-201 棚卸の開始
  対象：東京倉庫 / エリアA / 担当：現場担当2名
  ↓  ★ 開始した瞬間、対象SKUの理論在庫が凍結される
【現場担当】SC-202 カウント入力
  棚番順のリストが出る（A-01-1 → A-01-2 → …）
  バーコードをスキャン → 実数を入力（1画面で連続入力）
  ↓  ★ 未カウント件数が減っていく
  SKU-1042：理論 120 / 実数 116 と入力
   ↓
【在庫管理者】SC-203 差異一覧
  差異率が大きい順に並ぶ
  SKU-1042  理論120 → 実数116  差異 −4  差異金額 −¥5,200
   ↓
  ★ 原因分類が必須。未分類があると承認に進めない
  「破損（廃棄済み・記録漏れ）」を選択
   ↓
SC-204 承認と確定
  ★ 承認するまで在庫は動かない
  承認 → 調整トランザクション（−4 / 理由：棚卸差異・破損）が登録される
   ↓
SC-012 在庫履歴 ── ★ 履歴に「棚卸差異 −4」が並び、残高が 116 になっている
   ↓
SC-404 差異分析 ── ★ 原因別の差異金額に「破損」が積み上がる
   ↓
★ ここで伝わること：
  「在庫は必ずズレる。だから見つけて、原因を分類して、履歴に残す」

フローC：欠品と過剰発注を同時に防ぐ

SC-001 ダッシュボード ──「要発注 18件」「欠品リスク 3件」「遅延発注 2件」
   ↓
SC-300 推奨発注リスト
  判定式：有効在庫 + 入荷予定 < 発注点
  ┌──────────────────────────────────────────────────┐
  │ SKU     商品名        有効  入荷  発注点  推奨    │
  │ 1042    ボトル500ml     80    60      60    －    │ ← 入荷予定込みで足りている
  │ 2011    キャップ黒      12     0      50    88    │ ← 発注が必要
  └──────────────────────────────────────────────────┘
   ↓  ★ 「入荷予定」を見ていないと、SKU-1042 に重複発注してしまう
SC-301 発注書の作成 ── 仕入先別にまとめて、最小発注金額を確認、PDF出力
   ↓
発注登録 → ★ 入荷予定が増え、推奨発注リストから消える
   ↓
入荷日に SC-100 入庫（検品）
  バーコードを連続スキャン → 予定数との差異を記録
  ロット番号・賞味期限を入力
   ↓
SC-101 棚入れ ── 棚番を指定（同一SKUの既存棚を推奨）
   ↓
★ 実在庫が増え、入荷予定が減る
   ↓
SC-310 期限アラート ── ★ 入力した期限が近い場合、ここに現れる
   ↓
次の出庫時、SC-102 で ★ FEFO（期限が近いロットから）が推奨される

6. 機能要件

各要件はテスト仕様書の項目と1:1で対応する。「〜できること」の粒度で、判定可能な形で記述している。

6.1 在庫算出（このデモの心臓部）

6.2 一覧・検索・ビュー（業務システムの中核）

6.3 入出庫・移動

6.4 棚卸

6.5 発注・ロット期限

6.6 分析・設定

6.7 CSV入出力・デモ基盤

7. データ設計

型定義（lib/types/）

// ---- 組織・ユーザー ----
type Warehouse = { id: string; code: string; name: string; address: string; isActive: boolean }
type Location = {               // 棚番
  id: string
  warehouseId: string
  code: string                  // 'A-01-1'（エリア-列-段）
  area: string
  storageCondition: 'normal' | 'chilled' | 'frozen'
  sortOrder: number             // ★ ピッキングの巡回順
}
type User = {
  id: string
  name: string
  role: 'staff' | 'keeper' | 'admin'
  warehouseIds: string[]        // ★ 担当拠点。スコープ判定の起点
  isActive: boolean
}

// ---- マスタ ----
type Item = {
  id: string
  sku: string
  name: string
  jan?: string
  categoryId: string
  // --- 単位換算（FR-110） ---
  baseUnit: string              // 最小単位（「本」）
  packUnits: { name: string; qtyInBase: number }[]  // [{ケース,24},{ボール,6}]
  // --- 原価・売価（★ 権限で出し入れする項目）---
  cost: number                  // 移動平均原価
  price: number
  // --- 補充 ---
  reorderPoint: number
  safetyStock: number
  orderLot: number
  defaultSupplierId?: string
  leadTimeDays: number
  // --- 管理方式 ---
  isLotManaged: boolean         // ★ ロット・期限管理の対象か
  isSerialManaged: boolean
  shelfLifeDays?: number
  storageCondition: 'normal' | 'chilled' | 'frozen'
  abcClass?: 'A' | 'B' | 'C'    // 算出値だが検索性のため保持
  isActive: boolean
}
type Category = { id: string; name: string; expiryAlertDays: number; sortOrder: number }
type Partner = { id: string; kind: 'supplier' | 'customer'; code: string; name: string; leadTimeDays: number; minOrderAmount: number }
type ReasonCode = { id: string; kind: 'adjust' | 'variance'; name: string; sortOrder: number }
type Lot = { id: string; itemId: string; lotNo: string; receivedAt: string; expiryDate?: string; supplierId?: string }

// ---- ★★★ トランザクション（このプロジェクトの中核）★★★ ----
type TxnType =
  | 'receive'        // 入庫
  | 'ship'           // 出庫
  | 'transfer_out'   // 拠点間移動：出荷
  | 'transfer_in'    // 拠点間移動：入荷
  | 'move'           // 棚間移動
  | 'adjust'         // 在庫調整
  | 'stocktake'      // 棚卸差異（承認済みのみ生成）
  | 'opening'        // 期首棚卸（初期在庫の投入）(FR-703)

type Transaction = {
  id: string
  seq: number                   // ★ 連番。メモ化の世代管理に使う（INV-04）
  type: TxnType
  itemId: string
  warehouseId: string
  locationId?: string
  lotId?: string
  qtyBase: number               // ★ 常に最小単位。符号付き（入庫 +、出庫 −）
  inputQty: number              // 入力された数量
  inputUnit: string             // 入力された単位（ケース等）
  unitCost?: number             // 入庫時の単価（移動平均の計算に使う）
  reasonCodeId?: string         // ★ adjust / stocktake では必須
  refType?: 'purchase_order' | 'shipping_order' | 'transfer' | 'stocktake'
  refId?: string
  // --- 取消（FR-315）---
  reversedByTxnId?: string      // この取引を打ち消した逆仕訳
  reversesTxnId?: string        // この取引が打ち消している元取引
  // --- 監査 ---
  userId: string
  device: 'pc' | 'mobile' | 'scanner'
  occurredAt: string
  createdAt: string
  note: string
  syncState: 'synced' | 'pending'
}

// ---- 引当（★ 実在庫を動かさない）----
type Allocation = {
  id: string
  itemId: string
  warehouseId: string
  lotId?: string
  qtyBase: number               // 正の数
  refType: 'shipping_order'
  refId: string
  status: 'active' | 'released' | 'shipped'
  createdAt: string
  releasedAt?: string
}

// ---- 発注 / 入荷予定 ----
type PurchaseOrder = {
  id: string
  code: string
  supplierId: string
  warehouseId: string
  status: 'draft' | 'ordered' | 'partial' | 'received' | 'cancelled'
  orderedAt?: string
  expectedAt?: string           // ★ 遅延判定の基準（FR-507）
  lines: PurchaseOrderLine[]
  createdAt: string
}
type PurchaseOrderLine = {
  id: string
  itemId: string
  qtyBase: number
  receivedQtyBase: number       // ★ 入荷予定 = qtyBase − receivedQtyBase
  unitCost: number
}

type ShippingOrder = {
  id: string
  code: string
  customerId: string
  warehouseId: string
  status: 'draft' | 'allocated' | 'picking' | 'shipped' | 'cancelled'
  shipBy?: string
  lines: { id: string; itemId: string; qtyBase: number; shippedQtyBase: number }[]
  createdAt: string
}

type Transfer = {
  id: string
  code: string
  fromWarehouseId: string
  toWarehouseId: string
  status: 'in_transit' | 'received' | 'cancelled'
  shippedAt: string
  receivedAt?: string
  lines: { itemId: string; lotId?: string; qtyBase: number; receivedQtyBase: number }[]
}

// ---- 棚卸 ----
type Stocktake = {
  id: string
  code: string
  warehouseId: string
  scope: { areas?: string[]; categoryIds?: string[] }
  status: 'counting' | 'reviewing' | 'approved' | 'cancelled'
  frozenAt: string              // ★ 理論在庫を凍結した時刻（FR-401）
  assigneeIds: string[]
  lines: StocktakeLine[]
  approvedBy?: string
  approvedAt?: string
  createdAt: string
}
type StocktakeLine = {
  id: string
  itemId: string
  locationId?: string
  lotId?: string
  theoreticalQty: number        // ★ 凍結時点の理論在庫
  countedQty?: number           // 未入力なら undefined
  countedBy?: string
  countedAt?: string
  varianceQty?: number          // countedQty − theoreticalQty
  varianceAmount?: number
  reasonCodeId?: string         // ★ 必須（FR-406）
  note: string
}

// ---- 在庫スナップショット（★ 保存しない。常に算出）----
type StockSnapshot = {
  itemId: string
  warehouseId?: string          // 未指定なら全拠点合計
  lotId?: string
  // ★ 4つの在庫数（FR-102, INV-06）
  onHand: number                // 実在庫
  allocated: number             // 引当済
  available: number             // 有効在庫 = onHand − allocated
  incoming: number              // 入荷予定（発注残 + 移動中）
  inTransit: number             // うち移動中
  reorderPoint: number
  safetyStock: number
  status: 'stockout' | 'below_reorder' | 'normal' | 'excess'
  // --- 金額（★ 権限がない場合は含めない。SCP-03）---
  unitCost?: number
  stockValue?: number
  // --- 滞留・期限 ---
  lastShippedAt?: string
  idleDays?: number
  nearestExpiryDate?: string
  expiringQty?: number
}

// ---- 分析（算出値。ストアに保存しない）----
type TurnoverMetrics = { itemId: string; shippedValue: number; avgStockValue: number; turnover: number; idleDays: number }
type AbcResult = { itemId: string; shippedValue: number; cumulativeRatio: number; abcClass: 'A'|'B'|'C' }
type VarianceSummary = { reasonCodeId: string; count: number; varianceQty: number; varianceAmount: number }

// ---- ビュー・監査 ----
type SavedView = {
  id: string
  name: string
  target: 'stock' | 'transactions' | 'lots' | 'replenishment'
  ownerId: string
  isShared: boolean             // keeper 以上のみ true にできる
  filters: Filter[]
  visibleColumns: string[]
  sort: { field: string; dir: 'asc' | 'desc' }[]
}
type Filter = { field: string; operator: 'eq'|'contains'|'gte'|'lte'|'between'|'in'|'isEmpty'; value: unknown }
type AuditLog = {
  id: string
  actorId: string
  action: 'adjust' | 'approve_stocktake' | 'reverse_txn' | 'update_master' | 'import'
  targetType: string
  targetId: string
  changes: { field: string; before: unknown; after: unknown }[]
  createdAt: string
}

在庫算出の実装（7章の中核）

// lib/inventory/snapshot.ts
export function getSnapshot(input: SnapshotInput): StockSnapshot {
  const { itemId, warehouseId, txns, allocations, purchaseOrders, transfers, item } = input

  // ★ 在庫は必ずトランザクションの合計として算出する（INV-01）
  const onHand = txns
    .filter(t => t.itemId === itemId && matchWarehouse(t, warehouseId) && !t.reversedByTxnId)
    .reduce((sum, t) => sum + t.qtyBase, 0)

  // ★ 引当は実在庫を動かさない。有効在庫だけを減らす（FR-310）
  const allocated = allocations
    .filter(a => a.itemId === itemId && a.status === 'active' && matchWh(a, warehouseId))
    .reduce((sum, a) => sum + a.qtyBase, 0)

  // ★ 入荷予定 = 発注残 + 移動中（FR-503 の判定に使う）
  const onOrder = purchaseOrders
    .filter(po => po.status === 'ordered' || po.status === 'partial')
    .flatMap(po => po.lines.filter(l => l.itemId === itemId)
                          .map(l => l.qtyBase - l.receivedQtyBase))
    .reduce((a, b) => a + b, 0)

  const inTransit = transfers
    .filter(t => t.status === 'in_transit' && t.toWarehouseId === warehouseId)
    .flatMap(t => t.lines.filter(l => l.itemId === itemId)
                         .map(l => l.qtyBase - l.receivedQtyBase))
    .reduce((a, b) => a + b, 0)

  return {
    itemId, warehouseId,
    onHand,
    allocated,
    available: onHand - allocated,     // ★ 有効在庫
    incoming: onOrder + inTransit,     // ★ 入荷予定
    inTransit,
    reorderPoint: item.reorderPoint,
    safetyStock: item.safetyStock,
    status: judgeStatus(onHand - allocated, item),
    // 金額は _scope.ts で権限に応じて付与／除去する（SCP-03）
  }
}

シードデータ（lib/seed/）

シード作成のルール（品質を左右する）

• 実在企業名・実在商品名を使わない。 架空の商品・取引先で構成する
• 商品名を「商品A」のようなダミーにしない。 業種の世界観を持たせる（「ステンレスボトル 500ml マット黒」等）。ここが手抜きだとデモ全体が安っぽくなる
• 在庫状態を全帯域に分散させる。 欠品／発注点以下／適正／過剰／滞留が必ず存在すること
• 引当済がある商品を必ず作る。 「実在庫はあるのに有効在庫が足りない」商品がないと、1章の事実②が伝わらない
• 入荷予定がある商品を作る。 「発注済みなので発注不要」が推奨発注リストで表現されること
• 期限切れ・期限間近のロットを作る。 期限アラートが空だと機能が死ぬ
• 移動中の在庫を残す。 「どこにもない在庫」の存在を見せる
• 未承認の棚卸差異を1件残す。 ダッシュボードのアラートが動いて見える
• 差異の原因を分散させる。 差異分析のグラフに意味のあるパターンが出ること
• 遅延している発注を作る。 全部順調だとアラート機能が動いて見えない
• 日付は現在日時からの相対で生成する。固定日付を埋め込まない
• トランザクションは時系列に矛盾がないこと（在庫がマイナスになる履歴を作らない）

ストアとリポジトリ

lib/
├── types/  seed/
├── inventory/                  # ★ 在庫算出の唯一の場所。純粋関数のみ
│   ├── snapshot.ts             # ★ 4つの在庫数（FR-102）
│   ├── ledger.ts               # 履歴と残高推移（FR-106）
│   ├── valuation.ts            # 移動平均原価・在庫金額（FR-111）
│   ├── unit.ts                 # 単位換算（FR-110）
│   ├── fefo.ts                 # 期限順のロット選択（FR-308）
│   ├── replenish.ts            # 発注点判定・推奨数量（FR-503, FR-504）
│   └── status.ts               # 在庫状態の判定
├── analytics/                  # 回転率・滞留・ABC・差異・欠品（純粋関数）
├── csv/                        # インポート（列マッピング・検証・無害化）／エクスポート
├── scan/                       # バーコード入力（キー入力・カメラ）
├── query/                      # 絞り込み・ソート・ビューの適用
├── store/  { session, data, settings, sync, ui }
└── repo/                       # ★ コンポーネントが触るのはここだけ
    ├── _delay.ts
    ├── _scope.ts               # ★ データスコープ + 項目スコープ（SCP-01）
    ├── stock.ts  items.ts  lots.ts  transactions.ts
    ├── receive.ts  ship.ts  allocations.ts  transfers.ts  adjust.ts
    ├── stocktakes.ts  purchaseOrders.ts  views.ts  analytics.ts  settings.ts

リポジトリ層の規約（厳守）

• 全メソッドを async で定義する。中身が同期でも例外なく
• 戻り値は { ok: true; data: T } | { ok: false; error: string } に統一する
• コンポーネントから Zustand ストアを直接参照しない。 読み取りも書き込みもリポジトリ経由
• 在庫算出を lib/inventory/ の外に書かない（INV-01）
• 在庫を変えるのはトランザクションの追加だけ（INV-02）
• スコープ適用（_scope.ts）を全メソッドが必ず通す。 ここが実案件で権限制御・RLS に置き換わる箇所
• 原価・在庫金額は、権限がない場合オブジェクトから除外して返す（SCP-03）
• 派生値（在庫数・回転率・ABC区分・差異金額）はストアに保存せず算出する
• 在庫の再算出と一覧の絞り込みに擬似ディレイを入れない

8. デザイン要件

アートディレクション

「表の中に、在庫の水位を描く」

在庫管理システムの画面には、常に数字が並ぶ。しかし人が知りたいのは数字そのものではなく、「多いのか、少ないのか、あとどれくらいか」である。KURA は一覧のすべての行に在庫の水位バーを埋め込み、欠品線・発注点・現在庫・入荷予定を1本の帯で読ませる。

• 数字と図を同じ行に置く。 表とグラフを別画面に分けない
• 色は在庫状態のためだけにある。 通常状態はほぼ無彩色
• 産業的なトーン。 倉庫・工場の色（セメントのグレー、ティール、注意喚起のアンバー）
• 数値は縦長書体で。 桁数の多い数量が並んでも列幅を食わない

RELATE との差別化（最重要） どちらも「白背景・高密度・業務システム」だが、方向を分ける。 RELATE：罫線と等幅数字（Roboto Mono）で表を読ませる。藍。色は警告のためだけ。 KURA：表の各行に水位バーを描く。ティール＋アンバー。数値は縦長（Roboto Condensed）。 並べたときに「同じ管理画面」と見えたら失敗。

カラートークン

:root {
  /* 産業的なクールグレー */
  --bg:        #EEF0F1;   /* ページ背景（セメント） */
  --panel:     #FFFFFF;   /* テーブル・カード */
  --panel-alt: #F5F7F8;   /* 縞・ヘッダー */
  --line:      #DBDFE2;   /* 罫線 */
  --line-hi:   #B9C0C5;   /* テーブルヘッダー下 */

  --ink-900:   #10161C;   /* 見出し・本文・数値 */
  --ink-600:   #4E585F;   /* 補助テキスト */
  --ink-400:   #8B959C;   /* ラベル・非活性 */

  --primary:   #0E7C86;   /* 主要CTA・選択状態（ティール） */
  --primary-d: #0A5C64;
  --primary-50:#E2F0F1;

  /* ★ 在庫状態。これ以外の色を意味づけに使わない */
  --st-stockout: #B3352B;   /* 欠品 */
  --st-low:      #C9821B;   /* 発注点以下（産業安全色のアンバー） */
  --st-normal:   #3E7A5E;   /* 適正 */
  --st-excess:   #6B6FA8;   /* 過剰 */
  --st-idle:     #8B959C;   /* 滞留（無彩色） */

  /* ★ 水位バーの構成色 */
  --gauge-track:    #E4E8EA;   /* 目盛の地 */
  --gauge-onhand:   #0E7C86;   /* 実在庫（塗り） */
  --gauge-allocated:repeating-linear-gradient(  /* ★ 引当済（斜線） */
      45deg, transparent 0 4px, rgba(14,124,134,.30) 4px 8px);
  --gauge-incoming: #A9C6C9;   /* 入荷予定（淡色） */
  --gauge-reorder:  #C9821B;   /* 発注点ライン */
  --gauge-safety:   #B3352B;   /* 安全在庫ライン */

  /* 期限 */
  --exp-expired: #B3352B;
  --exp-near:    #C9821B;
}

配色ルール

• 通常状態の行に色を持たせない。 色がついている行は「対応が必要な行」だけ
• 引当済は色ではなく斜線で表す。 「実在庫の中に含まれるが、使えない部分」であることを、塗りとテクスチャの違いで示す
• 過剰在庫を赤にしない。 赤は欠品と期限切れにだけ使う
• カテゴリに固有色を割り当てない。8色のバッジが並ぶ画面にしない

タイポグラフィ

Roboto Condensed が KURA の視覚的な指紋。 RELATE の Roboto Mono（等幅）とは字幅が明確に違い、並べたときに一目で区別できる。

レイアウトとスペーシング

主要コンポーネント仕様

インタラクション要件（業務システムの肝）

モーション

prefers-reduced-motion: reduce 時は全アニメーションを無効化する。

アクセシビリティ（WCAG 2.1 AA）

ライティング規約

9. 技術要件・ディレクトリ構成

技術スタック（固定・勝手に変更しない）

上記以外のライブラリを入れる前に必ず提案し、承認を得ること。特に会計・在庫計算系のライブラリと、重量級チャートライブラリの導入は禁止。

ディレクトリ構成

/
├── CLAUDE.md
├── app/
│   ├── layout.tsx                  # アプリシェル（サイドバー・ヘッダー・デモ切替バー）
│   ├── page.tsx                    # SC-001 / SC-900（?embed=1）
│   ├── stock/  items/[sku]/        # SC-010〜013
│   ├── import/                     # SC-014
│   ├── locations/  partners/       # SC-020, 021
│   ├── receive/  ship/  allocations/  transfer/  adjust/   # SC-100〜121
│   ├── transactions/               # SC-130
│   ├── stocktakes/                 # SC-200〜205
│   ├── replenishment/  purchase-orders/  expiry/  lots/    # SC-300〜311
│   ├── reports/                    # SC-400〜404
│   ├── settings/                   # SC-500〜502
│   └── dev/components/
├── components/
│   ├── gauge/                      # ★ 最重要
│   │   ├── StockGauge.tsx          # 在庫水位バー（行内・詳細の2サイズ）
│   │   ├── FourNumbers.tsx         # 4つの在庫数ブロック
│   │   └── GaugeTooltip.tsx
│   ├── table/                      # DataTable, ColumnPicker, FilterBar, BulkActionBar, ViewSidebar
│   ├── scan/                       # ScanInput（常時フォーカス）, ScanLineList, CameraScanner
│   ├── domain/                     # StockStatusBadge, ExpiryBadge, LedgerRow, VarianceRow, PickingRow, MetricCard
│   ├── demo/                       # RoleSwitcher, ResetButton, GuideTour, BackToArticle
│   └── layout/
├── lib/
│   ├── types/ seed/ store/ repo/
│   ├── inventory/                  # ★ 在庫算出。純粋関数のみ
│   ├── analytics/                  # ★ 分析。純粋関数のみ
│   ├── csv/ scan/ query/ validation/ utils/
├── docs/
│   └── inventory-checklist.md      # 資料PDFの元原稿（在庫要件チェックシート）
├── e2e/
└── public/

コーディング規約

• TypeScript strict。any 禁止。やむを得ない場合は unknown + 型ガード
• ファイル名は kebab-case、コンポーネントは PascalCase
• 1ファイル300行を超えたら分割を検討する
• コンポーネントから Zustand ストアを直接参照しない。必ず lib/repo/ 経由
• 在庫算出を lib/inventory/ の外に書かない（INV-01）
• 在庫を変えるのはトランザクションの追加だけ。数量を直接更新するコードを書かない（INV-02）
• lib/inventory/ と lib/analytics/ は純粋関数のみ。 ストア・DOM に依存させず、new Date() を内部で呼ばない（INV-05）
• 派生値をストアに保存しない。常に算出する
• 数量は常に最小単位（qtyBase）・符号付きで保持し、表示時に単位換算する
• 金額計算に浮動小数点の累積誤差を持ち込まない（原価は小数第2位で丸めた整数演算で扱う）
• コミットは1タスクごと。メッセージに要件IDを含める 例：feat(inventory): 有効在庫の算出に引当を反映 (FR-102)

10. 非機能要件

実案件への転用時の注意（デモ本体の要件ではない）

商談で聞かれた際に説明できるよう記録として残す。

• 在庫の同時更新はサーバー側で守る必要がある。 トランザクションを追加するだけの設計は競合しにくいが、「有効在庫を超えないことを保証する」なら排他制御が必要。本デモの lib/inventory/ がその判定ロジックの置き換え地点になる
• 在庫は会計と繋がる。 在庫金額は決算に影響するため、原価評価の方法（移動平均／総平均／先入先出）は経理と合意してから実装する。後から変えると過去の評価額が全部変わる
• トランザクションは消さない。 監査対応上も、原因追跡上も、削除ではなく逆仕訳が原則
• 食品を扱う場合、ロットトレーサビリティが法令・取引先要求の対象になりうる。 回収時に「どのロットがどこに出たか」を遡れる設計が必要
• 本デモはデータをサーバーに送信しないため、これらの義務は発生しない。「デモである」旨は画面上に常時明示する

11. 費用設計

記事の主題の半分は「費用」。この章は実装要件であると同時に、記事本文の原稿素材でもある。

在庫管理だけの特殊事情：ハードウェア費が乗る

他のシステムと違い、在庫管理は現場で物に触る。ソフトだけでは完結しない。

②③を見積もらずに始めると、「システムはできたが現場で使えない」になる。

②の分岐：ハンディ端末か、スマホか（現場を左右する判断）

判断の目安：

• 1日に数百件スキャンする現場（出荷が多い倉庫）→ ハンディ端末が必須。 カメラでは業務が終わらない
• 1日に数十件（店舗の棚卸、少量出荷）→ スマホ + Bluetoothリーダーで足りる
• まず始めたい／小規模 → カメラのみで開始し、ボトルネックになったら追加

KURA が「キー入力を既定、カメラを任意」にしているのはこの理由（FR-303）。ハンディ端末はキーボードとして振る舞うため、キー入力を主にしておけば、ハード追加時にソフトの改修が不要になる。設計判断が将来のハードウェア選択の自由度を守っている例であり、記事で説明する価値がある。

③の分岐：見落とされやすい「マスタ整備」の工数

在庫管理システムの導入で最も工数を食うのは、実装ではなくマスタ整備。

• SKUの整理（同じ物が別コードで登録されている、廃番が混ざっている）
• 単位の統一（ケース入数がバラバラ、記録がない）
• 棚番の付与（そもそも棚に番号が振られていない）
• 初期在庫の実地棚卸（正しい数を1回作らないと、その後の在庫が全部ずれる）

KURA が初期在庫を「期首棚卸トランザクション」として投入する設計にしているのは（FR-703）、この最初の棚卸を履歴として残し、後から「どこが起点だったか」を追えるようにするため。

①の分岐：既製の在庫管理サービスがあるのに、なぜ自作するのか

この問いに答えられない案件は、受けるべきではない。 正直にそう書くことが信頼を生む。

逆に、①〜⑤のどれにも当てはまらないなら、既製サービスを使うべき。

損益分岐の計算式

既製サービスの年間コスト
  = 月額 × 12
  + 明細行数課金（もしあれば）× 年間明細数
  + アドオン費用（拠点追加・ユーザー追加）

回収年数 = （開発費 + ハードウェア費）÷（既製サービスの年間コスト − 自作の年間運用費）

Webで足りるか、ネイティブが必要か

在庫管理は、Webで足りる領域。

判断の目安： ハンディ端末をキーボードモードで使うなら Webで十分。専用SDKでの高速制御が必要な規模なら、ネイティブ（またはハンディ端末メーカーのアプリ基盤）を検討する。

デモ自体の運用コストを実測して記事に載せる

12. 実装タスク

この順に進める。フェーズを飛ばさない。 完了時は [x] に更新する。

Phase 0 — 基盤と在庫算出エンジン（4日）

0-1. 初期化

• Next.js 15 / TypeScript strict / App Router / Tailwind で初期化
• ESLint / Prettier / husky（pre-commit で lint + typecheck）
• 9章のディレクトリ構成を作成

0-2. lib/inventory/（心臓部。最初に書いてテストで固める）

• unit.ts：単位換算（ケース／ボール／バラ ⇔ 最小単位）(FR-110)
• snapshot.ts：4つの在庫数の算出（7章のコードを参照）(FR-102, INV-06)
• ledger.ts：履歴と残高推移、任意時点の在庫（FR-106）
• valuation.ts：移動平均原価と在庫金額（FR-111）
• status.ts：在庫状態の判定
• fefo.ts：期限順のロット選択（FR-308）
• replenish.ts：判定式「有効在庫 + 入荷予定 < 発注点」と推奨数量（FR-503, FR-504）
• new Date() を内部で呼ばない。現在時刻は引数で受け取る（INV-05）
• メモ化と、トランザクション追加時の無効化（INV-04, FR-107）
• 単体テストを網羅的に書く。以下を必ず含めること：
  • 引当を作ると、実在庫は変わらず有効在庫だけ減ること（最重要）
  • 発注を登録すると入荷予定が増え、入庫すると入荷予定が減って実在庫が増えること
  • 拠点間移動で、出荷元から減り「移動中」に計上され、入荷処理で到着先に加わること
  • 逆仕訳を追加すると在庫が元に戻り、かつ両方の取引が履歴に残ること（INV-03）
  • 単位換算（ケース入庫・バラ出庫）が正しいこと
  • FEFO が期限順にロットを選ぶこと
  • 移動平均原価が入庫のたびに正しく更新されること
  • 任意の過去日の在庫が算出できること
  • 推奨発注の判定に入荷予定が反映されること（実在庫だけで判定していないこと）
• 620 SKU × 2拠点 × 5,000トランザクションで 150ms以下をベンチマークで確認（NFR-04）

0-3. lib/analytics/（純粋関数）

• 回転率・滞留日数（FR-603, FR-604）／ABC分析（FR-605）
• 差異集計（原因別・拠点別・担当者別）(FR-609)／欠品・機会損失（FR-608）
• 単体テストを書く

0-4. 型とシード

• lib/types/ に7章の型定義をすべて実装
• lib/seed/ の全ファイル
• 商品名を業種の世界観を持つ架空名にする。「商品A」のようなダミーを残さない
• 在庫状態を全帯域に分散させる（欠品／発注点以下／適正／過剰／滞留）
• 引当済がある商品、入荷予定がある商品を必ず作る
• 期限切れ・期限間近のロット、移動中在庫、遅延発注、未承認の棚卸差異を作る
• トランザクションの時系列に矛盾がないこと（在庫がマイナスになる履歴を作らない）
• 日付は現在日時からの相対で生成する

0-5. ストアとリポジトリ

• lib/store/{session,data,settings,sync,ui}.ts を Zustand + persist で実装
• lib/repo/_scope.ts を最初に実装する（データスコープ + 項目スコープ）(SCP-01〜03, FR-707, FR-708)
• lib/repo/ の全モジュール。全メソッド async、Result型、スコープ適用
• 在庫を変えるのはトランザクション追加のみ（INV-02）
• スコープと項目スコープの単体テストをこの時点で書く（原価が現場担当のデータに含まれないこと）
• 在庫の再算出と絞り込みに擬似ディレイを入れない

0-6. デザインシステム

• app/globals.css にカラートークンを CSS 変数で定義（在庫状態色 + 水位バーの構成色）
• tailwind.config.ts から CSS 変数を参照するよう theme を拡張
• フォント（Noto Sans JP / Roboto Condensed）を next/font で最適化。数値に tabular-nums
• shadcn/ui を導入し、トークンに合わせて上書き
• アプリシェル（サイドバー折りたたみ、ヘッダー、パンくず）
• StockGauge.tsx：在庫水位バー（行内120px / 詳細フル幅の2サイズ）
• FourNumbers.tsx：4つの在庫数ブロック（− と = で関係を示す）
• バーの aria-label と数値の併記（A11Y-05, A11Y-06）
• 共通コンポーネント：StockStatusBadge / ExpiryBadge / MetricCard / EmptyState（2種の出し分け）／Skeleton（水位バーの位置も確保）
• prefers-reduced-motion の対応
• /dev/components にコンポーネントカタログを作成

0-7. デモ基盤

• RoleSwitcher（3ロール + 現場担当の拠点選択）(FR-706)
• デモ切替バーを固定配置。プロダクトのトークンとは別扱いのデザイン
• 「デモをリセット」(FR-709)／ロール権限外アクセス時の案内画面（FR-711）
• 元記事リンク・資料ダウンロード（FR-713）

Phase 0 完了チェック

• lib/inventory/ のテストが全パターン通る
• 「引当で有効在庫だけが減る」がテストで検証済み
• 「逆仕訳で在庫が戻り、履歴が消えない」がテストで検証済み
• ロールを切り替えると、リポジトリが返す件数と項目（原価の有無）が変わる
• 620 SKU の在庫算出が150ms以下
• /dev/components で水位バーが全パターン正しく描画される

Phase 1 — 一覧基盤と在庫照会（4日）

1-1. データテーブル基盤（ここの品質が全画面に波及する）

• lib/query/ に絞り込み・ソート・ビュー適用ロジックを実装（テスト付き）
• DataTable（TanStack Table ヘッドレス + 自前UI）。固定ヘッダー、列幅リサイズ
• 列カスタマイズ（FR-202）／複数列ソート
• FilterBar：項目ごとの条件指定（FR-203）
• 在庫状態での絞り込み（FR-204）
• URLクエリとの同期（FR-205）／ConditionChips（FR-206）
• 行選択と BulkActionBar（下からせり上がる）(FR-209, FR-210)
• 取り消し可能な操作トースト（IX-06）
• 仮想スクロール（FR-213）／密度切替（FR-214）
• キーボード操作（↑↓ Enter Space ⌘A）(IX-02)
• 数量列の右寄せ + Condensed 表示（FR-215）

1-2. 保存ビュー

• ViewSidebar：ビュー一覧、件数バッジ、ワンクリック切替（FR-208）
• ビューの保存・編集・削除。個人／共有の区別（FR-207）

1-3. 在庫照会

• SC-010 在庫一覧（4つの在庫数 + 行内水位バー）（FR-201）
• SC-011 商品詳細（4数値ブロック + フル幅水位バー + 拠点別・ロット別内訳）
• SC-012 在庫履歴（元帳）。残高列で「積み上げ」を可視化（FR-101, FR-106）
• SC-013 商品の登録・編集
• SC-020 拠点・ロケーション／SC-021 取引先
• SC-001 ダッシュボード（ロールで表示内容が変わる）(FR-601, FR-602)

1-4. CSV入出力・検索

• lib/csv/：インポート（列マッピング・検証）／エクスポート
• SC-014 インポート4ステップ（FR-701, FR-702）
• 初期在庫を「期首棚卸トランザクション」として登録（FR-703）
• 数式インジェクションの無害化（FR-704, NFR-12）
• エクスポート（FR-705）
• グローバル検索（SKU・商品名・JAN・ロット番号）(FR-211)／⌘K コマンドパレット（FR-212）

1-5. 埋め込みモード

• SC-900 埋め込みモード：1商品の水位バー + 入出庫ボタン（FR-715, 2章）
• 引当ボタンで有効在庫だけが減ることが見えること
• カメラを呼ばない（EMB-04）／アプリ内遷移をしない（EMB-05）
• 初期バンドル 60KB以下を実測（NFR-08）

Phase 1 完了チェック

• フローAが完走する（埋め込みで4つの在庫数が別々に動く → 全画面 → 履歴で積み上げが追える）
• 620行でも絞り込みが100ms以下、スクロールが60fps
• テーブルがキーボードのみで操作完遂できる
• 現場担当ロールで原価・在庫金額の列が存在しない（CSSで隠していない）

Phase 2 — 入出庫・移動・スキャン（4日）

2-1. スキャン入力基盤

• ScanInput.tsx：常時フォーカスを保つ入力欄。スキャン後もフォーカスを失わない（IX-03）
• ScanLineList.tsx：スキャンごとに行が積み上がる。同一SKUは数量 +1（FR-302）
• 各行の取り消しボタン
• スキャンの成功・失敗を aria-live で通知（A11Y-10）
• 1件あたり50ms以下の入力遅延を実測（NFR-07）
• CameraScanner.tsx（@zxing/browser、動的import・任意で有効化）(FR-303)
• 未登録バーコードの扱い（その場で登録／保留）(FR-304)

2-2. 入庫・出庫

• SC-100 入庫（検品）：発注選択、数量差異、部分入荷（FR-301）
• ロット管理対象では、ロット番号と期限の入力を必須化（FR-305）
• SC-101 棚入れ（既存棚の推奨）(FR-306)
• SC-102 出庫（ピッキング）：巡回順のリスト（FR-307）
• FEFO推奨と逸脱時の理由確認（FR-308）
• 有効在庫超過の警告（ブロックはしない）（FR-309）
• SC-103 ピッキングリスト印刷（PDF、動的import）
• SC-104 引当：実在庫を変えずに有効在庫を減らす（FR-310）

2-3. 移動・調整・取消

• SC-110 在庫移動：拠点間は「移動中」状態を持つ（FR-311）
• SC-111 移動の入荷処理／移動中一覧と滞留日数（FR-312）／棚間移動（FR-313）
• SC-120 在庫調整：理由コード必須（FR-314）
• SC-121 取消（逆仕訳の追加）。元取引に「取消済」の印を付け、履歴から消さない（FR-315）
• SC-130 トランザクション一覧（絞り込み、CSV出力）
• 全取引に担当者・拠点・日時・端末種別を記録（FR-317）

Phase 2 完了チェック

• フローCの後半が完走する（発注 → 入庫 → 棚入れ → 期限アラート → FEFO出庫）
• 4章「ロールを跨ぐ体験」の1・4・6が動作する
• 連続スキャンが止まらず、フォーカスが外れない
• 取消後も両方の取引が履歴に残っている

Phase 3 — 棚卸（3日・1章の事実①を体験に落とす）

• SC-201 棚卸の開始：対象範囲の指定、理論在庫の凍結（FR-401）
• 棚卸中も通常の入出庫を継続でき、凍結後の取引を差異計算から除外（FR-402）
• SC-202 カウント入力：棚番順リスト、バーコード、1画面で連続入力（FR-403, IX-09）
• 未カウント件数・進捗率の常時表示（FR-404）
• SC-203 差異一覧：理論・実数・差異数・差異金額・差異率ソート（FR-405）
• 原因分類を必須化。未分類があると承認に進めない（FR-406）
• SC-204 承認と確定：承認するまで在庫を動かさない。承認時に調整トランザクションを生成（FR-408）
• 承認権限の制御（カウント者の単独承認を防ぐ設定）(FR-409)
• SC-200 棚卸一覧／SC-205 棚卸履歴（差異推移）(FR-410)

Phase 3 完了チェック

• フローBが完走する（棚卸開始 → カウント → 差異 → 原因分類 → 承認 → 在庫が動く → 履歴に残る）
• 4章「ロールを跨ぐ体験」の2が動作する
• 承認前に在庫が動いていないことを確認

Phase 4 — 発注・期限・分析（3日）

4-1. 発注・期限

• 発注点・安全在庫・発注ロットの設定（FR-501）
• 発注点の推奨値の算出（リードタイム × 平均出庫 + 安全在庫）(FR-502)
• SC-300 推奨発注リスト：判定式に入荷予定を含める（FR-503, FR-504）
• 仕入先別グループ化と最小発注金額の表示（FR-505）
• SC-301 発注書の作成・PDF出力（FR-506）
• SC-302 発注一覧・入荷予定・遅延アラート（FR-507）
• SC-310 期限アラート：閾値設定、期限切れの扱い（FR-509, FR-510）／SC-311 ロット一覧
• 期限切れの廃棄登録（FR-511）

4-2. 分析・設定

• SC-400 在庫回転率・滞留（FR-603, FR-604）
• SC-401 ABC分析（パレート図）（FR-605）／SC-402 在庫金額推移（FR-607）
• SC-403 欠品分析（FR-608）／SC-404 差異分析（原因別・拠点別・担当者別）（FR-609）
• 全分析画面の期間指定（FR-610）
• SC-500 設定（理由コード・単位・期限閾値・発注点の一括設定）(FR-611)
• SC-501 ユーザー・権限（FR-612）／SC-502 操作ログ（FR-613）

Phase 4 完了チェック

• 4章「ロールを跨ぐ体験」の3と5が動作する
• 差異分析に意味のあるパターンが出ている（シードの品質確認）
• 推奨発注リストが「入荷予定込み」で判定されている

Phase 5 — オフライン・記事統合・仕上げ（3日）

5-1. オフライン

• Service Worker / PWA マニフェスト／オフライン検知とバナー
• オフラインでの入出庫記録と未同期バッジ（FR-316）
• オンライン復帰時の自動同期と進捗表示
• localStorage 上限時の圧縮処理（NFR-13）

5-2. 記事統合

• 記事側の埋め込みコードを作成し、実際の記事ページで動作確認（EMB-01〜05）
• 記事の Core Web Vitals を埋め込み前後で比較検証
• 「全画面で試す」カードの設置
• 資料PDF（在庫要件チェックシート・損益分岐計算シート）の作成とダウンロード導線
• 元記事リンク・問い合わせ導線
• GA4 イベント設定（txn_posted / allocation_created / stocktake_done / csv_imported 等）(EMB-06)
• GA4 に商品名・取引先名を送っていないことを確認（EMB-07, NFR-14）
• ?embed=1 を noindex に、デモ本体の title / description / OGP（EMB-08）

5-3. 体験の総点検

• 4章「ロールを跨ぐ体験」の6パターンをすべて手動で確認
• 全32画面を開き、空の画面が1つもないことを確認
• 空状態（データ0件／絞り込み0件）の出し分けを確認
• ガイドツアーを実装（FR-714）

5-4. アクセシビリティ監査

• axe-core を全画面に実行し、Critical / Serious を0件に
• 13px本文のコントラスト比を実測（A11Y-01）
• 水位バーの aria-label と数値併記を確認（A11Y-05, A11Y-06）
• キーボードのみで全画面・スキャン入力・棚卸を完遂
• フォントサイズ200%での確認（A11Y-12）

5-5. パフォーマンス

• PDF・グラフ・カメラを動的import に切り出し、初期バンドルを250KB以下に（NFR-09）
• 在庫算出150ms以下、絞り込み100ms以下、スキャン50ms以下を実測（NFR-04, NFR-05, NFR-07）
• 620行のスクロール60fpsを実測（NFR-06）
• Lighthouse で Performance 90 / Accessibility 95（NFR-10）

5-6. 公開と記録

• Playwright で フローA・B・C の E2E
• Vitest：lib/inventory lib/analytics lib/query lib/csv _scope のカバレッジ85%以上
• /dev/components を本番で非公開に
• Vercel へデプロイ
• トランザクション登録数の記録を開始。明細行数課金の換算も試算（COST-01, COST-02）
• 解説動画（3分）の収録：4つの在庫数 → 引当で有効在庫だけ減る → 棚卸で差異 → 原因分類 → 承認で在庫が動く → 履歴に残る
• 各フェーズのキャプチャを整理し、記事の「方法」パートの素材にまとめる

合計 21営業日（約4週間）／1名専任 + レビュー体制。

工数配分の意図： Phase 0 に4日、うち lib/inventory/ のテストに2日を充てる。在庫算出はこのプロジェクトの価値そのものであり、かつ間違っていても画面上は動いているように見える種類のバグを生む。「引当で有効在庫だけが減る」「逆仕訳で在庫が戻り履歴が残る」がテストで保証されていない状態で画面を作り始めると、後半で全画面の数字を疑うことになる。 Phase 1 に4日を割いているのは、データテーブル基盤が全一覧画面に波及するため。逆にここが良ければ、トランザクション・ロット・発注の一覧はほぼ設定だけで完成する。

13. 受入基準

1. 6章の優先度 P1 の要件がすべて実装され、テストで合格していること
2. 5章の主要フローA・B・Cが、エンドツーエンドで完走すること
3. 4章「ロールを跨ぐ体験」の6パターンがすべて動作すること
4. 在庫数量がストアに保存されておらず、常にトランザクションから算出されていること
5. 在庫を変更するコードが、トランザクションの追加以外に存在しないこと
6. 4つの在庫数が同一の関数から返され、在庫一覧に同時表示されていること
7. 引当を作成すると、実在庫は変わらず有効在庫のみが減ること
8. 取消が逆仕訳として実装され、元の取引が履歴から消えないこと
9. 拠点間移動で「移動中」状態が存在し、入荷処理まで到着先の在庫に入らないこと
10. 推奨発注リストの判定に入荷予定が含まれていること（実在庫だけで判定していない）
11. 棚卸の差異が、原因分類と承認を経てから調整トランザクションとして登録されること。承認前に在庫が動かないこと
12. ロールを切り替えると、見える行（拠点）と見える列（原価・在庫金額）の両方が変わること。かつ原価がデータに含まれずに返されていること（CSSで隠していない）
13. 620 SKU × 5,000トランザクションで、在庫算出が150ms以下、絞り込みが100ms以下であること
14. 連続スキャンで入力欄のフォーカスが外れず、1件あたり50ms以下で処理されること
15. 水位バーが aria-label を持ち、4つの在庫数が数値としても表示されていること
16. CSVインポートが列マッピングとエラー行表示に対応し、初期在庫が期首棚卸トランザクションとして登録されること
17. CSVエクスポートと発注書PDFが実際にダウンロードできること
18. 全32画面のいずれにも空の状態がなく、リアルなデータが表示されていること
19. リロード後も操作結果が保持され、「デモをリセット」で初期状態に戻ること
20. axe-core で Critical / Serious の指摘が0件であること
21. データアクセスがすべて lib/repo/ を経由し、在庫算出が lib/inventory/ の外に存在しないこと
22. RELATE と並べたときに、明確に別のプロダクトとして見えること（水位バーと Condensed 数値が効いていること）

判断に迷ったときのルール

1. 仕様がこの文書にない場合は、実装せずに質問する。 推測で作らない
2. 在庫数を書き換えない。 出来事（トランザクション）を追加する。これがこのプロジェクトの存在理由
3. 在庫算出を lib/inventory/ の外に書かない。「ここだけ簡単に足せば」が全ての崩壊の始まり
4. lib/inventory/ と lib/analytics/ を純粋関数に保つ。 現在時刻は必ず引数で受け取る
5. トランザクションを削除・編集しない。 取消は逆仕訳
6. 4つの在庫数を混同しない。 画面でも文言でも、必ず区別して表示する
7. 原価・在庫金額は権限がなければデータに含めない。 CSSで隠すのは実装ミス
8. 警告はブロックしない。 現場は理屈通りに動かない。警告して記録し、あとで直せるようにする
9. スキャン入力のフォーカスを失わせない。 ここが崩れると現場で使われなくなる
10. 数量は常に最小単位・符号付きで保持する。 表示時に換算する
11. スコープ外（3章 Won't have）は実装しない。特に単位換算・引当優先順位・セット品は要件定義段階で洗い出す
12. 「デモだから」を理由に品質を落とす判断はしない
13. RELATE のトークン・コンポーネントをコピーしない。 同じ業務システムでも方向は別