KANAME — 要件定義書 兼 Claude Code 実装指示書
版数 1.0 / 作成日 2026-10-06 / 発行 ソウゾウ合同会社
用途 業務アプリの実演デモ / 製造業の作業手順書・力量表編
公開中の実装 https://kaname.souzohnic.workers.dev (本書はこの実装と同じものを作るための指示書である)
土台 飲食版 TSUTAE(マニュアル作成・共有)の仕組みを使い、製造の現場に合わせて「急所と理由」「良品と不良品の比べ」「力量表」を足した業種版
このドキュメントの使い方(Claude Code へ)
これ1枚が、規約・仕様・タスクのすべて。リポジトリ直下に CLAUDE.md として置き、毎回読み込むこと。
- 実装は「11. 実装タスク」の順に進める。フェーズを飛ばさない。
- 各タスクの括弧内は要件ID。着手前に該当章を読むこと。
- 仕様がここに書かれていない場合は、推測で実装せず質問する。
- スコープ外(3章 Won't have)は、思いついても実装しない。
- 「デモだから」を理由に品質を落とす判断はしない。
- 現場の言葉で書く。 画面の文言は、班や工場で働く人がそのまま読んで分かる言葉にする。「ナレッジ」「コンテンツ」「ドキュメント」「アセット」「ワークフロー」のような言葉を画面に出さない(「手順書」「手順」「写真」「動画」「確認」と書く)。
v2.0 で変わったこと(v1.0 から)
- 画面の骨組みを「左のメニュー+上の帯(探す・お知らせ)+ダッシュボード型のホーム」にした(8章)
- 案内役のキャラクター 「かなめ」 を足した。画面の右下にいつもいて、話しかけ、押すとその場で質問できる(6.9)
- スタートページを、かなめが自己紹介をして約5秒でアプリへ案内する形にした(SC-000)
- ⌘K で、手順書・手順・画面をまとめて探せる(FR-901)
- 初版の見本は写真だけで作る(工場の動画は、利用条件のはっきりした素材が見つかったら足す。動画の機能そのものは残す)
このアプリの勝ち筋
手順書は「作るのが面倒」「作っても読まれない」「読んでも分からないところを聞く相手がいない」の3つで死ぬ。KANAME は、スマホで撮った写真に矢印を描くだけで手順書ができ、現場ではQRコードからすぐ開け、分からないことはチャットで聞くと手順書の該当の手順が写真つきで返ってくることで、この3つを一度に解く。
作るのに10分以上かかる、現場で開くのに3回以上押す、質問しても関係のない手順が返ってくる、のどれか1つでもあれば失敗とみなす。
目次
- プロジェクト概要
- アーキテクチャ方針 — データベースを持たない
- スコープ定義
- ロールとデモ切替
- 画面一覧とユーザーフロー
- 機能要件
- データ設計
- デザイン要件
- 技術要件・ディレクトリ構成
- 非機能要件
- 実装タスク
- 受入基準
1. プロジェクト概要
背景と目的
中小の製造業(従業員20〜300名・多品種少量の切削加工や組立)では、作業の急所(うまくいくか・けがをしないかを分ける点)がベテランの頭の中にあり、手順書は古くて誰も見ない。新人や外国人の技能実習生が入るたびに、班長が同じことを口で教え、教える人によってやり方が変わる。分からないことがあっても忙しいベテランに聞きづらく、自己流で済ませた結果が、不良や設備の故障や、けがになる。
一方、管理する側は「誰がどの作業を一人でできるか」を、紙やExcelの力量表で、記憶を頼りに付けている。ある作業を一人でできる人が1人しかいないことに、その人が休んだ日に初めて気づく。
KANAME は、写真に矢印と急所を描いて手順書を作る・必要な人に届ける・質問には手順書から答える・読んだ/テストに合格した/現場で一人でできた、を力量表に積み上げるを1つにまとめる。
| 目的 |
内容 |
| 作りやすさの証明 |
スマホで撮った写真を並べ、矢印や丸を描き、「急所」と「その理由」をひとこと書くだけで手順書ができる |
| 「聞ける」手順書の証明 |
案内役「かなめ」に質問すると、手順書の中から該当の手順を、写真と急所つきで返す。答えられなかった質問は、手順書を足すべき場所として班長に知らせる |
| 力量の見える化の証明 |
読んだ・確認テストに合格した、は記録から自動で入り、「一人でできる」「教えられる」は班長が現場で見て付ける。一人でできる人が少ない作業に印が出る |
| 横展開の資産化 |
飲食版(TSUTAE)・介護版(SASAE)と同じ土台で、中身(会社・班・手順)と業種の機能だけを差し替える構造にする |
プロダクト定義
| 項目 |
内容 |
| プロダクト名 |
KANAME(かなめ)※仮称。作業の「要(かなめ)」=急所を伝える、の意 |
| 一言定義 |
製造業の作業手順書アプリ。写真に急所を描いた手順書を届け、質問に答え、力量表まで自動でそろえる |
| 提供形態 |
レスポンシブWebアプリ。フロントエンド完結(サーバー側の保存なし) |
| 主戦場 |
現場のスマホ・タブレット(読む・質問する・設備のQRから開く)と、事務所のPC(作る・配る・力量表を付ける) |
| 想定利用者 |
現場の作業者(新人・技能実習生・ベテラン)、手順書を作る人(班長・リーダー)、管理する人(品質保証課) |
| 見本の会社 |
「株式会社 早瀬精工」— 架空の会社。自動車・産業機械向けの精密部品(シャフト・フランジ・ブラケット)の切削加工と小組立。第1工場(旋盤班・マシニング班)・第2工場(組立班・検査・出荷班)・品質保証課、34名 |
プロダクトコンセプト
「急所が伝わる。聞けば、返ってくる。できる人が見える。」
手順書の主役は写真と急所。文字は「どこを見て、何をするか」と「なぜそうするか」をひとこと添えるだけ。現場の人は設備に貼ったQRコードからその手順を開き、分からないことはチャットで聞く。読んで、テストに受かって、現場で見てもらった記録が、そのまま力量表になる。
デモとしての成功条件
- 触った瞬間に「うちの工場で使える」と分かる — 空の画面が1つもなく、写真と急所の入った手順書が20本入っている(始業点検・チップの交換・ノギス・トルクレンチ・赤札など、町工場の誰もが知っている作業)
- 作るのが速い — 写真を3枚選び、矢印を描き、急所を書いて公開を依頼するまでが、初めての人でも3分でできる
- 聞けば返ってくる — 「チップを替えたら寸法がずれた」と聞くと、『チップ(刃物)の交換』の手順5「工具の補正を戻す」が写真と急所つきで返る
- 力量表で、休むと止まる作業が分かる — 旋盤班の「チップの交換」「試し削り」は一人でできる人が班長しかいない、と一目で分かる
- ロールで見え方が変わる — 作業者は自分の班に配られた手順書だけ、班長は自分の班の読まれ具合と力量表、品質保証は全体
- リセットできる — 誰が触った後でも、初期状態に戻せる
- 開いて5秒で何のアプリか分かる — スタートページで案内役が「工場の手順書係」と名乗り、写真・急所・質問・力量表の見本を見せてからアプリへ入る
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件)」「確からしさ」だけを渡すので、画面は変更しなくてよい。
// 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 |
| F-R12 |
わたしの力量(研修の画面に、一人でできる作業の数と、次に目指す作業) |
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 |
| F-D09 |
力量表(班の人×作業。読んだ・テスト合格は自動、「一人でできる」「教えられる」は班長が現場で見て付ける。一人でできる人が2人より少ない作業に印) |
Must |
質問と分析(班長・品質保証)
| 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. ロールとデモ切替
ロール定義
| ロール |
見本の人 |
できること |
見える範囲 |
| 作業者 |
佐々木 蓮(第1工場 旋盤班・入社3週間) |
読む・聞く・確認テスト・研修・わたしの力量を見る |
自分の班に配られた手順書と、全社公開の手順書だけ |
| 班長 |
石原 健一(旋盤班の班長) |
上のすべて+自分の班の手順書を作る・配る・読まれ具合と力量表を見る・力量表に「一人でできる」を付ける・自分の班の質問を見る |
自分の班と全社公開の手順書。読まれ具合と力量表は自分の班の人だけ |
| 品質保証 |
森下 由紀(品質保証課 課長) |
上のすべて+全部の班の手順書・公開の確認・全体の分析・研修の作成・全部の班の力量表 |
すべて |
見える範囲の判定は src/lib/repo/_scope.ts の1か所に集約する。 作業者が質問したときも、作業者に見えない手順書(ほかの班だけに配られたもの・下書き)を回答の根拠にしてはならない(answer/ に渡すのは _scope.ts を通した後の手順書だけ)。
デモ切替バー(F-S01)
画面の最上部に常に表示する、黒い細い帯(高さ 44px。PCでは上に固定)。
| 要素 |
内容 |
| 左 |
「デモ」の印と「これはデモです。入力した内容と写真・動画は、このブラウザの中にだけ保存されます」 |
| 中央 |
見え方の切り替え:作業者 / 班長 / 品質保証(名前と班も小さく出す) |
| 右 |
「使い方」(ガイドの再表示)・「デモをリセット」(確認ダイアログあり) |
スマホの幅では、中央を短い表記にし、右はアイコンだけにする。
ロールを跨ぐ体験(必ず動くようにする)
- 作って届ける — 班長で写真を3枚追加して手順を作り、矢印を描き急所を書いて公開を依頼 → 品質保証で確認して公開 → 班長で旋盤班の作業者に配る → 作業者のホームに「新しい手順書が届きました」が出る
- 読んで確かめる — 作業者で届いた手順書を最後まで読み「確認しました」→ 確認テストに合格 → 班長の読まれ具合で、佐々木さんが「合格」になる → 力量表の佐々木さんのそのマスが「テスト合格(△)」になる
- 聞いて返る — 作業者で「チップを替えたら寸法がずれた」と聞く → 『チップ(刃物)の交換』の手順5「工具の補正を戻す」が写真と急所つきで返る → 「この手順を開く」で該当の手順へ
- 答えられない質問が届く — 作業者で「エアコンの温度を変えたい」と聞く → 見つからないので「見つかりませんでした。班長に聞く」 → 班長の「答えられなかった質問」に出る → 「言いかえを登録」か「手順書を作る」へ進める
- 言いかえが効く — 班長で「ツールチェンジ」を「チップ(刃物)の交換」の言いかえに登録 → 作業者で「ツールチェンジのやり方」と聞くと、チップの交換が一番上に返る
- 見える範囲が違う — マシニング班だけに配られた「バイスでワークをつかむ(マシニング)」は、旋盤班の作業者には一覧にも質問の答えにも出ない。品質保証では見える
- QRで開く — 品質保証で「チップ(刃物)の交換」の手順3のQRを表示 → 「スマホで開く(デモ)」で作業者の画面のその手順が開く
- 案内役がそばにいる — 作業者で「チップ(刃物)の交換」の手順3を開く → 右下のかなめが「手順3で分からないことがあったら…」と話しかける → かなめを押して「ねじの締め方は?」と聞く → いま読んでいる手順書を優先して「新しい刃先にして締める」が一番上に返る
- 力量表で、休むと止まる作業が分かる — 班長で力量表を開く → 「チップ(刃物)の交換」「加工プログラムの呼び出しと試し削り」に「一人でできる 1人」の印。教えられる人と、次に教えられる(テスト合格の)人の名前が並ぶ → テスト合格の佐々木さんのマスを押して「一人でできるのを見た」→ 作業者の「わたしの力量」が1つ増える
5. 画面一覧とユーザーフロー
スタート
| ID |
画面 |
パス |
内容 |
| SC-000 |
スタートページ |
/ |
暗い画面の真ん中に案内役「かなめ」を大きく出し、3行の自己紹介を1文字ずつ話す(「はじめまして。工場の手順書係、かなめです。」「写真に急所を描いた手順書を届けて、質問にも答えます。」「だれがどの作業を一人でできるかも、ひと目で分かります。」「では、工場にご案内しますね。」)。2・3行目で見本のカード(書き込みつきの写真・急所・質問の答え・力量表)が浮かぶ。話し終わったら約5秒で、いまのロールのホームへ自動で移る。「飛ばして入る」「入る」「止める」と、別の見え方で入るボタン(班長・品質保証)。LP のような説明文は置かない |
作業者(読む・聞く)
| ID |
画面 |
パス |
内容 |
| SC-001 |
ホーム |
/home |
ダッシュボード(8章「ホームの配置」)。今日のハイライト(期限の近い届いた手順書)・大きな数字4つ(読んでいない・期限が近い・研修・今週聞いた)・案内役の入口「何を探しますか?」・届いた手順書・急所だけ拾い読み・研修の進み具合・班でよく見られている手順・お知らせ・最近見たもの |
| SC-010 |
手順書一覧 |
/manuals |
カテゴリのタブ(加工/検査/組立/安全・5S/設備保全/受入・出荷)・表紙の写真つきカード(題名・手順の数・所要時間・読んだ印・新着)・絞り込み(班・タグ・読んでいない) |
| 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 |
わたしの力量(一人でできる作業の数・次に目指す作業3つ)・自分に割り当てられた研修・順番に並んだ手順書・それぞれの状態(未・読んだ・合格)・期限 |
| 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 |
タブ「答えられなかった」「解決しなかった」「すべて」。質問・日時・班・返した手順・「言いかえを登録」「手順書を作る」「対応済み」 |
| SC-130 |
力量表 |
/studio/skills |
班の人×作業(その班に配られた公開中の手順書)の表。記号は ◎教えられる/○一人でできる/△テスト合格/・読んだ/空まだ(色と記号と文字で示す)。上に大きな数字3つ(一人でできる人が少ない作業・教えられる・この30日で付けた確認)。一人でできる人が2人より少ない作業は列ごと薄い赤にし、上の帯に「教えられる人」と「次に教えられる(△の)人」を並べる。マスを押すと「一人でできるのを見た」「人に教えられる」「確認を取り消す」。品質保証は班を切り替えて見られる |
品質保証
| 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の写真を開き、矢印でチャックハンドルを指し「ハンドルを外す」と文字を置く → 保存
→ 各手順に見出しを書く(「ドリルをチャックに付ける」「チャックハンドルを外す」「ワークを万力で固定する」)
→ 手順1に急所「ハンドルは必ず外してフックに掛ける」と、安全「回っているドリルに手を近づけない」
→ 言いかえに「ボール盤」「ドリルの穴あけ」→ 確認テストを1問 → 公開を依頼
品質保証:確認待ち → 開く → 公開する
班長:配る → 旋盤班の作業者全員・期限は1週間後 → 送る
作業者:ホームに「新しい手順書が届きました」→ 読む → 確認しました → テストに合格
班長:読まれ具合で佐々木さんが「合格」、力量表でその作業が「テスト合格(△)」
フロー2:現場で聞く(作業者)
作業者:ホームの案内役の入口「何を探しますか?」に「チップを替えたら寸法がずれた」と入れる
→ 「手順書を探しています…」(0.8秒)
→ 回答:「『チップ(刃物)の交換』の手順5『工具の補正を戻す』が近そうです。」
+ 手順5のカード(写真・見出し・説明の最初の2行・急所)+ 手順4のカード
→ 「この手順を開く」→ 手順5の画面
→ チャットに戻り「解決した」
フロー3:答えられない質問を手順書にする(作業者 → 班長)
作業者:「エアコンの温度を変えたい」→ 回答:「工場の手順書には見つかりませんでした。」+「班長に知らせる」
班長:質問 → 答えられなかった に1件 → 「手順書を作る」→ 題名に質問が入った下書き
フロー4:QRで開く(現場)
品質保証:「チップ(刃物)の交換」→ QRコード → 手順3「座面の切粉を吹き飛ばす」のQR → スマホで開く(デモ)
→ 作業者の画面で手順3が直接開く(ほかの手順へもめくれる)。旋盤の横に貼っておけば、刃物を替えるたびにその場で開ける
フロー6:力量表で、休むと止まる作業に手を打つ(班長 → 作業者)
班長:力量表 → 「一人でできる人が少ない作業 2作業」→ 「チップ(刃物)の交換」の列が薄い赤
→ 上の帯に「教えられる:石原 健一/次に教えられる(△):…」
→ テスト合格の佐々木さんのマスを押す → 「一人でできるのを見た」(現場で見てから付ける)
作業者:研修の「わたしの力量」で、一人でできる作業が1つ増える
フロー5:開いて、かなめに聞く(はじめての人)
スタートページ:かなめが4行で自己紹介 → 約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でマウスを乗せている間だけ区間を音なしでくり返す |
P1 |
| FR-112 |
ホームの大きな数字4つ(読んでいない・期限が近い(3日以内)・研修 n/N と進み具合の輪・今週聞いた)は、0から数え上がる。最終値の幅を先に取り、数え上がる間に周りが動かないこと |
P1 |
| FR-113 |
ホームに「急所だけ拾い読み」を横に並べる(6.11)。一覧の「動画あり」の絞り込みは、動画のある手順書があるときだけ出す |
P1 |
| FR-114 |
ホームのタイルは、そのセッションで初めて開いたときだけ60msずつずらして浮かび上がる。2回目からはすぐ出す |
P2 |
| FR-102 |
手順書一覧で、カテゴリ・班・タグ・「読んでいない」で絞り込めること。カードに表紙の写真・題名・手順の数・所要時間・読んだ印・新着(7日以内)を出すこと |
P1 |
| FR-103 |
手順書を読む画面で、スマホは手順を横にめくり(スワイプとボタンの両方)、PCは左に目次・右に本文を出すこと。いまの手順の番号と全体の数(3/8)を常に出すこと |
P1 |
| FR-104 |
手順の写真は書き込みを重ねて表示し、押すと全画面で拡大(指で拡大縮小)できること |
P1 |
| FR-105 |
手順の動画は、指定の区間だけを再生し、区間の終わりで止めること。「もう一度」「全部見る」を出すこと。自動再生はしない(音が出るため) |
P1 |
| FR-106 |
急所(黄と黒の縞の帯)と安全の注意(赤)を、説明と見分けがつく枠で出すこと。色だけでなく「急所」「なぜ」「安全」の文字と印を添えること(6.11) |
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文字まで)・急所の理由(120文字まで)・安全の注意(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 |
ひな形から作ると、型の手順の見出しだけが入った下書きができること(設備の始業点検:7手順/段取り替え:7手順/検査:6手順/安全の決まり:5手順) |
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つの手順につき、次の文字をまとめて探す対象にする:手順書の題名・タグ・言いかえ(重み3)/手順の見出し・手順の言いかえ(重み3)/手順の説明・安全の注意・急所・急所の理由(重み1)
- 文字の正規化:全角・半角、カタカナ・ひらがな、大文字・小文字をそろえ、記号と空白を除く。「〜ってどうやるの」「〜したい」「〜のやり方」「教えて」などの言い回し(
answer/phrases.ts に並べる)を質問から取り除く
- 言葉の分け方:日本語は単語の区切りがないため、**2文字ずつ区切った言葉(例:「検査灯」→「検査」「査灯」)**と、
answer/dictionary.ts の現場の言葉の辞書(「チップ」「クーラント」「合いマーク」など。約250語)に一致した言葉の両方を使う
- 同じ意味の言葉:
answer/synonyms.ts に「チップ=インサート=刃物=バイト」「切削油=クーラント=切削液」「0点=ゼロ点=ゼロ合わせ」のような組を持ち、質問の言葉を広げる(初期 68組)。手順書の言いかえ(FR-310)も同じ扱いにする
- 点数:BM25(よく使われる検索の点数の付け方。k1=1.2、b=0.75)に、上の重みを掛ける。同じ手順書の手順は最大2件までにし、ほかの手順書の手順も候補に残す
- 確からしさ:一番の点数が基準(初期:正規化した点数で 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 |
6.11 急所と理由・良品と不良品の比べ(製造版で足したもの)
製造の手順書は、手順の並びより急所で決まる。作業分解(TWI)の型にならい、手順ごとに「主なステップ(見出しと説明)」「急所(うまくいくか・けがをしないか・やりやすいかを分ける点)」「急所の理由(外すと何が起きるか)」を持つ。
| ID |
要件 |
優先度 |
| FR-1101 |
手順に急所(100文字まで)と急所の理由(120文字まで)を書けること。読む画面では、説明のすぐ下に、左に黄と黒の縞を付けた枠で「急所」(黒地に黄の文字の印)と「なぜ」を出すこと |
P1 |
| FR-1102 |
手順に、良品と不良品の写真を1組だけ持てること。読む画面では左右に並べ、「良品」(緑・チェックの印)「不良」(赤・×の印)と、それぞれの見分け方をひとことで出すこと |
P1 |
| FR-1103 |
安全の注意は、急所とは別に赤の枠で出すこと(けが・事故につながることだけ) |
P1 |
| FR-1104 |
質問の答えの手順のカードに、急所を1行出すこと(手順を開かなくても一番大事な点が分かるように) |
P1 |
| FR-1105 |
ホームの「急所だけ拾い読み」:まだ読んでいない手順書から、写真と書き込みのある急所を、1つの手順書から2つまで、最大12件並べる。押すとその手順を開く |
P1 |
| FR-1106 |
版の違い(FR-602)に、急所と急所の理由の変更も出すこと |
P1 |
| FR-1107 |
手順書のPDF(FR-109)に、急所となぜを入れること |
P2 |
6.12 力量表(製造版で足したもの)
「誰がどの作業を一人でできるか」は、品質の仕組み(力量の管理)の真ん中にある。紙やExcelの力量表は付けた人の記憶に頼り、更新されない。KANAME は、読んだ・確認テストに合格した、は手順書の記録から自動で入れ、「一人でできる」「教えられる」だけを班長が現場で見て付ける。
| 段階 |
記号 |
決まり方 |
| まだ |
(空) |
読んでいない |
| 読んだ |
・ |
最後まで読んで「確認しました」を押した(確認テストがある手順書で、まだ合格していない) |
| テスト合格 |
△ |
確認テストに合格した(テストのない手順書は、読んだらここ) |
| 一人でできる |
○ |
班長が現場で見て付けた |
| 教えられる |
◎ |
班長が現場で見て付けた(人に教えられる) |
| ID |
要件 |
優先度 |
| FR-1201 |
力量表(SC-130)は、班の人(班長・リーダー・作業者の順、同じ役割は入社の古い順)×その班に配られた公開中の手順書の表にすること。段階は src/lib/calc/skills.ts の関数で毎回算出し、保存しない(保存するのは「一人でできる」「教えられる」の確認の記録だけ) |
P1 |
| FR-1202 |
「一人でできる」以上の人が2人より少ない作業は、列を薄い赤にし、上の帯に作業名・一人でできる人数・教えられる人・次に教えられる(△の)人を並べること |
P1 |
| FR-1203 |
マスを押すと「一人でできるのを見た」「人に教えられる」「確認を取り消す」を選べること。テスト合格(△)になっていない人には付けられない(理由を出す)。付けた人と日付を残すこと |
P1 |
| FR-1204 |
付けられるのは、班長は自分の班の人だけ、品質保証はすべて。作業者は力量表を開けない |
P1 |
| FR-1205 |
作業者の研修の画面に「わたしの力量」(一人でできる作業の数/その班の作業の数・次に目指す作業3つ。段階の高い順)を出すこと |
P1 |
| FR-1206 |
品質保証は、班を切り替えて全部の班の力量表を見られること |
P1 |
| FR-1207 |
スマホでは、名前の列を細くし(顔の丸を出さない)、表を横に動かして見られること。名前の列は動かさない |
P1 |
7. データ設計
型定義(src/lib/types/)
export type Role = 'staff' | 'author' | 'hq'
export interface Site { id: string; name: string; kind: 'line' | 'hq'; plant: string } // 班(line)と品質保証課(hq)。plant は第1工場など
export interface Person { id: string; name: string; siteId: string; position: 'staff' | 'leader' | 'manager' | 'hq'; joinedAt: string }
export type Category = 'machining' | 'inspection' | 'assembly' | 'safety' | 'maintenance' | 'logistics'
// 加工/検査/組立/安全・5S/設備保全/受入・出荷
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 // 急所(作業分解の「急所」)
why: string // 急所の理由(外すと何が起きるか)
compare: { ok: MediaRef; ng: MediaRef; okLabel: string; ngLabel: string } | null // 良品と不良品の写真の比べ
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'
}
// 力量表:班長の実地確認(読んだ・テスト合格は記録から算出し、3と4だけを持つ)
export interface SignOff { personId: string; manualId: string; level: 3 | 4; by: string; at: string }
派生値は保存しない。 既読率・合格率・研修の進み具合・番号の書き込みの番号・古くなった印は、src/lib/calc/ の関数で毎回算出する。
シードデータ(src/lib/seed/)
| データ |
件数 |
内容 |
| 班 |
5 |
第1工場 旋盤班・マシニング班/第2工場 組立班・検査・出荷班/本社 品質保証課 |
| 人 |
34 |
各班7〜9名(班長1・リーダー1・作業者)・品質保証課2名。うち技能実習生4名(ベトナム)。名前は架空 |
| 手順書 |
20 |
下の一覧。公開中17・確認待ち1(試し削りの版3)・下書き1(ヒヤリハット)・差し戻し1(給油とグリスアップ)。マシニング班だけのもの1(4章 体験6) |
| 手順 |
111 |
1手順書あたり4〜7手順。すべての手順に写真と急所と理由がある。良品と不良品の比べ8か所 |
| 写真 |
127 |
111手順+比べの16枚。Cloudflare Workers AI(FLUX.2 [klein] 4B)で作った架空の工場の写真。手元と道具が主役で、人の顔は写さない |
| 確認テスト |
19本 |
1本2〜3問 |
| 配布と既読 |
— |
各班の既読率を 55〜95% にばらけさせる(旋盤班がいちばん低い=声かけの見せ場)。班長とリーダーは自分の班の手順書を読み終え、合格している |
| 力量表 |
— |
入社の古い人ほど「一人でできる」が多い。旋盤班の「チップの交換」「試し削り」は班長しか一人でできない(4章 体験9) |
| 研修 |
2 |
「新人教育(旋盤)」9本・「新人教育(組立)」8本。佐々木 蓮に「新人教育(旋盤)」を割り当て、3本合格済み |
| 質問の履歴 |
120件 |
直近8週。答えられなかったもの18件(同じ意味のまとまりで「エアコン」「有給」「残業の申請」が複数回) |
| 版の履歴 |
— |
4本の手順書に2〜3版の履歴(チップの交換は、不良が続いたので座面の手順を足した版3) |
手順書の一覧(題名・手順の数)
| 加工 |
検査 |
組立 |
安全・5S |
設備保全 |
受入・出荷 |
| CNC旋盤の始業点検 7 |
ノギスの0点合わせと測り方 6 |
トルクレンチでの本締め 7 |
保護具の着け方 5 |
給油とグリスアップ 5 |
材料の受け入れと先入れ先出し 5 |
| チップ(刃物)の交換 6 |
マイクロメータで外径を測る 6 |
ねじロック剤の塗り方 5 |
異常のときは「止める・呼ぶ・待つ」 5 |
— |
出荷前の梱包とラベル 6 |
| 加工プログラムの呼び出しと試し削り 6 |
初物検査と記録 6 |
バリ取りとエアブロー 5 |
不良品の識別と隔離(赤札) 5 |
— |
— |
| 切削油の濃度の測り方と補充 5 |
外観検査(キズ・打痕・バリ) 6 |
— |
ヒヤリハットの報告のしかた 4 |
— |
— |
| バイスでワークをつかむ(マシニング班のみ) 5 |
— |
— |
— |
— |
— |
| 切粉の片づけと終業時の清掃 6 |
— |
— |
— |
— |
— |
手順の中身は、町工場で実際に行われている一般的なやり方で書く(数値は見本の会社の決まりとして置く。例:切削油の濃度は5〜7%、M8は25N·m)。「法令対応済み」「認証に通る」のような言い方はしない。
写真の上の書き込み(矢印・丸・番号)を、シードの写真の6割以上に入れる。書き込みのない手順書は、このアプリの見せ場を伝えない。
見本の質問(src/lib/seed/sample-questions.ts):FR-508 のテストに使う40問。質問の文・期待する手順書・期待する手順を持つ。例:
| 質問 |
期待する手順書/手順 |
| 刃物の交換ってどうやるの |
チップ(刃物)の交換/手順1〜4 |
| インサートを替えたあとにやること |
チップ(刃物)の交換/手順5・6 |
| 冬の朝のウォーミングアップ |
CNC旋盤の始業点検/手順5「暖機運転をする」 |
| マイクロメーターで測るときの力加減 |
マイクロメータで外径を測る/手順3「ラチェットで3回空回りさせる」 |
| トルクレンチがカチッと鳴ったら |
トルクレンチでの本締め/手順5 |
| 不良を自分で直していい? |
不良品の識別と隔離(赤札)/手順4「勝手に手直ししない」 |
| 旋盤で手袋は使う? |
保護具の着け方/手順4「回る機械では手袋をしない」 |
| 古い材料から使う |
材料の受け入れと先入れ先出し/手順4・5 |
このテストは 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 |
安全の注意 |
#B4162E / #FEECEE |
--tip / --tip-bg |
急所の見出し・急所の地 |
#7A4500 / #FFF6D6(左に黄 #F5B700 と黒の縞 .hazard) |
--ok / --ng |
良品・合格/不良 |
#15803D・#DCFCE7 / #BE123C・#FFE4E6 |
| 書き込みの色 |
赤・黄・白 |
#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 |
写真(4:3)+急所の地(黄・縞)に急所となぜのカードを横に流す |
| 研修/よく見られている/お知らせ |
4×3 |
|
| 最近見たもの |
12 |
|
スマホは1列で、ハイライト → 案内役の入口 → 大きな数字(2列) → ほかの順。
- 手順の写真は 4:3 の枠に収め、縦長の写真は枠の中で切らずに左右に余白を入れる(写真を切り抜いて、書き込みが枠の外に出ることがないように)
- 読む画面(スマホ):上に手順の番号と見出し・写真は画面の幅いっぱい・下にめくるボタン(固定)
- 読む画面(PC):左に手順の目次(幅 280px)・右に本文(最大幅 760px)
- 編集の画面(PC):左に手順の目次(幅 260px)・中に編集(最大幅 720px)・右に基本情報(幅 320px)。幅 1100px 未満では右をタブにする
- 押せるものは 44×44px 以上
主要コンポーネント仕様
| コンポーネント |
仕様 |
ManualCard |
表紙の写真(16:10)・カテゴリ・題名(2行まで)・手順の数と所要時間・読んだ印/新着/期限 |
StepView |
番号の丸+見出し・写真(書き込みを重ねる)か動画・説明・急所となぜ(Tip)・良品と不良品(CompareView)・安全の注意(Caution) |
KeyPointCard |
急所だけ拾い読みのカード(写真・手順書名と番号・急所・なぜ) |
| 力量表のマス |
44px の四角。◎(紺の塗り・白)/○(薄い紺・紺の縁)/△(薄い黄・茶)/・(灰)/空(点線)。押すと選ぶ小窓(Radix Popover) |
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. 初期化
0-2. 型・シード・ストア
0-3. デザインシステム
Phase 1 — 写真と動画をそろえる(1日)
Phase 2 — 読む・確認テスト・QR(3日)
Phase 3 — 質問チャット(3日)
Phase 4 — 作る・書き込み(4日)
Phase 5 — 届ける・確かめる・分析(3日)
Phase 6 — 仕上げ(2日)
6-1. 体験の総点検
6-2. アクセシビリティ監査
6-3. パフォーマンス
6-4. テストと公開
合計 約18営業日(約3.5週間)/1名専任 + レビュー体制。
工数配分の意図: Phase 1 で写真と動画を先にそろえるのは、このアプリの見栄えと「聞けば返ってくる」の確かさが、どちらも中身(手順の写真と文章)で決まるため。中身が薄いと、検索をいくら調整しても良い答えは返らない。Phase 3 の質問チャットは、見本の質問40問のテストを先に書き、数字で合格するまで調整する。
12. 受入基準
- 6章の優先度 P1 の要件がすべて実装されていること
- 5章の主要フローが、最初から最後まで完走すること。フローと4章の体験に出てくる機能は、6章の優先度が P2・P3 でも必須とする
- 4章「ロールを跨ぐ体験」の7つがすべて動作すること
- ロールを切り替えると、一覧・ホーム・質問の答え・分析の表示範囲が変わること。スコープ判定が
src/lib/repo/_scope.ts に集約されていること
- 見本の質問40問のうち36問以上で、期待する手順が上位3件に入ること(
answer.test.ts)
- 回答の文章に、手順書に書かれていない手順や数字が含まれないこと
- 作業者に見えない手順書が、質問の回答に一度も出てこないこと
- 写真の書き込みが、320px〜2560px のどの幅でもずれないこと。ぼかしの下の元の写真が見えないこと
- 写真の追加(向きの補正・縮小)、動画の追加(区間の指定)、書き込み、公開、配る、読む、テスト、が1本の流れで動くこと
- 全画面のいずれにも空の状態がなく、すべての手順に写真があること
- リロード後も操作結果(追加した写真・動画を含む)が保持され、「デモをリセット」で初期状態に戻ること
- 手順書とQRのPDFが実際にダウンロードでき、日本語と書き込みが正しく出ること
- axe-core で Critical / Serious の指摘が0件であること
- Lighthouse の基準値を満たすこと
- データアクセスがすべて
src/lib/repo/ を経由しており、コンポーネントが Zustand ストアを直接参照していないこと
- スマホ(375px)で、読む・聞く・写真から手順を作る、が快適に使えること
- 案内役「かなめ」がスタートページ以外のすべての画面の右下にいて、話しかけ・その場の質問・表情の変化・ドラッグ・休ませる、が動くこと。答えの下に「かなめが手順書から探した答えです」が出ること
- スタートページで、かなめが「工場の手順書係」と名乗り、止めなければ約6秒でホームへ移ること
- すべての手順に急所と理由があり、良品と不良品の比べが8か所以上あること
- 力量表で、旋盤班の「チップの交換」「試し削り」が一人でできる人の少ない作業として出て、テスト合格の人に「一人でできる」を付けると作業者の「わたしの力量」に反映されること
判断に迷ったときのルール
- 仕様がこの文書にない場合は、実装せずに質問する。 推測で作らない
- 「聞けば返ってくる」の確かさと「空の画面を作らない」は削減対象外。 速度を出すために削らない
- スコープ外(3章 Won't have)は、思いついても実装しない。特に生成AIへの接続(費用ゼロの方針)
- 「デモだから」を理由に品質を落とす判断はしない
- コンポーネントからストアを直接触りたくなったら、それはリポジトリ層に足りないメソッドがあるということ
- 迷ったら、夜勤明けの朝、チップを替えたら寸法が合わなくなって困っている入社3週間の作業者を思い浮かべる。 班長は別の機械の段取り中。その人が油の付いた手袋のままタブレットで聞いて、10秒で答えにたどり着けるか
- 答えをでっち上げない。 見つからないときは「見つかりませんでした」と正直に返し、班長に知らせる道を出す。それが手順書を育てる入口になる
- 写真を暗くしない、写真の上に利用者が描いたもの以外を重ねない
- 案内役は見た目のキャラクター。 答えはいつも手順書の検索から作る。かなめに、手順書にないことを言わせない