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

**版数** 1.2（DBレス構成・実装を反映：案内役「さじ」・スタートページ・席数の訂正・店の画面のデザイン）／ **作成日** 2026-10-01 ／ **改訂** 2026-10-02 ／ **発行** ソウゾウ合同会社
**公開中の実装** https://saji.souzohnic.workers.dev
**用途** 業種特化アプリの実演デモ ／ 飲食店向け モバイルオーダー編

---

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

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

- **実装は「11. 実装タスク」の順に進める。フェーズを飛ばさない。**
- 各タスクの括弧内は要件ID。着手前に該当章を読むこと。
- **仕様がここに書かれていない場合は、推測で実装せず質問する。**
- スコープ外（3章 Won't have）は、思いついても実装しない。
- 「デモだから」を理由に品質を落とす判断はしない。
- **飲食店の言葉で書く。** 画面の文言・項目名・並び順は、飲食店のホールと厨房で毎日使っている言葉に合わせる（卓・お通し・提供・品切れ・ラストオーダー・お会計・片付け）。汎用の言葉（「アイテム」「チケット」「ステータス」「ユーザー」など）を画面に出さない。

> **このアプリが「業種特化」であることの意味**
> 注文を受けるだけの仕組みは、すでに多くある。SAJI が選ばれる理由は、**お客さまのスマホ・厨房・ホール・会計が1本の流れでつながり、「いまどの卓が何を待っているか」が店じゅうで同じに見えること**である。
> 注文が厨房に届かない、提供したのにお客さまの画面が変わらない、会計の金額が注文と合わない、のどれか1つでもあれば失敗とみなす。

---

## 目次

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

---

# 1. プロジェクト概要

## 背景と目的

客席30〜60席ほどの居酒屋・和食店・カフェの多くは、**注文を店員が手書きの伝票かハンディ端末で受け、厨房へ口頭や紙で伝えている**。混む時間帯には「呼んでも店員が来ない」「注文が厨房に通っていなかった」「どの卓の料理か分からず出し間違える」「会計で伝票と金額が合わない」が起きる。人手が足りない店ほど、注文を取りに行く往復だけでホールの時間が消える。

モバイルオーダーは、お客さまが自分のスマホでテーブルのQRコードを読み、そのまま注文する仕組みである。SAJI は、**注文する・作る・運ぶ・片付ける・会計する**を1本の流れとしてつなぎ、店の誰が見ても同じ状態が見えるようにする。

| 目的 | 内容 |
|---|---|
| 業種特化の実装力の証明 | 卓・お通し・飲み放題・ラストオーダー・品切れ・提供順といった飲食店の決まりごとを、そのまま画面にする |
| つながりの証明 | お客さまが注文した瞬間に厨房に表示され、厨房で完成を押すとホールとお客さまの画面が変わる。**1人で触って流れ全体を体験できる** |
| 現場で使える操作性の証明 | 厨房は油や水で手が汚れていても押せる大きさ、ホールは歩きながら片手で状況が分かる |
| 横展開の資産化 | 店舗の情報・メニュー・卓をデータとして差し替えれば、業態（居酒屋・カフェ・焼肉）を変えられる構造にする |

## プロダクト定義

| 項目 | 内容 |
|---|---|
| プロダクト名 | SAJI（さじ）※仮称 |
| 一言定義 | テーブルのQRから注文、厨房に即表示、会計まで。飲食店のためのモバイルオーダー |
| 提供形態 | レスポンシブWebアプリ。**フロントエンド完結（サーバー側の保存なし）** |
| 主戦場 | お客さまのスマホ（注文）、厨房のタブレット（厨房モニター）、ホールのスマホ（卓の状況・呼び出し）、レジのPCまたはタブレット（会計・店長の画面） |
| 想定利用者 | 来店したお客さま、厨房の調理担当、ホール担当、店長 |
| 見本の店 | 「炉端と酒 あかり」— 架空の居酒屋。客席58席（テーブル8卓・カウンター6席・座敷2卓）、営業 17:00〜24:00（ラストオーダー フード23:00 ／ ドリンク23:30） |

## プロダクトコンセプト

> **「呼ばなくていい。待たせない。間違えない。」**
>
> お客さまは店員を呼ばずに好きなときに注文できる。厨房は届いた順と待ち時間が一目で分かる。ホールは「料理ができた卓」「呼ばれている卓」「会計したい卓」だけを見て動ける。会計の金額は注文から自動で決まるので、伝票の書き間違いが起きない。

## デモとしての成功条件

1. **1人で全部の流れを体験できる** — お客さまのスマホで注文 → 厨房モニターに届く → 完成を押す → ホールに「提供待ち」が出る → 提供済みにする → お客さまの画面が「お届け済み」に変わる → お会計、までを、切り替えながら（または横に並べて）触れる
2. **開いた瞬間から営業中に見える** — 空の画面が1つもない。何卓かが着席中で、厨房には調理中の注文があり、今日の売上が出ている
3. **速い** — 注文の確定から厨房に表示されるまで1秒以内。厨房の「完成」を押してから各画面が変わるまで1秒以内
4. **飲食店の言葉でできている** — お通し、飲み放題の残り時間、ラストオーダー、品切れ、提供までの時間、が当たり前に出てくる
5. **リセットできる** — 誰が触った後でも、初期状態（営業中のようす）に戻せる

---

# 2. アーキテクチャ方針 — データベースを持たない

## 基本方針

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

| 一般的な構成 | 本プロジェクト |
|---|---|
| PostgreSQL / Supabase | シードデータ（TypeScript）+ ブラウザ内ストア |
| 店員のログイン | デモ用ロール切替（ワンクリック） |
| 注文API・リアルタイム配信（WebSocket） | ストア上の操作（リポジトリ層）＋ **同じブラウザの別タブへは BroadcastChannel で即時に伝える** |
| 決済（クレジットカード・QR決済） | **行わない。** 支払い方法を選んで「会計を完了する」と、会計済みとして記録するだけ |
| レシート・領収書の印刷 | 画面に表示し、PDFとしてダウンロードできる |
| 卓のQRコード | ブラウザ内で生成し、印刷用PDFとしてダウンロードできる |
| メニュー写真のアップロード | ブラウザ内で縮小して IndexedDB に保持する（7章「画像」） |

## なぜこの構成にするか

- **デモとして最適** — 訪問者は登録もログインもせずに、お客さまと店の両方を即座に触れる
- **お客さまの情報を一切預からない** — 入力されたデータはブラウザから出ない
- **開発速度** — 認証・権限のサーバー実装・リアルタイム配信のサーバーが不要になり、**流れのつながりと操作感に全時間を投下できる**
- **運用コストゼロ** — 静的配信のみ

## 差し替え可能性の担保（重要）

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

```
[ 画面・コンポーネント ]
        ↓  呼ぶのはこの層だけ
[ src/lib/repo/*.ts ]   ← 全メソッドを async にしておく
        ↓
[ src/lib/store/*.ts ]  ← Zustand + persist（localStorage）
        ↓                 変更は src/lib/sync/ が BroadcastChannel で他のタブへ伝える
[ src/lib/seed/*.ts ]   ← 初期データ（「いま」を基準に作る）
```

リポジトリの各メソッドは、中身が同期処理でも **`async` で定義し、`await` で呼ぶ**。本番化する際は、リポジトリの実装だけをサーバーへの問い合わせに、`src/lib/sync/` をリアルタイム配信（WebSocket 等）に差し替えれば、画面は一行も変更せずに済む。

```ts
// src/lib/repo/orders.ts — 中身は同期でも async にする
export async function placeOrder(input: PlaceOrderInput): Promise<Result<Order>> {
  await delay('write')
  const check = validateOrder(input, getMenuState())     // 品切れ・ラストオーダー・飲み放題の対象を確認
  if (!check.ok) return check
  const order = useDataStore.getState().addOrder(toOrder(input))
  publish({ type: 'order.placed', orderId: order.id })     // 本番化でここがサーバーからの配信になる
  return { ok: true, data: order }
}
```

## 永続化の範囲

| 対象 | 挙動 |
|---|---|
| シードデータ | 初期投入。**時刻は「いま」を基準に作る**（例：卓3は42分前に着席、飲み放題は残り48分）。以降は編集可能 |
| 操作の結果（着席・注文・完成・提供・呼び出し・会計・メニュー編集・品切れ） | localStorage に保存。**リロードしても保持される** |
| 他のタブへの反映 | 同じブラウザで開いた別タブ（例：左にお客さま、右に厨房）へ、変更を 1秒以内に反映する。BroadcastChannel が使えない環境では `storage` イベントで代替する |
| 画像（メニュー写真） | シードの写真は `public/photos/` を参照し、保存しない。店長が追加・差し替えた写真だけを、長辺1280pxに縮小しJPEG品質0.8・1枚200KB以下にして **IndexedDB** に保存する（localStorage は5MB程度しかなく、写真を20枚ほどで使い切るため） |
| リセット | デモ切替バーの「デモをリセット」で localStorage と IndexedDB を空にし、**その時点の「いま」を基準に**初期状態を作り直す |

**擬似的な非同期を必ず入れること。** リポジトリの書き込みに 150〜300ms のディレイを挟み、送信中の状態を実際に見せる。ただし**メニューのカテゴリ切替・数量の増減・厨房の画面の絞り込みは待たせない**（100ms 以下）。

> **時刻の扱いに注意。** デモは昼でも夜でも開かれる。営業時間（17:00〜24:00）と実際の時刻は照らし合わせない。**シードは「いまが営業中の20時台のつもり」で作り、表示する時刻も「いま」から算出する。** ラストオーダーは「いまから何分後」で設定できる（6.7）。

---

# 3. スコープ定義

## お客さまの注文（スマホ）

| ID | 機能 | 優先度 |
|---|---|---|
| F-C01 | 来店の受付（QRを読んだ後の最初の画面。人数の確認・お店からのお知らせ・アレルギーの案内） | Must |
| F-C02 | メニュー（カテゴリ・おすすめ・写真・価格・品切れ・飲み放題の対象） | Must |
| F-C03 | 商品の詳細（写真・説明・アレルギー・選択肢・数量・ひとこと） | Must |
| F-C04 | カートと注文の確定 | Must |
| F-C05 | 注文の進み具合（受付済み → 調理中 → お届け済み） | Must |
| F-C06 | 店員の呼び出し（お水・おしぼり・取り皿・その他） | Must |
| F-C07 | お会計（明細・合計・割り勘の目安・会計の依頼） | Must |
| F-C08 | 飲み放題の残り時間とラストオーダーの案内 | Must |
| F-C09 | 「いつもの」再注文（同じ卓で頼んだものをもう一度） | Should |
| F-C10 | 表示の言語を英語に切り替える | Could |

## 厨房（厨房モニター）

