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

**版数** 1.0（DBレス構成のデモ）／ **作成日** 2026-10-05 ／ **発行** ソウゾウ合同会社
**用途** 業種特化アプリの実演デモ ／ 運輸・物流向け「運行管理の記録」

---

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

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

- 実装は「11. 実装タスク」の順に進める。フェーズを飛ばさない。
- 仕様に書かれていないことは推測で作らず質問する。質問できない状況では「判断に迷ったときのルール」で決め、`docs/DECISIONS.md` に1行ずつ残す。
- 3章の「作らないもの」は、思いついても作らない。
- 「デモだから」を理由に品質を落とさない。
- **運送会社の言葉で書く。** 画面の文言は、運行管理者とドライバーが毎日使っている言葉に合わせる（点呼・業務前／業務後・点呼執行者・アルコール検知器・酒気帯び・日常点検・荷主・積込み／取卸し・荷待ち・荷役・附帯業務・拘束時間・休息期間・運転日報・点呼記録簿・営業所・車番）。「ユーザー」「タスク」「ステータス」「レコード」を画面に出さない。

> **このアプリが選ばれる理由**
> 運送会社には、毎日残さなければならない記録が多い。点呼記録簿、アルコール検知器での確認、日常点検、運転日報、そして2025年4月からは全車両で荷待ち・荷役の記録。それぞれ紙とExcelに分かれていて、ドライバーは同じことを何度も書き、運行管理者は月末に「誰の何が抜けているか」を探す。
> WADACHI は、**ドライバーが1日の流れに沿ってスマホで1回入力すれば、義務の記録がそろう**ようにする。運行管理者は、未実施の人と、荷待ちの長い荷主だけを見ればよい。記録は**いつもの様式のまま**PDFとExcelで出せる。
> ドライバーが同じ内容を2回入力する、管理者が抜けを探すのに画面を3つ以上開く、出した帳票が自社の様式と違う、のどれか1つでもあれば失敗とみなす。

---

## 課題定義

| 項目 | 内容 |
|---|---|
| 誰に刺すか | 運送会社の運行管理者（紙・Excelの記録に追われている） |
| 場面 | 毎朝・毎晩の点呼、月末の記録簿の整理、監査（運輸局の監査・指導）の前 |
| 課題（ギャップ） | ドライバーの1回の入力で、点呼・アルコールチェック・日常点検・日報・荷待ちの記録がそろい、運行管理者は未実施の人だけ見ればよい状態にする |
| 見る前の感情 | 「アプリは高そう」「うちの様式には合わないだろう」「監査が来たら不安」 |
| 見た後の感情 | 「これならうちの様式のままいける」「紙をやめられそう」「一度相談したい」 |
| 見せ場（必ず見せる） | ①ドライバーのスマホで、業務前点呼→日常点検→荷待ち開始／終了→業務後点呼・日報が1回の流れで終わる ②運行管理者の画面で、点呼の未実施と荷待ちの長い荷主が一目で分かる ③点呼記録簿と運転日報が、いつもの様式でPDF・Excelに出る |
| 既製品で足りる部分／作る価値 | アルコールチェック単体は既製品で十分（無料アプリもある）。点呼・日報・荷待ちを1回の入力でそろえ、自社の様式で出せるのが作る価値 |
| 言わないこと | 「法令対応済み」「監査に通る」／「IT点呼・遠隔点呼ができる」／拘束時間の正式な判定（表示は目安） |

---

# 1. プロジェクト概要

## 背景

- 荷待ち・荷役等の記録（集貨地点、到着・出発時刻、積込み・取卸しの開始・終了、荷役作業の内容、荷主の確認）は、2025年4月から**全車両**が対象になった（国交省）。乗務記録は1年保存。
- 白ナンバーの事業所も、2023年12月からアルコール検知器での確認と、その記録の1年保存が義務（警察庁）。
- トラック運転者の拘束時間は、2024年4月から原則 年3,300時間・月284時間（厚労省 改善基準告示）。
- 検索されているのは「運転日報 テンプレート」「点呼記録簿 エクセル」で、「点呼 アプリ」はほとんど検索されていない＝点呼はまだ紙とExcelで回っている。

## プロダクト定義

