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

**版数** 2.0（初版 1.0 の実装と、見た目の作り直し・案内役「つたえ」の追加を反映した改訂版）／ **作成日** 2026-10-01 ／ **発行** ソウゾウ合同会社
**用途** 業務アプリの実演デモ ／ 飲食店のマニュアル作成・共有編
**公開中の実装** https://tsutae.souzohnic.workers.dev （本書 v2.0 はこの実装と同じものを作るための指示書である）

---

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

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

- **実装は「11. 実装タスク」の順に進める。フェーズを飛ばさない。**
- 各タスクの括弧内は要件ID。着手前に該当章を読むこと。
- **仕様がここに書かれていない場合は、推測で実装せず質問する。**
- スコープ外（3章 Won't have）は、思いついても実装しない。
- 「デモだから」を理由に品質を落とす判断はしない。
- **現場の言葉で書く。** 画面の文言は、店舗や工場で働く人がそのまま読んで分かる言葉にする。「ナレッジ」「コンテンツ」「ドキュメント」「アセット」「ワークフロー」のような言葉を画面に出さない（「マニュアル」「手順」「写真」「動画」「確認」と書く）。

> **v2.0 で変わったこと（v1.0 から）**
> - 画面の骨組みを「左のメニュー＋上の帯（探す・お知らせ）＋ダッシュボード型のホーム」にした（8章）
> - 案内役のキャラクター **「つたえ」** を足した。画面の右下にいつもいて、話しかけ、押すとその場で質問できる（6.9）
> - スタートページを、つたえが自己紹介をして約5秒でアプリへ案内する形にした（SC-000）
> - ⌘K で、マニュアル・手順・画面をまとめて探せる（FR-901）
> - 動画は同じ素材を使い回してよいので、30本のうち16本・25の手順に置く（7章）

> **このアプリの勝ち筋**
> マニュアルは「作るのが面倒」「作っても読まれない」「読んでも分からないところを聞く相手がいない」の3つで死ぬ。TSUTAE は、**スマホで撮った写真に矢印を描くだけで手順書ができ、現場ではQRコードからすぐ開け、分からないことはチャットで聞くとマニュアルの該当の手順が写真つきで返ってくる**ことで、この3つを一度に解く。
> 作るのに10分以上かかる、現場で開くのに3回以上押す、質問しても関係のない手順が返ってくる、のどれか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. プロジェクト概要

## 背景と目的

飲食・小売・介護・製造など、パートやアルバイトが多く入れ替わる現場（従業員20〜300名規模）では、**仕事のやり方が先輩の頭の中と、古い紙のファイルと、誰かのスマホの動画に散らばっている**。新人が入るたびに同じことを口で教え、教える人によってやり方が変わる。分からないことがあっても、忙しい先輩に聞きづらく、自己流で済ませてしまう。

紙や文書ソフトでマニュアルを作ると、写真を貼って矢印を描くだけで1時間かかり、作り直されずに古くなる。TSUTAE は、**写真と動画で手順を作る・必要な人に届ける・読まれたか確かめる・分からないことに答える**を1つにまとめる。

| 目的 | 内容 |
|---|---|
| 作りやすさの証明 | スマホで撮った写真を並べ、矢印や丸を描き、ひとこと書くだけで手順書ができる |
| 届けて確かめる仕組みの証明 | 店舗・部署ごとに配り、誰が読んだか・確認テストに合格したかが分かる |
| 「聞ける」マニュアルの証明 | 案内役「つたえ」に質問すると、マニュアルの中から該当の手順を写真つきで返す。答えられなかった質問は、マニュアルを足すべき場所として作成者に知らせる |
| 横展開の資産化 | マニュアルの中身（会社・部署・手順）をデータとして差し替えれば、業種を変えられる構造にする |

## プロダクト定義

| 項目 | 内容 |
|---|---|
| プロダクト名 | TSUTAE（つたえ）※仮称 |
| 一言定義 | 飲食店のマニュアル管理アプリ。写真と動画で手順書をつくり、現場に届け、質問には案内役がマニュアルから答える |
| 提供形態 | レスポンシブWebアプリ。**フロントエンド完結（サーバー側の保存なし）** |
| 主戦場 | 現場のスマホ（読む・質問する・QRから開く）と、事務所のPC（作る・配る・確かめる） |
| 想定利用者 | 現場のスタッフ（パート・アルバイト・新人）、マニュアルを作る人（店長・リーダー）、管理する人（本部の教育担当） |
| 見本の会社 | 「ひだまりフーズ株式会社」— 架空の会社。定食屋4店舗とセントラルキッチン（仕込みの工場）1か所、従業員約120名 |

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

> **「撮って、描いて、伝わる。聞けば、返ってくる。」**
>
> 手順書の主役は写真と動画。文字は「どこを見て、何をするか」をひとこと添えるだけ。現場の人は、機械に貼ったQRコードからそのマニュアルを開き、分からないことはチャットで聞く。答えはいつも、会社のマニュアルの中にある。

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

1. **触った瞬間に「うちの現場で使える」と分かる** — 空の画面が1つもなく、写真と動画の入った手順書が30本ほど入っている
2. **作るのが速い** — 写真を3枚選び、矢印を描き、ひとこと書いて公開するまでが、初めての人でも3分でできる
3. **聞けば返ってくる** — 「レジ締めのやり方」「食洗機が止まった」「アレルギーの確認ってどうする」と聞くと、該当のマニュアルの該当の手順が写真つきで返る
4. **ロールで見え方が変わる** — スタッフは自分の店に配られたマニュアルだけ、作成者は自分の店の読まれ具合、本部は全体
5. **リセットできる** — 誰が触った後でも、初期状態に戻せる
6. **開いて5秒で何のアプリか分かる** — スタートページで案内役が「飲食店のマニュアル係」と名乗り、見本のカードを見せてからアプリへ入る
7. **相棒がいる** — どの画面でも右下に案内役がいて、画面に合わせて話しかけ、押せばその場で聞ける

---

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

## 基本方針

**バックエンドとデータベースを持たない。すべてブラウザ内で完結させる。AIの外部サービスも使わない（費用ゼロ）。**

| 一般的な構成 | 本プロジェクト |
|---|---|
| PostgreSQL / Supabase | シードデータ（TypeScript）+ ブラウザ内ストア |
| ログイン | デモ用ロール切替（ワンクリック） |
| 写真・動画のクラウド保存 | **ブラウザ内の IndexedDB** に保存（写真は縮小、動画は大きさの上限つき） |
| 生成AIによる回答（文章を作るAI） | **使わない。** ブラウザ内の検索（6.6）で質問に合う手順を探し、決まった型の文章と写真で返す |
| メール・通知の配信 | 画面内のお知らせで再現 |
| PDFの生成（サーバー側） | ブラウザ内で生成し、実際にダウンロードできる |

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

- **デモとして最適** — 訪問者は登録もログインもせずに、作る・配る・読む・聞くを即座に触れる
- **費用ゼロ・データを預からない** — 質問の内容も写真もブラウザから出ない。外部のAIに送らないので、1回いくらの費用も、情報が外へ出る心配もない
- **開発速度** — 認証・ファイル保存のサーバー・AIの接続が不要になり、**作る画面の使いやすさと、質問への答えの的確さに全時間を投下できる**
- **運用コストゼロ** — 静的配信のみ

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

**データアクセスは必ず `src/lib/repo/` のリポジトリ層を経由すること。** コンポーネントからストアを直接触らない。**質問への回答も `src/lib/answer/` の1か所に閉じ込める。**

```
[ 画面・コンポーネント ]
        ↓  呼ぶのはこの層だけ
[ src/lib/repo/*.ts ]        ← 全メソッドを async にしておく
        ↓                         └ repo/assistant.ts → src/lib/answer/（検索と回答文の組み立て）
[ src/lib/store/*.ts ]       ← Zustand + persist（localStorage）
[ src/lib/media/*.ts ]       ← 写真・動画（IndexedDB）
        ↓
[ src/lib/seed/*.ts ]        ← 初期データ
```

リポジトリの各メソッドは、中身が同期処理でも **`async` で定義し、`await` で呼ぶ**。本番化する際は、リポジトリの実装だけをデータベースへの問い合わせに差し替えれば、画面は一行も変更せずに済む。

**回答の差し替え口：** `repo/assistant.ts` の `ask(question)` は、デモでは `src/lib/answer/` の検索で回答を作る。本番で生成AIに切り替える場合は、`ask` の中身だけを「検索で見つけた手順をAIに渡し、文章を作らせる」形に差し替える。**画面には「回答（文章）」「根拠になった手順（最大3件）」「確からしさ」だけを渡す**ので、画面は変更しなくてよい。

```ts
// src/lib/repo/assistant.ts — 中身は同期でも async にする
export async function ask(question: string): Promise<Result<Answer>> {
  await delay('ask')                                   // 「考えています」を見せる 600〜900ms
  const hits = searchSteps(question, getVisibleManuals()) // スタッフに見えるマニュアルだけを探す（FR-003）
  return { ok: true, data: composeAnswer(question, hits) } // 本番化でここが生成AIの呼び出しになる
}
```

## 永続化の範囲

| 対象 | 挙動 |
|---|---|
| シードデータ | 初期投入。以降は編集可能 |
| 操作の結果（マニュアルの作成・編集・公開・配布・既読・確認テスト・質問の履歴） | localStorage に保存。**リロードしても保持される** |
| 写真 | シードの写真は `public/photos/` を参照し、保存しない。利用者が追加した写真だけを長辺1600pxに縮小しJPEG品質0.82・1枚300KB以下にして **IndexedDB** に保存する（localStorage は5MB程度しかないため） |
| 動画 | シードの動画は `public/videos/` を参照する。利用者が追加した動画は **1本30MB・60秒まで**、IndexedDB に保存する。超える場合は理由を出して受け付けない（ブラウザ内で動画の圧縮はしない） |
| リセット | デモ切替バーの「デモをリセット」で localStorage と IndexedDB を空にし、初期状態へ |

**擬似的な非同期を必ず入れること。** リポジトリの操作に 150〜400ms のディレイを挟み、読み込み中の状態を実際に見せる。質問への回答だけは 600〜900ms（「マニュアルを探しています」を見せる）。ただし**マニュアルの一覧の絞り込みと、検索窓の候補は 100ms 以下**にする。

> **容量に注意。** IndexedDB の使える容量はブラウザと端末の空きで変わる。`navigator.storage.estimate()` で残りを確かめ、残りが動画1本分（30MB）を下回ったら、動画の追加を止めて理由を出す（NFR-10）。

---

# 3. スコープ定義

## 読む・聞く（スタッフ）