| ID | 機能 | 優先度 |
|---|---|---|
| F-K01 | 注文の一覧（届いた順・卓・経過時間・選択肢・ひとこと） | Must |
| F-K02 | 調理場ごとの表示（焼き場・揚げ場・キッチン・ドリンク） | Must |
| F-K03 | 品ごとの「完成」と、注文ごとの「全部完成」 | Must |
| F-K04 | 遅れの強調（経過時間で色が変わる） | Must |
| F-K05 | 品切れの登録（厨房からもすぐに止められる） | Must |
| F-K06 | 完成の取り消し（押し間違いの戻し） | Must |
| F-K07 | 品ごとのまとめ表示（同じ品が何個待っているか） | Should |

## ホール

| ID | 機能 | 優先度 |
|---|---|---|
| F-H01 | 卓の配置図（空席・着席中・料理待ち・提供待ち・呼び出し中・会計待ち・片付け中） | Must |
| F-H02 | 着席の案内（人数・卓のQRの表示・飲み放題の開始） | Must |
| F-H03 | 提供待ちの一覧と「提供済み」 | Must |
| F-H04 | 呼び出しの一覧と「対応済み」 | Must |
| F-H05 | 卓の詳細（人数・滞在時間・注文の明細・飲み放題の残り） | Must |
| F-H06 | 店員による代理の注文（スマホを使わないお客さま向け） | Must |
| F-H07 | 卓の移動・卓の合体（2卓を1つの会計にする） | Should |
| F-H08 | 片付けの完了（片付け中 → 空席） | Must |

## 会計（レジ）

| ID | 機能 | 優先度 |
|---|---|---|
| F-R01 | 会計する卓の選択と明細（お通し・飲み放題・注文） | Must |
| F-R02 | 値引き（金額・割合）と、取り消し・数量の訂正 | Must |
| F-R03 | 支払い方法（現金・クレジットカード・QR決済）と、現金のお釣りの計算 | Must |
| F-R04 | 割り勘（人数で均等・1円単位の端数の扱い） | Must |
| F-R05 | レシートの表示とPDFのダウンロード、領収書（宛名・但し書き） | Must |
| F-R06 | 会計の取り消し（レジ締め前のみ） | Should |

## 店長

| ID | 機能 | 優先度 |
|---|---|---|
| F-M01 | 今日のようす（売上・客数・客単価・回転・提供までの平均時間・人気の品） | Must |
| F-M02 | メニューの管理（追加・編集・並べ替え・写真・アレルギー・選択肢・調理場・おすすめ・表示/非表示） | Must |
| F-M03 | 品切れの管理（一覧で一括に切り替え） | Must |
| F-M04 | 卓とQRの管理（卓の名前・席数・配置・印刷用のQR） | Must |
| F-M05 | 時間帯別・品別の分析（直近14日） | Must |
| F-M06 | お店の設定（お通し・ラストオーダー・飲み放題のコース・呼び出しの項目・遅れの基準） | Must |
| F-M07 | 売上の書き出し（CSV） | Should |

## 共通・基盤

| ID | 機能 | 優先度 |
|---|---|---|
| F-S07 | 案内役「さじ」（店の画面の右下にいる。注文 → 厨房 → ホールの順を案内し、画面ごとに一言話す。動かせる・休ませられる。お客さまの画面には出さない。質問には答えない） | Must |
| F-S01 | デモ切替バー（お客さま／厨房／ホール／会計／店長の切り替え・リセット） | Must |
| F-S02 | 並べて見る（パソコンでは、お客さまのスマホと厨房・ホールを左右に並べる） | Must |
| F-S03 | 他のタブへの即時反映（同じブラウザの別タブ） | Must |
| F-S04 | 通知（厨房に新しい注文・ホールに提供待ちと呼び出し）を画面と音で知らせる | Must |
| F-S05 | はじめての人への案内（3ステップのガイド） | Must |
| F-S06 | スタートページ（このデモで何ができるか・どこから触るか） | Must |

## 対象外（Won't have）

以下は**作らない**。思いついても実装しない。

- 実際の決済（クレジットカード・QR決済・電子マネーの決済処理）
- POSレジや会計ソフト、キャッシュドロワー、レシートプリンター、キッチンプリンターとの接続
- お客さまの会員登録・ポイント・クーポン・LINE連携
- テイクアウト・デリバリーの注文（店内飲食のみ）。**店内飲食のみなので、消費税は10%の1種類だけを扱う**
- 予約の受付（別のデモ「予約サイト」の範囲）
- 在庫・仕入れの管理（品切れの手動切り替えのみ）
- シフト・勤怠
- 複数店舗の管理（1店舗のみ）
- 英語以外の多言語（中国語・韓国語など）
- メニューの自由なデザイン編集（レイアウトは固定。店長が変えられるのは内容だけ）

---

# 4. ロールとデモ切替

## ロール定義

| ロール | 使う場所 | できること | 主な画面 |
|---|---|---|---|
| お客さま | 客席・自分のスマホ | 注文・呼び出し・進み具合の確認・お会計の依頼。**自分の卓のことしか見えない** | 注文の画面一式（SC-C01〜C08） |
| 厨房 | 厨房のタブレット（横向き） | 注文を見る・完成を押す・品切れにする | 厨房モニター（SC-K01） |
| ホール | ホール担当のスマホ | 卓の状況・着席の案内・提供・呼び出し・代理の注文・片付け | 卓の配置図ほか（SC-H01〜H04） |
| 会計 | レジのPC・タブレット | 卓を選んで会計する・領収書 | 会計（SC-R01〜R02） |
| 店長 | 事務所のPC・レジ | 上のすべて＋分析・メニュー・卓・設定 | 今日のようす・分析・管理（SC-M01〜M06） |

**見える範囲の判定は `src/lib/repo/_scope.ts` の1か所に集約する。** お客さまのロールでは、他の卓の注文・金額・全体の売上が、画面にも、リポジトリが返すデータにも含まれないこと。店員のロール（厨房・ホール・会計）は売上の分析と設定を開けない（メニューの品切れだけは厨房・ホールも切り替えられる）。

## お客さまの卓（デモ上の約束）

お客さまのロールは「卓をひとつ選んで、その卓のスマホとして振る舞う」。デモ切替バーで卓を選べる（初期は「テーブル 3」）。**空席の卓を選んだ場合は、QRを読んだ直後と同じく来店の受付（SC-C01）から始まる。** 会計済みの卓を選んだ場合は「ご来店ありがとうございました」の画面を出し、「もう一度この卓で試す」で空席に戻せる。

## デモ切替バー（F-S01）

画面の最上部に常に表示する、黒い細い帯。

| 要素 | 内容 |
|---|---|
| 左 | 「デモ」の印と「これはデモです。注文・支払いは実際には発生しません」 |
| 中央 | 見え方の切り替え：**お客さま ／ 厨房 ／ ホール ／ 会計 ／ 店長**。お客さまを選んでいるときは、その右に卓の選択 |
| 右 | 「並べて見る」（パソコンのみ）・「デモをリセット」（確認ダイアログあり） |

スマホの幅では、中央の切り替えを短い表記（客・厨房・ホール・会計・店長）にし、リセットはアイコンだけにする。

## 並べて見る（F-S02）

パソコン（幅1200px以上）で「並べて見る」を押すと、**左にお客さまのスマホ（幅390pxの端末の枠）、右に店の画面（厨房・ホール・会計・店長から選ぶ）**を並べる。どちらも同じデータを見ているので、左で注文すると右の厨房に1秒以内に届く。これがこのデモの最大の見せ場であり、**初めて開いた人には、スタートページから最初にこの画面を案内する**。

- 左右の画面はそれぞれ独立に操作できる（左の注文中に右で完成を押せる）
- 左のお客さまの卓は、左の枠の上で選べる
- 幅1200px未満では「並べて見る」を出さない。代わりに「別のタブで開く」を出し、同じ店のデータを別タブで開けるようにする（F-S03）

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

以下は、ロールを切り替えたり並べたりして**つながりを見せる**ための体験である。すべて動くこと。

1. **注文が厨房に届く** — お客さま（テーブル3）で「焼き鳥 盛り合わせ」と「生ビール」を注文 → 厨房モニターに新しい注文として1秒以内に出る。焼き鳥は「焼き場」、生ビールは「ドリンク」に分かれて出る
2. **完成がお客さまに伝わる** — 厨房で生ビールを「完成」→ ホールの提供待ちに「テーブル3 生ビール」→ ホールで「提供済み」→ お客さまの画面で生ビールが「お届け済み」になる
3. **品切れが止まる** — 厨房で「だし巻き玉子」を品切れにする → お客さまのメニューで「品切れ」と表示され、カートに入っていた場合は注文の確定で止まり、理由が出る
4. **呼び出しが届く** — お客さまで「お水」を呼ぶ → ホールの配置図でテーブル3が「呼び出し中」になり、音が鳴る → 「対応済み」でお客さまの画面に「店員が向かいます」は消える
5. **飲み放題が終わる** — 飲み放題のラストオーダーの時刻を過ぎると、お客さまのメニューで飲み放題の対象が注文できなくなる（店長の設定で「いまから1分後」にして確かめられる）
6. **会計が注文と合う** — お客さまで「お会計をお願いする」→ ホールの配置図で「会計待ち」→ 会計でテーブル3を開くと、**お客さまの画面に出ていた合計と1円も違わない**金額が出る → 会計を完了すると、卓が「片付け中」になり、お客さまの画面は「ご来店ありがとうございました」になる
7. **店長の数字が動く** — 会計を完了すると、店長の「今日のようす」の売上・客数・客単価が増える
8. **見える範囲が違う** — お客さまのロールでは、他の卓の注文・全体の売上が一切見えない

---

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

画面の文言は、すべて飲食店で使う言葉で書く。

## スタート

| ID | 画面 | パス | 内容 |
|---|---|---|---|
| SC-000 | スタートページ | `/` | **LP にしない。** 白木のカウンターの画面に案内役「さじ」を大きく出し、3行（「いらっしゃいませ。炉端と酒 あかりの案内係、さじです。」「お客さまのスマホから、厨房・ホール・お会計まで、ひとつの流れでつながります。」「では、お客さまのスマホと厨房を並べてご案内します。」）を1文字ずつ話す。2行目で見本のカード（料理の写真・厨房の札・配置図の卓・お会計）が浮かぶ。**約5秒で、PC（幅1200px以上）は「並べて見る」（右は厨房）へ、スマホはテーブル3のお客さまの画面へ自動で入る。**「止める」「入る」「飛ばして入る」と、別の見え方（お客さま／厨房／ホール／会計／店長）で入るボタン。下に「写真のクレジット」 |

## お客さま（スマホ）