| 項目 | 内容 |
|---|---|
| プロダクト名 | WADACHI（わだち）※仮称。車が通ったあとに残る跡＝記録 |
| 一言定義 | ドライバーの1回の入力で、点呼・アルコールチェック・日常点検・荷待ち・運転日報がそろう運行管理の記録アプリ |
| 提供形態 | レスポンシブWebアプリ。ドライバーはスマホ、運行管理者はPC。**フロントエンド完結（サーバー側の保存なし）** |
| 見本の会社 | しろかね運送株式会社（架空）本社営業所。トラック8台・ドライバー10名・荷主6社（すべて架空） |

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

1. ドライバー画面だけで、業務前点呼から日報の提出までを**3分以内**に通せる（荷待ちは「時計を進める」で待たずに試せる）
2. ドライバーが入力した点呼が、管理者画面の「今日の点呼」に**すぐ**出る（同じブラウザ内で役割を切り替えて確かめられる）
3. 点呼記録簿は国交省の様式例と同じ欄の並びで、PDF（A4横）とExcel（.xlsx）に出る
4. 様式の設定で欄の名前・並び・表示を変えると、プレビューとPDF・Excelの両方が変わる
5. 375／768／1024／1280px の幅で、横はみ出し・文字の切れ・リンク切れがない

---

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

- 見本データは「今日」を基準に**決まった乱数で毎回同じものを組み立てる**（過去60日分）。保存しない。
- 保存するのは、見本から**変わった分だけ**（新しい記録・確認・様式の設定）。localStorage に置く（Zustand persist、`partialize` で差分だけ）。写真は IndexedDB。
- 画面はストアを直接触らず `src/lib/repo/` を通す。本番ではここを API に差し替える。
- **デモの時計**：`now()` は実時刻＋「時計を進めた分」。荷待ちを30分待たずに試すため、デモ切替バーから「時計を15分進める」ができる。記録の時刻はすべて `now()` で付ける。
- 判断の計算（拘束時間・荷待ち時間・未実施の判定・荷主別の集計）は `src/lib/calc/` の純粋関数にして、テストを書く。

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

1. 運行管理者が監査の前に困らないほうを選ぶ（記録を消さない・直したら履歴を残す）
2. ドライバーの入力が1つでも減るほうを選ぶ（前の画面で入れたものは聞き直さない）
3. 法令の解釈が必要なものは「目安」と書いて、断定しない

---

# 3. スコープ

## 作るもの

**ドライバー（スマホ）**
- 今日の業務：車番・行き先・今日の流れ（業務前点呼→日常点検→運行→業務後点呼→日報）と、次にやること
- 業務前点呼：アルコール検知器の数値・検知器の写真・体調（疾病・疲労・睡眠不足）・睡眠時間・点呼方法・管理者からの指示事項の確認
- 日常点検：1項目1タップ。「異常あり」のときだけ内容を書く
- 運行：今日の行き先（荷主・場所）ごとに「到着」「荷待ち開始」「積込み／取卸し開始」「終了」「出発」の大きなボタン。休憩。荷役作業の内容と荷主の確認の有無
- 業務後点呼：検知器の数値・写真・自動車／道路／運行の状況・交替運転者への通告
- 運転日報：ここまでの入力から**自動で埋まる**。ドライバーが入れるのはメーターの数値（出庫・帰庫）と特記事項だけ。提出
- 過去の記録（自分の分）

**運行管理者（PC）**
- 今日の点呼：全ドライバーの業務前／業務後の済・未・確認待ち。検知器の数値が0でない人・点検に異常がある人を先頭に。確認（点呼執行者の記名）
- 荷待ち：荷主別の荷待ち時間（平均・30分以上の回数・合計）の順位と、1件ずつの記録。荷主別にExcelで出す
- 拘束時間：ドライバーごとの今月の拘束時間と、月284時間（原則）までの残り。**目安**の表示
- 記録簿の出力：点呼記録簿（1日1枚）と運転日報（1人1日1枚）を、期間を選んでPDF・Excelに
- 様式の設定：会社名・営業所名・欄の名前・欄の並び・表示する欄・確認印の欄。プレビューつき
- ドライバー・車両・荷主の一覧

**共通**
- デモ切替バー（ドライバー3名／運行管理者・時計を進める・デモをリセット）
- はじめの画面（このデモで何ができるか・役割を選ぶ）

## 作らないもの（Won't have）