| ID | 機能 | 優先度 |
|---|---|---|
| F-R01 | ホーム（自分に届いたマニュアル・読んでいない数・研修の進み具合・よく見られている手順） | Must |
| F-R02 | マニュアルを読む（手順ごとに写真・動画・説明・注意・コツ。スマホで1手順ずつめくる） | Must |
| F-R03 | 読んだ印（最後の手順まで見て「確認しました」） | Must |
| F-R04 | 確認テスト（マニュアルごとに2〜5問の選択式） | Must |
| F-R05 | マニュアルを探す（文字・カテゴリ・店舗・タグ） | Must |
| F-R06 | 質問チャット（質問すると、該当の手順を写真つきで返す） | Must |
| F-R07 | QRコードから開く（機械や棚に貼ったQRで、そのマニュアルのその手順を直接開く） | Must |
| F-R08 | お気に入り・最近見たもの | Should |
| F-R09 | 研修（新人向けの、マニュアルを順番に並べた課題） | Must |
| F-R10 | 印刷（手順書をA4のPDFで保存） | Should |
| F-R11 | 動画で見る手順（ホームに動画の手順を横に並べる・一覧で「動画あり」に絞る） | Must |

## 作る（作成者）

| ID | 機能 | 優先度 |
|---|---|---|
| F-E01 | マニュアルの作成（題名・カテゴリ・対象の店舗・表紙の写真・所要時間） | Must |
| F-E02 | 手順の編集（追加・並べ替え・削除・複製。手順ごとに写真か動画・説明・注意・コツ） | Must |
| F-E03 | 写真の書き込み（矢印・丸・四角・番号・文字・ぼかし）。元の写真は残し、書き込みは別に持つ | Must |
| F-E04 | 写真をまとめて追加すると、1枚につき1手順を自動で作る | Must |
| F-E05 | 動画の追加と、見せたい区間（開始と終わりの秒）の指定 | Must |
| F-E06 | 下書きの自動保存 | Must |
| F-E07 | 確認テストの作成 | Must |
| F-E08 | ひな形から作る（開店準備・機械の使い方・衛生・接客の型） | Should |
| F-E09 | 質問の言いかえの登録（このマニュアルに当たってほしい言葉。例：「締め作業」→レジ締め） | Must |

## 届ける・確かめる（作成者・本部）

| ID | 機能 | 優先度 |
|---|---|---|
| F-D01 | 公開の流れ（下書き → 確認待ち → 公開。本部の確認を通す設定） | Must |
| F-D02 | 版の履歴（いつ・誰が・何を変えたか。前の版に戻す） | Must |
| F-D03 | 配る（店舗・部署・個人を選んで届ける。期限つき） | Must |
| F-D04 | 読まれ具合（配った人のうち、読んだ人・テストに合格した人・まだの人） | Must |
| F-D05 | まだの人への声かけ（画面内のお知らせを送る） | Must |
| F-D06 | QRコードの発行（手順を指定したQR。印刷用PDF） | Must |
| F-D07 | 研修の作成（マニュアルを順番に並べ、新人に割り当てる） | Must |
| F-D08 | 古くなったマニュアルの知らせ（最終更新から180日たったもの） | Should |

## 質問と分析（作成者・本部）

| ID | 機能 | 優先度 |
|---|---|---|
| F-Q01 | 質問の記録（質問・返した手順・「解決した／しなかった」） | Must |
| F-Q02 | 答えられなかった質問の一覧（マニュアルを足すべき場所として） | Must |
| F-Q03 | 答えられなかった質問から、言いかえを登録する・新しいマニュアルを作り始める | Must |
| F-Q04 | 分析（よく見られるマニュアル・読まれていないマニュアル・テストの正答率・よく聞かれる質問） | Must |

## 共通・基盤

| ID | 機能 | 優先度 |
|---|---|---|
| F-S01 | デモ切替バー（スタッフ／作成者／本部の切り替え・リセット） | Must |
| F-S02 | 画面内のお知らせ（配られた・期限が近い・声かけ・確認待ち） | Must |
| F-S03 | はじめての人への案内（3ステップのガイド） | Must |
| F-S04 | スタートページ（案内役が自己紹介をして、そのままアプリへ案内する） | Must |
| F-S05 | 案内役「つたえ」（画面の右下にいつもいる。話しかける・その場で質問に答える・動かせる・休ませられる） | Must |
| F-S06 | まとめて探す（⌘K。マニュアル・手順・画面を横断して探す） | Must |
| F-S07 | お知らせの引き出し（上の帯のベルから右に開く） | Must |

## 対象外（Won't have）

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

- 生成AI（文章を作るAI）への接続・外部のAIサービスの利用（費用ゼロの方針。差し替え口だけ用意する。2章）。**案内役「つたえ」は見た目のキャラクターであり、答えはいつも 6.6 の検索で作る**
- 動画の編集（切り貼り・字幕の自動作成・音声の読み上げ）。区間の指定だけ
- 多言語への自動翻訳
- 外部のサービスとの連携（LINE・Slack・メール配信・人事システム）
- 複数の会社の管理（1社のみ）
- 権限の細かい設定画面（ロールは3つで固定）
- マニュアルの自由なデザイン編集（見た目の型は固定。変えられるのは中身だけ）
- 手書きの書き込みの筆圧・レイヤーの重ね順の編集

---

# 4. ロールとデモ切替

## ロール定義

| ロール | 見本の人 | できること | 見える範囲 |
|---|---|---|---|
| スタッフ | 中野 さくら（駅前店・入社2週間のアルバイト） | 読む・聞く・確認テスト・研修 | **自分に配られたマニュアルと、全社公開のマニュアルだけ** |
| 作成者 | 木村 大輔（駅前店の店長） | 上のすべて＋自分の店のマニュアルを作る・配る・読まれ具合を見る・自分の店の質問を見る | 自分の店と全社公開のマニュアル。読まれ具合は自分の店の人だけ |
| 本部 | 小川 美和（本部 教育担当） | 上のすべて＋全店のマニュアル・公開の確認・全体の分析・研修の作成 | すべて |

**見える範囲の判定は `src/lib/repo/_scope.ts` の1か所に集約する。** スタッフが質問したときも、**スタッフに見えないマニュアル（他店だけに配られたもの・下書き）を回答の根拠にしてはならない**（`answer/` に渡すのは `_scope.ts` を通した後のマニュアルだけ）。

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

画面の最上部に常に表示する、黒い細い帯（高さ 44px。PCでは上に固定）。

| 要素 | 内容 |
|---|---|
| 左 | 「デモ」の印と「これはデモです。入力した内容と写真・動画は、このブラウザの中にだけ保存されます」 |
| 中央 | 見え方の切り替え：**スタッフ ／ 作成者 ／ 本部**（名前と店も小さく出す） |
| 右 | 「使い方」（ガイドの再表示）・「デモをリセット」（確認ダイアログあり） |

スマホの幅では、中央を短い表記にし、右はアイコンだけにする。

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

1. **作って届ける** — 作成者で写真を3枚追加して手順を作り、矢印を描いて公開を依頼 → 本部で確認して公開 → 作成者で駅前店のスタッフに配る → スタッフのホームに「新しいマニュアルが届きました」が出る
2. **読んで確かめる** — スタッフで届いたマニュアルを最後まで読み「確認しました」→ 確認テストに合格 → 作成者の読まれ具合で、中野さんが「合格」になる
3. **聞いて返る** — スタッフで「レジ締めってどうやるの」と聞く → 「レジ締め（閉店後）」の手順3〜6が写真つきで返る → 「この手順を開く」で該当の手順へ
4. **答えられない質問が届く** — スタッフで「エアコンの温度を変えたい」と聞く → 見つからないので「見つかりませんでした。店長に聞く」 → 作成者の「答えられなかった質問」に出る → 「言いかえを登録」か「マニュアルを作る」へ進める
5. **言いかえが効く** — 作成者で「締め作業」を「レジ締め（閉店後）」の言いかえに登録 → スタッフで「締め作業のやり方」と聞くと、レジ締めが一番上に返る
6. **見える範囲が違う** — 中央店だけに配られた「中央店 フライヤーの油交換」は、駅前店のスタッフには一覧にも質問の答えにも出ない。本部では見える
7. **QRで開く** — 本部で「食器洗浄機の使い方」の手順4のQRを表示 → 「スマホで開く（デモ）」でスタッフの画面のその手順が開く
8. **案内役がそばにいる** — スタッフで「食器洗浄機の使い方」の手順7を開く → 右下のつたえが「手順7で分からないことがあったら…」と話しかける → つたえを押して「洗剤は？」と聞く → いま読んでいるマニュアルを優先して「洗剤の補充」が一番上に返る

---

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

## スタート

| ID | 画面 | パス | 内容 |
|---|---|---|---|
| SC-000 | スタートページ | `/` | 暗い画面の真ん中に案内役「つたえ」を大きく出し、3行の自己紹介を1文字ずつ話す（「はじめまして。飲食店のマニュアル係、つたえです。」「写真と動画の手順書を届けて、質問にも答えます。」「では、お店にご案内しますね。」）。2行目で見本のカード（書き込みつきの写真・動画の手順・質問の答え・既読率）が浮かぶ。話し終わったら約5秒で、いまのロールのホームへ自動で移る。「飛ばして入る」「入る」「止める」と、別の見え方で入るボタン（店長・本部）。LP のような説明文は置かない |

## スタッフ（読む・聞く）

| ID | 画面 | パス | 内容 |
|---|---|---|---|
| SC-001 | ホーム | `/home` | ダッシュボード（8章「ホームの配置」）。今日のハイライト（期限の近い届いたマニュアル。動画があれば音なしでくり返す）・大きな数字4つ（読んでいない・期限が近い・研修・今週聞いた）・案内役の入口「何を探しますか？」・届いたマニュアル・動画で見る手順・研修の進み具合・お店でよく見られている手順・お知らせ・最近見たもの |
| SC-010 | マニュアル一覧 | `/manuals` | カテゴリのタブ（開店・閉店／調理／衛生／接客／機械・設備／事務）・表紙の写真つきカード（題名・手順の数・所要時間・読んだ印・新着）・絞り込み（店舗・タグ・読んでいない） |
| SC-011 | マニュアルを読む | `/manuals/:id`（手順 `/manuals/:id/steps/:n`） | 表紙（題名・所要時間・必要なもの・更新日）→ 手順ごとの画面（写真か動画を大きく・番号・ひとことの見出し・説明・注意（黄）・コツ（緑））。スマホは横にめくる／PCは左に手順の目次・右に本文。最後に「確認しました」と確認テストへ |
| SC-012 | 確認テスト | `/manuals/:id/quiz` | 1問ずつ・選択式・答えるとすぐ正誤と解説（該当の手順へのリンク）。合格の基準（初期 80%）。不合格はやり直せる |
| SC-020 | 質問チャット | `/ask` | 上に案内役の見出し（大きなつたえ・いまの状態）。つたえのあいさつと質問の例・やり取りの履歴・回答の吹き出し（つたえのアバター＋文章＋手順のカード最大3件＋「解決した／しなかった」）・入力（下に固定。左につたえ、右に送るボタン） |
| SC-030 | 研修 | `/training` / `/training/:id` | 自分に割り当てられた研修・順番に並んだマニュアル・それぞれの状態（未・読んだ・合格）・期限 |
| SC-040 | お知らせ | `/notices` | 配られた・期限が近い・声かけ |
| SC-050 | QRから開く | `/q/:code` | QRの番号から該当のマニュアルの該当の手順へ移る。見る権限がなければ「このマニュアルは、あなたの店には配られていません」 |