| ID | 画面 | パス | 内容 |
|---|---|---|---|
| SC-C01 | 来店の受付 | `/t/:tableId` | 店名・卓の名前・「ようこそ」・人数の確認（ホールで入力済みならその人数を表示し、変更できる）・お店からのお知らせ（お通しのこと・ラストオーダーの時刻）・アレルギーの案内・「メニューを見る」 |
| SC-C02 | メニュー | `/t/:tableId/menu` | 上にカテゴリのタブ（横スクロール・押すとその位置へ移動）。先頭に「おすすめ」。写真つきのカード（品名・価格・品切れ・飲み放題の対象）。下に固定のカートの帯（品数・合計・「注文へ進む」） |
| SC-C03 | 商品の詳細 | `/t/:tableId/menu/:itemId`（下から出るシート） | 大きな写真・品名・価格・説明・アレルギー（含むものを並べる）・選択肢（例：塩/たれ）・数量・お店へのひとこと（30文字まで）・「カートに入れる」 |
| SC-C04 | カート | `/t/:tableId/cart` | 品ごとの明細（選択肢・ひとこと・数量の変更・削除）・合計・「この内容で注文する」。品切れ・ラストオーダー後の品があれば、その行に理由を出して注文の確定を止める |
| SC-C05 | 注文の進み具合 | `/t/:tableId/orders` | この卓で頼んだものを新しい順に。品ごとに「受付済み → 調理中 → お届け済み」。注文した時刻・何分前か。「もう一度頼む」（F-C09） |
| SC-C06 | 店員を呼ぶ | `/t/:tableId/call`（シート） | お水・おしぼり・取り皿・お箸・その他（ひとこと）。送ったあとは「店員が向かいます」をメニューの上に出し、対応済みで消す |
| SC-C07 | お会計 | `/t/:tableId/bill` | 明細（お通し・飲み放題・注文の品）・合計（税込）・うち消費税・割り勘の目安（人数を変えられる）・「お会計をお願いする」→ 依頼後は「レジでお支払いください（または店員が伺います）」と卓の名前を大きく表示 |
| SC-C08 | ご来店ありがとうございました | `/t/:tableId/thanks` | 会計が済んだあとの画面。「もう一度この卓で試す」（デモのみ） |

スマホの下部の帯：**メニュー ／ 注文の進み具合 ／ 店員を呼ぶ ／ お会計**。カートは帯の上に浮く。

## 厨房

| ID | 画面 | パス | 内容 |
|---|---|---|---|
| SC-K01 | 厨房モニター | `/kitchen` | 上：調理場の切り替え（すべて／焼き場／揚げ場／キッチン／ドリンク）・待ちの件数・品切れの切り替えボタン。中：注文の札を届いた順に左から並べる（横向きタブレットで4〜5枚見える）。札＝卓の名前・届いた時刻・経過時間・品の一覧（数量・選択肢・ひとこと）・品ごとの「完成」・札の「全部完成」。右（または下）：品ごとのまとめ（F-K07） |
| SC-K02 | 品切れ | `/kitchen/soldout`（シート） | カテゴリ別に全品を並べ、押すだけで品切れ／販売中を切り替える |

## ホール

| ID | 画面 | パス | 内容 |
|---|---|---|---|
| SC-H01 | 卓の配置図 | `/hall` | 店の見取り図に卓を配置（テーブル・カウンター・座敷）。卓ごとに状態の色と印・人数・滞在時間・飲み放題の残り。上に「提供待ち N」「呼び出し N」「会計待ち N」の数（押すとその一覧へ） |
| SC-H02 | 卓の詳細 | `/hall/tables/:tableId`（右から出るパネル／スマホは全画面） | 状態・人数・着席の時刻・飲み放題・注文の明細（品ごとの状態）・呼び出し・操作（着席の案内／代理で注文／卓の移動／会計へ／片付け完了） |
| SC-H03 | 提供待ち・呼び出し | `/hall/queue` | タブで「提供待ち」「呼び出し」。提供待ちは完成した順に、卓の名前を大きく・品・完成してからの時間。「提供済み」を押す。呼び出しは届いた順に「対応済み」 |
| SC-H04 | 着席の案内 | `/hall/seat/:tableId`（シート） | 人数・飲み放題のコース（なし／90分／120分）・「この卓のQRを表示」（お客さまに読んでもらう画面。デモでは押すとお客さまの画面へ切り替えられる） |
| SC-H05 | 代理の注文 | `/hall/tables/:tableId/order` | お客さまのメニューと同じ内容を、店員向けに文字中心の一覧で。品名の検索・数量の素早い入力 |

スマホの下部の帯：**配置図 ／ 提供待ち ／ 呼び出し ／ 品切れ**

## 会計

| ID | 画面 | パス | 内容 |
|---|---|---|---|
| SC-R01 | 会計 | `/register` | 左：会計する卓の一覧（会計待ちを先頭に、着席中の卓も選べる）。右：明細・値引き・合計・支払い方法・お預かり・お釣り・割り勘・「会計を完了する」 |
| SC-R02 | レシート・領収書 | `/register/receipts/:billId` | レシートの表示（店名・日時・卓・明細・合計・消費税・支払い方法）・「レシートをPDFで保存」・領収書（宛名・但し書き・金額）の作成とPDF |
| SC-R03 | 今日の会計 | `/register/history` | 今日の会計の一覧（時刻・卓・人数・金額・支払い方法）・会計の取り消し（F-R06） |

## 店長

| ID | 画面 | パス | 内容 |
|---|---|---|---|
| SC-M01 | 今日のようす | `/manager` | 売上・客数・客単価・回転数・提供までの平均時間（目標との比較）・いま着席中の卓と人数・時間帯別の売上（棒）・今日の人気の品（上位10）・遅れが多い品 |
| SC-M02 | 分析 | `/manager/reports` | 直近14日：日別の売上と客数・曜日×時間帯の混み具合・品別の出数と売上（ABC分析）・カテゴリ別の売上構成・提供時間の分布。期間の切り替え（7日／14日） |
| SC-M03 | メニューの管理 | `/manager/menu` | カテゴリごとに品を一覧（写真・品名・価格・調理場・状態）。並べ替え（ドラッグとキーボード）・追加・編集（SC-M04）・表示/非表示・品切れ |
| SC-M04 | 品の編集 | `/manager/menu/:itemId` | 品名・英語の品名・価格（税込）・カテゴリ・説明・写真・アレルギー（特定原材料8品目＋準ずるもの20品目から選ぶ）・選択肢（グループと選択肢・追加料金）・調理場・おすすめ・飲み放題の対象・表示期間（任意） |
| SC-M05 | 卓とQR | `/manager/tables` | 卓の一覧（名前・種類・席数）・配置図の編集（ドラッグで位置を変える）・卓のQRの表示・**全卓のQRを印刷用PDFで保存** |
| SC-M06 | お店の設定 | `/manager/settings` | 店名・お通し（有無・1人あたりの金額）・ラストオーダー（フード・ドリンク。デモ用に「いまから◯分後」で設定できる）・飲み放題のコース（名前・時間・金額・ラストオーダーは終了の何分前か）・呼び出しの項目・遅れの基準（注意・遅れの分数）・通知の音 |

スマホの下部の帯（店長）：**今日 ／ 分析 ／ メニュー ／ 設定**

## 主要フロー

### フロー1：来店から注文まで（お客さま）

```
ホール：卓の配置図でテーブル3を押す → 着席の案内（2名・飲み放題90分）→ 「この卓のQRを表示」
  ↓（デモではここでお客さまの画面へ。並べて見るなら左の枠へ）
お客さま：来店の受付（2名・お通しのご案内）→ メニューを見る
  → 「焼き鳥 盛り合わせ（5本）」を開く → 選択肢「たれ」→ 数量1 → カートに入れる
  → 「生ビール（中）」を2つ → カートの帯「3品 ¥1,280」（飲み放題の卓なので生ビールは0円）→ 注文へ進む
  → この内容で注文する → 「注文を受け付けました」→ 注文の進み具合へ（受付済み）
```

### フロー2：厨房からテーブルまで

```
厨房：新しい注文の札が右端に出る（音と光）。焼き場とドリンクに分かれて表示
  → ドリンクで「生ビール（中）×2」を完成 → ホールの提供待ちに出る
ホール：提供待ち「テーブル3 生ビール（中）×2」→ 運んで「提供済み」
お客さま：注文の進み具合で生ビールが「お届け済み」に
厨房：焼き場で焼き鳥を完成 → （同じ流れ）→ 札の全品が完成すると札が消える
```

### フロー3：お会計

```
お客さま：お会計 → 明細を確認（お通し2名・飲み放題90分×2・料理）→ 割り勘の目安（2人で ¥4,200ずつ）
  → 「お会計をお願いする」→ 卓の名前を大きく表示
ホール：配置図でテーブル3が「会計待ち」
会計：テーブル3を選ぶ → 明細（お客さまの画面と同じ合計）→ 支払い方法「現金」→ お預かり ¥10,000 → お釣り ¥1,600
  → 会計を完了する → レシート → （領収書の宛名を入れてPDF）
ホール：テーブル3が「片付け中」→ 片付け完了 → 空席
店長：今日のようすの売上・客数・客単価が増える
```

### フロー4：品切れ

```
厨房：品切れのボタン → 「だし巻き玉子」を品切れに
お客さま：メニューのだし巻き玉子に「品切れ」（写真を薄く・押しても詳細は開くがカートに入れられない）
  （すでにカートに入っていた場合）カートでその行に「品切れになりました」→ 削除するまで注文の確定ができない
店長：品切れの管理に「だし巻き玉子 品切れ（20:14 厨房）」と記録
```

### フロー5：メニューを変える（店長）

```
店長：メニューの管理 → 「本日のおすすめ」に「秋刀魚の塩焼き ¥980」を追加（写真を選ぶ・アレルギーなし・焼き場）
  → 保存 → お客さまのメニューの「おすすめ」の先頭に出る
  → 厨房で注文すると焼き場に出る
```

---

# 6. 機能要件

> **v1.1 で足したこと：案内役「さじ」（F-S07）**
> まるい顔に朱のはちまきを締めたキャラクター（SVG で描く。`components/shared/saji.tsx`・`components/demo/pet.tsx`・`repo/pet.ts`）。店の画面と「並べて見る」の右下にいる（スタート・お客さまの画面・クレジットには出さない）。①「左のスマホで注文してみてください」→ 注文が届いたら ②「札の『完成』を押してみてください」→ 完成したら ③「ホールで『提供済み』に」→ 提供したら「できました！」と、体験の順を案内する。それ以外は画面ごとに、実際のデータから作った一言（遅れている札の数・呼び出しの数・会計待ちの卓の数・今日の売上）を話す。ドラッグで動かせ、月のボタンで休ませられる。見た目のキャラクターであり、質問には答えない。

優先度：**P1＝必須 ／ P2＝重要 ／ P3＝あれば良い**。ただし、5章の主要フローと4章の体験に出てくる機能は、P2・P3 でも必須とする（12章）。

## 6.1 ロール・デモ基盤

