SOUZOHSPECS

業務システム ・ TSUGITE

【リフォーム】顧客・工事管理システム

リフォーム・工務店向け

見積の粗利から工程・工事写真・アフター点検まで、リフォーム会社・工務店のための工事管理

作り方は無料です。このページの手順どおりに、要件定義書とプロンプトを Claude Code に送れば、このデモと同じアプリが完成します。

要件定義書をダウンロードデモを触る ↗

v1.0・作成 2026-09-30

  1. 要件定義書を保存する

    パソコンに tsugite-app のようなフォルダを作り、その中に保存します。

    要件定義書.md として保存

  2. ChatGPT で画面イメージを作る デザインにこだわりたい人

    ChatGPT に要件定義書を添付して、下の文を送ります。雰囲気のところは、好きな言葉に書きかえてください。

    ChatGPT に送る
    添付の要件定義書は、これから作るアプリ「【リフォーム】顧客・工事管理システム」のものです。
    このアプリのいちばん大事な画面を、デザイン画像にしてください。
    実際のアプリのように、文字やボタンまで入れてください。
    雰囲気:(例:やさしい/高級感/ポップ/シンプル など、好きな言葉で)

    気に入るまで「もっと明るく」「ボタンを大きく」のように直してもらい、できた画像を保存します。ほかの画面も欲しければ、同じように作ってもらえます。

  3. Claude Code に渡して「作って」と頼む

    Claude のデスクトップアプリで「Code」タブを開き、「Select folder」から tsugite-app を選びます。画面イメージがある人は、入力欄に画像をドラッグして貼りつけてから、下の文を送ります。詳しく

    Claude Code に送る(画像あり)
    @要件定義書.md をもとに、このアプリを作ってください。
    デザインは添付の画像に合わせてください。
    Claude Code に送る(画像なし)
    @要件定義書.md をもとに、このアプリを作ってください。

    作り終わるまで、しばらくかかります。途中で「許可しますか」と聞かれたら、内容を見て許可してください。

  4. 動かして確かめる・直す

    できたら、実際に画面を開いて触ります。直してほしいところは、スクリーンショットを貼りつけて、言葉で伝えれば大丈夫です。

    Claude Code に送る
    アプリを起動して、ブラウザで開けるようにしてください。
    Claude Code に送る
    (画面名)で(操作)をすると(今の動き)になります。
    (こうなってほしい動き)にしてください。
    Claude Code に送る
    このエラーを直してください。
    
    (ここにエラーの文をそのまま貼る)
  5. 途中で止まったら 必要なときだけ

    要件定義書が長いので、一度で作りきれないことがあります。そのときは新しい会話で、こう送ります。

    Claude Code に送る
    @要件定義書.md の続きを作ってください。
    まず、どこまでできているかを確かめてから進めてください。

    それでも進まないときは、30分無料相談でお手伝いします。公式LINEからのご相談もどうぞ。

    1段階ずつ頼みたいとき(全6段階)

    要件定義書には、作る順番が Phase 0〜5 で書かれています。止まりやすいときは、1つずつ頼むと確実です。

    Phase 0基盤とデザインシステム
    Claude Code に送る
    @要件定義書.md の「実装タスク」にある Phase 0 を作ってください。
    Phase 1一覧基盤とお客様管理
    Claude Code に送る
    @要件定義書.md の「実装タスク」にある Phase 1 を作ってください。
    Phase 2現地調査と見積
    Claude Code に送る
    @要件定義書.md の「実装タスク」にある Phase 2 を作ってください。
    Phase 3工事・工程・写真・入金
    Claude Code に送る
    @要件定義書.md の「実装タスク」にある Phase 3 を作ってください。
    Phase 4アフター・分析・設定
    Claude Code に送る
    @要件定義書.md の「実装タスク」にある Phase 4 を作ってください。
    Phase 5仕上げ
    Claude Code に送る
    @要件定義書.md の「実装タスク」にある Phase 5 を作ってください。
  6. 本番で使うなら

    できたアプリはデモです。データの保存・セキュリティ・運用のルール・公開の仕方は入っていないので、そのまま公開すると誰でも中身を見られます。本番で使うのに何が要るかは、「本番で使いたい方へ」にまとめました。

    自社向けに作り変えるなら、まずこう聞いてみてください。

    Claude Code に送る
    この要件定義書は、記事に埋め込むデモ用に書かれています。
    自分の会社で実際に使えるように変えたいです。外したほうがいいところと、残したほうがいいところを教えてください。

    本番運用について相談する