スマホの下部の帯：**ホーム ／ マニュアル ／ 聞く ／ 研修 ／ お知らせ**

## どの画面にも出るもの

| ID | もの | 内容 |
|---|---|---|
| SC-900 | 案内役「つたえ」 | 画面の右下にいつもいる（6.9）。スタートページ・大きな「聞く」画面・写真の書き込み中は出さない |
| SC-910 | まとめて探す | ⌘K・Ctrl+K・「/」・上の帯の検索窓で開く重ねた画面（FR-901〜903） |
| SC-920 | お知らせの引き出し | 上の帯のベルで右から開く。未読の数・すべて読んだ・押すと該当の画面へ |
| — | 左のメニュー（PC） | 幅 248px。ロゴ・読む聞く5項目・「作る・確かめる」（作成者・本部）・「本部」の区切り・数字のバッジ・下に自分のカード。幅 1024px 未満では上の帯の左のボタンから引き出す |
| — | 上の帯 | 高さ 64px。探す（⌘K）・お知らせのベル。背景は少し透かして、下の画面がにじんで見える |

## 作成者

| ID | 画面 | パス | 内容 |
|---|---|---|---|
| SC-100 | 作ったマニュアル | `/studio` | 自分の店のマニュアル（下書き・確認待ち・公開中・差し戻し）・古くなったもの・「新しく作る」 |
| SC-101 | マニュアルの編集 | `/studio/manuals/:id` | 左：手順の目次（ドラッグで並べ替え）。中：選んだ手順の編集（写真か動画・見出し・説明・注意・コツ）。右（または上のタブ）：基本情報（題名・カテゴリ・対象・表紙・所要時間・必要なもの）・言いかえ・確認テスト・公開。上に「プレビュー」「公開を依頼」。**スマホでも作れる**（1列で、手順を1つずつ） |
| SC-102 | 写真の書き込み | `/studio/manuals/:id/steps/:n/annotate`（全画面） | 道具：矢印・丸・四角・番号（①②③を順に置く）・文字・ぼかし（顔や伝票の個人情報を隠す）・色（赤・黄・白）・元に戻す／やり直す・全部消す。保存で手順に戻る |
| SC-103 | 写真をまとめて追加 | `/studio/manuals/:id/bulk`（シート） | 写真を複数選ぶ（またはドラッグ）→ 並び順を確かめる → 1枚1手順で追加 |
| SC-104 | 確認テストの編集 | `/studio/manuals/:id/quiz` | 問題・選択肢（2〜4）・正解・解説・根拠の手順 |
| SC-105 | ひな形から作る | `/studio/templates` | 4つの型（開店準備・機械の使い方・衛生・接客）。選ぶと手順の見出しだけが入った下書きができる |
| SC-110 | 配る | `/studio/manuals/:id/distribute`（シート） | 店舗・部署・個人を選ぶ・期限・「確認テストの合格を必須にする」・送る |
| SC-111 | 読まれ具合 | `/studio/manuals/:id/reach` | 配った人数・読んだ・合格・まだ。人ごとの一覧（名前・店・状態・読んだ日・点数）・「まだの人に声をかける」 |
| SC-112 | QRコード | `/studio/manuals/:id/qr` | マニュアル全体のQRと、手順ごとのQR。「印刷用PDF」（A4 に4枚、題名と手順の見出しつき）・「スマホで開く（デモ）」 |
| SC-120 | 質問 | `/studio/questions` | タブ「答えられなかった」「解決しなかった」「すべて」。質問・日時・店・返した手順・「言いかえを登録」「マニュアルを作る」「対応済み」 |

## 本部

| ID | 画面 | パス | 内容 |
|---|---|---|---|
| SC-200 | 確認待ち | `/admin/review` | 公開を依頼されたマニュアルの一覧 → 開くと変更点（前の版との違い）・「公開する」「差し戻す（理由）」 |
| SC-201 | 全体の分析 | `/admin/insights` | 配ったマニュアルの既読率・合格率（店舗別）・よく見られるマニュアル・読まれていないマニュアル・テストで間違いの多い問題・よく聞かれる質問・答えられなかった質問の推移（週） |
| SC-202 | 研修の管理 | `/admin/training` | 研修の作成（マニュアルを順に並べる・期限・対象）・進み具合（人×マニュアルの表） |
| SC-203 | 版の履歴 | `/studio/manuals/:id/history` | 版の一覧（版・日時・人・変更の要約）・2つの版の違い・この版に戻す（作成者も開ける） |
| SC-210 | 店舗と人 | `/admin/people` | 店舗・部署・人の一覧（デモでは閲覧と、人の店舗の変更だけ） |

## 主要フロー

### フロー1：写真から手順書を作って届ける（作成者 → 本部 → スタッフ）

```
作成者：作ったマニュアル → 新しく作る → 題名「ドリンクサーバーの洗い方」・カテゴリ「機械・設備」・対象「駅前店」
  → 写真をまとめて追加（見本の写真5枚から3枚を選ぶ）→ 3つの手順ができる
  → 手順2の写真を開き、矢印でノズルを指し「ここを外す」と文字を置く → 保存
  → 各手順に見出しを書く（「電源を切る」「ノズルを外す」「ぬるま湯で洗う」）→ 手順3に注意「熱湯は使わない」
  → 言いかえに「ドリンクバー」「ジュースの機械」→ 確認テストを1問 → 公開を依頼
本部：確認待ち → 開く → 公開する
作成者：配る → 駅前店のスタッフ全員・期限は1週間後 → 送る
スタッフ：ホームに「新しいマニュアルが届きました」→ 読む → 確認しました → テストに合格
作成者：読まれ具合で中野さんが「合格」
```

### フロー2：現場で聞く（スタッフ）

```
スタッフ：ホームの案内役の入口「何を探しますか？」に「食洗機が途中で止まった」と入れる
  → 「マニュアルを探しています…」（0.8秒）
  → 回答：「『食器洗浄機の使い方』の手順7『途中で止まったとき』が近そうです。」
          ＋ 手順7のカード（写真・見出し・説明の最初の2行）＋ 手順8のカード
  → 「この手順を開く」→ 手順7の画面
  → チャットに戻り「解決した」
```

### フロー3：答えられない質問をマニュアルにする（スタッフ → 作成者）

```
スタッフ：「エアコンの温度を変えたい」→ 回答：「お店のマニュアルには見つかりませんでした。」＋「店長に知らせる」
作成者：質問 → 答えられなかった に1件 → 「マニュアルを作る」→ 題名に質問が入った下書き
```

### フロー4：QRで開く（現場）

```
本部：「食器洗浄機の使い方」→ QRコード → 手順4「洗剤の補充」のQR → スマホで開く（デモ）
  → スタッフの画面で手順4が直接開く（ほかの手順へもめくれる）
```

### フロー5：開いて、つたえに聞く（はじめての人）

```
スタートページ：つたえが3行で自己紹介 → 約5秒でホームへ
ホーム：右下のつたえが「中野さん、期限が近いマニュアルが2本ありますよ」
  → 手順を読んでいる途中で、つたえを押して質問 → その場の小さなチャットで写真つきの答え → 押すとその手順へ
```

---

# 6. 機能要件

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

## 6.1 ロール・デモ基盤

| ID | 要件 | 優先度 |
|---|---|---|
| FR-001 | デモ切替バーで、スタッフ／作成者／本部を1クリックで切り替えられること。いまの画面がそのロールでも開けるならそのまま、開けないならそのロールのホームへ移ること | P1 |
| FR-002 | ロールの切り替えで、一覧・ホーム・質問の答え・分析の表示範囲が変わること | P1 |
| FR-003 | 見える範囲の判定を `src/lib/repo/_scope.ts` に集約すること。質問への回答は、`_scope.ts` を通したマニュアルだけを探すこと | P1 |
| FR-004 | 「デモをリセット」で、確認のうえ localStorage と IndexedDB を空にし、初期状態に戻すこと | P1 |
| FR-005 | はじめて開いた人に、3ステップのガイド（①質問してみる ②マニュアルを読む ③店長でマニュアルを作る）を出すこと。閉じたら出さない。デモ切替バーの「使い方」で再表示できること | P1 |
| FR-006 | 画面の上部に「デモです」の表示を常に出すこと | P1 |
| FR-007 | 権限のない画面のURLを直接開いた場合は、その画面を開けるロールを案内し、切り替えを促すこと | P1 |

## 6.2 読む（スタッフ）

| ID | 要件 | 優先度 |
|---|---|---|
| FR-101 | ホームに、届いて読んでいないマニュアル（期限の近い順）・研修の進み具合・質問の入口・最近見たもの・自分の店でよく見られている手順（直近7日）を出すこと。配置は8章「ホームの配置」 | P1 |
| FR-111 | ホームの「今日のハイライト」は、届いて読んでいないマニュアルのうち動画のあるもの（期限の近い順）を選び、表紙の写真（くっきりしたもの）を大きく敷く。動画があれば「動画あり」を出し、PCでマウスを乗せている間だけ区間を音なしでくり返す（最初の表示を写真にするのは、動画の1コマはぼやけやすく、最初の表示も遅くなるため） | P1 |
| FR-112 | ホームの大きな数字4つ（読んでいない・期限が近い（3日以内）・研修 n/N と進み具合の輪・今週聞いた）は、0から数え上がる。最終値の幅を先に取り、数え上がる間に周りが動かないこと | P1 |
| FR-113 | ホームに「動画で見る手順」を横に並べる。同じ動画が続かないよう散らす。PCではマウスを乗せると音なしで少し流れる。一覧には「動画あり」の絞り込みを置く | P1 |
| FR-114 | ホームのタイルは、そのセッションで初めて開いたときだけ60msずつずらして浮かび上がる。2回目からはすぐ出す | P2 |
| FR-102 | マニュアル一覧で、カテゴリ・店舗・タグ・「読んでいない」で絞り込めること。カードに表紙の写真・題名・手順の数・所要時間・読んだ印・新着（7日以内）を出すこと | P1 |
| FR-103 | マニュアルを読む画面で、スマホは手順を横にめくり（スワイプとボタンの両方）、PCは左に目次・右に本文を出すこと。いまの手順の番号と全体の数（3／8）を常に出すこと | P1 |
| FR-104 | 手順の写真は書き込みを重ねて表示し、押すと全画面で拡大（指で拡大縮小）できること | P1 |
| FR-105 | 手順の動画は、指定の区間だけを再生し、区間の終わりで止めること。「もう一度」「全部見る」を出すこと。自動再生はしない（音が出るため） | P1 |
| FR-106 | 注意（黄色）とコツ（緑）を、説明と見分けがつく枠で出すこと。色だけでなく「注意」「コツ」の文字と印を添えること | P1 |
| FR-107 | 最後の手順まで見たら「確認しました」を押せること。途中の手順を飛ばした場合も押せるが、飛ばした手順の番号を出して確かめること | P1 |
| FR-108 | どの手順まで読んだかを覚え、次に開いたときに「続きから（手順5）」を出すこと | P1 |
| FR-109 | マニュアル全体をA4のPDFで保存できること（1ページに手順2つ・写真と書き込み・注意とコツ） | P2 |
| FR-110 | お気に入りと最近見たもの（10件） | P2 |