| ID | 要件 | 優先度 |
|---|---|---|
| FR-001 | デモ切替バーで、お客さま／厨房／ホール／会計／店長を1クリックで切り替えられること。切り替えたら、そのロールの最初の画面へ移ること | P1 |
| FR-002 | お客さまのロールでは、卓を選べること。選んだ卓の状態（空席・着席中・会計済み）に応じて最初の画面を変えること（4章） | P1 |
| FR-003 | 見える範囲の判定を `src/lib/repo/_scope.ts` に集約すること。お客さまのロールでは、他の卓の注文・金額と店全体の数字をリポジトリが返さないこと | P1 |
| FR-004 | 「デモをリセット」で、確認のうえ localStorage と IndexedDB を空にし、その時点の「いま」を基準に初期状態を作り直すこと | P1 |
| FR-005 | 「並べて見る」（幅1200px以上）で、左にお客さまのスマホの枠、右に店の画面を並べ、両方を独立して操作できること（F-S02） | P1 |
| FR-006 | 同じブラウザの別タブで開いた画面に、変更が1秒以内に反映されること（BroadcastChannel。使えない場合は storage イベント） | P1 |
| FR-007 | 店員のロールで権限のない操作（例：ホールでメニューの価格を変える）は、ボタンを出さないこと。URLを直接開いた場合は「店長の画面です」と案内してロールの切り替えを促すこと | P1 |
| FR-008 | はじめて開いた人に、3ステップのガイド（①お客さまで注文する ②厨房で完成を押す ③ホールで提供する）を出すこと。閉じたら出さない（localStorage）。デモ切替バーから再表示できること | P1 |
| FR-009 | 画面の上部に「デモです。注文・支払いは実際には発生しません」を常に表示すること | P1 |

## 6.2 来店の受付とメニュー（お客さま）

| ID | 要件 | 優先度 |
|---|---|---|
| FR-101 | 来店の受付で、店名・卓の名前・人数・お知らせ（お通しの金額・ラストオーダーの時刻）を表示すること。人数は1〜卓の席数＋2まで変更できること | P1 |
| FR-102 | 空席の卓のQRを読んだ（＝お客さまのロールで空席の卓を選んだ）場合は、人数を入れた時点で卓を「着席中」にすること。ホールが着席の案内をしていなくても注文を始められること | P1 |
| FR-103 | メニューは、カテゴリのタブ（横スクロール）と、カテゴリごとの見出し付きの縦の一覧で表示すること。タブを押すとその見出しへ移り、スクロールに合わせて今いるタブが変わること | P1 |
| FR-104 | 先頭に「おすすめ」を出すこと（店長が「おすすめ」にした品。最大6品。横に流れる大きめのカード） | P1 |
| FR-105 | 品のカードに、写真・品名・価格（税込）・印（おすすめ・飲み放題の対象・辛い・品切れ）を出すこと。品切れの品は写真を薄くし「品切れ」と表示すること | P1 |
| FR-106 | 飲み放題の卓では、飲み放題の対象の品の価格を「飲み放題」と表示し、合計に加えないこと。飲み放題でない卓では通常の価格を出すこと | P1 |
| FR-107 | 商品の詳細で、選択肢（必須／任意・1つ選ぶ／複数選べる・追加料金）を選べること。必須の選択肢が未選択のまま「カートに入れる」を押した場合は、その選択肢へ移り理由を出すこと | P1 |
| FR-108 | アレルギーは、その品に含まれるものを、特定原材料8品目（えび・かに・くるみ・小麦・そば・卵・乳・落花生）を先に、準ずるものを後に並べて表示すること。「店舗の調理場では同じ器具を使います。重いアレルギーの方は店員にお声がけください」を必ず添えること | P1 |
| FR-109 | 「お店へのひとこと」を30文字まで書けること（例：「わさび抜き」）。厨房の札にそのまま出ること | P1 |
| FR-110 | メニューの検索（品名・読み）ができること | P2 |
| FR-111 | 表示の言語を英語に切り替えられること。英語の品名がない品は日本語のまま出すこと | P3 |

## 6.3 カートと注文（お客さま）

| ID | 要件 | 優先度 |
|---|---|---|
| FR-201 | カートは卓ごとに持つこと（同じ卓の別のスマホは別のカート。デモでは卓ごとに1つでよい） | P1 |
| FR-202 | カートの帯に品数と合計を常に出し、品を入れたら帯を短く動かして知らせること（動きを減らす設定では動かさない） | P1 |
| FR-203 | 注文の確定の直前に、品切れ・ラストオーダー後・飲み放題の終了後・非表示になった品がないかを確認し、あればその行に理由を出して確定を止めること | P1 |
| FR-204 | 注文を確定したら、カートを空にし、「注文を受け付けました」を出して注文の進み具合へ移ること。二度押しで同じ注文が2回入らないこと | P1 |
| FR-205 | 1回の注文の上限は30品・同じ品は10個までとし、超える場合は理由を出すこと（いたずらの防止） | P1 |
| FR-206 | 注文の進み具合で、品ごとに「受付済み → 調理中 → お届け済み」を出すこと。厨房の「完成」で「調理中」が「お届けの準備中」に、ホールの「提供済み」で「お届け済み」になること | P1 |
| FR-207 | 「もう一度頼む」で、過去に頼んだ品を同じ選択肢でカートに入れられること（品切れの品は入れずに理由を出す） | P2 |
| FR-208 | 「調理中」とは厨房が札を見ている状態のことであり、届いて30秒たった品を「調理中」と表示してよい（厨房に「調理を始める」の操作はない） | P1 |

## 6.4 呼び出しとお会計（お客さま）

| ID | 要件 | 優先度 |
|---|---|---|
| FR-301 | 店員を呼ぶで、項目（お水・おしぼり・取り皿・お箸・その他）を選んで送れること。その他は30文字までのひとことを付けられること | P1 |
| FR-302 | 呼び出し中は、メニューの上に「店員が向かいます（◯分前）」を出し、ホールが対応済みにしたら消すこと。同じ項目を対応前に重ねて送れないこと | P1 |
| FR-303 | お会計で、明細（お通し×人数・飲み放題×人数・注文の品）、合計（税込）、うち消費税（10%）を出すこと。**金額の計算は `src/lib/calc/bill.ts` の1か所だけで行い、お客さま・ホール・会計の画面はすべてこれを使うこと** | P1 |
| FR-304 | 割り勘の目安を出すこと（人数を変えられる）。1人あたりは100円単位に切り上げた額と、最後の1人の額を出すこと（例：合計 ¥8,580 を3人 → ¥2,900 ×2人・¥2,780 ×1人） | P1 |
| FR-305 | 「お会計をお願いする」で、卓を「会計待ち」にし、卓の名前を大きく表示すること。会計待ちのあいだも追加の注文はできること（その場合は会計待ちを解除し、ホールに知らせる） | P1 |
| FR-306 | お届け前の品がある状態でお会計を開いたら、「まだお届けしていない品があります」を出すこと（会計の依頼はできる） | P2 |

## 6.5 厨房モニター

| ID | 要件 | 優先度 |
|---|---|---|
| FR-401 | 注文を「札」として届いた順に左から並べること。札には卓の名前・届いた時刻・経過時間・品（数量・選択肢・ひとこと）を出すこと | P1 |
| FR-402 | 調理場（焼き場・揚げ場・キッチン・ドリンク）で絞り込めること。絞り込んだときは、その調理場の品だけを札に出すこと（同じ注文の他の調理場の品は「ほか2品」と小さく出す） | P1 |
| FR-403 | 品ごとの「完成」と札の「全部完成」を押せること。押した品は取り消し線になり、札の全品が完成したら札を3秒後に消すこと（3秒以内なら戻せる） | P1 |
| FR-404 | 「完成の取り消し」：直近に完成にした品を10件まで「さっき完成にした品」から戻せること（ホールで提供済みになる前まで） | P1 |
| FR-405 | 経過時間で札の色を変えること。基準は店の設定（初期：注意＝10分・遅れ＝15分）。ドリンクは別の基準（初期：注意＝3分・遅れ＝5分）。**色だけでなく、文字（「遅れ 16分」）と印でも示すこと** | P1 |
| FR-406 | 新しい注文が届いたら、札を目立たせ（1.5秒の強調）、通知の音を鳴らすこと。音はデモ切替バーで止められること（初期は鳴る。ただしブラウザの決まりで、画面を一度押すまで音は鳴らないことを画面に書いておく） | P1 |
| FR-407 | 品切れのボタンから、品切れの切り替えシートを開けること。品切れにした時刻とロールを記録すること | P1 |
| FR-408 | 品ごとのまとめ（例：「生ビール（中）× 6 ／ 3卓」）を出すこと。まとめの行を押すと、その品を含む札だけを強調すること | P2 |
| FR-409 | タブレットの横向き（1024×768）で札が4枚以上見えること。札の「完成」ボタンは高さ56px以上 | P1 |
| FR-410 | 札が画面に収まらない場合は横にスクロールでき、画面の端に「ほかに5件」と出すこと | P1 |

## 6.6 ホール

| ID | 要件 | 優先度 |
|---|---|---|
| FR-501 | 卓の配置図に、卓を店の見取り図どおりに並べること（テーブル・カウンター・座敷で形を変える） | P1 |
| FR-502 | 卓の状態を7つで示すこと：空席／着席中／料理待ち（未完成の品がある）／提供待ち（完成して運んでいない品がある）／呼び出し中／会計待ち／片付け中。**同時に当てはまる場合は、呼び出し中 → 提供待ち → 会計待ち → 料理待ち → 着席中 の順で1つを大きく、他を小さな印で出す** | P1 |
| FR-503 | 状態は色・文字・印の3つで示すこと（色だけに頼らない） | P1 |
| FR-504 | 卓に人数・滞在時間・飲み放題の残り時間を出すこと。滞在時間が長い卓（初期：150分）に印を出すこと | P1 |
| FR-505 | 着席の案内で、人数と飲み放題のコースを選び、卓を着席中にすること。飲み放題は開始時刻を記録し、終了時刻とラストオーダーの時刻を算出すること | P1 |
| FR-506 | 提供待ちの一覧で、完成した順に「卓・品・完成してからの時間」を出し、「提供済み」を押せること。同じ卓の品はまとめて「この卓をすべて提供済み」も押せること | P1 |
| FR-507 | 呼び出しの一覧で、届いた順に「卓・項目・ひとこと・何分前」を出し、「対応済み」を押せること | P1 |
| FR-508 | 新しい呼び出しと提供待ちが出たら、下部の帯の数を増やし、音を鳴らすこと（厨房と同じく止められる） | P1 |
| FR-509 | 代理の注文で、お客さまと同じ確認（FR-203）を通して注文できること。代理の注文は札に「ホール」と出すこと | P1 |
| FR-510 | 卓の移動（着席中の卓を空席の卓へ）と、卓の合体（2卓の注文と会計を1つにする）ができること | P2 |
| FR-511 | 片付け中の卓に「片付け完了」を押すと空席になること。会計の完了から10分たっても片付け中の卓に印を出すこと | P1 |

## 6.7 会計

