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

**版数** 2.5（DBレス構成・案内役『ともり』・「白と空色」のデザイン・画面とマニュアルの言語の切り替え・ロゴとアイコンを反映）／ **作成日** 2026-10-01 ／ **改訂** 2026-10-05 ／ **発行** ソウゾウ合同会社
**用途** 業種特化アプリの実演デモ ／ 介護事業所向け マニュアル・研修編

---

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

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

- **実装は「11. 実装タスク」の順に進める。フェーズを飛ばさない。**
- 各タスクの括弧内は要件ID。着手前に該当章を読むこと。
- **仕様がここに書かれていない場合は、推測で実装せず質問する。** ただし質問できない状況（自動で進めるよう指示されている場合）は、「判断に迷ったときのルール」に従って決め、決めたことを `docs/DECISIONS.md` に1行ずつ残す。
- スコープ外（3章 Won't have）は、思いついても実装しない。
- 「デモだから」を理由に品質を落とす判断はしない。
- **介護の現場の言葉で書く。** 画面の文言・項目名は、介護施設で働く人が毎日使っている言葉に合わせる（利用者さま・ご家族・ユニット・フロア・申し送り・介助・移乗・体位変換・排せつ・口腔ケア・ヒヤリハット・事故報告・夜勤・看護師オンコール・ケアプラン）。「ユーザー」「タスク」「ナレッジ」「コンテンツ」を画面に出さない。
- **利用者さまの尊厳を最優先にする。** 写真・例文・見本データのどこにも、利用者さまを笑いものにする表現、子ども扱いする呼び方、身体を晒す写真を入れない。

> **このアプリが選ばれる理由**
> 介護の手順は、間違えれば利用者さまのけがや命に関わる。それなのに現場は人の入れ替わりが激しく、外国人の職員も増え、夜勤は少ない人数で回している。さらに介護事業所には**法令で決まった研修（虐待防止・身体拘束の適正化・感染症・業務継続など）を年に決まった回数行い、その記録を残す義務**がある。
> SASAE は、**写真と動画の手順書（ふりがなつき）・夜中でも聞ける質問・義務研修の記録と書類**を1つにまとめ、「教える手間」「伝わらない不安」「指導の前に記録を探す手間」を同時に減らす。
> 手順書が読めない職員がいる、夜勤で聞いた質問に関係のない答えが返る、研修の記録が書類として出せない、のどれか1つでもあれば失敗とみなす。

---

## 目次

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

---

# 1. プロジェクト概要

## 背景と目的

特別養護老人ホーム・デイサービス・訪問介護などを運営する法人（職員50〜300名）では、次のことが毎日起きている。

- 新しい職員が入るたびに、先輩が移乗や入浴の介助を口で教える。教える人によってやり方が違い、腰を痛める・利用者さまにけがをさせる原因になる
- 外国人の職員（技能実習・特定技能）が増えたが、漢字の多い手順書が読めない。「分かりました」と言っても、本当に伝わったか分からない
- 夜勤は1フロア1〜2名。分からないことがあっても聞ける人がいない
- 虐待防止・身体拘束・感染症・業務継続（BCP）などの**義務の研修**を年に決まった回数行い、記録を残さなければならない。行政の指導（運営指導）の前に、紙の参加名簿を探し回る
- ヒヤリハット（事故になりかけた出来事）の報告は集まるが、手順書の見直しにつながらない

SASAE は、**写真と動画で手順を作る・ふりがなとやさしい日本語で伝える・夜中でも質問に答える・義務研修を計画して記録を書類にする・ヒヤリハットから手順を直す**を1つにまとめる。

| 目的 | 内容 |
|---|---|
| 業種特化の実装力の証明 | 介助の手順、感染対策、緊急時の対応、義務研修、ヒヤリハットといった介護の決まりごとを、そのまま画面にする |
| 「伝わる」の証明 | ふりがな・やさしい日本語・ことば帳で、日本語を勉強中の職員も手順を読める |
| 記録が書類になる証明 | 研修の実施記録・参加者・理解度の確認を、運営指導でそのまま出せる形のPDFにする |
| 安全の証明 | 夜勤で「息をしていない」「喉に詰まった」と聞かれたら、マニュアルを探す前に、まず緊急時の行動を出す |
| 横展開の資産化 | 法人・事業所・マニュアルをデータとして差し替えれば、障害福祉・医療・保育にも広げられる構造にする |

## プロダクト定義

| 項目 | 内容 |
|---|---|
| プロダクト名 | SASAE（ささえ）※仮称 |
| 一言定義 | 写真と動画の介護手順書、ふりがなとことば帳、義務研修の記録まで。介護事業所のためのマニュアル・研修アプリ |
| 提供形態 | レスポンシブWebアプリ。**フロントエンド完結（サーバー側の保存なし）** |
| 主戦場 | 現場のスマホ（読む・聞く・確かめる。夜勤の詰所でも）と、事務所のPC（作る・研修を計画する・記録を出す） |
| 想定利用者 | 介護職員（新人・外国人職員を含む）、ユニットリーダー・サービス提供責任者、施設長・研修担当 |
| 見本の法人 | 「社会福祉法人 やまぶき会」— 架空の法人。特別養護老人ホーム「やまぶき苑」（80床・4ユニット）、デイサービス「やまぶきデイ」、訪問介護「やまぶき訪問」、グループホーム「すみれ」。職員約150名（うち外国人職員18名） |

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

> **「だれが読んでも、同じ介助ができる。夜中でも、ひとりにしない。」**
>
> 手順の主役は写真と動画。文字には必ずふりがなを付けられ、難しい言葉は押せば意味が出る。分からないことは、いつでもチャットで聞ける。研修は、計画した時点から記録が残り、そのまま書類になる。

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

1. **触った瞬間に「うちの施設で使える」と分かる** — 空の画面が1つもなく、写真つきの介護の手順書が36本、研修の計画と記録が1年分入っている
2. **伝わる** — 「ふりがな」を押すと全部の漢字に読みが付き、「やさしい日本語」を押すと短い文に変わる。分からない言葉は押すと意味が出る
3. **聞けば返る・危ないときは止める** — 「おむつ交換の順番」と聞けば手順が返り、「息をしていない」と聞けば、マニュアルを探す前に緊急時の行動（119番・看護師への連絡）が出る
4. **記録が書類になる** — 義務研修の実施記録を、参加者と理解度の確認つきでPDFにできる
5. **ロールで見え方が変わる** — 職員は自分の事業所のもの、リーダーは自分のユニットの職員の進み具合、施設長は法人全体と義務研修の達成状況
6. **リセットできる** — 誰が触った後でも、初期状態に戻せる

---

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

## 基本方針

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

| 一般的な構成 | 本プロジェクト |
|---|---|
| PostgreSQL / Supabase | シードデータ（TypeScript）+ ブラウザ内ストア |
| ログイン | デモ用ロール切替（ワンクリック） |
| 写真・動画のクラウド保存 | ブラウザ内の IndexedDB |
| 生成AIによる回答 | **使わない。** ブラウザ内の検索で手順を探して返す（6.6） |
| 機械翻訳 | **使わない。** やさしい日本語とことば帳の訳は、シードとして人が書いたものを持つ（6.3） |
| ふりがなの自動付与（形態素解析） | **使わない。** 文の中に読みを `{漢字|かんじ}` の書式で持つ（7章）。作成者が書くときは、ことば帳にある言葉に自動で読みを付ける（FR-306） |
| PDF の生成（サーバー側） | ブラウザ内で生成し、実際にダウンロードできる |
| 通知 | 画面内のお知らせで再現 |

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

- **デモとして最適** — 訪問者は登録もログインもせずに、作る・読む・聞く・研修を記録する、を即座に触れる
- **費用ゼロ・情報を外に出さない** — 介護の現場では利用者さまの情報が飛び交う。質問も写真もブラウザから出さない
- **開発速度** — 認証・ファイル保存・AIの接続が不要になり、**伝わる工夫と記録の正確さに全時間を投下できる**
- **運用コストゼロ** — 静的配信のみ

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

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

```
[ 画面・コンポーネント ]
        ↓  呼ぶのはこの層だけ
[ src/lib/repo/*.ts ]        ← 全メソッドを async にしておく
        ↓                         ├ repo/assistant.ts → src/lib/answer/（緊急の判定・検索・回答の組み立て）
        ↓                         └ repo/training.ts  → src/lib/compliance/（義務研修の達成判定）
[ src/lib/store/*.ts ]       ← Zustand + persist（localStorage）
[ src/lib/media/*.ts ]       ← 写真・動画（IndexedDB）
        ↓
[ src/lib/seed/*.ts ]        ← 初期データ（「今日」を基準に1年分を作る）
```

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

**回答の差し替え口：** `repo/assistant.ts` の `ask(question)` は、デモでは `src/lib/answer/` の検索で回答を作る。本番で生成AIに切り替える場合も、**緊急の判定（6.6 ①）は必ずAIより先に、決まった言葉の一致で行う**（AIの判断に命に関わる案内を任せないため）。画面に渡す形（`Answer`）は変えない。

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

## 永続化の範囲

| 対象 | 挙動 |
|---|---|
| シードデータ | 初期投入。**研修の計画と記録は「今日」を基準に、今年度（4月〜翌3月）の分を作る**（今日より前は実施済み、後は予定） |
| 操作の結果（マニュアル・既読・理解度の確認・研修の記録・ヒヤリハット・質問・表示の設定） | localStorage に保存。**リロードしても保持される** |
| 写真 | シードの写真は `public/photos/` を参照。利用者が追加した写真だけを長辺1600px・JPEG品質0.82・1枚300KB以下にして **IndexedDB** に保存 |
| 動画 | シードの動画は `public/videos/` を参照。追加は1本30MB・60秒まで、IndexedDB に保存 |
| 表示の設定（ふりがな・やさしい日本語・文字の大きさ・ことばの訳の言語） | 人ごとに localStorage に保存 |
| リセット | デモ切替バーの「デモをリセット」で localStorage と IndexedDB を空にし、初期状態へ |

**擬似的な非同期を必ず入れること。** リポジトリの操作に 150〜400ms のディレイを挟み、読み込み中の状態を実際に見せる。質問への回答は 600〜900ms。**ただし緊急の判定に当たった質問は待たせずに即座に返す。** 一覧の絞り込み・ふりがなとやさしい日本語の切り替えは 100ms 以下。

---

# 3. スコープ定義

## 読む・聞く（職員）