## 6.3 確認テスト

| ID | 要件 | 優先度 |
|---|---|---|
| FR-201 | 確認テストは、マニュアルごとに2〜5問。選択肢は2〜4つ。1問ずつ答え、すぐに正誤と解説を出すこと | P1 |
| FR-202 | 解説には、根拠の手順へのリンクを付けること | P1 |
| FR-203 | 合格の基準は正答率80%（設定で変えられる）。不合格は間違えた問題の根拠の手順を示し、やり直せること | P1 |
| FR-204 | 選択肢の並び順は、受けるたびに入れ替えること | P2 |

## 6.4 作る（作成者）

| ID | 要件 | 優先度 |
|---|---|---|
| FR-301 | マニュアルの基本情報：題名（40文字まで）・カテゴリ・対象（全社／店舗・部署を選ぶ）・表紙の写真（手順の写真から選べる）・所要時間（分）・必要なもの（任意）・タグ | P1 |
| FR-302 | 手順：見出し（30文字まで・必須）・写真か動画（どちらか1つ・任意）・説明（300文字まで）・注意（100文字まで）・コツ（100文字まで） | P1 |
| FR-303 | 手順の追加・削除・複製・並べ替え（ドラッグとキーボードの両方）ができること。削除は5秒間「元に戻す」を出すこと | P1 |
| FR-304 | 写真をまとめて追加すると、並び順を確かめたうえで1枚1手順を作り、見出しを「手順 N」の仮の文字で入れること（見出しは後で直す前提。仮のまま公開を依頼したら止める） | P1 |
| FR-305 | 写真を選ぶと、ブラウザ内で長辺1600pxに縮小し、JPEG品質0.82にして IndexedDB に保存すること。スマホのカメラの写真の向き（EXIF）を正しく直すこと | P1 |
| FR-306 | 動画は mp4 / mov / webm、1本30MB・60秒まで。区間（開始と終わりの秒）を、動画の下のつまみで指定できること。表紙用の1コマ（区間の開始の画面）を自動で作ること | P1 |
| FR-307 | 編集の内容は、入力をやめて1秒後に自動で保存し、「保存しました（12:04）」を出すこと | P1 |
| FR-308 | 「プレビュー」で、スタッフが見る画面そのものを、スマホの枠とPCの両方で見られること | P1 |
| FR-309 | ひな形から作ると、型の手順の見出しだけが入った下書きができること（開店準備：8手順／機械の使い方：7手順／衛生：6手順／接客：6手順） | P2 |
| FR-310 | 言いかえ（このマニュアルに当たってほしい言葉）を10個まで登録できること。手順にも、手順ごとの言いかえを5個まで登録できること | P1 |
| FR-311 | 確認テストの作成：問題（100文字まで）・選択肢（各40文字まで）・正解・解説（200文字まで）・根拠の手順 | P1 |

## 6.5 写真の書き込み（FR-4xx）

| ID | 要件 | 優先度 |
|---|---|---|
| FR-401 | 道具：矢印・丸・四角・番号・文字・ぼかし。色は赤・黄・白の3色。線の太さは3段階 | P1 |
| FR-402 | **書き込みは写真に焼き込まず、図形のデータとして別に持つこと**（写真の大きさに対する割合で位置を持ち、どの画面幅でもずれないこと） | P1 |
| FR-403 | 番号は、置くたびに ①②③… と自動で増えること。途中を消したら番号を詰めること | P1 |
| FR-404 | 置いた図形を、選んで動かす・大きさを変える・消すことができること。元に戻す／やり直すは20回まで | P1 |
| FR-405 | ぼかしは、選んだ四角の範囲をぼかして表示すること（顔や伝票の個人情報を隠すため）。**ぼかしだけは表示のときに写真に重ねて塗り、元の写真が透けて見えないようにすること** | P1 |
| FR-406 | 指（スマホ）とマウス（PC）の両方で書けること。キーボードでも、選んだ図形を矢印キーで動かせること | P1 |
| FR-407 | 文字は20文字まで。白い縁取りをつけて、写真の上でも読めるようにすること | P1 |

## 6.6 質問チャット（費用ゼロの回答のしくみ）

**生成AIは使わない。** ブラウザ内の検索で「質問に一番合う手順」を探し、決まった型の文章と手順のカードで返す。

### 探し方（`src/lib/answer/search.ts`）

1. **探す対象は「手順」**。1つの手順につき、次の文字をまとめて探す対象にする：マニュアルの題名・タグ・言いかえ（重み3）／手順の見出し・手順の言いかえ（重み3）／手順の説明・注意・コツ（重み1）
2. **文字の正規化**：全角・半角、カタカナ・ひらがな、大文字・小文字をそろえ、記号と空白を除く。「〜ってどうやるの」「〜したい」「〜のやり方」「教えて」などの言い回し（`answer/phrases.ts` に並べる）を質問から取り除く
3. **言葉の分け方**：日本語は単語の区切りがないため、**2文字ずつ区切った言葉（例：「食洗機」→「食洗」「洗機」）**と、`answer/dictionary.ts` の現場の言葉の辞書（「食洗機」「レジ締め」「釣り銭」など）に一致した言葉の両方を使う
4. **同じ意味の言葉**：`answer/synonyms.ts` に「食洗機＝食器洗浄機＝洗い場の機械」「レジ締め＝精算＝締め作業」のような組を持ち、質問の言葉を広げる（初期 60組）。マニュアルの言いかえ（FR-310）も同じ扱いにする
5. **点数**：BM25（よく使われる検索の点数の付け方。k1=1.2、b=0.75）に、上の重みを掛ける。同じマニュアルの手順は最大2件までにし、ほかのマニュアルの手順も候補に残す
6. **確からしさ**：一番の点数が基準（初期：正規化した点数で 0.35）を超えれば「見つかった」、超えなければ「見つからなかった」とする。基準は `answer/config.ts` に置き、テストで調整する

### 返し方（`src/lib/answer/compose.ts`）

| 結果 | 文章の型 | 一緒に出すもの |
|---|---|---|
| 見つかった（1つのマニュアルにまとまる） | 「『{マニュアル名}』の手順{n}『{見出し}』が近そうです。」 | 手順のカード（最大3件。写真・見出し・説明の最初の2行・「この手順を開く」）。手順に注意があれば「注意：…」も1行 |
| 見つかった（複数のマニュアルにまたがる） | 「関係しそうな手順が{件数}つ見つかりました。」 | 手順のカード（最大3件、マニュアル名つき） |
| 見つからなかった | 「お店のマニュアルには見つかりませんでした。言い方を変えるか、店長に聞いてください。」 | 「店長に知らせる」（答えられなかった質問として記録）・よく聞かれる質問の候補3つ |

- **文章をでっち上げない。** 返す文章は上の型と、マニュアルに書いてある文字だけで作る。マニュアルにない手順や数字を作らない
- 回答の下に「解決した／しなかった」を出し、記録すること（F-Q01）
- 回答の吹き出しの下に小さく「マニュアルから探した答えです」と出す（AIが文章を考えたように見せない）

| ID | 要件 | 優先度 |
|---|---|---|
| FR-501 | 質問を入れると、600〜900msの「マニュアルを探しています」の後に、上の型で回答すること | P1 |
| FR-502 | 回答の手順のカードを押すと、そのマニュアルのその手順が開くこと。読み終えたら「質問に戻る」で元のやり取りへ戻れること | P1 |
| FR-503 | 見える範囲（FR-003）の外のマニュアルを、回答の根拠にも候補にも出さないこと | P1 |
| FR-504 | 質問・返した手順・解決したかを記録すること（質問の内容はブラウザの外に出ない） | P1 |
| FR-505 | 「店長に知らせる」で、答えられなかった質問として作成者の質問の画面に出すこと | P1 |
| FR-506 | 入力の途中で、よく聞かれる質問とマニュアルの題名から候補を出すこと（100ms以下） | P2 |
| FR-507 | 続けて聞いた質問（例：「洗剤は？」）は、直前に返したマニュアルの点数を1.3倍にして探すこと（話の流れを汲むため） | P2 |
| FR-508 | 7章の「見本の質問」40問のうち、36問以上で、期待する手順が上位3件に入ること（テストで確かめる） | P1 |

## 6.7 届ける・確かめる

| ID | 要件 | 優先度 |
|---|---|---|
| FR-601 | 公開の流れ：下書き → 確認待ち → 公開／差し戻し。本部の確認を通すかどうかは設定（初期：通す）。差し戻しは理由が必須 | P1 |
| FR-602 | 公開するたびに版を1つ増やし、版ごとの内容を残すこと。2つの版の違い（足した手順・消した手順・変えた文字・変えた写真）を並べて見られること。前の版に戻すと、新しい版として公開すること | P1 |
| FR-603 | 公開中のマニュアルを直すと、下書きの版ができ、公開中の版はそのまま見え続けること | P1 |
| FR-604 | 配る：店舗・部署・個人を選び、期限（任意）と「テストの合格を必須にする」を指定して送ること。送った人に画面内のお知らせが届くこと | P1 |
| FR-605 | 内容を大きく変えた版を公開するときに「読み直しを求める」を選ぶと、配った人の読んだ印を外し、お知らせを送ること | P2 |
| FR-606 | 読まれ具合：配った人数・読んだ人数・合格した人数・まだの人数と、人ごとの状態の一覧。店で絞り込めること | P1 |
| FR-607 | 「まだの人に声をかける」で、まだの人にお知らせを送ること。同じ人へは1日1回まで | P1 |
| FR-608 | QRコード：マニュアル全体と手順ごとに発行し、A4に4枚並べた印刷用PDF（題名・手順の番号と見出し・「スマホで読み取ってください」）を作れること | P1 |
| FR-609 | 最終更新から180日たったマニュアルに「見直しの時期です」を出すこと | P2 |
| FR-610 | 研修：マニュアルを順に並べ、対象の人と期限を決めて割り当てること。人×マニュアルの表で進み具合が分かること | P1 |

## 6.8 質問と分析

| ID | 要件 | 優先度 |
|---|---|---|
| FR-701 | 答えられなかった質問・解決しなかった質問の一覧。同じ意味の質問は、正規化した文字が同じものを1行にまとめて回数を出すこと | P1 |
| FR-702 | 質問の行から「言いかえを登録」：マニュアル（または手順）を選び、質問の言葉を言いかえに足すこと。足したら、その質問で検索し直した結果をその場で見せること | P1 |
| FR-703 | 質問の行から「マニュアルを作る」：質問の文を題名の候補に入れた下書きを作ること | P1 |
| FR-704 | 分析：店舗別の既読率・合格率、よく見られるマニュアル（上位10）、配ったのに読まれていないマニュアル、テストで間違いの多い問題、よく聞かれる質問（上位10）、答えられなかった質問の数の推移（週ごと8週） | P1 |
| FR-705 | 作成者の分析は自分の店の分だけ、本部はすべて | P1 |

## 6.9 案内役「つたえ」（F-S05）