| ID | 要件 | 優先度 |
|---|---|---|
| FR-601 | 会計する卓を選ぶと、明細と合計を出すこと。**金額は FR-303 の `bill.ts` で算出し、お客さまのお会計の画面と1円も違わないこと** | P1 |
| FR-602 | 明細の行の取り消し（理由：作り間違い／お客さまの取り消し／その他）と数量の訂正ができること。取り消した行は消さずに取り消し線で残し、合計から除くこと | P1 |
| FR-603 | 値引き（金額 または 割合）を1つ付けられること。割合の値引きは1円未満を切り捨てること | P1 |
| FR-604 | 支払い方法（現金・クレジットカード・QR決済）を選べること。現金は「お預かり」を入れるとお釣りを出し、足りない場合は会計を完了できないこと。よく使う金額（¥1,000・¥5,000・¥10,000・ちょうど）をボタンで入れられること | P1 |
| FR-605 | 割り勘で、人数を入れると1人あたりの額を出し、人数分の支払いを1件ずつ記録できること（支払い方法を人ごとに変えられる） | P1 |
| FR-606 | 会計を完了すると、卓を「片付け中」にし、お客さまの画面を「ご来店ありがとうございました」にすること | P1 |
| FR-607 | レシートを表示し、PDFでダウンロードできること。領収書は宛名・但し書き（初期：お飲食代として）・金額・発行日を入れてPDFでダウンロードできること。領収書の金額が5万円以上の場合は「収入印紙が必要です」と表示すること | P1 |
| FR-608 | 今日の会計の一覧から、会計を取り消して卓を会計待ちに戻せること（理由を必須とする） | P2 |

### 金額の計算（`src/lib/calc/bill.ts`）

- **価格はすべて税込の整数（円）で持つ。** 店内飲食のため、消費税は10%の1種類
- 合計 ＝ お通し（1人あたりの金額×人数）＋ 飲み放題（コースの金額×人数）＋ 注文の品（（価格＋選択肢の追加料金）×数量、取り消しを除く。飲み放題の卓の飲み放題の対象は0円）− 値引き
- うち消費税 ＝ 合計 × 10 ÷ 110 を**1円未満切り捨て**
- 割り勘：1人あたり ＝ 合計 ÷ 人数 を100円単位に切り上げ。最後の1人 ＝ 合計 − 1人あたり ×（人数−1）。最後の1人が0円以下になる場合は、1円単位で均等に割り、余りを先頭から1円ずつ足す
- 例：お通し ¥390×2 ＋ 飲み放題90分 ¥1,650×2 ＋ 焼き鳥 盛り合わせ ¥1,280 ＋ だし巻き玉子 ¥680 ＋ 唐揚げ ¥780 ＋ 刺身三点盛り ¥1,580 ＋ 生ビール（飲み放題）¥0×2 ＝ **¥8,400**、うち消費税 ¥763。2人で割り勘 → ¥4,200 ×2人

**このテストを `bill.test.ts` に必ず入れる**（上の例・値引き・取り消し・割り勘の端数・0円の卓）。

## 6.8 店長

| ID | 要件 | 優先度 |
|---|---|---|
| FR-701 | 今日のようすに、売上（会計済みの合計）・客数（会計済みの人数）・客単価・回転数（客数÷席数）・提供までの平均時間（注文から提供済みまで。ドリンクを除く）を出すこと。それぞれ先週の同じ曜日と比べること | P1 |
| FR-702 | いま着席中の卓の数・人数と、まだ会計していない金額（見込み）を出すこと | P1 |
| FR-703 | 時間帯別の売上（17時〜24時の1時間ごとの棒）と、今日の人気の品（出数の上位10）を出すこと | P1 |
| FR-704 | 遅れが多い品（遅れの基準を超えて提供した回数の上位5）を出すこと | P2 |
| FR-705 | 分析で、直近7日／14日の日別の売上と客数、曜日×時間帯の混み具合（色の濃さ）、品別の出数と売上（ABC分析：売上の累計で上位70%をA・90%までをB・残りをC）を出すこと | P1 |
| FR-706 | メニューの管理で、品の追加・編集・並べ替え・表示/非表示・品切れができること。並べ替えはドラッグとキーボード（選んで上下キー）の両方でできること | P1 |
| FR-707 | 品の編集で、価格は1〜99,999円の整数、品名は1〜30文字、説明は100文字までとすること。写真を選ぶと長辺1280pxに縮小して保存すること | P1 |
| FR-708 | 卓とQRで、卓の追加・名前・席数・種類・配置図の位置を変えられること。全卓のQR（卓の名前と「スマホで読み取ってご注文ください」）を A4 に8枚並べた印刷用PDFを作れること | P1 |
| FR-709 | お店の設定で、お通し・ラストオーダー・飲み放題のコース・呼び出しの項目・遅れの基準・通知の音を変えられること。ラストオーダーは「時刻で指定」と「いまから◯分後（デモ用）」を選べること | P1 |
| FR-710 | 売上の書き出し（CSV：日付・時刻・卓・人数・品・数量・金額・支払い方法）ができること。数式として読まれる文字で始まる値は無害化すること | P2 |

---

# 7. データ設計

## 型定義（`src/lib/types/`）

```ts
// 金額はすべて税込の整数（円）。時刻は ISO 8601 文字列（ブラウザの時刻）

export type Role = 'guest' | 'kitchen' | 'hall' | 'register' | 'manager'

export interface Store {
  id: string
  name: string                 // 炉端と酒 あかり
  otoshi: { enabled: boolean; pricePerPerson: number }       // お通し
  lastOrder: { food: LastOrderRule; drink: LastOrderRule }
  courses: DrinkCourse[]       // 飲み放題のコース
  callItems: string[]          // お水・おしぼり・取り皿・お箸・その他
  delay: { warnMin: number; lateMin: number; drinkWarnMin: number; drinkLateMin: number }
  longStayMin: number          // 長居の印（初期 150）
  sound: boolean
}

export type LastOrderRule =
  | { kind: 'time'; at: string }            // '23:00'
  | { kind: 'relative'; minutesFromNow: number; setAt: string }   // デモ用
  | { kind: 'none' }

export interface DrinkCourse { id: string; name: string; minutes: number; pricePerPerson: number; lastOrderBeforeMin: number }

export type Station = 'yakiba' | 'agemono' | 'kitchen' | 'drink'   // 焼き場・揚げ場・キッチン・ドリンク

export interface Category { id: string; name: string; nameEn?: string; sortOrder: number; kind: 'food' | 'drink' }

export interface MenuItem {
  id: string
  categoryId: string
  name: string
  nameEn?: string
  kana: string                 // 検索用の読み
  price: number                // 税込
  description: string
  photo: PhotoRef              // シードはファイル、追加分は IndexedDB
  allergens: Allergen[]
  optionGroups: OptionGroup[]
  station: Station
  isRecommended: boolean
  isAllYouCanDrink: boolean    // 飲み放題の対象
  isSpicy: boolean
  visible: boolean
  soldOut: { at: string; byRole: Role } | null
  sortOrder: number
}

export type PhotoRef = { kind: 'file'; path: string } | { kind: 'idb'; id: string }

export type Allergen =
  // 特定原材料（8品目）
  | 'えび' | 'かに' | 'くるみ' | '小麦' | 'そば' | '卵' | '乳' | '落花生'
  // 特定原材料に準ずるもの（20品目）
  | 'アーモンド' | 'あわび' | 'いか' | 'いくら' | 'オレンジ' | 'カシューナッツ' | 'キウイフルーツ' | '牛肉'
  | 'ごま' | 'さけ' | 'さば' | '大豆' | '鶏肉' | 'バナナ' | '豚肉' | 'マカダミアナッツ' | 'もも' | 'やまいも' | 'りんご' | 'ゼラチン'

export interface OptionGroup {
  id: string; name: string                      // 焼き方
  required: boolean; multiple: boolean
  options: { id: string; name: string; extra: number }[]   // 塩 / たれ（+0）
}

export type TableKind = 'table' | 'counter' | 'zashiki'
export interface Table { id: string; name: string; kind: TableKind; seats: number; x: number; y: number; w: number; h: number }

export interface Visit {                          // 1回の来店（卓に座ってから会計まで）
  id: string
  tableIds: string[]                              // 合体した卓は複数
  guests: number
  seatedAt: string
  course: { courseId: string; startedAt: string } | null
  billRequestedAt: string | null
  closedAt: string | null                         // 会計の完了
  clearedAt: string | null                        // 片付けの完了
}

export interface Order {
  id: string
  visitId: string
  placedAt: string
  placedBy: 'guest' | 'hall'
  lines: OrderLine[]
}

export interface OrderLine {
  id: string
  menuItemId: string
  nameSnapshot: string                            // 注文した時点の品名と価格を残す
  unitPriceSnapshot: number                       // 選択肢の追加料金を含む
  allYouCanDrink: boolean                         // 注文した時点で飲み放題の対象だったか（0円になる）
  options: { groupName: string; optionName: string; extra: number }[]
  quantity: number
  note: string
  station: Station
  readyAt: string | null                          // 厨房の完成
  servedAt: string | null                         // ホールの提供済み
  canceled: { at: string; reason: CancelReason } | null
}

export type CancelReason = 'mistake' | 'guest' | 'other'

export interface Call { id: string; visitId: string; item: string; note: string; createdAt: string; doneAt: string | null }

export interface Bill {
  id: string
  visitId: string
  closedAt: string
  discount: { kind: 'amount' | 'percent'; value: number } | null
  total: number                                   // bill.ts で算出した値をその時点で確定して残す
  tax: number
  payments: { method: 'cash' | 'card' | 'qr'; amount: number; received?: number }[]
  voided: { at: string; reason: string } | null
}

export interface DailySummary {                   // 分析用。過去14日ぶんはシードで持つ
  date: string
  sales: number; guests: number; visits: number
  byHour: { hour: number; sales: number; guests: number }[]
  byItem: { menuItemId: string; count: number; sales: number }[]
  avgServeMin: number
}
```

**派生値は保存しない。** 卓の状態（FR-502）、注文の品の進み具合（FR-206）、遅れの判定（FR-405）、今日の数字（FR-701）は、`src/lib/calc/` の関数で毎回算出する。例外は `Bill.total` と `Bill.tax`（会計の時点の金額を確定させるため）。

## シードデータ（`src/lib/seed/`）

**シードは「いま」を基準に作る。** `buildSeed(now: Date)` の純粋な関数にし、同じ `now` から同じデータができること（乱数は種を固定）。

| データ | 件数 | 内容 |
|---|---|---|
| 店 | 1 | 炉端と酒 あかり。お通し ¥390、ラストオーダー フード23:00／ドリンク23:30、飲み放題 90分 ¥1,650・120分 ¥2,200（終了の30分前がラストオーダー） |
| 卓 | 16 | テーブル1〜8（4席×6・6席×2）、カウンター1〜6（1席）、座敷1〜2（8席）。合計 58席 |
| カテゴリ | 9 | 本日のおすすめ／焼き鳥／炉端焼き／お刺身／揚げ物／一品料理／〆（しめ）／甘味／ドリンク（ビール・サワー・ハイボール・日本酒・焼酎・ソフトドリンクは「ドリンク」の中の見出しにする） |
| メニュー | 54 | フード36（焼き鳥8・炉端焼き5・刺身4・揚げ物5・一品7・〆4・甘味3）＋ドリンク18。うち飲み放題の対象 14、おすすめ 5、辛い 3、選択肢あり 12 |
| いまの来店 | 9卓 | 下の表のとおり、状態がばらけるように作る |
| 今日の会計済み | 11件 | 「いま」の3時間前〜30分前に会計した来店（売上と客数が今日のようすに出る） |
| 過去14日 | 14日 | `DailySummary`。曜日で客数を変える（金土が多い・月が少ない）。雨の日を2日つくり客数を2割減らす |

