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

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

---

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

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

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

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

---

## 目次

1. [プロジェクト概要](#1-プロジェクト概要)
2. [アーキテクチャ方針 — データベースを持たない](#2-アーキテクチャ方針--データベースを持たない)
3. [スコープ定義](#3-スコープ定義)
4. [ロールとデモ切替](#4-ロールとデモ切替)
5. [画面一覧とユーザーフロー](#5-画面一覧とユーザーフロー)
6. [機能要件](#6-機能要件)
7. [データ設計](#7-データ設計)
8. [デザイン要件](#8-デザイン要件)
9. [技術要件・ディレクトリ構成](#9-技術要件ディレクトリ構成)
10. [非機能要件](#10-非機能要件)
11. [実装タスク](#11-実装タスク)
12. [受入基準](#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` で呼ぶ**。本番化する際は、リポジトリの実装だけをデータベースへの問い合わせに差し替えれば、画面は一行も変更せずに済む。

```ts
// 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'` も同じ対応とする。

### 共通の型

```ts
// ---- 組織・ユーザー ----
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 }
```

### 不動産仲介の型

```ts
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` のような透明度指定が無言で効かなくなるため）。

```css
: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. 法令に関わる計算・表示（仲介手数料・重要事項説明）は、この文書に書いた範囲から広げない。広げたくなったら質問する


---

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

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

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

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

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

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