**画面の右下にいつもいる相棒。** ボタンではなく、そこに「いる」ことが大事。見た目は暗いガラスの球に光る目（8章 `AgentOrb`）。答えはいつも 6.6 の検索で作り、生成AIは使わない。

| ID | 要件 | 優先度 |
|---|---|---|
| FR-801 | 画面の右下に常に出す（スマホは下の帯の上、マニュアルを読む画面ではめくるボタンの上）。大きさはスマホ 64px・PC（幅1024px以上）104px。スタートページ・大きな「聞く」画面・写真の書き込み中は出さない | P1 |
| FR-802 | ふだんはゆっくり浮かび、まばたきし、まわりを小さな星が回る。PCでは目がマウスの方を追う | P1 |
| FR-803 | 画面が変わると約1.4秒後に、その画面に合わせた吹き出しで話しかけ、約9秒で消える（×で閉じられる）。言う内容は実際のデータから作り、数字をでっち上げない（例：ホーム「中野さん、期限が近いマニュアルが2本ありますよ」／手順の画面「手順7で分からないことがあったら、ここから聞いてくださいね」／作成者「答えられなかった質問が7件あります」） | P1 |
| FR-804 | 押すと、その場で小さなチャット（幅380px、PCは420px）が開く。直近4件のやり取り・質問の例・写真つきの答え（押すとその手順へ）・「店長に知らせる」・大きな「聞く」画面へのリンク。やり取りは `/ask` と同じ記録を使う | P1 |
| FR-805 | マニュアルを読んでいる途中に聞いたときは、そのマニュアルを FR-507 と同じ倍率で優先して探す | P1 |
| FR-806 | 表情を変える：探している間は目が黄色に光って左右を見回し、星が速く回る／答えが見つかったら笑って跳ねる／チャットを開いている間は笑顔 | P1 |
| FR-807 | ドラッグで好きな位置へ動かせ、位置は覚える。押しただけ（6px未満の移動）はチャットを開く | P2 |
| FR-808 | 月のボタンで休ませられる（目を閉じて小さくなり「z」が出る。話しかけない）。押すと起きて跳ねる | P2 |
| FR-809 | キーボードでも操作できる（Enter/スペースで開く・Escで閉じてつたえに戻る）。吹き出しは読み上げに知らせる。光の輪や星は押す邪魔をしない（`pointer-events: none`） | P1 |
| FR-810 | 答えの下に「つたえがマニュアルから探した答えです」と出す（AIが文章を考えたように見せない） | P1 |

## 6.10 まとめて探す（⌘K・F-S06）

| ID | 要件 | 優先度 |
|---|---|---|
| FR-901 | ⌘K・Ctrl+K・「/」（入力中でないとき）・上の帯の検索窓で開く。マニュアル（題名・言いかえ・タグ）・手順（見出し・言いかえ）・画面（ロールのメニュー）を横断して出す。入力した言葉を「〇〇を聞く」の行として先頭に出し、押すと `/ask` で聞く | P1 |
| FR-902 | 完全一致 ＞ 前方一致 ＞ 部分一致の順に並べ、見える範囲（FR-003）の外は出さない。待ち時間なしで返す（100ms以下） | P1 |
| FR-903 | ↑↓で選び、Enterで開き、Escで閉じる。キーボードだけで完結すること | P1 |

---

# 7. データ設計

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

```ts
export type Role = 'staff' | 'author' | 'hq'

export interface Site { id: string; name: string; kind: 'store' | 'kitchen' | 'hq' }   // 駅前店・中央店・…・セントラルキッチン・本部
export interface Person { id: string; name: string; siteId: string; position: 'staff' | 'leader' | 'manager' | 'hq'; joinedAt: string }

export type Category = 'open-close' | 'cooking' | 'hygiene' | 'service' | 'equipment' | 'office'
// 開店・閉店／調理／衛生／接客／機械・設備／事務

export type MediaRef =
  | { kind: 'file'; path: string; width: number; height: number }        // シード（public/）
  | { kind: 'idb'; id: string; width: number; height: number }           // 利用者が追加したもの

export type Shape =
  | { id: string; type: 'arrow'; x1: number; y1: number; x2: number; y2: number; color: Color; weight: 1 | 2 | 3 }
  | { id: string; type: 'circle' | 'rect' | 'blur'; x: number; y: number; w: number; h: number; color: Color; weight: 1 | 2 | 3 }
  | { id: string; type: 'number'; x: number; y: number; color: Color }      // 番号は並び順から算出（保存しない）
  | { id: string; type: 'text'; x: number; y: number; text: string; color: Color }
// 位置はすべて写真の幅・高さに対する割合（0〜1）
export type Color = 'red' | 'yellow' | 'white'

export interface Step {
  id: string
  title: string                     // 見出し
  body: string                      // 説明
  caution: string                   // 注意
  tip: string                       // コツ
  media:
    | { kind: 'photo'; ref: MediaRef; shapes: Shape[] }
    | { kind: 'video'; ref: MediaRef; poster: MediaRef; start: number; end: number }
    | null
  aliases: string[]                 // 手順の言いかえ
}

export interface QuizQuestion { id: string; text: string; choices: string[]; answer: number; explanation: string; stepId: string | null }

export interface ManualVersion {
  version: number
  title: string
  category: Category
  coverStepId: string | null
  minutes: number
  tools: string                     // 必要なもの
  tags: string[]
  aliases: string[]                 // マニュアルの言いかえ
  steps: Step[]
  quiz: QuizQuestion[]
  publishedAt: string | null
  publishedBy: string | null
  changeNote: string                // 変更の要約
}

export interface Manual {
  id: string
  siteIds: string[] | 'all'         // 対象（全社 or 店舗）
  ownerId: string                   // 作成者
  status: 'draft' | 'review' | 'published' | 'returned'
  returnReason: string | null
  published: ManualVersion | null   // いま公開中の版
  draft: ManualVersion | null       // 編集中の版（公開中を直しているときも）
  history: ManualVersion[]          // 過去の版（新しい順）
  createdAt: string
  updatedAt: string
  qrCode: string                    // QRの番号（/q/:code）
}

export interface Distribution {
  id: string; manualId: string
  targets: { siteIds: string[]; personIds: string[] }
  dueAt: string | null; requireQuiz: boolean
  sentAt: string; sentBy: string
}

export interface ReadRecord {       // 人×マニュアル
  personId: string; manualId: string; version: number
  lastStep: number; completedAt: string | null
  quiz: { score: number; passed: boolean; at: string } | null
}

export interface Training { id: string; name: string; manualIds: string[]; personIds: string[]; dueAt: string | null; createdBy: string }

export interface Question {
  id: string; personId: string; siteId: string; text: string; normalized: string
  askedAt: string
  hits: { manualId: string; stepId: string; score: number }[]
  found: boolean
  feedback: 'solved' | 'unsolved' | null
  reported: boolean                 // 店長に知らせた
  resolvedAt: string | null         // 作成者が対応済みにした
}

export interface Notice { id: string; personId: string; kind: 'distributed' | 'due' | 'nudge' | 'review' | 'returned' | 'reread'; manualId: string | null; text: string; createdAt: string; readAt: string | null }

export interface QrLink { code: string; manualId: string; stepId: string | null }

export interface Answer {                    // 画面に渡す回答（生成AIに差し替えても形は変えない）
  text: string
  hits: { manualId: string; manualTitle: string; stepId: string; stepIndex: number; stepTitle: string; excerpt: string; caution: string | null; media: Step['media'] }[]
  confidence: 'found' | 'not-found'
}
```

**派生値は保存しない。** 既読率・合格率・研修の進み具合・番号の書き込みの番号・古くなった印は、`src/lib/calc/` の関数で毎回算出する。

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

| データ | 件数 | 内容 |
|---|---|---|
| 拠点 | 6 | 駅前店・中央店・南口店・港町店・セントラルキッチン・本部 |
| 人 | 40 | 各店8名前後（店長1・リーダー1・スタッフ）・キッチン6名・本部2名。名前は架空 |
| マニュアル | 30 | 下の一覧。公開中26・確認待ち2・下書き1・差し戻し1。うち中央店だけに配ったもの1（4章 体験6） |
| 手順 | 約180 | 1マニュアルあたり4〜9手順。**すべての手順に写真か動画がある**（写真176枚・動画の素材8本。動画は同じ素材を、場面の近い手順に使い回して **30本のうち16本・25の手順** に置く。`seed/videos.ts` の `videoSteps`。区間は手順ごとに変えてよい） |
| 確認テスト | 22本 | 1本2〜5問 |
| 配布と既読 | — | 各店の既読率を 55〜95% にばらけさせる（駅前店がいちばん低い＝声かけの見せ場） |
| 研修 | 2 | 「新人研修（ホール）」8本・「新人研修（キッチン）」6本。中野さくらに「新人研修（ホール）」を割り当て、3本合格済み |
| 質問の履歴 | 120件 | 直近8週。答えられなかったもの18件（うち同じ意味のまとまりで「エアコン」「シフトの交代」「制服の洗い方」が複数回） |
| 版の履歴 | — | 5本のマニュアルに2〜4版の履歴 |

**マニュアルの一覧（題名・カテゴリ・手順の数）**

| 開店・閉店 | 調理 | 衛生 | 接客 | 機械・設備 | 事務 |
|---|---|---|---|---|---|
| 開店準備（ホール）8 | ご飯の炊き方（業務用炊飯器）6 | 手洗いの手順 6 | いらっしゃいませから案内まで 6 | 食器洗浄機の使い方 9 | シフトの提出のしかた 4 ／ 勤怠の打刻のしかた 4 |
| 開店準備（キッチン）7 | 味噌汁の仕込み 5 | アレルギーの確認と伝え方 7 | 注文の取り方（ハンディ）7 | 券売機のつり銭の補充 5 | 発注のしかた 6 |
| レジ締め（閉店後）8 | 唐揚げの揚げ方 7 | 調理場の清掃（閉店後）8 | お会計と領収書 6 | フライヤーの油の交換 7 | 落とし物の扱い 4 |
| 閉店後のホール清掃 6 | 生姜焼き定食の盛り付け 5 | 冷蔵庫の温度の記録 4 | クレームを受けたとき 6 | 製氷機の掃除 5 | 新人の受け入れ（店長向け）6 |
| ゴミの分別と出し方 5 | 仕込み品の日付ラベル 4 | 体調が悪いときの報告 4 | 電話の受け方 5 | 中央店 フライヤーの油交換（中央店のみ）6 | — |

> 写真と動画は、利用条件で商用利用が認められているもの（Pexels・Unsplash などの写真と動画、または AI で生成した画像）だけを使い、`public/photos/CREDITS.json` と `public/videos/CREDITS.json` に出典を記録する。スタートページの下に「写真・動画のクレジット」へのリンクを置く。**実在の会社のロゴ・制服の文字・人の顔がはっきり分かる写真は使わない**（顔が写る場合はシードの書き込みでぼかしを置き、FR-405 の見本にする）。
> 写真の上の書き込み（矢印・丸・番号）を、シードの写真の6割以上に入れる。書き込みのないマニュアルは、このアプリの見せ場を伝えない。