| ID | 機能 | 優先度 |
|---|---|---|
| F-R01 | ホーム（届いたマニュアル・受ける研修・理解度の確認・質問の入口・自分の事業所でよく見られている手順） | Must |
| F-R02 | マニュアルを読む（手順ごとに写真か動画・説明・注意・コツ・「やってはいけないこと」） | Must |
| F-R03 | 表示の切り替え：ふりがな／やさしい日本語／文字の大きさ（3段階） | Must |
| F-R04 | ことば帳（介護の言葉を押すと、読み・意味・絵・英語／ベトナム語／インドネシア語／ミャンマー語の訳） | Must |
| F-R05 | 理解度の確認（マニュアルごとの選択式の問題。ふりがなつき） | Must |
| F-R06 | 質問チャット（緊急の判定 → 手順の検索。写真つきで返す） | Must |
| F-R07 | 緊急時の案内（119番・看護師オンコール・施設長への連絡の順と、その場でやること） | Must |
| F-R08 | QRコードから開く（リフトや特浴機に貼ったQRで、その手順を開く） | Must |
| F-R09 | 研修（受ける研修・受けた研修・理解度の確認の結果） | Must |
| F-R10 | ヒヤリハットの報告（場所・時間帯・内容・関係する手順を選んで送る） | Must |
| F-R11 | 申し送りの「この手順を見てください」（リーダーから届いた手順） | Should |

## 作る（リーダー）

| ID | 機能 | 優先度 |
|---|---|---|
| F-E01 | マニュアルの作成（題名・分類・対象の事業所・表紙・所要時間・必要なもの・やってはいけないこと） | Must |
| F-E02 | 手順の編集（追加・並べ替え・削除・複製。写真か動画・説明・注意・コツ） | Must |
| F-E03 | 写真の書き込み（矢印・丸・番号・文字・ぼかし）。**利用者さまの顔は必ずぼかす**ための注意を出す | Must |
| F-E04 | 写真をまとめて追加すると1枚1手順 | Must |
| F-E05 | 動画の追加と区間の指定 | Must |
| F-E06 | やさしい日本語の文を手順ごとに書く。書き方の手引き（1文を短く・敬語を減らす・カタカナ語を避ける）を横に出す | Must |
| F-E07 | ふりがなの確認（ことば帳にある言葉には自動で読みが付く。付かなかった漢字を一覧で見せ、読みを書き足せる） | Must |
| F-E08 | 理解度の確認の問題の作成 | Must |
| F-E09 | 言いかえの登録（質問で当たってほしい言葉） | Must |
| F-E10 | 下書き → 確認待ち → 公開、版の履歴 | Must |

## 研修と記録（施設長・研修担当）

| ID | 機能 | 優先度 |
|---|---|---|
| F-T01 | 年間の研修計画（義務研修の種類ごとに、年に何回・いつ・どの事業所で） | Must |
| F-T02 | 研修の実施（日時・場所・講師・内容・使ったマニュアル・参加者の出欠・理解度の確認） | Must |
| F-T03 | **義務研修の達成状況**（事業所×研修の種類で、必要な回数に対して何回できたか・新しく入った職員が受けたか） | Must |
| F-T04 | 研修に出られなかった職員への、あとからの受講（マニュアルを読んで理解度の確認に合格したら「受講済み（個別）」） | Must |
| F-T05 | **研修の実施記録のPDF**（運営指導でそのまま出せる形：研修名・日時・場所・講師・内容・参加者名簿・理解度の確認の結果） | Must |
| F-T06 | 職員ごとの研修の履歴（受けた研修・日付・結果） | Must |
| F-T07 | 新人の受け入れ研修（入職から30日で受けるマニュアルの組み合わせ） | Must |

## ヒヤリハットと改善（リーダー・施設長）

| ID | 機能 | 優先度 |
|---|---|---|
| F-H01 | ヒヤリハットの一覧（場所・時間帯・種類・関係する手順） | Must |
| F-H02 | 傾向（種類別・時間帯別・場所別。夜勤の転倒が多い、など） | Must |
| F-H03 | 「この手順を見直す」（関係する手順の編集へ。見直した内容と理由を記録） | Must |
| F-H04 | 見直した手順を、関係する職員に「読み直してください」と届ける | Must |

## 質問と分析

| ID | 機能 | 優先度 |
|---|---|---|
| F-Q01 | 質問の記録（質問・返した手順・解決した／しなかった・時間帯） | Must |
| F-Q02 | 答えられなかった質問の一覧と、言いかえの登録・マニュアルの作成 | Must |
| F-Q03 | 分析（既読率・確認の合格率・よく見られる手順・夜勤によく聞かれる質問） | Must |

## 共通・基盤

| ID | 機能 | 優先度 |
|---|---|---|
| F-S01 | デモ切替バー（職員／リーダー／施設長、職員は「日本人の新人」「外国人の職員」を選べる・リセット） | Must |
| F-S02 | 画面内のお知らせ | Must |
| F-S03 | はじめての人への案内（3ステップ） | Must |
| F-S04 | スタートページ | Must |
| F-S05 | 言語の切り替え（日本語・英語・ベトナム語・インドネシア語。画面の言葉と、マニュアルの中身の両方） | Must |

## 対象外（Won't have）

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

- 生成AI・機械翻訳・自動のふりがな付与（形態素解析）など、外部のサービスや大きな辞書の利用
- 介護記録・ケアプラン・請求（国保連への請求）・シフト・勤怠の機能（別のシステムの範囲）
- 利用者さまの個人情報の管理（このアプリは職員向けの手順と研修のみ）
- 外部の研修（認知症介護基礎研修・喀痰吸引等研修などの受講そのもの）の提供。修了の記録を付けるだけ
- 動画の編集・字幕の自動作成・音声の読み上げ
- 複数の法人の管理（1法人のみ）
- 権限の細かい設定画面（ロールは3つで固定）

---

# 4. ロールとデモ切替

## ロール定義

| ロール | 見本の人 | できること | 見える範囲 |
|---|---|---|---|
| 職員（日本人の新人） | 佐藤 ひなた（やまぶき苑 2階ひまわりユニット・入職3週間） | 読む・聞く・理解度の確認・研修・ヒヤリハットの報告 | 自分の事業所と法人共通のマニュアル。自分の記録 |
| 職員（外国人の職員） | グエン・ティ・ラン（やまぶき苑 2階ひまわりユニット・特定技能・入職2か月・ベトナム出身） | 同上。**初期の表示は「ふりがな あり・やさしい日本語 あり・ことばの訳 ベトナム語」** | 同上 |
| リーダー | 山口 健太（やまぶき苑 2階ひまわりユニットのユニットリーダー） | 上のすべて＋自分の事業所のマニュアルを作る・配る・ユニットの職員の進み具合・ヒヤリハットの見直し・研修の実施の記録 | 自分の事業所。進み具合は自分のユニットの職員 |
| 施設長 | 石田 京子（やまぶき苑 施設長・法人の研修委員長） | すべて＋年間の研修計画・義務研修の達成状況・研修の記録のPDF・公開の確認 | 法人全体 |

**見える範囲の判定は `src/lib/repo/_scope.ts` の1か所に集約する。** 職員が質問したときも、職員に見えないマニュアル（他の事業所だけのもの・下書き）を回答の根拠にしてはならない。

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

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

| 要素 | 内容 |
|---|---|
| 左 | 「デモ」の印と「これはデモです。入力した内容は、このブラウザの中にだけ保存されます」 |
| 中央 | 見え方の切り替え：**職員（新人） ／ 職員（外国人） ／ リーダー ／ 施設長** |
| 右 | 「使い方」・「デモをリセット」（確認ダイアログあり） |

スマホの幅では、中央を短い表記（新人・外国人・リーダー・施設長）にし、右はアイコンだけにする。

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

1. **伝わる** — 職員（外国人）で「ベッドから車いすへの移乗」を開く → ふりがな・やさしい日本語で表示されている → 「移乗」を押すと、ことば帳に「いじょう：ベッドから車いすなどへ移ること／Vietnamese: Di chuyển…」が出る → 「ふつうの日本語」に切り替えると、元の文に戻る
2. **聞いて返る** — 職員（新人）で「おむつ交換の順番」と聞く → 「おむつ交換（ベッド上）」の手順が写真つきで返る
3. **危ないときは止める** — 職員で「利用者さんが息をしてない」と聞く → **待たずに**赤い緊急の案内（①大きな声で人を呼ぶ ②119番 ③看護師オンコールに電話 ④その場の手順「呼吸が止まっているとき」）が出る。マニュアルの検索結果はその下に出す
4. **ヒヤリハットから手順を直す** — 職員（新人）で「夜間、トイレ誘導の途中でふらついた」をヒヤリハットとして報告し、関係する手順に「トイレ誘導（夜間）」を選ぶ → リーダーの一覧に届く → 「この手順を見直す」→ 手順3に注意「立ち上がる前に、足元のセンサーマットを確認」を足して公開を依頼 → 施設長で公開 → ユニットの職員に「読み直してください」が届く
5. **研修を記録して書類にする** — 施設長で年間計画の「感染症の予防（10月）」を開く → リーダーで実施の記録（参加者の出欠・使ったマニュアル「嘔吐物の処理」）→ 参加した職員に理解度の確認が届く → 職員（外国人）で確認に合格 → 施設長で研修の実施記録のPDFを出す（参加者名簿と確認の結果つき）→ 義務研修の達成状況で「感染症 やまぶき苑 1/2回」が「2/2回」になる
6. **欠席者があとから受ける** — 研修を欠席した職員に「あとから受講」が届く → マニュアルを読んで確認に合格 → 記録に「受講済み（個別・日付）」で残り、PDFの名簿にも出る
7. **見える範囲が違う** — 訪問介護だけのマニュアル「訪問先での鍵の管理」は、やまぶき苑の職員には一覧にも質問の答えにも出ない

---

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

## スタート

| ID | 画面 | パス | 内容 |
|---|---|---|---|
| SC-000 | スタートページ | `/` | **LP にしない。** 白と空色の明るい画面に案内役『ともり』を大きく出し、3行（自己紹介・何をするか・ご案内します）を1文字ずつ話す。話が進むと下の施設の窓に空色の灯りがひとつずつともり、PCでは見本のカード（写真の手順・動画・緊急の案内・研修の達成）が浮かぶ。**約5秒で自動で職員のホームへ入る。**「止める」「入る」「飛ばして入る」と、別の見え方（外国人の職員／リーダー／施設長）で入るボタン。ガイド（FR-005）はスタートページでは出さず、アプリに入ってから出す |

## 職員

