SOUZOHSPECS

業務システム ・ SUMIKA

【不動産】顧客・物件管理システム

不動産向け

反響から契約まで、追客を取りこぼさない不動産仲介のための顧客・物件管理

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

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

v1.0・作成 2026-09-30

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

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

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

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

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

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

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

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

    Claude のデスクトップアプリで「Code」タブを開き、「Select folder」から sumika-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つ必要です。

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

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

版数 1.0(DBレス構成)/ 作成日 2026-09-30 / 発行 ソウゾウ合同会社 用途 業種特化アプリの実演デモ / 不動産仲介向け 顧客・物件管理編


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

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

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

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


目次

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

1. プロジェクト概要

背景と目的

地域の不動産仲介会社(賃貸・売買の仲介を行う、社員5〜30名規模の会社)の多くは、ポータルサイトから届く反響メールをメールソフトで受け、顧客と物件の情報をExcelと紙で管理している。反響が集中する繁忙期(1〜3月)には、初回の連絡が遅れたお客様が他社で決めてしまう。追客(あとからの連絡)も担当者の記憶頼みで、止まったまま忘れられる。

汎用の顧客管理を入れても、「物件」「内見」「申込」「重要事項説明」がないため、結局Excelに戻る。SUMIKA は、反響の受付から契約・鍵渡しまでを、不動産仲介の順番と言葉のまま1つにまとめる。

目的 内容
業種特化の実装力の証明 反響・物件・内見・申込・契約という不動産仲介の業務の流れを、そのまま画面にする
取りこぼしを減らす設計の証明 反響への初回連絡の速さ、止まった追客、条件に合う新着物件を、システム側から知らせる
現場で使える操作性の証明 外出先(内見・現地)でスマホから記録でき、店では一覧で素早くさばける
横展開の資産化 共通の土台(ロール・一覧・設定・帳票)に、業種の部分だけを載せる構造にする

プロダクト定義

項目 内容
プロダクト名 SUMIKA(すみか)※仮称
一言定義 反響から契約まで、追客を取りこぼさない。不動産仲介のための顧客・物件管理
提供形態 レスポンシブWebアプリ。フロントエンド完結(サーバー側の保存なし)
主戦場 店のPC(反響の対応・物件の登録・提案書の作成)とスマホ(内見の現場・移動中の記録)
想定利用者 賃貸・売買の仲介会社の営業、店長、事務・本部の管理者

プロダクトコンセプト

「反響は、待たせない。追客は、止めない。」

仲介の売上は、反響に早く返せたか、内見まで進められたか、申込の後に抜け漏れなく契約まで運べたかで決まる。SUMIKA は、画面を開いた瞬間に「今すぐ返すべき反響」「止まっている追客」「条件に合う新着物件」を返すことを設計の中心に置く。入力を増やすのではなく、次の一手を示す。

デモとしての成功条件

  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/cases.ts — 中身は同期でも async にする