**いまの来店（シードの見本）**

| 卓 | 人数 | 着席 | 飲み放題 | 状態を作るための注文 |
|---|---|---|---|---|
| テーブル1 | 4 | 95分前 | 120分（残り25分） | ほぼ提供済み。ドリンク1つが提供待ち |
| テーブル2 | 2 | 12分前 | なし | 注文2件が厨房で調理中 |
| テーブル3 | — | — | — | **空席**（お客さまのロールの初期の卓。ここから試してもらう） |
| テーブル4 | 4 | 40分前 | 90分（残り50分） | 呼び出し中（取り皿） |
| テーブル5 | 6 | 128分前 | なし | 会計待ち |
| テーブル7 | 3 | 25分前 | なし | 焼き場の品が遅れ（16分） |
| カウンター2 | 1 | 50分前 | なし | 提供済みのみ（着席中） |
| カウンター5 | 2 | 8分前 | なし | ドリンクのみ注文・完成待ち |
| 座敷1 | 7 | 160分前 | なし | 長居の印・片付け中ではない |

テーブル6 は「片付け中」（会計の完了から4分）にする。

**品名と価格の見本**（すべて税込）：焼き鳥 盛り合わせ（5本）¥1,280／ねぎま ¥220／つくね（月見）¥320／皮 ¥200／砂肝 ¥200／レバー ¥220／ぼんじり ¥240／手羽先 ¥260、ほっけの炉端焼き ¥980／厚揚げ ¥480／椎茸の炉端焼き ¥420、刺身三点盛り ¥1,580／〆さば ¥780、鶏の唐揚げ ¥780／アジフライ ¥680、だし巻き玉子 ¥680／ポテトサラダ ¥480／冷やしトマト ¥420／枝豆 ¥380／たこわさ ¥420、焼きおにぎり ¥380／鶏そば ¥880、生ビール（中）¥650／ハイボール ¥550／レモンサワー ¥500／日本酒（1合）¥780〜／烏龍茶 ¥380。**実在の店の品名・写真・価格表を写さない。**

> 上の金額は6.7の計算例と合わせてある。シードの価格を変えたら `bill.test.ts` の例も直すこと。

## 画像

- メニューの写真は54品すべてに用意する。**写真のない品を作らない**（メニューの見栄えがデモの第一印象を決めるため）
- 写真は、利用条件で商用利用が認められているもの（Unsplash・Pexels などのライセンス、またはAIで生成した画像）だけを使い、`public/photos/menu/CREDITS.json` に出典を記録する。スタートページの下に「写真のクレジット」へのリンクを置く
- **写真の上に文字を重ねない。写真を暗くしない。** 料理がおいしそうに見えることを最優先する
- 縮小版（幅480px・WebP）と大きい版（幅1280px・WebP）を用意し、一覧は縮小版、詳細は大きい版を使う
- AIで生成する場合は、器と料理だけを写し、文字・ロゴ・人の顔が入らないようにする。焼き鳥の串の本数など、品名と食い違う絵は作り直す

## ストアとリポジトリ

| ストア（`src/lib/store/`） | 中身 |
|---|---|
| `data.ts` | store・tables・categories・menuItems・visits・orders・calls・bills・dailySummaries |
| `ui.ts` | 現在のロール・お客さまの卓・並べて見るの状態・音の有無・ガイドの既読・カート（卓ごと） |

| リポジトリ（`src/lib/repo/`） | 主なメソッド |
|---|---|
| `menu.ts` | `listMenu(scope)`, `getItem(id)`, `saveItem(input)`, `reorder(categoryId, ids)`, `setSoldOut(id, soldOut)` |
| `visits.ts` | `seat(tableId, guests, courseId?)`, `getVisitByTable(tableId)`, `requestBill(visitId)`, `moveTable(...)`, `mergeTables(...)`, `clear(tableId)` |
| `orders.ts` | `placeOrder(input)`, `listKitchenTickets(station?)`, `markReady(lineIds)`, `undoReady(lineId)`, `listToServe()`, `markServed(lineIds)`, `cancelLine(lineId, reason)` |
| `calls.ts` | `createCall(visitId, item, note)`, `listOpenCalls()`, `doneCall(id)` |
| `bills.ts` | `previewBill(visitId, discount?)`, `closeBill(input)`, `voidBill(id, reason)`, `listTodayBills()` |
| `reports.ts` | `today()`, `range(days)` |
| `_scope.ts` | ロールごとの見える範囲（FR-003）。お客さまは自分の来店だけ |
| `_delay.ts` | 擬似的な待ち時間 |

**同期（`src/lib/sync/`）**：ストアの変更を `BroadcastChannel('saji')` で他のタブへ送り、受け取った側はストアを読み直す。送るのは「何が変わったか」の短い知らせだけ（`{ type: 'order.placed', id }` など）。受け取った知らせから、通知の音と強調を出す。

---

# 8. デザイン要件

## アートディレクション

**「温かい木と白い器」。** 炉端の店の、白木のカウンターと白い器のような、明るく清潔で温かい画面にする。**主役は料理の写真**。画面の色と飾りは写真の邪魔をしない。

- お客さまの画面：白い地・写真を大きく・角の丸いカード。指で押しやすく、迷わない。高級店ではなく「気軽な居酒屋」の親しみやすさ
- 厨房モニター：**暗い地に明るい札**（厨房の照明の下で見やすく、画面の光がまぶしすぎない）。文字は大きく太く。遠くから経過時間と卓の名前が読める
- ホール・会計・店長：**墨色の左のメニュー**（幅232px。店名を明朝で、いまの項目に朱の細い線）と、白い地の業務の画面。色は墨・石の中間色に朱をひとつ。**緑と黄色は使わない**。状態の色は落ち着いた色だけにし、文字と印を必ず添える

## デザイントークン

色は `src/styles/tokens.css` の CSS 変数にだけ置く（チャンネル値で定義し、Tailwind の不透明度の指定が効くようにする）。

| トークン | 用途 | 値（目安） |
|---|---|---|
| `--brand` | 主な操作（注文する・カートに入れる・会計を完了する） | 朱色 #C2410C（白い文字とのコントラスト 4.5:1 以上を実測すること） |
| `--brand-strong` | 押した時・強調 | #9A3412 |
| `--wood` | 見出しの小さな飾り・カテゴリのタブの下線 | 白木 #B98A55 |
| `--ink` / `--ink-2` / `--ink-3` | 文字（本文／補足／薄い補足） | #1C1917 / #44403C / #6B645C |
| `--surface` / `--surface-2` / `--line` | 地・一段沈んだ地・線 | #FFFFFF / #F7F4EF / #E7E1D8 |
| `--kds-bg` / `--kds-card` | 厨房の地・札 | #1A1A1A / #FAFAF9 |
| 状態の色 | 空席／着席中／料理待ち／提供待ち／呼び出し中／会計待ち／片付け中 | 点線の枠（色なし）／墨 #44403C／銅 #8C5A2B／藍 #1F4E79／朱 #C2410C／葡萄 #6D3B5E／枯茶 #7A6A58。卓は白く、状態は左の細い線と札で示す。**それぞれ文字と印を必ず併記** |
| 遅れの色 | ふつう／注意／遅れ | 墨 #2E2A27 ／ 銅 #8C5A2B ／ 赤 #B42318（札の上の帯。「完成」は墨のボタン、「全部完成」は墨の枠のボタン） |

## タイポグラフィ

| 用途 | 指定 |
|---|---|
| 和文 | 端末の日本語フォント（Mac・iPhone はヒラギノ、Windows は游ゴシック）。**Webフォントは読み込まない**（v1.1。Noto Sans JP・Zen Old Mincho を読むと Lighthouse が80前後まで落ちたため、NFR-07 を優先）。PDF だけは Noto Sans JP を同梱する |
| 店名・カテゴリの見出し | 明朝（ヒラギノ明朝・游明朝）。**見出しのみ**に使う |
| 数字（価格・時刻・経過時間） | 等幅の数字（`font-variant-numeric: tabular-nums`） |
| お客さまの本文 | 16px・ウェイト500。品名 17px・700。価格 17px・700 |
| 業務の画面の本文 | 15px・ウェイト500 |
| 厨房の札 | 卓の名前 28px・700、品名 20px・700、経過時間 24px・700 |

**小さく細い文字にしない。** 補足の文字も 13px 以上・色は `--ink-3` 以上の濃さにする。

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

- 余白は 4px の倍数。カードの角丸 14px、ボタンの角丸 12px
- お客さまの画面は幅 390px を基準に作り、幅 600px 以上では中央に最大幅 560px で置く
- 厨房モニターは 1024×768（横向きタブレット）を基準に作る。1920×1080 では札を6枚以上並べる
- ホールの配置図は、スマホでは拡大縮小せずに縦スクロールで全卓が見えるよう、配置を縦長に組み替える（`x, y` はパソコン用、スマホでは種類ごとの一覧に並べ直す）
- 押せるものは 44×44px 以上。厨房の「完成」は 56px 以上

## 主要コンポーネント仕様

| コンポーネント | 仕様 |
|---|---|
| `MenuCard` | 写真（4:3・角丸）・品名（2行まで）・価格・印。品切れは写真の不透明度 0.45 と「品切れ」の札。押すと商品の詳細 |
| `CartBar` | 画面下に固定。品数の丸・合計・「注文へ進む」。品を入れると0.3秒だけ持ち上がる |
| `ItemSheet` | 下から出るシート。上の写真は全幅。選択肢は押しやすい行。下に固定の「カートに入れる（¥1,280）」 |
| `ProgressRow` | 品名・数量・3段の進み具合（点と線）・時刻 |
| `Ticket`（厨房の札） | 上の帯に卓の名前と経過時間（遅れで色が変わる）。品の行ごとに「完成」。下に「全部完成」。代理の注文は「ホール」の札 |
| `TableTile`（配置図の卓） | 卓の形（テーブル＝角丸の四角・カウンター＝小さな丸・座敷＝大きな四角に畳の模様）・状態の色と印・人数・滞在時間・飲み放題の残り |
| `StatusBadge` | 状態の色＋印＋文字。色だけにしない |
| `MoneyText` | 「¥1,280」の形に整える。マイナスは「−¥200」 |
| `DemoBar` | 4章の仕様 |
| `PhoneFrame` | 並べて見るの左の枠。幅 390px・高さは画面に合わせる。中は本物の画面（iframe ではなく同じアプリの部品として描く） |

## インタラクション要件

- 注文の確定・完成・提供済み・対応済みは、**押した直後に画面を変える**（待ちの間は押したものを「送信中」にし、失敗したら元に戻して理由を出す）
- 品切れの切り替えは押した瞬間に変わり、他の画面に1秒以内に届く
- 厨房の札が増えても、いま見ている札の位置がずれない（新しい札は右端に足す）
- 卓の配置図の状態が変わったら、その卓を0.6秒だけ光らせる
- 元に戻せる操作（完成・提供済み）は、5秒間「元に戻す」を画面の下に出す