| ID | 画面 | パス | 内容 |
|---|---|---|---|
| SC-001 | ホーム | `/home` | ダッシュボード型。1段目：**ともりの入口**（空色の面・あいさつ・大きな入力欄・よく聞かれている質問）と**緊急時の案内**（赤い面・4つの場面へ直接）。2段目：**数字の帯**（読んでいない・受け入れ研修 7/12 の輪・確認の残り・次の研修。数字は0から数え上がる）。届いたマニュアル（写真のカードを横に並べ、期限まであと何日）・**動画で見る介助**（PCではマウスを乗せると音なしで流れる）・研修のこれから（灯りの点の時系列）・続きから読む・自分の事業所でよく見られている手順 |
| SC-010 | マニュアル一覧 | `/manuals` | 分類のタブ（介助／感染対策／緊急時／記録・報告／接遇・認知症ケア／機器／事業所の決まり）・写真つきカード・絞り込み（事業所・読んでいない・研修で使う） |
| SC-011 | マニュアルを読む | `/manuals/:id`・`/manuals/:id/steps/:n` | 表紙（題名・所要時間・必要なもの・**やってはいけないこと**（赤い枠））→ 手順ごとの画面（写真か動画・番号・見出し・説明・注意・コツ）。上に「ふりがな」「やさしい」「文字の大きさ」の切り替え。言葉を押すとことば帳 |
| SC-012 | 理解度の確認 | `/manuals/:id/check` | 1問ずつ・選択式・ふりがなつき・答えるとすぐ正誤と解説（根拠の手順へ） |
| SC-013 | ことば帳 | `/words`・`/words/:id` | 介護の言葉の一覧（50音順・分類）・検索。1語の画面：読み・意味（やさしい日本語）・絵・訳（4言語）・この言葉が出てくる手順 |
| SC-020 | 質問チャット | `/ask` | 上に空色の見出しとともり（考え中・見つかった・緊急で表情が変わる）。質問の入力・やり取り（回答の吹き出しにはともりの顔）・回答（緊急の案内／手順のカード最大3件）・解決した／しなかった・よく聞かれる質問 |
| SC-021 | 緊急時の案内 | `/emergency` | 状況のボタン（呼吸がない・反応がない／喉に詰まった／転倒・頭を打った／大量の出血／火事・地震）→ その場でやることを大きな字で順に・連絡先（119・看護師オンコール・施設長。デモでは番号を画面に出すだけ） |
| SC-030 | 研修 | `/training` | 受ける研修（日時・場所）・あとから受講が必要なもの・受けた研修の一覧と結果 |
| SC-040 | ヒヤリハットの報告 | `/hiyari/new` | いつ（日時・時間帯）・どこ（居室・トイレ・浴室・食堂・廊下・屋外）・種類（転倒・転落／誤嚥・むせ／誤薬／皮膚のけが／離設／その他）・何があったか（200文字・やさしい日本語の例つき）・関係する手順（検索して選ぶ・任意）・利用者さまの名前は**入れない**（「Aさま」など仮の呼び方を案内） |
| SC-050 | お知らせ | `/notices` | 配られた・研修・読み直し・確認 |
| SC-060 | QRから開く | `/q/:code` | 該当のマニュアルの手順へ |

スマホの下部の帯：**ホーム ／ マニュアル ／ 聞く ／ 研修 ／ 緊急**（「緊急」は赤い印で常に右端）

## リーダー

| ID | 画面 | パス | 内容 |
|---|---|---|---|
| SC-100 | 作ったマニュアル | `/studio` | 自分の事業所のマニュアル（下書き・確認待ち・公開中・差し戻し）・見直しの時期・「新しく作る」 |
| SC-101 | マニュアルの編集 | `/studio/manuals/:id` | 左：手順の目次。中：手順の編集（写真か動画・見出し・説明・**やさしい日本語の文**・注意・コツ）。右：基本情報・やってはいけないこと・言いかえ・理解度の確認・ふりがなの確認・公開 |
| SC-102 | 写真の書き込み | `/studio/manuals/:id/steps/:n/annotate` | 矢印・丸・番号・文字・ぼかし。**初めて開いたときに「利用者さまの顔・名札・ベッドの名前の札は、必ずぼかしてください」を出す** |
| SC-103 | ふりがなの確認 | `/studio/manuals/:id/ruby`（シート） | 読みが付いていない漢字の一覧と、その文。読みを書き足す（その場で全文に反映）・ことば帳に足す |
| SC-110 | 配る・読まれ具合 | `/studio/manuals/:id/reach` | 配る（事業所・ユニット・個人・期限）・読んだ／合格／まだ・声をかける |
| SC-120 | ヒヤリハット | `/studio/hiyari` | 一覧（新しい順・未対応を上に）・傾向（種類・時間帯・場所のグラフ）・1件の画面（内容・関係する手順・「この手順を見直す」・対応のメモ・対応済み） |
| SC-130 | 研修の実施の記録 | `/studio/sessions/:id` | 日時・場所・講師・内容（200文字）・使ったマニュアル・参加者（ユニット・事業所の職員を一覧から出欠を付ける）・保存すると参加者に理解度の確認が届く |
| SC-140 | ユニットの進み具合 | `/studio/team` | 職員×（新人の受け入れ研修・今年の義務研修・届いたマニュアル）の表。まだのところに印 |
| SC-150 | 質問 | `/studio/questions` | 答えられなかった・解決しなかった・すべて。言いかえを登録・マニュアルを作る |

## 施設長

| ID | 画面 | パス | 内容 |
|---|---|---|---|
| SC-200 | 義務研修の達成状況 | `/admin/compliance` | 表：事業所（行）×研修の種類（列）で「実施 1/2回」「新入職員 3/4名」。足りないところを赤く。今年度の残りの月数。各マスを押すとその研修の記録へ |
| SC-201 | 年間の研修計画 | `/admin/plan` | 4月〜3月の横長の予定表。研修の種類ごとに予定と実施済み。予定の追加・日付の変更 |
| SC-202 | 研修の記録 | `/admin/sessions` | 実施した研修の一覧（日付・研修の種類・事業所・参加者数・確認の合格率）→ 1件の画面とPDF |
| SC-203 | 研修の実施記録のPDF | `/admin/sessions/:id/pdf` | 6.7 の形。プレビューとダウンロード。複数を選んでまとめて1つのPDFにもできる |
| SC-204 | 職員の研修の履歴 | `/admin/staff`・`/admin/staff/:id` | 職員の一覧（事業所・入職日・在留資格の種別（日本人／技能実習／特定技能／EPA）・今年の義務研修の受講数）→ 1人の履歴 |
| SC-205 | 確認待ち | `/admin/review` | 公開を依頼されたマニュアル・変更点（前の版との違い）・公開／差し戻し |
| SC-206 | 全体の分析 | `/admin/insights` | 既読率・合格率（事業所別）・よく見られる手順・夜勤（22時〜6時）によく聞かれる質問・答えられなかった質問・ヒヤリハットの推移（月別）と、見直した手順の数 |

## 主要フロー

### フロー1：外国人の職員が手順を読む

```
職員（外国人）：ホーム → 届いたマニュアル「ベッドから車いすへの移乗（全介助）」
  → 表紙：やってはいけないこと「ひとりで無理に持ち上げない」（ふりがなつき）
  → 手順2：「ブレーキを かけます。フットサポートを 上げます。」（やさしい日本語）
  → 「フットサポート」を押す → ことば帳：足をのせる台／Vietnamese: bàn để chân …／絵
  → 最後まで読む → 理解度の確認（3問・ふりがなつき）→ 合格
リーダー：ユニットの進み具合でグエンさんが「合格」
```

### フロー2：夜勤で聞く

```
職員（新人）：23:40 「むせこんで顔が赤い」と聞く
  → 緊急の判定に当たる（誤嚥・窒息）→ 赤い案内：①食べるのを止める ②前かがみにして背中をたたく ③顔色・呼吸が悪くなったら119番 ④看護師オンコールへ
  → その下に「誤嚥・窒息のとき」「食事の介助」の手順カード
職員（新人）：01:10 「体位変換って何時間ごと？」と聞く
  → 「『体位変換』の手順1『時間の目安』が近そうです。」＋手順のカード
```

### フロー3：ヒヤリハットから手順を直す（4章 体験4）

### フロー4：義務研修を実施して書類にする（4章 体験5・6）