**見本の質問（`src/lib/seed/sample-questions.ts`）**：FR-508 のテストに使う40問。質問の文・期待するマニュアル・期待する手順を持つ。例：

| 質問 | 期待するマニュアル／手順 |
|---|---|
| レジ締めってどうやるの | レジ締め（閉店後）／手順1〜3 |
| 締め作業のやり方 | レジ締め（閉店後）（言いかえで当たる） |
| 食洗機が途中で止まった | 食器洗浄機の使い方／手順「途中で止まったとき」 |
| 洗剤どこに入れる | 食器洗浄機の使い方／手順「洗剤の補充」 |
| アレルギーのお客さんが来たら | アレルギーの確認と伝え方／手順1 |
| 油っていつ替える | フライヤーの油の交換／手順1 |
| 冷蔵庫の温度ってどこに書く | 冷蔵庫の温度の記録／手順2 |
| お客さんに怒られた | クレームを受けたとき／手順1 |
| 領収書の書き方 | お会計と領収書／手順「領収書」 |
| 熱があるとき休んでいい？ | 体調が悪いときの報告／手順1 |

**このテストは `answer.test.ts` に必ず入れ、FR-508 の基準（40問中36問以上で上位3件）を満たすまで、辞書・同じ意味の言葉・基準の値を調整する。** 見本の質問と同じ文を辞書や言いかえにそのまま入れて当てるのは禁止（ずるになるため）。

## ストアとリポジトリ

| ストア（`src/lib/store/`） | 中身 |
|---|---|
| `data.ts` | sites・people・manuals・distributions・readRecords・trainings・questions・notices・qrLinks |
| `ui.ts` | 現在のロール・ガイドの既読・最近見たもの・お気に入り・チャットのやり取り（表示用）・開いた手順（飛ばした手順の確認用）・案内役の位置と休み（`pet: { x, y, sleep }`） |

| リポジトリ（`src/lib/repo/`） | 主なメソッド |
|---|---|
| `manuals.ts` | `list(filter)`, `get(id)`, `createDraft(input)`, `saveDraft(id, patch)`, `requestReview(id)`, `publish(id)`, `returnToAuthor(id, reason)`, `revert(id, version)`, `diff(id, a, b)` |
| `steps.ts` | `addSteps(manualId, media[])`, `updateStep(...)`, `reorder(...)`, `remove(...)`, `saveShapes(stepId, shapes)` |
| `media.ts` | `putPhoto(file)`, `putVideo(file)`, `getUrl(ref)`, `estimate()` |
| `reading.ts` | `markStep(manualId, n)`, `complete(manualId)`, `submitQuiz(manualId, answers)` |
| `distribution.ts` | `distribute(input)`, `reach(manualId)`, `nudge(manualId)` |
| `training.ts` | `list()`, `create(input)`, `progress(id)` |
| `assistant.ts` | `ask(question)`, `feedback(questionId, solved)`, `report(questionId)` |
| `questions.ts` | `listUnanswered(scope)`, `addAlias(target, word)`, `resolve(id)` |
| `insights.ts` | `forSite(siteId)`, `forAll()` |
| `_scope.ts` | ロールごとの見える範囲（FR-003） |
| `_delay.ts` | 擬似的な待ち時間 |
| `pet.ts` | 案内役が画面ごとに話しかける言葉（データから作る。FR-803） |
| `search.ts` | ⌘K の横断検索（FR-901〜903） |
| `badges.ts` | メニューのバッジの数（未読・確認待ち・答えられなかった質問）。各画面の件数と同じ関数から取る |

---

# 8. デザイン要件

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

**「明るい現場の掲示板」と「案内役の小さな未来」。** 業務の画面は、白い面のタイルが並ぶダッシュボード（社内ポータル並みの作り込み）。案内役「つたえ」にまつわる面だけは、暗い青緑の地に格子が流れる近未来の世界観にする（スタートページ・ホームの聞く入口・聞く画面の見出し・小さなチャットの頭）。白い地に、写真が主役のカード。手順の番号は大きく、注意は黄色、コツは緑で、誰が見ても迷わない。働く人の手元のスマホで、片手で読める。**写真を暗くしない、写真の上に飾りを重ねない**（書き込みは利用者が描いたものだけ）。

## デザイントークン

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

| トークン | 用途 | 値（目安） |
|---|---|---|
| `--brand` | 主な操作（公開する・送る・確認しました）・選んでいるタブ | 深い青緑 #0F766E（白い文字とのコントラスト 4.5:1 以上を実測） |
| `--brand-soft` | 選んでいる行・メニューの今の項目 | #E3F3EF |
| `--brand-bright` | 飾り（輪・光・グラデーション）。文字には使わない | #14B8A6 |
| `--sun` | ロゴの点・強調の下地（上の文字は ink） | #FACC15 |
| `--bg` | 画面の地（タイルの下） | #F3F6F5 |
| 大きな数字の色 | 青緑・琥珀・青・赤 | #0F766E / #B45309 / #1D4ED8 / #BE123C |
| 案内役の世界 | 暗い地・光・目 | #041816（地）／ #5EEAD4（光・文字）／ #B6FFF3（目）。格子は #5EEAD4 の 8% |
| 影 | タイル／浮いたもの | `--shadow-tile`（ほぼ平ら）／ `--shadow-lift`（ホバー・引き出し） |
| `--ink` / `--ink-2` / `--ink-3` | 文字 | #1A1D1F / #3F4549 / #5F676C |
| `--surface` / `--surface-2` / `--line` | 地・一段沈んだ地・線 | #FFFFFF / #F5F6F4 / #E3E6E3 |
| `--caution` / `--caution-bg` | 注意 | #92400E / #FEF3C7 |
| `--tip` / `--tip-bg` | コツ | #166534 / #DCFCE7 |
| 書き込みの色 | 赤・黄・白 | #E11D48 / #FACC15 / #FFFFFF（すべて黒の細い縁取りつき） |
| 状態 | 下書き／確認待ち／公開中／差し戻し | 灰／黄／緑／赤（文字と印を併記） |

## タイポグラフィ

| 用途 | 指定 |
|---|---|
| 和文 | Noto Sans JP（ウェイト 400・500・700） |
| 数字 | 等幅の数字（`tabular-nums`） |
| 本文 | 16px・ウェイト500（スマホでも小さくしない） |
| 手順の見出し | 20px・700。手順の番号は 28px・700 の丸 |
| 補足 | 13.5px 以上・`--ink-3` 以上の濃さ |

**小さく細い文字にしない。** 現場の人は、立ったまま・手袋のまま・明るい場所で読む。

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

- 余白は 4px の倍数。タイルの角丸 20px、カードの角丸 14〜20px、ボタンの角丸 10〜14px
- 骨組み：デモ切替バー 44px（PCは上に固定）／左のメニュー 248px（PC）／上の帯 64px（少し透かす）／本文の最大幅 1440px（一覧系は 1120px）

### ホームの配置（PC 12列・間隔 20px）

| タイル | 幅（列） | 中身 |
|---|---|---|
| 今日のハイライト | 7 | 高さ 440px。表紙の写真を敷き（動画はマウスを乗せたときだけ）、下から白へのグラデーションに題名（36px）・カテゴリ・期限・手順の数・「読みはじめる」 |
| 大きな数字×4 | 5（2×2） | アイコン・ラベル・48px の数字＋単位・補足・「→ ○○」。研修だけ進み具合の輪 |
| 案内役の入口 | 5 | 暗い世界観の面。大きなつたえ（64px・輪つき）・「○○さん、何を探しますか？」・光る入力欄・よく聞かれている質問 |
| 届いたマニュアル | 7 | 写真つきの行×4（題名・手順の数・動画・期限・読んだ印） |
| 動画で見る手順 | 12 | 16:9 のカードを横に流す（再生の印・秒数・カテゴリ） |
| 研修／よく見られている／お知らせ | 4×3 | |
| 最近見たもの | 12 | |

スマホは1列で、ハイライト → 案内役の入口 → 大きな数字（2列） → ほかの順。
- 手順の写真は 4:3 の枠に収め、縦長の写真は枠の中で切らずに左右に余白を入れる（**写真を切り抜いて、書き込みが枠の外に出ることがないように**）
- 読む画面（スマホ）：上に手順の番号と見出し・写真は画面の幅いっぱい・下にめくるボタン（固定）
- 読む画面（PC）：左に手順の目次（幅 280px）・右に本文（最大幅 760px）
- 編集の画面（PC）：左に手順の目次（幅 260px）・中に編集（最大幅 720px）・右に基本情報（幅 320px）。幅 1100px 未満では右をタブにする
- 押せるものは 44×44px 以上

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

| コンポーネント | 仕様 |
|---|---|
| `ManualCard` | 表紙の写真（16:10）・カテゴリ・題名（2行まで）・手順の数と所要時間・読んだ印／新着／期限 |
| `StepView` | 番号の丸＋見出し・写真（書き込みを重ねる）か動画・説明・注意・コツ |
| `AnnotatedPhoto` | 写真の上に SVG で書き込みを重ねる。写真の大きさが変わっても位置がずれない（割合で持つ）。ぼかしは CSS の `backdrop-filter` ではなく、写真の該当部分を縮小して拡大した画像で塗る（どのブラウザでも同じに見えるように） |
| `AnnotateEditor` | 全画面。上に道具の帯、下に色と太さ。図形を選ぶと枠と取っ手。スマホでは2本指で拡大 |
| `VideoClip` | 区間だけを再生。下に区間のつまみ（編集のとき）／「もう一度」「全部見る」（読むとき） |
| `AnswerBubble` | 回答の文章・手順のカード（最大3）・「解決した／しなかった」・「マニュアルから探した答えです」 |
| `StepHitCard` | 手順の写真（小）・マニュアル名・手順の番号と見出し・説明の最初の2行・「この手順を開く」 |
| `ReachBar` | 読んだ・合格・まだ を1本の帯で（色と数字と文字） |
| `DemoBar` | 4章の仕様 |
| `Tile` / `StatTile` | タイル（白い面・角丸20px・ほぼ平らな影・見出しの左に色つきの四角いアイコン・右に「すべて見る」）／大きな数字のタイル（ホバーで2px浮く） |
| `CountUp` / `Ring` | 0から数え上がる数字（900ms・最終値の幅を先に取る）／進み具合の輪（1200msで描く） |
| `AgentOrb` | 案内役の見た目。暗いガラスの球（中心 #0B3B37→#041816、縁に #5EEAD4 の光）・光る目2つ・ゆっくり回る渦・まわりを回る黄色い星・広がる光の輪。状態は `idle`（まばたき・呼吸）／`thinking`（目が黄色・左右を見回す・星が速く回る）／`happy`（目が笑う）／`sleep`（目を閉じ「z」）。`look` で目線を動かす |
| `AgentPet` | 6.9 の右下の案内役（吹き出し・小さなチャット・ドラッグ・休ませる） |
| `HeroTile` / `AskTile` / `VideoThumb` | ホームのハイライト／案内役の入口／動画の手順のカード |
| `CommandPalette` / `NoticeDrawer` / `SideNav` / `TopBar` | SC-910 ／ SC-920 ／ 左のメニュー ／ 上の帯 |

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