## モーション

- 動きは 150〜300ms。`prefers-reduced-motion` では動きを止め、色の変化だけにする
- 出現の動きで要素を `opacity: 0` のまま止めないこと（`animation-fill-mode` は `both` を使わず、終わった状態が見えるようにする）

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

| ID | 要件 |
|---|---|
| A11Y-01 | 本文と背景のコントラスト比 4.5:1 以上（実測すること） |
| A11Y-02 | 状態・遅れ・品切れを色だけで示さない（文字と印を併記） |
| A11Y-03 | キーボードだけで、メニュー → カート → 注文、厨房の完成、ホールの提供済み、会計の完了ができる |
| A11Y-04 | 下から出るシートとダイアログは、開いたら中に焦点を移し、Esc で閉じ、閉じたら元の場所へ焦点を戻す |
| A11Y-05 | 新しい注文・呼び出しの到着を、画面の読み上げにも知らせる（`aria-live="polite"`） |
| A11Y-06 | 写真には品名を代替テキストに入れる |
| A11Y-07 | 文字サイズ200%でも、注文の流れが最後まで操作できる |

## ライティング規約

- お客さまには敬語（「ご注文を受け付けました」「店員が伺います」）。店員の画面は短い言葉（「完成」「提供済み」「対応済み」）
- 価格は「¥1,280」。「税込」は合計の横に1か所だけ書く（品ごとに書かない）
- 時間は「12分前」「残り25分」「遅れ 16分」
- **使わない言葉**：アイテム・チケット・ステータス・オーダー（「注文」と書く）・ユーザー・カスタマー・キュー
- エラーは「何が起きたか＋どうすればいいか」（例：「だし巻き玉子が品切れになりました。カートから外してください」）

---

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

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

| レイヤ | 技術 | 備考 |
|---|---|---|
| ビルド | Vite 6 ／ TypeScript strict | 静的ファイルとして配信する |
| 画面 | React 19 ／ React Router 7（ブラウザ内で画面を切り替える方式） | |
| スタイリング | Tailwind CSS v4 + CSS Variables | トークンは CSS 変数で定義（チャンネル値） |
| UIコンポーネント | Radix UI（Dialog・Tabs・Toggle など必要なものだけ） | a11y要件を自前実装せずに満たす |
| 状態管理 | Zustand + persist ミドルウェア | localStorage に永続化 |
| タブ間の同期 | BroadcastChannel（ブラウザ標準） | 使えない場合は storage イベント |
| フォーム | React Hook Form + Zod | メニューの編集・設定 |
| ドラッグ | dnd-kit | メニューの並べ替え・配置図の編集。**キーボード操作対応が必須のため** |
| グラフ | Recharts | 店長の画面。動的に読み込む |
| QRコード | qrcode | 卓のQR。動的に読み込む |
| PDF | @react-pdf/renderer | レシート・領収書・QRの印刷用。**ブラウザ内で生成する**。動的に読み込む |
| 写真の保存 | idb-keyval | 店長が追加した写真だけ |
| 日付 | date-fns（ja locale） | |
| アイコン | lucide-react | |
| 配信 | Cloudflare Workers（静的アセット） | 全ルートを `index.html` に返す設定にする（`not_found_handling: "single-page-application"`） |
| テスト | Vitest / Playwright / axe-core | |

**上記以外のライブラリを入れる前に必ず提案し、承認を得ること。**

**PDF の日本語について：** @react-pdf/renderer は日本語フォントを登録しないと文字が出ない。Noto Sans JP の TTF（静的ウェイト 400 と 700）を `public/fonts/` に置き `Font.register` する。さらに、日本語は単語の区切りがないため、**既定の自動ハイフネーションで「-」が行末に入る**。`Font.registerHyphenationCallback(word => [word])` で無効にすること。

**音について：** 通知の音は Web Audio API で短い音を合成する（音のファイルを置かない）。ブラウザは利用者が一度画面を押すまで音を出さないので、最初の操作で `AudioContext` を作り直す。

## ディレクトリ構成

```
/
├── CLAUDE.md                  # このファイル
├── wrangler.jsonc             # 公開の設定（静的アセット + SPA）
├── public/
│   ├── photos/menu/           # メニュー写真（480・1280 の WebP）と CREDITS.json
│   └── fonts/                 # PDF用の日本語フォント
└── src/
    ├── main.tsx  app.tsx      # ルーター・デモ切替バー・並べて見る
    ├── routes/
    │   ├── start.tsx                      # SC-000
    │   ├── guest/                         # SC-C01〜C08
    │   ├── kitchen/                       # SC-K01, K02
    │   ├── hall/                          # SC-H01〜H05
    │   ├── register/                      # SC-R01〜R03
    │   ├── manager/                       # SC-M01〜M06
    │   └── credits.tsx                    # 写真のクレジット
    ├── components/
    │   ├── ui/                # Radix ベースのプリミティブ
    │   ├── guest/             # MenuCard, CartBar, ItemSheet, ProgressRow
    │   ├── kitchen/           # Ticket, StationTabs, ItemTally
    │   ├── hall/              # FloorMap, TableTile, QueueList
    │   ├── register/          # BillLines, PaymentPad, SplitPanel
    │   ├── manager/           # MetricCard, Charts（動的読み込み）
    │   ├── shared/            # StatusBadge, MoneyText, Elapsed
    │   └── demo/              # DemoBar, SideBySide, PhoneFrame, GuideTour, ResetButton
    ├── lib/
    │   ├── types/  seed/  store/  repo/  sync/
    │   ├── calc/              # bill.ts（金額）, table-status.ts（卓の状態）, line-status.ts（品の進み具合）, delay.ts（遅れ）, reports.ts（今日・分析）, last-order.ts
    │   ├── pdf/               # receipt.tsx, invoice.tsx（領収書）, qr-sheet.tsx
    │   ├── sound/             # 通知の音
    │   ├── i18n/terms.ts      # 飲食店の言葉・英語の表記
    │   └── utils/
    ├── styles/tokens.css
    └── e2e/                   # Playwright
```

## コーディング規約

- TypeScript strict。`any` 禁止。やむを得ない場合は `unknown` + 型ガード
- ファイル名は kebab-case、コンポーネントは PascalCase
- 1ファイル300行を超えたら分割を検討する
- **コンポーネントから Zustand ストアを直接参照しない。必ず `src/lib/repo/` 経由**
- **金額・状態・遅れ・集計の計算は `src/lib/calc/` に置き、コンポーネントに埋め込まない**（テスト対象にするため）
- 派生値をストアに保存しない。常に算出する（例外は 7章の `Bill.total`・`Bill.tax`）
- 「いま」の時刻は `src/lib/utils/now.ts` の `now()` だけから取る（テストで時刻を固定するため）
- 飲食店の言葉は `src/lib/i18n/terms.ts` にまとめる
- コミットは1タスクごと。メッセージに要件IDを含める
  例：`feat(kitchen): 遅れの色分けを実装 (FR-405)`

---

# 10. 非機能要件

| ID | 要件 | 目標値 |
|---|---|---|
| NFR-01 | LCP（スマホ・お客さまのメニュー） | 2.5秒以下 |
| NFR-02 | INP（操作への応答） | 200ms以下 |
| NFR-03 | CLS | 0.1以下（写真の枠の大きさを先に確保する） |
| NFR-04 | 注文の確定から、別タブの厨房モニターに表示されるまで | 1秒以内 |
| NFR-05 | 厨房に札が40枚あってもスクロールと「完成」がもたつかないこと | — |
| NFR-06 | 初期JSバンドルサイズ（gzip後） | お客さまの画面 180KB以下（PDF・グラフ・QR・店長の画面は動的に読み込む） |
| NFR-07 | Lighthouse | Performance 90 / Accessibility 95 以上（お客さまのメニュー） |
| NFR-08 | 対応ブラウザ | Chrome / Safari / Edge 最新2バージョン、iOS Safari 16以降 |
| NFR-09 | ユーザー入力（ひとこと・品名）はサニタイズし、CSVの数式インジェクション（`=`, `+`, `-`, `@` 始まり）を無害化すること | — |
| NFR-10 | localStorage の容量上限（5MB程度）に近づいた場合、警告を表示し、データを破損させないこと（古い会計の明細から集計に畳む） | — |
| NFR-11 | 画面幅 320px〜2560px のどこでも、横にはみ出さず崩れないこと | — |
| NFR-12 | メニューの写真54枚は、一覧で遅延読み込みにし、最初の画面に必要な分だけを先に読むこと | — |

## 本番化するときに必要になること（デモ本体の要件ではない）

将来このデモを実際の店で使う形にする場合、以下が追加で必要になる。**お客様への提案の場で聞かれた際に説明できるよう、記録として残す。**

- **注文の受け付けと配信はサーバーで行う必要がある。** 本デモの `src/lib/repo/` と `src/lib/sync/` がその置き換え地点（リアルタイム配信・同じ卓の複数のスマホの注文の合流）
- **QRコードのいたずら対策。** 卓のQRを写真に撮って店の外から注文されないよう、来店ごとに変わる番号（着席の案内で発行し、会計で失効）を使う
- 決済を組み込む場合は、決済代行会社との契約と、カード情報を自社で持たない構成（決済代行会社の画面へ移る方式）が必要になる
- POSレジ・キッチンプリンターとの接続、インボイス制度に対応した領収書（登録番号の記載）
- アレルギーの表示は、店が責任を持って正しい情報を入れる運用が必要。画面上の注意書きも本番では店の文言に合わせる
- お酒の注文時の年齢確認（20歳未満の飲酒防止）の運用
- 通信が切れた場合の扱い（注文の再送・二重注文の防止）
- **本デモはお客さまのデータをサーバーに送信しないため、これらの義務は発生しない。** ただし「デモである」旨は画面上に常時明示する

---

# 11. 実装タスク

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

## Phase 0 — 基盤とデザインシステム（2日）

### 0-1. 初期化
- [x] Vite 6 / React 19 / TypeScript strict / React Router 7 / Tailwind v4 で初期化
- [ ] ESLint / Prettier、`npm run check` で lint + 型チェック + テスト（2026-10-02 時点：ESLint・Prettier は入れていない。`npm run check` は型チェックとテストのみ）
- [x] 9章のディレクトリ構成を作成
- [x] `wrangler.jsonc` を置き、静的アセット配信と `not_found_handling: "single-page-application"` を設定

### 0-2. 型・シード・ストア・同期
- [x] 7章の型を定義
- [x] `buildSeed(now)` を実装し、7章の件数と「いまの来店」の状態になることをテストで確認
- [x] ストア（persist）とリポジトリの土台、`_delay.ts`、`_scope.ts` (FR-003)
- [x] `src/lib/sync/`：BroadcastChannel で別タブへ伝える (FR-006)