準備や、うまくいかないときの対処は 作り方ガイド にまとめています。分からないときは 30分無料相談 へどうぞ。

これはデモ用の要件定義書です。本番で使うには、あと4つ必要です。

要件定義書をダウンロード

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

版数 1.0(DBレス構成)/ 作成日 2026-09-30 / 発行 ソウゾウ合同会社 用途 業種特化アプリの実演デモ / リフォーム・工務店向け 顧客・見積・工事管理編


このドキュメントの使い方(Claude Code へ)

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

  • 実装は「11. 実装タスク」の順に進める。フェーズを飛ばさない。
  • 各タスクの括弧内は要件ID。着手前に該当章を読むこと。
  • 仕様がここに書かれていない場合は、推測で実装せず質問する。
  • スコープ外(3章 Won't have)は、思いついても実装しない。
  • 「デモだから」を理由に品質を落とす判断はしない。
  • リフォーム・工務店の言葉で書く。 画面の文言・項目名・並び順・帳票は、この業種の人が毎日使っている言葉と順番に合わせる。汎用の顧客管理の言葉(「リード」「商談」「アカウント」など)に置き換えない。

このアプリが「業種特化」であることの意味 汎用の顧客管理は、無料〜月数千円のサービスがすでに多くある。TSUGITE がそれらと並べて選ばれる理由は、開いた瞬間に「これはうちの仕事のために作られている」と分かることだけである。 項目・言葉・流れ・帳票・ダッシュボードの数字がリフォーム・工務店のものになっていない画面は、1つでもあれば失敗とみなす。


目次

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

1. プロジェクト概要

背景と目的

地域のリフォーム会社・工務店(社員5〜40名規模)の多くは、問い合わせをノートとExcelで受け、見積は表計算で作り、工程はホワイトボード、工事の写真は担当者のスマホの中にある。見積の段階で粗利が薄いことに気づかないまま契約し、追加工事の請求を忘れ、同じ職人を同じ日に2つの現場へ入れてしまう。引渡し後の点検の連絡も途切れ、OBのお客様からの次の依頼を逃す。

汎用の顧客管理を入れても、「原価と粗利のある見積」「工程表」「工事写真の台帳」がないため、結局Excelとホワイトボードに戻る。TSUGITE は、問い合わせから現地調査・見積・契約・工程・写真・入金・アフター点検までを、リフォームの現場の順番と言葉のまま1つにつなぐ。

目的 内容
業種特化の実装力の証明 原価と粗利のある見積、工程表、写真台帳という、リフォームに固有の業務を画面にする
利益を守る設計の証明 見積の粗利率・実行予算との差・追加工事の請求漏れを、システム側から知らせる
現場で使える操作性の証明 現地調査・日報・写真はスマホで、見積・工程は事務所のPCで、同じデータを扱う
横展開の資産化 共通の土台(ロール・一覧・設定・帳票)に、業種の部分だけを載せる構造にする

プロダクト定義

項目 内容
プロダクト名 TSUGITE(つぎて)※仮称。木材をつなぐ「継手」から
一言定義 見積の粗利から、工程・写真・アフター点検まで。リフォーム会社のための顧客・工事管理
提供形態 レスポンシブWebアプリ。フロントエンド完結(サーバー側の保存なし)
主戦場 事務所のPC(見積・工程・請求)と、現場のスマホ(現地調査・写真・日報)
想定利用者 リフォーム会社・工務店の営業兼現場の担当、工事責任者、社長・事務

プロダクトコンセプト

「利益は、見積で決まる。信頼は、写真で残る。」

リフォームの利益は見積を出した時点でほぼ決まり、お客様の信頼は工事の途中と完了の写真で積み上がる。TSUGITE は、見積の画面で粗利を常に見せ、現場の写真を工事の記録と報告書にそのままつなぐことを設計の中心に置く。

デモとしての成功条件

  1. 触った瞬間に「リフォーム・工務店の仕事で使える」と分かる — 空の画面が1つもなく、リフォーム・工務店らしいリアルなデータが入っている
  2. 速い — 一覧の絞り込み、状態の変更、対応記録が、待たされずに終わる
  3. ロールで見え方が変わる — 担当は自分の担当、工事責任者はチーム全体。権限の設計ができていることを示す
  4. 業種の言葉でできている — 項目・段階・帳票・ダッシュボードの数字が、リフォーム・工務店のものになっている
  5. リセットできる — 誰が触った後でも、初期状態に戻せる

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行に収め、ロール名はアイコン+短い名前にする。

ロールを跨ぐ体験(必ず動くようにする)

  1. 担当が見積を作り、粗利率が目標(既定25%)を下回った状態で「提出する」を押す → 提出ではなく「承認待ち」になり、工事責任者に切替 → 承認待ちの一覧に理由(粗利率 21.4%)つきで現れる
  2. 工事責任者が工程表で大工の「(架空)田島工務」を、別の現場と同じ日に割り当てる → 重なりの警告が出て、担当に切替 → 自分の工事の工程にも警告の印がついている
  3. 担当が追加工事(手すりの取り付け)の見積を作り、お客様の承認を記録する → 契約の金額が増え、「追加工事(手すり)」の入金予定が作られ、管理者の未入金の見込みが変わる
  4. 管理者が工事を「引渡し済み」にする → 1か月・1年・2年の点検のタスクが担当に自動で作られ、ダッシュボードの点検の予定に並ぶ
  5. 管理者が見積のひな形「ユニットバスの交換」の原価を変える → 次に作る見積に新しい原価が入る(作成済みの見積は変わらない)

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. 初期化

  • Vite 6 / React 19 / TypeScript strict / React Router 7 / Tailwind v4 で初期化
  • ESLint / Prettier(保存時に整形)、npm run check で lint + 型チェック + テスト
  • 9章のディレクトリ構成を作成
  • wrangler.jsonc を置き、静的アセット配信と not_found_handling: "single-page-application" を設定

0-2. 型とシード

  • src/lib/types/ に7章の型定義をすべて実装
  • src/lib/seed/ を実装(7章の件数・分布どおり。乱数の種を固定)
  • 文章をお客様・段階に応じて書き分ける。テンプレの使い回し禁止
  • 日付は現在日時からの相対で生成する
  • 工事写真を scripts/fetch-photos.mjs で取得し、public/photos/works/ と CREDITS.json を作る(着工前・完了の組み合わせを確認する)
  • src/lib/calc/estimate.ts と schedule.ts を実装し、テストを通してから、見積と工程のシードを作る(シードの粗利と重なりが、この関数の結果と一致するように)

0-3. ストアとリポジトリ

  • src/lib/store/{session,data,settings,ui}.ts を Zustand + persist で実装
  • src/lib/repo/_scope.ts を最初に実装する(FR-005, FR-006)
  • src/lib/repo/ の全モジュールを実装。全メソッド async、擬似ディレイ(一覧の絞り込みは100ms以下)、Result型、スコープ適用 (FR-010)
  • src/lib/calc/ に業種の計算(7章の派生値)を実装
  • スコープと calc の単体テストをこの時点で書く。後回しにしない

0-4. デザインシステム

  • src/styles/tokens.css にトークンを CSS 変数(チャンネル値)で定義し、Tailwind の theme から参照
  • フォント(Noto Sans JP 可変 / Inter)を読み込み、数値に tabular-nums を適用
  • タイプスケールをユーティリティクラスとして定義
  • Radix ベースで Button / Input / Select / Checkbox / Dialog / Sheet / Popover / Toast / Badge / Tabs / Tooltip / DropdownMenu を作り、トークンに合わせる
  • アプリシェル(サイドバー折りたたみ、ヘッダー、パンくず、スマホの下部タブ)
  • 共通コンポーネント:EmptyState(データ0件と絞り込み0件を出し分け)/Skeleton(行の形)/MetricCard / StatusBadge / TagChip / UserAvatar / StageBar / ActivityTimeline / TaskRow
  • src/lib/i18n/terms.ts に業種の言葉をまとめる
  • prefers-reduced-motion の全体対応
  • /dev/components にコンポーネントカタログを作成(公開版では出さない)

0-5. デモ基盤

  • RoleSwitcher(3ロール + 担当のメンバー選択)(FR-001, FR-002)
  • デモ切替バーを固定配置。プロダクトのトークンとは別扱いのデザイン
  • 「デモをリセット」(FR-003)
  • ロール権限外アクセス時の案内画面 (FR-008)
  • 権限外の操作のボタンを非活性にし、理由をツールチップで出す仕組み(can(action, record) を repo から返す)(FR-007)
  • 通知センター(ヘッダーの鈴・未読の件数・一覧・既読)(FR-907)

Phase 0 完了チェック

  • /dev/components で全コンポーネントがトークン通りに表示される
  • ロールを切り替えると、リポジトリが返す件数が変わる(スコープのテストが通る)
  • リロードしても状態が保持される (FR-004)

Phase 1 — 一覧基盤とお客様管理(4日)

1-1. データテーブル基盤(最重要。ここの品質が全画面に波及する)

  • src/lib/query/ に 絞り込み・ソート・ビュー適用ロジックを実装(テスト付き)
  • DataTable(TanStack Table ヘッドレス + 自前UI)。固定ヘッダー、列幅リサイズ
  • 列カスタマイズ(表示・非表示・並び替え)(FR-101)/ソート(複数列)(FR-102)
  • FilterBar:項目ごとの条件指定 (FR-103)/URLクエリとの同期 (FR-104)/条件チップ (FR-105)
  • 行選択と BulkActionBar(下からせり上がる)(FR-108, FR-109)
  • 取り消し可能な削除トースト (FR-110, IX-06)
  • 仮想スクロール (FR-113)/密度切替 (FR-114)
  • キーボード操作(↑↓ Enter Space ⌘A)(IX-02)/インライン編集 (FR-115, IX-03)
  • スマホ幅でカード型リストに切り替える (FR-116)

1-2. 保存ビュー

  • ViewSidebar:ビュー一覧、件数バッジ、ワンクリック切替 (FR-107)
  • ビューの保存・編集・削除。個人/共有の区別(共有は工事責任者以上)(FR-106)

1-3. お客様

  • SC-020 お客様一覧(上記テーブル基盤を適用。築年・OB・最後の工事の列)(FR-201)
  • SC-021 お客様詳細(インライン編集、建物の情報、工事の履歴、タブ構成)(FR-151, FR-202, FR-204)
  • SC-022 お客様の新規作成 + 重複の検出 (FR-152)
  • SC-010 問い合わせの受付モーダル (FR-203)
  • 対応記録モーダルと、次にやることからのタスク自動生成 (FR-156, FR-157)
  • SC-095 タスク/SC-096 対応履歴 (FR-158, FR-159)

1-4. CSV入出力

  • src/lib/csv/ にインポート(列の対応付け・検証)/エクスポートを実装
  • インポート4ステップ(ファイル選択 → 列の対応付け → プレビュー → 結果)(FR-153, FR-154)
  • 数式インジェクションの無害化 (NFR-09)
  • エクスポート(現在の絞り込み・表示列のまま、BOM付きUTF-8で実際にダウンロード)(FR-155)

1-5. 横断検索・コマンドパレット

  • ヘッダーの横断検索(種別グループ化)(FR-111)
  • ⌘K コマンドパレット(cmdk)(FR-112)
  • ショートカット:/ 検索フォーカス、N 新規作成、? 一覧表示 (IX-04, IX-05)

Phase 1 完了チェック

  • CSVインポート → 一覧に反映 → 書き出し が完走する
  • 1,000行でも絞り込みが100ms以下、スクロールが60fps
  • テーブルがキーボードのみで操作完遂できる
  • ロールを切り替えると一覧の件数が変わる
  • スマホ幅(375px)で、一覧がカード型になり横にはみ出さない

Phase 2 — 現地調査と見積(5日)

  • SC-040・041 現地調査の予定と記録(スマホ優先、カメラから撮る、縮小)(FR-211〜214)
  • src/lib/calc/estimate.ts とテスト(6.7 の例)
  • SC-051 見積の作成・編集(工種 → 行、原価・売価、即時の再計算、上部に固定した粗利率)(FR-221〜227)
  • ひな形の読み込み (FR-225)/諸経費・値引き (FR-226, FR-227)
  • 目標の粗利率を下回るときの承認待ちと、承認・差し戻し (FR-224)
  • SC-052 案の比較 (FR-228)
  • SC-053 見積書プレビューとPDF(原価なし)(FR-229, FR-171〜174)
  • SC-050 見積の一覧 (FR-230)
  • SC-001 ダッシュボード(ロールで範囲が変わる)(FR-281)

Phase 2 完了チェック

  • フローAが完走する
  • 4章「ロールを跨ぐ体験」の1が動作する(5は見積のひな形の編集を作る Phase 4 で確認)
  • 見積書PDFに原価・粗利が1つも出ていない

Phase 3 — 工事・工程・写真・入金(5日)

  • SC-030・031 工事ボード(段階の列、件数と契約金額、ドラッグとキーボード)(FR-231, FR-232)
  • SC-032 工事詳細、契約と支払条件、入金予定の自動生成 (FR-233, FR-234)
  • 追加・変更工事と、契約金額への加算・追加工事の入金予定の作成 (FR-235)
  • 実行予算 (FR-236)/返事待ちの印 (FR-237)/失注の登録 (FR-238)
  • src/lib/calc/schedule.ts とテスト、SC-060・061 工程表(自前のガント、ドラッグとキーボード、重なりの警告、現場の行/協力業者の行、スマホのリスト)(FR-241〜247)
  • SC-070 工事写真の台帳、前後の比較 (FR-251, FR-252)
  • SC-071 作業日報(スマホで1分、前日の下書き)(FR-253)
  • SC-072 工事完了報告書PDF (FR-254, FR-171〜174)
  • SC-080・081 入金(記録と確定)と請求書PDF(適格請求書)(FR-261〜263, FR-171〜174)
  • 引渡し時の点検のタスクの自動生成と Inspection (FR-271)
  • 写真の保存(IndexedDB・1枚200KB以下・容量の警告)(FR-255)

Phase 3 完了チェック

  • フローB・Cが完走する
  • 4章「ロールを跨ぐ体験」の2・3・4が動作する
  • 工事完了報告書PDFに、写真が崩れずに入っている

Phase 4 — アフター・分析・設定(3日)

  • SC-091 アフター点検(結果の記録・要対応から新しい工事)、次の提案の候補 (FR-272, FR-273)
  • SC-090 協力業者の一覧・SC-212 協力業者の登録 (FR-291, FR-292)
  • SC-100 粗利の分析 (FR-282)/SC-101 受注の分析 (FR-283)/SC-102 協力業者の稼働 (FR-284)/SC-103 失注の分析
  • 期間の指定 (FR-901)
  • SC-201〜207 共通の設定 (FR-902〜907)
  • SC-208 工種と見積のひな形/SC-209 目標の粗利率・承認/SC-210 支払条件/SC-211 点検のルール/SC-212 協力業者

Phase 4 完了チェック

  • フローD・Eが完走する
  • 4章「ロールを跨ぐ体験」の5が動作する(ひな形の変更)

Phase 5 — 仕上げ(3日)

5-1. 体験の総点検

  • 4章「ロールを跨ぐ体験」をすべて手動で確認する
  • 全44画面を開き、空の画面が1つもないことを確認する
  • 全画面の空状態(データ0件/絞り込み0件の出し分け)・読み込み中・エラー状態を確認する
  • ガイドツアーを実装 (FR-009)
  • localStorage 容量上限時の警告 (NFR-10)
  • 全画面の文言をリフォーム・工務店の言葉で読み直す。 汎用の言葉(リード・商談・アカウント・ステータス等)が残っていないこと

5-2. アクセシビリティ監査

  • axe-core を全画面に実行し、Critical / Serious を0件に
  • キーボードのみで全画面を操作完遂する手動確認
  • 14px本文のコントラスト比を実測して 4.5:1 以上を確認 (A11Y-01)
  • 文字サイズ200%での確認 (A11Y-10)

5-3. パフォーマンス

  • PDF・グラフ・CSVを動的読み込みに切り出し、初期バンドルを250KB以下に (NFR-06)
  • 1,000行での絞り込み100ms以下、スクロール60fps を実測 (NFR-04, NFR-05)
  • Lighthouse で Performance 90 / Accessibility 95 を達成 (NFR-07)
  • 320px〜2560px で崩れないことを確認 (NFR-11)

5-4. テストと公開

  • Playwright で 5章の主要フローの E2E を実装・実行
  • Vitest:src/lib/query src/lib/calc src/lib/csv src/lib/repo/_scope のカバレッジ80%以上
  • /dev/components を公開版で非表示に
  • Cloudflare Workers へ公開(npx wrangler deploy)
  • 公開URLで、直接開いた詳細画面のURL(例 /works/w-001)が 404 にならないことを確認する

合計 約23営業日(約4.5週間)/1名専任 + レビュー体制。

工数配分の意図: Phase 1 に4日を割いているのは、データテーブル基盤が全画面に波及するため。ここを雑に作ると、以降の全一覧画面が作り直しになる。逆にここが良ければ、業種の一覧はほぼ設定だけで完成し、Phase 2〜4 の時間を業種の作り込みに使える。


12. 受入基準

  1. 6章の優先度 P1 の要件がすべて実装されていること
  2. 5章の主要フローが、最初から最後まで完走すること。フローと4章の体験に出てくる機能は、6章の優先度が P2・P3 でも必須とする
  3. 4章「ロールを跨ぐ体験」がすべて動作すること
  4. ロールを切り替えると、一覧・ダッシュボード・分析の表示範囲が変わること。かつスコープ判定が src/lib/repo/_scope.ts に集約されていること
  5. 一覧テーブルが、絞り込み・列選択・保存ビュー・一括操作・キーボード操作のすべてに対応し、スマホ幅ではカード型になること
  6. 1,000行での絞り込みが100ms以下、スクロールが60fpsを維持すること
  7. CSVインポートが列の対応付けとエラー行表示に対応し、CSVの書き出しと帳票PDFが実際にダウンロードできること
  8. 全44画面のいずれにも空の状態がなく、リフォーム・工務店らしいリアルなデータが表示されていること
  9. リロード後も操作結果が保持され、「デモをリセット」で初期状態に戻ること
  10. axe-core で Critical / Serious の指摘が0件であること
  11. Lighthouse の基準値を満たすこと
  12. データアクセスがすべて src/lib/repo/ を経由しており、コンポーネントが Zustand ストアを直接参照していないこと
  13. 見積の原価・粗利が、入力のたびに正しく再計算され、お客様向けの見積書PDFに一度も出ないこと
  14. 工程の重なり(同じ協力業者が同じ日に2現場)が、全現場の工程表と工事ごとの工程の両方で検出されること
  15. 承認された追加工事が契約の金額に加算されて追加工事の入金予定が作られ、未承認の追加工事は工事詳細で分かること
  16. 引渡し済みにすると、点検のタスクがルールどおりに作られること
  17. スマホ(375px)で、現地調査の記録・写真の撮影・作業日報が片手で使えること(ボタンの高さ56px・文字16px以上)

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

  1. 仕様がこの文書にない場合は、実装せずに質問する。 推測で作らない
  2. キーボード操作と「空の画面を作らない」は削減対象外。 速度を出すために削らない
  3. スコープ外(3章 Won't have)は、思いついても実装しない。特にワークフローのビルダーと帳票の自由レイアウト編集
  4. 「デモだから」を理由に品質を落とす判断はしない
  5. コンポーネントからストアを直接触りたくなったら、それはリポジトリ層に足りないメソッドがあるということ
  6. 迷ったらリフォーム・工務店の人の1日を思い浮かべる。 その人が毎朝最初に開く画面で、最初に知りたい数字は何か。それが画面のいちばん上にあるか
  7. 見積の計算・粗利を、画面のコンポーネントの中で計算しない。 すべて src/lib/calc/estimate.ts を通す
  8. お客様に渡す帳票(見積書・請求書・報告書)に、原価・粗利・社内のメモが出ていないかを、帳票を変えるたびに確認する

FROM DEMO TO PRODUCTION

本番で使うには、あと4つ必要です

この要件定義書は、画面と動きを確かめるためのデモとして書かれています。「【リフォーム】顧客・工事管理システム」を社内やお客さまに実際に使ってもらうには、見た目の裏側に次の4つが要ります。

  1. 1データの保存

    デモでは
    データはその端末のブラウザの中にしか残りません。ほかの端末やほかの人とは共有されず、消えることもあります。
    本番では
    サーバーのデータベースに保存し、バックアップと復元ができるようにします。
  2. 2セキュリティ

    デモでは
    ログインがなく、誰でもすべての画面とデータを見られます。
    本番では
    ログイン、権限(誰が何を見られるか)、通信とデータの暗号化、不正なアクセスへの対策を入れます。
  3. 3ガバナンス(運用ルール)

    デモでは
    決めていません。
    本番では
    誰がいつ何をしたかの記録、個人情報の扱い(プライバシーポリシー・同意)、アカウントの発行と削除、障害のときの連絡体制を決めます。
  4. 4公開・デプロイ

    デモでは
    手元で動かすか、デモとして公開するだけです。
    本番では
    独自ドメイン、本番とテストの環境分け、更新の手順、監視と障害対応、月々の費用の管理を整えます。

本番運用をお考えの方へ

ぜひ一度ご相談ください。最適なプランのご紹介と、進め方をお伝えします。代表の西澤が直接お話しします。

  • 自分で作ったアプリを、そのまま本番で使いたい
  • どこまで自分で作り、どこから任せるか決めたい
  • 社内の決まりやセキュリティの基準に合わせたい

下のカレンダーから、空いている日時を選ぶだけで予約できます。

料金とプランは、サービス資料(全29ページ)にまとめています。先に質問したいときは、公式LINE か お問い合わせフォーム からもお気軽にどうぞ。

FREE CONSULTATION

分からないときは、お気軽に30分無料相談へ

途中で止まった、エラーが消えない、自社向けに作り変えたい。どんなことでも大丈夫です。

日程を決めて話す

代表の西澤と直接お話しできます。空いている日時を選ぶだけで予約できます。

代表 西澤と話す日程を選ぶ

まずは問い合わせる

要件定義書がほしい方・ご相談は公式LINEから。お問い合わせフォームからも受け付けています。