- 保存・公開・送るは、押した直後に画面を変える（送信中を見せ、失敗したら戻して理由を出す）
- 読む画面の手順のめくりは、指の動きについてくる（離したら次へ、または戻る）
- チャットの回答は、文章 → 手順のカードの順に少しずらして出す（動きを減らす設定では同時に）
- 削除・並べ替えは5秒間「元に戻す」を出す

## モーション

- 動きは 150〜300ms（大きな出現は 520ms）。`prefers-reduced-motion` では動きを止める
- 出現の動きで要素を `opacity: 0` のまま止めないこと（`animation-fill-mode` に `both` を使わない）
- 使う動き：タイルの段差入場（初回のみ）・ホバーで2px浮く・数字の数え上げ・輪の描画・写真のゆっくりした拡大（ホバー）・案内役の呼吸／まばたき／渦／星／光の輪／跳ねる・吹き出しの出現（**吹き出しは不透明度を変えず、位置と大きさだけで出す**。途中で文字が薄くなるとコントラスト不足になる）・スタートページの1文字ずつの表示
- 動きの名前（keyframes）と値は `src/styles/index.css` に置き、案内役のものは `@layer components` に入れる（Tailwind の `hidden` などが効くように）

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

| ID | 要件 |
|---|---|
| A11Y-01 | 本文と背景のコントラスト比 4.5:1 以上（実測すること） |
| A11Y-02 | 注意・コツ・状態・既読を色だけで示さない |
| A11Y-03 | キーボードだけで、読む・テストに答える・質問する・手順を作って公開する、ができる |
| A11Y-04 | 写真には「手順N：見出し」を代替テキストに入れる。書き込みの文字も読み上げに含める |
| A11Y-05 | 動画には、手順の説明を代わりの文字として近くに出す（音声がなくても分かるように） |
| A11Y-06 | チャットの新しい回答を読み上げに知らせる（`aria-live="polite"`） |
| A11Y-07 | 文字サイズ200%でも、読む画面とチャットが最後まで使える |
| A11Y-08 | スタートページの自動の移動は、止める・飛ばすができること（WCAG 2.2.1） |
| A11Y-09 | 横に動く表は `role="region"`＋`tabIndex=0` で、キーボードでも動かせること |

## ライティング規約

- スタッフの画面はやさしい言葉（「確認しました」「分からないことを聞く」「続きから」）
- 作成者・本部の画面は短く（「公開を依頼」「配る」「声をかける」）
- **使わない言葉**：ナレッジ・コンテンツ・ドキュメント・アセット・ワークフロー・ステータス・ユーザー・タスク
- 回答の文章は「〜が近そうです」「〜が見つかりました」。**言い切らない**（検索で探した答えであるため）
- エラーは「何が起きたか＋どうすればいいか」（例：「動画が大きすぎます（45MB）。30MB以下の動画を選んでください」）

---

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

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

| レイヤ | 技術 | 備考 |
|---|---|---|
| ビルド | Vite 6 ／ TypeScript strict | 静的ファイルとして配信する |
| 画面 | React 19 ／ React Router 7（ブラウザ内で画面を切り替える方式） | |
| スタイリング | Tailwind CSS v4 + CSS Variables | トークンは CSS 変数で定義（チャンネル値） |
| UIコンポーネント | Radix UI（Dialog・Tabs・Popover・Toggle など必要なものだけ） | a11y要件を自前実装せずに満たす |
| 状態管理 | Zustand + persist ミドルウェア | localStorage に永続化 |
| 写真・動画の保存 | idb-keyval | IndexedDB の薄いラッパー |
| 写真の縮小 | ブラウザの canvas（`createImageBitmap` の `imageOrientation: 'from-image'` で向きを直す） | 追加のライブラリは入れない |
| 書き込み | SVG（自前） | 図形の描画と編集。ライブラリは入れない |
| ドラッグ | dnd-kit | 手順の並べ替え。**キーボード操作対応が必須のため** |
| フォーム | React Hook Form + Zod | 基本情報・確認テスト |
| グラフ | Recharts | 分析。動的に読み込む |
| QRコード | qrcode | 動的に読み込む |
| PDF | @react-pdf/renderer | 手順書の印刷・QRの印刷。**ブラウザ内で生成する**。動的に読み込む |
| 日付 | date-fns（ja locale） | |
| アイコン | lucide-react | |
| 配信 | Cloudflare Workers（静的アセット） | 全ルートを `index.html` に返す設定にする（`not_found_handling: "single-page-application"`） |
| テスト | Vitest / Playwright / axe-core（テストのときだけ jsdom・fake-indexeddb も使う） | |

**上記以外のライブラリを入れる前に必ず提案し、承認を得ること。** 特に、形態素解析の辞書（kuromoji など）は数MBあり、初期の読み込みを重くするので入れない（6.6 は2文字区切りと自前の辞書で作る）。

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

## ディレクトリ構成

```
/
├── CLAUDE.md                  # このファイル
├── wrangler.jsonc             # 公開の設定（静的アセット + SPA）
├── scripts/                   # 写真の生成（gen-photos.mjs）・WebP への変換（convert-photos.mjs）・目で確かめる一覧画像（contact-sheet.mjs）。アプリには含めない
├── public/
│   ├── photos/                # 手順の写真（幅 640 と 1600 の WebP）と CREDITS.json
│   ├── samples/               # 写真をまとめて追加の見本（ドリンクサーバー5枚）
│   ├── videos/                # 手順の動画（mp4・720p・各10MB以下）と表紙の1コマ、CREDITS.json
│   └── fonts/                 # PDF用の日本語フォント
└── src/
    ├── main.tsx  app.tsx      # ルーター・アプリシェル（デモ切替バー・左のメニュー・上の帯・下部の帯・案内役）
    ├── routes/
    │   ├── start.tsx  home.tsx  notices.tsx  qr.tsx
    │   ├── manuals/           # SC-010〜012
    │   ├── ask.tsx            # SC-020
    │   ├── training/          # SC-030
    │   ├── studio/            # SC-100〜120
    │   └── admin/             # SC-200〜210
    ├── components/
    │   ├── ui/                # Radix ベースのプリミティブ・Tile・StatTile・CountUp・Ring・Avatar
    │   ├── manual/            # ManualCard, StepView, AnnotatedPhoto, VideoClip, StepNav
    │   ├── editor/            # StepList, StepEditor, AnnotateEditor, BulkAdd, QuizEditor, VersionDiff
    │   ├── assistant/         # AgentOrb, AgentPet, AnswerBubble, StepHitCard, AliasSheet
    │   ├── shell/             # SideNav, TopBar, CommandPalette, NoticeDrawer, nav（メニューの定義とバッジ）
    │   ├── home/              # HeroTile, AskTile
    │   ├── reach/             # ReachBar, PeopleTable
    │   └── demo/              # DemoBar, GuideTour, ResetButton
    ├── lib/
    │   ├── types/  seed/  store/  repo/  media/
    │   ├── answer/            # normalize.ts, tokenize.ts, dictionary.ts, synonyms.ts, phrases.ts, search.ts, compose.ts, config.ts
    │   ├── calc/              # reach.ts（既読率）, training.ts, stale.ts（古くなった印）, diff.ts（版の違い）, numbering.ts（番号の書き込み）
    │   ├── pdf/               # manual-pdf.tsx, qr-sheet.tsx
    │   ├── i18n/terms.ts      # 現場の言葉
    │   └── utils/
    ├── styles/tokens.css
    └── e2e/                   # Playwright
```

## コーディング規約

- TypeScript strict。`any` 禁止。やむを得ない場合は `unknown` + 型ガード
- ファイル名は kebab-case、コンポーネントは PascalCase
- 1ファイル300行を超えたら分割を検討する
- **コンポーネントから Zustand ストアを直接参照しない。必ず `src/lib/repo/` 経由**
- **検索と回答の組み立ては `src/lib/answer/` の純粋な関数にし、コンポーネントに埋め込まない**（テスト対象にするため）
- 派生値をストアに保存しない
- 写真・動画の Blob をストア（localStorage）に入れない。必ず `src/lib/media/` 経由で IndexedDB に置き、ストアには ID だけを持つ
- コミットは1タスクごと。メッセージに要件IDを含める
  例：`feat(answer): 同じ意味の言葉で質問を広げる (FR-501)`

---

# 10. 非機能要件

| ID | 要件 | 目標値 |
|---|---|---|
| NFR-01 | LCP（スマホ・ホームと読む画面） | 2.5秒以下（ホームは同期で読み、待ち時間を挟まない。見本データの塊は最初から並行して読み込む。和文フォントは画面が出たあとに読み込む） |
| NFR-02 | INP（操作への応答） | 200ms以下 |
| NFR-03 | CLS | 0.1以下（写真の枠の大きさを先に確保する） |
| NFR-04 | 質問の検索そのものの処理時間（約180手順を探す） | 50ms以下（見せる待ち時間 600〜900ms とは別） |
| NFR-05 | 写真1枚の縮小と保存 | 1.5秒以下（iPhone 12 相当） |
| NFR-06 | 初期JSバンドルサイズ（gzip後） | 220KB以下（PDF・グラフ・QR・書き込みの編集・作成者と本部の画面は動的に読み込む） |
| NFR-07 | Lighthouse | Performance 90 / Accessibility 95 以上（スマホ・ホーム） |
| NFR-08 | 対応ブラウザ | Chrome / Safari / Edge 最新2バージョン、iOS Safari 16以降 |
| NFR-09 | ユーザー入力（題名・説明・質問・書き込みの文字）はサニタイズすること | — |
| NFR-10 | localStorage（5MB程度）と IndexedDB の残りが少ないとき、警告を出し、データを壊さないこと | — |
| NFR-11 | 画面幅 320px〜2560px のどこでも、横にはみ出さず崩れないこと | — |
| NFR-12 | 写真は一覧で幅640の版を遅延読み込み、手順の画面で幅1600の版を使うこと。動画は手順を開くまで読み込まないこと | — |

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

- **生成AIで文章の回答を作る場合**は、`repo/assistant.ts` の `ask` を「検索で見つけた手順（最大5件）をAIに渡し、それだけを根拠に答えさせる」形に差し替える。**マニュアルにないことを答えさせない指示と、根拠の手順を必ず返す形**にし、1回あたりの費用と1日の上限を決める
- 写真と動画はクラウドの保存場所に置き、見る権限をサーバー側で確かめる。動画は自動で圧縮・再生しやすい形に変換する
- ログイン、退職者の停止、店舗の異動の反映、操作の記録
- スタッフの読んだ記録・テストの点数は人事の評価に使われうる情報であり、誰が見られるかを決める必要がある
- 写真に写る人の顔・伝票の個人情報の扱い（撮影の同意・ぼかしの徹底）
- **本デモはデータをサーバーに送信しないため、これらの義務は発生しない。** ただし「デモである」旨は画面上に常時明示する

---

# 11. 実装タスク

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

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

