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

**版数** 1.0（DBレス構成 / 記事埋め込み型デモ）／ **作成日** 2026-08-17 ／ **発行** ソウゾウ合同会社
**用途** SEO記事「【デモで試せる】Claude Codeで予約システム・予約アプリを自作する方法と費用｜動画つき資料【2026年】」に組み込む実演デモ

---

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

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

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

> **姉妹プロジェクトとの関係**
> HIREBASE（求人）／ RELATE（顧客管理）／ CASTA（動画配信）／ FIELDPIN（位置情報）／ KANADE（音楽）／ MIWAKE（画像認識）に続く7本目。**並べて「同じテンプレ」と思われた時点で失敗。**
> HIREBASE＝明朝・温かい紙白・余白／ RELATE＝ゴシック・白・13px高密度・罫線／ CASTA＝ダーク・無彩色／ FIELDPIN＝地図全画面・大型UI／ KANADE＝ダーク・色が曲ごとに変わる／ MIWAKE＝無彩色グレー・画像上の注釈／
> **AKIMA＝丸ゴシック・青みのある白・時間を面積で見せるタイムライン（予約させる）。**
> **7本の中で唯一、丸ゴシックを使う。** 書体構成だけで別プロダクトと分かるようにする。

---

## 目次

1. [プロジェクト概要](#1-プロジェクト概要)
2. [枠の壁 — この記事の核心](#2-枠の壁--この記事の核心)
3. [記事への組み込み設計](#3-記事への組み込み設計)
4. [アーキテクチャ方針](#4-アーキテクチャ方針)
5. [スコープ定義](#5-スコープ定義)
6. [ロールとデモ切替](#6-ロールとデモ切替)
7. [画面一覧とユーザーフロー](#7-画面一覧とユーザーフロー)
8. [機能要件](#8-機能要件)
9. [データ設計](#9-データ設計)
10. [デザイン要件](#10-デザイン要件)
11. [技術要件・ディレクトリ構成](#11-技術要件ディレクトリ構成)
12. [非機能要件・法令](#12-非機能要件法令)
13. [費用設計](#13-費用設計)
14. [実装タスク](#14-実装タスク)
15. [受入基準](#15-受入基準)

---

# 1. プロジェクト概要

## 背景と目的

「予約システムを作りたい」という相談は、**見た目の簡単さと実装の難しさのギャップが最も大きい**領域。カレンダーを出して枠を選ばせるだけに見えるが、実際には次の2つが本体になる。

1. **空き枠の計算** — 営業時間・スタッフのシフト・既存予約・休憩・準備時間・定休日・受付期限を全部引き算した結果が「空き」。リソースが複数になると組み合わせが爆発する
2. **同時予約の競合制御** — 同じ枠を2人が同時に取ろうとしたとき、どちらか一方だけを通す仕組み。**これは画面では絶対に防げない**

そしてもう一つ、相談の前提として必ず問われるべき論点がある。

3. **月額数千円の既製サービスがあるのに、なぜ自作するのか** — ここに答えられないなら、作るべきではない（13章）

AKIMA はこの3点に正面から答えるデモとして作る。

| 目的 | 内容 |
|---|---|
| 実装力の証明 | 空き枠計算・仮押さえ・競合制御・スタッフ指名・定員制クラスまで、実務に耐える予約エンジンを見せる |
| **難所の可視化** | **「予約システムの本体は画面ではない」**を、実物で示す。これが最大の価値 |
| 判断材料の提供 | **既製サービスと自作の損益分岐**を計算式で示す |
| リード獲得 | デモ内から記事・問い合わせへの導線を常設し、GA4で計測する |

## プロダクト定義

| 項目 | 内容 |
|---|---|
| プロダクト名 | AKIMA（アキマ／空き間）※仮称 |
| 一言定義 | スタッフ指名と定員制クラスの両方に対応した、予約受付・管理システム |
| 想定業態 | 美容室・サロン・整体・エステ／クリニック／スクール・教室／レンタルスペース・会議室／飲食店 |
| 提供形態 | レスポンシブWebアプリ。**フロントエンド完結（サーバー側の永続化なし）** |
| 主戦場 | **予約側はスマホ**（夜間・移動中に予約される）。**管理側はPC**（店頭・バックヤード） |
| 想定利用者 | 記事の読者。登録なしで、予約する側と受ける側の両方を体験できる |

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

> **「空いていることが、商品。」**
>
> 予約システムのUIは、埋まっている枠を見せるためではなく、**空いている枠を見つけやすくするため**にある。AKIMA は空白を主役に置き、「いつなら行けるか」に最短で辿り着かせる。管理側では逆に、空白は埋めるべき機会として見える。

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

1. **記事の読者が、3タップで予約完了まで到達できる**
2. **枠が本当に埋まる** — 予約すると、その枠が他の日程選択画面から消える
3. **競合が体験できる** — 仮押さえ中に「他のお客様が予約しました」が起きる（意図的に再現）
4. **管理側も見られる** — タイムライン、予約変更、シフト設定、空き枠ルールまで確認できる
5. **本当に予約したと誤解されない** — デモであることが常時明示されている（**この領域固有の最重要リスク**）
6. **記事に戻れる／問い合わせできる** — デモが行き止まりにならない

---

# 2. 枠の壁 — この記事の核心

**この章は、実装要件であると同時に、記事本文の中核原稿である。** 曖昧にしない。

## 壁①：空き枠は「引き算」で決まる

「10時が空いているか」は、単純なフラグでは決まらない。次のすべてを引いた残りが空き枠になる。

```
空き枠 =  営業時間
        ∩ スタッフの勤務シフト
        − 既存の予約
        − 休憩時間
        − 施術前の準備時間（バッファ）
        − 施術後の片付け時間（バッファ）
        − 定休日・臨時休業
        − 予約受付期限（例：2時間前まで）
        − 予約可能期間（例：60日先まで）
        かつ メニューの所要時間が丸ごと収まること
        かつ 必要な設備・席が同時に空いていること
```

**この計算を1箇所に閉じ込められるかどうかが、予約システムの設計の質を決める。** ここが画面のあちこちに散らばると、「予約画面では空いているのに、確定しようとすると取れない」という最悪のバグが生まれる。

## 壁②：リソースが増えると組み合わせが爆発する

| 業態 | 必要なリソース | 難易度 |
|---|---|---|
| 会議室 | 部屋のみ | 低 |
| 整体・クリニック | スタッフ + ベッド | 中 |
| **美容室** | **スタイリスト + 席 + シャンプー台 + アシスタント** | **高** |
| レストラン | テーブル（人数に応じた組み合わせ） | 高 |

美容室の「カット + カラー」は、**カラー剤の放置時間中にスタイリストが別の客を担当できる**——このような業務ルールを入れ始めると、単純な時間ブロックでは表現できなくなる。

**だからこそ、要件定義の最初に「何と何が同時に空いていれば予約できるのか」を確定させる必要がある。** ここが曖昧なまま作り始めると、必ず作り直しになる。

## 壁③：ダブルブッキングは、画面では防げない

**これが最も重要な一点。**

```
10:00 の枠が1つだけ空いている

  お客様A                        お客様B
    │  10:00 を選択                 │  10:00 を選択
    │  （画面上は「空き」）          │  （画面上は「空き」）
    │  名前を入力…                  │  名前を入力…
    │  「予約する」                  │  「予約する」
    └──────────┬───────────────────┘
               ▼
        両方とも成功してしまう
```

フロントエンドで「空きをチェックしてから登録する」という順序で書くと、**チェックと登録の間に別の予約が入り込む**（Time-of-check to time-of-use）。これはロジックの書き方では防げない。

**防ぐ方法は、データベース側で「同じ枠は1つしか作れない」という制約を持つこと**（一意制約、排他ロック、トランザクション分離レベル）。つまり——

> **予約システムのダブルブッキング対策は、フロントエンドの問題ではなく、データベース設計の問題である。**

これが「予約システムはバックエンドが本体」と言われる理由。

## 壁④：仮押さえ（Hold）がないと、決済中に枠を奪われる

決済や入力に3分かかるとして、その間その枠が「空き」のままだと、確定直前で埋まる。だから実務では**枠を数分間ロックする「仮押さえ」**を挟む。

```
枠を選択 → 【仮押さえ 5分】 → 情報入力 → 確定
                  │
                  └─ 時間切れ → 自動解放（他の人が取れるようになる）
```

**この仮押さえの存在を知らずに見積もると、後から実装が増える。** 席の在庫管理と同じで、ECのカートと構造的に同じ問題を扱っている。

## 本デモでの扱い

本デモはバックエンドを持たないため、**壁③の本質的な解決（DB制約）は実装できない。** ここを誤魔化さない。

| ID | 要件 |
|---|---|
| SLT-01 | **空き枠計算を `lib/availability/` の1モジュールに完全に閉じ込めること。** 画面側で個別に空き判定を書かない |
| SLT-02 | **仮押さえ（Hold）を実装し、残り時間をカウントダウン表示すること**（FR-303） |
| SLT-03 | **競合を意図的に再現すること。** 仮押さえ中に一定確率で「他のお客様が先に予約されました」を発生させ、枠の再選択に戻す（FR-305） |
| SLT-04 | 競合が発生した画面に、**「実際のシステムではデータベース側の制約で防ぎます」という解説を出すこと**。デモの限界を教材に変える |
| SLT-05 | 「予約できました」の裏で何が起きているかを説明する導線（`/how-it-works`）を用意すること |

## 記事に書くべき一文

> **「予約システムで一番難しいのは、カレンダーの見た目ではありません。『同じ時間に2人が予約ボタンを押したとき、どちらか一方だけを通すこと』です。」**

---

# 3. 記事への組み込み設計

## 予約固有の最大リスク：本当に予約したと誤解される

**これは他の6本にない、この領域だけの事故リスク。** デモで予約完了画面が出たとき、読者が「本当に店を予約してしまった」と思い込むと、問い合わせが発生し、信頼を損なう。

| ID | 要件 |
|---|---|
| DEMO-01 | **全画面の常時表示位置に「これはデモです。実際の予約は発生しません」を明示すること** |
| DEMO-02 | **予約確認画面・予約完了画面には、通常より強い明示を置くこと**（背景色を変えた帯、または確定ボタン直上のチェック文言） |
| DEMO-03 | 店舗名・スタッフ名・電話番号・住所は、**すべて架空とし、実在しないことが分かる表記にすること**（例：「AKIMA サロン 表参道店（架空の店舗です）」） |
| DEMO-04 | 予約完了時に**メールを送らないこと**。「送信されるメールのプレビュー」として表示するに留める |
| DEMO-05 | 電話番号・メールアドレスの入力欄に、**ダミー値が最初から入っていること**（読者が本物を入れる動機をなくす） |
| DEMO-06 | 埋め込みモードでは**予約確定まで進ませないこと**（枠選択までで止め、続きは別タブへ誘導） |

## 配置方針（2段構え）

| 段 | 配置 | 中身 | 予約確定 |
|---|---|---|---|
| ① 記事内インライン | 記事の冒頭〜中盤、`<iframe>` | **空き枠カレンダー。** 日付とスタッフを切り替えると空き枠が変わる様子を見せる | **させない**（DEMO-06） |
| ② 全画面デモ | 「予約の流れを試す」カード → **別タブ** | アプリ全体（予約完了・管理画面・競合体験まで） | させる |

記事内は「**空き枠が本当に計算されている**」ことの証明、別タブは予約フロー全体の体験。

## 埋め込みモード（`?embed=1`）

| | 通常モード | 埋め込みモード `?embed=1` |
|---|---|---|
| ヘッダー・ナビ・ロール切替バー | 表示 | **非表示** |
| 表示内容 | アプリ全体 | 店舗1件の空き枠カレンダー + メニュー/スタッフ切替 |
| 予約の確定 | できる | **できない。** 枠タップで「続きは全画面デモで」と案内 |
| 個人情報の入力 | ある（ダミー値） | **入力欄を出さない** |
| 遷移 | 通常 | **アプリ内遷移を禁止。**「全画面で試す」は `target="_blank"` |

```html
<!-- 記事側の埋め込みコード -->
<iframe
  src="https://akima.souzoh-demo.com/shops/salon-01/booking?embed=1"
  width="100%" style="aspect-ratio:4/5; border:0"
  loading="lazy"
  title="AKIMA 予約カレンダーのデモ"></iframe>
```

## 記事本体のパフォーマンスを壊さない

| ID | 要件 |
|---|---|
| EMB-01 | 記事内 iframe は `loading="lazy"` とし、ビューポート接近まで読み込まないこと |
| EMB-02 | 埋め込みモードのJS初期バンドルは 70KB以下（gzip後）とすること |
| EMB-03 | 埋め込み iframe が記事の LCP 要素にならないこと |
| EMB-04 | 埋め込みモードで音を出さないこと。アニメーションを控えめにすること |
| EMB-05 | 空き枠の再計算は 100ms以下で完了すること。**日付を切り替えるたびに待たされないこと** |

## 「動画つき資料」との一体化

- 動画：空き枠を選ぶ → 仮押さえのカウントダウン → **競合が発生して枠を取られる** → 別の枠で予約完了 → 管理側のタイムラインに現れる → シフトを変更すると空き枠が変わる、までを3分で収録
- 資料：本要件定義から抜粋した「**予約要件の確認シート**（何と何が同時に空いていれば予約可能か）」と「**既製サービスと自作の損益分岐計算シート**」をPDF化
- デモ内の「資料をダウンロード」からも取得でき、そこを問い合わせ導線に接続する

**「予約要件の確認シート」は、そのまま商談の初回ヒアリング資料として使える。** 資料請求が有効なリードになる設計にする。

## 導線と計測

| ID | 要件 |
|---|---|
| EMB-10 | 全画面デモの上部に、**元の記事に戻るリンク**を常設すること |
| EMB-11 | 問い合わせ導線を、資料ダウンロード後・予約完了画面・管理画面に配置すること。**枠選択中・入力中には出さない** |
| EMB-12 | GA4 で以下を計測すること：`demo_open` / `slot_selected` / `hold_started` / `hold_expired` / `conflict_occurred`（競合体験）／`booking_completed` / `role_switch` / `how_it_works_viewed` / `doc_download` / `form_click` / `line_click` |
| EMB-13 | `form_click` と `line_click` は既存メディアのキーイベント名と揃えること |
| EMB-14 | **`conflict_occurred` と `how_it_works_viewed` は特に重要。** 「読者が競合の存在に触れたか」は、この記事の主張が届いたかの指標になる |
| EMB-15 | **入力された氏名・電話番号・メールアドレスを GA4 に送らないこと**（12章） |

## SEO上の扱い

| ID | 要件 |
|---|---|
| EMB-20 | デモは記事とは別サブドメインで配信し、**固有の title / description** を持つこと |
| EMB-21 | `?embed=1` のURLは `noindex` とすること |
| EMB-22 | デモの各ページから記事へリンクし、記事側からも `nofollow` を付けずリンクすること |
| EMB-23 | 記事側に `VideoObject`（解説動画）と `HowTo`（開発手順）の構造化データを設置すること |
| EMB-24 | **`LocalBusiness` `Reservation` 等の構造化データを使わないこと。** 架空の店舗を実在の事業者として検索エンジンに登録させない |

---

# 4. アーキテクチャ方針

## 基本方針

**バックエンドとデータベースを持たない。** ただし2章の壁③（ダブルブッキング）は、**本来サーバー側で解くべき問題であることを明示する。**

| 一般的な構成 | 本プロジェクト |
|---|---|
| PostgreSQL（一意制約・排他ロック） | シードデータ + ブラウザ内ストア。**競合はシミュレーションで再現** |
| 認証 | デモ用ロール切替（ワンクリック） |
| 決済（Stripe） | 事前決済のUIと完了画面まで再現。課金処理なし |
| メール・SMS・LINE通知 | **送信内容のプレビュー表示**で再現（DEMO-04） |
| 外部カレンダー連携 | ics のダウンロードのみ対応 |
| **空き枠の計算** | **これは本物。** ブラウザ内で実際に計算する |
| **仮押さえ（Hold）** | **これも本物。** タイマーで実際に期限切れる |

## 空き枠計算だけは本物にする

「空いています」と表示するだけのデモには意味がない。**シフトを変えたら空き枠が変わり、予約を入れたら枠が消える**——この因果が実際に動くことが、このデモの成否そのもの。

そして**空き枠計算はサーバーがなくても完全に実装できる**（純粋な計算だから）。ここに実装コストを集中させる。

## 空き枠エンジンの構造（**最重要の設計判断**）

```
lib/availability/
  ├── engine.ts          # ★ 空き枠計算の唯一の入口
  ├── rules.ts           # 営業時間・定休日・受付期限・予約可能期間
  ├── shift.ts           # スタッフの勤務シフトと休憩
  ├── buffer.ts          # 前準備・後片付けの時間
  ├── resource.ts        # 席・設備の同時空き判定
  ├── capacity.ts        # 定員制クラスの残席計算
  └── slot.ts            # 刻み（15分/30分）での枠生成
```

| ID | 規約 |
|---|---|
| AVL-01 | **空き枠を判定するコードを `lib/availability/` の外に書かないこと。** 画面・リポジトリ・コンポーネントのどこにも個別判定を置かない |
| AVL-02 | `lib/availability/` は**純粋関数のみ**。ストア・DOM・日時の「現在時刻」に直接依存させず、**現在時刻は引数で受け取ること**（テスト可能性のため） |
| AVL-03 | 入口は `getAvailability(input): AvailabilityResult` の1関数に統一する |
| AVL-04 | **「なぜこの枠が埋まっているのか」の理由を返すこと**（予約済み／シフト外／定休日／受付期限切れ／設備なし／バッファ）。管理画面でこれを表示する（FR-604） |
| AVL-05 | **予約確定の直前に必ず再検証すること。** 選択時のチェックだけで確定させない（2章の壁③への、フロント側でできる最大限の対処） |

## 予約タイプの2モード対応

| モード | 例 | 枠の考え方 |
|---|---|---|
| **指名制（1対1）** | 美容室、整体、クリニック、面談 | スタッフ×時間で1枠。所要時間はメニュー依存 |
| **定員制（1対N）** | ヨガ教室、セミナー、体験教室 | 開催日時が固定。残席数を管理 |

**両方に対応することが、このデモの実装力の証明になる。** 実案件でも「うちはクラス制なんですが」は頻出する。

## 永続化の範囲

| 対象 | 挙動 |
|---|---|
| シードデータ（店舗・スタッフ・メニュー・シフト・既存予約） | 初期投入。管理画面から編集可能 |
| **予約・仮押さえ・キャンセル** | localStorage に保存。**リロードしても残る** |
| **仮押さえの残り時間** | 保存された期限時刻から算出。**リロードしてもカウントダウンが続く** |
| 入力された顧客情報 | localStorage のみ。**どこにも送信しない** |
| リセット | 「デモをリセット」で localStorage をクリア |

**擬似ディレイ** は 150〜400ms。ただし**空き枠の再計算にはディレイを入れない**（日付切替のたびに待たされると、予約体験として致命的）。

---

# 5. スコープ定義

## 予約する側（お客様）

| ID | 機能 | 概要 | 優先度 |
|---|---|---|---|
| F-C01 | 店舗ページ | 店舗情報、メニュー、スタッフ、アクセス、予約導線 | Must |
| F-C02 | **メニュー選択** | 複数選択、合計所要時間・合計金額の自動計算 | Must |
| F-C03 | **スタッフ指名** | 指名あり／指名なし（誰でも可）。スタッフ別の空き状況 | Must |
| F-C04 | **空き枠カレンダー** | 日付横並び × 時間縦並び。空き／残りわずか／満席を色で表示 | Must |
| F-C05 | 日付ナビゲーション | 週送り、月表示への切替、**空きのある最短日へジャンプ** | Must |
| F-C06 | **仮押さえ** | 枠選択で5分間ロック。残り時間をカウントダウン表示 | Must |
| F-C07 | 予約者情報の入力 | 氏名・電話・メール・要望。**ダミー値が初期入力済み**（DEMO-05） | Must |
| F-C08 | 予約内容の確認 | メニュー・スタッフ・日時・所要時間・金額・キャンセル規定 | Must |
| F-C09 | 予約完了 | 予約番号、ics ダウンロード、**送信されるメールのプレビュー** | Must |
| F-C10 | **定員制クラスの予約** | 開催日時の一覧、残席数、複数名での申込 | Must |
| F-C11 | 予約の確認・変更・キャンセル | 予約番号 + 電話番号で照会。**キャンセル規定に応じた警告** | Must |
| F-C12 | 事前決済 | カード情報入力UI、決済完了画面（課金処理なし） | Should |
| F-C13 | キャンセル待ち | 満席の枠に登録。空きが出たら通知（デモ内で再現） | Should |
| F-C14 | 予約履歴 | 過去の来店履歴、同じ内容で再予約 | Should |
| F-C15 | リマインド通知 | 前日・当日の通知（**送信内容のプレビューで再現**） | Should |
| F-C16 | **仕組みの解説** | 「予約が確定するまでに何が起きているか」の解説ページ（SLT-05） | Must |

## 受ける側（店舗スタッフ・管理者）

| ID | 機能 | 概要 | 優先度 |
|---|---|---|---|
| F-A01 | **タイムライン** | 横軸=スタッフ／縦軸=時間。予約ブロックの高さ=所要時間 | Must |
| F-A02 | **予約のドラッグ移動** | 時間・スタッフをドラッグで変更。**移動先が予約不可なら弾く** | Must |
| F-A03 | 日／週表示の切替 | 日＝タイムライン、週＝スタッフ別の一覧 | Must |
| F-A04 | 予約の手動作成 | 電話予約の代理入力。**空き枠の制約を無視できる管理者権限** | Must |
| F-A05 | 予約詳細・編集 | 内容変更、ステータス変更（確定／来店済／無断キャンセル） | Must |
| F-A06 | 予約一覧・検索 | 日付・スタッフ・ステータス・顧客名での絞り込み | Must |
| F-A07 | **ブロック枠の設定** | 予約を受けない時間帯を、タイムライン上でドラッグして作成 | Must |
| F-A08 | **スタッフのシフト管理** | 勤務時間、休憩、週次パターン、個別の変更 | Must |
| F-A09 | **営業設定** | 営業時間、定休日、臨時休業、予約受付期限、予約可能期間、刻み幅 | Must |
| F-A10 | メニュー管理 | メニューCRUD、所要時間、前後バッファ、必要設備、対応スタッフ | Must |
| F-A11 | 設備・席の管理 | 設備CRUD、同時利用可能数 | Should |
| F-A12 | 定員制クラスの管理 | 開催日時の作成、定員設定、繰り返し開催 | Should |
| F-A13 | 顧客管理 | 顧客一覧、来店履歴、無断キャンセル回数、メモ | Should |
| F-A14 | 通知設定 | 予約確定・リマインド・キャンセルの文面編集 | Should |
| F-A15 | **予約分析** | 稼働率、時間帯別の埋まり方、**空き枠の機会損失**、キャンセル率 | Should |
| F-A16 | キャンセル規定の設定 | 何日前まで無料、以降の料率 | Should |

## 共通・基盤

| ID | 機能 | 概要 | 優先度 |
|---|---|---|---|
| F-S01 | ロール切替 | お客様／スタッフ／管理者 をワンクリック切替 | Must |
| F-S02 | 埋め込みモード | `?embed=1` で空き枠カレンダーのみ（3章） | Must |
| F-S03 | **競合シミュレーション** | 仮押さえ中に他者の予約を発生させる。解説付き（SLT-03, SLT-04） | Must |
| F-S04 | **デモである旨の常時明示** | 全画面。予約確認・完了画面では強調（DEMO-01, DEMO-02） | Must |
| F-S05 | 資料ダウンロード | 予約要件の確認シート・損益分岐計算シートのPDF | Must |
| F-S06 | 記事への導線 | 元記事へのリンク、問い合わせ導線 | Must |
| F-S07 | デモリセット | localStorage をクリア | Must |
| F-S08 | ガイドツアー | 初回訪問時に「何を試せるか」を3ステップで案内 | Should |

## 対象外（Won't have）

| 項目 | 理由 |
|---|---|
| データベース・バックエンドAPI | 4章の方針に基づく |
| **サーバー側での本物の排他制御** | **バックエンドがないため実装不可。** シミュレーションと解説で扱う（2章） |
| 本物の認証・実際の課金処理 | ロール切替と完了画面で代替 |
| 実際のメール・SMS・LINE送信 | プレビュー表示で再現 |
| Google カレンダー等との双方向同期 | ics のダウンロードのみ |
| 複数店舗のまたぎ予約・在庫の共有 | 店舗は複数持つが、予約は店舗単位で完結 |
| 順番待ち（整理券）システム | 時間指定予約に限定 |
| POS・レジ連携、売上管理 | 対象外 |
| 多言語UI | 日本語のみ |
| ネイティブアプリ | レスポンシブWebで対応。**予約はWebで完結する典型**（13章） |

> **スコープリスク：** 予約システムは「うちはこういうルールがあって」が無限に出てくる領域。**「2名同時施術」「掛け持ち」「シャンプーだけアシスタント」「回数券」「サブスク会員は優先枠」**など、業態固有のルールが必ず現れる。**これらは空き枠エンジンの根幹に影響する**ため、後付けではなく要件定義の段階で洗い出す必要がある。資料PDFの「予約要件の確認シート」は、この洗い出しのために作る。

---

# 6. ロールとデモ切替

## ロール定義

| ロールID | 名称 | できること | 特徴 |
|---|---|---|---|
| `customer` | お客様 | 予約する・確認する・変更する・キャンセルする | スマホ最適化。空き枠が主役 |
| `staff` | 店舗スタッフ | **自分の担当予約の閲覧・来店受付。** タイムラインは全体を見られるが編集は自分の分のみ | 店頭での運用を想定 |
| `admin` | 管理者 | 上記 + **予約の代理作成・移動・シフト・営業設定・メニュー・分析** | 設定メニューが出現する |

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

1. **お客様として予約する** → 管理者に切替 → **タイムラインにその予約ブロックが現れている**
2. **管理者がスタッフのシフトを短縮する** → お客様に切替 → **その時間帯が予約できなくなっている**
3. **管理者が予約をドラッグで別の時間に移動** → お客様に切替 → **予約確認画面に変更後の時間が出ている**
4. **管理者がブロック枠を作る** → お客様に切替 → **その枠が空き枠から消えている**
5. **お客様が仮押さえ中に競合が発生** → 枠選択に戻される → **解説パネルが「実際はDB制約で防ぎます」を説明する**
6. **管理者がメニューの所要時間を60分→90分に変更** → お客様に切替 → **選べる枠の数が減っている**（所要時間が収まらない枠が消える）

**6番は特に重要。** 空き枠が「引き算」で決まっていることが、体験で分かる唯一の瞬間になる。

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

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

- 現在のロール表示と3ロールの切替
- **「これはデモです。実際の予約は発生しません」の明示**（DEMO-01）
- **デモ内の現在日時**（シードが相対日付で生成されるため、基準を示す）
- 「デモをリセット」ボタン（確認ダイアログ付き）
- 元記事へ戻るリンク

**デザイン上の扱い：** アプリ本体が明るく柔らかいトーンなので、切替バーは**濃色の帯**にして明確に区別する。

---

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

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

## お客様側画面

| 画面ID | 画面名 | パス | 主要要素 |
|---|---|---|---|
| SC-001 | 店舗トップ | `/shops/[shopId]` | 店舗情報、メニュー、スタッフ、写真、予約ボタン |
| SC-010 | **メニュー選択** | `/shops/[shopId]/booking` | カテゴリ別メニュー、複数選択、**合計時間と金額の自動計算** |
| SC-011 | **スタッフ選択** | `/shops/[shopId]/booking/staff` | 指名なし／指名あり、スタッフ別の直近空き状況 |
| SC-012 | **空き枠カレンダー** | `/shops/[shopId]/booking/slots` | 日付横 × 時間縦、週送り、**空きのある最短日へジャンプ** |
| SC-013 | 埋め込みカレンダー | `/shops/[shopId]/booking?embed=1` | カレンダーのみ。確定させない |
| SC-014 | **仮押さえ中** | `/shops/[shopId]/booking/hold` | **残り時間のカウントダウン**、選択内容の確認 |
| SC-015 | 予約者情報の入力 | `/shops/[shopId]/booking/info` | 氏名・電話・メール・要望。**ダミー値が初期入力済み** |
| SC-016 | 事前決済 | `/shops/[shopId]/booking/payment` | カード入力UI、金額、キャンセル規定 |
| SC-017 | **予約内容の確認** | `/shops/[shopId]/booking/confirm` | 全内容 + キャンセル規定 + **デモ明示の強調帯** |
| SC-018 | **予約完了** | `/booking/complete/[code]` | 予約番号、ics ダウンロード、**メールのプレビュー**、デモ明示 |
| SC-019 | **競合発生** | モーダル | 「他のお客様が先に予約されました」+ **解説パネル**（SLT-04） |
| SC-020 | 定員制クラス一覧 | `/shops/[shopId]/classes` | 開催日時、残席、定員、講師 |
| SC-021 | クラス予約 | `/shops/[shopId]/classes/[id]` | 詳細、人数選択、残席チェック |
| SC-030 | 予約照会 | `/reservations/lookup` | 予約番号 + 電話番号で照会 |
| SC-031 | 予約詳細（お客様） | `/reservations/[code]` | 内容、変更、キャンセル、地図、ics |
| SC-032 | 予約の変更 | `/reservations/[code]/change` | 日時・メニューの変更。**再度の空き枠選択と仮押さえ** |
| SC-033 | キャンセル | `/reservations/[code]/cancel` | **キャンセル規定に応じた料率の警告**、理由選択 |
| SC-034 | キャンセル待ち登録 | モーダル | 満席枠への登録、通知方法 |
| SC-040 | **仕組みの解説** | `/how-it-works` | 空き枠計算・仮押さえ・競合制御の解説（SLT-05） |

## 店舗側画面

| 画面ID | 画面名 | パス | 主要要素 |
|---|---|---|---|
| SC-100 | 本日のダッシュボード | `/admin` | 本日の予約数、来店待ち、空き枠、キャンセル、稼働率 |
| SC-110 | **タイムライン（日）** | `/admin/timeline` | 横=スタッフ／縦=時間、**ブロックの高さ=所要時間**、ドラッグ移動 |
| SC-111 | 週表示 | `/admin/timeline?view=week` | スタッフ別の週間一覧 |
| SC-112 | 予約詳細・編集 | `/admin/reservations/[id]` | 内容、ステータス、メモ、変更履歴 |
| SC-113 | 予約の手動作成 | `/admin/reservations/new` | 代理入力。**空き枠制約を無視するオプション（管理者のみ）** |
| SC-114 | 予約一覧 | `/admin/reservations` | 絞り込み、CSV出力 |
| SC-115 | **ブロック枠の作成** | タイムライン上 | ドラッグで時間帯を確保。理由の入力 |
| SC-120 | **シフト管理** | `/admin/shifts` | スタッフ×日付のグリッド、週次パターン、休憩設定 |
| SC-121 | スタッフ管理 | `/admin/staff` | CRUD、対応メニュー、色設定 |
| SC-130 | **営業設定** | `/admin/settings/business` | 営業時間、定休日、臨時休業、受付期限、予約可能期間、刻み幅 |
| SC-131 | メニュー管理 | `/admin/menus` | CRUD、所要時間、**前後バッファ**、必要設備、対応スタッフ |
| SC-132 | 設備・席の管理 | `/admin/resources` | CRUD、同時利用可能数 |
| SC-133 | 定員制クラスの管理 | `/admin/classes` | 開催日時の作成、定員、繰り返し |
| SC-134 | キャンセル規定 | `/admin/settings/cancel-policy` | 何日前まで無料、以降の料率 |
| SC-135 | 通知文面の設定 | `/admin/settings/notifications` | 確定・リマインド・キャンセルの文面と差し込み変数 |
| SC-140 | 顧客管理 | `/admin/customers` | 一覧、来店履歴、**無断キャンセル回数**、メモ |
| SC-150 | **予約分析** | `/admin/analytics` | 稼働率、時間帯別の埋まり方、**機会損失**、キャンセル率、リピート率 |

## 主要フロー

### フローA：記事の読者が予約を体験する（最重要）

```
SEO記事を読んでいる
   ↓
記事内の埋め込み（空き枠カレンダー）
   ↓  ★ スタッフを切り替えると空き枠が変わる
   ★ メニューを「カット」→「カット＋カラー」に変えると、選べる枠が減る
   ↓  （所要時間が伸びて収まらない枠が消えるため）
「全画面で予約の流れを試す」→ 別タブ
   ↓
SC-010 メニュー選択 ── 複数選択で合計時間・金額が変わる
   ↓
SC-011 スタッフ選択 ── 指名なし／指名あり
   ↓
SC-012 空き枠カレンダー ──「空きのある最短日へ」でジャンプ
   ↓
枠をタップ
   ↓
SC-014 **仮押さえ開始（5分カウントダウン）**
   ↓
SC-015 予約者情報 ── ★ ダミー値が既に入っている
   ↓
SC-017 確認 ── ★ 「これはデモです」の強調帯
   ↓
SC-018 予約完了 ── 予約番号、ics、**送信されるメールのプレビュー**
   ↓
ロール切替「管理者」→ SC-110 タイムライン
   ↓  ★ たった今の予約が、ブロックとして現れている
資料ダウンロード or 元記事に戻る
```

### フローB：競合を体験する（**記事の核心を体験に落とす**）

```
SC-012 空き枠カレンダー ── 枠をタップ
   ↓
SC-014 仮押さえ中（残り 4:52…）
   ↓
SC-015 予約者情報を入力している最中
   ↓
★ 一定確率で発生（または「競合を再現する」ボタンで任意発生）
   ↓
SC-019 競合モーダル
   ┌──────────────────────────────────────┐
   │  申し訳ありません                       │
   │  この時間は、他のお客様が先に            │
   │  予約されました                          │
   │                                        │
   │  ［別の時間を選ぶ］                      │
   │                                        │
   │  ─── なぜこれが起きるのか ───            │
   │  2人が同時に同じ枠を選ぶと、画面上は      │
   │  どちらにも「空き」と表示されます。       │
   │  実際のシステムでは、データベース側の      │
   │  一意制約で片方だけを通します。           │
   │  画面のチェックだけでは防げません。        │
   │                        ［詳しく見る］     │
   └──────────────────────────────────────┘
   ↓
SC-012 に戻る ── ★ その枠が実際に埋まっている
   ↓
別の枠を選んで予約完了
   ↓
SC-040 仕組みの解説（「詳しく見る」から）
   空き枠の引き算 / 仮押さえ / 競合制御 を図で説明
```

### フローC：店舗側の運用（設定が空き枠を動かす）

```
SC-110 タイムライン ── 本日の予約状況を確認
   ↓
電話予約が入る → SC-113 手動作成
   ★ 管理者は「空き枠の制約を無視して作成」できる（現実の運用に合わせる）
   ↓
予約を別の時間に移したい → タイムライン上でブロックをドラッグ
   ★ 移動先が予約不可なら弾かれ、理由が表示される
   ↓
SC-115 ブロック枠 ── 15時〜16時をドラッグで確保（理由：ミーティング）
   ↓
【ロール切替：お客様】
SC-012 ── ★ 15時台が予約できなくなっている
   ↓
【ロール切替：管理者】
SC-131 メニュー管理 ── 「カラー」の所要時間を 60分 → 90分に変更
   ↓
【ロール切替：お客様】
SC-012 ── ★ 選べる枠が明らかに減っている
   （90分が丸ごと収まる枠しか出ないため）
   ↓
【ロール切替：管理者】
SC-150 予約分析 ── ★ 「機会損失」に、埋まらなかった空き枠が計上されている
```

---

# 8. 機能要件

## 8.1 空き枠エンジン（**このデモの心臓部**）

| ID | 要件 | 優先 |
|---|---|---|
| FR-101 | **空き枠の判定を `lib/availability/` に完全に閉じ込めること。** 画面・コンポーネント側で個別に空き判定を書かないこと（AVL-01） | P1 |
| FR-102 | `lib/availability/` を**純粋関数として実装し、現在時刻を引数で受け取ること**（AVL-02） | P1 |
| FR-103 | 空き枠は次のすべてを考慮して算出すること：営業時間／定休日・臨時休業／スタッフの勤務シフト／休憩／既存予約／前後バッファ／必要設備の同時空き／メニュー所要時間／予約受付期限／予約可能期間 | P1 |
| FR-104 | 枠の刻み幅（15分／30分／60分）を設定でき、算出に反映されること | P1 |
| FR-105 | メニューの所要時間が**丸ごと収まる枠のみ**を空きとすること。途中で営業終了・シフト終了する枠を出さないこと | P1 |
| FR-106 | 前バッファ・後バッファを考慮すること。**バッファは他の予約とは重ねられるが、施術時間とは重ねられない**というルールを設定できること | P2 |
| FR-107 | 複数メニューを選択した場合、**合計所要時間で枠を判定すること** | P1 |
| FR-108 | 「指名なし」の場合、**対応可能なスタッフの誰か1人が空いていれば空き**とすること。確定時に自動で割り当てること | P1 |
| FR-109 | 必要設備がある場合、**その設備が同時に空いていることを条件に含めること** | P2 |
| FR-110 | **「なぜ埋まっているか」の理由を返すこと**（予約済み／シフト外／定休日／受付期限／設備なし／バッファ）(AVL-04) | P1 |
| FR-111 | **空き枠の再計算が 100ms以下で完了すること**（60日分・スタッフ5名・刻み15分の条件で） | P1 |
| FR-112 | **予約確定の直前に必ず空き枠を再検証すること**（AVL-05） | P1 |
| FR-113 | 定員制クラスの残席を、定員 − 確定予約人数 − 仮押さえ人数 で算出すること | P1 |

## 8.2 予約フロー（お客様側）

| ID | 要件 | 優先 |
|---|---|---|
| FR-201 | メニューを複数選択でき、**合計所要時間と合計金額をリアルタイムに表示すること** | P1 |
| FR-202 | 同時に選べないメニューの組み合わせを設定でき、選択時に警告すること | P3 |
| FR-203 | スタッフを「指名なし／指名あり」から選べること。指名ありの場合、**そのスタッフが対応できるメニューのみ選択可**とすること | P1 |
| FR-204 | スタッフ一覧に、**直近で空いている最短日時を表示すること**（「最短：明日 14:00〜」） | P2 |
| FR-205 | 空き枠カレンダーは**日付横並び × 時間縦並び**とし、7日分を1画面に表示すること（モバイルは4日） | P1 |
| FR-206 | 週送り・週戻しができ、**予約可能期間の範囲外には進めないこと** | P1 |
| FR-207 | **「空きのある最短日へジャンプ」を提供すること。** 満席の週を延々とめくらせないこと | P1 |
| FR-208 | 枠の状態を「空き／残りわずか／満席／受付終了」で色分けし、**色以外（記号・テキスト）でも区別すること** | P1 |
| FR-209 | 月表示への切替を提供し、**日ごとの空き状況（○△×）を一覧できること** | P2 |
| FR-210 | 予約者情報の入力欄に、**ダミー値が初期入力されていること**（DEMO-05） | P1 |
| FR-211 | 電話番号・メールアドレスの形式検証を行うこと。**ただしデモでは実在性を問わないこと** | P1 |
| FR-212 | 予約確認画面に、メニュー・スタッフ・日時・所要時間・金額・**キャンセル規定**を表示すること | P1 |
| FR-213 | 予約完了時、予約番号を発行し、**ics ファイルをダウンロードできること** | P1 |
| FR-214 | 予約完了時、**送信されるメールの内容をプレビュー表示すること。実際には送信しないこと**（DEMO-04） | P1 |
| FR-215 | 入力途中でページを離脱しようとした場合、確認ダイアログを表示すること | P2 |

## 8.3 仮押さえと競合（**記事の核心を実装する部分**）

| ID | 要件 | 優先 |
|---|---|---|
| FR-301 | 枠を選択した時点で**仮押さえを作成し、既定5分の有効期限を設定すること** | P1 |
| FR-302 | 仮押さえ中の枠を、**他の枠選択画面から「仮押さえ中」として除外すること** | P1 |
| FR-303 | **残り時間をカウントダウン表示すること。** 残り1分で警告色に変えること | P1 |
| FR-304 | **リロードしてもカウントダウンが継続すること**（期限時刻を保存し、そこから算出する） | P1 |
| FR-305 | 仮押さえ中に、**一定確率（既定15%）で競合を発生させること。** 加えて「競合を再現する」ボタンで任意に発生させられること（SLT-03） | P1 |
| FR-306 | 競合発生時、**モーダルで「他のお客様が先に予約されました」を表示し、なぜ起きるかの解説を併記すること**（SLT-04） | P1 |
| FR-307 | 競合発生後、**その枠が実際に埋まった状態でカレンダーに戻ること** | P1 |
| FR-308 | 仮押さえの期限切れ時、**枠を自動解放し、その旨を通知すること。** 入力内容は保持し、別の枠を選び直せば再利用できること | P1 |
| FR-309 | 予約確定の直前に空き枠を再検証し、埋まっていた場合は競合と同じ扱いにすること（FR-112） | P1 |
| FR-310 | SC-040「仕組みの解説」で、**空き枠の引き算・仮押さえ・競合制御を図で説明すること**（SLT-05） | P1 |

## 8.4 予約の確認・変更・キャンセル

| ID | 要件 | 優先 |
|---|---|---|
| FR-401 | 予約番号 + 電話番号（下4桁）で予約を照会できること | P1 |
| FR-402 | 予約詳細に、内容・店舗情報・地図リンク・ics再取得・変更・キャンセルの導線を置くこと | P1 |
| FR-403 | 予約の日時変更ができること。**変更時も空き枠選択と仮押さえを経ること** | P1 |
| FR-404 | 変更の受付期限（既定：前日まで）を設定でき、期限を過ぎたら電話連絡を案内すること | P2 |
| FR-405 | キャンセル時、**キャンセル規定に応じた料率を明示すること**（「本日のキャンセルは50%のキャンセル料が発生します」） | P1 |
| FR-406 | キャンセル理由を選択できること（都合が悪くなった／体調不良／間違えて予約した／その他） | P2 |
| FR-407 | キャンセルされた枠が、**即座に他のお客様の空き枠に戻ること** | P1 |
| FR-408 | 満席の枠にキャンセル待ちを登録でき、空きが出たら通知されること（デモ内で再現） | P2 |
| FR-409 | 過去の予約履歴を表示し、**同じ内容で再予約できること** | P2 |

## 8.5 店舗側：タイムラインと予約管理

| ID | 要件 | 優先 |
|---|---|---|
| FR-501 | タイムラインを**横軸=スタッフ／縦軸=時間**で表示し、**予約ブロックの高さを所要時間に比例させること** | P1 |
| FR-502 | 営業時間外・シフト外・休憩・ブロック枠を、背景の塗りで区別すること | P1 |
| FR-503 | **予約ブロックをドラッグして、時間とスタッフを変更できること** | P1 |
| FR-504 | **ドラッグ先が予約不可な場合は弾き、理由を表示すること**（シフト外／既存予約と重複／設備なし） | P1 |
| FR-505 | ドラッグ操作を**キーボードでも行えること**（ブロック選択 → 移動先選択） | P1 |
| FR-506 | ブロックの下端をドラッグして、所要時間を変更できること | P2 |
| FR-507 | **タイムライン上でドラッグしてブロック枠（予約を受けない時間）を作成できること**。理由を入力できること | P1 |
| FR-508 | 現在時刻を示す横線をタイムライン上に表示し、自動でスクロール位置を合わせること | P2 |
| FR-509 | 予約の手動作成ができること。**管理者は「空き枠の制約を無視して作成」を選べること**（電話予約・無理な差し込みへの対応） | P1 |
| FR-510 | 制約を無視して作成した予約に、**警告マークを付けて識別できるようにすること** | P1 |
| FR-511 | 予約のステータスを「確定／来店済／無断キャンセル／キャンセル」に変更できること | P1 |
| FR-512 | 予約の変更履歴（誰がいつ何を変えたか）を保持すること | P2 |
| FR-513 | 日表示と週表示を切り替えられること | P1 |
| FR-514 | 予約一覧を、日付・スタッフ・ステータス・顧客名で絞り込めること。CSV出力できること | P2 |

## 8.6 店舗側：設定（**空き枠に直結する部分**）

| ID | 要件 | 優先 |
|---|---|---|
| FR-601 | 営業時間を曜日別に設定でき、**変更が空き枠に即座に反映されること** | P1 |
| FR-602 | 定休日（曜日指定）と臨時休業（日付指定）を設定できること | P1 |
| FR-603 | 予約受付期限（例：2時間前まで）と予約可能期間（例：60日先まで）を設定できること | P1 |
| FR-604 | **空き枠のプレビューを設定画面上で確認でき、埋まっている理由を表示すること**（AVL-04） | P1 |
| FR-605 | スタッフのシフトを、**スタッフ×日付のグリッドで編集できること**。週次パターンからの一括生成に対応すること | P1 |
| FR-606 | 休憩時間をシフト内に設定できること | P1 |
| FR-607 | メニューに、所要時間・前バッファ・後バッファ・金額・必要設備・対応スタッフを設定できること | P1 |
| FR-608 | **メニューの所要時間を変更すると、選べる空き枠が変わること**（6章の体験6） | P1 |
| FR-609 | 設備・席を登録し、同時利用可能数を設定できること | P2 |
| FR-610 | 定員制クラスの開催日時を作成でき、繰り返し（毎週◯曜）に対応すること | P2 |
| FR-611 | キャンセル規定（何日前まで無料／以降の料率）を設定でき、**お客様側の画面に反映されること** | P2 |
| FR-612 | 通知文面（確定・リマインド・キャンセル）を編集でき、差し込み変数（`{{お客様名}}` `{{日時}}` `{{メニュー}}` `{{スタッフ}}`）を使えること | P2 |

## 8.7 通知・決済

| ID | 要件 | 優先 |
|---|---|---|
| FR-701 | 予約確定・リマインド（前日／当日）・変更・キャンセル の各通知について、**送信される内容をプレビュー表示すること。実際には送信しないこと** | P1 |
| FR-702 | 通知チャネル（メール／SMS／LINE）を選べるUIを提供し、**チャネルごとの文字数制限と概算コストを表示すること**（13章の費用理解につながる） | P2 |
| FR-703 | 事前決済のUI（カード情報入力・金額・確認）を実装し、**課金処理を行わないこと。デモである旨を明示すること** | P2 |
| FR-704 | 決済手数料の目安を、金額の内訳として表示すること（**費用理解の教材として**） | P3 |

## 8.8 分析

| ID | 要件 | 優先 |
|---|---|---|
| FR-801 | 稼働率（営業時間に対する予約時間の割合）をスタッフ別・期間別に表示すること | P2 |
| FR-802 | **時間帯別の埋まり方**をヒートマップで表示すること（何曜日の何時が埋まりやすいか） | P2 |
| FR-803 | **機会損失**を算出すること：空いていたのに埋まらなかった枠の時間と、その推定金額 | P2 |
| FR-804 | キャンセル率・無断キャンセル率を表示すること | P2 |
| FR-805 | 新規／リピートの比率、リピート率を表示すること | P3 |
| FR-806 | **デモ中に行った予約・キャンセルが、これらの分析に反映されること** | P1 |

## 8.9 デモ基盤

| ID | 要件 | 優先 |
|---|---|---|
| FR-901 | 3ロールをワンクリックで切り替えられること | P1 |
| FR-902 | **「これはデモです。実際の予約は発生しません」を全画面で常時明示すること**（DEMO-01） | P1 |
| FR-903 | **予約確認・予約完了画面では、より強い明示（帯・確認文言）を置くこと**（DEMO-02） | P1 |
| FR-904 | 店舗名・スタッフ名・電話番号・住所を**すべて架空とし、架空である旨を表記すること**（DEMO-03） | P1 |
| FR-905 | 「デモをリセット」で localStorage をクリアすること | P1 |
| FR-906 | 予約・仮押さえ・設定変更がリロード後も保持されること | P1 |
| FR-907 | **デモ内の現在日時を切替バーに表示すること**（シードが相対日付のため、基準を示す） | P2 |
| FR-908 | 元記事へ戻るリンクと資料ダウンロードを常設すること | P1 |
| FR-909 | ロール権限外の画面にアクセスした場合、案内画面から切り替えられること。素の404を出さないこと | P1 |
| FR-910 | 権限で不可の操作はボタンを非活性にし、理由をツールチップで示すこと | P1 |
| FR-911 | データスコープは `lib/repo/_scope.ts` に集約すること | P1 |
| FR-912 | 初回訪問時に3ステップのガイドツアーを表示し、「今後表示しない」を選べること | P2 |

---

# 9. データ設計

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

```ts
// ---- 店舗・スタッフ ----
type Shop = {
  id: string
  name: string                  // ★ 架空。「（架空の店舗です）」を含める（DEMO-03）
  description: string
  address: string               // 架空
  phone: string                 // 架空（000-0000-0000 等）
  imageUrls: string[]
  businessHours: BusinessHour[]
  closedWeekdays: number[]      // 定休日（0=日）
  specialClosures: string[]     // 臨時休業（YYYY-MM-DD）
  slotStepMin: 15 | 30 | 60     // 刻み幅
  bookingLeadTimeMin: number    // 予約受付期限（例：120 = 2時間前まで）
  bookingWindowDays: number     // 予約可能期間（例：60日先まで）
  cancelPolicy: CancelPolicy
}
type BusinessHour = { weekday: number; openMin: number; closeMin: number }  // 分単位（540 = 9:00）
type CancelPolicy = { freeUntilDaysBefore: number; tiers: { daysBefore: number; rate: number }[] }

type Staff = {
  id: string
  shopId: string
  name: string                  // ★ 架空
  role: 'staff' | 'admin'
  avatarUrl: string
  color: string                 // ★ タイムライン上の識別色
  menuIds: string[]             // 対応できるメニュー
  isActive: boolean
  sortOrder: number
}

type Shift = {
  id: string
  staffId: string
  date: string                  // YYYY-MM-DD
  startMin: number
  endMin: number
  breaks: { startMin: number; endMin: number }[]
}

// ---- メニュー・設備 ----
type Menu = {
  id: string
  shopId: string
  categoryId: string
  name: string
  description: string
  durationMin: number           // ★ 所要時間。変更すると空き枠が変わる（FR-608）
  bufferBeforeMin: number       // 前準備
  bufferAfterMin: number        // 後片付け
  price: number
  requiredResourceIds: string[] // 必要な設備・席
  isActive: boolean
  sortOrder: number
}
type MenuCategory = { id: string; name: string; sortOrder: number }

type Resource = {               // 席・ベッド・設備
  id: string
  shopId: string
  name: string
  capacity: number              // 同時利用可能数
}

// ---- 予約 ----
type Reservation = {
  id: string
  code: string                  // 予約番号（お客様に見せる）
  shopId: string
  type: 'appointment' | 'class'  // ★ 指名制 / 定員制
  // --- 指名制 ---
  staffId?: string
  menuIds: string[]
  resourceIds: string[]
  // --- 定員制 ---
  classSessionId?: string
  partySize: number             // 人数
  // --- 時間 ---
  startAt: string               // ISO8601
  endAt: string
  durationMin: number
  // --- 顧客 ---
  customer: CustomerInfo
  // --- 状態 ---
  status: 'confirmed' | 'visited' | 'cancelled' | 'no_show'
  cancelledAt?: string
  cancelReason?: string
  cancelFeeRate?: number
  // --- 管理 ---
  createdVia: 'web' | 'staff_manual'
  isForced: boolean             // ★ 空き枠制約を無視して作成された（FR-510）
  note: string
  totalPrice: number
  isPaid: boolean
  history: ReservationChange[]
  createdAt: string
}
type CustomerInfo = { name: string; nameKana: string; phone: string; email: string; request: string }
type ReservationChange = { at: string; by: string; field: string; before: string; after: string }

// ---- 仮押さえ（★ 記事の核心） ----
type Hold = {
  id: string
  shopId: string
  staffId?: string
  classSessionId?: string
  startAt: string
  endAt: string
  partySize: number
  expiresAt: string             // ★ ここから残り時間を算出する（FR-304）
  createdAt: string
}

// ---- ブロック枠 ----
type BlockedSlot = {
  id: string
  shopId: string
  staffId?: string              // 未指定なら店舗全体
  startAt: string
  endAt: string
  reason: string
}

// ---- 定員制クラス ----
type ClassSession = {
  id: string
  shopId: string
  name: string
  instructorStaffId: string
  startAt: string
  durationMin: number
  capacity: number
  price: number
  recurrence?: { type: 'weekly'; weekdays: number[]; untilDate: string }
}

// ---- キャンセル待ち ----
type Waitlist = {
  id: string
  shopId: string
  staffId?: string
  desiredDate: string
  desiredTimeRange: { fromMin: number; toMin: number }
  menuIds: string[]
  customer: CustomerInfo
  status: 'waiting' | 'notified' | 'converted' | 'expired'
  createdAt: string
}

// ---- 顧客 ----
type Customer = {
  id: string
  shopId: string
  name: string; nameKana: string; phone: string; email: string
  visitCount: number
  noShowCount: number           // ★ 無断キャンセル回数
  lastVisitAt?: string
  note: string
  createdAt: string
}

// ---- 空き枠計算の入出力（★ lib/availability/ の契約） ----
type AvailabilityInput = {
  shop: Shop
  staffList: Staff[]
  shifts: Shift[]
  reservations: Reservation[]
  holds: Hold[]
  blocked: BlockedSlot[]
  resources: Resource[]
  menus: Menu[]
  // 検索条件
  selectedMenuIds: string[]
  preferredStaffId?: string     // 未指定なら「指名なし」
  fromDate: string
  toDate: string
  now: string                   // ★ 現在時刻は必ず引数で受け取る（AVL-02）
}

type AvailabilityResult = {
  days: DayAvailability[]
  earliestAvailableAt?: string  // ★「最短の空き」（FR-207）
}
type DayAvailability = {
  date: string
  isClosed: boolean
  slots: Slot[]
  availableCount: number
}
type Slot = {
  startAt: string
  endAt: string
  state: 'available' | 'few' | 'full' | 'held' | 'closed' | 'past_deadline'
  availableStaffIds: string[]   // 指名なし時に割り当て候補となるスタッフ
  remainingCapacity?: number    // 定員制の場合
  // ★ なぜ埋まっているかの理由（AVL-04, FR-110）
  blockedReason?: 'reserved' | 'off_shift' | 'break' | 'closed_day' | 'blocked' | 'no_resource' | 'buffer' | 'lead_time' | 'out_of_window'
}
```

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

| ファイル | 内容 | 件数 |
|---|---|---|
| `shops.ts` | 店舗（**架空。指名制のサロン1店 + 定員制のスタジオ1店**） | 2件 |
| `staff.ts` | スタッフ（識別色付き。対応メニューを分散させる） | 6名 |
| `menus.ts` | メニュー（所要時間 30〜120分、バッファ設定、必要設備あり／なし） | 18件 |
| `resources.ts` | 設備・席（シャンプー台2台、施術ベッド3台 等） | 5件 |
| `shifts.ts` | シフト（**過去14日 + 今後60日**。スタッフごとに勤務日を変える） | — |
| `reservations.ts` | 予約（**直近ほど密、先ほど疎**。過去は来店済／無断キャンセルを含む） | 約300件 |
| `blocked.ts` | ブロック枠（ミーティング、清掃、研修） | 12件 |
| `classSessions.ts` | 定員制クラス（週次繰り返し、残席にばらつき） | 40件 |
| `customers.ts` | 顧客（来店回数・無断キャンセル回数を分散） | 120名 |

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

- **店舗名・スタッフ名・住所・電話番号はすべて架空。** 実在の店舗・人物を想起させない。電話番号は明らかにダミーと分かる形式にする（DEMO-03）
- **予約の密度に濃淡をつける。** 土日夕方は埋まり、平日午前は空く。**均等に埋まっていると、空き枠カレンダーが意味を持たない**
- **「今日から3日以内は7〜8割埋まっている」状態にする。** 空きスカスカだと予約体験の緊張感がなく、満席だと予約できずデモにならない
- **数枠だけ「残りわずか」を作る**（指名なしで1名だけ対応可能な状態）
- **スタッフごとに埋まり方を変える。** 人気スタッフと空いているスタッフがいること
- **メニューの所要時間に幅を持たせる**（30分／60分／90分／120分）。**所要時間による枠の減り方**が体験できるように
- **無断キャンセルのある顧客を数名作る**（顧客管理と分析が意味を持つ）
- 日付は**現在日時からの相対で生成する。固定日付を埋め込まない**
- **キャンセル待ちが登録された満席枠を1つ用意する**（フローの実演用）

## ストアとリポジトリ

```
lib/
├── types/ seed/
├── availability/               # ★ 空き枠計算の唯一の場所。純粋関数のみ
│   ├── engine.ts               # getAvailability() 入口
│   ├── rules.ts  shift.ts  buffer.ts  resource.ts  capacity.ts  slot.ts
│   └── reason.ts               # 埋まっている理由の判定
├── time/                       # 日時ユーティリティ。純粋関数
│   ├── minutes.ts              # 分↔時刻文字列の相互変換
│   ├── range.ts                # 時間帯の重なり・結合・差分
│   └── calendar.ts             # 週の生成、日付の走査
├── hold/
│   ├── manager.ts              # 仮押さえの作成・期限切れ・解放
│   └── conflict-simulator.ts   # ★ 競合の再現（FR-305）
├── calc/                       # 稼働率・機会損失・キャンセル率
├── store/  { session, data, settings, hold, ui }
└── repo/                       # ★ コンポーネントが触るのはここだけ
    ├── _delay.ts _scope.ts
    ├── availability.ts reservations.ts holds.ts
    ├── shops.ts staff.ts shifts.ts menus.ts resources.ts
    ├── classes.ts customers.ts analytics.ts
```

**規約（厳守）**

- リポジトリの全メソッドを `async` で定義。戻り値は `{ ok: true; data: T } | { ok: false; error: string }` に統一
- **コンポーネントから Zustand ストアを直接参照しない**
- **`lib/availability/` と `lib/time/` は純粋関数のみ。** ストア・DOM・`new Date()` の直接呼び出しを禁止（**現在時刻は必ず引数で渡す**）
- **空き判定を `lib/availability/` の外に書かない**（AVL-01）
- 派生値（稼働率・機会損失・残席）はストアに保存せず `lib/calc/` で都度算出する
- **空き枠の再計算に擬似ディレイを入れない**（FR-111）

```ts
// lib/repo/reservations.ts — 確定直前の再検証（FR-112, AVL-05）
export async function confirmReservation(input: ConfirmInput): Promise<Result<Reservation>> {
  // 1. 仮押さえが有効か確認
  const hold = useHoldStore.getState().find(input.holdId)
  if (!hold || new Date(hold.expiresAt) <= new Date(input.now))
    return { ok: false, error: 'HOLD_EXPIRED' }

  // 2. ★ 空き枠を再計算して、まだ取れることを検証する
  const avail = getAvailability({ ...buildInput(), now: input.now })
  if (!isStillAvailable(avail, input.startAt, input.staffId))
    return { ok: false, error: 'SLOT_TAKEN' }   // → 競合モーダルへ（FR-309）

  // 3. 確定・仮押さえ解放・通知プレビュー生成
}
```

---

# 10. デザイン要件

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

**「時間を、面積で見せる」**

予約とは、時間という在庫の売買である。AKIMA では**時間の長さがそのまま面積になる**——90分の施術は60分の1.5倍の高さを持ち、空き時間は空白として見える。お客様側では「空白＝行ける時間」、店舗側では「空白＝埋めるべき機会」。同じ空白が、立場によって意味を変える。

- **空白が主役。** 埋まっている枠を目立たせるのではなく、空いている枠を見つけやすくする
- **柔らかいが正確。** サービス業のUIに冷たさは不要。ただし時刻の表示だけは正確に、等幅で
- **色はスタッフと状態に。** スタッフごとの識別色と、予約状態の色。それ以外に色を使わない
- **7本の中で唯一、丸ゴシックを使う**

> **姉妹プロジェクトとの差別化（重要）**
> 書体で完全に分ける。HIREBASE＝明朝／ RELATE・CASTA・FIELDPIN・KANADE・MIWAKE＝角ゴシック（ウェイトと密度で差別化）／ **AKIMA＝丸ゴシック（Zen Maru Gothic）**。
> **一目で「別のプロダクト」と分かる最も確実な手段が書体である。**

## カラートークン

```css
:root {
  /* わずかに青みのある白。清潔感（サービス業） */
  --bg:        #F7F8FA;   /* ページ背景 */
  --panel:     #FFFFFF;   /* カード・パネル */
  --panel-alt: #EFF1F5;   /* 区切り・ヘッダー */
  --line:      #DEE2E9;   /* 罫線 */

  --ink-900:   #1B2330;   /* 見出し・本文 */
  --ink-600:   #58637A;   /* 補助テキスト */
  --ink-400:   #97A0B2;   /* ラベル・非活性 */

  --primary:   #2A6B5F;   /* 主要CTA「この時間で予約する」 */
  --primary-d: #1F5148;
  --primary-50:#E4F0ED;

  /* ★ 枠の状態。これ以外の色を枠に使わない */
  --slot-open:   #2A6B5F;   /* 空き */
  --slot-few:    #B5772A;   /* 残りわずか */
  --slot-full:   #C3C8D2;   /* 満席（無彩色。赤にしない） */
  --slot-held:   #7A6BA8;   /* 仮押さえ中 */
  --slot-closed: #E7E9EE;   /* 営業時間外・受付終了 */

  --slot-open-bg: #E4F0ED;
  --slot-few-bg:  #F7EEDF;

  /* 予約ステータス（管理側） */
  --st-confirmed: #2A6B5F;
  --st-visited:   #4A6FA5;
  --st-cancelled: #97A0B2;
  --st-noshow:    #B4453B;   /* ★ 無断キャンセルだけが赤 */
  --st-forced:    #B5772A;   /* 制約を無視して作成された予約 */
}
```

**配色ルール**

- **満席を赤にしない。** 満席は無彩色にして「そこにはない」ことを示す。**赤は無断キャンセルにだけ使う**
- **スタッフの識別色は、タイムラインの予約ブロックにのみ使う。** UIの意味づけには使わない
- **枠の状態は色 + 記号 + テキストで示す**（○ 空き／△ 残りわずか／× 満席）。色覚に依存させない（A11Y-04）
- お客様側と管理側で配色を変えない。**同じシステムであることが分かるようにする**

## タイポグラフィ

| 役割 | 書体 | 用途 |
|---|---|---|
| **見出し・ボタン** | **Zen Maru Gothic 500 / 700** | 画面タイトル、メニュー名、店舗名、CTA。**丸みが本プロダクトの識別記号** |
| 本文 | Noto Sans JP 400 | 説明、注記、規約 |
| **時刻・数値** | Roboto Mono 500（`tabular-nums`） | 時刻、残り時間、所要時間、金額、残席数 |

| トークン | デスクトップ | モバイル | 用途 |
|---|---|---|---|
| title | 22px / 700 Maru | 20px | 画面タイトル |
| section | 16px / 700 Maru | 16px | セクション見出し |
| menu | 16px / 500 Maru | 16px | メニュー名 |
| body | 14px / 400 | 14px | 説明文 |
| meta | 12px / 400 | 12px | 注記 |
| **time-lg** | 28px / 500 Mono | 24px | **選択中の日時、残り時間のカウントダウン** |
| time | 14px / 500 Mono | 14px | 枠の時刻、タイムラインの目盛り |
| price | 16px / 500 Mono | 16px | 金額 |

**丸ゴシックと等幅数字の組み合わせが、AKIMA の視覚的な指紋になる。** 柔らかさ（丸ゴシック）と正確さ（等幅数字）の同居が、予約というサービスの性格を表す。

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

| 項目 | 定義 |
|---|---|
| スペーシング | 4pxベース：4 / 8 / 12 / 16 / 24 / 32 / 48 |
| コンテンツ最大幅 | お客様側 720px（読み進める導線のため狭く）／管理側は画面幅いっぱい |
| **予約フローのステップ** | 上部にステップインジケータ（メニュー→スタッフ→日時→情報→確認）を常時表示 |
| **空き枠カレンダー** | 日付を横に7列（モバイル4列）、時間を縦に。**横スクロールではなく列数を減らす** |
| 枠ボタン | 高さ44px、日付列の幅いっぱい。**タップ領域は最低44×44px** |
| **タイムライン（管理）** | 1時間 = 60px を基準。**予約ブロックの高さ = 所要時間 × 1px/分** |
| タイムラインの列幅 | スタッフ1人あたり最小160px。横スクロール可 |
| 角丸 | **8px（カード・ボタン・枠）／12px（モーダル）。** 他6本より大きめにして柔らかさを出す |
| 影 | `0 1px 3px rgba(27,35,48,.08)`。カードのみ |
| セーフエリア | `env(safe-area-inset-bottom)` を考慮（モバイルの固定CTA） |

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

| コンポーネント | 仕様 |
|---|---|
| **空き枠カレンダー** | 日付ヘッダー（曜日・日付・空き数）+ 時刻行 × 日付列のグリッド。**枠は状態別の色 + 記号 + 時刻（Mono）** |
| 枠ボタン | 空き＝`--slot-open` の枠線 + 白背景／残りわずか＝`--slot-few` 背景／満席＝無彩色 + `×`／仮押さえ中＝`--slot-held` + 「他の方が選択中」 |
| **日付ヘッダー** | 曜日（土=青／日・祝=赤）、日付（Mono）、その日の空き数。**定休日は斜線** |
| **最短空きジャンプ** | カレンダー上部に常設。「最短の空き：3日後（木）14:00」+ ジャンプボタン |
| **仮押さえカウントダウン** | 画面上部に固定。`time-lg` の Mono で `04:52`。**残り1分で `--slot-few` に変わり、脈動する** |
| **競合モーダル** | 中央。上半分＝謝罪と再選択導線、**下半分＝罫線で区切った解説パネル**（SLT-04）。解説は畳まれておらず、最初から見えている |
| ステップインジケータ | 5ステップ。完了は塗り、現在は輪郭、未到達は淡色。**戻れるステップはクリック可** |
| **タイムライン** | 縦=時間（1時間60px）、横=スタッフ列。**予約ブロックは所要時間に比例した高さ**。バッファは薄い斜線 |
| 予約ブロック | 上端に時刻（Mono）、中央に顧客名 + メニュー、左端にスタッフ色の帯。**ドラッグ中は3度傾け影を強める** |
| 営業時間外の塗り | `--slot-closed`。シフト外は斜線、休憩は点線パターンで区別 |
| **現在時刻ライン** | タイムライン上の横線 + 左端に時刻。**1分ごとに更新** |
| デモ明示帯 | **予約確認・完了画面の上部。** `--slot-few-bg` の帯 + アイコン + 「これはデモです。実際の予約・連絡は発生しません」 |
| メールプレビュー | 実際のメール体裁（差出人・件名・本文）を封筒風のカードで表示。**「このメールは送信されていません」を明記** |
| 空状態 | 「この週に空きはありません」+ **最短の空きへのジャンプボタン**。行き止まりにしない |
| デモ切替バー | **濃色帯**。柔らかいアプリ本体と明確に区別する |

## モーション

| 対象 | duration | 内容 |
|---|---|---|
| 枠の選択 | 120ms | 背景色の変化。**移動やスケールはさせない**（誤タップの誘発を防ぐ） |
| **カウントダウン** | 1000ms周期 | 数値の更新のみ。**残り1分から脈動（2秒周期）** |
| 週送り | 240ms | 横スライド。cubic-bezier(.32,.72,0,1) |
| **競合モーダル** | 280ms | フェード + 8px上昇。**素早すぎると事故に見えるため、他のモーダルよりやや遅く** |
| タイムラインのドラッグ | 160ms | 掴む/離すのスケール変化。ドロップ時に着地 |
| ステップ遷移 | 200ms | フェード + 8px |
| 空き枠の再計算 | なし | **即座に反映する。** アニメーションで遅らせない |
| トースト | 200ms | 下から |

`prefers-reduced-motion: reduce` 時は、**カウントダウンの脈動を停止し、遷移を即時にする。**

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

| ID | 要件 |
|---|---|
| A11Y-01 | コントラスト比は通常4.5:1以上、18px以上は3:1以上 |
| A11Y-02 | **空き枠カレンダーをキーボードで操作できること**（矢印で枠移動、Enterで選択）。グリッド構造を `role="grid"` で表現すること |
| A11Y-03 | 各枠に、アクセシブルな名前（「3月14日 木曜日 14時00分 予約可能」／「満席」）を持たせること |
| A11Y-04 | **枠の状態を色のみで伝えないこと。** 記号（○△×）とテキストを併記すること |
| A11Y-05 | **仮押さえの残り時間を `aria-live="polite"` で通知すること**（1分ごと。毎秒読み上げさせない） |
| A11Y-06 | 残り時間が1分を切ったら `aria-live="assertive"` で警告すること |
| A11Y-07 | **タイムラインのドラッグ操作にキーボード代替を用意すること**（FR-505） |
| A11Y-08 | 競合モーダルはフォーカストラップし、**フォーカスを最初に「別の時間を選ぶ」ボタンに置くこと** |
| A11Y-09 | フォームの各入力に `label` を関連付け、エラーは `aria-describedby` と `role="alert"` で読み上げること |
| A11Y-10 | フォーカスリングは2px・オフセット2pxで常時可視 |
| A11Y-11 | タップ領域は最小44×44px |
| A11Y-12 | フォントサイズ200%指定でも、空き枠カレンダーと予約フォームが操作できること |
| A11Y-13 | **タイムラインを使わずに、予約一覧だけで店舗運営が完結できること**（視覚的なタイムラインに依存させない） |

## ライティング規約

| 原則 | 例 |
|---|---|
| **デモであることを繰り返す** | ○「これはデモです。実際の予約・連絡は発生しません」／× 小さく1箇所だけ |
| 満席を否定形で終わらせない | ○「この週に空きはありません。最短の空きは3日後（木）14:00です」+ ボタン／×「空きがありません」 |
| 仮押さえの意味を説明する | ○「この時間を5分間お取り置きしています。時間内にお進みください」／×「残り 04:52」だけ |
| **競合を謝る、しかし責めない** | ○「申し訳ありません。この時間は他のお客様が先に予約されました」／×「予約に失敗しました」 |
| キャンセル料は先に見せる | ○「本日のキャンセルは、料金の50%（3,300円）が発生します」／×「キャンセルポリシーをご確認ください」 |
| 所要時間を必ず添える | ○「カット + カラー（合計 120分）」／×「カット + カラー」 |
| エラーは原因と対処 | ○「お取り置きの時間が過ぎました。もう一度お時間をお選びください。入力内容は保存されています」 |
| システム語を使わない | ○「この時間の受付を停止する」／×「statusをblockedに更新」 |

---

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

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

| レイヤ | 技術 | 備考 |
|---|---|---|
| フレームワーク | Next.js 15（App Router）／ TypeScript strict | |
| スタイリング | Tailwind CSS + CSS Variables | |
| UIコンポーネント | shadcn/ui（Radix UI基盤） | 角丸を大きめに上書き |
| 状態管理 | Zustand + persist | localStorage に永続化 |
| **日時処理** | **date-fns（ja locale）+ 自前の分単位ユーティリティ** | **タイムゾーンは Asia/Tokyo 固定。** dayjs / moment を入れない |
| **空き枠計算** | **自前実装**（`lib/availability/`） | **カレンダーライブラリの空き枠機能に依存しない** |
| カレンダーUI | **自前実装** | FullCalendar 等を使わない。**既製カレンダーを貼るとデモの意味がなくなる** |
| D&D | dnd-kit | タイムラインの予約移動。**キーボード対応必須** |
| グラフ | Recharts | 分析画面（動的import） |
| フォーム | React Hook Form + Zod | |
| ics生成 | 自前実装（数十行） | ライブラリを足さない |
| アイコン | lucide-react | |
| フォント | Zen Maru Gothic / Noto Sans JP / Roboto Mono（`next/font`） | |
| ホスティング | Vercel | |
| テスト | Vitest / Playwright / axe-core | |

**上記以外のライブラリを入れる前に必ず提案し、承認を得ること。特に FullCalendar・react-big-calendar 等のカレンダーライブラリの導入は禁止。**

## ディレクトリ構成

```
/
├── CLAUDE.md
├── app/
│   ├── layout.tsx
│   ├── shops/[shopId]/
│   │   ├── page.tsx                 # SC-001
│   │   ├── booking/                 # SC-010〜018（?embed=1 は SC-013）
│   │   └── classes/                 # SC-020, 021
│   ├── reservations/                # SC-030〜034
│   ├── how-it-works/                # SC-040
│   ├── admin/                       # SC-100〜150
│   └── dev/components/
├── components/
│   ├── booking/                     # ★ 最重要
│   │   ├── SlotCalendar.tsx         # 空き枠カレンダー
│   │   ├── SlotButton.tsx           # 状態別の枠
│   │   ├── DayHeader.tsx
│   │   ├── EarliestJump.tsx         # 最短の空きへ
│   │   ├── HoldCountdown.tsx        # ★ 仮押さえのカウントダウン
│   │   ├── ConflictModal.tsx        # ★ 競合 + 解説パネル
│   │   ├── StepIndicator.tsx
│   │   └── MailPreview.tsx
│   ├── timeline/                    # ★ 管理側
│   │   ├── Timeline.tsx             # スタッフ列 × 時間軸
│   │   ├── ReservationBlock.tsx     # 高さ = 所要時間
│   │   ├── NowLine.tsx
│   │   ├── BlockedOverlay.tsx       # 営業外・シフト外・休憩
│   │   └── useTimelineDnd.ts
│   ├── domain/                      # MenuCard, StaffCard, CancelPolicyNote, DemoBanner
│   ├── demo/                        # RoleSwitcher, ResetButton, GuideTour, ConflictTrigger
│   └── layout/
├── lib/
│   ├── types/ seed/ store/ repo/
│   ├── availability/                # ★ 空き枠計算の唯一の場所。純粋関数
│   ├── time/                        # ★ 日時ユーティリティ。純粋関数
│   ├── hold/                        # 仮押さえ・競合シミュレーション
│   ├── ics/                         # ics生成
│   ├── calc/ query/ validation/ utils/
├── e2e/
└── public/
```

## コーディング規約

- TypeScript strict。`any` 禁止
- **空き判定を `lib/availability/` の外に書かない**（AVL-01）
- **`lib/availability/` と `lib/time/` は純粋関数のみ。** ストア・DOM に依存させない
- **`new Date()` を `lib/availability/` `lib/time/` の中で呼ばない。** 現在時刻は必ず引数で受け取る（AVL-02）
- **時刻は「その日の0時からの分数」で内部処理する。** 文字列の切り貼りで時刻を扱わない
- **タイムゾーンは Asia/Tokyo 固定。** UTC変換を挟まない（実案件では要検討である旨をコメントに残す）
- **コンポーネントから Zustand ストアを直接参照しない。必ず `lib/repo/` 経由**
- 派生値（残席・稼働率・機会損失）をストアに保存しない
- **仮押さえのタイマーは `setInterval` を使い、アンマウント時に必ず `clearInterval` すること**
- コミットは1タスクごと。メッセージに要件IDを含める
  例：`feat(availability): 前後バッファを空き枠計算に反映 (FR-106)`

---

# 12. 非機能要件・法令

## 性能要件

| ID | 要件 | 目標値 |
|---|---|---|
| NFR-01 | **空き枠の再計算**（60日分・スタッフ5名・刻み15分） | **100ms以下** |
| NFR-02 | 日付・スタッフ・メニューの切替から画面反映まで | 150ms以下 |
| NFR-03 | LCP（モバイル4G相当） | 2.5秒以下 |
| NFR-04 | INP | 200ms以下 |
| NFR-05 | CLS | 0.1以下。**カレンダー領域の高さを最初から確保すること** |
| NFR-06 | 埋め込みモードの初期JSバンドル（gzip後） | 70KB以下 |
| NFR-07 | アプリ本体の初期JSバンドル（gzip後） | 200KB以下（Recharts は動的import） |
| NFR-08 | タイムラインのドラッグ操作 | 60fps維持 |
| NFR-09 | 予約300件のタイムライン表示・切替がもたつかないこと | — |
| NFR-10 | **仮押さえのカウントダウンが、タブを離れて戻っても正確であること**（期限時刻から算出） | — |
| NFR-11 | Lighthouse | Performance 90 / Accessibility 95 以上 |
| NFR-12 | 対応環境 | iOS Safari 16以降、Android Chrome 最新、PC Chrome / Edge / Safari / Firefox 最新2バージョン |
| NFR-13 | localStorage 上限接近時に警告し、古い予約から削除すること。データを破損させないこと | — |

## セキュリティ・プライバシー

| ID | 要件 |
|---|---|
| SEC-01 | **入力された氏名・電話番号・メールアドレスを一切外部に送信しないこと。** localStorage にのみ保存すること |
| SEC-02 | この事実を、入力画面・確認画面・デモ切替バーで明示すること |
| SEC-03 | **GA4 に個人情報を送らないこと**（EMB-15） |
| SEC-04 | ユーザー入力（要望欄・管理画面のメモ）をサニタイズすること |
| SEC-05 | 「デモをリセット」ですべての入力情報が消えることを明示し、実際に消えること |

## デモ固有の誤解防止（**この領域の最重要リスク**）

| ID | 要件 |
|---|---|
| DEMO-01〜06 | 3章を参照。**全画面での常時明示、確認・完了画面での強調、架空データ、メール非送信、ダミー値の初期入力、埋め込みでは確定させない** |
| DEMO-07 | 予約完了画面に、**「この予約は記録されていますが、あなたのブラウザ内にのみ存在します」**と明記すること |
| DEMO-08 | 店舗の電話番号を、**実在しないことが明らかな形式**にすること（例：`03-0000-0000`） |

> **実案件への転用時の注意（デモ本体の要件ではない。商談で聞かれた際に説明できるよう記録）**
>
> **① ダブルブッキング対策は、必ずサーバー側で実装する**（2章の壁③）。データベースの一意制約・排他ロック・トランザクション分離レベルの設計が必須。**フロントエンドのバリデーションだけで済ませない**
>
> **② 特定商取引法**：事前決済やキャンセル料を取る場合、**キャンセルポリシーを予約前に明示する義務**がある。AKIMA が確認画面で規定を表示しているのはこのため
>
> **③ 個人情報保護法**：予約者情報は個人情報。利用目的の明示、保管期間の設定、安全管理措置が必要
>
> **④ 決済**：カード情報を自社で保持しない（PCI DSS）。決済代行のトークン方式を使う
>
> **⑤ 無断キャンセル対策**：飲食・サロンでは事前決済やクレジットカード登録が有効だが、**キャンセル料の徴収条件は契約として成立している必要がある**
>
> **⑥ タイムゾーン**：国内のみなら Asia/Tokyo 固定でよいが、**オンライン面談・海外顧客を扱うなら UTC 保持 + 表示時変換**が必要になる。後から変えると全データの移行が発生する
>
> **本デモは予約者情報をサーバーに送信しないため、②〜④の義務は発生しない。**「デモである」旨は画面上に常時明示する

---

# 13. 費用設計

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

## 予約システムだけの特殊事情：既製サービスが安くて強い

他の6テーマと違い、予約には**月額数千円から使える既製サービスが多数ある**。したがって、この記事で最初に答えるべきは「いくらか」ではなく——

> **「なぜ、既製サービスではなく自作するのか」**

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

## 自作が正当化される5つのケース

| ケース | 内容 |
|---|---|
| **① 独自の枠計算ルールがある** | 「カラーの放置中は別の客を受けられる」「2名同時施術」「回数券保有者は優先枠」など、既製サービスの設定範囲を超えるルール |
| **② 既存システムと連携する必要がある** | 自社の顧客管理・基幹システム・会員基盤と予約を一体化したい |
| **③ 予約件数が多く、手数料が重い** | 予約1件ごとの課金や送客手数料が、開発費を上回る規模になっている |
| **④ ブランド体験を握りたい** | 予約導線が事業の中核（高単価サービス・会員制）で、他社のUIに乗せたくない |
| **⑤ データを自社で持ちたい** | 顧客・予約データを自社資産として蓄積・分析したい |

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

## 損益分岐の計算式（**記事の中核**）

```
既製サービスの年間コスト
  = 月額 × 12
  + 予約1件あたりの手数料 × 年間予約件数
  + 決済手数料率 × 年間予約金額
  ( + 送客手数料 × 送客経由の予約件数 )

回収年数 = 開発費 ÷ （既製サービスの年間コスト − 自作の年間運用費）
```

**例の作り方（記事では実数を入れる）**

| 項目 | 小規模サロン | 中規模・多店舗 |
|---|---|---|
| 年間予約件数 | 2,400件（月200件） | 24,000件（月2,000件） |
| 既製サービスの年間コスト | 小 | **大（件数課金が効いてくる）** |
| 回収年数 | **長い → 既製を使うべき** | **短い → 自作の検討価値あり** |

**予約件数が増えるほど、自作が有利になる。** これが予約システムの費用構造の本質。件数が少ないうちは既製、伸びたら自作、という順序が合理的。

> **注意：** 各サービスの料金体系（月額／件数課金／送客手数料／決済手数料）は**変動するため、この文書に金額を書き込まない。** 記事執筆時点で公式の料金ページを確認し、**確認日を明記して掲載すること。**

## 見落とされやすい変動費：通知コスト

予約システムは**通知の塊**。1件の予約につき、確定・前日リマインド・当日リマインド・変更・キャンセルで**最大5通**が飛ぶ。

| チャネル | コスト構造 | 到達率 | 注意 |
|---|---|---|---|
| **メール** | ほぼ無料（送信サービスの従量課金は小さい） | 低い（迷惑メール・見落とし） | 無断キャンセル対策としては弱い |
| **SMS** | **1通ごとに課金。積み上がる** | 非常に高い | **年間予約件数 × 通数 で計算すること** |
| **LINE** | 配信数に応じた従量課金 | 高い | 友だち追加が必要 |
| アプリのプッシュ | ほぼ無料 | 中 | **ネイティブアプリが必要になる** |

```
SMS の年間コスト = 年間予約件数 × 1予約あたりの送信通数 × 1通あたりの単価
例：年間 2,400件 × 2通（リマインド）= 4,800通/年
```

**「リマインドで無断キャンセルを減らしたい」という要望は必ず出る。** そのとき SMS を選ぶと、月額は小さくても年間で効いてくる。**通知チャネルの選択は費用設計そのもの**なので、AKIMA では通知設定画面にチャネル別の概算コストを表示する（FR-702）。

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

**予約は、Webで完結する典型的な領域。**

| やりたいこと | Web | ネイティブ |
|---|---|---|
| 予約・変更・キャンセル | **できる** | できる |
| カレンダーへの登録 | **できる**（ics） | できる |
| リマインド通知 | メール／SMS／LINE | **プッシュ通知が使える** |
| リピート予約の利便性 | **PWAで十分** | 高い |

**判断の目安：** プッシュ通知を無料で送りたい、かつリピート率が非常に高い（月1回以上）業態でなければ、**Webで十分**。開発費は大きく下がる。

## 3層のコスト構造

| 層 | 内容 | 特徴 |
|---|---|---|
| ① 初期開発費 | 設計・実装・テスト | **枠計算ルールの複雑さで大きく変わる**（2章の壁②） |
| ② 固定運用費 | ホスティング、ドメイン、監視、データベース | 小さい |
| ③ 変動運用費 | **通知（特にSMS）／決済手数料** | 予約件数に比例。**通知チャネルの選択で桁が変わる** |

## 開発費の目安（スコープ別）

| スコープ | 含まれるもの | 目安 |
|---|---|---|
| 最小構成 | 単一リソース（部屋1つ等）の時間予約 + メール通知 | 小 |
| **標準構成（本デモ相当）** | **スタッフ指名／複数メニューと所要時間／前後バッファ／設備の同時空き／シフト管理／仮押さえ／競合制御／定員制クラス／管理タイムライン／分析** | 中 |
| 拡張構成 | 上記 + 事前決済 + 会員基盤 + 複数店舗の在庫共有 + 業態固有の複雑ルール + ネイティブアプリ | 大 |

**「予約システム」の幅が広いことが、費用が伝わらない最大の原因。** 記事ではこの3段階を明示し、デモは「標準構成」の実物であることを示す。

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

| ID | 要件 |
|---|---|
| COST-01 | デモ公開後、月次で「デモ起動数・予約完了数・ホスティング費用」を記録すること |
| COST-02 | **`booking_completed` の件数から、「これが実際の予約だった場合の既製サービス手数料」を試算して併記すること** |
| COST-03 | 記録した実測値を記事に掲載し、**確認日を明記すること** |
| COST-04 | **`conflict_occurred` の発生率を記録すること。** 「読者の何%が競合を体験したか」は、記事の主張が届いた指標になる（EMB-14） |

---

# 14. 実装タスク

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

## Phase 0 — 基盤と空き枠エンジン（4日）

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

### 0-2. `lib/time/`（**純粋関数。最初に書いてテストで固める**）
- [ ] `minutes.ts`：分↔時刻文字列の相互変換、日付+分 → ISO
- [ ] `range.ts`：時間帯の重なり判定・結合・差分（**空き枠計算の土台**）
- [ ] `calendar.ts`：週の生成、日付の走査、曜日・祝日判定
- [ ] **単体テストを書く。特に `range.ts` の差分演算は境界条件を網羅すること**

### 0-3. `lib/availability/`（**このプロジェクトの心臓部**）
- [ ] `rules.ts`：営業時間・定休日・臨時休業・受付期限・予約可能期間
- [ ] `shift.ts`：スタッフの勤務時間と休憩
- [ ] `buffer.ts`：前後バッファの扱い
- [ ] `resource.ts`：設備の同時空き判定
- [ ] `capacity.ts`：定員制の残席
- [ ] `slot.ts`：刻み幅での枠生成
- [ ] `reason.ts`：**埋まっている理由の判定**（AVL-04）
- [ ] `engine.ts`：`getAvailability()` 入口（AVL-03）
- [ ] **`new Date()` を内部で呼ばない。現在時刻は引数で受け取る**（AVL-02）
- [ ] **単体テストを網羅的に書く。** 以下を必ず含めること：
  - [ ] 所要時間が営業終了を跨ぐ枠が出ないこと（FR-105）
  - [ ] シフト外・休憩・既存予約・ブロック枠が除外されること
  - [ ] バッファが正しく効くこと（FR-106）
  - [ ] 「指名なし」で誰か1人空いていれば空きになること（FR-108）
  - [ ] 設備が埋まっていれば予約不可になること（FR-109）
  - [ ] 受付期限・予約可能期間の境界（FR-103）
  - [ ] メニュー所要時間を変えると空き枠が変わること（FR-608）
  - [ ] **埋まっている理由が正しく返ること**（FR-110）
- [ ] **60日分・スタッフ5名・刻み15分で 100ms以下であることをベンチマークで確認**（NFR-01）

### 0-4. 型とシード
- [ ] `lib/types/` に9章の型定義をすべて実装
- [ ] `lib/seed/` の全ファイル
- [ ] **店舗名・スタッフ名・住所・電話番号をすべて架空にする**（DEMO-03, DEMO-08）
- [ ] **予約の密度に濃淡をつける。** 直近3日は7〜8割、土日夕方は満席、平日午前は空き
- [ ] **「残りわずか」の枠を数個作る。** スタッフごとに埋まり方を変える
- [ ] **メニューの所要時間に幅を持たせる**（30/60/90/120分）
- [ ] 無断キャンセルのある顧客、キャンセル待ちのある満席枠を用意
- [ ] 日付は現在日時からの相対で生成する

### 0-5. `lib/hold/` とストア
- [ ] `manager.ts`：仮押さえの作成・期限判定・解放
- [ ] **`conflict-simulator.ts`：競合の再現**（確率発生 + 任意発生）(FR-305)
- [ ] `lib/store/{session,data,settings,hold,ui}.ts` を Zustand + persist で実装
- [ ] `lib/repo/_scope.ts`（FR-911）と全リポジトリモジュール
- [ ] **`confirmReservation` に確定直前の再検証を実装**（FR-112, AVL-05）
- [ ] **空き枠の再計算に擬似ディレイを入れない**

### 0-6. デザインシステム
- [ ] `app/globals.css` にカラートークンを CSS 変数で定義
- [ ] `tailwind.config.ts` を拡張（**角丸を大きめに**）
- [ ] フォント（**Zen Maru Gothic** / Noto Sans JP / Roboto Mono）を `next/font` で最適化。時刻に `tabular-nums`
- [ ] shadcn/ui を導入し、トークンに合わせて上書き
- [ ] 共通コンポーネント：`SlotButton` / `DemoBanner` / `StepIndicator` / `EmptyState`（**最短の空きへのジャンプ付き**）／`Skeleton`
- [ ] `prefers-reduced-motion` の対応
- [ ] **`/dev/components` にコンポーネントカタログを作成**

### 0-7. デモ基盤
- [ ] `RoleSwitcher`（3ロール）+ **デモ内の現在日時表示**（FR-901, FR-907）
- [ ] デモ切替バー（濃色帯）+ **「これはデモです」の常時明示**（FR-902）
- [ ] 「デモをリセット」(FR-905)
- [ ] 元記事リンク・資料ダウンロード（FR-908）

### Phase 0 完了チェック
- [ ] **`lib/availability/` のテストが全パターン通る**
- [ ] **シフトを変えると空き枠が変わることを、テストで検証済み**
- [ ] **メニューの所要時間を変えると空き枠が変わることを、テストで検証済み**
- [ ] 60日分の空き枠計算が100ms以下
- [ ] `/dev/components` で全コンポーネントがトークン通りに表示される

---

## Phase 1 — 予約フロー（5日・**最重要フェーズ**）

### 1-1. 空き枠カレンダー
- [ ] `SlotCalendar.tsx`：日付横 × 時間縦のグリッド（FR-205）
- [ ] `SlotButton.tsx`：状態別の**色 + 記号 + 時刻**（FR-208, A11Y-04）
- [ ] `DayHeader.tsx`：曜日・日付・空き数・定休日の斜線
- [ ] 週送り・週戻し、**予約可能期間の範囲外に進めない**（FR-206）
- [ ] **`EarliestJump.tsx`：最短の空きへジャンプ**（FR-207）
- [ ] 月表示への切替（○△×の一覧）(FR-209)
- [ ] **キーボード操作**：`role="grid"`、矢印で移動、Enterで選択（A11Y-02）
- [ ] 各枠のアクセシブルな名前（A11Y-03）
- [ ] **空状態：「この週に空きはありません」+ 最短の空きへのボタン**

### 1-2. 予約フロー
- [ ] SC-010 メニュー選択（複数選択、**合計時間と金額のリアルタイム計算**）(FR-201)
- [ ] SC-011 スタッフ選択（指名なし／あり、**最短空き日時の表示**）(FR-203, FR-204)
- [ ] `StepIndicator.tsx`（戻れるステップはクリック可）
- [ ] SC-012 空き枠カレンダー画面
- [ ] SC-015 予約者情報（**ダミー値の初期入力**）(FR-210, DEMO-05)
- [ ] 入力検証（FR-211）、離脱確認（FR-215）
- [ ] SC-017 確認画面（**キャンセル規定の表示 + デモ明示の強調帯**）(FR-212, DEMO-02)
- [ ] SC-018 完了画面（予約番号、**ics ダウンロード**、**メールプレビュー**）(FR-213, FR-214)
- [ ] `lib/ics/`：ics生成（自前実装）
- [ ] SC-001 店舗トップ

### 1-3. 仮押さえと競合（**記事の核心**）
- [ ] SC-014 仮押さえ画面
- [ ] `HoldCountdown.tsx`：**カウントダウン。残り1分で警告色 + 脈動**（FR-303）
- [ ] **リロードしてもカウントダウンが継続すること**（FR-304, NFR-10）
- [ ] `aria-live` での残り時間通知（1分ごと）(A11Y-05, A11Y-06)
- [ ] 仮押さえ中の枠を他の画面から除外（FR-302）
- [ ] **期限切れ時の自動解放と、入力内容の保持**（FR-308）
- [ ] **`ConflictModal.tsx`：競合モーダル + 解説パネル**（FR-306, SLT-04）
- [ ] **競合の確率発生（15%）と「競合を再現する」ボタン**（FR-305）
- [ ] 競合後、**その枠が実際に埋まっていること**（FR-307）
- [ ] **確定直前の再検証で埋まっていた場合も競合扱い**（FR-309）
- [ ] `setInterval` の確実な `clearInterval`

### 1-4. 埋め込みモード
- [ ] SC-013 埋め込みモード（3章、DEMO-06）
- [ ] **予約確定まで進ませない。** 枠タップで「続きは全画面デモで」
- [ ] 個人情報の入力欄を出さない
- [ ] 初期バンドル 70KB以下を実測（NFR-06）
- [ ] 空き枠の再計算 100ms以下を実測（EMB-05）

### Phase 1 完了チェック
- [ ] **フローAが完走する**（メニュー → スタッフ → 枠 → 仮押さえ → 情報 → 確認 → 完了）
- [ ] **フローBが完走する**（仮押さえ中に競合 → 解説 → 枠が埋まっている → 別枠で予約）
- [ ] 予約すると、その枠が空き枠カレンダーから消える
- [ ] リロードしてもカウントダウンが正確
- [ ] **カレンダーがキーボードのみで操作できる**
- [ ] 埋め込みモードで確定まで進めない

---

## Phase 2 — 管理側タイムライン（4日）

- [ ] `Timeline.tsx`：**横=スタッフ／縦=時間、1時間60px**（FR-501）
- [ ] `ReservationBlock.tsx`：**高さ = 所要時間 × 1px/分**、スタッフ色の帯
- [ ] `BlockedOverlay.tsx`：営業外・シフト外・休憩・ブロック枠の塗り分け（FR-502）
- [ ] `NowLine.tsx`：現在時刻ライン、自動スクロール（FR-508）
- [ ] **dnd-kit による予約のドラッグ移動**（FR-503）
- [ ] **移動先が予約不可なら弾き、理由を表示**（FR-504）
- [ ] **キーボードでの移動代替**（FR-505, A11Y-07）
- [ ] ブロック下端のドラッグで所要時間変更（FR-506）
- [ ] **タイムライン上のドラッグでブロック枠を作成**（FR-507, SC-115）
- [ ] SC-110 タイムライン画面 / SC-111 週表示（FR-513）
- [ ] SC-112 予約詳細・編集、ステータス変更（FR-511）、変更履歴（FR-512）
- [ ] SC-113 手動作成（**管理者は制約を無視できる**）(FR-509)
- [ ] **制約を無視した予約に警告マーク**（FR-510）
- [ ] SC-114 予約一覧・絞り込み・CSV（FR-514）
- [ ] SC-100 本日のダッシュボード
- [ ] **予約一覧だけで運営が完結できることを確認**（A11Y-13）

### Phase 2 完了チェック
- [ ] **6章「ロールを跨ぐ体験」の1と3が動作する**
- [ ] タイムラインがキーボードのみで操作できる
- [ ] 予約ブロックの高さが所要時間に正しく比例している

---

## Phase 3 — 設定と空き枠の連動（4日）

- [ ] SC-130 営業設定（営業時間・定休日・臨時休業・受付期限・予約可能期間・刻み幅）(FR-601〜603)
- [ ] **SC-130 内に空き枠プレビューと「埋まっている理由」の表示**（FR-604, AVL-04）
- [ ] SC-120 シフト管理（**スタッフ×日付グリッド**、週次パターンからの一括生成）(FR-605)
- [ ] 休憩時間の設定（FR-606）
- [ ] SC-121 スタッフ管理（対応メニュー、識別色）
- [ ] SC-131 メニュー管理（**所要時間・前後バッファ・必要設備・対応スタッフ**）(FR-607)
- [ ] SC-132 設備・席の管理（FR-609）
- [ ] SC-134 キャンセル規定（FR-611）
- [ ] SC-135 通知文面の設定（差し込み変数）(FR-612)
- [ ] SC-133 定員制クラスの管理（繰り返し開催）(FR-610)
- [ ] SC-020 / SC-021 定員制クラスの予約（残席、複数名）(FR-113)
- [ ] SC-140 顧客管理（来店履歴、**無断キャンセル回数**）

### Phase 3 完了チェック
- [ ] **6章「ロールを跨ぐ体験」の2・4・6が動作する**
- [ ] **メニューの所要時間を60分→90分にすると、選べる枠が目に見えて減る**（体験6）
- [ ] ブロック枠を作ると、お客様側から即座に消える
- [ ] 定員制クラスの予約が完走する

---

## Phase 4 — 予約管理・通知・分析（3日）

- [ ] SC-030 予約照会（予約番号 + 電話下4桁）(FR-401)
- [ ] SC-031 予約詳細（お客様側）(FR-402)
- [ ] SC-032 予約の変更（**再度の空き枠選択と仮押さえ**）(FR-403, FR-404)
- [ ] SC-033 キャンセル（**規定に応じた料率の警告**）(FR-405, FR-406)
- [ ] **キャンセル枠が即座に空き枠へ戻ること**（FR-407）
- [ ] SC-034 キャンセル待ち（FR-408）
- [ ] 予約履歴からの再予約（FR-409）
- [ ] **通知プレビュー**（確定・リマインド・変更・キャンセル）(FR-701)
- [ ] **チャネル別の文字数制限と概算コストの表示**（FR-702）
- [ ] SC-016 事前決済UI（**課金しない、デモ明示**）(FR-703, FR-704)
- [ ] SC-150 予約分析：稼働率（FR-801）、**時間帯別ヒートマップ**（FR-802）
- [ ] **機会損失の算出**（FR-803）
- [ ] キャンセル率・無断キャンセル率（FR-804）、リピート率（FR-805）
- [ ] **デモ中の予約・キャンセルが分析に反映されること**（FR-806）

### Phase 4 完了チェック
- [ ] 予約の変更・キャンセルが完走し、枠が正しく戻る
- [ ] 分析画面に意味のある数字が出ている（シードの品質確認）

---

## Phase 5 — 記事統合と仕上げ（3日）

### 5-1. 仕組みの解説と記事統合
- [ ] **SC-040「仕組みの解説」の作成**（空き枠の引き算・仮押さえ・競合制御を図で）(FR-310, SLT-05)
- [ ] 記事側の埋め込みコードを作成し、**実際の記事ページで動作確認**（EMB-01〜05）
- [ ] 記事の Core Web Vitals を埋め込み前後で比較検証
- [ ] 「全画面で予約の流れを試す」カードの設置
- [ ] 資料PDF（**予約要件の確認シート**・損益分岐計算シート）の作成とダウンロード導線
- [ ] 元記事リンク・問い合わせ導線（EMB-10, EMB-11）
- [ ] GA4 イベント設定。**`conflict_occurred` と `how_it_works_viewed` を必ず含める**（EMB-12, EMB-14）
- [ ] **GA4 に個人情報を送っていないことを確認**（EMB-15, SEC-03）
- [ ] `?embed=1` を `noindex` に（EMB-21）
- [ ] デモ本体の title / description / OGP（EMB-20）
- [ ] 記事側に `VideoObject` と `HowTo`。**`LocalBusiness` `Reservation` は使わない**（EMB-23, EMB-24）

### 5-2. 誤解防止の総点検（**この領域固有・最重要**）
- [ ] **全画面で「これはデモです」が見えることを確認**（DEMO-01）
- [ ] **予約確認・完了画面の強調帯を確認**（DEMO-02）
- [ ] **店舗名・スタッフ名・住所・電話番号がすべて架空であることを確認**（DEMO-03）
- [ ] **メールが1通も送信されないことを確認**（DEMO-04）
- [ ] **予約者情報の入力欄にダミー値が入っていることを確認**（DEMO-05）
- [ ] **埋め込みモードで確定まで進めないことを確認**（DEMO-06）
- [ ] 第三者に触ってもらい、**「本当に予約したと思ったか」を確認する**

### 5-3. 体験の総点検
- [ ] 6章「ロールを跨ぐ体験」の6パターンをすべて手動で確認
- [ ] 全30画面を開き、**空の画面が1つもないこと**を確認
- [ ] 空状態（空きなし／絞り込み0件）の出し分けを確認
- [ ] ガイドツアーを実装（FR-912）

### 5-4. アクセシビリティ監査
- [ ] axe-core を全画面に実行し、Critical / Serious を0件に
- [ ] **空き枠カレンダーをキーボードのみで操作完遂**（A11Y-02）
- [ ] **タイムラインをキーボードのみで操作完遂**（A11Y-07）
- [ ] **予約一覧だけで店舗運営が完結できることを確認**（A11Y-13）
- [ ] スクリーンリーダーで枠の状態と残り時間が読み上げられることを確認
- [ ] フォントサイズ200%での操作確認（A11Y-12）

### 5-5. パフォーマンス
- [ ] Recharts を動的import に切り出し、初期バンドルを200KB以下に（NFR-07）
- [ ] **空き枠の再計算100ms以下を実測**（NFR-01）
- [ ] タイムラインのドラッグ60fpsを実測（NFR-08）
- [ ] Lighthouse で Performance 90 / Accessibility 95（NFR-11）

### 5-6. 公開と記録
- [ ] Playwright で フローA・B・C の E2E（**競合は「任意発生」ボタンで決定的に**）
- [ ] Vitest：`lib/availability` `lib/time` `lib/calc` `_scope` のカバレッジ85%以上
- [ ] `/dev/components` を本番で非公開に
- [ ] Vercel へデプロイ
- [ ] **予約完了数・競合発生率の記録を開始**（COST-01, COST-04）
- [ ] 解説動画（3分）の収録：枠選択 → 仮押さえ → **競合発生** → 別枠で予約 → 管理タイムライン → シフト変更で空き枠が変わる
- [ ] 各フェーズのキャプチャを整理し、記事の「方法」パートの素材にまとめる

---

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

> **工数配分の意図：** Phase 0 に4日、うち**`lib/time/` と `lib/availability/` のテストに丸2日以上**を充てる。空き枠計算は**画面から見ると単純だが、境界条件が異常に多い**（営業終了跨ぎ、バッファの重なり、シフト境界、受付期限、設備の同時性）。ここをテストで固めずに画面から作ると、後半でバグの温床になり、しかも**再現条件の特定に膨大な時間がかかる**。
> Phase 1 に5日を割いているのは、**仮押さえと競合が記事の核心**だから。ここが動かないと、この記事は何も証明していないことになる。

---

# 15. 受入基準

1. 8章の優先度 P1 の要件がすべて実装されていること
2. 7章の主要フローA・B・Cが、エンドツーエンドで完走すること
3. 6章「ロールを跨ぐ体験」の6パターンがすべて動作すること
4. **空き判定を行うコードが `lib/availability/` の外に一切存在しないこと**
5. **`lib/availability/` が純粋関数であり、内部で `new Date()` を呼んでいないこと**
6. **60日分・スタッフ5名・刻み15分の空き枠再計算が 100ms以下であること**
7. **メニューの所要時間を変更すると、選べる空き枠が変わること**
8. **シフト・ブロック枠・営業設定の変更が、お客様側の空き枠に即座に反映されること**
9. **仮押さえのカウントダウンが、リロード後も正確に継続すること**
10. **競合が発生し、解説パネルが表示され、その枠が実際に埋まった状態でカレンダーに戻ること**
11. **予約確定の直前に空き枠が再検証されていること**
12. キャンセルした枠が、即座に他のお客様の空き枠に戻ること
13. **空き枠カレンダーとタイムラインが、キーボードのみで操作できること**
14. **予約一覧だけで店舗運営が完結できること**（タイムラインに依存しない）
15. **全画面で「これはデモです」が明示され、確認・完了画面では強調されていること**
16. **店舗名・スタッフ名・住所・電話番号がすべて架空であり、メールが1通も送信されないこと**
17. **入力された個人情報が外部に一切送信されていないこと**（DevTools と GA4 のイベントで確認）
18. 全30画面のいずれにも空の状態がなく、リアルなデータが表示されていること
19. axe-core で Critical / Serious の指摘が0件であること
20. データアクセスがすべて `lib/repo/` を経由していること
21. **HIREBASE / RELATE / CASTA / FIELDPIN / KANADE / MIWAKE と並べたときに、明確に別のプロダクトとして見えること**

---

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

1. **仕様がこの文書にない場合は、実装せずに質問する。** 推測で作らない
2. **空き判定を `lib/availability/` の外に書かない。** 「ここだけ簡単にチェックすれば」が全ての崩壊の始まり
3. **`lib/availability/` と `lib/time/` を純粋関数に保つ。** 現在時刻は必ず引数で受け取る
4. **既製のカレンダーライブラリ（FullCalendar 等）を導入しない。** 自前実装であることがこのデモの価値
5. **競合とダブルブッキングの話を薄めない。** これは記事の核心であり、正直に「デモでは本質的には解けない」と書く
6. **「これはデモです」の明示を削らない。** この領域で最も重い事故は、本当に予約したと誤解されること
7. **時刻は分単位の数値で扱う。** 文字列の切り貼りで時刻計算をしない
8. `setInterval` の `clearInterval` を忘れない
9. スコープ外（5章 Won't have）は実装しない。**特に業態固有の複雑ルールは、要件定義の段階で洗い出す**
10. 「デモだから」を理由に品質を落とす判断はしない
11. **姉妹プロジェクトのトークン・コンポーネントをコピーしない。特に書体は AKIMA だけが丸ゴシック**


---

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

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

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

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

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

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