```
施設長：年間の研修計画 → 10月「感染症の予防」（やまぶき苑・2回目）
リーダー：研修の実施の記録 → 日時・場所・講師（看護師 森）・内容 → 使ったマニュアル「嘔吐物の処理」「手洗いの手順」
  → 参加者：2階ひまわりユニット8名のうち7名に出席の印 → 保存
職員：理解度の確認が届く → 合格
施設長：研修の記録 → この回 → PDF：研修名・日時・場所・講師・内容・参加者名簿（氏名・事業所・出欠・確認の結果・日付）・欠席者のあとからの受講の記録
施設長：義務研修の達成状況 → 「感染症の予防」やまぶき苑 2/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 | ホームに、届いて読んでいないマニュアル・受ける研修・理解度の確認の残り・新人の受け入れ研修の進み具合・よく見られている手順・緊急時の案内へのボタンを出すこと | P1 |
| FR-102 | マニュアル一覧で、分類・事業所・「読んでいない」・「研修で使う」で絞り込めること | P1 |
| FR-103 | マニュアルの表紙に「やってはいけないこと」（最大5項目）を赤い枠で出すこと。色だけでなく「してはいけません」の文字と印を添えること | P1 |
| FR-104 | 手順の画面：スマホは横にめくる、PCは左に目次。番号と全体の数（3／8）を常に出すこと | P1 |
| FR-105 | 写真は書き込みを重ねて表示し、押すと全画面で拡大できること。動画は指定の区間だけを再生すること | P1 |
| FR-106 | 最後の手順まで見たら「確認しました」。どこまで読んだかを覚え「続きから」を出すこと | P1 |
| FR-107 | 手順の画面の上に、ふりがな・やさしい・文字の大きさ（標準／大／特大）の切り替えを常に出すこと（6.3） | P1 |
| FR-108 | マニュアル全体をA4のPDFで保存できること（ふりがな・やさしい日本語の設定どおりに出す） | P2 |

## 6.3 ふりがな・やさしい日本語・ことば帳（`src/lib/reading/`）

**このアプリの見せ場。** 自動の解析はせず、データとして持った読みと文を使う。

### 文の持ち方

- 手順の文（見出し・説明・注意・コツ・やってはいけないこと・問題・選択肢）は、**読みを `{漢字|かんじ}` の書式で埋め込んだ文字列**で持つ。例：`{車|くるま}いすの{ブレーキ|}を かけます` のように、読みの要らないところはそのまま書く
- 手順ごとに、ふつうの文（`body`）と**やさしい日本語の文（`bodyEasy`）**を持つ。やさしい日本語の文が無い手順は、ふつうの文を出す
- 文の中の**ことば帳にある言葉**は `[[移乗]]` の書式で印を付ける。読むときは押せる言葉として出す

### 表示

| ID | 要件 | 優先度 |
|---|---|---|
| FR-201 | 「ふりがな」を入れると、`{漢字|かんじ}` を HTML の `<ruby>` で表示すること。切ると漢字だけを出すこと。切り替えは 100ms 以下で、読んでいる位置がずれないこと | P1 |
| FR-202 | 「やさしい」を入れると、`bodyEasy` があれば差し替えること。やさしい日本語の文のある手順には、手順の番号の横に小さな「やさしい」の印を出すこと | P1 |
| FR-203 | 文字の大きさ（標準 16px／大 19px／特大 22px）。行の間隔も合わせて広げること | P1 |
| FR-204 | `[[言葉]]` は点線の下線つきで出し、押すと下から「ことば帳」のシート（読み・意味・絵・訳）を出すこと。閉じたら元の位置に戻ること | P1 |
| FR-205 | ことばの訳の言語は、英語・ベトナム語・インドネシア語・ミャンマー語から選べること（人ごとの設定） | P1 |
| FR-206 | ことば帳の画面で、50音順・分類（体の部位／介助／福祉用具／病気・症状／感染対策／記録）・検索で探せること。1語の画面に、その言葉が出てくる手順の一覧を出すこと | P1 |

### 画面の言語（`src/lib/i18n/`）

外国人の職員が、**画面の操作でも、マニュアルの中身でも迷わない**ようにする。画面の言葉もマニュアルの中身も選んだ言語で出し、マニュアルの読む画面では元の日本語（ふりがな・ことば帳つき）を下に小さく添える（日本語も覚えられるように。「日本語も見る」で消せる）。

| ID | 要件 | 優先度 |
|---|---|---|
| FR-207 | 上の帯に地球の印の「画面の言語」を置き、日本語・English・Tiếng Việt・Bahasa Indonesia から選べること（職員のロールで出す）。人ごとの設定として覚えること。外国人の職員の初期値はベトナム語 | P1 |
| FR-208 | 職員の画面（ホーム・マニュアルの一覧と読む画面の枠・理解度の確認・聞く・ことば帳・研修・お知らせ・ヒヤリハットの報告・緊急の案内・案内役の言葉）の文言を、選んだ言語で出すこと | P1 |
| FR-209 | メニューと見出しは「訳」を大きく、その下に元の日本語を小さく出すこと（職員が日本語の言葉も覚えられるように）。小さな日本語も本文と同じコントラストにすること | P1 |
| FR-210 | 緊急の案内は、日本語の下に訳を出すこと。「だれか来てください」のように周りの日本人に向けて言う言葉は日本語のまま出し、訳はその説明として添えること | P1 |
| FR-211 | 画面の言語を日本語以外にすると、ことばの訳の言語も同じ言語に合わせること | P2 |
| FR-212 | 訳の本体は、日本語以外を選んだときだけ、その言語の分だけ読み込むこと（日本語の人の初期の読み込みを重くしない） | P1 |
| FR-213 | マニュアルの中身（題名・必要なもの・やってはいけないこと・手順の見出しと説明（やさしい日本語の版も）・注意・コツ・写真の書き込みの文字・理解度の確認の問題と選択肢と解説）を、選んだ言語で出すこと。ことば帳の意味・研修の名前・お知らせ・質問の答えの文と手順のカードも同じ | P1 |
| FR-214 | 読む画面と確認の画面では、訳の下に元の日本語を小さく出すこと（「日本語も見る」で切り替え）。手順の訳の下に「訳は参考です。分からないときは、日本語の文とリーダーに確かめてください。」を出すこと | P1 |
| FR-215 | 日付は、選んだ言語の書き方で出すこと（例：Oct 5, 2026／5 thg 10, 2026） | P2 |
| FR-216 | スタートページ（ともりの自己紹介・見本のカード）・はじめての人への案内・見つからない画面・デモ切替バー・タブの題名・読み上げ用の文字（aria-label・代わりの文字）も、選んだ言語で出すこと。`<html lang>` も画面の言語に合わせ、元の日本語の部分には `lang="ja"` を付けること | P1 |
| FR-217 | ことば帳の一覧は、日本語以外の画面では訳を大きく、日本語の言葉と読みを下に出すこと | P2 |

- 画面の言葉の訳は `src/lib/i18n/ui-dict.ts`、マニュアルなどの中身の訳は `src/lib/i18n/content-{en,vi,id}.json` に、**シードとして持つ**（日本語の文（ふりがな・印を外したもの）をそのまま鍵にする）。画面で機械翻訳はしない（外部のサービスを使わない）。訳のない文は日本語のまま出す（推測で埋めない）
- 中身の訳は、実装時に Claude が用意した（`scripts/extract-content.ts` で文を集め、`scripts/build-content.mjs` でまとめる）。**時間・回数・量などの数字が訳で消えていないことをテストで確かめる**（`content.test.ts`）。本番では、母語話者の確認を通してから使うこと
- **ミャンマー語は画面の言葉には用意しない**（訳の確かさに自信が持てないため）。ことば帳の訳だけで選べる
- 質問の入力は日本語（ひらがなでも）で探す。ただし**緊急の言葉だけは英語・ベトナム語・インドネシア語でも当たる**（6.6 ①）

### やさしい日本語の決まり（シードと作成の手引きに使う）

- 1文は短く（目安 30文字まで）。1文に1つのこと
- 「〜してください」は「〜します」に。尊敬語・謙譲語を減らす
- カタカナ語・略語を避ける（避けられない言葉はことば帳に入れる）
- 数字は算用数字。時間は「2時間ごと」のように具体的に
- 文と文の間に空白を入れて区切りを見せる

### 訳の正確さ

- **ことば帳の訳はシードとして人が書いたもの**。ベトナム語・インドネシア語・ミャンマー語の訳は、実装時に用意し、`public/words/SOURCES.md` に「どう用意したか（参考にした辞書・資料）」を記録する
- **訳に自信のない言葉は訳を空にし、「訳はまだありません」と出す**（間違った訳を出すほうが危ない）。12章の基準は「ことば帳の80語のうち、英語は全語・他の3言語は60語以上」

## 6.4 理解度の確認

| ID | 要件 | 優先度 |
|---|---|---|
| FR-301 | マニュアルごとに2〜5問。選択肢は2〜4つ。ふりがな・やさしい日本語の設定に従って表示すること | P1 |
| FR-302 | 答えるとすぐに正誤と解説（根拠の手順へのリンク）を出すこと | P1 |
| FR-303 | 合格の基準は80%。不合格は間違えた問題の手順を示し、やり直せること | P1 |
| FR-304 | 研修の理解度の確認として受けた結果は、その研修の記録に結び付けること（6.7） | P1 |

## 6.5 作る

| ID | 要件 | 優先度 |
|---|---|---|
| FR-401 | マニュアルの基本情報：題名（40文字）・分類・対象（法人共通／事業所・ユニット）・表紙・所要時間・必要なもの・やってはいけないこと（最大5・各40文字）・タグ | P1 |
| FR-402 | 手順：見出し（30文字・必須）・写真か動画・説明（300文字）・やさしい日本語の文（300文字・任意）・注意（100文字）・コツ（100文字） | P1 |
| FR-403 | 手順の追加・削除・複製・並べ替え（ドラッグとキーボード）。削除は5秒間「元に戻す」 | P1 |
| FR-404 | 写真の追加（長辺1600pxに縮小・向きの補正）・まとめて追加・動画の追加と区間の指定 | P1 |
| FR-405 | 写真の書き込み：矢印・丸・四角・番号・文字・ぼかし。書き込みは図形のデータとして別に持ち、写真の大きさに対する割合で位置を持つこと。ぼかしは元の写真が透けないこと | P1 |
| FR-406 | **ふりがなの自動付与（ことば帳の範囲）**：作成者が普通の文を書くと、ことば帳と読みの辞書（`reading/dictionary.ts`、介護の言葉と常用の言葉 600語以上）にある言葉に `{…|…}` を自動で付けること。付かなかった漢字を「ふりがなの確認」に一覧で出し、作成者が読みを書き足せること | P1 |
| FR-407 | やさしい日本語の文を書く欄の横に、6.3 の決まりを短く出し、1文が30文字を超えた文に印を付けること | P1 |
| FR-408 | 言いかえを10個まで登録できること（マニュアル・手順ごと） | P1 |
| FR-409 | 下書き → 確認待ち → 公開／差し戻し。公開ごとに版を残し、前の版との違いを見られること。前の版に戻せること | P1 |
| FR-410 | 入力をやめて1秒後に自動で保存すること | P1 |
| FR-411 | 「プレビュー」で、職員（新人）・職員（外国人）の両方の見え方を切り替えて見られること | P1 |

## 6.6 質問チャットと緊急の案内（費用ゼロ）

### ① 緊急の判定（`src/lib/answer/emergency.ts`）— 検索より先に、必ず行う

| 状況 | 当たる言葉の例（正規化した後に含むか） |
|---|---|
| 呼吸がない・反応がない | 息をしていない／息してない／呼吸がない／呼吸してない／反応がない／意識がない／呼んでも起きない／脈がない |
| 喉に詰まった | 詰まった／つまった／窒息／喉に何か／むせて顔色／顔が紫／チアノーゼ／むせこんで苦しそう |
| 転倒・頭を打った | 頭を打った／頭打った／転んで動かない／転倒して痛がる／床に倒れている |
| 大量の出血 | 血が止まらない／大量に出血／血だらけ |
| 火事・地震 | 火事／煙が出ている／燃えている／地震 |
| （外国語） | 英語・ベトナム語・インドネシア語でも、上の5つの状況に当たる言葉を持つ（例：not breathing／không thở／tidak bernapas、choking／bị hóc／tersedak、fell down／bị ngã／jatuh、bleeding／chảy máu／pendarahan、fire／cháy／kebakaran）。ふつうの外国語の文（例：おむつ・昼ごはんの質問）では当たらないことをテストで固定する |

- 当たったら、**待ち時間なしで**赤い緊急の案内を一番上に出す：「いますぐ」の行動（大きな字・番号つき）→ 連絡の順（大きな声で人を呼ぶ → 119番 → 看護師オンコール → 施設長）→ 該当の緊急時の手順へのボタン
- その下に、通常の検索の結果も出す
- **当たる言葉は `emergency.ts` の表だけで決める。** 確からしさの計算や点数で判定しない（見逃しと誤りの両方を、テストで固定できるようにするため）
- 緊急の案内の文は、法人のマニュアル「急変時の対応」の手順の写しではなく、`emergency.ts` に固定の文で持つ（マニュアルが下書きのまま・誤って消されても出るように）

### ③ 案内役『ともり』（`components/assistant/tomori*.tsx`・`repo/pet.ts`）

灯り（ランタン）の形の案内役。**ボタンではなく、画面の右下に常にいる**（スタート・聞く・書き込み・PDFの画面では出さない）。

| 項目 | 内容 |
|---|---|
| 見た目 | 白から空色へのしずく形の灯りに、空色の炎と顔。大きさは PC 108px／スマホ 66px。表情：ふつう・考え中・うれしい・休み（月）・**緊急（赤く光ってふるえる）** |
| ひとこと | 画面が変わって1.4秒後に、その画面に合った一言（時間帯のあいさつ・読んでいない数・研修・答えられなかった質問の数）。×で閉じる。スマホの読む画面では話しかけない |
| 小さなチャット | 押すと開く。回答は `ask()` を同じように使い、読んでいるマニュアルを話の流れとして渡す（FR-507）。緊急の言葉には、検索を待たずに赤い案内と「緊急時の案内を開く」 |
| 動かす・休ませる | ドラッグで置き場所を変えられ、場所と「休ませる」は保存する |
| 文言 | 「ともりがマニュアルからさがした答えです」。AIが文章を考えたように見せない（生成AIは使わない） |

### ② 検索（`src/lib/answer/search.ts`）

1. **探す対象は「手順」**。マニュアルの題名・タグ・言いかえ（重み3）／手順の見出し・言いかえ（重み3）／説明・やさしい日本語の文・注意・コツ（重み1）／ことば帳の読み（重み2：ひらがなで聞いても漢字の手順に当たるように）
2. **正規化**：全角・半角、カタカナ・ひらがな、大文字・小文字、`{漢字|かんじ}` と `[[言葉]]` の書式を外す。言い回し（「〜ってどうやるの」「〜の順番」「〜していい？」「教えて」）を除く
3. **言葉の分け方**：2文字ずつ区切った言葉と、`answer/dictionary.ts`（介護の言葉 200語以上）に一致した言葉
4. **同じ意味の言葉**：`answer/synonyms.ts`（初期 80組。例：おむつ交換＝パッド交換＝排せつ介助／移乗＝トランスファー＝乗り移り／体位変換＝体交＝寝返りの介助／誤嚥＝むせ／特浴＝機械浴＝特殊浴槽／オンコール＝夜間の連絡）
5. **点数**：BM25（k1=1.2、b=0.75）×重み。同じマニュアルの手順は最大2件
6. **確からしさ**：基準（`answer/config.ts`）を超えれば「見つかった」

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

| 結果 | 文章の型 | 一緒に出すもの |
|---|---|---|
| 見つかった（1つのマニュアル） | 「『{マニュアル名}』の手順{n}『{見出し}』が近そうです。」 | 手順のカード（最大3件）。手順に注意があれば1行。マニュアルに「やってはいけないこと」があれば1つ目を1行 |
| 見つかった（複数） | 「関係しそうな手順が{件数}つ見つかりました。」 | 手順のカード（最大3件） |
| 見つからなかった | 「法人のマニュアルには見つかりませんでした。言い方を変えるか、リーダーに聞いてください。」 | 「リーダーに知らせる」・よく聞かれる質問 |

- 回答の文もふりがな・やさしい日本語の設定に従う
- **文章をでっち上げない。** 型と、マニュアルに書いてある文字だけで作る
- 吹き出しの下に「マニュアルから探した答えです」

| ID | 要件 | 優先度 |
|---|---|---|
| FR-501 | 緊急の判定に当たる質問には、待たずに緊急の案内を出すこと | P1 |
| FR-502 | 当たらない質問には、600〜900ms の後に③の型で回答すること | P1 |
| FR-503 | 見える範囲の外のマニュアルを根拠にも候補にも出さないこと | P1 |
| FR-504 | 質問・時刻・返した手順・解決したかを記録すること | P1 |
| FR-505 | 7章の見本の質問50問のうち45問以上で、期待する手順が上位3件に入ること（`answer.test.ts`） | P1 |
| FR-506 | **緊急の見本の質問20問はすべて緊急の案内を出し、緊急でない見本の質問50問は1問も緊急の案内を出さないこと**（`emergency.test.ts`） | P1 |
| FR-507 | 続けて聞いた質問は、直前に返したマニュアルの点数を1.3倍にすること | P2 |

## 6.7 研修と記録（`src/lib/compliance/`）

### 義務研修の種類と必要な回数（見本の値）

`compliance/rules.ts` に次の表を持つ。**値は一般的な基準に沿った見本であり、実際の回数は事業の種類と自治体の運用で確かめる必要がある**（画面の注記と 10章に書く）。

| 研修の種類 | 施設（特養・グループホーム） | 通い・訪問（デイ・訪問介護） | 新しく入った職員 |
|---|---|---|---|
| 虐待の防止 | 年2回以上 | 年1回以上 | 入職時に受ける |
| 身体拘束の適正化 | 年2回以上 | 年1回以上 | 入職時に受ける |
| 感染症の予防とまん延の防止 | 年2回以上 | 年1回以上 | 入職時に受ける |
| 業務継続（災害・感染症）の計画 | 年2回以上 | 年1回以上 | 入職時に受ける |
| 事故の発生の防止 | 年2回以上 | — | 入職時に受ける |
| 認知症ケア | 年1回以上 | 年1回以上 | — |

| ID | 要件 | 優先度 |
|---|---|---|
| FR-601 | 年間の研修計画で、研修の種類ごとに予定（月・事業所・対象）を置けること。今年度（4月〜3月）の表で、予定と実施済みを並べて見せること | P1 |
| FR-602 | 研修の実施の記録：日時・場所・講師・内容・使ったマニュアル・参加者の出欠。保存すると、出席した職員に理解度の確認（使ったマニュアルの問題）が届くこと | P1 |
| FR-603 | 欠席した職員に「あとから受講」を届け、マニュアルを読んで確認に合格したら「受講済み（個別）」として同じ研修の記録に入ること | P1 |
| FR-604 | 義務研修の達成状況：事業所×研修の種類ごとに「実施の回数／必要な回数」と「新しく入った職員のうち受けた人数／人数」を出し、足りないものを赤く（文字と印も）すること。今年度の残りの月数を出すこと | P1 |
| FR-605 | 研修の実施記録のPDF（A4縦）：法人名・事業所名・研修の種類・研修名・日時・場所・講師・内容・使った資料（マニュアル名と版）・参加者名簿（氏名・職種・出欠・理解度の確認の点数と合否・受講の日付・「個別」の印）・作成日・作成者。複数の回をまとめて1つのPDFにできること | P1 |
| FR-606 | 職員ごとの研修の履歴（研修・日付・形（集合／個別）・結果）を出し、PDFにできること | P2 |
| FR-607 | 新人の受け入れ研修：入職からの日数と、受けるマニュアル（12本）の進み具合。30日を過ぎて終わっていない人に印 | P1 |

## 6.8 ヒヤリハット

| ID | 要件 | 優先度 |
|---|---|---|
| FR-701 | 報告：日時・時間帯（日中／夕方／夜間）・場所・種類・何があったか（200文字）・関係する手順（任意）。**利用者さまの実名を入れないよう、入力欄の上に案内を出し、よくある名字（佐藤・鈴木・高橋 など50個）と「様」「さん」が続く書き方を見つけたら確認を出すこと** | P1 |
| FR-702 | 一覧：新しい順・未対応を上に。種類・場所・時間帯・事業所で絞り込めること | P1 |
| FR-703 | 傾向：種類別・時間帯別・場所別の数（直近6か月）。いちばん多い組み合わせを文で出すこと（例：「夜間・トイレ・転倒が多い（14件）」） | P1 |
| FR-704 | 「この手順を見直す」：関係する手順の編集へ移り、見直しの理由にヒヤリハットを結び付けること。公開したら、ヒヤリハットに「見直した手順（版）」を記録すること | P1 |
| FR-705 | 見直した手順を公開するとき「読み直してください」を選ぶと、対象の職員の読んだ印を外し、お知らせを送ること | P1 |

## 6.9 分析

| ID | 要件 | 優先度 |
|---|---|---|
| FR-801 | 事業所別の既読率・合格率、よく見られる手順（上位10）、読まれていないマニュアル | P1 |
| FR-802 | 夜勤（22時〜6時）に聞かれた質問の上位10と、緊急の案内を出した回数 | P1 |
| FR-803 | 答えられなかった質問の一覧と推移（週ごと8週） | P1 |
| FR-804 | ヒヤリハットの数（月別）と、見直した手順の数 | P1 |

---

# 7. データ設計

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

```ts
export type Role = 'staff-new' | 'staff-intl' | 'leader' | 'director'
export type Lang = 'en' | 'vi' | 'id' | 'my'