- 配車（案件×ドライバー×日付）→ 2本目のデモで扱う
- 拘束時間・休息期間の詳しい計算・特例（分割休息・2人乗務・フェリー等）→ 3本目で扱う
- IT点呼・遠隔点呼、アルコール検知器との機器連携（デモは手入力と写真）
- ログイン・権限・サーバーへの保存・メール通知
- 地図・位置情報

---

# 4. 役割とデモ切替

| 役割 | 画面 | 見本の人 |
|---|---|---|
| ドライバー | スマホ（/d） | 佐藤 健一（2号車・4t）※今日はまだ何もしていない＝流れを最初から試せる／高橋 翔（5号車）※荷待ち中／中村 大輔（7号車）※業務前点呼が確認待ち |
| 運行管理者 | PC（/m） | 山本 恵子（運行管理者）・補助者 1名 |

- 役割を切り替えたら、その役割の最初の画面へ移る。
- ドライバー画面をPCで開いたときは、中央にスマホ幅（最大 480px）で出す。

---

# 5. 画面一覧

| パス | 画面 | 役割 |
|---|---|---|
| / | はじめに（何ができるか・役割を選ぶ） | 共通 |
| /d | 今日の業務 | ドライバー |
| /d/tenko/before | 業務前点呼 | ドライバー |
| /d/inspection | 日常点検 | ドライバー |
| /d/run | 運行（荷待ち・荷役の記録） | ドライバー |
| /d/tenko/after | 業務後点呼 | ドライバー |
| /d/report | 運転日報（確認して提出） | ドライバー |
| /d/history | 過去の記録 | ドライバー |
| /m | 今日の点呼 | 管理者 |
| /m/waiting | 荷待ち（荷主別） | 管理者 |
| /m/hours | 拘束時間 | 管理者 |
| /m/books | 記録簿の出力 | 管理者 |
| /m/forms | 様式の設定 | 管理者 |
| /m/master | ドライバー・車両・荷主 | 管理者 |

---

# 6. 機能要件

## 6.1 1回の入力でそろう（このデモの心臓部）

| 入力したところ | そろう記録 |
|---|---|
| 業務前点呼 | 点呼記録簿（業務前の欄）・アルコールチェックの記録・運転日報の「始業時刻」 |
| 日常点検 | 点呼記録簿の「日常点検の状況」・日常点検の記録 |
| 運行（到着・荷待ち・荷役・出発） | 乗務記録の荷待ち・荷役の欄・運転日報の「行き先・積荷・荷待ち」・荷主別の集計 |
| 業務後点呼 | 点呼記録簿（業務後の欄）・アルコールチェックの記録・運転日報の「終業時刻」・拘束時間 |
| 日報（メーター） | 運転日報の走行距離 |

- 日報の画面では、**自動で入った欄に印（「点呼から」「運行から」）を付けて**見せる。
- 同じ内容を2回聞かない。業務後点呼では「日常点検の状況」を聞き直さない。

## 6.2 点呼

- 点呼の欄は国交省「点呼記録簿」の様式例に合わせる：
  - 業務前：運転者名・車両番号・実施日時・点呼方法・点呼執行者・アルコール検知器の使用の有無・酒気帯びの有無・疾病／疲労／睡眠不足等の状況・日常点検の状況・その他必要な指示事項
  - 業務後：実施日時・点呼方法・点呼執行者・アルコール検知器の使用の有無・酒気帯びの有無・自動車／道路及び運行の状況・交替運転者に対する通告・その他必要な指示事項
- 検知器の数値（mg/L、小数2桁）。0.00 より大きい値は「酒気帯びの疑い」として赤で出し、**送信はできるが管理者の画面の先頭に出る**。デモでは乗務させない旨の案内を出す（判定は会社の規程による、と書く）。
- 写真：カメラで撮る／見本の写真を使う（数値を表示した検知器の絵を自動で描く。画像生成は使わない）。
- 点呼方法：対面／電話／その他。デモでは「対面」が既定。**IT点呼は選択肢に出さない。**
- ドライバーが送ると「確認待ち」。管理者が確認すると、点呼執行者に管理者の名前が入る。ドライバーの画面にも「山本さんが確認しました」と出る。

## 6.3 日常点検

- 項目は事業用トラックの日常点検の項目（ブレーキ・タイヤ・灯火・ワイパー・エンジン・バッテリー等）から15項目。1項目1タップ（良／異常）。「全部良」を一度に付けるボタンは**付けない**（見ずに押すのを防ぐ）。
- 異常のときは内容を書く。管理者の画面に出る。