### 0-1. 初期化
- [ ] Vite 6 / React 19 / TypeScript strict / React Router 7 / Tailwind v4 で初期化
- [ ] `npm run check` で 型チェック + テスト
- [ ] 9章のディレクトリ構成を作成
- [ ] `wrangler.jsonc` を置き、静的アセット配信と `not_found_handling: "single-page-application"` を設定

### 0-2. 型・シード・ストア
- [ ] 7章の型を定義
- [ ] シード（拠点・人・マニュアル30本の文章・確認テスト・配布・既読・研修・質問の履歴）を作り、件数をテストで確認
- [ ] ストア（persist）とリポジトリの土台、`_delay.ts`、`_scope.ts` (FR-003)
- [ ] `src/lib/media/`（IndexedDB の写真・動画、`estimate()`）

### 0-3. デザインシステム
- [ ] `tokens.css`（8章）とフォントの読み込み
- [ ] 共通部品：Button・Sheet・Dialog・Tabs・StatusBadge・ReachBar・Tile・StatTile・CountUp・Ring・Avatar
- [ ] デモ切替バー (FR-001, FR-004, FR-006)
- [ ] 骨組み：左のメニュー・上の帯・お知らせの引き出し・スマホの下の帯（SC-920）

## Phase 1 — 写真と動画をそろえる（1日）

- [ ] マニュアル30本・約180手順ぶんの写真（約170枚）と動画（8本）を用意する。**手順の見出しと写真の中身が合っていること**を1枚ずつ目で確かめる
- [ ] 写真を幅640と1600のWebPに、動画を720p・10MB以下のmp4と表紙の1コマにする。CREDITS.json に出典を記録
- [ ] シードの写真の6割以上に書き込み（矢印・丸・番号）を入れる。顔が写る写真にはぼかしを置く

## Phase 2 — 読む・確認テスト・QR（3日）

- [ ] ホーム SC-001（8章「ホームの配置」・ハイライト・大きな数字・動画で見る手順）(FR-101, FR-111〜FR-114)
- [ ] マニュアル一覧 SC-010 (FR-102)
- [ ] 書き込みつきの写真の表示 `AnnotatedPhoto`（割合の位置・ぼかし）(FR-104, FR-402, FR-405)
- [ ] 動画の区間の再生 `VideoClip` (FR-105)
- [ ] マニュアルを読む SC-011（スマホのめくり・PCの目次・続きから・確認しました）(FR-103, FR-106〜FR-108)
- [ ] 確認テスト SC-012 (FR-201〜FR-204)
- [ ] QRから開く SC-050
- [ ] 研修 SC-030・お知らせ SC-040
- [ ] お気に入りと最近見たもの (FR-110)

## Phase 3 — 質問チャット（3日）

- [ ] `answer/normalize.ts`・`tokenize.ts`（2文字区切り＋辞書）・`phrases.ts`
- [ ] `answer/dictionary.ts`（現場の言葉 150語以上）・`synonyms.ts`（60組以上）
- [ ] `answer/search.ts`（BM25・重み・同じマニュアル2件まで・確からしさ）
- [ ] `answer/compose.ts`（6.6 の文章の型。マニュアルにない文字を作らない）
- [ ] **`answer.test.ts`：見本の質問40問で FR-508（36問以上で上位3件）を満たすまで調整する**
- [ ] 質問チャット SC-020（候補・回答の吹き出し・手順のカード・解決した／しなかった・店長に知らせる）(FR-501〜FR-507)
- [ ] 案内役 `AgentOrb`（4つの表情・目線）と、右下の `AgentPet`（話しかける・小さなチャット・読んでいるマニュアルの優先・ドラッグ・休ませる）(FR-801〜FR-810)
- [ ] まとめて探す ⌘K（SC-910）(FR-901〜FR-903)

## Phase 4 — 作る・書き込み（4日）

- [ ] 作ったマニュアル SC-100
- [ ] マニュアルの編集 SC-101（基本情報・手順の追加/削除/複製/並べ替え・自動保存・プレビュー）(FR-301〜FR-303, FR-307, FR-308)
- [ ] 写真の追加と縮小・向きの補正 (FR-305)、写真をまとめて追加 SC-103 (FR-304)
- [ ] 動画の追加と区間の指定 (FR-306)
- [ ] 写真の書き込み SC-102（矢印・丸・四角・番号・文字・ぼかし・選択と移動・元に戻す）(FR-401〜FR-407)
- [ ] 確認テストの編集 SC-104 (FR-311)、言いかえ (FR-310)
- [ ] ひな形から作る SC-105 (FR-309)

## Phase 5 — 届ける・確かめる・分析（3日）

- [ ] 公開の流れ・確認待ち SC-200・差し戻し (FR-601)
- [ ] 版の履歴と違いの表示・戻す SC-203 (FR-602, FR-603)
- [ ] 配る SC-110・読み直しを求める (FR-604, FR-605)
- [ ] 読まれ具合 SC-111・声かけ (FR-606, FR-607)
- [ ] QRコードと印刷用PDF SC-112 (FR-608)、手順書のPDF (FR-109)
- [ ] 質問 SC-120（まとめ・言いかえを登録して検索し直す・マニュアルを作る）(FR-701〜FR-703)
- [ ] 全体の分析 SC-201 (FR-704, FR-705)、研修の管理 SC-202 (FR-610)、古くなった印 (FR-609)
- [ ] スタートページ SC-000（つたえの自己紹介3行・見本のカード・約5秒で自動で入る・止める／飛ばす）・ガイド (FR-005)・権限のない画面の案内 (FR-007)

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

### 6-1. 体験の総点検
- [ ] 4章「ロールを跨ぐ体験」の8つを、すべて手動で確認する
- [ ] 全画面を開き、**空の画面が1つもないこと**を確認する
- [ ] 全画面の空状態・読み込み中・エラー状態を確認する
- [ ] **全画面の文言を現場の言葉で読み直す。** 8章の「使わない言葉」が残っていないこと
- [ ] 容量が少ないときの警告 (NFR-10)

### 6-2. アクセシビリティ監査
- [ ] axe-core を全画面に実行し、Critical / Serious を0件に
- [ ] キーボードのみで、読む・テスト・質問・手順を作って公開する、を確認
- [ ] 本文のコントラスト比を実測して 4.5:1 以上を確認 (A11Y-01)
- [ ] 文字サイズ200%での確認 (A11Y-07)

### 6-3. パフォーマンス
- [ ] PDF・グラフ・QR・書き込みの編集・作成者と本部の画面を動的読み込みに切り出し、初期バンドルを220KB以下に (NFR-06)
- [ ] 質問の検索が50ms以下であることを実測 (NFR-04)
- [ ] Lighthouse（スマホ・ホーム）で Performance 90 / Accessibility 95 (NFR-07)
- [ ] 320px〜2560px で崩れないことを確認 (NFR-11)

### 6-4. テストと公開
- [ ] Playwright で 5章の主要フロー1〜4の E2E を実装・実行（写真の追加は見本の写真ファイルで）。体験3・5・6、権限のない画面、リセット、キーボードだけの操作、全画面の axe、320／375／1280／2560px のはみ出しも E2E にする
- [ ] Vitest：`src/lib/answer` `src/lib/calc` `src/lib/repo/_scope` のカバレッジ80%以上
- [ ] Cloudflare Workers へ公開（`npx wrangler deploy`）
- [ ] 公開URLで、直接開いた画面のURL（例 `/manuals/m-dishwasher/steps/4`・`/q/xxxx`）が 404 にならないことを確認する

---

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

> **工数配分の意図：** Phase 1 で写真と動画を先にそろえるのは、このアプリの見栄えと「聞けば返ってくる」の確かさが、どちらも中身（手順の写真と文章）で決まるため。中身が薄いと、検索をいくら調整しても良い答えは返らない。Phase 3 の質問チャットは、見本の質問40問のテストを先に書き、**数字で合格するまで調整する**。

---

# 12. 受入基準

1. 6章の優先度 P1 の要件がすべて実装されていること
2. 5章の主要フローが、最初から最後まで完走すること。**フローと4章の体験に出てくる機能は、6章の優先度が P2・P3 でも必須とする**
3. 4章「ロールを跨ぐ体験」の7つがすべて動作すること
4. ロールを切り替えると、一覧・ホーム・質問の答え・分析の表示範囲が変わること。スコープ判定が `src/lib/repo/_scope.ts` に集約されていること
5. **見本の質問40問のうち36問以上で、期待する手順が上位3件に入ること**（`answer.test.ts`）
6. 回答の文章に、マニュアルに書かれていない手順や数字が含まれないこと
7. スタッフに見えないマニュアルが、質問の回答に一度も出てこないこと
8. 写真の書き込みが、320px〜2560px のどの幅でもずれないこと。ぼかしの下の元の写真が見えないこと
9. 写真の追加（向きの補正・縮小）、動画の追加（区間の指定）、書き込み、公開、配る、読む、テスト、が1本の流れで動くこと
10. 全画面のいずれにも空の状態がなく、すべての手順に写真か動画があること
11. リロード後も操作結果（追加した写真・動画を含む）が保持され、「デモをリセット」で初期状態に戻ること
12. 手順書とQRのPDFが**実際にダウンロードでき、日本語と書き込みが正しく出ること**
13. axe-core で Critical / Serious の指摘が0件であること
14. Lighthouse の基準値を満たすこと
15. データアクセスがすべて `src/lib/repo/` を経由しており、**コンポーネントが Zustand ストアを直接参照していない**こと
16. スマホ（375px）で、読む・聞く・写真から手順を作る、が快適に使えること
17. 案内役「つたえ」がスタートページ以外のすべての画面の右下にいて、話しかけ・その場の質問・表情の変化・ドラッグ・休ませる、が動くこと。答えの下に「つたえがマニュアルから探した答えです」が出ること
18. スタートページで、つたえが「飲食店のマニュアル係」と名乗り、止めなければ約5秒でホームへ移ること
19. 動画の手順が16本以上のマニュアルにあり、ホームの「動画で見る手順」と一覧の「動画あり」で見つけられること

---

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

1. **仕様がこの文書にない場合は、実装せずに質問する。** 推測で作らない
2. **「聞けば返ってくる」の確かさと「空の画面を作らない」は削減対象外。** 速度を出すために削らない
3. スコープ外（3章 Won't have）は、思いついても実装しない。特に生成AIへの接続（費用ゼロの方針）
4. 「デモだから」を理由に品質を落とす判断はしない
5. コンポーネントからストアを直接触りたくなったら、それはリポジトリ層に足りないメソッドがあるということ
6. **迷ったら、ランチのピークが終わった14時、洗い場で食洗機が止まって困っている入社2週間のアルバイトを思い浮かべる。** その人がスマホで聞いて、10秒で答えにたどり着けるか
7. **答えをでっち上げない。** 見つからないときは「見つかりませんでした」と正直に返し、店長に知らせる道を出す。それがマニュアルを育てる入口になる
8. 写真を暗くしない、写真の上に利用者が描いたもの以外を重ねない
9. **案内役は見た目のキャラクター。** 答えはいつもマニュアルの検索から作る。つたえに、マニュアルにないことを言わせない


---

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

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

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

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

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

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