export interface Office { id: string; name: string; kind: 'facility' | 'day' | 'home-visit' | 'group-home'; units: { id: string; name: string }[] }
export interface Staff {
  id: string; name: string; nameKana: string; officeId: string; unitId: string | null
  job: '介護職員' | '看護職員' | '生活相談員' | 'ケアマネジャー' | '管理者'
  status: '日本人' | '技能実習' | '特定技能' | 'EPA'
  joinedAt: string
}

/** 読みと言葉の印を埋め込んだ文。例：'{車|くるま}いすの[[ブレーキ]]を かけます' */
export type RichText = string

export interface ReadingPrefs { ruby: boolean; easy: boolean; size: 'm' | 'l' | 'xl'; lang: Lang }

export interface Word {
  id: string; word: string; reading: string
  category: 'body' | 'care' | 'equipment' | 'condition' | 'infection' | 'record'
  meaningEasy: RichText                 // やさしい日本語の意味
  image: string | null                  // 絵（public/words/*.webp）
  tr: Partial<Record<Lang, string>>     // 訳。自信がないものは入れない
}

export type Category = 'care' | 'infection' | 'emergency' | 'record' | 'communication' | 'equipment' | 'rules'
// 介助／感染対策／緊急時／記録・報告／接遇・認知症ケア／機器／事業所の決まり

export interface Step {
  id: string
  title: RichText; titleEasy?: RichText
  body: RichText; bodyEasy?: RichText
  caution: RichText; tip: RichText
  media: { kind: 'photo'; ref: MediaRef; shapes: Shape[] } | { kind: 'video'; ref: MediaRef; poster: MediaRef; start: number; end: number } | null
  aliases: string[]
}
// MediaRef・Shape は TSUTAE と同じ形（位置は写真の幅・高さに対する割合 0〜1）

export interface ManualVersion {
  version: number; title: RichText; category: Category
  coverStepId: string | null; minutes: number; tools: RichText
  donts: RichText[]                     // やってはいけないこと（最大5）
  tags: string[]; aliases: string[]
  steps: Step[]; checks: CheckQuestion[]
  publishedAt: string | null; publishedBy: string | null
  changeNote: string; reviewedFromHiyariId: string | null
}

export interface Manual {
  id: string; scope: { officeIds: string[] | 'all'; unitIds?: string[] }
  ownerId: string; status: 'draft' | 'review' | 'published' | 'returned'; returnReason: string | null
  published: ManualVersion | null; draft: ManualVersion | null; history: ManualVersion[]
  trainingKinds: TrainingKind[]         // この手順書を使う義務研修の種類
  qrCode: string; createdAt: string; updatedAt: string
}

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

export type TrainingKind = 'abuse' | 'restraint' | 'infection' | 'bcp' | 'accident' | 'dementia'

export interface TrainingPlan { id: string; kind: TrainingKind; officeId: string; month: number /* 4〜15（翌3月=15） */; title: string; sessionId: string | null }

export interface TrainingSession {
  id: string; kind: TrainingKind; officeId: string; title: string
  heldAt: string; place: string; lecturer: string; content: string
  manualRefs: { manualId: string; version: number }[]
  attendees: { staffId: string; present: boolean }[]
  makeups: { staffId: string; completedAt: string }[]   // あとからの受講（個別）
  recordedBy: string; recordedAt: string
}

export interface ReadRecord { staffId: string; manualId: string; version: number; lastStep: number; completedAt: string | null }
export interface CheckResult { staffId: string; manualId: string; sessionId: string | null; score: number; passed: boolean; at: string }

export interface Hiyari {
  id: string; reporterId: string; officeId: string; unitId: string | null
  occurredAt: string; timeBand: 'day' | 'evening' | 'night'
  place: 'room' | 'toilet' | 'bath' | 'dining' | 'corridor' | 'outdoor'
  kind: 'fall' | 'aspiration' | 'medication' | 'skin' | 'wandering' | 'other'
  text: string; relatedStepId: string | null
  status: 'open' | 'reviewing' | 'done'; note: string
  reviewedManual: { manualId: string; version: number } | null
}

