TSUGITE — 要件定義書 兼 Claude Code 実装指示書
版数 1.0(DBレス構成)/ 作成日 2026-09-30 / 発行 ソウゾウ合同会社
用途 業種特化アプリの実演デモ / リフォーム・工務店向け 顧客・見積・工事管理編
このドキュメントの使い方(Claude Code へ)
これ1枚が、規約・仕様・タスクのすべて。リポジトリ直下に CLAUDE.md として置き、毎回読み込むこと。
- 実装は「11. 実装タスク」の順に進める。フェーズを飛ばさない。
- 各タスクの括弧内は要件ID。着手前に該当章を読むこと。
- 仕様がここに書かれていない場合は、推測で実装せず質問する。
- スコープ外(3章 Won't have)は、思いついても実装しない。
- 「デモだから」を理由に品質を落とす判断はしない。
- リフォーム・工務店の言葉で書く。 画面の文言・項目名・並び順・帳票は、この業種の人が毎日使っている言葉と順番に合わせる。汎用の顧客管理の言葉(「リード」「商談」「アカウント」など)に置き換えない。
このアプリが「業種特化」であることの意味
汎用の顧客管理は、無料〜月数千円のサービスがすでに多くある。TSUGITE がそれらと並べて選ばれる理由は、開いた瞬間に「これはうちの仕事のために作られている」と分かることだけである。
項目・言葉・流れ・帳票・ダッシュボードの数字がリフォーム・工務店のものになっていない画面は、1つでもあれば失敗とみなす。
目次
- プロジェクト概要
- アーキテクチャ方針 — データベースを持たない
- スコープ定義
- ロールとデモ切替
- 画面一覧とユーザーフロー
- 機能要件
- データ設計
- デザイン要件
- 技術要件・ディレクトリ構成
- 非機能要件
- 実装タスク
- 受入基準
1. プロジェクト概要
背景と目的
地域のリフォーム会社・工務店(社員5〜40名規模)の多くは、問い合わせをノートとExcelで受け、見積は表計算で作り、工程はホワイトボード、工事の写真は担当者のスマホの中にある。見積の段階で粗利が薄いことに気づかないまま契約し、追加工事の請求を忘れ、同じ職人を同じ日に2つの現場へ入れてしまう。引渡し後の点検の連絡も途切れ、OBのお客様からの次の依頼を逃す。
汎用の顧客管理を入れても、「原価と粗利のある見積」「工程表」「工事写真の台帳」がないため、結局Excelとホワイトボードに戻る。TSUGITE は、問い合わせから現地調査・見積・契約・工程・写真・入金・アフター点検までを、リフォームの現場の順番と言葉のまま1つにつなぐ。
| 目的 |
内容 |
| 業種特化の実装力の証明 |
原価と粗利のある見積、工程表、写真台帳という、リフォームに固有の業務を画面にする |
| 利益を守る設計の証明 |
見積の粗利率・実行予算との差・追加工事の請求漏れを、システム側から知らせる |
| 現場で使える操作性の証明 |
現地調査・日報・写真はスマホで、見積・工程は事務所のPCで、同じデータを扱う |
| 横展開の資産化 |
共通の土台(ロール・一覧・設定・帳票)に、業種の部分だけを載せる構造にする |
プロダクト定義
| 項目 |
内容 |
| プロダクト名 |
TSUGITE(つぎて)※仮称。木材をつなぐ「継手」から |
| 一言定義 |
見積の粗利から、工程・写真・アフター点検まで。リフォーム会社のための顧客・工事管理 |
| 提供形態 |
レスポンシブWebアプリ。フロントエンド完結(サーバー側の保存なし) |
| 主戦場 |
事務所のPC(見積・工程・請求)と、現場のスマホ(現地調査・写真・日報) |
| 想定利用者 |
リフォーム会社・工務店の営業兼現場の担当、工事責任者、社長・事務 |
プロダクトコンセプト
「利益は、見積で決まる。信頼は、写真で残る。」
リフォームの利益は見積を出した時点でほぼ決まり、お客様の信頼は工事の途中と完了の写真で積み上がる。TSUGITE は、見積の画面で粗利を常に見せ、現場の写真を工事の記録と報告書にそのままつなぐことを設計の中心に置く。
デモとしての成功条件
- 触った瞬間に「リフォーム・工務店の仕事で使える」と分かる — 空の画面が1つもなく、リフォーム・工務店らしいリアルなデータが入っている
- 速い — 一覧の絞り込み、状態の変更、対応記録が、待たされずに終わる
- ロールで見え方が変わる — 担当は自分の担当、工事責任者はチーム全体。権限の設計ができていることを示す
- 業種の言葉でできている — 項目・段階・帳票・ダッシュボードの数字が、リフォーム・工務店のものになっている
- リセットできる — 誰が触った後でも、初期状態に戻せる
2. アーキテクチャ方針 — データベースを持たない
基本方針
バックエンドとデータベースを持たない。すべてブラウザ内で完結させる。
| 一般的な構成 |
本プロジェクト |
| PostgreSQL / Supabase |
シードデータ(TypeScript)+ ブラウザ内ストア |
| 認証・SSO |
デモ用ロール切替(ワンクリック) |
| REST / GraphQL API |
ストア上の操作(リポジトリ層) |
| メール送信・SMS |
送信内容のプレビュー表示で再現 |
| PDF生成(サーバー側) |
ブラウザ内で生成し、実際にダウンロードできる |
| CSVインポート/エクスポート |
実際に動く。 ブラウザ内で読み込み/書き出しする |
| 画像のアップロード |
写真を扱う業種のみ。ブラウザ内で縮小して IndexedDB に保持する(7章「画像」) |
なぜこの構成にするか
- デモとして最適 — 訪問者は登録もログインもせずに、全機能を即座に触れる
- 顧客データを一切預からない — 入力されたデータはブラウザから出ない。自社のCSVを投入して試すこともできる
- 開発速度 — 認証・権限のサーバー実装・マイグレーションが不要になり、業種の作り込みと操作効率に全時間を投下できる
- 運用コストゼロ — 静的配信のみ
差し替え可能性の担保(重要)
データアクセスは必ず src/lib/repo/ のリポジトリ層を経由すること。 コンポーネントからストアを直接触らない。
[ 画面・コンポーネント ]
↓ 呼ぶのはこの層だけ
[ src/lib/repo/*.ts ] ← 全メソッドを async にしておく
↓
[ src/lib/store/*.ts ] ← Zustand + persist(localStorage)
↓
[ src/lib/seed/*.ts ] ← 初期データ
リポジトリの各メソッドは、中身が同期処理でも async で定義し、await で呼ぶ。本番化する際は、リポジトリの実装だけをデータベースへの問い合わせに差し替えれば、画面は一行も変更せずに済む。
// src/lib/repo/works.ts — 中身は同期でも async にする
export async function findWorks(q: Query): Promise<Result<WorkView[]>> {
await delay('list')
const all = useDataStore.getState().works
return { ok: true, data: scopeWorks(filterAndSort(all, q)).map(toView) } // 本番化でここが問い合わせになる
}
永続化の範囲
| 対象 |
挙動 |
| シードデータ |
初期投入。以降は編集可能 |
| ユーザーの操作結果(登録・編集・状態変更・対応記録・タスク) |
localStorage に保存。リロードしても保持される |
| CSVインポートしたデータ |
localStorage に保存される |
| 画像(写真) |
写真を扱う業種のみ。長辺1280pxに縮小しJPEG品質0.8、1枚200KB以下に収めて IndexedDB に保存する(localStorage は5MB程度しかなく、写真を20枚ほどで使い切るため)。レコードには写真のIDだけを持つ |
| リセット |
デモ切替バーの「デモをリセット」で localStorage と IndexedDB(写真)を空にし、初期状態へ |
擬似的な非同期を必ず入れること。 リポジトリの各操作に 150〜400ms のディレイを挟み、読み込み中の状態を実際に見せる。ただし一覧の絞り込み・並び替えは 100ms 以下にする(体感速度が価値のため)。
ストアの容量に注意。 localStorage は5MB程度しか使えない。シードの写真はファイル(public/)を参照させて保存しない。ユーザーが追加した写真だけを IndexedDB に保存し、リセット時は IndexedDB も空にする。
3. スコープ定義
問い合わせ・お客様
| ID |
機能 |
概要 |
優先度 |
| F-C01 |
問い合わせの受付 |
電話・チラシ・ホームページ・紹介・OBのお客様からの問い合わせを登録し、現地調査の予定までつなぐ |
Must |
| F-C02 |
お客様一覧 |
テーブル表示、絞り込み、並び替え、列の選択、保存ビュー |
Must |
| F-C03 |
お客様詳細 |
基本情報、建物の情報、工事の履歴(OBなら過去の工事)、対応履歴、点検の予定 |
Must |
| F-C04 |
建物の情報 |
住まいの種類(戸建て・マンション)、築年、構造、延床面積、過去の改修 |
Must |
現地調査
| ID |
機能 |
概要 |
優先度 |
| F-V01 |
現地調査の予定 |
カレンダーで予定を入れる |
Must |
| F-V02 |
現地調査の記録 |
スマホで、部位ごとの写真・採寸のメモ・劣化の状態・要望を記録する |
Must |
見積
| ID |
機能 |
概要 |
優先度 |
| F-E01 |
見積の作成 |
工種(解体・木工事・内装・設備・電気・左官・塗装・諸経費 など)ごとの明細。行ごとに原価と売価 |
Must |
| F-E02 |
粗利の表示 |
行・工種・合計の粗利と粗利率を常に表示。目標の粗利率を下回ると警告 |
Must |
| F-E03 |
見積のひな形 |
よくある工事(ユニットバスの交換・キッチンの交換・外壁の塗装・トイレの交換 など)のひな形から作る |
Must |
| F-E04 |
案の比較 |
1つの工事に複数の案(松・竹・梅 など)を持ち、並べて比べる |
Should |
| F-E05 |
見積書PDF |
お客様に出す見積書(原価・粗利は出さない) |
Must |
工事(契約〜引渡し)
| ID |
機能 |
概要 |
優先度 |
| F-W01 |
工事ボード |
段階別の列表示(カンバン)。問い合わせ〜アフターまで |
Must |
| F-W02 |
工事詳細 |
段階バー、契約の金額と支払条件、工程、写真、日報、実行予算、追加工事、入金 |
Must |
| F-W03 |
工程表 |
工種ごとのバー(ガント)。協力業者・職人の割当。ドラッグで日程を変える |
Must |
| F-W04 |
職人の重なりの警告 |
同じ職人・協力業者が同じ日に2つの現場に入っていると警告 |
Must |
| F-W05 |
追加・変更工事 |
追加の見積を作り、承認されると契約の金額に加える。請求の漏れを防ぐ |
Must |
| F-W06 |
実行予算 |
見積の原価・協力業者への発注額・追加の原価から、最終の粗利を見込む |
Should |
現場の記録
| ID |
機能 |
概要 |
優先度 |
| F-P01 |
工事写真の台帳 |
着工前・施工中・完了を、部位ごとに撮って並べる。前後の比較 |
Must |
| F-P02 |
作業日報 |
スマホで、その日の作業・人工(にんく)・写真・気づいたこと |
Must |
| F-P03 |
工事完了報告書 |
部位ごとの着工前・完了の写真を並べた報告書(PDF) |
Must |
入金・アフター
| ID |
機能 |
概要 |
優先度 |
| F-M01 |
支払条件と入金予定 |
着手金・中間金・完工金の割合から入金予定を作り、入金を記録する |
Must |
| F-M02 |
請求書PDF |
適格請求書の記載事項を満たした請求書 |
Must |
| F-A01 |
アフター点検 |
引渡しからの点検のタスクを、点検のルール(既定:1か月・1年・2年。外壁・屋根の工事は5年も)で自動で作る |
Must |
| F-A02 |
OBのお客様 |
過去に工事をしたお客様を、築年・前回の工事からの年数・工事の種類から、次の提案の候補として並べる |
Should |
分析
| ID |
機能 |
概要 |
優先度 |
| F-R01 |
ダッシュボード |
稼働中の現場、今週の予定(現地調査・着工・完工)、見積の提出待ち、未入金、粗利が目標を下回る工事、点検の予定 |
Must |
| F-R02 |
粗利の分析 |
工事の種類別・担当者別の粗利率、見積時と完了時の差 |
Should |
| F-R03 |
受注の分析 |
問い合わせの経路別の 現地調査→見積→契約 の歩留まり、見積から契約までの日数 |
Should |
| F-R04 |
協力業者の稼働 |
協力業者ごとの予定の埋まり具合、発注額 |
Could |
共通・基盤
| ID |
機能 |
概要 |
優先度 |
| F-S01 |
ロール切替 |
担当/工事責任者/管理者をワンクリックで切替。切替バーは常時表示 |
Must |
| F-S02 |
横断検索 |
お客様・工事・見積・協力業者を横断検索。ヘッダーから常時アクセス |
Must |
| F-S03 |
コマンドパレット |
⌘K / Ctrl+K で検索・画面遷移・新規作成を呼び出す |
Must |
| F-S04 |
通知センター |
担当の割当、期限の接近、放置のアラート、上長からの差し戻し、業種の通知 |
Must |
| F-S05 |
保存ビュー |
絞り込み条件 + 表示列 + 並び順を名前を付けて保存。個人/共有を選択 |
Must |
| F-S06 |
デモリセット |
localStorage と IndexedDB(写真)を空にして初期状態に戻す |
Must |
| F-S07 |
ガイドツアー |
初回訪問時に「何を試せるか」を3ステップで案内 |
Should |
| F-S08 |
CSV入出力 |
お客様の取り込み(列の対応付け・プレビュー・エラー行の表示)と、一覧の書き出し |
Must |
| F-S09 |
カスタム項目 |
お客様・工事に独自の項目を画面から追加できる |
Should |
| F-S10 |
操作ログ |
誰が・いつ・何を変えたかの履歴 |
Could |
対象外(Won't have)
| 項目 |
理由 |
| 図面・3Dのパースの作成 |
専用のソフトの領域 |
| 工事請負契約書の作成 |
法定の記載事項があるため。契約の金額・支払条件の管理までを対象とする |
| 協力業者がログインする画面・受発注のやり取り |
発注の記録と、送る文面のコピーで再現する |
| 資材の在庫管理・仕入れの発注 |
対象外 |
| 会計ソフトとの連携・給与の計算 |
CSVの書き出しで代替 |
| 住宅ローン・補助金の申請の代行 |
補助金の名前と申請の締切をメモできるだけにする |
| データベース・バックエンドAPI |
2章の方針に基づく |
| 本物の認証・SSO |
ロール切替で代替 |
| 実際のメール・SMS・LINEの送受信 |
送信内容のプレビューで再現 |
| 外部カレンダー連携(Google / Outlook) |
予定は内部で保持。.ics のダウンロードのみ対応 |
| ワークフローの自由な組み立て(ノーコードのビルダー) |
固定ルールのみ実装 |
| 帳票レイアウトの自由編集 |
決まった帳票のみ。ロゴ・会社情報・備考の差し替えだけ対応 |
| モバイルのネイティブアプリ |
レスポンシブWebで対応 |
| 複数ブラウザ間でのデータ共有 |
各ブラウザで独立。デモとして問題ない |
スコープリスク: 業務システムは「あれもこれも」が最も起きやすい領域。特にワークフローのビルダーと帳票の自由レイアウト編集は、単体で数週間かかる。要望が出た場合は別フェーズとして見積り、この文書のスコープは変えない。
4. ロールとデモ切替
ロール定義
| ロールID |
名称 |
見えるデータ |
特徴的な権限 |
staff |
担当 |
自分が担当するお客様・工事と、全協力業者 |
現地調査・見積・日報・写真の登録、自分の工事の工程の変更。見積の原価は見られるが、会社全体の粗利の分析は見られない |
manager |
工事責任者 |
自チーム(リフォーム課・新築課)の全員の工事 |
見積の承認(目標の粗利率を下回るものは承認が必要)、工程の調整、職人の割当、共有ビューの作成 |
admin |
管理者 |
会社のすべて |
設定(見積のひな形・工種・目標の粗利率・支払条件・点検のルール)、協力業者の管理、入金の確定、メンバー管理 |
協力業者は全員が見える。 職人の予定は会社全体で共有しないと重なりが防げないため。見える範囲を絞るのは「お客様」と「工事」だけにする。
認証は行わない。ロールはストアの状態として保持し、切替バーから即座に変更できる。
データスコープ(デモの見せ場)
ロールによって同じ画面の表示件数が変わることを、明確に体験させる。
- 担当(中村・リフォーム課)で工事ボードを開く → 自分の工事 21件
- 工事責任者(リフォーム課)に切替 → 同じ画面が課の全体の 74件になり、担当者の絞り込みと「承認待ちの見積」が出現する
- 管理者に切替 → 会社全体 160件。設定メニューと、粗利の分析が出現する
スコープの適用は src/lib/repo/_scope.ts に集約し、全リポジトリメソッドが必ず通す。コンポーネント側でフィルタしない(本番化でデータベース側の権限設定に置き換わる箇所であるため)。
デモ切替バー(F-S01)
画面上部に常時表示する固定バー。
- 現在のロールと操作中の人の名前の表示、3ロールの切替
- 担当ロール時:3名のメンバーから選択(見え方の違いを体験できる)
- 「デモをリセット」ボタン(確認ダイアログ付き)
- 「これはデモです。入力した内容はこのブラウザの中にだけ保存されます」の明示
デザイン上の扱い: プロダクト本体のUIとは意図的に別扱い(墨色の帯 + 小さめの文字)にし、「アプリの外側にある操作パネル」であることを視覚的に区別する。スマホでは1行に収め、ロール名はアイコン+短い名前にする。
ロールを跨ぐ体験(必ず動くようにする)
- 担当が見積を作り、粗利率が目標(既定25%)を下回った状態で「提出する」を押す → 提出ではなく「承認待ち」になり、工事責任者に切替 → 承認待ちの一覧に理由(粗利率 21.4%)つきで現れる
- 工事責任者が工程表で大工の「(架空)田島工務」を、別の現場と同じ日に割り当てる → 重なりの警告が出て、担当に切替 → 自分の工事の工程にも警告の印がついている
- 担当が追加工事(手すりの取り付け)の見積を作り、お客様の承認を記録する → 契約の金額が増え、「追加工事(手すり)」の入金予定が作られ、管理者の未入金の見込みが変わる
- 管理者が工事を「引渡し済み」にする → 1か月・1年・2年の点検のタスクが担当に自動で作られ、ダッシュボードの点検の予定に並ぶ
- 管理者が見積のひな形「ユニットバスの交換」の原価を変える → 次に作る見積に新しい原価が入る(作成済みの見積は変わらない)
5. 画面一覧とユーザーフロー
全44画面。画面IDはディレクトリ構成と 1:1 で対応させる。
メイン画面
| 画面ID |
画面名 |
パス |
主要要素 |
| SC-001 |
ダッシュボード |
/ |
稼働中の現場、今週の予定、見積の提出待ち・承認待ち、未入金、粗利が目標を下回る工事、点検の予定 |
| SC-010 |
問い合わせの受付 |
モーダル |
お客様(新規・既存)、経路、要望、現地調査の候補日 |
| SC-020 |
お客様一覧 |
/customers |
テーブル、絞り込み(地域・築年・OB)、列の選択、保存ビュー、一括操作、CSV入出力 |
| SC-021 |
お客様詳細 |
/customers/:id |
基本情報、建物の情報、工事の履歴、対応履歴、点検の予定 |
| SC-022 |
お客様の新規作成 |
/customers/new |
フォーム。電話・住所の重複を入力中に検出 |
| SC-023 |
CSVインポート |
/customers/import |
ファイル選択 → 列の対応付け → プレビュー → 取込結果 |
| SC-030 |
工事ボード |
/works |
段階の列、ドラッグ、列ごとの件数・契約金額 |
| SC-031 |
工事一覧(表) |
/works?view=table |
ボードと同じデータの表形式 |
| SC-032 |
工事詳細 |
/works/:id |
段階バー、概要、契約と支払条件、工程、写真、日報、実行予算、追加工事、入金 |
| SC-033 |
失注の登録 |
モーダル |
失注の理由(他社に決定・予算が合わない・時期の延期・連絡がとれない など) |
| SC-040 |
現地調査の予定 |
/surveys |
日・週のカレンダー、担当別 |
| SC-041 |
現地調査の記録 |
/surveys/:id |
部位ごとの写真・採寸・劣化の状態・要望(スマホ優先) |
| SC-050 |
見積の一覧 |
/estimates |
状態(作成中/承認待ち/提出済み/契約/失注)、粗利率 |
| SC-051 |
見積の作成・編集 |
/estimates/:id |
工種ごとの明細、原価・売価・粗利、合計、ひな形の読み込み、案の切替 |
| SC-052 |
案の比較 |
/estimates/:id/compare |
松・竹・梅を並べて金額・内容・粗利を比べる |
| SC-053 |
見積書プレビュー |
モーダル |
お客様向けのレイアウト(原価なし)→ PDF |
| SC-060 |
工程表 |
/schedule |
全現場の工程(ガント)、協力業者の行・現場の行の切替、重なりの警告 |
| SC-061 |
工事ごとの工程 |
/works/:id/schedule |
工種ごとのバー、職人の割当、ドラッグ |
| SC-070 |
工事写真の台帳 |
/works/:id/photos |
部位 × 時点(着工前・施工中・完了)、前後の比較 |
| SC-071 |
作業日報 |
/daily |
日付 × 現場、作業・人工・写真(スマホ優先) |
| SC-072 |
工事完了報告書 |
モーダル |
部位ごとの着工前・完了の写真 → PDF |
| SC-080 |
入金 |
/payments |
入金予定(着手金・中間金・完工金・追加)、入金の記録、未入金 |
| SC-081 |
請求書プレビュー |
モーダル |
適格請求書のレイアウト → PDF |
| SC-090 |
協力業者 |
/partners |
協力業者の一覧、工種、連絡先、予定の埋まり具合 |
| SC-091 |
アフター点検 |
/aftercare |
点検の予定(1か月・1年・2年 …)、OBのお客様の次の提案の候補 |
| SC-095 |
タスク |
/tasks |
期限別、点検・入金・承認のタスク |
| SC-096 |
対応履歴 |
/activities |
全対応のタイムライン |
分析画面
| 画面ID |
画面名 |
パス |
主要要素 |
| SC-100 |
粗利の分析 |
/analytics/profit |
工事の種類別・担当者別の粗利率、見積時と完了時の差(管理者) |
| SC-101 |
受注の分析 |
/analytics/orders |
経路別の歩留まり(問い合わせ→現地調査→見積→契約)、見積から契約までの日数 |
| SC-102 |
協力業者の稼働 |
/analytics/partners |
協力業者 × 週の埋まり具合、発注額 |
| SC-103 |
失注の分析 |
/analytics/lost |
失注の理由、段階別の失注率 |
設定画面(管理者のみ)
| 画面ID |
画面名 |
パス |
主要要素 |
| SC-200 |
設定トップ |
/settings |
設定項目の一覧 |
| SC-201 |
カスタム項目 |
/settings/fields |
対象(お客様/工事)、型、選択肢、必須、並び順 |
| SC-202 |
工事の段階 |
/settings/stages |
段階の追加・名称変更・並び替え |
| SC-203 |
メンバー・チーム |
/settings/members |
メンバー一覧、ロール変更、チーム編成 |
| SC-204 |
タグ |
/settings/tags |
タグの追加・色・使用件数 |
| SC-205 |
文面テンプレート |
/settings/templates |
連絡文のひな形、差し込み変数 |
| SC-206 |
会社情報・帳票 |
/settings/company |
会社名・住所・ロゴ・印影・振込先(帳票に差し込む) |
| SC-207 |
操作ログ |
/settings/logs |
変更履歴の検索 |
| SC-208 |
工種と見積のひな形 |
/settings/estimate-templates |
工種の一覧、よくある工事のひな形(明細・原価・売価) |
| SC-209 |
目標の粗利率・承認 |
/settings/margin |
目標の粗利率(既定25%)、下回ったときに承認を必要にするか |
| SC-210 |
支払条件 |
/settings/payment-terms |
着手金・中間金・完工金の割合の既定(金額の大きさ別) |
| SC-211 |
点検のルール |
/settings/aftercare |
引渡しからの点検の時期(1か月・1年・2年・5年)、工事の種類ごと |
| SC-212 |
協力業者 |
/settings/partners |
協力業者の登録・工種・単価の目安 |
主要フロー
フローA:問い合わせから現地調査・見積の提出まで
【ロール:担当(中村)】
SC-010 問い合わせの受付 ── 新規のお客様、経路「チラシ」、要望「浴室が寒い。ユニットバスを交換したい」
現地調査の候補日:土曜 10時
↓ ★ お客様・工事(段階:問い合わせ)・現地調査の予定が作られる
SC-041 現地調査の記録(スマホ)── 浴室・脱衣所の写真、採寸(1616サイズ)、劣化「土台の一部に腐れの疑い」
↓
SC-051 見積の作成 ── ひな形「ユニットバスの交換」を読み込む → 解体・設備・電気・内装の明細が並ぶ
土台の補修(木工事)を追加 → 行ごとに原価と売価を入れる
↓ ★ 粗利率が画面の右上に常に出る(例 21.4%。目標25%を下回るため警告)
案を2つ作る(竹:標準グレード/松:断熱強化) → SC-052 案の比較
↓
「提出する」→ 粗利率が目標未満のため「承認待ち」に
↓
【ロール切替:工事責任者】承認待ちの一覧 → 内容を見て承認
↓
【ロール切替:担当】SC-053 見積書プレビュー(原価なし)→ PDF → 「提出済み」
フローB:契約から工程・写真・引渡し・点検まで
【ロール:担当】
SC-032 工事詳細 ── 段階を「契約」へ。契約の金額・支払条件(着手金30%・完工金70%)を入れる
↓ ★ 入金予定が自動で作られる
SC-061 工事ごとの工程 ── 解体 → 土台の補修 → 設備 → 電気 → 内装 を並べ、協力業者を割り当てる
↓ ★ 同じ日に別の現場へ入っている職人がいると警告
段階を「着工」へ → SC-070 写真の台帳に「着工前」の写真を撮る
↓
SC-071 作業日報(スマホ)── 毎日の作業・人工・写真
↓
追加工事:手すりの取り付け → 追加の見積 → お客様の承認を記録 → 契約の金額に加算、追加工事の入金予定ができる
↓
段階を「完工」へ → 写真の台帳に「完了」の写真
↓
SC-072 工事完了報告書(着工前・完了の写真を部位ごとに並べる)→ PDF
↓
段階を「引渡し済み」へ → SC-081 請求書(完工金+追加)→ PDF
↓ ★ 1か月・1年・2年の点検のタスクが自動で作られる
SC-080 入金の記録(担当)→【ロール切替:管理者】入金の確定 → 未入金が消える
フローC:職人の重なりの解消(工事責任者の週次の調整)
【ロール:工事責任者】
SC-001 ダッシュボード ──「工程の重なり 2件」
↓
SC-060 工程表(協力業者の行)── 大工「田島工務」の行で、木曜に2つの現場のバーが重なって赤い印
↓
片方のバーを金曜へドラッグ → 警告が消える
↓ ★ その工事の担当に「工程が変わりました」の通知
フローD:OBのお客様への次の提案
【ロール:管理者】
SC-091 アフター点検 ── 今月の点検の予定 8件、「次の提案の候補」(FR-273 の条件:例 外壁の塗装から10年以上)
↓
候補のお客様を選ぶ → 文面テンプレート「外壁の点検のご案内」で文面を作ってコピー
↓
対応記録に残る → 反応があれば、そのまま問い合わせの受付(SC-010)へ
フローE:Excelからの移行(CSVインポート)
SC-020 お客様一覧 ──「インポート」→ 列の対応付け(「施主名」→お客様名、「築年」→建物の築年 …)
↓
プレビュー → 取込実行 → 成功 176件 / スキップ 4件
6. 機能要件
各要件は判定可能な粒度で記述している。テスト項目と 1:1 で対応させる。
6.1 ロール・デモ基盤
| ID |
要件 |
優先 |
| FR-001 |
画面上部の固定バーから、3ロール(担当/工事責任者/管理者)をワンクリックで切り替えられること |
P1 |
| FR-002 |
担当ロールでは、3名のメンバーから操作する人を選択できること |
P1 |
| FR-003 |
「デモをリセット」で localStorage と IndexedDB(写真)を空にし、確認ダイアログを経て初期状態に戻ること |
P1 |
| FR-004 |
操作結果はブラウザをリロードしても保持されること |
P1 |
| FR-005 |
データスコープは src/lib/repo/_scope.ts に集約し、全リポジトリメソッドが必ず通すこと。コンポーネント側でロールによるフィルタを行わないこと |
P1 |
| FR-006 |
担当は自分の担当のみ、工事責任者は自チーム、管理者は会社全体のレコードが見えること |
P1 |
| FR-007 |
権限外の操作を試みた場合、ボタンを非活性にし、理由をツールチップで示すこと。実行してからエラーを出さないこと |
P1 |
| FR-008 |
ロール権限外の画面(担当で /settings)にアクセスした場合、案内画面からロール切替できること。素の404を出さないこと |
P1 |
| FR-009 |
初回訪問時に3ステップのガイドツアーを表示し、「今後表示しない」を選択できること。ツアーを閉じても別の画面へ飛ばさないこと |
P2 |
| FR-010 |
リポジトリ層の各操作は 150〜400ms の擬似ディレイを持つこと。ただし一覧の絞り込み・並び替えは 100ms 以下とすること |
P1 |
6.2 一覧・検索・ビュー(業務システムの中核)
| ID |
要件 |
優先 |
| FR-101 |
一覧テーブルは、表示する列をユーザーが選択・並び替えできること。設定は保持されること |
P1 |
| FR-102 |
各列でソートでき、複数列でのソート(第1キー・第2キー)に対応すること |
P2 |
| FR-103 |
絞り込みは項目ごとの条件指定(等しい/含む/以上/以下/期間/空である)に対応すること |
P1 |
| FR-104 |
絞り込み条件はURLのクエリに反映し、リロード・URL共有で同一結果を再現できること |
P1 |
| FR-105 |
適用中の絞り込み条件をチップで一覧表示し、個別に解除できること |
P1 |
| FR-106 |
絞り込み条件 + 表示列 + 並び順を「ビュー」として名前を付けて保存できること。個人ビューと共有ビュー(工事責任者以上が作成)を区別すること |
P1 |
| FR-107 |
保存ビューはサイドバーに一覧表示し、ワンクリックで切り替えられること。件数バッジを表示すること |
P1 |
| FR-108 |
行のチェックボックス選択で一括操作(担当変更/タグ付与/状態変更)ができること。全選択・絞り込み結果全件選択に対応すること |
P1 |
| FR-109 |
一括操作の実行前に、対象件数と操作内容の確認ダイアログを表示すること |
P1 |
| FR-110 |
削除操作は取り消し可能なトースト(5秒間「元に戻す」を表示)とすること |
P1 |
| FR-111 |
ヘッダーの横断検索から、お客様・工事・見積・協力業者を横断検索できること。種別ごとにグループ化して結果を表示すること |
P1 |
| FR-112 |
⌘K / Ctrl+K でコマンドパレットを開き、検索・画面遷移・新規作成を実行できること |
P1 |
| FR-113 |
一覧の行数が多い場合も描画がもたつかないこと(仮想スクロールを実装すること) |
P2 |
| FR-114 |
一覧の行の高さを「標準(44px)/コンパクト(34px)」で切り替えられること |
P2 |
| FR-115 |
テーブル上でセルを直接編集できること(インライン編集)。Enterで確定、Escで取消、Tabで次のセルへ移動すること |
P2 |
| FR-116 |
スマホ幅では、テーブルをカード型のリストに切り替えること。 横スクロールのテーブルをスマホで見せない |
P1 |
6.3 お客様・CSV・共通部品
| ID |
要件 |
優先 |
| FR-151 |
お客様の詳細で、基本情報の各項目をクリックしてその場で編集できること(インライン編集) |
P1 |
| FR-152 |
お客様の新規作成時、氏名(または会社名)・電話番号の入力中に既存レコードとの類似を検出し、重複候補を警告表示すること |
P2 |
| FR-153 |
CSVインポートで、列の対応付け(自動推測 + 手動修正)、プレビュー、エラー行の理由表示、部分取込 ができること |
P1 |
| FR-154 |
インポート結果を「成功N件/スキップN件(理由別内訳)」で表示し、取り込んだレコードに実行日時のタグを自動付与すること |
P1 |
| FR-155 |
現在の絞り込み条件・表示列のままCSVを書き出せ、実際にファイルがダウンロードされること。Excelで文字化けしないよう BOM付きUTF-8 で出力すること |
P1 |
| FR-156 |
対応記録(電話・訪問・現地調査・見積の説明・現場・メールなど)を、一覧画面や詳細画面から遷移せずにモーダルで記録できること |
P1 |
| FR-157 |
対応記録時に「次にやること」と期限を入力すると、タスクが自動生成され、関連レコードに紐づくこと |
P1 |
| FR-158 |
タスクを「期限超過/今日/今週/今後/完了」でグルーピング表示し、チェックのワンクリックで完了・取り消しできること |
P1 |
| FR-159 |
工事責任者は他メンバーにタスクを割り当てられること。割当時、対象者の通知に配信されること |
P1 |
| FR-160 |
文面テンプレートを選択し、差し込み変数({{お客様名}} {{自分の氏名}} など)を置換して本文を生成できること。「コピー」で本文をクリップボードに入れ、同時に対応記録に残すこと |
P2 |
6.4 帳票(PDF)共通
| ID |
要件 |
優先 |
| FR-171 |
帳票はプレビューを印刷レイアウトで表示し、実際にPDFをダウンロードできること |
P1 |
| FR-172 |
帳票には会社情報(会社名・住所・電話・ロゴ・印影)を差し込み、設定画面(SC-206)の変更が即座に反映されること |
P1 |
| FR-173 |
帳票の日本語が文字化け・欠けしないこと(日本語フォントを埋め込む。9章) |
P1 |
| FR-174 |
金額は3桁区切り、日付は和暦ではなく西暦(2026年10月1日)で表記すること。和暦が慣習の帳票だけ例外として明記する |
P1 |
6.5 お客様・問い合わせ
| ID |
要件 |
優先 |
| FR-201 |
お客様に、氏名・フリガナ・電話・携帯・メール・住所(市区町村 + 以降)・連絡してよい時間帯・問い合わせの経路・担当・チーム・OBかどうか・タグ・メモ を登録できること |
P1 |
| FR-202 |
お客様ごとに建物の情報(種類:戸建て/マンション、築年、構造:木造/鉄骨/RC、延床面積、過去の改修)を持てること |
P1 |
| FR-203 |
問い合わせの受付モーダルから、お客様(新規・既存の検索)・経路・要望・現地調査の候補日を入れると、お客様・工事・現地調査の予定がまとめて作られること |
P1 |
| FR-204 |
お客様詳細に、建物の情報・工事の履歴・対応履歴・点検の予定 をタブで表示すること |
P1 |
6.6 現地調査
| ID |
要件 |
優先 |
| FR-211 |
現地調査の予定を日・週のカレンダーで表示し、担当者ごとの列で見られること。.ics をダウンロードできること |
P1 |
| FR-212 |
現地調査の記録は、部位(浴室・キッチン・トイレ・洗面・外壁・屋根・居室 など)ごとに、写真・採寸のメモ・劣化の状態(良/注意/要補修)・お客様の要望 を記録できること |
P1 |
| FR-213 |
現地調査の記録はスマホで片手で入力できること。写真はカメラから直接撮れ(<input type="file" accept="image/*" capture="environment">)、ブラウザ内で縮小して保持すること |
P1 |
| FR-214 |
現地調査の記録から、見積の作成へそのまま進めること(部位からひな形を提案する) |
P2 |
6.7 見積(TSUGITE の中核)
| ID |
要件 |
優先 |
| FR-221 |
見積の明細は、工種 → 行 の2段で持ち、行ごとに 品名・仕様・数量・単位・原価の単価・売価の単価 を入れられること。行の並び替えはドラッグとキーボードの両方でできること |
P1 |
| FR-222 |
行・工種・合計のそれぞれで、原価・売価・粗利・粗利率を入力のたびに即座に再計算すること。計算は src/lib/calc/estimate.ts に置くこと |
P1 |
| FR-223 |
合計の粗利率を画面の上部に常に表示し、目標の粗利率(SC-209)を下回ると --warn の印と「目標まであと ◯円」を出すこと |
P1 |
| FR-224 |
目標の粗利率を下回る見積を「提出する」と、工事責任者の承認待ちになること(設定で承認を必要にしている場合)。承認・差し戻しは理由つきで通知すること |
P1 |
| FR-225 |
見積のひな形(SC-208)から明細を読み込めること。読み込んだ後の変更は、ひな形に影響しないこと |
P1 |
| FR-226 |
諸経費は「工事の合計に対する割合」または「金額」で入れられること |
P1 |
| FR-227 |
値引きは合計に対して入れられ、値引き後の粗利率を表示すること |
P1 |
| FR-228 |
1つの工事に最大3つの案を持て、案の比較画面で金額・内容・粗利率を横に並べられること |
P2 |
| FR-229 |
見積書PDFは、お客様名・工事名・工事の場所・有効期限・工種ごとの小計と明細・値引き・消費税・合計・備考・会社情報を載せ、原価・粗利は載せないこと |
P1 |
| FR-230 |
見積の状態(作成中/承認待ち/提出済み/契約/失注)を持つこと |
P1 |
計算のテスト: 原価 70,000円・売価 100,000円の行 → 粗利 30,000円・粗利率 30.0%。値引きは売価からのみ引き、原価は変えない。消費税は値引き後の合計に対して計算し、1円未満は切り捨て(設定で変更可)。
6.8 工事(契約〜引渡し)
| ID |
要件 |
優先 |
| FR-231 |
工事の段階は、問い合わせ/現地調査/見積作成中/見積提出済み(ここまで進行中)/契約/着工準備/着工/完工/引渡し済み(ここまで受注=won)/アフター(after)/失注(lost)とすること(設定で名称変更・並び替え可) |
P1 |
| FR-232 |
工事ボードで段階を列に並べ、各列に件数と契約金額の合計を出すこと。ドラッグとキーボードの両方で段階を変えられること |
P1 |
| FR-233 |
段階を「契約」に進めるとき、契約の金額(採用した案)と支払条件を入れさせること。支払条件は設定(SC-210)の既定から選べること |
P1 |
| FR-234 |
契約すると、支払条件から入金予定(着手金:契約日、中間金:工期の中間日、完工金:引渡し日 を既定)を自動で作ること |
P1 |
| FR-235 |
追加・変更工事は、追加の見積として作り、お客様の承認を記録すると契約の金額に加算し、「追加工事(◯◯)」の入金予定を別に作ること(入金日の既定は引渡し日)。承認されていない追加工事は、工事詳細に「未承認の追加 ◯件」と出すこと |
P1 |
| FR-236 |
実行予算として、見積の原価・協力業者への発注額(工種ごと)・追加工事の原価を並べ、見込みの最終の粗利と粗利率を出すこと。見積時より5ポイント以上下がった工事に --warn の印を付けること |
P2 |
| FR-237 |
最後の動きから既定10日(設定で変更可)経った「見積提出済み」の工事に「返事待ちが長い」の印を付けること |
P1 |
| FR-238 |
失注の登録時に理由(他社に決定/予算が合わない/時期の延期/連絡がとれない/その他)を複数選択 + 自由記述で入れられること |
P1 |
6.9 工程表
| ID |
要件 |
優先 |
| FR-241 |
工程表は、工事ごとの工種のバーを日付の軸に並べるガントとし、外部のガントのライブラリを使わず自前で作ること(CSS Grid。日の列、週末の網かけ、今日の縦線) |
P1 |
| FR-242 |
バーはドラッグで移動・伸び縮みでき、キーボード(バーを選んで ←→ で1日移動、Shift + ←→ で長さを変える)でも同じことができること |
P1 |
| FR-243 |
バーに協力業者(と職人の名前)を割り当てられること |
P1 |
| FR-244 |
同じ協力業者が同じ日に2つ以上の現場に入っている場合、両方のバーに重なりの警告(--alert + アイコン + 文字)を出すこと。 判定は src/lib/calc/schedule.ts に置き、テストを書くこと |
P1 |
| FR-245 |
全現場の工程表で、「現場の行」と「協力業者の行」を切り替えられること。協力業者の行では、その業者の予定の埋まり具合が一目で分かること |
P1 |
| FR-246 |
工程を変えたとき、その工事の担当と、割り当てた協力業者の欄に変更の記録を残し、担当に通知すること。重なりが生まれたときは、重なった両方の工事の担当に通知すること |
P1 |
| FR-247 |
工程表のスマホの表示は、今日から2週間を縦に並べたリスト(日ごとの現場と工種)に切り替えること |
P1 |
6.10 写真・日報・報告書
| ID |
要件 |
優先 |
| FR-251 |
工事写真の台帳は、部位 × 時点(着工前/施工中/完了)で写真を並べ、写真ごとに撮った日・部位・メモを持つこと |
P1 |
| FR-252 |
同じ部位の着工前と完了を、左右に並べて比べられること(スマホでは上下) |
P1 |
| FR-253 |
作業日報は、日付・現場・作業の内容・人工(0.5人工単位、協力業者ごと)・写真・気づいたこと を記録できること。スマホで1分で書けること(前日の内容を下書きに使える) |
P1 |
| FR-254 |
工事完了報告書(PDF)は、表紙(お客様名・工事名・工期・担当・会社情報)と、部位ごとの着工前・完了の写真を並べたページで作ること |
P1 |
| FR-255 |
追加した写真は1枚200KB以下に収めて IndexedDB に保存し、ブラウザが使える容量(navigator.storage.estimate())の8割を超えたら警告すること |
P1 |
6.11 入金・請求
| ID |
要件 |
優先 |
| FR-261 |
入金の画面で、入金予定(着手金・中間金・完工金・追加工事)を予定日順に並べ、入金を記録できること。予定日を過ぎた未入金に --alert の印を付けること |
P1 |
| FR-262 |
請求書は適格請求書の記載事項を満たすこと:発行する会社の名称と登録番号(Tから始まる番号。シードは架空)・取引の年月日・取引の内容・税率ごとに区分した合計額と適用税率・税率ごとの消費税額・受け取るお客様の名前 |
P1 |
| FR-263 |
入金の記録(入金日・金額)は担当もできるが、確定は管理者だけができること。確定されるまでは「確認待ち」と表示し、未入金の集計からは外さないこと |
P1 |
6.12 アフター点検・OBのお客様
| ID |
要件 |
優先 |
| FR-271 |
工事を「引渡し済み」にすると、点検のルール(SC-211)にもとづいて点検のタスク(1か月・1年・2年 など)を担当に自動で作ること(Task.source = 'rule') |
P1 |
| FR-272 |
アフター点検の画面で、今月・来月の点検の予定を並べ、点検の結果(異常なし/要対応)を記録できること。要対応は新しい工事(問い合わせ)として作れること |
P1 |
| FR-273 |
次の提案の候補として、築年・前回の工事からの年数・工事の種類から、外壁・屋根・水回りなどの提案の候補を出すこと。条件は設定(SC-211)で持ち、既定は「外壁の塗装・屋根から10年以上」「水回りの工事から15年以上」「築20年以上で水回りの工事の履歴なし」とすること |
P2 |
6.13 協力業者
| ID |
要件 |
優先 |
| FR-291 |
管理者は協力業者を登録・編集・停止できること(SC-212)。業者名・工種(複数)・電話・単価の目安のメモ を持つこと |
P1 |
| FR-292 |
協力業者の一覧(SC-090)で、業者ごとの今後4週間の予定の埋まり具合と、担当している現場を表示すること。全ロールが見られること |
P1 |
6.14 分析
| ID |
要件 |
優先 |
| FR-281 |
ダッシュボードに、稼働中の現場(今日作業がある現場)・今週の予定(現地調査・着工・完工)・見積の提出待ち・承認待ち・未入金・粗利が目標を下回る工事・工程の重なり・今月の点検 を表示すること。ロールで範囲が変わること |
P1 |
| FR-282 |
粗利の分析で、工事の種類別・担当者別の粗利率と、見積時と完了時(実行予算)の差を表示すること(管理者) |
P2 |
| FR-283 |
受注の分析で、経路別の 問い合わせ→現地調査→見積→契約 の件数と率、見積から契約までの日数の分布を表示すること |
P2 |
| FR-284 |
協力業者の稼働で、協力業者 × 週の埋まり具合と、発注額を表示すること |
P3 |
6.15 分析・設定(共通)
| ID |
要件 |
優先 |
| FR-901 |
全ての分析画面で、期間(今月/先月/四半期/任意)を指定できること |
P2 |
| FR-902 |
管理者はカスタム項目を追加できること。型は テキスト/数値/日付/単一選択/複数選択/チェックボックス に対応すること |
P2 |
| FR-903 |
追加したカスタム項目が、対象レコードの詳細画面・編集フォーム・一覧の列選択・絞り込み条件に即座に反映されること |
P2 |
| FR-904 |
管理者はメンバーのロール変更とチーム編成ができること |
P2 |
| FR-905 |
管理者は段階(工事の段階)を追加・名称変更・並び替えでき、変更が既存の全レコードに即座に反映されること。段階は必ず「進行中」「成約(受注)」「失注」のどれかの種類を持ち、成約・失注の段階は削除できないこと |
P2 |
| FR-906 |
レコードの変更履歴(誰が・いつ・どの項目を・何から何に)を操作ログに記録し、検索できること |
P3 |
| FR-907 |
通知センターに、担当の割当・期限の接近・放置のアラート・タスクの割当・業種の通知(7章 IndustryNotificationType)が配信され、ヘッダーの鈴に未読の件数が出ること。4章の体験で使うため、Phase 0 で作る |
P1 |
7. データ設計
型定義(src/lib/types/)
すべての型を先に定義し、これを唯一の真実とする。コード上の型名は英語、画面の言葉はリフォーム・工務店の言葉にする(型名 Customer を画面では「お客様」、Work を「工事」と表示する)。
共通の型の customerId は Customer.id を、caseId は Work.id を指す。CustomField.target の 'customer' 'case' も同じ対応とする。
共通の型
// ---- 組織・ユーザー ----
type Role = 'staff' | 'manager' | 'admin' // 担当 / 工事責任者 / 管理者
type User = {
id: string
name: string
nameKana: string
email: string
avatarUrl: string
role: Role
teamId: string
isActive: boolean
}
type Team = { id: string; name: string; managerId: string }
// ---- 対応記録・タスク ----
type Activity = {
id: string
type: ActivityType // 業種ごとに定義(下の業種の型を参照)
customerId: string
caseId?: string
ownerId: string
occurredAt: string
subject: string
body: string
nextAction?: string // 入力するとタスクが自動生成される(FR-157)
messagePreview?: { channel: 'mail' | 'sms' | 'line'; to: string; body: string } // 文面テンプレートから作った連絡
createdAt: string
}
type Task = {
id: string
title: string
dueDate: string
ownerId: string
assignedById?: string // 他者から割り当てられた場合
customerId?: string
caseId?: string
activityId?: string // 自動生成元
source: 'manual' | 'activity' | 'rule' // rule=業種のルールで自動生成(期限・点検など)
isDone: boolean
doneAt?: string
createdAt: string
}
// ---- カスタム項目・ビュー ----
type CustomField = {
id: string
target: 'customer' | 'case'
label: string
type: 'text' | 'number' | 'date' | 'select' | 'multiselect' | 'checkbox'
options?: string[]
isRequired: boolean
sortOrder: number
}
type CustomValue = string | number | boolean | string[] | null
type SavedView = {
id: string
name: string
target: string // 'customer' | 'case' | 業種ごとの一覧
ownerId: string
isShared: boolean // 工事責任者以上のみ true にできる
filters: Filter[]
visibleColumns: string[]
sort: { field: string; dir: 'asc' | 'desc' }[]
createdAt: string
}
type Filter = {
field: string
operator: 'eq' | 'contains' | 'gte' | 'lte' | 'between' | 'in' | 'isEmpty' | 'isNotEmpty'
value: unknown
}
// ---- その他 ----
type Tag = { id: string; name: string; color: string }
type Notification = {
id: string
targetUserId: string
type: 'assigned' | 'task_assigned' | 'due_soon' | 'neglected' | 'returned' | 'done' | IndustryNotificationType // 業種の通知は業種の型で定義する
title: string; body: string; link: string
readAt?: string
createdAt: string
}
type AuditLog = {
id: string
actorId: string
action: 'create' | 'update' | 'delete' | 'merge' | 'import'
targetType: string
targetId: string
changes: { field: string; before: unknown; after: unknown }[]
createdAt: string
}
type Company = { // 帳票に差し込む会社情報(SC-206)
name: string; postalCode: string; address: string; phone: string
logoDataUrl?: string; sealDataUrl?: string
bank?: { bankName: string; branch: string; type: '普通' | '当座'; number: string; holder: string }
invoiceRegNo?: string // 適格請求書発行事業者の登録番号(T + 13桁)。請求書に差し込む
license?: string // 業種の登録・許可・免許の番号(業種の型を参照)
}
type Result<T> = { ok: true; data: T } | { ok: false; error: string }
リフォーム・工務店の型
type ActivityType = 'call' | 'visit' | 'survey' | 'estimate' | 'site' | 'mail' | 'other'
// 電話 / 訪問 / 現地調査 / 見積の説明 / 現場 / メール / その他
type Customer = {
id: string
name: string; nameKana: string
phone: string; mobile: string; email: string
city: string; addressRest: string
contactTime: string
source: 'phone' | 'flyer' | 'web' | 'referral' | 'ob' | 'event' // 電話 / チラシ / ホームページ / 紹介 / OB / 見学会
ownerId: string // 担当。スコープ判定の起点
teamId: string
isOb: boolean // 過去に工事をしたお客様
building: { kind: 'house' | 'mansion'; builtYear: number; structure: 'wood' | 'steel' | 'rc'; floorArea: number; pastWorks: string[] }
tagIds: string[]
note: string
customFields: Record<string, CustomValue>
lastContactAt: string | null
createdAt: string; updatedAt: string
}
type Survey = {
id: string
workId: string; customerId: string; ownerId: string
scheduledAt: string
items: { part: Part; photos: Photo[]; measure: string; condition: 'ok' | 'caution' | 'repair'; request: string }[]
status: 'planned' | 'done'
}
type Part = 'bath' | 'kitchen' | 'toilet' | 'washroom' | 'exterior' | 'roof' | 'room' | 'other'
type Photo = {
id: string
workId?: string; surveyId?: string; dailyReportId?: string // どの工事・現地調査・日報の写真か(どれか1つ以上)
src: string // シードは public/ のパス。追加した写真は IndexedDB のキー
takenAt: string; part: Part; phase?: 'before' | 'during' | 'after'; memo: string
}
type Inspection = { // アフター点検(FR-271, 272)
id: string; workId: string; customerId: string; ownerId: string
monthsAfter: number; dueDate: string
result?: 'ok' | 'needs_work'; note?: string; doneAt?: string
followUpWorkId?: string // 要対応から作った新しい工事
}
type IndustryNotificationType = 'estimate_review' | 'schedule_changed' | 'schedule_conflict' | 'inspection_due' // 見積の承認待ち / 工程の変更 / 工程の重なり / 点検の時期
type Trade = { id: string; name: string; sortOrder: number } // 工種:解体・木工事・内装・設備・電気・左官・塗装・諸経費 …
type Estimate = {
id: string
number: string // 見積番号(自動採番)
workId: string
planLabel: string // 案の名前(松・竹・梅 など)
groups: { tradeId: string; lines: EstimateLine[] }[]
overhead: { mode: 'rate' | 'amount'; value: number } // 諸経費
discount: number // 値引き(売価から)
taxRate: number // 0.10
validUntil: string
note: string
status: 'draft' | 'review' | 'submitted' | 'contracted' | 'lost'
reviews: { by: string; at: string; result: 'approved' | 'returned'; reason?: string }[]
isAddition: boolean // 追加・変更工事の見積
approvedByCustomerAt?: string // 追加工事のお客様の承認
createdAt: string; updatedAt: string
}
type EstimateLine = { id: string; name: string; spec: string; qty: number; unit: string; costUnit: number; priceUnit: number; sortOrder: number }
type WorkStage = { id: string; name: string; sortOrder: number; type: 'open' | 'won' | 'lost' | 'after' }
type Work = {
id: string
customerId: string
title: string // 例:浴室改修(ユニットバス交換)
kind: 'bath' | 'kitchen' | 'toilet' | 'exterior' | 'roof' | 'interior' | 'full' | 'other'
ownerId: string
stageId: string
contract?: { amount: number; estimateId: string; signedAt: string; terms: { label: string; rate: number; due: 'contract' | 'middle' | 'handover' }[] }
period?: { start: string; end: string }
handoverAt?: string
orders: { tradeId: string; partnerId: string; amount: number }[] // 協力業者への発注(実行予算)
closeReason?: { codes: string[]; note: string }
subsidyMemo?: string // 補助金の名前と締切のメモ
lastActivityAt: string | null
customFields: Record<string, CustomValue>
createdAt: string; updatedAt: string
}
type ScheduleBar = { id: string; workId: string; tradeId: string; partnerId?: string; craftsman?: string; start: string; end: string; memo: string }
type Partner = { id: string; name: string; tradeIds: string[]; phone: string; unitPriceMemo: string; isActive: boolean } // 協力業者(架空)
type DailyReport = { id: string; workId: string; date: string; authorId: string; body: string; manDays: { partnerId: string; value: number }[]; photoIds: string[]; notice: string }
type Payment = {
id: string; workId: string
label: string // 着手金 / 中間金 / 完工金 / 追加工事(◯◯)
amount: number; dueDate: string
paidAt?: string; paidAmount?: number; recordedBy?: string // 入金の記録(担当もできる)
confirmedAt?: string; confirmedBy?: string // 入金の確定(管理者のみ)
estimateId?: string // 追加工事の入金は、その追加の見積を指す
}
type AftercareRule = { id: string; workKind: Work['kind'] | 'all'; monthsAfter: number[] } // 例 [1, 12, 24]
// 派生値。ストアには保存せず算出する
type EstimateCalc = { cost: number; price: number; profit: number; rate: number; byTrade: Record<string, { cost: number; price: number; rate: number }>; tax: number; total: number }
type Conflict = { partnerId: string; date: string; barIds: string[] }
type WorkView = Work & { contractAmount: number; expectedRate?: number; unpaid: number; hasConflict: boolean; pendingAdditions: number }
画像
- シードの工事写真(浴室・キッチン・トイレ・外壁・室内の着工前・完了)は
public/photos/works/ に置き、localStorage には入れない(パスだけを持つ)
- 着工前と完了は、同じ部位として見て不自然でない組み合わせを選ぶ(古い浴室 → 新しいユニットバス など)。写真のクレジットは
public/photos/CREDITS.json に記録し、アプリの「写真について」に一覧を出す
- 写真は
scripts/fetch-photos.mjs で1回だけ取得してリポジトリに含める。取得元は商用利用できる写真サービス(例 Unsplash)とし、透かし入り・有料の写真は除外する。Node の fetch が弾かれる場合は curl で取得する
- ユーザーが追加した写真だけを IndexedDB に保存する(長辺1280px・200KB以下。2章「永続化の範囲」)
シードデータ(src/lib/seed/)
| ファイル |
内容 |
件数 |
masters.ts |
工種(12)、部位、経路、失注の理由、タグ、点検のルール |
— |
users.ts |
担当7・工事責任者2・管理者1、チーム2(リフォーム課・新築課) |
10名 |
partners.ts |
協力業者(大工・設備・電気・内装・塗装・左官・板金・解体・クリーニング など。架空) |
24社 |
estimate-templates.ts |
見積のひな形(ユニットバスの交換・システムキッチンの交換・トイレの交換・洗面台の交換・外壁の塗装・屋根の葺き替え・内装の張り替え・手すりの取り付け など) |
12種 |
customers.ts |
お客様(うちOB 70名)。建物の情報つき |
180名 |
works.ts |
工事(問い合わせ18/現地調査10/見積作成中14/見積提出済み16/契約6/着工準備5/着工12/完工4/引渡し済み・アフター60/失注15) |
160件 |
estimates.ts |
見積(案の比較つき・追加工事つきを含む。目標の粗利率を下回るものを意図的に含める) |
190件 |
schedule.ts |
工程のバー(着工・着工準備の工事。重なりを2件だけ意図的に含める) |
約140本 |
photos.ts |
工事写真・現地調査の写真(シードの写真ファイルを参照) |
約400枚分 |
daily-reports.ts |
作業日報(稼働中の現場の過去3週間) |
約180件 |
payments.ts |
入金予定と入金(未入金を3件) |
約260件 |
activities.ts |
対応履歴 |
1,300件 |
tasks.ts |
タスク(期限超過7/今日6/今週12/今後22/完了45。点検のタスクを含む) |
92件 |
templates.ts |
文面テンプレート(現地調査のお礼・見積の送付・着工のご案内・近隣へのご挨拶・完工のご報告・点検のご案内 など10種) |
— |
リフォームらしさのためのシードの注意
- 見積の金額は、工事の種類と整合させる(トイレの交換は数十万円、ユニットバスの交換は百万円前後、外壁の塗装は百万円台、全面の改修は数百万円〜)。原価と売価の比率は工種ごとに現実的な幅(設備機器は粗利が薄く、手間の工種は厚い)にする
- 日報・現地調査のメモ・気づいたことは、現場の言い回しで書き分ける(「解体したら土台に腐れ。施主に写真で説明、補修の追加見積を出す」「給水管の位置が図面と違う」「雨天のため外部の作業を中止」など)
- 春と秋に外壁・屋根の工事、年末に水回りの工事が増える季節の波を入れる
シード作成のルール(品質を左右する)
- 実在の企業名・人名・住所の番地を使わない。 架空のものを使う。地名は市区町村までにとどめ、番地以降は架空にする
- 文章をテンプレの繰り返しにしない。 お客様・段階・季節に応じて書き分ける。同じ言い回しが続くと一瞬で作り物だと分かる
- 金額・件数の分布に偏りを持たせる(小さいものが多く、大きいものが少ない)。均等分布は不自然
- 日付は現在日時からの相対で生成する。固定日付を埋め込まない(期限・締め日のように暦で決まるものは、今日から見た次回・前回を計算して入れる)
- 対応の頻度に濃淡をつける。頻繁にやり取りしているお客様と、しばらく放置のお客様が混在すること
- 期限超過・放置・目標未達を意図的に配置する。 全部が順調だと、ダッシュボードのアラートが動いて見えない
- シードの生成は乱数の種(seed)を固定し、毎回同じデータになるようにする
ストアとリポジトリ
src/lib/
├── types/ # 上記の型定義
├── seed/ # シードデータ
├── store/
│ ├── session.ts # 現在のロール、操作中のユーザー
│ ├── data.ts # 業種のデータ(customers / works / surveys / estimates / scheduleBars / photos / dailyReports / payments / activities / tasks ...)
│ ├── settings.ts # customFields / stages / tags / templates / company
│ └── ui.ts # 表示密度、ガイドツアー表示済みフラグ
└── repo/ # ★ コンポーネントが触るのはここだけ
├── _delay.ts # 擬似ディレイ
├── _scope.ts # ★ ロールによるデータスコープ。全メソッドが通す
└── (業種ごとのモジュール。9章のディレクトリ構成)
リポジトリ層の規約(厳守)
- 全メソッドを
async で定義する。中身が同期でも例外なく
- 戻り値は
Result<T> に統一する
- コンポーネントから Zustand ストアを直接参照しない。 読み取りも書き込みもリポジトリ経由
- スコープ適用(
_scope.ts)を全メソッドが必ず通す。 ここが本番化でデータベースの権限設定に置き換わる箇所(FR-005)
- 派生値(経過日数・残り日数・合計金額・粗利など)はストアに保存せず、リポジトリ/計算モジュール(
src/lib/calc/)で都度算出する
- Zustand のセレクタで新しいオブジェクトや配列を作って返さない。(毎回別物と判定され、無限に再描画される。必要なら
useShallow を使うか、フックの外で組み立てる)
- persist の読み込み完了時の処理(
onRehydrateStorage)の中で、ストア自身を参照しない(生成途中のため失敗し、画面が永遠に読み込み中になる。queueMicrotask で後ろへ逃がす)
8. デザイン要件
アートディレクション
「現場の道具箱」
TSUGITE は、事務所の机と、ほこりっぽい現場の両方で使われる。現場では手袋のまま、日差しの下で、片手で操作する。したがって事務所の画面は数字の密度を、現場の画面は大きく・はっきり・迷わないことを優先する。
- 粗利は、見積の画面の上に常に置く。 見積の作業中、どこまでスクロールしても合計と粗利率が見える(上部に固定)
- 工程は線で見せる。 バーは工種の名前だけを持ち、色で工種を分けない。重なりだけが赤い
- 写真は証拠。 工事写真は角を揃えて大きく並べ、撮った日を必ず添える。写真の上に文字を重ねない
- 現場の画面は大きく。 スマホの現地調査・日報・写真の画面は、ボタンの高さ56px・文字16px以上。屋外でも読めるコントラストにする
デザイントークン
src/styles/tokens.css に CSS 変数で定義し、Tailwind の theme から参照する。直書きの色指定を禁止する。 色の値はチャンネル値(例 35 64 122)で定義し、rgb(var(--brand-700) / <alpha-value>) で参照する(16進数で定義すると bg-brand/60 のような透明度指定が無言で効かなくなるため)。
:root {
--ink-900: 26 27 29; /* 見出し・本文・数値 #1A1B1D */
--ink-600: 86 89 94; /* 補助テキスト #56595E */
--ink-400: 139 142 148; /* ラベル・非活性 #8B8E94 */
--brand-700: 29 78 137; /* 主要な操作・選択状態(群青) #1D4E89 */
--brand-500: 44 101 168; /* ホバー #2C65A8 */
--brand-50: 234 241 249; /* 選択行・アクティブなビュー #EAF1F9 */
--surface: 246 245 242; /* ページ背景(ややあたたかい灰) #F6F5F2 */
--card: 255 255 255;
--border: 226 224 219; /* #E2E0DB */
--border-strong: 196 193 186;
/* シグナル:これ以外の色を画面に持ち込まない */
--won: 38 125 86; /* 契約・入金済み */
--lost: 139 142 148; /* 失注(無彩色) */
--alert: 196 62 48; /* 工程の重なり・未入金・要補修 */
--warn: 180 112 18; /* 目標の粗利率を下回る・返事待ちが長い・注意 */
}
- 工種・工事の種類を色で分けない。文字のラベルで分ける
- 粗利率の数字は、目標以上=
--ink-900、目標未満=--warn。緑にして「良い」を強調しない(良い状態は普通の状態)
配色ルール(共通)
- 通常状態の行に色を持たせない。色がついている行は「対応が必要な行」だけ
- 段階に固有色を割り当てて虹色のバッジを並べない。段階は位置と進捗で表現する
- 色だけで状態を伝えない。必ずアイコン+文字を添える(A11Y-04)
タイポグラフィ
| 役割 |
書体 |
用途 |
| UI全般 |
Noto Sans JP(可変フォント。400 / 500 / 700) |
見出しも本文もこれ1つ。ウェイトと文字サイズだけで階層を作る |
| 数値 |
Inter(font-variant-numeric: tabular-nums) |
金額・件数・日数・日付・時刻。桁を揃えて縦に比較できることが最優先 |
Noto Sans JP は可変フォント1本で読み込む。 ウェイトごとに別ファイルを読み込むと、日本語の文字範囲が重複して CSS と転送量が大きく膨らむ。
| トークン |
サイズ |
行間 |
用途 |
| page-title |
22px / 700 |
1.4 |
画面タイトル |
| section |
16px / 700 |
1.5 |
セクション見出し |
| body |
14px / 400 |
1.7 |
テーブルセル、本文 |
| label |
12px / 500 |
1.5 |
項目ラベル(letter-spacing: .04em) |
| metric-lg |
30px / 600 Inter |
1.2 |
ダッシュボードの主要数値 |
| metric-sm |
15px / 600 Inter |
1.4 |
テーブル内の金額・日数 |
レイアウトとスペーシング
| 項目 |
定義 |
| スペーシング |
4pxベース:4 / 8 / 12 / 16 / 24 / 32 / 48 |
| アプリシェル |
左サイドバー(240px、折りたたみで64px)+ メインエリア。ヘッダー56px固定 |
| スマホ |
サイドバーは隠し、下部に5つのタブ(業種ごとにいちばん使う画面を割り当てる)。ヘッダーは48px |
| コンテンツ幅 |
一覧は画面幅いっぱい。詳細・フォームは最大 1120px |
| テーブル行高 |
標準44px / コンパクト34px(切替可能、FR-114) |
| 角丸 |
8px(カード・入力・ボタン)/4px(バッジ)/999px(アバター) |
| 影 |
ポップオーバー・モーダル・スマホの下部シートのみ。一覧のテーブルに影を使わない |
主要コンポーネント仕様(共通)
| コンポーネント |
仕様 |
| データテーブル |
固定ヘッダー、行ホバーで背景を薄く、選択行は --brand-50。金額・日数は右寄せ + 等幅数字。列幅リサイズ可 |
| ツールバー |
テーブル上部に固定。左=ビュー切替・絞り込み・列設定、右=密度切替・書き出し・新規作成 |
| 絞り込みチップ |
適用中の条件を横並び表示。× で個別解除、「すべて解除」を末尾に |
| 一括操作バー |
行を選択するとテーブル下部からせり上がる。「N件を選択中」+ 操作ボタン + 解除 |
| 段階の進捗バー |
詳細画面の上部。通過済み・現在地・未通過を1本のバーで表現。クリックで段階変更 |
| 対応タイムライン |
左に種別アイコン + 縦罫線、右に内容。日付でグルーピング。種別フィルタをタブで |
| タスク行 |
チェックボックス/内容/関連レコード/期限(超過は --alert)/担当アバター。チェックで即完了、取り消し可 |
| メトリクスカード |
ラベル/主数値/前期比(増減の記号 + %)。飾りのグラフを載せない |
| 空状態 |
全一覧に専用の空状態。「何が表示されるか」+ 次の行動ボタン。絞り込み0件と、データ0件を別の文言にする |
| スケルトン |
一覧は行の形のスケルトン。スピナーを使わない |
| コマンドパレット |
⌘K。検索・遷移・新規作成をグループ化。矢印キー + Enter で実行 |
| デモ切替バー |
プロダクトのトークンとは別扱い(墨色の帯 + 小さめの文字) |
インタラクション要件(業務システムの肝)
| ID |
要件 |
| IX-01 |
一覧の絞り込み・並び替えは体感で即座に反映されること(100ms以下) |
| IX-02 |
テーブル上で ↑↓ 行移動、Enter 詳細を開く、Space 行選択、⌘A 全選択 ができること |
| IX-03 |
インライン編集は Enter 確定、Esc 取消、Tab で次のセルへ移動すること |
| IX-04 |
⌘K コマンドパレット、/ 横断検索にフォーカス、N 新規作成 のショートカットを提供すること |
| IX-05 |
ショートカット一覧を ? キーで表示すること |
| IX-06 |
破壊的操作(削除・一括更新)は、実行後に5秒間「元に戻す」を表示すること |
| IX-07 |
保存はすべて楽観的更新とし、失敗時のみロールバックしてエラーを表示すること |
| IX-08 |
モーダルを開いても背後の一覧の状態(スクロール位置・選択)が保持されること |
| IX-09 |
スマホでは、主要な操作ボタンを親指の届く下側に置くこと。ボタンの押せる大きさは最低 44×44px |
モーション
| 対象 |
duration |
内容 |
| ホバー・フォーカス |
80ms |
色のみ。業務システムでは反応が速いことが価値 |
| モーダル・ポップオーバー |
160ms |
フェード + 4px |
| 一括操作バーのせり上がり |
200ms |
下から。cubic-bezier(.16,1,.3,1) |
| ドラッグ(カンバン・工程) |
150ms |
ドロップ時に着地 |
| トースト |
160ms |
右下から(スマホは下部中央) |
| 数値の変化 |
400ms |
ダッシュボードのメトリクスのみカウントアップ。テーブル内では行わない |
prefers-reduced-motion: reduce 時は全アニメーションを無効化する。登場アニメーションに animation-fill-mode: both を使わない(初期状態のまま要素が消えたり、固定配置の要素が壊れたりする。forwards か、終了状態を通常のスタイルに書く)。
アクセシビリティ(WCAG 2.1 AA)
| ID |
要件 |
| A11Y-01 |
コントラスト比は通常4.5:1以上、18px以上は3:1以上。14px本文でも必ず満たすこと |
| A11Y-02 |
全ての操作をキーボードのみで完遂できる。ドラッグ操作にはキーボード代替を用意する |
| A11Y-03 |
フォーカスリングは2px・オフセット2pxで常時可視。outline:none の単独使用禁止 |
| A11Y-04 |
情報を色のみで伝えない。期限超過・放置は色 + アイコン + テキストで示す |
| A11Y-05 |
テーブルは <table> を用い、scope 属性と caption を適切に設定する |
| A11Y-06 |
フォームの各入力に label を関連付け、エラーは aria-describedby と role="alert" で読み上げる |
| A11Y-07 |
モーダルはフォーカストラップ + Esc で閉じる + 起動元へフォーカス復帰 |
| A11Y-08 |
一括操作の選択件数、絞り込み結果の件数を aria-live で通知 |
| A11Y-09 |
ページタイトルは画面ごとに固有。見出しレベルを飛ばさない |
| A11Y-10 |
文字サイズ200%指定でも内容が読めること |
ライティング規約
| 原則 |
例 |
| ボタンは「何が起きるか」 |
○「見積を提出済みにする」/×「保存」「OK」 |
| 件数を明示する |
○「12件の担当を変更しますか?」/×「変更しますか?」 |
| エラーは原因と対処 |
○「3行目:電話番号の形式が違います。半角数字とハイフンで入力してください」/×「取り込みに失敗しました」 |
| 空状態を区別する |
データ0件:「まだ登録がありません。最初の1件を登録しましょう」/絞り込み0件:「条件に一致するものはありません」+ 条件解除ボタン |
| 謝罪しない |
×「申し訳ございませんが〜」/○ 事実と次の行動 |
| システム語を使わない |
○「この工事を「着工」に進める」/×「ステータスを更新」 |
| 業種の言葉を使う |
汎用の言葉に言い換えない(現地調査・見積・粗利・工程・着工・完工・引渡し・協力業者・職人・人工・追加工事・アフター点検) |
9. 技術要件・ディレクトリ構成
技術スタック(固定・勝手に変更しない)
| レイヤ |
技術 |
備考 |
| ビルド |
Vite 6 / TypeScript strict |
静的ファイルとして配信する |
| 画面 |
React 19 / React Router 7(ブラウザ内で画面を切り替える方式) |
|
| スタイリング |
Tailwind CSS v4 + CSS Variables |
トークンは CSS 変数で定義(チャンネル値) |
| UIコンポーネント |
Radix UI(shadcn/ui の作り方でコードを取り込む) |
a11y要件を自前実装せずに満たす |
| 状態管理 |
Zustand + persist ミドルウェア |
localStorage に永続化 |
| テーブル |
TanStack Table v8 |
列制御・ソート・選択。見た目は自前。ヘッドレスのまま使う |
| 仮想スクロール |
TanStack Virtual |
FR-113 |
| フォーム |
React Hook Form + Zod |
|
| ドラッグ |
dnd-kit |
キーボード操作対応が必須のため |
| グラフ |
Recharts |
分析画面。動的に読み込む |
| CSV |
Papa Parse |
インポート/エクスポート |
| 写真の保存 |
idb-keyval |
IndexedDB の薄いラッパー。写真を扱う業種のみ |
| PDF |
@react-pdf/renderer |
ブラウザ内で生成する。動的に読み込む |
| 日付 |
date-fns(ja locale) |
|
| アイコン |
lucide-react |
|
| コマンドパレット |
cmdk |
FR-112 |
| 配信 |
Cloudflare Workers(静的アセット) |
全ルートを index.html に返す設定にする(not_found_handling: "single-page-application") |
| テスト |
Vitest / Playwright / axe-core |
|
上記以外のライブラリを入れる前に必ず提案し、承認を得ること。
PDF の日本語について: @react-pdf/renderer は日本語フォントを登録しないと文字が出ない。Noto Sans JP の TTF(静的ウェイト 400 と 700)を public/fonts/ に置き Font.register する。さらに、日本語は単語の区切りがないため、既定の自動ハイフネーションで「-」が行末に入る。Font.registerHyphenationCallback(word => [word]) で無効にすること。
ディレクトリ構成
/
├── CLAUDE.md # このファイル
├── wrangler.jsonc # 公開の設定(静的アセット + SPA)
├── public/
│ ├── photos/works/ # 工事写真(シード用)と CREDITS.json
│ └── fonts/ # PDF用の日本語フォント
├── scripts/fetch-photos.mjs # 写真の取得(1回だけ)
└── src/
├── main.tsx app.tsx # ルーター・アプリシェル(サイドバー・ヘッダー・デモ切替バー・下部タブ)
├── routes/
│ ├── dashboard.tsx # SC-001
│ ├── customers/ # SC-020〜023
│ ├── works/ # SC-030〜033, 061, 070, 072
│ ├── surveys/ # SC-040, 041
│ ├── estimates/ # SC-050〜053
│ ├── schedule.tsx # SC-060
│ ├── daily.tsx # SC-071
│ ├── payments.tsx # SC-080, 081
│ ├── partners.tsx aftercare.tsx # SC-090, 091
│ ├── tasks.tsx activities.tsx # SC-095, 096
│ ├── analytics/ # SC-100〜103
│ ├── settings/ # SC-200〜212
│ └── dev/components.tsx
├── components/
│ ├── ui/ table/ demo/ layout/
│ └── domain/ # EstimateEditor, MarginBar, PlanCompare, Gantt, GanttBar, ConflictBadge, PhotoGrid, BeforeAfter, DailyForm, PaymentRow, StageBar, ActivityTimeline, TaskRow, MetricCard
├── lib/
│ ├── types/ seed/ store/ repo/ # 7章参照
│ ├── query/
│ ├── calc/ # estimate.ts(原価・粗利・税), schedule.ts(重なり), payment.ts(入金予定), aftercare.ts(点検), budget.ts(実行予算)
│ ├── image/resize.ts # 写真の縮小(200KB以下に収める)
│ ├── csv/ pdf/ # 見積書・工事完了報告書・請求書
│ ├── i18n/terms.ts
│ ├── validation/ utils/
├── styles/tokens.css
└── e2e/
スマホの下部タブ:ホーム/工事/工程/日報/アフター(写真は工事詳細から開く)
コーディング規約
- TypeScript strict。
any 禁止。やむを得ない場合は unknown + 型ガード
- ファイル名は kebab-case、コンポーネントは PascalCase
- 1ファイル300行を超えたら分割を検討する
- コンポーネントから Zustand ストアを直接参照しない。必ず
src/lib/repo/ 経由
- 絞り込み・計算ロジックは
src/lib/query/ と src/lib/calc/ に置き、コンポーネントに埋め込まない(テスト対象にするため)
- 派生値をストアに保存しない。常に算出する
- 業種の言葉は
src/lib/i18n/terms.ts にまとめる(画面に直書きしない。言葉の統一が業種特化の品質を決めるため)
- コミットは1タスクごと。メッセージに要件IDを含める
例:
feat(works): 放置の検出を実装 (FR-xxx)
10. 非機能要件
| ID |
要件 |
目標値 |
| NFR-01 |
LCP(デスクトップ) |
1.8秒以下 |
| NFR-02 |
INP(操作への応答) |
200ms以下 |
| NFR-03 |
CLS |
0.1以下 |
| NFR-04 |
一覧1,000行での絞り込み・並び替えの反映 |
100ms以下 |
| NFR-05 |
一覧1,000行のスクロールが60fpsを維持すること(仮想スクロール) |
— |
| NFR-06 |
初期JSバンドルサイズ(gzip後) |
250KB以下(PDF・グラフ・CSVは動的に読み込む) |
| NFR-07 |
Lighthouse |
Performance 90 / Accessibility 95 以上 |
| NFR-08 |
対応ブラウザ |
Chrome / Safari / Edge 最新2バージョン、iOS Safari 16以降 |
| NFR-09 |
ユーザー入力はサニタイズし、CSVの数式インジェクション(=, +, -, @ 始まり)を無害化すること |
— |
| NFR-10 |
localStorage の容量上限(5MB程度)・IndexedDB の使える容量に近づいた場合、警告を表示し、データを破損させないこと |
— |
| NFR-11 |
画面幅 320px〜2560px のどこでも、横にはみ出さず崩れないこと |
— |
| NFR-T1 |
見積の明細100行で、入力のたびの再計算と表示の更新が 50ms 以下 |
— |
| NFR-T2 |
全現場の工程表(60現場 × 3か月)のスクロールとドラッグが60fpsを維持すること。測定用のデータはシードとは別に scripts/perf-seed.ts で作る(シードの稼働中の工事は約20件のため) |
— |
| NFR-T3 |
スマホで撮った写真(10MB程度)を縮小して保存するまで 1.5秒 以下 |
— |
本番化するときに必要になること(デモ本体の要件ではない)
将来このデモを実際の業務で使う形にする場合、以下が追加で必要になる。お客様への提案の場で聞かれた際に説明できるよう、記録として残す。
- データの見える範囲は、サーバー側(データベースの権限設定)で守る必要がある。 本デモの
src/lib/repo/_scope.ts がその置き換え地点であり、構造上そのまま差し替えられる
- ログイン、メンバーの招待と停止、毎日のバックアップ、止まったときの通知
- お客様の情報は個人情報保護法の対象。利用目的の明示、安全管理措置、委託先の管理、開示・削除請求への対応が必要になる
- CSVの書き出しは情報の持ち出し経路になるため、実運用では権限の制御と操作ログが必須
- 建設業法に関わる運用。 工事請負契約書には法定の記載事項があり、本番で契約書を作る場合は確認が必要。一定の金額以上の工事を請け負うには建設業の許可が要る
- 工事写真には、お客様の住まいの中が写る。本番では、写真を見られる人の限定と、社外への持ち出しの制御が必要
- 協力業者への発注を本番でやり取りする場合は、下請代金の支払いに関する決まり(支払期日など)を確認する必要がある
- 本デモはお客様のデータをサーバーに送信しないため、これらの義務は発生しない。 ただし「デモである」旨は画面上に常時明示する
11. 実装タスク
この順に進める。フェーズを飛ばさない。 完了時は [x] に更新する。
Phase 0 — 基盤とデザインシステム(3日)
0-1. 初期化
0-2. 型とシード
0-3. ストアとリポジトリ
0-4. デザインシステム
0-5. デモ基盤
Phase 0 完了チェック
Phase 1 — 一覧基盤とお客様管理(4日)
1-1. データテーブル基盤(最重要。ここの品質が全画面に波及する)
1-2. 保存ビュー
1-3. お客様
1-4. CSV入出力
1-5. 横断検索・コマンドパレット
Phase 1 完了チェック
Phase 2 — 現地調査と見積(5日)
Phase 2 完了チェック
Phase 3 — 工事・工程・写真・入金(5日)
Phase 3 完了チェック
Phase 4 — アフター・分析・設定(3日)
Phase 4 完了チェック
Phase 5 — 仕上げ(3日)
5-1. 体験の総点検
5-2. アクセシビリティ監査
5-3. パフォーマンス
5-4. テストと公開
合計 約23営業日(約4.5週間)/1名専任 + レビュー体制。
工数配分の意図: Phase 1 に4日を割いているのは、データテーブル基盤が全画面に波及するため。ここを雑に作ると、以降の全一覧画面が作り直しになる。逆にここが良ければ、業種の一覧はほぼ設定だけで完成し、Phase 2〜4 の時間を業種の作り込みに使える。
12. 受入基準
- 6章の優先度 P1 の要件がすべて実装されていること
- 5章の主要フローが、最初から最後まで完走すること。フローと4章の体験に出てくる機能は、6章の優先度が P2・P3 でも必須とする
- 4章「ロールを跨ぐ体験」がすべて動作すること
- ロールを切り替えると、一覧・ダッシュボード・分析の表示範囲が変わること。かつスコープ判定が
src/lib/repo/_scope.ts に集約されていること
- 一覧テーブルが、絞り込み・列選択・保存ビュー・一括操作・キーボード操作のすべてに対応し、スマホ幅ではカード型になること
- 1,000行での絞り込みが100ms以下、スクロールが60fpsを維持すること
- CSVインポートが列の対応付けとエラー行表示に対応し、CSVの書き出しと帳票PDFが実際にダウンロードできること
- 全44画面のいずれにも空の状態がなく、リフォーム・工務店らしいリアルなデータが表示されていること
- リロード後も操作結果が保持され、「デモをリセット」で初期状態に戻ること
- axe-core で Critical / Serious の指摘が0件であること
- Lighthouse の基準値を満たすこと
- データアクセスがすべて
src/lib/repo/ を経由しており、コンポーネントが Zustand ストアを直接参照していないこと
- 見積の原価・粗利が、入力のたびに正しく再計算され、お客様向けの見積書PDFに一度も出ないこと
- 工程の重なり(同じ協力業者が同じ日に2現場)が、全現場の工程表と工事ごとの工程の両方で検出されること
- 承認された追加工事が契約の金額に加算されて追加工事の入金予定が作られ、未承認の追加工事は工事詳細で分かること
- 引渡し済みにすると、点検のタスクがルールどおりに作られること
- スマホ(375px)で、現地調査の記録・写真の撮影・作業日報が片手で使えること(ボタンの高さ56px・文字16px以上)
判断に迷ったときのルール
- 仕様がこの文書にない場合は、実装せずに質問する。 推測で作らない
- キーボード操作と「空の画面を作らない」は削減対象外。 速度を出すために削らない
- スコープ外(3章 Won't have)は、思いついても実装しない。特にワークフローのビルダーと帳票の自由レイアウト編集
- 「デモだから」を理由に品質を落とす判断はしない
- コンポーネントからストアを直接触りたくなったら、それはリポジトリ層に足りないメソッドがあるということ
- 迷ったらリフォーム・工務店の人の1日を思い浮かべる。 その人が毎朝最初に開く画面で、最初に知りたい数字は何か。それが画面のいちばん上にあるか
- 見積の計算・粗利を、画面のコンポーネントの中で計算しない。 すべて
src/lib/calc/estimate.ts を通す
- お客様に渡す帳票(見積書・請求書・報告書)に、原価・粗利・社内のメモが出ていないかを、帳票を変えるたびに確認する