## 6.4 荷待ち・荷役

- 今日の行き先（荷主・集貨地点等・積込み／取卸し）が並ぶ。行き先ごとに、状態に応じたボタンが1つだけ大きく出る：到着 → 荷待ち開始 → 積込み（取卸し）開始 → 終了 → 出発。荷待ちが無ければ「荷待ち開始」を飛ばせる。
- 進行中は経過時間を大きく表示（デモの時計で進む）。荷待ちが30分を超えたら色を変え「30分以上は記録の対象です」と出す。
- 終了時：荷役作業の内容（積込み・取卸し・附帯業務の種類）、荷主の確認が得られたか（得た／得られなかった）。
- 時刻はあとから直せる。直したら「修正」の印と、元の時刻を残す。

## 6.5 運行管理者：今日の点呼

- ドライバーごとに1行。業務前・日常点検・業務後・日報の4つの丸（済・確認待ち・未・異常）。
- 並び順：①酒気帯びの疑い ②点検の異常 ③確認待ち ④未実施 ⑤済。上の要約に「確認待ち 2・未実施 3・異常 1」。
- 行を開くと点呼の内容と写真。「確認する」で点呼執行者として記名。

## 6.6 荷待ち（荷主別）

- 期間（直近30日・今月・先月）。荷主ごとに、平均の荷待ち時間・30分以上の回数・合計時間・件数。長い順。棒で見せる。
- 荷主を開くと1件ずつ（日付・ドライバー・集貨地点・到着・荷待ち・荷役・出発）。Excelで出す。
- 文言は「改善の相談の材料に」まで。「荷主に請求できる」などは書かない。

## 6.7 拘束時間（目安）

- 1日の拘束時間＝業務前点呼の時刻から業務後点呼の時刻まで（このデモの単純化。DECISIONS に残す）。
- 今月の合計と、月284時間までの残り。月末までの見込み（ここまでの1日平均×残りの出勤予定日）。
- 1日13時間を超えた日の数。表示はすべて「目安」。正式な判定は改善基準告示による、と画面に書く。

## 6.8 記録簿の出力・様式

- 点呼記録簿：1日1枚（A4横）。上に会社名・営業所名・日付。表は国交省の様式例の欄の並び。下に確認印の欄（設定で 0〜3個）。
- 運転日報：1人1日1枚（A4縦）。始業・終業・走行距離・行き先ごとの到着／荷待ち／荷役／出発・休憩・特記事項・点呼の要約。
- Excel：同じ内容を .xlsx で（1日1シート、欄の幅・罫線・見出しの太字つき）。
- 様式の設定：欄ごとに「表示する／しない」「名前」「並び（上下ボタン）」。会社名・営業所名・確認印の名前。設定はプレビュー・PDF・Excel に同じように効く。「元の様式（国交省の例）に戻す」。

---

# 7. データ設計（要点）

```ts
Driver { id, name, kana, vehicleId, license, hiredAt }
Vehicle { id, no /* 車番 */, label /* 2号車 */, kind /* 4t 等 */ }
Shipper { id, name, site /* 集貨地点等 */ }
Trip /* 1人1日の業務 */ { id, date, driverId, vehicleId, stops: Stop[], meterStart?, meterEnd?, note?, reportSubmittedAt? }
Stop { id, shipperId, kind: 'load'|'unload', arrivedAt?, waitStart?, waitEnd?, workStart?, workEnd?, departedAt?, workKind?, shipperConfirmed?, edits: Edit[] }
Tenko { id, tripId, phase: 'before'|'after', at, method, alcohol: number, detectorUsed: true, photoKey?, health?, sleepHours?, instructions?, roadReport?, handover?, confirmedBy?, confirmedAt? }
Inspection { id, tripId, at, items: { key, ok: boolean, note? }[] }
FormSettings { company, office, tenkoColumns: Col[], reportColumns: Col[], stamps: string[] }
```

- 記録はすべて id を持つ（差分保存のため必須）。
- 日付のまとめは日本時間で行う（ISO文字列の先頭10文字はUTC）。

---

# 8. デザイン要件