### 0-3. デザインシステム
- [x] `tokens.css`（8章）とフォントの読み込み
- [x] 共通部品：Button・Sheet・Dialog・Tabs・StatusBadge・MoneyText・Elapsed
- [x] デモ切替バー (FR-001, FR-002, FR-004, FR-009)

## Phase 1 — お客さまの注文（3日）

### 1-1. メニュー
- [x] メニュー写真54枚を用意し、480・1280 の WebP と CREDITS.json を作る（7章「画像」）
- [x] 来店の受付 SC-C01 (FR-101, FR-102)
- [x] メニュー SC-C02（カテゴリのタブとスクロールの連動・おすすめ・品切れ・飲み放題の表示）(FR-103〜FR-106)
- [x] 商品の詳細 SC-C03（選択肢・アレルギー・ひとこと）(FR-107〜FR-109)

### 1-2. カートと注文
- [x] カートの帯とカート SC-C04 (FR-201〜FR-203, FR-205)
- [x] 注文の確定と二度押しの防止 (FR-204)
- [x] 注文の進み具合 SC-C05 (FR-206, FR-208)
- [x] 店員を呼ぶ SC-C06 (FR-301, FR-302)

## Phase 2 — 厨房とホール（3日）

### 2-1. 厨房モニター
- [x] 札の並びと調理場の切り替え SC-K01 (FR-401, FR-402, FR-409, FR-410)
- [x] 完成・全部完成・取り消し (FR-403, FR-404)
- [x] 遅れの色分け (FR-405)
- [x] 新しい注文の強調と音 (FR-406)
- [x] 品切れのシート SC-K02 (FR-407)
- [x] 品ごとのまとめ (FR-408)

### 2-2. ホール
- [x] 卓の状態の算出 `calc/table-status.ts`（優先順位つき）とテスト (FR-502)
- [x] 卓の配置図 SC-H01（パソコンの配置・スマホの一覧）(FR-501, FR-503, FR-504)
- [x] 卓の詳細 SC-H02・着席の案内 SC-H04 (FR-505)
- [x] 提供待ち・呼び出し SC-H03 (FR-506〜FR-508)
- [x] 代理の注文 SC-H05 (FR-509)
- [x] 片付け完了 (FR-511)、卓の移動・合体 (FR-510)

## Phase 3 — 会計とお会計（2日）

- [x] `calc/bill.ts` と `bill.test.ts`（6.7 の例・値引き・取り消し・割り勘の端数・0円の卓）
- [x] お客さまのお会計 SC-C07・会計の依頼 (FR-303〜FR-306)
- [x] 会計 SC-R01（明細・取り消し・値引き・支払い方法・お釣り・割り勘）(FR-601〜FR-606)
- [x] レシート・領収書のPDF SC-R02 (FR-607)
- [x] 今日の会計と取り消し SC-R03 (FR-608)
- [x] ご来店ありがとうございました SC-C08

## Phase 4 — 店長と並べて見る（3日）

### 4-1. 店長
- [x] 今日のようす SC-M01 (FR-701〜FR-704)
- [x] 分析 SC-M02 (FR-705)
- [x] メニューの管理・品の編集 SC-M03, M04（並べ替えはドラッグとキーボード、写真の縮小と IndexedDB）(FR-706, FR-707)
- [x] 卓とQR SC-M05（QRの印刷用PDF）(FR-708)
- [x] お店の設定 SC-M06（ラストオーダーの「いまから◯分後」）(FR-709)
- [x] 売上の書き出し (FR-710)

### 4-2. 並べて見るとスタート
- [x] 並べて見る（左にスマホの枠・右に店の画面）(FR-005)
- [x] スタートページ SC-000
- [x] 3ステップのガイド (FR-008)
- [x] 権限のない画面の案内 (FR-007)

## Phase 5 — 仕上げ（2日）

### 5-1. 体験の総点検
- [x] 4章「ロールを跨ぐ体験」の8つを、並べて見ると別タブの両方で手動で確認する（並べて見るは8つすべてを E2E で確認。別タブは「注文が厨房に届く」を E2E で確認）
- [x] 全画面を開き、**空の画面が1つもないこと**を確認する
- [x] 全画面の空状態・読み込み中・エラー状態を確認する
- [x] **全画面の文言を飲食店の言葉で読み直す。** 8章の「使わない言葉」が残っていないこと
- [x] localStorage 容量上限時の警告 (NFR-10)

### 5-2. アクセシビリティ監査
- [x] axe-core を全画面に実行し、Critical / Serious を0件に
- [x] キーボードのみで、注文・完成・提供済み・会計の完了まで操作できることを確認
- [x] 本文のコントラスト比を実測して 4.5:1 以上を確認 (A11Y-01)
- [x] 文字サイズ200%での確認 (A11Y-07)

### 5-3. パフォーマンス
- [x] PDF・グラフ・QR・店長の画面を動的読み込みに切り出し、お客さまの画面の初期バンドルを180KB以下に (NFR-06)
- [x] 別タブへの反映が1秒以内であることを実測 (NFR-04)
- [x] Lighthouse（スマホ・メニュー）で Performance 90 / Accessibility 95 (NFR-07)
- [x] 320px〜2560px で崩れないことを確認 (NFR-11)

### 5-4. テストと公開
- [x] Playwright で 5章の主要フロー1〜5の E2E を実装・実行（並べて見ると、2つのタブの両方）
- [x] Vitest：`src/lib/calc` `src/lib/repo/_scope` `src/lib/seed` のカバレッジ80%以上
- [x] Cloudflare Workers へ公開（`npx wrangler deploy`）
- [x] 公開URLで、直接開いた画面のURL（例 `/t/table-3/menu`・`/kitchen`）が 404 にならないことを確認する

---

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

> **工数配分の意図：** Phase 0 で同期（別タブへの反映）とシードを先に作るのは、このデモの価値が「つながり」にあるため。お客さま・厨房・ホールをそれぞれ作り込んでも、つながりが後付けだと状態の食い違いが残る。**卓の状態・品の進み具合・金額は、最初から `src/lib/calc/` の関数1つずつで決め、すべての画面がそれを使う。**

---

# 12. 受入基準

1. 6章の優先度 P1 の要件がすべて実装されていること
2. 5章の主要フローが、最初から最後まで完走すること。**フローと4章の体験に出てくる機能は、6章の優先度が P2・P3 でも必須とする**
3. 4章「ロールを跨ぐ体験」の8つが、並べて見る・別タブの両方で動作すること
4. お客さまのロールで、他の卓の注文・金額と店全体の数字が、画面にもリポジトリの戻り値にも含まれないこと。スコープ判定が `src/lib/repo/_scope.ts` に集約されていること
5. **お客さまのお会計・ホールの卓の詳細・会計の画面の合計が、すべての卓で1円も違わないこと**（金額の計算が `calc/bill.ts` の1か所だけで行われていること）
6. 6.7 の計算例が `bill.test.ts` で通ること
7. 注文の確定から別タブの厨房モニターに表示されるまで1秒以内であること
8. 品切れ・ラストオーダー後・飲み放題の終了後の品が、注文として一度も確定されないこと
9. 全画面のいずれにも空の状態がなく、営業中の居酒屋らしいデータが表示されていること。メニューの全54品に写真があること
10. リロード後も操作結果が保持され、「デモをリセット」で「いま」を基準にした初期状態に戻ること
11. レシート・領収書・卓のQRのPDFが**実際にダウンロードでき、日本語が正しく表示されること**
12. axe-core で Critical / Serious の指摘が0件であること
13. Lighthouse の基準値を満たすこと
14. データアクセスがすべて `src/lib/repo/` を経由しており、**コンポーネントが Zustand ストアを直接参照していない**こと
15. スマホ（375px）でお客さまの注文の流れ、タブレットの横向き（1024×768）で厨房モニター、スマホでホールの配置図が快適に使えること

---

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

1. **仕様がこの文書にない場合は、実装せずに質問する。** 推測で作らない
2. **「つながり」と「空の画面を作らない」は削減対象外。** 速度を出すために削らない
3. スコープ外（3章 Won't have）は、思いついても実装しない。特に実際の決済とプリンターの接続
4. 「デモだから」を理由に品質を落とす判断はしない
5. コンポーネントからストアを直接触りたくなったら、それはリポジトリ層に足りないメソッドがあるということ
6. **迷ったら混んでいる金曜の20時の店を思い浮かべる。** 厨房は手が汚れていて画面を見る時間は1秒、ホールは両手に皿を持っている。その人が一目で次にやることを分かるか
7. **料理の写真を暗くしたり、写真の上に文字を重ねたりしない。** おいしそうに見えることが、お客さまの注文を増やす
8. 金額の計算を2か所に書かない。表示のために計算したくなったら `calc/bill.ts` を呼ぶ

---

# 改訂の記録

| 版 | 日付 | 内容 |
|---|---|---|
| 1.0 | 2026-10-01 | 初版 |
| 1.1 | 2026-10-02 | 実装を反映。客席の合計を58席に訂正（7章の内訳に合わせる）。スタートページを案内役が話して自動で入る形に。案内役「さじ」（F-S07）。Webフォントをやめて端末のフォントに。判断は `docs/DECISIONS.md` |
| 1.2 | 2026-10-02 | 案内役「さじ」を顔だけのデザイン（まるい顔に朱のはちまき）にした。店の画面（ホール・会計・店長・厨房）のデザインを作り直した（菊池さんの指示）。墨色の左のメニュー、緑と黄色をやめて落ち着いた状態の色に |


---

## 付録　本番運用に向けて（ソウゾウ合同会社より）

> **この章は実装の対象ではありません。Claude Code は、この章の内容を実装しないでください。** 要件定義書を読んでいる方へのご案内です。

この要件定義書は、画面と動きを確かめるための**デモ**として書かれています。社内やお客さまに実際に使ってもらうには、次の4つが別に必要です。

| 項目 | デモでは | 本番では |
|---|---|---|
| データの保存 | データはその端末のブラウザの中にしか残りません。ほかの端末やほかの人とは共有されず、消えることもあります。 | サーバーのデータベースに保存し、バックアップと復元ができるようにします。 |
| セキュリティ | ログインがなく、誰でもすべての画面とデータを見られます。 | ログイン、権限（誰が何を見られるか）、通信とデータの暗号化、不正なアクセスへの対策を入れます。 |
| ガバナンス（運用ルール） | 決めていません。 | 誰がいつ何をしたかの記録、個人情報の扱い（プライバシーポリシー・同意）、アカウントの発行と削除、障害のときの連絡体制を決めます。 |
| 公開・デプロイ | 手元で動かすか、デモとして公開するだけです。 | 独自ドメイン、本番とテストの環境分け、更新の手順、監視と障害対応、月々の費用の管理を整えます。 |

本番運用をお考えの方は、ぜひ一度ご相談ください。最適なプランのご紹介と、進め方をお伝えします。

- 日程を選んで相談する（代表 西澤）：https://vszh6zudz50.jp.larksuite.com/scheduler/e7fecdad1a756dbe
- 公式LINE：https://lin.ee/UNwvWjp
- お問い合わせフォーム：https://service.souzoh-official.com/contact/