export interface Question { id: string; staffId: string; text: string; normalized: string; askedAt: string; emergency: string | null; hits: { manualId: string; stepId: string; score: number }[]; found: boolean; feedback: 'solved' | 'unsolved' | null; reported: boolean }

export interface Answer {
  emergency: { situation: string; actions: string[]; contacts: { label: string; number: string }[]; manualId: string | null } | null
  text: RichText
  hits: { manualId: string; manualTitle: RichText; stepId: string; stepIndex: number; stepTitle: RichText; excerpt: RichText; caution: RichText | null; media: Step['media'] }[]
  confidence: 'found' | 'not-found'
}
```

**派生値は保存しない。** 義務研修の達成状況・既読率・新人の受け入れ研修の進み具合・ヒヤリハットの傾向は `src/lib/compliance/` と `src/lib/calc/` の関数で毎回算出する。

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

| データ | 件数 | 内容 |
|---|---|---|
| 事業所 | 4 | やまぶき苑（特養・4ユニット：1階すずらん・1階あやめ・2階ひまわり・2階さくら）、やまぶきデイ、やまぶき訪問、グループホームすみれ（2ユニット） |
| 職員 | 60 | 名前は架空。外国人の職員 12名（ベトナム5・インドネシア3・ミャンマー2・フィリピン2）。今年度に入職した職員 14名（受け入れ研修の途中 6名） |
| マニュアル | 36 | 下の一覧。公開中32・確認待ち2・下書き1・差し戻し1。うち訪問介護だけのもの3 |
| 手順 | 約220 | 1本あたり4〜9手順。**すべての手順に写真か動画**（写真約200枚・動画の手順19。動画は10本の素材を、内容の近い手順で区間を変えて使い回す）。**すべての手順にやさしい日本語の文** |
| ことば帳 | 80語 | 介護の言葉。英語は全語・他の3言語は60語以上（6.3） |
| 理解度の確認 | 30本 | 1本2〜5問 |
| 研修の計画と記録 | 今年度 | 6種類×4事業所の計画。「今日」より前の月は実施済み（記録・出欠・確認の結果つき）、後は予定。**やまぶき苑の「感染症の予防」は1/2回**（4章 体験5で2/2回になる）。デイの「身体拘束」は未実施で赤い（見せ場） |
| ヒヤリハット | 直近6か月 90件 | 夜間・トイレ・転倒がいちばん多くなるように（14件前後）。うち未対応 6件 |
| 質問の履歴 | 直近8週 160件 | 夜勤の時間帯を4割。答えられなかったもの 20件 |

**マニュアルの一覧（分類：題名・手順の数）**

| 分類 | マニュアル |
|---|---|
| 介助（12） | ベッドから車いすへの移乗（全介助）8／移乗（一部介助）6／体位変換 6／おむつ交換（ベッド上）8／トイレ誘導 6／トイレ誘導（夜間）6／食事の介助 7／口腔ケア 7／入浴の介助（一般浴）9／訪問での入浴の準備（訪問のみ）6／歩行の介助 5／車いすの押し方 5 |
| 感染対策（5） | 手洗いの手順 6／ガウン・手袋の着け外し 7／嘔吐物の処理 8／新型コロナ・インフルエンザが出たとき 6／おむつの捨て方 4 |
| 緊急時（5） | 急変時の対応 7／誤嚥・窒息のとき 6／転倒・転落のとき 7／夜間の看護師オンコール 5／火事・地震のとき 6 |
| 記録・報告（4） | 介護記録の書き方 6／申し送りのしかた 5／ヒヤリハットの書き方 5／事故報告の流れ 6 |
| 接遇・認知症ケア（4） | 声かけの基本 6／帰りたいと言われたとき 5／入浴を嫌がられたとき 5／身体拘束にあたること 6 |
| 機器（4） | 移乗用リフトの使い方 8／特殊浴槽（特浴）の使い方 9／見守りセンサーの確認 5／電動ベッドの使い方 5 |
| 事業所の決まり（2） | 訪問先での鍵の管理（訪問のみ）5／訪問前の持ち物の確認（訪問のみ）4 |

（訪問だけのものは「事業所の決まり」の2本と、介助の「訪問での入浴の準備」の3本。合計36本・約220手順）

**写真と動画の注意（必須）**
- 写真は AI で生成した画像、または商用利用が認められた素材のみ。出典を `public/photos/CREDITS.json` に記録
- **利用者さま役の人の顔は写さない**（手元・後ろ姿・福祉用具・介助者の手の動きが主役の構図にする）。顔が写る構図はぼかしの書き込みを必ず置く
- 実在の施設のロゴ・名札の文字・ベッドの名前の札は写さない
- 身体を晒す写真（入浴・排せつ）は**使わない**。入浴と排せつの手順は、福祉用具・手元・タオル・手順を示すイラスト風の図で表す
- 写真の6割以上に書き込み（矢印・丸・番号）を入れる

**見本の質問（`src/lib/seed/sample-questions.ts`）**

- 通常の質問 50問（期待するマニュアルと手順つき）。例：

| 質問 | 期待 |
|---|---|
| おむつ交換の順番 | おむつ交換（ベッド上）／手順1〜3 |
| パッド交換ってどうやる | おむつ交換（ベッド上）（同じ意味の言葉で当たる） |
| 体交って何時間ごと？ | 体位変換／手順1 |
| 車いすのブレーキどこ | 車いすの押し方／手順1・移乗（全介助）／手順2 |
| リフトのベルトの付け方 | 移乗用リフトの使い方／該当手順 |
| 吐いた時の片付け | 嘔吐物の処理／手順1 |
| 夜中に看護師さん呼んでいい？ | 夜間の看護師オンコール／手順1 |
| 帰りたいって言われた | 帰りたいと言われたとき／手順1 |
| ミトンって使っていいの | 身体拘束にあたること／該当手順 |
| とくよくの準備 | 特殊浴槽（特浴）の使い方／手順1（ひらがなで当たる） |

- 緊急の質問 20問（4つの状況から各4〜6問。言い方を変えたもの）
- **見本の質問と同じ文を、辞書・同じ意味の言葉・言いかえ・緊急の表にそのまま入れて当てるのは禁止**

## ストアとリポジトリ

| リポジトリ（`src/lib/repo/`） | 主なメソッド |
|---|---|
| `manuals.ts` | `list`, `get`, `createDraft`, `saveDraft`, `requestReview`, `publish`, `returnToAuthor`, `revert`, `diff` |
| `steps.ts` | `addSteps`, `updateStep`, `reorder`, `remove`, `saveShapes` |
| `reading.ts` | `getPrefs`, `setPrefs`, `listWords`, `getWord`, `autoRuby(text)`, `missingRuby(text)` |
| `media.ts` | `putPhoto`, `putVideo`, `getUrl`, `estimate` |
| `progress.ts` | `markStep`, `complete`, `submitCheck` |
| `distribution.ts` | `distribute`, `reach`, `nudge`, `requestReread` |
| `training.ts` | `plan`, `savePlan`, `sessions`, `recordSession`, `makeup`, `compliance`, `staffHistory`, `onboarding` |
| `hiyari.ts` | `report`, `list`, `trends`, `startReview`, `close` |
| `assistant.ts` | `ask`, `feedback`, `report` |
| `insights.ts` | `forOffice`, `forAll` |
| `_scope.ts` / `_delay.ts` | 見える範囲／擬似的な待ち時間 |

---

# 8. デザイン要件

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

**「白と空色」。** 白い地に、澄んだ青と薄い空色。清潔で明るく、病院や施設の白さになじむ画面。案内役「ともり」とその入口の面だけ、薄い空色のグラデーションにやわらかな光の粒を置く。**飲食向けの TSUTAE（暗い青緑の近未来の案内役）とは、明るさ・色・案内役の形で分ける。** 読み間違えないはっきりした文字と区切りは守る。緊急の案内だけは、ほかと見間違えようのない赤のまま。

- 職員の画面：やさしい色・大きな文字・押しやすいボタン。夜勤の暗い詰所でまぶしくないよう、白は真っ白にしない
- リーダー・施設長の画面：表と数字が読みやすい業務の画面
- 研修の記録のPDF：役所に出す書類として、飾りのない白黒の表

## ロゴとアイコン

| もの | 内容 |
|---|---|
| しるし（`components/brand/logo-mark.tsx`） | 空色→澄んだ青の角丸の地に、**両の手が灯り（ともりの顔のしずく）を下から支える**形。「支え」と案内役を1つにする。文字の「さ」などで代用しない |
| 置き場所 | 左のメニューの上・上の帯（スマホ）・スタートページ・手順書のPDFの下 |
| ブラウザ・端末 | `public/favicon.svg`（タブ）・`favicon-32.png`・`apple-touch-icon.png`（180・角丸なし）・`icon-192/512.png`・`icon-maskable-512.png`（中身を78%に縮めた安全域つき）・`manifest.webmanifest`（ホーム画面に追加したときの名前は SASAE） |
| 共有 | `public/og.png`（1200×630）。og:title・og:description・twitter:card を index.html に置く |

## デザイントークン

| トークン | 用途 | 値（目安） |
|---|---|---|
| `--brand` / `--brand-strong` | 主な操作・選んでいるタブ・左のメニューのいまの項目 | 澄んだ青 #1E63C6 / #164C9C（白い文字と 5.5:1 を実測） |
| `--brand-soft` | 選んでいる行・ラベルの地 | #E7F0FC |
| `--bg` | 画面の地 | #F4F8FD（ごく薄い空色） |
| `--lamp` / `--lamp-ink` / `--lamp-soft` | 空色：進み具合の輪・飾りの光（文字には使わない）／空色の文字／薄い地 | #5FA8F2 / #1B5BAE / #E3F0FD |
| `--night` / `--moon` | 動画の印など小さな濃い地と、その上の文字 | #1E3A64 / #FFFFFF |
| `.sky-panel` | ともりの入口・聞く画面の見出し・小さなチャットの頭・スタートページ | 白→薄い空色のグラデーション＋淡い青の光の粒 |
| `--surface` / `--surface-2` / `--line` | カードの地 | #FFFFFF / #EDF3FA / #DDE6F1 |
| `--danger` / `--danger-bg` | 緊急・やってはいけないこと | 澄んだ紅 #C8233A / #FDEDEF（白い文字で 5.6:1。空色の画面に合う、少し青みの赤）。緊急の大きな面（ホームの緊急の入口・緊急の案内）は #D3304A → #B01D35 のグラデーション（`.em-surface`） |
| `--caution` / `--caution-bg` | 注意 | #8A4B08 / #FEF3C7 |
| `--tip` / `--tip-bg` | コツ | #1F6B3A / #DDF3E4 |
| `--ruby` | ふりがなの文字 | `--ink-2` |
| 状態 | 未・読んだ・合格・足りない | 灰／青／緑／赤（文字と印を併記） |

## タイポグラフィ

| 用途 | 指定 |
|---|---|
| 和文 | Noto Sans JP（ウェイト 400・500・700）。ミャンマー語の訳は Noto Sans Myanmar を追加で読み込む（ことば帳を開いたときだけ） |
| 見出し・大きな数字 | 丸ゴシック（`font-round`：端末の Hiragino Maru Gothic、無ければ Zen Maru Gothic・BIZ UDPGothic）。**Webフォントは読み込まない**（初回の表示を遅らせないため） |
| 本文 | 16px（標準）／19px（大）／22px（特大）・ウェイト500・行の高さ 1.9（ふりがなが入っても行が詰まらないように。ふりがな ありのときは 2.2） |
| ふりがな | 本文の 0.5倍・ウェイト500 |
| 手順の見出し | 本文の 1.25倍・700。番号は 28px の丸 |
| 緊急の案内 | 22px以上・700。行動の番号は 32px |
| 補足 | 13.5px 以上 |

## レイアウト

- 余白は 4px の倍数。カードの角丸 22px（大きな面は 28px）、ボタン 14px。影はやわらかく
- アプリの枠（PC）：左に白いメニュー（幅 256px・いまの項目は薄い青の地と青い印・下に自分の頭文字の丸）、上に帯（さがす・緊急・お知らせ）。スマホは上の帯と下部の帯
- 写真は 4:3 の枠に収め、切らずに余白を入れる
- 読む画面（スマホ）：上に切り替え（ふりがな・やさしい・文字の大きさ）を1行で・写真は幅いっぱい・下にめくるボタン（固定）
- 読む画面（PC）：左に手順の目次（幅 280px）・右に本文（最大幅 760px）
- 緊急の案内：スマホでは画面いっぱいの赤い面。PCでも幅 720px の大きな面
- 押せるものは 48×48px 以上（手袋をしていても押せるよう、ほかのアプリより大きく）

## 主要コンポーネント

| コンポーネント | 仕様 |
|---|---|
| `RichTextView` | `RichText` を、設定に従って `<ruby>`・押せる言葉で描く。**このコンポーネント以外で文を描かない**（ふりがなの表示漏れを防ぐ） |
| `ReadingBar` | ふりがな・やさしい・文字の大きさの切り替え（押しやすいトグル3つ）。言葉の訳の言語は「…」の中 |
| `WordSheet` | 下から出るシート：言葉・読み・絵・やさしい日本語の意味・訳（選んだ言語＋英語）・「この言葉が出てくる手順」 |
| `StepView` | 番号＋見出し・写真（書き込みを重ねる）か動画・説明・注意・コツ |
| `DontsBox` | やってはいけないこと（赤い枠・印・「してはいけません」） |
| `EmergencyPanel` | 赤い面・状況名・番号つきの行動・連絡の順（電話番号を大きく）・手順へのボタン |
| `AnswerBubble` / `StepHitCard` | TSUTAE と同じ考え方。回答の横にともりの顔 |
| `Tomori` / `TomoriPet` | 案内役（6.6 ③） |
| `LampAsk` / `EmergencyTile` / `StatStrip` / `VideoStepTile` | ホームの部品（SC-001） |
| `ComplianceGrid` | 事業所×研修の種類の表。マスに「1/2回」「3/4名」と印 |
| `PlanTimeline` | 4月〜3月の横長の予定表（スマホは月ごとの縦の一覧に組み替える） |
| `AnnotatedPhoto` / `AnnotateEditor` | 書き込みの表示と編集（割合の位置・ぼかし） |
| `DemoBar` | 4章の仕様 |

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

| ID | 要件 |
|---|---|
| A11Y-01 | 本文と背景のコントラスト比 4.5:1 以上（実測） |
| A11Y-02 | 緊急・やってはいけないこと・注意・状態を色だけで示さない |
| A11Y-03 | キーボードだけで、読む・ふりがなの切り替え・ことば帳・確認・質問・研修の記録ができる |
| A11Y-04 | `<ruby>` は読み上げで二重に読まれないよう、`<rt>` を読み上げから外すか、読み上げ用に漢字だけの文を別に持つ |
| A11Y-05 | 写真に「手順N：見出し」を代替テキストとして入れる |
| A11Y-06 | 緊急の案内が出たら、読み上げにも知らせる（`aria-live="assertive"`。緊急のときだけ） |
| A11Y-07 | 文字サイズ200%・特大の設定でも、読む画面と緊急の案内が最後まで使える |

## ライティング規約

- 利用者さまは「利用者さま」「〇〇さま」。子ども扱いの言葉（「〜ちゃん」「おりこうさん」）を使わない
- 職員の画面はやさしい言葉。緊急の案内は短い命令形でよい（「声を出して人を呼ぶ」）
- **使わない言葉**：ユーザー・タスク・ナレッジ・コンテンツ・ステータス・アセット・ワークフロー
- 回答は「〜が近そうです」。言い切らない

---

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

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

| レイヤ | 技術 | 備考 |
|---|---|---|
| ビルド | Vite 6 ／ TypeScript strict | 静的ファイルとして配信 |
| 画面 | React 19 ／ React Router 7 | |
| スタイリング | Tailwind CSS v4 + CSS Variables | トークンは CSS 変数（チャンネル値） |
| UIコンポーネント | Radix UI（Dialog・Tabs・Popover・Toggle・Switch など必要なものだけ） | |
| 状態管理 | Zustand + persist | localStorage |
| 写真・動画の保存 | idb-keyval | |
| 写真の縮小 | 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（静的アセット） | `not_found_handling: "single-page-application"` |
| テスト | Vitest / Playwright / axe-core | |

**上記以外のライブラリを入れる前に必ず提案し、承認を得ること（自動で進める場合は入れない）。** 特に形態素解析の辞書（kuromoji 等）は入れない。

**PDF の日本語について：** Noto Sans JP の TTF（静的ウェイト 400 と 700）を `public/fonts/` に置き `Font.register`。`Font.registerHyphenationCallback(word => [word])` で自動ハイフネーションを無効にする。**PDF のふりがなは、漢字の上に小さな文字を置く形で描く**（@react-pdf には ruby が無いため、`RichText` を「漢字の箱の上に読みの箱」を並べる形に変換する関数を `lib/pdf/ruby.tsx` に作る）。研修の実施記録のPDFは、ふりがなを付けない。

## ディレクトリ構成

```
/
├── CLAUDE.md
├── docs/DECISIONS.md          # 仕様に無いことを自分で決めた記録
├── wrangler.jsonc
├── public/
│   ├── photos/  videos/       # 手順の写真・動画と CREDITS.json
│   ├── words/                 # ことば帳の絵と SOURCES.md（訳の用意のしかた）
│   └── fonts/
└── src/
    ├── main.tsx  app.tsx
    ├── routes/
    │   ├── start.tsx  home.tsx  emergency.tsx  notices.tsx  qr.tsx
    │   ├── manuals/  words/  ask.tsx  training.tsx  hiyari/
    │   ├── studio/            # SC-100〜150
    │   └── admin/             # SC-200〜206
    ├── components/
    │   ├── reading/           # RichTextView, ReadingBar, WordSheet
    │   ├── manual/  editor/  assistant/  emergency/  training/  hiyari/  demo/  ui/
    ├── lib/
    │   ├── types/  seed/  store/  repo/  media/
    │   ├── reading/           # parse.ts（RichText の解析）, ruby.ts（自動付与と漏れの検出）, dictionary.ts（読み 600語以上）, easy.ts（やさしい日本語の点検）
    │   ├── answer/            # emergency.ts, normalize.ts, tokenize.ts, dictionary.ts, synonyms.ts, phrases.ts, search.ts, compose.ts, config.ts
    │   ├── compliance/        # rules.ts（義務研修の表）, status.ts（達成状況）, onboarding.ts
    │   ├── calc/              # reach.ts, hiyari-trends.ts, diff.ts, numbering.ts
    │   ├── pdf/               # session-record.tsx, staff-history.tsx, manual.tsx, qr-sheet.tsx, ruby.tsx
    │   └── utils/
    ├── styles/tokens.css
    └── e2e/