- 世界観：**「夜明けの車庫」**。点呼は早朝と夜。濃い藍の面（道路標識の青）と、白い紙のような記録の面。荷待ちだけは信号の琥珀色で目立たせる。
- 色：藍 #1D4E89（ブランド・白文字 7:1 以上）／墨 #141C26／地 #F3F4F1／琥珀 #B86E00（荷待ち。文字用は濃く）／済 #146132／異常 #9A2E22。安全色は WCAG を満たす濃さで使う。
- 数字は等幅（tabular-nums）。時刻・数値は大きく。
- ドライバー画面：親指で押せる大きさ（ボタンの高さ 56px 以上）・片手・手袋でも押せる余白。
- 管理者画面：一覧の密度を上げ、異常だけが色を持つ。
- 写真は使わない（画像生成なし）。ロゴ・検知器の絵・空の状態の絵は SVG で描く。

# 9. 技術

Vite 6 ＋ React 19 ＋ React Router 7（SPA）＋ Tailwind CSS 4 ＋ Zustand 5 ＋ idb-keyval ＋ @react-pdf/renderer（日本語は Noto Sans JP）＋ fflate（Excel の組み立て）＋ Vitest ＋ Playwright。Cloudflare Workers の静的配信（`not_found_handling: single-page-application`）。

# 10. 非機能

- 初期表示の JS は gzip 後 200KB 以下を目標（PDF・Excel は押したときに読み込む）。
- アクセシビリティ：axe で重大0。色だけで状態を伝えない（丸の中に文字・記号）。
- 本番で使うには、4つ（データの保存とバックアップ・ログインと権限・記録とアカウント管理・公開の設定）が要る。デモの画面にも同じ言い方で書く。

# 11. 実装タスク

## Phase 1 — 土台と見本データ

- 型（7章）・見本データ（決まった乱数・62日分・今日は途中の状態）・ストア（差分だけ保存）・デモの時計
- 計算関数（未実施の判定・荷待ち時間・拘束時間・荷主別の集計）とテスト

## Phase 2 — ドライバーの画面

- 今日の業務 → 業務前点呼 → 日常点検 → 運行（荷待ち・荷役）→ 業務後点呼 → 運転日報 → 過去の記録
- 自動で入った欄には「点呼から」「運行から」の印を付ける

## Phase 3 — 運行管理者の画面

- 今日の点呼（確認）→ 荷待ち（荷主別）→ 拘束時間（目安）→ ドライバー・車両・荷主の一覧

## Phase 4 — 記録簿の出力と様式の設定

- 点呼記録簿・運転日報のプレビュー・PDF（A4）・Excel（.xlsx）
- 様式の設定（欄の名前・並び・表示・確認印）がプレビュー・PDF・Excel のすべてに効く

## Phase 5 — 仕上げと検査

- はじめに・デモ切替バー・ロゴ・OGP
- E2E（ドライバーの流れ→管理者で確認→PDF・Excel）・幅 375/768/1024/1280 の横はみ出し・axe

# 12. 受入基準

- [ ] 佐藤さんで業務前点呼から日報の提出まで通せ、管理者の「今日の点呼」で済になる
- [ ] 検知器 0.05 を入れると、管理者の画面の先頭に赤で出る
- [ ] 荷待ちを開始して時計を30分進めると、30分以上の色に変わる
- [ ] 日報の始業・終業・行き先・荷待ちが、入力なしで埋まっている
- [ ] 点呼記録簿のPDF・Excelが国交省の様式例の欄の並びで出る。様式の設定で欄を隠すと両方から消える
- [ ] 荷主別の荷待ちの順位が出て、荷主ごとにExcelで出せる
- [ ] 「法令対応済み」「監査に通る」「IT点呼」の文言が画面のどこにもない

# 出典

- 国交省｜令和7年4月から荷待時間等の記録義務の対象が全車両に拡大 https://www.mlit.go.jp/jidosha/content/001865382.pdf
- 国交省｜乗務記録の記載対象となる荷待時間・荷役作業等 https://www.mlit.go.jp/jidosha/jidosha_fr4_000026.html
- 国交省｜点呼記録簿の様式例 https://www.mlit.go.jp/jidosha/jidosha_tk2_000162.html
- 警察庁｜安全運転管理者の業務の拡充等 https://www.npa.go.jp/bureau/traffic/insyu/index-2.html
- 厚労省｜トラック運転者の改善基準告示 https://driver-roudou-jikan.mhlw.go.jp/truck/notice


---

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

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

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

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

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

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