export async function findCases(q: Query): Promise<Result<CaseView[]>> {
  await delay('list')
  const all = useDataStore.getState().cases
  return { ok: true, data: scopeCases(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-I01 反響の受信箱 新着の反響を経過時間の短い順に表示。未対応・対応中・対応済みで切替 Must
F-I02 反響の取り込み ポータルサイトの反響メールの本文を貼り付けると、顧客・希望条件・問い合わせ物件を読み取って登録する Must
F-I03 担当の割当 店長が反響を営業に割り当てる。自動の割当(順番・店舗)も選べる Must
F-I04 初回連絡の記録 受信箱からワンクリックで「電話した/メールした」を記録。受信から初回連絡までの時間を自動で計る Must
F-I05 重複の判定 同じお客様からの別ポータル経由の反響を、電話・メールで照合してまとめる Must

顧客・希望条件

ID 機能 概要 優先度
F-C01 顧客一覧 テーブル表示、絞り込み、並び替え、列の選択、保存ビュー Must
F-C02 顧客詳細 基本情報、希望条件、案件、対応履歴、提案した物件、内見の履歴 Must
F-C03 希望条件 エリア(駅・市区町村)、賃料/価格の上限、間取り、面積、築年数、駅からの徒歩分数、入居・購入の時期、こだわり条件 Must
F-C04 追客の状態 最後の連絡からの日数を自動で数え、止まっている顧客を知らせる Must
F-C05 一括操作 担当変更/タグ付与/追客の文面を一括で作成 Must

物件

ID 機能 概要 優先度
F-P01 物件一覧 写真付きのカードと表の切替。賃料/価格・間取り・駅・徒歩・築年・状態で絞り込み Must
F-P02 物件詳細 写真、概要、設備、周辺、元付の業者、問い合わせの多さ、条件の合う顧客 Must
F-P03 物件の登録・編集 写真の追加(ブラウザ内で縮小)、募集状態の変更 Must
F-P04 募集状態の管理 募集中/申込あり/成約済み/募集終了。成約済みの物件を提案・広告に出せないようにする Must
F-P05 条件の照合(マッチ) 顧客の希望条件と物件を照合して合う度合いを出す。顧客からも物件からも引ける Must

提案・内見

ID 機能 概要 優先度
F-V01 物件提案 顧客に合う物件を選び、提案書(PDF)と送る文面を作る。提案した記録を残す Must
F-V02 内見の予定 日・週のカレンダー。物件・顧客・担当・鍵の手配を1つの予定として持つ Must
F-V03 内見の結果 物件ごとの感想・評価を記録。気に入らなかった理由から次の提案につなげる Must
F-V04 内見のまわる順番 同じ日の複数物件を、住所から近い順に並べて見せる(地図は使わず住所の近さで) Could

案件(申込〜契約)

ID 機能 概要 優先度
F-D01 案件ボード 段階別の列表示(カンバン)。賃貸と売買で段階を切り替える Must
F-D02 案件詳細 段階バー、申込の内容、契約までの予定、必要書類のチェック、関連する顧客・物件 Must
F-D03 必要書類のチェック 申込・審査・契約に必要な書類を、ひな形から自動で並べ、受領を記録する Must
F-D04 契約までの予定 審査の結果予定日、重要事項説明の日時、契約日、鍵渡し・決済日 Must
F-D05 仲介手数料 取引の種類と金額から上限額を自動で計算し、見込み額を持つ Must
F-D06 成約・失注 成約日・手数料の確定、失注理由(他社で決定・条件変更・審査否決 など) Must

分析

ID 機能 概要 優先度
F-R01 ダッシュボード 今日の内見、未対応の反響、止まっている追客、今月の申込・契約・手数料見込み Must
F-R02 反響の分析 媒体別の 反響→来店・内見→申込→契約 の歩留まり、初回連絡の速さ別の成約率 Should
F-R03 担当者別の実績 反響数・内見数・申込数・契約数・手数料。店長以上のみ Should
F-R04 手数料の予実 月次の目標と実績、見込み(段階ごとの見込み率で加重) Should
F-R05 物件の動き 問い合わせの多い物件、長く決まらない物件 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)

項目 理由
業者間の物件情報システム・ポータルサイトとの自動連携 反響メールの貼り付けで再現する。各サービスの規約と接続契約が必要なため
物件広告の出稿・一括入稿 対象外
家賃の集金・入金管理・賃貸管理(管理物件の修繕・更新) 仲介の業務に絞る
電子契約・重要事項説明書の作成 日程と必要書類の管理までを対象とする
本人確認書類・収入証明の画像の保管 個人情報の扱いが重いため、デモでは「受領した」記録とファイル名のみ
地図の表示・経路の検索 住所の近さで代替(F-V04)
売却の依頼(査定・媒介契約・売り出し)の段階管理 「売却を検討」の顧客は、登録・追客・対応記録・タスクまでを扱う。案件ボードと照合の対象にしない
データベース・バックエンドAPI 2章の方針に基づく
本物の認証・SSO ロール切替で代替
実際のメール・SMS・LINEの送受信 送信内容のプレビューで再現
外部カレンダー連携(Google / Outlook) 予定は内部で保持。.ics のダウンロードのみ対応
ワークフローの自由な組み立て(ノーコードのビルダー) 固定ルールのみ実装
帳票レイアウトの自由編集 決まった帳票のみ。ロゴ・会社情報・備考の差し替えだけ対応
モバイルのネイティブアプリ レスポンシブWebで対応
複数ブラウザ間でのデータ共有 各ブラウザで独立。デモとして問題ない

スコープリスク: 業務システムは「あれもこれも」が最も起きやすい領域。特にワークフローのビルダーと帳票の自由レイアウト編集は、単体で数週間かかる。要望が出た場合は別フェーズとして見積り、この文書のスコープは変えない。


4. ロールとデモ切替

ロール定義

ロールID 名称 見えるデータ 特徴的な権限
staff 営業 自分が担当する顧客・案件と、全物件 自分の担当の登録・編集、物件の登録、内見の予定。他人の顧客は見えない
manager 店長 自店舗の全員の顧客・案件(SUMIKA のチーム=店舗。Team.id は Store.id と同じ値にする) 反響の担当の割当、店舗の実績の閲覧、共有ビューの作成、手数料の確定
admin 管理者 全店舗のデータ 設定(段階・必要書類のひな形・手数料の計算・取り込みの読み方)、メンバー管理、操作ログ

切替バー: 店長ロールでは2店舗の店長から選べる(既定は駅前店)。営業ロールでは、選んだ店舗の営業3名から選べる。

物件は全員が見える。 物件は会社の在庫であり、担当に関係なく提案に使うため。見える範囲を絞るのは「顧客」と「案件」だけにする(個人情報であるため)。

認証は行わない。ロールはストアの状態として保持し、切替バーから即座に変更できる。

データスコープ(デモの見せ場)

ロールによって同じ画面の表示件数が変わることを、明確に体験させる。

  • 営業(佐々木・駅前店)で顧客一覧を開く → 自分の顧客 28名
  • 店長(駅前店)に切替 → 同じ画面が店舗全体の 96名になり、担当者の絞り込みと「未割当の反響」が出現する
  • 管理者に切替 → 全店舗 220名。設定メニューと、店舗の比較が出現する

スコープの適用は src/lib/repo/_scope.ts に集約し、全リポジトリメソッドが必ず通す。コンポーネント側でフィルタしない(本番化でデータベース側の権限設定に置き換わる箇所であるため)。

デモ切替バー(F-S01)

画面上部に常時表示する固定バー。

  • 現在のロールと操作中の人の名前の表示、3ロールの切替
  • 営業ロール時:3名のメンバーから選択(見え方の違いを体験できる)
  • 「デモをリセット」ボタン(確認ダイアログ付き)
  • 「これはデモです。入力した内容はこのブラウザの中にだけ保存されます」の明示

デザイン上の扱い: プロダクト本体のUIとは意図的に別扱い(墨色の帯 + 小さめの文字)にし、「アプリの外側にある操作パネル」であることを視覚的に区別する。スマホでは1行に収め、ロール名はアイコン+短い名前にする。

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

  1. 店長が新着の反響を営業(佐々木)に割り当てる → 佐々木に切替 → 受信箱の先頭に現れ、通知が届いている
  2. 営業が受信箱から「電話した」を記録 → 店長に切替 → ダッシュボードの未対応の反響が1件減り、初回連絡の平均時間が更新されている
  3. 営業が新しい物件(募集中)を登録 → 条件の合う顧客が物件詳細に並び、その担当の営業に「条件に合う新着物件」が通知される
  4. 管理者が必要書類のひな形に「緊急連絡先の届出」を追加 → 営業の案件詳細(申込の段階)のチェックリストに、その書類が出現する
  5. 物件を「成約済み」にする → その物件が提案の候補から消え、提案書の作成画面で選べなくなる

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

全40画面。画面IDはディレクトリ構成と 1:1 で対応させる。

メイン画面

画面ID 画面名 パス 主要要素
SC-001 ダッシュボード / 今日の内見、未対応の反響(経過時間)、初回連絡の平均時間、止まっている追客、契約までの予定、今月の申込・契約・手数料見込み
SC-010 反響の受信箱 /inquiries 新着順・経過時間、媒体、問い合わせ物件、担当、初回連絡ボタン
SC-011 反響の取り込み /inquiries/import 本文の貼り付け → 読み取り結果の確認 → 顧客・案件として登録
SC-020 顧客一覧 /customers テーブル、絞り込み、列の選択、保存ビュー、一括操作、CSV入出力
SC-021 顧客詳細 /customers/:id 基本情報、希望条件、案件、対応履歴、提案した物件、内見の履歴、合う物件
SC-022 顧客の新規作成 /customers/new フォーム。電話・メールの重複を入力中に検出
SC-023 CSVインポート /customers/import ファイル選択 → 列の対応付け → プレビュー → 取込結果
SC-030 案件ボード /cases 賃貸/売買の切替、段階別の列、ドラッグ、列ごとの件数・手数料見込み
SC-031 案件一覧(表) /cases?view=table ボードと同じデータの表形式
SC-032 案件詳細 /cases/:id 段階バー、申込の内容、契約までの予定、必要書類、手数料、関連する顧客・物件
SC-033 成約・失注の登録 モーダル 成約日・確定手数料/失注理由(定型選択 + 自由記述)
SC-040 物件一覧 /properties 写真カード/表の切替、賃料・価格・間取り・駅・徒歩・築年・状態で絞り込み
SC-041 物件詳細 /properties/:id 写真ギャラリー、概要・設備、元付、問い合わせ数、条件の合う顧客
SC-042 物件の登録・編集 /properties/:id/edit 基本項目、設備のチェック、写真の追加・並び替え
SC-043 条件の照合 /match 顧客を選ぶ → 合う物件を合う度合い順に/物件を選ぶ → 合う顧客を順に
SC-050 物件提案の作成 /proposals/new?customer= 物件の選択(最大6件)、並び替え、ひとことコメント、送る文面
SC-051 提案書プレビュー モーダル 印刷レイアウト → PDFダウンロード
SC-052 提案の履歴 /proposals 顧客ごとの提案した物件、反応(内見希望・見送り)
SC-060 内見の予定 /viewings 日・週のカレンダー、担当別の列、鍵の手配の状態
SC-061 内見の登録 モーダル 顧客、物件(複数)、日時、集合場所、鍵の手配(元付に連絡済み/現地のキーボックス など)
SC-062 内見の結果 モーダル 物件ごとの評価(◎○△×)、良かった点・気になった点、次にやること
SC-070 タスク /tasks 期限別(超過/今日/今週/今後)、担当者の絞り込み
SC-071 対応履歴 /activities 全対応のタイムライン。種別・担当・期間で絞り込み

分析画面

画面ID 画面名 パス 主要要素
SC-100 反響の分析 /reports/inquiries 媒体別の歩留まり(反響→内見→申込→契約)、初回連絡の速さ別の成約率
SC-101 担当者別の実績 /reports/members 反響・内見・申込・契約・手数料(店長以上)
SC-102 手数料の予実 /reports/fees 月次の目標・実績・見込み、達成率
SC-103 物件の動き /reports/properties 問い合わせの多い物件、募集から日数の長い物件
SC-104 失注の分析 /reports/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/inquiry-rules 媒体ごとの本文の読み方(「お名前:」の次の行を氏名に、など)、試しに読む
SC-209 必要書類のひな形 /settings/documents 取引の種類 × 段階ごとの必要書類
SC-210 仲介手数料の計算 /settings/fees 上限額の計算式の確認、実際に請求する割合の既定値、消費税率
SC-211 店舗 /settings/stores 店舗名・住所・電話・宅建業の免許番号(帳票に差し込む)

主要フロー

フローA:反響の受付から内見の予定まで

【ロール:店長】
SC-010 反響の受信箱 ──「取り込み」
   ↓
SC-011 反響の取り込み ── ポータルサイトから届いた反響メールの本文を貼り付け
   読み取り結果:氏名/電話/メール/問い合わせ物件/希望の入居時期/メッセージ
   ↓  ★ 電話番号が既存の顧客と一致 →「同じお客様です。まとめますか?」
「登録する」→ 顧客・案件(段階:反響)が作られ、受信箱の先頭に並ぶ(経過 0分)
   ↓
担当に「佐々木」を割り当てる → 佐々木に通知
   ↓
【ロール切替:営業(佐々木)】
SC-010 受信箱の先頭に割り当てられた反響 ──「電話した」
   ↓  ★ 初回連絡までの時間(例 12分)が記録され、段階が「初回連絡」に進む
対応記録のモーダル(FR-156)── 内容・次にやること「内見の候補日を送る(明日)」
   ↓  ★ タスクが自動生成される
SC-043 条件の照合 ── 顧客の希望条件に合う物件が、合う度合い順に並ぶ
   ↓
SC-050 物件提案 ── 3件を選んで提案書PDF + 送る文面をコピー → 提案の記録が残る
   ↓
SC-061 内見の登録 ── 2物件・土曜10時・鍵は元付に連絡済み
   ↓
SC-060 内見の予定に並び、ダッシュボードの「今日の内見」に出る

フローB:内見から申込・契約・鍵渡しまで

【ロール:営業】
SC-062 内見の結果 ── 物件A ◎(申込したい)/物件B △(日当たりが気になる)
   ↓
SC-032 案件詳細 ── 段階を「申込」へ(物件を「申込あり」にする確認 → 同意)
   ↓  ★ 必要書類のチェックリストが自動で並ぶ(入居申込書・本人確認書類・収入を証明する書類…)
書類を受け取るたびにチェック → 全部そろうと「審査へ進める」が押せるようになる
   ↓
段階「審査」→ 審査の結果予定日を入れる → 期日がタスクになる
   ↓
段階「契約」→ 重要事項説明の日時・契約日を入れる
   ↓  ★「物件を成約済みにしますか?」の確認 → 同意すると募集状態が「申込あり」→「成約済み」に変わる
SC-033 成約の登録 ── 仲介手数料(上限額が自動計算済み)を確認して確定
   ↓
SC-102 手数料の予実に実績として計上される

フローC:止まった追客の立て直し(店長の週次の確認)

【ロール:店長】
SC-001 ダッシュボード ──「止まっている追客 9件」(最後の連絡から14日以上)
   ↓
一覧を開く → 顧客ごとに、最後の連絡・希望条件・提案した物件が並ぶ
   ↓
★「条件に合う新着物件あり」の印がついた顧客を先に選ぶ
   ↓
担当にタスクを割り当て「新着物件を提案(今週中)」
   ↓
【ロール切替:営業】
タスク一覧に並んでいる → SC-050 物件提案で、新着物件をすぐに提案できる

フローD:Excelからの移行(CSVインポート)

SC-020 顧客一覧 ──「インポート」
   ↓
SC-023 Step1 ファイル選択(CSVをドロップ)
   ↓
Step2 列の対応付け(「お客様名」→氏名、「TEL」→電話、「希望エリア」→希望条件のエリア …)
   自動推測 + 手動修正。対応しない列は「取り込まない」または「カスタム項目として追加」
   ↓
Step3 プレビュー(先頭10行の変換結果、エラー行を理由付きで表示)
   ↓
Step4 取込実行 → 成功 186件 / スキップ 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 対応記録(電話・メール・SMS・来店・内見・物件提案など)を、一覧画面や詳細画面から遷移せずにモーダルで記録できること 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 受信箱は、未対応の反響を受信からの経過時間付きで新しい順に並べること。経過30分を超えたものは --warn、2時間を超えたものは --alert の印を付けること(色 + アイコン + 文字) P1
FR-202 反響の取り込みで、貼り付けた本文から 氏名・フリガナ・電話・メール・問い合わせ物件(物件名または物件番号)・希望の時期・メッセージ を読み取ること。読み取れなかった項目は空欄のまま確認画面で入力できること P1
FR-203 読み取りは設定(SC-208)の「媒体ごとの読み方」に従うこと。シードに架空の媒体3種(ポータルA・ポータルB・自社ホームページ)の読み方と、それぞれの反響メールの見本を入れること P1
FR-204 取り込んだ反響の問い合わせ物件が登録済みの物件と一致した場合、案件に自動で紐づけること P1
FR-205 電話番号またはメールが既存の顧客と一致した場合、「同じお客様です。まとめますか?」を表示し、まとめると既存の顧客に新しい案件として追加すること P1
FR-206 店長は反響の担当を割り当てられること。割り当ての方法として「手動」「店舗の営業に順番」を選べること P1
FR-207 受信箱から「電話した」「メールした」「SMSした」をワンクリックで記録でき、受信から初回連絡までの分数を案件に保存すること。記録すると段階が「初回連絡」に進むこと P1

6.6 顧客・希望条件・追客

ID 要件 優先
FR-211 顧客に、氏名・フリガナ・電話・メール・連絡してよい時間帯・連絡方法の希望・区分(賃貸で探している/購入を検討/売却を検討)・担当・店舗・タグ・メモ を登録できること P1
FR-212 希望条件に、エリア(駅は複数、市区町村は複数)・賃料または価格の上限と下限・間取り(複数)・専有面積の下限・築年数の上限・駅からの徒歩分数の上限・時期・こだわり条件(ペット可・2階以上・バストイレ別・駐車場・オートロック など)を登録できること P1
FR-213 顧客ごとに最後の連絡からの日数を算出し、既定14日(設定で変更可)を超えたら「追客が止まっている」として印を付けること P1
FR-214 顧客詳細に、案件・対応履歴・提案した物件・内見の履歴・合う物件(上位5件)をタブで表示すること P1
FR-215 顧客一覧から複数の顧客を選び、文面テンプレートから追客の文面をまとめて作れること(1人ずつ差し込み変数を置換し、送る前に全員分のプレビューを見られる) P2

6.7 物件

ID 要件 優先
FR-221 物件に、物件名・取引の種類(賃貸/売買)・種別(マンション・アパート・一戸建て・土地・店舗事務所)・所在地(市区町村まで + 以降)・最寄駅と徒歩分数(最大3つ)・賃料と管理費/価格・敷金・礼金・間取り・専有面積・階数・築年月・構造・設備・入居可能時期・元付の業者・写真 を登録できること P1
FR-222 物件一覧は写真カードと表を切り替えられ、絞り込み条件は切替後も維持されること P1
FR-223 物件の写真はブラウザ内で長辺1280pxに縮小して保持し、並び替え・代表写真の指定ができること P1
FR-224 募集状態(募集中/申込あり/成約済み/募集終了)を持ち、成約済み・募集終了の物件は、提案の候補・照合の結果に出さないこと P1
FR-225 物件詳細に、問い合わせ数(反響の件数)と内見の件数、条件の合う顧客(合う度合い順)を表示すること P1
FR-226 募集中の物件を登録・変更したとき、合う度合いが80%以上の顧客の担当営業に「条件に合う新着物件」を通知すること P1

6.8 条件の照合(マッチ)

ID 要件 優先
FR-231 照合は src/lib/calc/match.ts の1つの関数で行い、顧客→物件・物件→顧客の両方で同じ関数を使うこと P1
FR-232 合う度合いは、**必須の条件(取引の種類・賃料または価格の上限・エリア)を満たさない物件は0%**とし、満たすものを100点満点で採点すること。エリアは「希望の駅のどれか」または「希望の市区町村のどれか」に当てはまれば満たす(両方とも未入力なら条件なし)。配点:間取り 20/徒歩 15/面積 15/築年 10/時期 10/こだわり条件 30(希望したこだわり条件の数で30点を等分し、満たした数だけ加点。こだわり条件が0件なら30点)。未入力の条件はその配点を満点とする。内訳を画面に出すこと P1
FR-233 合う度合いの横に「合っている点」と「合わない点」を文字で出すこと(例:「徒歩7分(希望10分以内)」「築28年(希望20年以内)」) P1
FR-234 照合の結果から、そのまま提案書の作成(FR-241)へ進めること P1

6.9 提案・内見

ID 要件 優先
FR-241 顧客に対して最大6件の物件を選び、並び替えとひとことコメントを付けて、提案書のPDFを作れること。1物件1ページ(代表写真・間取り・賃料または価格・所在地・交通・主要な設備・コメント)+ 表紙(顧客名・担当・会社情報) P1
FR-242 提案と同時に、送る文面(テンプレート + 物件の一覧)を生成し、コピーできること。提案した記録が顧客に残ること P1
FR-243 内見の予定は、顧客・物件(複数)・日時・集合場所・担当・鍵の手配(未手配/元付に連絡済み/現地のキーボックス/店で鍵を預かり)を持つこと。鍵が未手配の予定は、前日にタスクを自動生成すること P1
FR-244 内見の予定を日・週のカレンダーで表示し、担当者ごとの列で見られること。.ics をダウンロードできること P1
FR-245 内見の結果として、物件ごとに評価(◎○△×)と良かった点・気になった点を記録できること。気になった点を選ぶと、次の照合の採点に反映できること(例:「日当たり」を気にした → 「南向き」を条件に加える提案) P2
FR-246 同じ日の複数の内見物件を、住所の近い順(同じ町名 → 同じ市区町村 → 駅)に並べて見せること P3

6.10 案件(申込〜契約)

ID 要件 優先
FR-251 案件は、顧客・取引の種類・物件(申込前は空でよい)・担当・段階・手数料見込み・契約までの予定 を持つこと P1
FR-252 段階は取引の種類ごとに持つこと。賃貸:反響/初回連絡/内見調整/内見済み/申込/審査/契約/鍵渡し(成約)/失注。売買(購入):反響/初回連絡/内見調整/内見済み/購入申込/ローン事前審査/契約/決済・引渡し(成約)/失注。規則(書類・予定・物件の状態)は段階の名前ではなく CaseStage.key で判定すること P1
FR-253 案件ボードは賃貸・売買を切り替えて表示し、各列に件数と手数料見込みの合計を出すこと。ドラッグとキーボードの両方で段階を変えられること P1
FR-254 段階が申込の段階(key: 'apply'。賃貸「申込」・売買「購入申込」)に進むと、必要書類のひな形(SC-209)から書類のチェックリストを自動で作ること。全部に受領の印がつくまで「審査へ進める」を非活性にし、足りない書類を示すこと P1
FR-255 契約までの予定(審査の結果予定日・重要事項説明の日時・契約日・鍵渡しまたは決済日)を入れると、それぞれの前日にタスクを自動生成すること P1
FR-256 案件が申込の段階(key: 'apply')に進むと物件を「申込あり」に、契約の段階(key: 'contract')に進むと「成約済み」に変えるかを確認し、同意すると変更すること。失注したときは「募集中」に戻すかを確認すること P1
FR-257 最後の対応から既定7日(設定で変更可)動きのない、申込の段階以降(key が apply〜contract)の案件を「止まっている」として印を付けること P1
FR-258 成約の登録(SC-033)をすると、案件を成約の段階(key: 'handover'。賃貸「鍵渡し(成約)」・売買「決済・引渡し(成約)」)へ移すこと。鍵渡し・決済の日が先の場合も、段階は成約にし、日付は契約までの予定に残す。成約の登録時に確定手数料を入れ、失注の登録時に理由(他社で決定/条件が変わった/審査が通らなかった/連絡がとれない/その他)を複数選択 + 自由記述で入れられること P1

6.11 仲介手数料

ID 要件 優先
FR-261 手数料の上限額を src/lib/calc/fee.ts で計算すること。売買(税抜の上限):取引額200万円以下の部分×5%+200万円超400万円以下の部分×4%+400万円超の部分×3%(400万円超は「取引額×3%+6万円」の速算式と一致すること)。賃貸:賃料の1か月分(借主・貸主の合計の上限。居住用の建物は、依頼者の承諾がなければ借主・貸主それぞれ0.5か月分が上限)。計算の元の賃料・価格は税別で、管理費・共益費を含めない P1
FR-262 消費税率(既定10%)を設定で持ち、税込の上限額を表示すること P1
FR-263 案件ごとに「実際に請求する額」を上限額以下で入れられ、上限を超える入力はできないこと P1
FR-264 計算の画面・設定の画面に「上限額の計算は宅地建物取引業法の報酬の規定にもとづく目安です。特例(低廉な空家等 など)や最新の告示は、実務で確認してください」と表示すること P1

計算のテストを必ず書く。 売買 1,000万円 → 税抜36万円(1,000万×3%+6万)、300万円 → 税抜14万円(300万×4%+2万)、150万円 → 税抜7.5万円(150万×5%)。境界(200万円ちょうど・400万円ちょうど)も含める。

6.12 分析

ID 要件 優先
FR-271 ダッシュボードに、今日の内見・未対応の反響(件数と最も古い経過時間)・今月の初回連絡の平均時間(分)・止まっている追客・今週の契約までの予定・今月の申込件数/契約件数/手数料見込み を表示すること。ロールで範囲が変わること P1
FR-272 反響の分析で、媒体別の 反響→内見→申込→契約 の件数と率、初回連絡の速さ(30分以内/2時間以内/当日中/翌日以降)別の契約率 を表示すること P2
FR-273 担当者別の実績で、反響・内見・申込・契約・手数料を表示すること。営業ロールでは非表示とすること P2
FR-274 手数料の予実で、月次の目標・実績・見込み(段階ごとの見込み率 × 手数料見込み)・達成率を表示すること P2
FR-275 物件の動きで、問い合わせ数の多い物件と、募集開始からの日数が長い物件を表示すること P3

6.13 分析・設定(共通)

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 を画面では「顧客」、Case を「案件」と表示する)。

共通の型の customerId は Customer.id を、caseId は Case.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 IndustryNotificationType = 'new_match' | 'inquiry_assigned' | 'doc_missing'   // 条件に合う新着物件 / 反響の割当 / 書類の不足

type ActivityType = 'call' | 'mail' | 'sms' | 'visit_store' | 'viewing' | 'proposal' | 'other'
// 電話 / メール / SMS / 来店 / 内見 / 物件提案 / その他

type Store = { id: string; name: string; address: string; phone: string; licenseNo: string }  // 宅建業の免許番号(架空)

type Customer = {
  id: string
  name: string; nameKana: string
  phone: string; email: string
  contactTime: string              // 連絡してよい時間帯
  preferredChannel: 'call' | 'mail' | 'sms' | 'line'
  segment: 'rent' | 'buy' | 'sell' // 賃貸で探している / 購入を検討 / 売却を検討
  ownerId: string                  // 担当営業。スコープ判定の起点
  storeId: string
  wish: Wish
  tagIds: string[]
  note: string
  customFields: Record<string, CustomValue>
  lastContactAt: string | null     // 対応記録時に自動更新
  createdAt: string; updatedAt: string
}

type Wish = {
  dealKind: 'rent' | 'sale'
  stations: string[]; cities: string[]
  priceMin?: number; priceMax: number        // 賃料(月額・管理費込み)または価格(円)
  layouts: Layout[]                          // '1R' | '1K' | '1DK' | '1LDK' | '2K' ...
  areaMin?: number                           // ㎡
  builtWithinYears?: number
  walkMaxMin?: number
  moveBy?: string                            // 時期(年月)
  musts: FeatureKey[]                        // こだわり条件
}

type Inquiry = {
  id: string
  receivedAt: string
  media: string                    // 媒体(ポータルA / ポータルB / 自社ホームページ / 電話 / 来店 / 紹介)
  rawText: string                  // 取り込んだ本文
  customerId: string
  caseId: string
  propertyId?: string              // 問い合わせ物件
  assigneeId?: string
  firstContactAt?: string
  status: 'new' | 'working' | 'done'
}

type Property = {
  id: string
  code: string                     // 物件番号(自動採番)
  name: string
  dealKind: 'rent' | 'sale'
  type: 'mansion' | 'apartment' | 'house' | 'land' | 'office'
  city: string; addressRest: string
  access: { line: string; station: string; walkMin: number }[]
  rent?: number; mgmtFee?: number; deposit?: number; keyMoney?: number   // 賃貸
  price?: number                                                         // 売買
  layout: Layout; area: number; floor?: number; floors?: number
  builtYm: string                  // 築年月
  structure: 'RC' | 'SRC' | 'S' | 'W' | 'other'
  features: FeatureKey[]
  availableFrom: string            // 入居可能時期
  listingAgent: string             // 元付の業者(架空)
  photos: { src: string; caption: string; isCover: boolean }[]
  status: 'open' | 'applied' | 'closed' | 'ended'   // 募集中 / 申込あり / 成約済み / 募集終了
  listedAt: string
  createdAt: string; updatedAt: string
}

type CaseStage = {
  id: string; dealKind: 'rent' | 'sale'; name: string; sortOrder: number; expectRate: number
  type: 'open' | 'won' | 'lost'
  key?: 'inquiry' | 'contact' | 'arrange' | 'viewed' | 'apply' | 'screening' | 'contract' | 'handover' | 'lost'  // 段階の役割。名前を変えても判定が変わらないよう、規則はこの key で書く。管理者が追加した段階は key を持たず、規則の対象にならない
}

type Case = {
  id: string
  customerId: string
  dealKind: 'rent' | 'sale'
  propertyId?: string
  ownerId: string
  stageId: string
  expectedFee: number              // 手数料見込み(税抜)
  confirmedFee?: number
  schedule: { screeningDue?: string; explanationAt?: string; contractAt?: string; handoverAt?: string }
  documents: { id: string; name: string; receivedAt?: string }[]
  firstContactMinutes?: number     // 受信から初回連絡までの分数(FR-207)
  closeReason?: { codes: string[]; note: string }
  closedAt?: string
  lastActivityAt: string | null
  customFields: Record<string, CustomValue>
  createdAt: string; updatedAt: string
}

type Viewing = {
  id: string
  customerId: string; caseId: string; ownerId: string
  startsAt: string; endsAt: string
  meetingPlace: string
  items: { propertyId: string; key: 'none' | 'agent' | 'keybox' | 'store'; result?: { grade: 'A' | 'B' | 'C' | 'D'; good: string[]; concern: string[]; note: string } }[]
  status: 'planned' | 'done' | 'canceled'
}

type Proposal = { id: string; customerId: string; ownerId: string; propertyIds: string[]; comments: Record<string, string>; message: string; reaction?: Record<string, 'want' | 'pass'>; createdAt: string }

type DocumentTemplate = { id: string; dealKind: 'rent' | 'sale'; stageName: string; items: string[] }

// 派生値。ストアには保存せず算出する
type CustomerView = Customer & { daysSinceContact: number | null; isStalled: boolean; matchNewCount: number }
type MatchResult = { propertyId: string; customerId: string; score: number; good: string[]; bad: string[]; blocked: boolean }
type FeeCalc = { dealKind: 'rent' | 'sale'; base: number; capExTax: number; capInTax: number }

画像

  • シードの物件写真は public/photos/properties/ に置き、localStorage には入れない(パスだけを持つ)
  • 写真は外観・室内・水回り・眺望など1物件4〜8枚。建物の外観・室内の写真を、実在の物件と誤解されない形で使う(住所と組み合わせない。写真のクレジットは public/photos/CREDITS.json に記録し、アプリの「写真について」に一覧を出す)
  • 写真は scripts/fetch-photos.mjs で1回だけ取得してリポジトリに含める。取得元は商用利用できる写真サービス(例 Unsplash)とし、透かし入り・有料の写真は除外する。Node の fetch が弾かれる場合は curl で取得する
  • 画面では loading="lazy" と、一覧用の縮小版(長辺480px)を使う

シードデータ(src/lib/seed/)

ファイル 内容 件数
masters.ts 路線・駅(架空の2路線 + 実在の地名に寄せない駅名)、市区町村、設備、媒体、失注理由、タグ —
users.ts 営業8・店長2・管理者1、店舗2(駅前店・郊外店) 11名
stages.ts 賃貸9段階・売買9段階(FR-252。成約・失注を含む)と見込み率 18件
properties.ts 物件(賃貸120・売買40)。状態:募集中90/申込あり18/成約済み24/募集終了28(成約から30日を過ぎた物件は募集終了にしてある。成約60件のうち、他社が元付の物件への客付けは自社の物件一覧に残らない) 160件
customers.ts 顧客(賃貸160・購入45・売却15)。希望条件つき 220名
inquiries.ts 反響(過去90日。媒体の偏りあり。未対応を必ず5〜8件含め、うち2件は2時間超) 260件
cases.ts 案件(進行中140・成約60・失注40)。止まっている申込・書類の不足を意図的に含める 240件
viewings.ts 内見(過去60日+今後14日。今日の内見を3〜5件) 180件
proposals.ts 物件提案 90件
activities.ts 対応履歴(過去6か月。繁忙期の1〜3月に偏らせる) 1,400件
tasks.ts タスク(期限超過8/今日7/今週14/今後20/完了50) 99件
templates.ts 文面テンプレート(初回の連絡・物件提案・内見のお礼・申込のご案内・追客 など8種)、反響メールの見本(媒体3種 × 3通) —
documents.ts 必要書類のひな形(賃貸・売買 × 段階) —
targets.ts 月次の手数料目標(全社/店舗/個人、過去6か月+今月) —

不動産らしさのためのシードの注意

  • 賃料・価格は、間取り・面積・駅からの徒歩・築年と整合させる(駅から近く新しいほど高い)。ワンルームが月30万円のような不自然な値を作らない
  • 反響のメッセージ、内見の感想、対応の内容は、実際の現場の言い回しに寄せて書き分ける(「日当たりが思ったより良かった」「2人入居の可否を管理会社に確認」「審査書類の源泉徴収票が未着」など)
  • 反響の媒体ごとに、本文の形式(項目名の書き方・並び)を変える。読み取り(FR-202)の見せ場になる
  • 繁忙期(1〜3月)に反響と契約が増える季節の波を入れる

シード作成のルール(品質を左右する)

  • 実在の企業名・人名・住所の番地を使わない。 架空のものを使う。地名は市区町村までにとどめ、番地以降は架空にする
  • 文章をテンプレの繰り返しにしない。 顧客・段階・季節に応じて書き分ける。同じ言い回しが続くと一瞬で作り物だと分かる
  • 金額・件数の分布に偏りを持たせる(小さいものが多く、大きいものが少ない)。均等分布は不自然
  • 日付は現在日時からの相対で生成する。固定日付を埋め込まない(期限・締め日のように暦で決まるものは、今日から見た次回・前回を計算して入れる)
  • 対応の頻度に濃淡をつける。頻繁にやり取りしている顧客と、しばらく放置の顧客が混在すること
  • 期限超過・放置・目標未達を意図的に配置する。 全部が順調だと、ダッシュボードのアラートが動いて見えない
  • シードの生成は乱数の種(seed)を固定し、毎回同じデータになるようにする

ストアとリポジトリ

src/lib/
├── types/          # 上記の型定義
├── seed/           # シードデータ
├── store/
│   ├── session.ts  # 現在のロール、操作中のユーザー
│   ├── data.ts     # 業種のデータ(customers / inquiries / properties / cases / viewings / proposals / 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. デザイン要件

アートディレクション

「明るい窓口」

SUMIKA は、店のカウンターと内見の現場の両方で使われる。お客様に画面を見せながら物件を提案することもある。したがって業務システムの密度と、お客様に見せても恥ずかしくない明るさの両方が要る。

  • 物件の写真が主役。 物件の一覧・詳細・提案書では写真を大きく、角を揃えて並べる。写真の上に文字を載せない(写真を暗くして文字を載せることはしない)
  • 一覧は密に、提案は広く。 反響・顧客・案件の一覧は情報を詰める。物件提案と提案書は余白を取り、1物件ずつ見せる
  • 時間の色。 反響の経過時間・止まっている追客・書類の不足だけが色を持つ。通常の状態はほぼ無彩色
  • 金額は大きく、桁を揃える。 賃料・価格・手数料は Inter の等幅数字で、単位(万円・円)は小さく添える

デザイントークン

src/styles/tokens.css に CSS 変数で定義し、Tailwind の theme から参照する。直書きの色指定を禁止する。 色の値はチャンネル値(例 35 64 122)で定義し、rgb(var(--brand-700) / <alpha-value>) で参照する(16進数で定義すると bg-brand/60 のような透明度指定が無言で効かなくなるため)。

:root {
  --ink-900: 22 27 30;       /* 見出し・本文・数値 #161B1E */
  --ink-600: 80 88 94;       /* 補助テキスト #50585E */
  --ink-400: 134 141 146;    /* ラベル・非活性 #868D92 */
  --brand-700: 18 94 84;     /* 主要な操作・選択状態(深い青緑) #125E54 */
  --brand-500: 30 122 109;   /* ホバー #1E7A6D */
  --brand-50: 233 244 241;   /* 選択行・アクティブなビュー #E9F4F1 */
  --surface: 248 247 244;    /* ページ背景(温かい白) #F8F7F4 */
  --card: 255 255 255;
  --border: 229 227 222;     /* #E5E3DE */
  --border-strong: 203 200 193;

  /* シグナル:これ以外の色を画面に持ち込まない */
  --won: 36 128 92;          /* 成約・達成 */
  --lost: 134 141 146;       /* 失注(無彩色) */
  --alert: 194 69 59;        /* 2時間超の未対応・期限超過・書類の不足で進めない */
  --warn: 184 116 28;        /* 30分超の未対応・止まっている追客 */
}
  • 賃貸と売買は色で分けない。ボードの切替とラベル(「賃貸」「売買」)で分ける
  • 物件の募集状態は文字のバッジで示す(募集中=ブランド色の枠、申込あり=--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/properties/     # 物件写真(シード用)と CREDITS.json
│   └── fonts/                 # PDF用の日本語フォント
├── scripts/fetch-photos.mjs   # 写真の取得(1回だけ)
└── src/
    ├── main.tsx  app.tsx      # ルーター・アプリシェル(サイドバー・ヘッダー・デモ切替バー・下部タブ)
    ├── routes/
    │   ├── dashboard.tsx                 # SC-001
    │   ├── inquiries/                    # SC-010, 011
    │   ├── customers/                    # SC-020〜023
    │   ├── cases/                        # SC-030〜033
    │   ├── properties/                   # SC-040〜042
    │   ├── match.tsx                     # SC-043
    │   ├── proposals/                    # SC-050〜052
    │   ├── viewings/                     # SC-060〜062
    │   ├── tasks.tsx  activities.tsx     # SC-070, 071
    │   ├── reports/                      # SC-100〜104
    │   ├── settings/                     # SC-200〜211
    │   └── dev/components.tsx            # コンポーネントカタログ(公開版では出さない)
    ├── components/
    │   ├── ui/                # Radix ベースのプリミティブ
    │   ├── table/             # DataTable, ColumnPicker, FilterBar, BulkActionBar, ViewSidebar
    │   ├── domain/            # InquiryRow, ElapsedBadge, PropertyCard, PhotoGallery, MatchScore, ViewingCalendar, DocChecklist, StageBar, ActivityTimeline, TaskRow, MetricCard
    │   ├── demo/              # RoleSwitcher, ResetButton, GuideTour
    │   └── layout/
    ├── lib/
    │   ├── types/  seed/  store/  repo/   # 7章参照
    │   ├── query/             # 絞り込み・ソート・ビューの適用
    │   ├── calc/              # match.ts(照合), fee.ts(手数料), elapsed.ts(経過時間・止まり判定), forecast.ts(見込み)
    │   ├── parse/inquiry.ts   # 反響メールの読み取り(FR-202, 203)
    │   ├── csv/               # インポート/エクスポート
    │   ├── pdf/               # 提案書テンプレート
    │   ├── i18n/terms.ts      # 業種の言葉
    │   ├── validation/        # Zod スキーマ
    │   └── utils/
    ├── styles/tokens.css
    └── e2e/                   # Playwright

スマホの下部タブ:ホーム/反響/顧客/物件/内見

コーディング規約

  • 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(cases): 放置の検出を実装 (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-S1 物件一覧(写真カード)で160件を表示したとき、スクロールがもたつかないこと(縮小版の写真と遅延読み込み) —
NFR-S2 反響の読み取り(FR-202)は、貼り付けから結果表示まで 300ms 以下 —

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

将来このデモを実際の業務で使う形にする場合、以下が追加で必要になる。お客様への提案の場で聞かれた際に説明できるよう、記録として残す。

  • データの見える範囲は、サーバー側(データベースの権限設定)で守る必要がある。 本デモの src/lib/repo/_scope.ts がその置き換え地点であり、構造上そのまま差し替えられる
  • ログイン、メンバーの招待と停止、毎日のバックアップ、止まったときの通知
  • 顧客の情報は個人情報保護法の対象。利用目的の明示、安全管理措置、委託先の管理、開示・削除請求への対応が必要になる
  • CSVの書き出しは情報の持ち出し経路になるため、実運用では権限の制御と操作ログが必須
  • 宅地建物取引業法に関わる運用。 重要事項説明は宅地建物取引士が行う。成約済みの物件を広告に出し続けることは禁止されている(おとり広告)ため、募集状態の管理(FR-224)は本番では広告の掲載停止と連動させる必要がある
  • 本人確認書類・収入を証明する書類を実際に保管する場合は、保管期間・アクセスできる人・削除の手順を決める必要がある
  • 本デモは顧客のデータをサーバーに送信しないため、これらの義務は発生しない。 ただし「デモである」旨は画面上に常時明示する

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/properties/ と CREDITS.json を作る
  • 反響メールの見本(媒体3種 × 3通)を、媒体ごとに形式を変えて作る

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 顧客一覧(上記テーブル基盤を適用。最後の連絡からの日数・止まりの印の列)(FR-211, FR-213)
  • SC-021 顧客詳細(インライン編集、希望条件、タブ構成)(FR-151, FR-212, FR-214)
  • SC-022 顧客の新規作成 + 重複の検出 (FR-152)
  • 対応記録モーダルと、次にやることからのタスク自動生成 (FR-156, FR-157)
  • SC-070 タスク/SC-071 対応履歴 (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 — 反響と案件(4日)

  • SC-010 反響の受信箱(経過時間の印、状態の切替)(FR-201)
  • src/lib/parse/inquiry.ts と SC-011 反響の取り込み(媒体ごとの読み方、確認画面)(FR-202, FR-203)
  • 問い合わせ物件の自動の紐づけ/同じお客様の検出 (FR-204, FR-205)
  • 担当の割当(手動・順番)と通知 (FR-206)
  • 受信箱からの初回連絡の記録と分数の保存 (FR-207)
  • SC-030 案件ボード(賃貸・売買の切替、列の件数と手数料見込み、ドラッグとキーボード)(FR-252, FR-253)
  • SC-032 案件詳細(段階バー、契約までの予定、必要書類のチェック)(FR-251, FR-254, FR-255)
  • 止まっている案件の検出 (FR-257)
  • SC-033 成約・失注の登録 (FR-258)
  • src/lib/calc/fee.ts とテスト(6.11 の例と境界)(FR-261〜264)
  • SC-001 ダッシュボード(ロールで範囲が変わる)(FR-271)

Phase 2 完了チェック

  • フローAの前半(取り込み → 割当 → 初回連絡)が完走する
  • 4章「ロールを跨ぐ体験」の1・2が動作する
  • 手数料の計算テストが全部通る

Phase 3 — 物件・照合・提案・内見(5日)

  • SC-040 物件一覧(写真カード/表、絞り込み)(FR-221, FR-222)
  • SC-041 物件詳細(写真ギャラリー、問い合わせ数、合う顧客)(FR-225)
  • SC-042 物件の登録・編集(写真の縮小・並び替え)(FR-223)
  • 募集状態と、成約済みを候補から外す処理 (FR-224, FR-256)
  • src/lib/calc/match.ts とテスト、SC-043 条件の照合(内訳・合う点/合わない点)(FR-231〜234)
  • 新着物件の通知 (FR-226)
  • SC-050〜052 物件提案と提案書PDF(表紙+1物件1ページ)、送る文面 (FR-241, FR-242, FR-171〜174)
  • SC-060〜062 内見の予定(カレンダー・担当別)、鍵の手配のタスク、結果の記録 (FR-243〜246)

Phase 3 完了チェック

  • フローA・Bが最後まで完走する
  • 4章「ロールを跨ぐ体験」の3・5が動作する
  • 提案書PDFが実際にダウンロードでき、日本語・写真・レイアウトが崩れていない

Phase 4 — 分析と設定(3日)

  • SC-100 反響の分析(媒体別の歩留まり、初回連絡の速さ別の契約率)(FR-272)
  • SC-101 担当者別の実績(営業ロールでは非表示)(FR-273)
  • SC-102 手数料の予実 (FR-274)/SC-103 物件の動き (FR-275)/SC-104 失注の分析
  • 期間の指定 (FR-901)
  • SC-201〜207 共通の設定(カスタム項目・段階・メンバー・タグ・文面・会社情報・操作ログ)(FR-902〜907)
  • SC-208 反響の取り込みの読み方(試しに読む)/SC-209 必要書類のひな形/SC-210 手数料の計算/SC-211 店舗

Phase 4 完了チェック

  • フローC・Dが完走する
  • 4章「ロールを跨ぐ体験」の4が動作する(ひな形の変更が案件詳細に反映)

Phase 5 — 仕上げ(3日)

5-1. 体験の総点検

  • 4章「ロールを跨ぐ体験」をすべて手動で確認する
  • 全40画面を開き、空の画面が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(例 /customers/c-001)が 404 にならないことを確認する

合計 約22営業日(約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. 全40画面のいずれにも空の状態がなく、不動産仲介らしいリアルなデータが表示されていること
  9. リロード後も操作結果が保持され、「デモをリセット」で初期状態に戻ること
  10. axe-core で Critical / Serious の指摘が0件であること
  11. Lighthouse の基準値を満たすこと
  12. データアクセスがすべて src/lib/repo/ を経由しており、コンポーネントが Zustand ストアを直接参照していないこと
  13. 反響の取り込みで、見本の反響メール(媒体3種 × 3通)がすべて正しく読み取れること
  14. 初回連絡までの分数が記録され、ダッシュボードと反響の分析に反映されること
  15. 成約済み・募集終了の物件が、照合と提案の候補に一度も出てこないこと
  16. 仲介手数料の計算が、6.11 の例と境界の値で正しいこと
  17. スマホ(375px)で、反響の受信箱・内見の予定・内見の結果の記録・物件の写真が快適に使えること

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

  1. 仕様がこの文書にない場合は、実装せずに質問する。 推測で作らない
  2. キーボード操作と「空の画面を作らない」は削減対象外。 速度を出すために削らない
  3. スコープ外(3章 Won't have)は、思いついても実装しない。特にワークフローのビルダーと帳票の自由レイアウト編集
  4. 「デモだから」を理由に品質を落とす判断はしない
  5. コンポーネントからストアを直接触りたくなったら、それはリポジトリ層に足りないメソッドがあるということ
  6. 迷ったら不動産仲介の人の1日を思い浮かべる。 その人が毎朝最初に開く画面で、最初に知りたい数字は何か。それが画面のいちばん上にあるか
  7. 物件の写真を暗くしたり、写真の上に文字を重ねたりしない。 物件の魅力が伝わらなくなる
  8. 法令に関わる計算・表示(仲介手数料・重要事項説明)は、この文書に書いた範囲から広げない。広げたくなったら質問する

FROM DEMO TO PRODUCTION

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

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

  1. 1データの保存

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

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

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

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

本番運用をお考えの方へ

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

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

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

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

FREE CONSULTATION

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

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

日程を決めて話す

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

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

まずは問い合わせる

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