```

## コーディング規約

- TypeScript strict。`any` 禁止
- ファイル名は kebab-case、コンポーネントは PascalCase。1ファイル300行を超えたら分割を検討
- **コンポーネントから Zustand ストアを直接参照しない。必ず `src/lib/repo/` 経由**
- **文の表示は必ず `RichTextView` を通す**（`{…|…}` や `[[…]]` が画面にそのまま出る事故を防ぐ）
- 検索・緊急の判定・ふりがな・義務研修の判定は `src/lib/` の純粋な関数にし、テストを書く
- 派生値をストアに保存しない
- 写真・動画の Blob をストアに入れない
- コミットは1タスクごと。メッセージに要件IDを含める

---

# 10. 非機能要件

| ID | 要件 | 目標値 |
|---|---|---|
| NFR-01 | LCP（スマホ・ホームと読む画面） | 2.5秒以下 |
| NFR-02 | INP | 200ms以下 |
| NFR-03 | CLS | 0.1以下 |
| NFR-04 | 質問の検索の処理時間（約220手順） | 50ms以下 |
| NFR-05 | 緊急の判定から案内の表示まで | 100ms以下 |
| NFR-06 | 初期JSバンドル（gzip後） | 230KB以下（PDF・グラフ・QR・編集・リーダーと施設長の画面は動的に読み込む） |
| NFR-07 | Lighthouse（スマホ・ホーム） | Performance 90 / Accessibility 95 以上 |
| NFR-08 | 対応ブラウザ | Chrome / Safari / Edge 最新2バージョン、iOS Safari 16以降 |
| NFR-09 | 入力のサニタイズ | — |
| NFR-10 | 保存の容量が少ないときの警告 | — |
| NFR-11 | 画面幅 320px〜2560px で横にはみ出さない（ふりがな あり・特大の設定でも） | — |
| NFR-12 | 写真は一覧で幅640、手順で幅1600。動画は手順を開くまで読み込まない | — |

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

- **義務研修の回数と内容は、事業の種類（施設・通所・訪問・地域密着など）と自治体の運用で異なる。** 本デモの `compliance/rules.ts` は一般的な基準に沿った見本であり、本番では事業所ごとに確認して設定できるようにする
- 研修の記録は運営指導で確認される書類になる。保存期間（一般に完結の日から2年以上、自治体によって5年）と、改ざんできない記録の仕組みが必要
- ヒヤリハット・事故報告には利用者さまの情報が含まれうる。本番では閲覧できる人を絞り、個人情報保護法と事業所の規程に沿って扱う
- 緊急の案内は、法人の急変時対応マニュアル・嘱託医・看護師の指示に合わせて、本番前に必ず専門職が確認する
- 生成AIで回答を作る場合も、緊急の判定は決まった言葉の一致で先に行い、AIに任せない
- ことば帳の訳は、本番前にその言語を母語とする人が確認する
- ログイン、退職者の停止、異動の反映、操作の記録
- **本デモはデータをサーバーに送信しないため、これらの義務は発生しない。** ただし「デモである」旨は画面上に常時明示する

---

# 11. 実装タスク

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

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

- [x] Vite 6 / React 19 / TypeScript strict / React Router 7 / Tailwind v4 で初期化。`npm run check`（型チェック＋テスト）
- [x] `wrangler.jsonc`（静的アセット＋SPA）
- [x] 7章の型・ストア・リポジトリの土台・`_delay.ts`・`_scope.ts`
- [x] `tokens.css` と共通部品、デモ切替バー (FR-001, FR-002, FR-004, FR-006)

## Phase 1 — ふりがなとことば帳（2日）

- [x] `reading/parse.ts`（`RichText` の解析）とテスト（入れ子・閉じ忘れ・読みの空を含む）
- [x] `RichTextView`（ruby・押せる言葉・文字の大きさ）・`ReadingBar`・`WordSheet` (FR-201〜FR-205)
- [x] ことば帳 80語（読み・やさしい意味・分類・絵・訳）と SOURCES.md (6.3)
- [x] ことば帳の画面 SC-013 (FR-206)
- [x] `reading/dictionary.ts`（600語以上）・`ruby.ts`（自動付与と漏れの検出）とテスト (FR-406)

## Phase 2 — 中身：マニュアル・写真・研修のシード（3日）

- [x] マニュアル36本・約220手順の文（ふつう・やさしい日本語・注意・コツ・やってはいけないこと）を `RichText` で書く。**ふりがなの漏れが0になるまで `ruby.ts` で点検する**
- [x] 写真約210枚・動画10本を用意（7章の注意を守る）。全枚を目で見て、見出しと写真が合っていることを確かめる
- [x] 写真の6割以上に書き込みを入れる
- [x] 理解度の確認30本、職員60名、研修の計画と記録（今年度）、ヒヤリハット90件、質問の履歴160件
- [x] シードの件数と、4章の初期状態（感染症 1/2回・デイの身体拘束が未実施など）をテストで確認

## Phase 3 — 読む・確認・緊急・QR（3日）

- [x] ホーム SC-001・マニュアル一覧 SC-010 (FR-101, FR-102)
- [x] マニュアルを読む SC-011（やってはいけないこと・めくり・目次・続きから・確認しました）(FR-103〜FR-107)
- [x] 理解度の確認 SC-012 (FR-301〜FR-303)
- [x] 緊急時の案内 SC-021 と `EmergencyPanel`
- [x] QRから開く SC-060・研修 SC-030・お知らせ SC-050

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

- [x] `answer/emergency.ts` と **`emergency.test.ts`（緊急20問すべて当たる・通常50問は1問も当たらない）** (FR-501, FR-506)
- [x] `answer/` の正規化・言葉の分け方・辞書（200語）・同じ意味の言葉（80組）・検索・回答の組み立て
- [x] **`answer.test.ts`：見本の質問50問で45問以上が上位3件に入るまで調整** (FR-505)
- [x] 質問チャット SC-020 (FR-501〜FR-504, FR-507)

## Phase 5 — 作る・書き込み・ヒヤリハット（4日）

- [x] 作ったマニュアル SC-100・編集 SC-101（やさしい日本語の欄と点検・自動保存・2つの見え方のプレビュー）(FR-401〜FR-404, FR-407, FR-410, FR-411)
- [x] 写真の書き込み SC-102（顔のぼかしの注意）(FR-405)
- [x] ふりがなの確認 SC-103 (FR-406)
- [x] 公開の流れ・版の履歴・確認待ち SC-205 (FR-409)
- [x] 配る・読まれ具合 SC-110・ユニットの進み具合 SC-140
- [x] ヒヤリハットの報告 SC-040（実名の確認）・一覧と傾向 SC-120・見直し・読み直し (FR-701〜FR-705)
- [x] 質問 SC-150 (F-Q02)

## Phase 6 — 研修と記録（3日）

- [x] `compliance/rules.ts`・`status.ts`・`onboarding.ts` とテスト（回数の数え方・新入職員・あとからの受講）
- [x] 義務研修の達成状況 SC-200 (FR-604)
- [x] 年間の研修計画 SC-201 (FR-601)
- [x] 研修の実施の記録 SC-130・研修の記録 SC-202・あとからの受講 (FR-602, FR-603)
- [x] **研修の実施記録のPDF SC-203**（名簿・確認の結果・個別の印・複数をまとめる）(FR-605)
- [x] 職員の研修の履歴 SC-204 (FR-606)・新人の受け入れ研修 (FR-607)
- [x] 全体の分析 SC-206 (FR-801〜FR-804)

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

- [x] 4章の体験7つと 5章のフローを、すべて手動で確認
- [x] 全画面を開き、空の画面が1つもないこと・`{…|…}` や `[[…]]` が画面に生のまま出ていないこと
- [x] 全画面の文言を介護の現場の言葉で読み直す。8章の「使わない言葉」がないこと。利用者さまへの言葉づかい
- [x] axe-core（Critical / Serious 0件）・キーボードのみの操作・コントラストの実測・文字サイズ200%と特大の設定
- [x] 初期バンドル 230KB 以下・Lighthouse・320px〜2560px（ふりがな あり・特大でも）
- [x] Playwright で 5章のフロー1〜4・4章の体験1〜7の E2E
- [x] Cloudflare Workers へ公開（`npx wrangler deploy`）。直接開いたURLが404にならないこと

---

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

> **工数配分の意図：** Phase 1 でふりがなとことば帳を先に作るのは、このアプリのすべての文がそれを通って表示されるため。後から足すと、文を描く場所のすべてを直すことになる。Phase 2 で中身を先にそろえるのは、質問の答えの確かさも、伝わりやすさも、研修の記録の見栄えも、中身で決まるため。

---

# 12. 受入基準

1. 6章の優先度 P1 の要件がすべて実装されていること
2. 5章の主要フローと 4章の体験7つが、最初から最後まで動くこと（P2・P3 でも必須）
3. ロールを切り替えると、表示範囲と表示の設定が変わること。スコープ判定が `_scope.ts` に集約されていること
4. **全マニュアルの全手順の文に、ふりがなの漏れが無いこと**（`ruby.ts` の点検で0件）。全手順にやさしい日本語の文があること
5. ことば帳80語：英語は全語・ベトナム語／インドネシア語／ミャンマー語は各60語以上。用意のしかたが SOURCES.md に記録されていること
6. **緊急の見本20問すべてで緊急の案内が出て、通常の見本50問では1問も出ないこと**
7. 見本の質問50問のうち45問以上で、期待する手順が上位3件に入ること
8. 回答の文に、マニュアルに書かれていない手順や数字が含まれないこと。職員に見えないマニュアルが回答に出ないこと
9. 義務研修の達成状況が、記録を足す・あとから受講する、で正しく変わること（テストで固定）
10. 研修の実施記録のPDFが**実際にダウンロードでき**、名簿・確認の結果・個別の印・日本語が正しく出ること
11. ヒヤリハットの報告 → 見直し → 公開 → 読み直し、が1本の流れで動くこと
12. 全画面のいずれにも空の状態がなく、すべての手順に写真か動画があること。利用者さま役の顔・身体を晒す写真が1枚も無いこと
13. リロード後も操作結果が保持され、「デモをリセット」で初期状態に戻ること
14. axe-core で Critical / Serious が0件、Lighthouse の基準値を満たすこと
15. データアクセスがすべて `src/lib/repo/` を経由し、文の表示がすべて `RichTextView` を通っていること
16. スマホ（375px）で、読む・ふりがなとことば帳・質問・緊急の案内・ヒヤリハットの報告が快適に使えること
17. 外国人の職員が画面の言語をベトナム語・英語・インドネシア語に変えると、メニュー・見出し・緊急の案内・案内役の言葉が切り替わり、ベトナム語・英語・インドネシア語で緊急の言葉を聞いても緊急の案内が出ること（E2E で固定）

---

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

1. **仕様がこの文書にない場合は質問する。** 質問できない（自動で進める）場合は、このルールに沿って決め、`docs/DECISIONS.md` に残す
2. **安全・伝わりやすさ・記録の正確さは削減対象外。** 速度を出すために削らない
3. スコープ外（3章 Won't have）は実装しない。特に生成AI・機械翻訳・形態素解析
4. 「デモだから」を理由に品質を落とさない
5. コンポーネントからストアを直接触りたくなったら、リポジトリ層に足りないメソッドがあるということ
6. **迷ったら、夜中の2時、ひとりで2階を見ている入社2か月の外国人の職員を思い浮かべる。** その人がスマホで、10秒で、正しい手順にたどり着けるか。危ないときに、迷わず人を呼べるか
7. **緊急の案内を、点数や確からしさで出し分けない。** 決まった言葉の表だけで出す。迷ったら「出す」側に倒す（ただし通常の見本50問で出ないこと）
8. **訳を推測で埋めない。** 自信のない訳は空にする
9. 利用者さまの尊厳を損なう写真・言葉・例を入れない

---

# 改訂の記録

| 版 | 日付 | 内容 |
|---|---|---|
| 1.0 | 2026-10-01 | 初版 |
| 2.0 | 2026-10-02 | 案内役『ともり』（右下に常にいる・小さなチャット・緊急で赤く光る）。デザインを「夜の灯り」にして TSUTAE と差別化。ホームをダッシュボード型に。スタートページを、ともりが話して約5秒でアプリへ入る形に。動画の手順を10→19（データ版2） |
| 2.1 | 2026-10-02 | 色を「白と空色」に変更（菊池さんの指示）。左のメニューを白に、ともりを空色の灯りに、スタートページを明るい画面に |
| 2.2 | 2026-10-05 | 緊急の赤を、レンガ色の #B42318 から、空色に合う澄んだ紅 #C8233A に変えた（菊池さんの指示）。緊急の大きな面はグラデーション、状況の選択は白いカードに紅の印 |
| 2.3 | 2026-10-05 | 画面の言語の切り替え（日本語・英語・ベトナム語・インドネシア語）を足した（菊池さんの指示）。メニューと見出しは訳＋小さな日本語、緊急の案内は日本語＋訳、緊急の判定は外国語でも当たる。訳の本体は日本語以外のときだけ読み込む。マニュアルの本文は日本語のまま（6.3「画面の言語」） |
| 2.5 | 2026-10-05 | ロゴとアイコンを作った（菊池さんの指示「アイコン設定も徹底」）。手が灯りを支えるしるし、favicon・ホーム画面のアイコン・マスク用アイコン・manifest・OGP画像・PDFの下のしるし（8章「ロゴとアイコン」） |
| 2.4 | 2026-10-05 | マニュアルの中身（題名・手順・注意・コツ・写真の書き込み・確認の問題）・ことば帳の意味・研修・お知らせ・質問の答え・日付・スタートページ・案内・タブの題名・読み上げ用の文字も、選んだ言語で出すようにした（菊池さんの指示「全部その言語に」）。中身の約1,900文はすべて訳あり。読む画面では訳の下に元の日本語を小さく添える |


---

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

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

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

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

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

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