KOMON — 要件定義書 兼 Claude Code 実装指示書
版数 1.0(DBレス構成)/ 作成日 2026-09-30 / 発行 ソウゾウ合同会社 用途 業種特化アプリの実演デモ / 士業事務所向け 顧問先・期限管理編
このドキュメントの使い方(Claude Code へ)
これ1枚が、規約・仕様・タスクのすべて。リポジトリ直下に CLAUDE.md として置き、毎回読み込むこと。
- 実装は「11. 実装タスク」の順に進める。フェーズを飛ばさない。
- 各タスクの括弧内は要件ID。着手前に該当章を読むこと。
- 仕様がここに書かれていない場合は、推測で実装せず質問する。
- スコープ外(3章 Won't have)は、思いついても実装しない。
- 「デモだから」を理由に品質を落とす判断はしない。
- 士業事務所の言葉で書く。 画面の文言・項目名・並び順・帳票は、この業種の人が毎日使っている言葉と順番に合わせる。汎用の顧客管理の言葉(「リード」「商談」「アカウント」など)に置き換えない。
このアプリが「業種特化」であることの意味 汎用の顧客管理は、無料〜月数千円のサービスがすでに多くある。KOMON がそれらと並べて選ばれる理由は、開いた瞬間に「これはうちの仕事のために作られている」と分かることだけである。 項目・言葉・流れ・帳票・ダッシュボードの数字が士業事務所のものになっていない画面は、1つでもあれば失敗とみなす。
目次
- プロジェクト概要
- アーキテクチャ方針 — データベースを持たない
- スコープ定義
- ロールとデモ切替
- 画面一覧とユーザーフロー
- 機能要件
- データ設計
- デザイン要件
- 技術要件・ディレクトリ構成
- 非機能要件
- 実装タスク
- 受入基準
1. プロジェクト概要
背景と目的
税理士・社会保険労務士・行政書士の事務所(職員3〜20名規模)は、数十〜数百の顧問先について、毎月・毎年くり返す期限を、Excelの一覧と担当者の記憶で守っている。決算月は顧問先ごとに違い、源泉所得税の納期の特例、年末調整、算定基礎届、労働保険の年度更新、許認可の更新と、期限の種類も多い。資料が届かないまま期限が近づき、所長の確認が期限の直前に集中する。顧問料に見合う手間で終わっているかも、誰も数字で見ていない。
汎用のタスク管理を入れても、「顧問先ごとの決算月から1年分の期限を作る」ことができないため、結局Excelに戻る。KOMON は、顧問先を登録すると1年分の期限が自動で並び、資料の回収・作業・所長の確認・請求までが1つの流れでつながる事務所のための管理アプリである。
| 目的 | 内容 |
|---|---|
| 業種特化の実装力の証明 | 決算月・納期の特例・届出の時期など、士業の期限のルールを画面の裏で計算し、1年分を自動で並べる |
| 期限を落とさない設計の証明 | 資料が届いていない・確認待ちが溜まっている・期限が近いものを、システム側から知らせる |
| 経営の数字を見せる設計の証明 | 顧問先ごとの工数と報酬から、採算(1時間あたりの報酬)を出す |
| 横展開の資産化 | 共通の土台(ロール・一覧・設定・帳票)に、業種の部分だけを載せる構造にする |
プロダクト定義
| 項目 | 内容 |
|---|---|
| プロダクト名 | KOMON(こもん)※仮称 |
| 一言定義 | 顧問先を登録すれば、1年分の期限が並ぶ。士業事務所のための顧問先・期限管理 |
| 提供形態 | レスポンシブWebアプリ。フロントエンド完結(サーバー側の保存なし) |
| 主戦場 | 事務所のPC(期限の管理・作業・確認・請求)。スマホは所長の確認と外出先での予定確認 |
| 想定利用者 | 税理士・社労士・行政書士の事務所の担当者、マネージャー、所長、事務 |
プロダクトコンセプト
「期限から、逆算する。」
士業の仕事は、すべて期限から逆算して進む。KOMON は期限を入力させるのではなく、顧問先の情報(決算月・契約しているサービス・従業員の有無)から期限を計算して並べる。担当者は毎朝「今週、何の資料がまだ届いていないか」「所長の確認に何日前に回せばよいか」を画面から受け取る。
デモとしての成功条件
- 触った瞬間に「士業事務所の仕事で使える」と分かる — 空の画面が1つもなく、士業事務所らしいリアルなデータが入っている
- 速い — 一覧の絞り込み、状態の変更、対応記録が、待たされずに終わる
- ロールで見え方が変わる — 担当者は自分の担当、マネージャーはチーム全体。権限の設計ができていることを示す
- 業種の言葉でできている — 項目・段階・帳票・ダッシュボードの数字が、士業事務所のものになっている
- リセットできる — 誰が触った後でも、初期状態に戻せる
2. アーキテクチャ方針 — データベースを持たない
基本方針
バックエンドとデータベースを持たない。すべてブラウザ内で完結させる。
| 一般的な構成 | 本プロジェクト |
|---|---|
| PostgreSQL / Supabase | シードデータ(TypeScript)+ ブラウザ内ストア |
| 認証・SSO | デモ用ロール切替(ワンクリック) |
| REST / GraphQL API | ストア上の操作(リポジトリ層) |
| メール送信・SMS | 送信内容のプレビュー表示で再現 |
| PDF生成(サーバー側) | ブラウザ内で生成し、実際にダウンロードできる |
| CSVインポート/エクスポート | 実際に動く。 ブラウザ内で読み込み/書き出しする |
| 画像のアップロード | 写真を扱う業種のみ。ブラウザ内で縮小して IndexedDB に保持する(7章「画像」) |
なぜこの構成にするか
- デモとして最適 — 訪問者は登録もログインもせずに、全機能を即座に触れる
- 顧客データを一切預からない — 入力されたデータはブラウザから出ない。自社のCSVを投入して試すこともできる
- 開発速度 — 認証・権限のサーバー実装・マイグレーションが不要になり、業種の作り込みと操作効率に全時間を投下できる
- 運用コストゼロ — 静的配信のみ
差し替え可能性の担保(重要)
データアクセスは必ず src/lib/repo/ のリポジトリ層を経由すること。 コンポーネントからストアを直接触らない。
[ 画面・コンポーネント ]
↓ 呼ぶのはこの層だけ
[ src/lib/repo/*.ts ] ← 全メソッドを async にしておく
↓
[ src/lib/store/*.ts ] ← Zustand + persist(localStorage)
↓
[ src/lib/seed/*.ts ] ← 初期データ
リポジトリの各メソッドは、中身が同期処理でも async で定義し、await で呼ぶ。本番化する際は、リポジトリの実装だけをデータベースへの問い合わせに差し替えれば、画面は一行も変更せずに済む。
// src/lib/repo/work-items.ts — 中身は同期でも async にする
export async function findWorkItems(q: Query): Promise<Result<WorkItemView[]>> {
await delay('list')
const all = useDataStore.getState().workItems
return { ok: true, data: scopeWorkItems(filterAndSort(all, q)).map(toView) } // 本番化でここが問い合わせになる
}
永続化の範囲
| 対象 | 挙動 |
|---|---|
| シードデータ | 初期投入。以降は編集可能 |
| ユーザーの操作結果(登録・編集・状態変更・対応記録・タスク) | localStorage に保存。リロードしても保持される |
| CSVインポートしたデータ | localStorage に保存される |
| 画像(写真) | 写真を扱う業種のみ。長辺1280pxに縮小しJPEG品質0.8、1枚200KB以下に収めて IndexedDB に保存する(localStorage は5MB程度しかなく、写真を20枚ほどで使い切るため)。レコードには写真のIDだけを持つ |
| リセット | デモ切替バーの「デモをリセット」で localStorage と IndexedDB(写真)を空にし、初期状態へ |
擬似的な非同期を必ず入れること。 リポジトリの各操作に 150〜400ms のディレイを挟み、読み込み中の状態を実際に見せる。ただし一覧の絞り込み・並び替えは 100ms 以下にする(体感速度が価値のため)。
ストアの容量に注意。 localStorage は5MB程度しか使えない。シードの写真はファイル(
public/)を参照させて保存しない。ユーザーが追加した写真だけを IndexedDB に保存し、リセット時は IndexedDB も空にする。
3. スコープ定義
顧問先
| ID | 機能 | 概要 | 優先度 |
|---|---|---|---|
| F-C01 | 顧問先一覧 | テーブル表示、絞り込み、並び替え、列の選択、保存ビュー | Must |
| F-C02 | 顧問先詳細 | 基本情報、契約しているサービス、1年分の期限、資料の回収、報酬・請求、採算、対応履歴 | Must |
| F-C03 | 契約サービス | 月次の顧問・記帳代行・決算申告・給与計算・年末調整・社会保険の手続き・許認可の更新 などを顧問先ごとに持つ | Must |
| F-C04 | 期限の自動生成 | 顧問先を登録・変更すると、契約サービスと業務のひな形から1年分の期限を作る | Must |
| F-C05 | 一括操作 | 担当変更/タグ付与/資料の依頼文をまとめて作成 | Must |
期限・業務
| ID | 機能 | 概要 | 優先度 |
|---|---|---|---|
| F-W01 | 期限ボード | 今月・来月の業務を、状態(未着手/資料待ち/作業中/確認待ち/差し戻し/完了)の列で表示 | Must |
| F-W02 | 期限カレンダー | 月のカレンダーに期限を並べ、1日に集中している日が分かる | Must |
| F-W03 | 業務の詳細 | 必要な資料のチェック、作業のメモ、工数、所長の確認の記録、提出の記録 | Must |
| F-W04 | 土日祝の繰り下げ | 期限が土日祝日にあたる場合、翌営業日にする | Must |
| F-W05 | 逆算の目安 | 「資料の依頼」「所長の確認に回す」の目安日を、期限から逆算して出す | Must |
資料の回収
| ID | 機能 | 概要 | 優先度 |
|---|---|---|---|
| F-D01 | 回収の一覧 | 顧問先 × 必要な資料の表。未回収を先頭に | Must |
| F-D02 | 依頼文の作成 | 必要な資料の一覧を差し込んだ依頼文を作り、コピーする。依頼した記録を残す | Must |
| F-D03 | 催促の自動化 | 依頼の目安日を過ぎても届いていない資料について、催促のタスクを自動で作る | Must |
所長の確認
| ID | 機能 | 概要 | 優先度 |
|---|---|---|---|
| F-R01 | 確認待ちの一覧 | 所長(またはマネージャー)が確認する業務を、期限の近い順に並べる | Must |
| F-R02 | 承認・差し戻し | 承認で「完了」に、差し戻しは理由をつけて担当に戻す。通知が届く | Must |
スポット案件
| ID | 機能 | 概要 | 優先度 |
|---|---|---|---|
| F-P01 | 案件ボード | 相談/見積提示/受任/作業中/完了/請求済み の段階で表示 | Should |
| F-P02 | 報酬の見積書 | 相続税の申告・会社の設立・補助金の申請・許認可の申請などの見積書(PDF) | Should |
工数・報酬・請求
| ID | 機能 | 概要 | 優先度 |
|---|---|---|---|
| F-T01 | 工数の記録 | 週の表で、顧問先 × 業務ごとに作業時間を記録する | Must |
| F-B01 | 請求の一括作成 | 今月の顧問料・決算料・スポットの報酬から、請求書をまとめて作る | Must |
| F-B02 | 請求書PDF | インボイス制度(適格請求書)の記載事項を満たした請求書 | Must |
| F-B03 | 入金の確認 | 入金の記録、未入金のアラート | Must |
| F-B04 | 報酬の源泉徴収 | 源泉徴収の対象になる報酬について、源泉徴収税額と差引の請求額を出す | Should |
分析
| ID | 機能 | 概要 | 優先度 |
|---|---|---|---|
| F-A01 | ダッシュボード | 今週の期限、資料が届いていない件数、確認待ち、未入金、担当者ごとの今月の件数 | Must |
| F-A02 | 顧問先別の採算 | 報酬 ÷ 工数 = 1時間あたりの報酬。低い顧問先を並べる | Should |
| F-A03 | 担当者の負荷 | 担当者ごとの今月・来月の期限の件数と工数 | Should |
| F-A04 | 期限の守り具合 | 期限の何日前に完了したか、確認に回すまでの日数 | Should |
共通・基盤
| 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)
| 項目 | 理由 |
|---|---|
| 申告書・届出書の作成、電子申告・電子申請の送信 | 各専用ソフトの領域。KOMON は期限と進み具合の管理に絞る |
| 会計ソフト・給与ソフトとの連携 | CSVの書き出しで代替 |
| 顧問先がログインする画面(資料のアップロード) | 依頼文のコピーと、受領の記録で再現する |
| 通帳・領収書などの資料の画像の保管 | 個人情報・機密の扱いが重いため、デモでは「受け取った」記録とファイル名のみ |
| 利用者識別番号・マイナンバーなどの番号の保管 | 対象外(デモで扱わない) |
| 会計・入金の消し込みの自動化 | 入金の手動の記録のみ |
| データベース・バックエンドAPI | 2章の方針に基づく |
| 本物の認証・SSO | ロール切替で代替 |
| 実際のメール・SMS・LINEの送受信 | 送信内容のプレビューで再現 |
| 外部カレンダー連携(Google / Outlook) | 予定は内部で保持。.ics のダウンロードのみ対応 |
| ワークフローの自由な組み立て(ノーコードのビルダー) | 固定ルールのみ実装 |
| 帳票レイアウトの自由編集 | 決まった帳票のみ。ロゴ・会社情報・備考の差し替えだけ対応 |
| モバイルのネイティブアプリ | レスポンシブWebで対応 |
| 複数ブラウザ間でのデータ共有 | 各ブラウザで独立。デモとして問題ない |
スコープリスク: 業務システムは「あれもこれも」が最も起きやすい領域。特にワークフローのビルダーと帳票の自由レイアウト編集は、単体で数週間かかる。要望が出た場合は別フェーズとして見積り、この文書のスコープは変えない。
4. ロールとデモ切替
ロール定義
| ロールID | 名称 | 見えるデータ | 特徴的な権限 |
|---|---|---|---|
staff |
担当者 | 自分が担当する顧問先と、その業務・請求 | 業務の状態の変更、資料の受領の記録、工数の記録、確認に回す |
manager |
マネージャー | 自チーム(税務チーム・労務チーム)の全員の顧問先 | 担当の割当、確認(承認・差し戻し)、チームの負荷の閲覧、共有ビューの作成 |
admin |
所長 | 事務所のすべて | 最終の確認、報酬・請求の確定、採算の閲覧、設定(業務のひな形・期限のルール・祝日・報酬)、メンバー管理 |
見える範囲の起点は「業務」。 業務(
WorkItem)ごとに担当(ownerId)とチーム(業務のひな形のteamから決まるteamId)を持つ。担当者は自分が担当の業務、マネージャーは自チームの業務が見え、顧問先は、見える業務が1件でもあれば見える(税務と労務の両方を契約している顧問先は、両方のチームのマネージャーから見える)。顧問先の主担当(Client.ownerId)は連絡の窓口であり、見える範囲の判定には使わない。
採算(1時間あたりの報酬)は所長だけが見られる。 担当者に顧問先ごとの報酬額を見せない事務所が多いため。担当者の画面では報酬の列を出さない(権限外の列は列の選択にも出さない)。
認証は行わない。ロールはストアの状態として保持し、切替バーから即座に変更できる。
データスコープ(デモの見せ場)
ロールによって同じ画面の表示件数が変わることを、明確に体験させる。
- 担当者(小林・税務チーム)で期限ボードを開く → 自分の今月の業務 34件
- マネージャー(税務チーム)に切替 → 同じ画面がチーム全体の 128件になり、担当者の絞り込みと「確認待ち」が出現する
- 所長に切替 → 事務所全体 212件。採算・請求の確定・設定が出現する
スコープの適用は src/lib/repo/_scope.ts に集約し、全リポジトリメソッドが必ず通す。コンポーネント側でフィルタしない(本番化でデータベース側の権限設定に置き換わる箇所であるため)。
デモ切替バー(F-S01)
画面上部に常時表示する固定バー。
- 現在のロールと操作中の人の名前の表示、3ロールの切替
- 担当者ロール時:3名のメンバーから選択(見え方の違いを体験できる)
- 「デモをリセット」ボタン(確認ダイアログ付き)
- 「これはデモです。入力した内容はこのブラウザの中にだけ保存されます」の明示
デザイン上の扱い: プロダクト本体のUIとは意図的に別扱い(墨色の帯 + 小さめの文字)にし、「アプリの外側にある操作パネル」であることを視覚的に区別する。スマホでは1行に収め、ロール名はアイコン+短い名前にする。
ロールを跨ぐ体験(必ず動くようにする)
- 担当者が業務を「確認待ち」に回す → マネージャーに切替 → 確認待ちの一覧の先頭に現れ、通知が届いている
- マネージャーが理由をつけて差し戻す(「減価償却の計算に固定資産台帳の最新版が必要」)→ 担当者に切替 → 業務が「差し戻し」に移り、理由が通知と業務の詳細に出ている
- 所長が顧問先の決算月を「3月」から「9月」に変える → その顧問先の決算・申告の期限が作り直され、期限ボードとカレンダーの位置が変わる(すでに完了した業務は動かさない)
- 担当者が資料「通帳のコピー(9月分)」の受領を記録する → 資料の回収の一覧から消え、その業務の必要な資料がすべてそろっていれば、確認のダイアログなしで「作業中」に進められる
- 所長が今月の請求を一括作成する → 担当者の顧問先詳細の「報酬・請求」に請求書が現れる(金額は所長のみ表示)
5. 画面一覧とユーザーフロー
全37画面。画面IDはディレクトリ構成と 1:1 で対応させる。
メイン画面
| 画面ID | 画面名 | パス | 主要要素 |
|---|---|---|---|
| SC-001 | ダッシュボード | / |
今週の期限(残り日数)、資料が届いていない件数、確認待ち、差し戻し、未入金、担当者ごとの今月の件数 |
| SC-010 | 期限ボード | /deadlines |
今月/来月/任意の月、状態の列、顧問先 × 業務のカード(残り日数・資料の回収率) |
| SC-011 | 期限の表 | /deadlines?view=table |
ボードと同じデータの表形式 |
| SC-012 | 期限カレンダー | /deadlines/calendar |
月のカレンダー、日ごとの件数、1日に集中している日の印 |
| SC-013 | 業務の詳細 | /deadlines/:id |
期限と逆算の目安、必要な資料、作業メモ、工数、確認の記録、提出の記録 |
| SC-014 | 確認待ち | /reviews |
確認する業務を期限の近い順に。承認・差し戻し |
| SC-020 | 顧問先一覧 | /clients |
テーブル、絞り込み、列の選択、保存ビュー、一括操作、CSV入出力 |
| SC-021 | 顧問先詳細 | /clients/:id |
基本情報、契約サービス、1年分の期限(年表)、資料の回収、報酬・請求、採算、対応履歴 |
| SC-022 | 顧問先の新規作成 | /clients/new |
フォーム。入力に合わせて、作られる1年分の期限を右側にプレビュー |
| SC-023 | CSVインポート | /clients/import |
ファイル選択 → 列の対応付け → プレビュー → 取込結果 |
| SC-030 | 資料の回収 | /documents |
顧問先 × 必要な資料の表、未回収・依頼済み・受領済み |
| SC-031 | 依頼文の作成 | モーダル | 顧問先ごとの必要な資料を差し込んだ依頼文、コピー |
| SC-040 | スポット案件 | /projects |
段階の列(相談〜請求済み)、報酬見込み |
| SC-041 | スポット案件の詳細 | /projects/:id |
段階バー、見積、作業、関連する顧問先 |
| SC-042 | 報酬の見積書 | モーダル | 明細の編集 → プレビュー → PDF |
| SC-050 | 工数の記録 | /timesheet |
週の表(行=顧問先 × 業務、列=曜日)、合計 |
| SC-060 | 請求 | /billing |
今月の請求の一括作成、請求書の一覧(下書き/送付済み/入金済み/未入金) |
| SC-061 | 請求書プレビュー | モーダル | 適格請求書のレイアウト → PDF |
| SC-062 | 入金の記録 | モーダル | 入金日・金額、差額の理由 |
| SC-070 | タスク | /tasks |
期限別(超過/今日/今週/今後)、催促のタスク |
| SC-071 | 対応履歴 | /activities |
全対応のタイムライン。種別・担当・期間で絞り込み |
分析画面
| 画面ID | 画面名 | パス | 主要要素 |
|---|---|---|---|
| SC-100 | 顧問先別の採算 | /reports/profit |
年間報酬・工数・1時間あたりの報酬、低い順(所長のみ) |
| SC-101 | 担当者の負荷 | /reports/load |
担当者 × 月の期限件数・工数の表と棒グラフ |
| SC-102 | 期限の守り具合 | /reports/deadlines |
完了した日の期限からの前後、確認に回すまでの日数、差し戻しの件数 |
| SC-103 | 報酬の推移 | /reports/revenue |
月別の報酬(顧問料・決算料・スポット)、未入金の残高 |
設定画面(所長のみ)
| 画面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/work-rules |
業務の種類ごとの期限の決め方・逆算の目安・担当の既定 |
| SC-209 | 必要な資料のひな形 | /settings/documents |
業務の種類ごとの必要な資料 |
| SC-210 | 祝日 | /settings/holidays |
祝日の一覧(年ごと)、事務所の休業日の追加 |
| SC-211 | 報酬のひな形 | /settings/fees |
顧問料・決算料・年末調整の標準額、源泉徴収の対象にするか |
主要フロー
フローA:新しい顧問先の登録から、1年分の期限が並ぶまで
【ロール:所長】
SC-020 顧問先一覧 ──「顧問先を登録」
↓
SC-022 顧問先の新規作成
法人/個人、決算月「3月」、消費税(原則課税)、従業員あり(給与計算・年末調整を契約)、
源泉所得税の納期の特例「あり」、申告期限の延長「なし」
↓ ★ 右側に、作られる1年分の期限がプレビューされる(2026年9月30日に登録した場合の例)
(毎月の月次の顧問/源泉所得税 2027年1月20日(水)・2027年7月10日(土)→ 土曜のため 7月12日(月)に繰り下げ/
法定調書・給与支払報告書 2027年1月31日(日)→ 2月1日(月)に繰り下げ/決算・申告 2027年5月31日(月)…)
※ 日付と繰り下げは、登録した日と暦によって変わる
「登録する」→ 顧問先と、1年分の業務が作られる
↓
担当に「小林」を割り当てる → 小林に通知
フローB:資料の依頼から、作業・確認・完了まで
【ロール:担当者(小林)】
SC-001 ダッシュボード ──「資料が届いていない 12件」
↓
SC-030 資料の回収 ── 顧問先「(架空)北浜精工」の年末調整の資料が未回収
↓
SC-031 依頼文の作成 ── 扶養控除等申告書・保険料控除申告書・前職の源泉徴収票 を差し込んだ依頼文をコピー
↓ ★ 依頼した記録が残り、依頼の目安日を過ぎても未回収なら催促のタスクが自動で作られる
資料が届くたびに「受領」を記録 → 全部そろうと業務を「作業中」に進められる
↓
SC-050 工数の記録 ── 作業時間を記録
↓
SC-013 業務の詳細 ──「マネージャーの確認に回す」
↓
【ロール切替:マネージャー】
SC-014 確認待ち ── 差し戻し(理由を記入)または承認
↓
【ロール切替:担当者】差し戻しの理由を見て直す → 再び確認に回す → マネージャーの承認で「完了」
↓
(決算・申告のように所長の確認が必要な業務は、マネージャーの承認のあと)
【ロール切替:所長】SC-014 確認待ち(2段目)── 承認で「完了」
フローC:月末の請求
【ロール:所長】
SC-060 請求 ──「今月の請求を作成」
↓ ★ 顧問料(毎月)・決算料(今月が決算の顧問先)・完了したスポット案件の報酬から、請求書の下書きがまとめて作られる
一覧で金額を確認 → 源泉徴収の対象の顧問先には、源泉徴収税額と差引の請求額が自動で入る
↓
SC-061 請求書プレビュー → PDF(適格請求書の記載事項つき)
↓
「送付済み」にする → 入金予定日を過ぎると未入金のアラート
↓
SC-062 入金の記録 → 報酬の推移(SC-103)に反映
フローD:採算の見直し(所長の月次の確認)
【ロール:所長】
SC-100 顧問先別の採算 ── 1時間あたりの報酬の低い順
↓
顧問先「(架空)森野フーズ」:年間報酬 48万円 / 工数 96時間 → 1時間あたり 5,000円(事務所の平均 11,200円)
↓
顧問先詳細 → 工数の内訳(記帳代行が半分)を確認
↓
対応記録に「顧問料の見直しを提案(記帳の範囲)」→ 次にやること → タスク
フローE:Excelからの移行(CSVインポート)
SC-020 顧問先一覧 ──「インポート」→ 列の対応付け(「決算期」→決算月、「顧問料(月)」→顧問料 …)
↓
プレビュー → 取込実行 → 成功 148件 / スキップ 2件(決算月が1〜12以外)
↓ ★ 取り込んだ顧問先の1年分の期限が作られる(作る前に件数を確認するダイアログ)
6. 機能要件
各要件は判定可能な粒度で記述している。テスト項目と 1:1 で対応させる。
6.1 ロール・デモ基盤
| ID | 要件 | 優先 |
|---|---|---|
| FR-001 | 画面上部の固定バーから、3ロール(担当者/マネージャー/所長)をワンクリックで切り替えられること | P1 |
| FR-002 | 担当者ロールでは、3名のメンバーから操作する人を選択できること | P1 |
| FR-003 | 「デモをリセット」で localStorage と IndexedDB(写真)を空にし、確認ダイアログを経て初期状態に戻ること | P1 |
| FR-004 | 操作結果はブラウザをリロードしても保持されること | P1 |
| FR-005 | データスコープは src/lib/repo/_scope.ts に集約し、全リポジトリメソッドが必ず通すこと。コンポーネント側でロールによるフィルタを行わないこと |
P1 |
| FR-006 | 担当者は自分の担当のみ、マネージャーは自チーム、所長は事務所全体のレコードが見えること | P1 |
| FR-007 | 権限外の操作を試みた場合、ボタンを非活性にし、理由をツールチップで示すこと。実行してからエラーを出さないこと | P1 |
| FR-008 | ロール権限外の画面(担当者で /settings)にアクセスした場合、案内画面からロール切替できること。素の404を出さないこと |
P1 |
| FR-009 | 初回訪問時に3ステップのガイドツアーを表示し、「今後表示しない」を選択できること。ツアーを閉じても別の画面へ飛ばさないこと | P2 |
| FR-010 | リポジトリ層の各操作は 150〜400ms の擬似ディレイを持つこと。ただし一覧の絞り込み・並び替えは 100ms 以下とすること | P1 |
6.2 一覧・検索・ビュー(業務システムの中核)
| ID | 要件 | 優先 |
|---|---|---|
| FR-101 | 一覧テーブルは、表示する列をユーザーが選択・並び替えできること。設定は保持されること | P1 |
| FR-102 | 各列でソートでき、複数列でのソート(第1キー・第2キー)に対応すること | P2 |
| FR-103 | 絞り込みは項目ごとの条件指定(等しい/含む/以上/以下/期間/空である)に対応すること | P1 |
| FR-104 | 絞り込み条件はURLのクエリに反映し、リロード・URL共有で同一結果を再現できること | P1 |
| FR-105 | 適用中の絞り込み条件をチップで一覧表示し、個別に解除できること | P1 |
| FR-106 | 絞り込み条件 + 表示列 + 並び順を「ビュー」として名前を付けて保存できること。個人ビューと共有ビュー(マネージャー以上が作成)を区別すること | P1 |
| FR-107 | 保存ビューはサイドバーに一覧表示し、ワンクリックで切り替えられること。件数バッジを表示すること | P1 |
| FR-108 | 行のチェックボックス選択で一括操作(担当変更/タグ付与/状態変更)ができること。全選択・絞り込み結果全件選択に対応すること | P1 |
| FR-109 | 一括操作の実行前に、対象件数と操作内容の確認ダイアログを表示すること | P1 |
| FR-110 | 削除操作は取り消し可能なトースト(5秒間「元に戻す」を表示)とすること | P1 |
| FR-111 | ヘッダーの横断検索から、顧問先・業務・スポット案件・請求を横断検索できること。種別ごとにグループ化して結果を表示すること | P1 |
| FR-112 | ⌘K / Ctrl+K でコマンドパレットを開き、検索・画面遷移・新規作成を実行できること |
P1 |
| FR-113 | 一覧の行数が多い場合も描画がもたつかないこと(仮想スクロールを実装すること) | P2 |
| FR-114 | 一覧の行の高さを「標準(44px)/コンパクト(34px)」で切り替えられること | P2 |
| FR-115 | テーブル上でセルを直接編集できること(インライン編集)。Enterで確定、Escで取消、Tabで次のセルへ移動すること | P2 |
| FR-116 | スマホ幅では、テーブルをカード型のリストに切り替えること。 横スクロールのテーブルをスマホで見せない | P1 |
6.3 顧問先・CSV・共通部品
| ID | 要件 | 優先 |
|---|---|---|
| FR-151 | 顧問先の詳細で、基本情報の各項目をクリックしてその場で編集できること(インライン編集) | P1 |
| FR-152 | 顧問先の新規作成時、氏名(または会社名)・電話番号の入力中に既存レコードとの類似を検出し、重複候補を警告表示すること | P2 |
| FR-153 | CSVインポートで、列の対応付け(自動推測 + 手動修正)、プレビュー、エラー行の理由表示、部分取込 ができること | P1 |
| FR-154 | インポート結果を「成功N件/スキップN件(理由別内訳)」で表示し、取り込んだレコードに実行日時のタグを自動付与すること | P1 |
| FR-155 | 現在の絞り込み条件・表示列のままCSVを書き出せ、実際にファイルがダウンロードされること。Excelで文字化けしないよう BOM付きUTF-8 で出力すること | P1 |
| FR-156 | 対応記録(電話・メール・打ち合わせ・訪問・資料の依頼・提出など)を、一覧画面や詳細画面から遷移せずにモーダルで記録できること | P1 |
| FR-157 | 対応記録時に「次にやること」と期限を入力すると、タスクが自動生成され、関連レコードに紐づくこと | P1 |
| FR-158 | タスクを「期限超過/今日/今週/今後/完了」でグルーピング表示し、チェックのワンクリックで完了・取り消しできること | P1 |
| FR-159 | マネージャーは他メンバーにタスクを割り当てられること。割当時、対象者の通知に配信されること | P1 |
| FR-160 | 文面テンプレートを選択し、差し込み変数({{顧問先名}} {{自分の氏名}} など)を置換して本文を生成できること。「コピー」で本文をクリップボードに入れ、同時に対応記録に残すこと |
P2 |
6.4 帳票(PDF)共通
| ID | 要件 | 優先 |
|---|---|---|
| FR-171 | 帳票はプレビューを印刷レイアウトで表示し、実際にPDFをダウンロードできること | P1 |
| FR-172 | 帳票には会社情報(会社名・住所・電話・ロゴ・印影)を差し込み、設定画面(SC-206)の変更が即座に反映されること | P1 |
| FR-173 | 帳票の日本語が文字化け・欠けしないこと(日本語フォントを埋め込む。9章) | P1 |
| FR-174 | 金額は3桁区切り、日付は和暦ではなく西暦(2026年10月1日)で表記すること。和暦が慣習の帳票だけ例外として明記する |
P1 |
6.5 顧問先と契約サービス
| ID | 要件 | 優先 |
|---|---|---|
| FR-201 | 顧問先に、名称・フリガナ・区分(法人/個人)・業種・代表者・所在地(市区町村 + 以降)・電話・メール・連絡方法の希望・決算月(法人)・消費税の区分(免税/簡易課税/原則課税)・従業員の人数・源泉所得税の納期の特例の有無・申告期限の延長の有無・担当・チーム・顧問開始日・タグ・メモ を登録できること | P1 |
| FR-202 | 顧問先ごとに、契約サービス(月次の顧問/記帳代行/決算・申告/給与計算/年末調整/社会保険の手続き/労働保険の年度更新/算定基礎届/許認可の更新 など、ひな形 SC-208 にあるもの)と、その報酬(月額または年額)を持てること | P1 |
| FR-203 | 顧問先の新規作成画面で、入力に合わせて作られる1年分の期限を右側にプレビューすること(スマホでは下に) | P1 |
| FR-204 | 顧問先詳細に、契約サービス・1年分の期限(月ごとの年表)・資料の回収・報酬と請求・採算(所長のみ)・対応履歴 をタブで表示すること | P1 |
6.6 期限の自動生成(KOMON の中核)
| ID | 要件 | 優先 |
|---|---|---|
| FR-211 | 期限は src/lib/calc/deadline.ts の純粋な関数で計算すること。入力=顧問先・業務のひな形・基準日、出力=期限日(繰り下げ後)と逆算の目安日。画面やストアに期限の計算を書かない |
P1 |
| FR-212 | 業務のひな形は、期限の決め方を次の型で持つこと:毎月の決まった日(例 翌月10日)/毎年の決まった日(例 1月31日)/決算月から数えた月の末日(例 決算月の2か月後の末日)/期間の最終日(例 6月1日〜7月10日の最終日)/登録した日から数えた日(許認可の更新 など) | P1 |
| FR-213 | 期限が土曜・日曜・祝日・年末年始(12月29日〜1月3日の休業日の設定)にあたる場合、翌営業日に繰り下げること。繰り下げたときは画面に「(日曜のため繰り下げ)」と理由を出すこと | P1 |
| FR-214 | 祝日は設定(SC-210)で年ごとに持ち、シードには内閣府が公表している「国民の祝日」の2026年・2027年分を入れること | P1 |
| FR-215 | 法人税等の申告期限の延長が「あり」の顧問先は決算・申告の期限を、消費税の申告期限の延長が「あり」の顧問先は消費税の申告の期限を、それぞれ1か月後ろにすること(別々の届出のため、別々に判定する) | P1 |
| FR-216 | 源泉所得税は、納期の特例が「なし」なら毎月(翌月10日)、「あり」なら年2回(1〜6月分は7月10日、7〜12月分は翌年1月20日)の業務を作ること | P1 |
| FR-217 | 顧問先の決算月・契約サービス・特例の有無を変えたとき、未完了の業務だけを作り直し、完了した業務は動かさないこと。作り直す前に、増える・減る・動く件数を確認するダイアログを出すこと | P1 |
| FR-218 | 各業務に逆算の目安日(資料の依頼:期限の30日前、確認に回す:期限の7日前 を既定。ひな形で変更可)を持ち、目安日を過ぎて進んでいない業務に --warn の印を付けること |
P1 |
| FR-219 | 期限の計算の画面と設定の画面に「期限は制度にもとづく目安です。法改正・個別の事情(中間申告・届出の有無など)は、各自で確認してください」と表示すること | P1 |
期限の計算のテストを必ず書く(Vitest)。 最低限、次を含める。
- 3月決算の法人 → 決算・申告の期限は5月31日。2026年5月31日は日曜なので 2026年6月1日(月)
- 同じ法人で申告期限の延長「あり」→ 6月30日
- 源泉所得税の納期の特例「あり」→ 2026年7月10日(金)と 2027年1月20日(水)
- 給与支払報告書・法定調書合計表 → 1月31日。2027年1月31日は日曜なので 2027年2月1日(月)
- 個人の所得税の確定申告 → 2027年3月15日(月)
- 12月29日〜1月3日に期限が来る設定のひな形 → 1月4日以降の最初の営業日
6.7 期限ボード・業務
| ID | 要件 | 優先 |
|---|---|---|
| FR-221 | 期限ボードは、月(今月・来月・任意)を選び、状態の列(未着手/資料待ち/作業中/確認待ち/差し戻し/完了)に顧問先 × 業務のカードを並べること。カードには 顧問先名・業務名・期限・残り日数・資料の回収率・担当 を出すこと | P1 |
| FR-222 | 残り日数は Inter の等幅数字で大きく出し、3日以内は --alert、7日以内は --warn の印を付けること(色 + アイコン + 文字) |
P1 |
| FR-223 | ドラッグとキーボードの両方で、カードの状態を変えられること。ただし「完了」には、確認の承認(FR-242。所長の確認が必要な業務は2段目まで)を経ないと移せないこと | P1 |
| FR-224 | 期限カレンダーで、日ごとの件数を出し、1日に5件以上集中している日に印を付けること。日をクリックするとその日の業務の一覧を出すこと | P1 |
| FR-225 | 業務の詳細に、期限と逆算の目安日、必要な資料のチェック、作業メモ、工数の合計、確認の記録(誰がいつ承認・差し戻したか、理由)、提出の記録(提出日・方法)を出すこと | P1 |
6.8 資料の回収
| ID | 要件 | 優先 |
|---|---|---|
| FR-231 | 業務が作られると、必要な資料のひな形(SC-209)から資料の一覧を作ること(例:年末調整 → 扶養控除等申告書・保険料控除申告書・前職の源泉徴収票(中途入社の人) など) | P1 |
| FR-232 | 資料の回収の画面で、顧問先 × 資料の表を出し、状態(未依頼/依頼済み/受領済み)で絞り込めること。未回収を先頭に並べること | P1 |
| FR-233 | 依頼文の作成で、選んだ顧問先ごとに未回収の資料を差し込んだ本文を作り、コピーできること。コピーすると「依頼済み」になり、依頼した記録が対応履歴に残ること | P1 |
| FR-234 | 依頼してから既定7日(ひな形で変更可)経っても受領していない資料があれば、催促のタスクを自動で作ること(Task.source = 'rule') |
P1 |
| FR-235 | 必要な資料がすべて受領済みになるまで、業務を「作業中」に進めるときに確認のダイアログ(「未受領の資料が2件あります。進めますか?」)を出すこと | P2 |
6.9 所長の確認
| ID | 要件 | 優先 |
|---|---|---|
| FR-241 | 担当者は業務を「確認待ち」に回せること。確認は2段とし、1段目はチームのマネージャー、業務のひな形で「所長の確認が必要」なものは、マネージャーの承認のあとに2段目として所長が確認する。回すたび、次に確認する人に通知すること(review_requested) |
P1 |
| FR-242 | 確認待ちの一覧を期限の近い順に並べ、承認・差し戻しをその場でできること。差し戻しは理由の入力を必須とすること | P1 |
| FR-243 | 差し戻された業務は「差し戻し」の列に移り、担当者に理由つきで通知すること。直して再び回したときは、前回の理由と今回のメモを並べて見せること | P1 |
6.10 工数
| ID | 要件 | 優先 |
|---|---|---|
| FR-251 | 工数の記録画面で、週の表(行=顧問先 × 業務、列=月〜日)に15分単位で時間を入れられること。行は「今週の担当業務」から自動で並べ、追加もできること | P1 |
| FR-252 | 業務の詳細からも工数を記録できること。記録は同じデータとして表と詳細に反映されること | P1 |
6.11 報酬・請求・入金
| ID | 要件 | 優先 |
|---|---|---|
| FR-261 | 「今月の請求を作成」で、顧問料(毎月)・決算料(今月が決算の顧問先)・年末調整の報酬(該当月)・完了したスポット案件の報酬から、顧問先ごとの請求書の下書きをまとめて作ること。作成前に件数と合計額を確認させること | P1 |
| FR-262 | 請求書は適格請求書の記載事項を満たすこと:発行する事務所の名称と登録番号(Tから始まる番号。シードは架空)・取引の年月日(または期間)・取引の内容・税率ごとに区分した合計額と適用税率・税率ごとの消費税額(端数処理は請求書1枚につき税率ごとに1回)・受け取る顧問先の名称 | P1 |
| FR-263 | 源泉徴収の対象とする顧問先(設定で指定)には、報酬の額に応じた源泉徴収税額(100万円以下の部分は10.21%、100万円を超える部分は20.42%。1円未満切り捨て)と、差引の請求額を表示すること。元の額は税抜の報酬とする(請求書で消費税を区分して書いているため)。計算は src/lib/calc/withholding.ts に置き、テストを書くこと。設定の画面に「源泉徴収の対象になるのは、個人の事務所が法人・個人事業者に請求する報酬です。法人の事務所の報酬、士業の種類による違い(行政書士の報酬は原則として対象外 など)は、実務で確認してください」と表示すること |
P2 |
| FR-264 | 請求書の状態(下書き/送付済み/入金済み)を持ち、入金予定日を過ぎた送付済みの請求に「未入金」の印を付けること | P1 |
| FR-265 | 入金の記録で、入金日と金額を入れ、請求額と違う場合は差額の理由(振込手数料・一部入金 など)を入れられること | P1 |
| FR-266 | 報酬の金額(顧問料・請求額・採算)は所長だけが見られること。担当者・マネージャーの画面では金額を「—」で表示し、列の選択にも出さないこと | P1 |
源泉徴収の計算のテスト: 税抜の報酬 55,000円 → 5,615円(55,000 × 10.21% = 5,615.5 → 1円未満切り捨て)。税抜 50,000円(税込 55,000円)→ 5,105円。報酬 1,200,000円 → 1,000,000 × 10.21% + 200,000 × 20.42% = 102,100 + 40,840 = 142,940円。
6.12 スポット案件
| ID | 要件 | 優先 |
|---|---|---|
| FR-276 | スポット案件は、依頼者(顧問先、または顧問先でない人の名前)・件名・担当・段階・見積の明細・報酬見込み・期限 を持つこと | P2 |
| FR-277 | 段階は 相談/見積提示/受任/作業中/完了/請求済み/見送り とし、見送りは失注の種類、請求済みは成約の種類とすること(設定 SC-202 で名称変更・並び替え可) | P2 |
| FR-278 | 案件ボードで段階を列に並べ、各列に件数と報酬見込みの合計を出すこと。ドラッグとキーボードの両方で段階を変えられること | P2 |
| FR-279 | 報酬の見積書(PDF)を作れること。依頼者名・件名・明細・消費税・合計・有効期限・事務所の情報を載せること | P2 |
| FR-280 | 「完了」にした案件の報酬は、その月の請求の一括作成(FR-261)の対象になること | P2 |
6.13 分析
| ID | 要件 | 優先 |
|---|---|---|
| FR-271 | ダッシュボードに、今週の期限(残り日数の短い順)・資料が届いていない件数・確認待ち・差し戻し・未入金(所長のみ)・担当者ごとの今月の件数 を表示すること。ロールで範囲が変わること | P1 |
| FR-272 | 顧問先別の採算で、年間の報酬・年間の工数・1時間あたりの報酬 を出し、低い順に並べること。事務所の平均との差を出すこと(所長のみ) | P2 |
| FR-273 | 担当者の負荷で、担当者 × 月(今月から6か月先まで)の期限の件数と、過去の工数の平均から見込んだ時間を表示すること | P2 |
| FR-274 | 期限の守り具合で、完了した日が期限の何日前だったかの分布、確認に回すまでの日数、差し戻しの件数を表示すること | P2 |
| FR-275 | 報酬の推移で、月別の報酬(顧問料・決算料・スポット)と未入金の残高を表示すること(所長のみ) | P2 |
6.14 分析・設定(共通)
| 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/)
すべての型を先に定義し、これを唯一の真実とする。コード上の型名は英語、画面の言葉は士業事務所の言葉にする(型名 Client を画面では「顧問先」、WorkItem を「業務」と表示する)。
共通の型の
customerIdはClient.idを、caseIdはWorkItem.idを指す。CustomField.targetの'customer''case'も同じ対応とする。
共通の型
// ---- 組織・ユーザー ----
type Role = 'staff' | 'manager' | 'admin' // 担当者 / マネージャー / 所長
type User = {
id: string
name: string
nameKana: string
email: string
avatarUrl: string
role: Role
teamId: string
isActive: boolean
}
type Team = { id: string; name: string; managerId: string }
// ---- 対応記録・タスク ----
type Activity = {
id: string
type: ActivityType // 業種ごとに定義(下の業種の型を参照)
customerId: string
caseId?: string
ownerId: string
occurredAt: string
subject: string
body: string
nextAction?: string // 入力するとタスクが自動生成される(FR-157)
messagePreview?: { channel: 'mail' | 'sms' | 'line'; to: string; body: string } // 文面テンプレートから作った連絡
createdAt: string
}
type Task = {
id: string
title: string
dueDate: string
ownerId: string
assignedById?: string // 他者から割り当てられた場合
customerId?: string
caseId?: string
activityId?: string // 自動生成元
source: 'manual' | 'activity' | 'rule' // rule=業種のルールで自動生成(期限・点検など)
isDone: boolean
doneAt?: string
createdAt: string
}
// ---- カスタム項目・ビュー ----
type CustomField = {
id: string
target: 'customer' | 'case'
label: string
type: 'text' | 'number' | 'date' | 'select' | 'multiselect' | 'checkbox'
options?: string[]
isRequired: boolean
sortOrder: number
}
type CustomValue = string | number | boolean | string[] | null
type SavedView = {
id: string
name: string
target: string // 'customer' | 'case' | 業種ごとの一覧
ownerId: string
isShared: boolean // マネージャー以上のみ true にできる
filters: Filter[]
visibleColumns: string[]
sort: { field: string; dir: 'asc' | 'desc' }[]
createdAt: string
}
type Filter = {
field: string
operator: 'eq' | 'contains' | 'gte' | 'lte' | 'between' | 'in' | 'isEmpty' | 'isNotEmpty'
value: unknown
}
// ---- その他 ----
type Tag = { id: string; name: string; color: string }
type Notification = {
id: string
targetUserId: string
type: 'assigned' | 'task_assigned' | 'due_soon' | 'neglected' | 'returned' | 'done' | IndustryNotificationType // 業種の通知は業種の型で定義する
title: string; body: string; link: string
readAt?: string
createdAt: string
}
type AuditLog = {
id: string
actorId: string
action: 'create' | 'update' | 'delete' | 'merge' | 'import'
targetType: string
targetId: string
changes: { field: string; before: unknown; after: unknown }[]
createdAt: string
}
type Company = { // 帳票に差し込む会社情報(SC-206)
name: string; postalCode: string; address: string; phone: string
logoDataUrl?: string; sealDataUrl?: string
bank?: { bankName: string; branch: string; type: '普通' | '当座'; number: string; holder: string }
invoiceRegNo?: string // 適格請求書発行事業者の登録番号(T + 13桁)。請求書に差し込む
license?: string // 業種の登録・許可・免許の番号(業種の型を参照)
}
type Result<T> = { ok: true; data: T } | { ok: false; error: string }
士業事務所の型
type ActivityType = 'call' | 'mail' | 'meeting' | 'visit' | 'request' | 'submit' | 'other'
// 電話 / メール / 打ち合わせ / 訪問 / 資料の依頼 / 提出 / その他
type Client = {
id: string
name: string; nameKana: string
kind: 'corp' | 'individual' // 法人 / 個人
industry: string
representative: string
city: string; addressRest: string
phone: string; email: string
preferredChannel: 'call' | 'mail' | 'chat'
fiscalMonth?: number // 決算月(1〜12。法人)
consumptionTax: 'exempt' | 'simple' | 'general' // 免税 / 簡易課税 / 原則課税
employees: number
withholdingSpecial: boolean // 源泉所得税の納期の特例
filingExtension: boolean // 法人税等の申告期限の延長の届出
consumptionTaxExtension: boolean // 消費税の申告期限の延長の届出(法人税等とは別の届出)
payday?: number // 毎月の給与支払日(1〜31。31は末日)
agreement36EndsAt?: string // 36協定の有効期間の終わりの日
licenses: { name: string; expiresAt: string }[] // 許認可(建設業許可 など)と有効期間の満了日
isWithholdingTarget: boolean // 報酬の源泉徴収の対象(FR-263)
services: { templateId: string; fee: number; feeUnit: 'month' | 'year' | 'once' }[]
ownerId: string // 主担当(連絡の窓口)
teamId: string
startedAt: string
tagIds: string[]
note: string
customFields: Record<string, CustomValue>
lastContactAt: string | null
createdAt: string; updatedAt: string
}
type WorkTemplate = { // 業務のひな形(SC-208)
id: string
name: string // 例:決算・申告(法人)/ 源泉所得税(納期の特例)/ 年末調整 / 算定基礎届
team: 'tax' | 'labor' | 'admin'
rule:
| { type: 'monthly'; day: number | 'end'; monthOffset: number } // 毎月:翌月10日/翌月末日 など
| { type: 'yearly'; dates: { month: number; day: number; periodLabel: string }[] } // 毎年:1月31日/7月10日と1月20日(年2回)など
| { type: 'fromFiscal'; monthsAfter: number; extendable: 'corp' | 'consumption' | false } // 決算月の2か月後の末日。延長の届出(法人税等/消費税)があれば1か月後ろ
| { type: 'window'; start: { month: number; day: number }; end: { month: number; day: number } } // 期間の最終日
| { type: 'fromClientDay'; field: 'payday'; offsetDays: number } // 毎月:顧問先の給与支払日の5日前 など
| { type: 'fromClientDate'; field: 'agreement36EndsAt' | 'licenses'; daysBefore: number } // 協定の終わりの日・許認可の満了日から数える
applies: (c: Client) => boolean // どの顧問先に作るか(従業員あり・特例あり など)※シリアライズ可能な条件式で持つ
leadDays: { request: number; review: number } // 逆算の目安(既定 30日・7日)
needsDirectorReview: boolean // 所長の確認が必要
documentIds: string[] // 必要な資料のひな形
}
type WorkItem = { // 期限のついた1件の業務
id: string
clientId: string
templateId: string
period: string // 対象の期間(例 2026年9月分 / 2026年3月期)
dueOriginal: string // 繰り下げ前の期限
due: string // 繰り下げ後の期限
shiftReason?: string // 例:日曜のため
ownerId: string // 担当。スコープ判定の起点
teamId: string // ひな形の team から決まる
reviewStep?: 'manager' | 'director' // いま誰の確認待ちか
status: 'todo' | 'waiting' | 'working' | 'review' | 'returned' | 'done'
documents: { id: string; name: string; requestedAt?: string; receivedAt?: string }[]
reviews: { by: string; at: string; result: 'approved' | 'returned'; reason?: string }[]
submittedAt?: string; submitMethod?: string
memo: string
createdAt: string; updatedAt: string
}
type TimeEntry = { id: string; userId: string; clientId: string; workItemId?: string; projectId?: string; date: string; minutes: number; note: string }
type Project = { // スポット案件
id: string
clientId?: string // 顧問先でない依頼者は名前だけ持つ
requesterName?: string
title: string // 例:相続税の申告 / 会社の設立 / 建設業許可の更新
ownerId: string
stageId: string
quoteItems: { name: string; amount: number }[]
expectedFee: number
dueDate?: string
createdAt: string; updatedAt: string
}
type Invoice = {
id: string
number: string // 請求書番号(自動採番)
clientId: string
issuedAt: string
periodLabel: string // 例 2026年9月分
items: { name: string; amount: number; taxRate: 0.1 | 0.08 | 0 }[]
withholding?: number // 源泉徴収税額(FR-263)
dueDate: string
status: 'draft' | 'sent' | 'paid'
payments: { at: string; amount: number; note?: string }[]
}
type ProjectStage = { id: string; name: string; sortOrder: number; type: 'open' | 'won' | 'lost' }
type Holiday = { date: string; name: string }
type IndustryNotificationType = 'review_requested' | 'doc_received' | 'deadline_moved' // 確認待ちに回された / 資料が届いた / 期限が作り直された
// 派生値。ストアには保存せず算出する
type WorkItemView = WorkItem & { daysLeft: number; docRate: number; isBehind: boolean }
type ClientProfit = { clientId: string; annualFee: number; annualMinutes: number; perHour: number }
WorkTemplate.appliesは関数ではなく、{ field: 'employees', op: 'gt', value: 0 }のような条件のデータで持つこと(localStorage に保存でき、設定画面で編集できるようにするため)。
シードデータ(src/lib/seed/)
| ファイル | 内容 | 件数 |
|---|---|---|
masters.ts |
業種、祝日(2026・2027年。内閣府の公表どおり)、年末年始の休業日、対応の種別、タグ | — |
users.ts |
担当者7・マネージャー2・所長1(事務1名を担当者に含める)、チーム2(税務・労務) | 10名 |
work-templates.ts |
業務のひな形(下の一覧)と、それぞれの必要な資料 | 16種 |
clients.ts |
顧問先(法人110・個人40)。決算月の分布は3月決算を多めに、12月・9月・6月が続く | 150件 |
work-items.ts |
顧問先から計算して作る(シードでも deadline.ts を通して作る。手で日付を書かない)。過去6か月分は完了にし、うち数件は期限ぎりぎり・1件は期限後に完了 |
約1,900件 |
time-entries.ts |
工数(過去6か月。顧問先ごとに濃淡。採算の悪い顧問先を意図的に作る) | 約3,200件 |
project-stages.ts |
スポット案件の段階7(FR-277) | 7件 |
projects.ts |
スポット案件(相続税の申告・会社の設立・補助金の申請・許認可の申請 など) | 36件 |
invoices.ts |
請求書(過去6か月。未入金を3〜5件) | 約900件 |
activities.ts |
対応履歴 | 1,100件 |
tasks.ts |
タスク(期限超過6/今日6/今週12/今後18/完了40。催促のタスクを含む) | 82件 |
templates.ts |
文面テンプレート(資料の依頼・催促・提出のご報告・請求書の送付 など8種) | — |
業務のひな形(シードに入れる16種)
所長の確認が必要(needsDirectorReview: true)なのは、決算・申告(法人)・所得税の確定申告(個人)・消費税の申告(法人・個人)・許認可の更新 の5種。ほかはマネージャーの確認で完了する。
| 業務 | 期限の決め方 | 作る条件 |
|---|---|---|
| 月次の顧問(試算表の報告) | 毎月:翌月末日(day: 'end') |
月次の顧問を契約 |
| 記帳代行 | 毎月:翌月20日 | 記帳代行を契約 |
| 源泉所得税(毎月) | 毎月:翌月10日 | 従業員あり・納期の特例なし |
| 源泉所得税(納期の特例) | 毎年:7月10日(1〜6月分)・1月20日(7〜12月分)の年2回(dates に2つ) |
従業員あり・納期の特例あり |
| 決算・申告(法人) | 決算月の2か月後の末日(法人税等の延長ありは3か月後) | 法人・決算・申告を契約 |
| 消費税の申告(法人) | 決算月の2か月後の末日(消費税の延長ありは3か月後) | 法人・消費税が課税 |
| 所得税の確定申告(個人) | 毎年:3月15日 | 個人 |
| 消費税の申告(個人) | 毎年:3月31日 | 個人・消費税が課税 |
| 年末調整 | 毎年:12月の給与支払日(シードは12月25日) | 年末調整を契約 |
| 法定調書合計表・給与支払報告書 | 毎年:1月31日 | 年末調整を契約 |
| 償却資産の申告 | 毎年:1月31日 | 決算・申告を契約 |
| 給与計算 | 毎月:顧問先の給与支払日の5日前(fromClientDay) |
給与計算を契約・給与支払日あり |
| 算定基礎届 | 期間:7月1日〜7月10日 | 社会保険の手続きを契約 |
| 労働保険の年度更新 | 期間:6月1日〜7月10日 | 労働保険の年度更新を契約 |
| 36協定の更新 | 協定の終わりの日(Client.agreement36EndsAt)の30日前 |
社会保険の手続きを契約・協定の日付あり |
| 許認可の更新(建設業許可 など) | 許認可ごとの満了日(Client.licenses)の30日前 |
許認可の更新を契約 |
士業らしさのためのシードの注意
- 顧問先の名前は架空の地域の中小企業らしく(「〇〇精工」「〇〇フーズ」「〇〇設計事務所」「個人:〇〇内科クリニック」など)。実在の会社名にしない
- 資料の名前・作業メモ・差し戻しの理由は、実際の事務所の言い回しで書き分ける(「9月分の通帳コピーが2枚目から欠けている」「減価償却の計算に固定資産台帳の最新版が必要」「扶養の追加について本人に確認中」など)
- 3月決算の申告期限が集中する5月、年末調整〜法定調書の12〜1月、労働保険・算定基礎の6〜7月に、業務と工数の山ができるようにする
シード作成のルール(品質を左右する)
- 実在の企業名・人名・住所の番地を使わない。 架空のものを使う。地名は市区町村までにとどめ、番地以降は架空にする
- 文章をテンプレの繰り返しにしない。 顧問先・段階・季節に応じて書き分ける。同じ言い回しが続くと一瞬で作り物だと分かる
- 金額・件数の分布に偏りを持たせる(小さいものが多く、大きいものが少ない)。均等分布は不自然
- 日付は現在日時からの相対で生成する。固定日付を埋め込まない(期限・締め日のように暦で決まるものは、今日から見た次回・前回を計算して入れる)
- 対応の頻度に濃淡をつける。頻繁にやり取りしている顧問先と、しばらく放置の顧問先が混在すること
- 期限超過・放置・目標未達を意図的に配置する。 全部が順調だと、ダッシュボードのアラートが動いて見えない
- シードの生成は乱数の種(seed)を固定し、毎回同じデータになるようにする
ストアとリポジトリ
src/lib/
├── types/ # 上記の型定義
├── seed/ # シードデータ
├── store/
│ ├── session.ts # 現在のロール、操作中のユーザー
│ ├── data.ts # 業種のデータ(clients / workItems / projects / timeEntries / invoices / 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. デザイン要件
アートディレクション
「几帳面な帳場」
KOMON は、期限と数字を毎日正確に扱う人の道具。華やかさより、整っていること・抜けがないことが一目で分かることを最優先する。
- 期限が主役。 残り日数を大きな等幅数字で左に置き、次に顧問先、業務の順に読ませる
- 表と年表。 顧問先ごとの1年分の期限は、月の列が並ぶ年表で見せる。紙の管理表をそのまま画面にしたような端正さ
- 色は期限のためにある。 通常はほぼ無彩色。7日以内・3日以内・差し戻し・未入金だけが色を持つ
- 金額は所長の画面だけ。 担当者の画面から金額が消えても、表が崩れない設計にする(列が減っても幅が整う)
デザイントークン
src/styles/tokens.css に CSS 変数で定義し、Tailwind の theme から参照する。直書きの色指定を禁止する。 色の値はチャンネル値(例 35 64 122)で定義し、rgb(var(--brand-700) / <alpha-value>) で参照する(16進数で定義すると bg-brand/60 のような透明度指定が無言で効かなくなるため)。
:root {
--ink-900: 24 25 33; /* 見出し・本文・数値 #181921 */
--ink-600: 84 87 102; /* 補助テキスト #545766 */
--ink-400: 138 141 156; /* ラベル・非活性 #8A8D9C */
--brand-700: 64 58 140; /* 主要な操作・選択状態(藍紫) #403A8C */
--brand-500: 88 81 168; /* ホバー #5851A8 */
--brand-50: 238 237 248; /* 選択行・アクティブなビュー #EEEDF8 */
--surface: 247 247 249; /* ページ背景 #F7F7F9 */
--card: 255 255 255;
--border: 226 227 233; /* #E2E3E9 */
--border-strong: 198 200 210;
/* シグナル:これ以外の色を画面に持ち込まない */
--won: 40 124 88; /* 完了・承認・入金済み */
--lost: 138 141 156; /* 不要・対象外(無彩色) */
--alert: 190 58 52; /* 残り3日以内・期限超過・未入金 */
--warn: 176 110 20; /* 残り7日以内・目安日の超過・差し戻し */
}
- 業務の種類(税務・労務・許認可)は色で分けない。小さな文字のラベルで分ける
- 年表の月の列は、決算月だけ太い罫線で示す
配色ルール(共通)
- 通常状態の行に色を持たせない。色がついている行は「対応が必要な行」だけ
- 段階に固有色を割り当てて虹色のバッジを並べない。段階は位置と進捗で表現する
- 色だけで状態を伝えない。必ずアイコン+文字を添える(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 の薄いラッパー。写真を扱う業種のみ |
| @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/fonts/ # PDF用の日本語フォント
└── src/
├── main.tsx app.tsx # ルーター・アプリシェル(サイドバー・ヘッダー・デモ切替バー・下部タブ)
├── routes/
│ ├── dashboard.tsx # SC-001
│ ├── deadlines/ # SC-010〜013
│ ├── reviews.tsx # SC-014
│ ├── clients/ # SC-020〜023
│ ├── documents.tsx # SC-030, 031
│ ├── projects/ # SC-040〜042
│ ├── timesheet.tsx # SC-050
│ ├── billing/ # SC-060〜062
│ ├── tasks.tsx activities.tsx # SC-070, 071
│ ├── reports/ # SC-100〜103
│ ├── settings/ # SC-200〜211
│ └── dev/components.tsx
├── components/
│ ├── ui/ table/ demo/ layout/
│ └── domain/ # DeadlineCard, DaysLeft, YearChart(年表), DocChecklist, ReviewPanel, TimesheetGrid, InvoicePreview, StageBar, ActivityTimeline, TaskRow, MetricCard
├── lib/
│ ├── types/ seed/ store/ repo/ # 7章参照
│ ├── query/
│ ├── calc/ # deadline.ts(期限・繰り下げ・逆算), holiday.ts, withholding.ts(源泉徴収), profit.ts(採算), load.ts(負荷)
│ ├── csv/ pdf/ # 請求書・報酬の見積書
│ ├── i18n/terms.ts
│ ├── validation/ utils/
├── styles/tokens.css
└── e2e/
スマホの下部タブ:ホーム/期限/確認待ち/顧問先/工数
コーディング規約
- TypeScript strict。
any禁止。やむを得ない場合はunknown+ 型ガード - ファイル名は kebab-case、コンポーネントは PascalCase
- 1ファイル300行を超えたら分割を検討する
- コンポーネントから Zustand ストアを直接参照しない。必ず
src/lib/repo/経由 - 絞り込み・計算ロジックは
src/lib/query/とsrc/lib/calc/に置き、コンポーネントに埋め込まない(テスト対象にするため) - 派生値をストアに保存しない。常に算出する
- 業種の言葉は
src/lib/i18n/terms.tsにまとめる(画面に直書きしない。言葉の統一が業種特化の品質を決めるため) - コミットは1タスクごと。メッセージに要件IDを含める
例:
feat(work-items): 放置の検出を実装 (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-K1 | 顧問先150件の1年分の期限(約1,900件)を作り直す処理が 500ms 以下で終わること | — |
| NFR-K2 | 期限の計算(deadline.ts)が、タイムゾーンに左右されないこと(日本時間の日付として扱い、時刻を持たせない) |
— |
本番化するときに必要になること(デモ本体の要件ではない)
将来このデモを実際の業務で使う形にする場合、以下が追加で必要になる。お客様への提案の場で聞かれた際に説明できるよう、記録として残す。
- データの見える範囲は、サーバー側(データベースの権限設定)で守る必要がある。 本デモの
src/lib/repo/_scope.tsがその置き換え地点であり、構造上そのまま差し替えられる - ログイン、メンバーの招待と停止、毎日のバックアップ、止まったときの通知
- 顧問先の情報は個人情報保護法の対象。利用目的の明示、安全管理措置、委託先の管理、開示・削除請求への対応が必要になる
- CSVの書き出しは情報の持ち出し経路になるため、実運用では権限の制御と操作ログが必須
- 税理士法・社会保険労務士法・行政書士法の守秘義務。 顧問先の情報は、事務所の外に出さない設計(アクセスできる人の限定・操作ログ・端末の管理)が本番では必須になる
- 顧問先から資料を受け取る仕組み(アップロード)を本番で作る場合は、保管の期間・暗号化・削除の手順を決める必要がある
- 期限のルールは法改正で変わる。本番では、ひな形の更新を誰がいつ確認するかの運用を決める必要がある
- 本デモは顧問先のデータをサーバーに送信しないため、これらの義務は発生しない。 ただし「デモである」旨は画面上に常時明示する
11. 実装タスク
この順に進める。フェーズを飛ばさない。 完了時は [x] に更新する。
Phase 0 — 基盤とデザインシステム(3日)
0-1. 初期化
- Vite 6 / React 19 / TypeScript strict / React Router 7 / Tailwind v4 で初期化
- ESLint / Prettier(保存時に整形)、
npm run checkで lint + 型チェック + テスト - 9章のディレクトリ構成を作成
-
wrangler.jsoncを置き、静的アセット配信とnot_found_handling: "single-page-application"を設定
0-2. 型とシード
-
src/lib/types/に7章の型定義をすべて実装 -
src/lib/seed/を実装(7章の件数・分布どおり。乱数の種を固定) - 文章を顧問先・段階に応じて書き分ける。テンプレの使い回し禁止
- 日付は現在日時からの相対で生成する
-
src/lib/calc/deadline.tsとholiday.tsをシードより先に実装し、6.6 のテストを通す(シードの業務は、この関数で作るため) - 業務のひな形16種と必要な資料のひな形を作る
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)
- キーボード操作(
↑↓EnterSpace⌘A)(IX-02)/インライン編集 (FR-115, IX-03) - スマホ幅でカード型リストに切り替える (FR-116)
1-2. 保存ビュー
-
ViewSidebar:ビュー一覧、件数バッジ、ワンクリック切替 (FR-107) - ビューの保存・編集・削除。個人/共有の区別(共有はマネージャー以上)(FR-106)
1-3. 顧問先
- SC-020 顧問先一覧(上記テーブル基盤を適用。決算月・担当・今月の件数・資料の回収率の列)(FR-201)
- SC-021 顧問先詳細(インライン編集、契約サービス、年表、タブ構成)(FR-151, FR-202, FR-204)
- SC-022 顧問先の新規作成と、1年分の期限のプレビュー (FR-152, FR-203)
- 対応記録モーダルと、次にやることからのタスク自動生成 (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 — 期限と業務(5日)
- 期限の作り直し(未完了だけ・確認ダイアログ)(FR-211〜219)
- SC-010 期限ボード(月の切替、状態の列、残り日数・回収率つきのカード、ドラッグとキーボード)(FR-221〜223)
- SC-011 期限の表/SC-012 期限カレンダー(集中する日の印)(FR-224)
- SC-013 業務の詳細 (FR-225)
- SC-030・031 資料の回収と依頼文の作成、催促の自動化 (FR-231〜235)
- SC-014 確認待ちと承認・差し戻し、通知 (FR-241〜243)
- SC-001 ダッシュボード(ロールで範囲が変わる)(FR-271)
Phase 2 完了チェック
- フローAと、フローBのうち工数の記録を除く部分が完走する(工数は Phase 3)
- 4章「ロールを跨ぐ体験」の1〜4が動作する
- 6.6 の期限の計算テストがすべて通る
Phase 3 — 工数・報酬・請求・スポット案件(4日)
- SC-050 工数の記録(週の表、15分単位)と業務の詳細からの記録 (FR-251, FR-252)
- SC-060 請求の一括作成 (FR-261)
- SC-061 請求書プレビューとPDF(適格請求書の記載事項)(FR-262, FR-171〜174)
-
src/lib/calc/withholding.tsとテスト、源泉徴収の表示 (FR-263) - 請求の状態・未入金・入金の記録 (FR-264, FR-265)
- 金額の表示を所長だけに限る(列の選択にも出さない)(FR-266)
- SC-040〜042 スポット案件(段階・ボード)と報酬の見積書PDF (FR-276〜280)
Phase 3 完了チェック
- フローC、フローBの工数の記録が完走する
- 4章「ロールを跨ぐ体験」の5が動作する
- 請求書PDFに、適格請求書の記載事項がすべて入っている
- 担当者・マネージャーの画面に、金額が一度も出てこない
Phase 4 — 分析と設定(3日)
- SC-100 顧問先別の採算(所長のみ)(FR-272)
- SC-101 担当者の負荷 (FR-273)/SC-102 期限の守り具合 (FR-274)/SC-103 報酬の推移 (FR-275)
- 期間の指定 (FR-901)
- SC-201〜207 共通の設定 (FR-902〜907)
- SC-208 業務のひな形と期限のルール(ルールの型ごとの入力、変更の影響件数の表示)
- SC-209 必要な資料のひな形/SC-210 祝日/SC-211 報酬のひな形
Phase 4 完了チェック
- フローD・Eが完走する
- 業務のひな形の変更が、未完了の業務にだけ反映される
Phase 5 — 仕上げ(3日)
5-1. 体験の総点検
- 4章「ロールを跨ぐ体験」をすべて手動で確認する
- 全37画面を開き、空の画面が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/querysrc/lib/calcsrc/lib/csvsrc/lib/repo/_scopeのカバレッジ80%以上 -
/dev/componentsを公開版で非表示に - Cloudflare Workers へ公開(
npx wrangler deploy) - 公開URLで、直接開いた詳細画面のURL(例
/clients/k-001)が 404 にならないことを確認する
合計 約22営業日(約4.5週間)/1名専任 + レビュー体制。
工数配分の意図: Phase 1 に4日を割いているのは、データテーブル基盤が全画面に波及するため。ここを雑に作ると、以降の全一覧画面が作り直しになる。逆にここが良ければ、業種の一覧はほぼ設定だけで完成し、Phase 2〜4 の時間を業種の作り込みに使える。
12. 受入基準
- 6章の優先度 P1 の要件がすべて実装されていること
- 5章の主要フローが、最初から最後まで完走すること。フローと4章の体験に出てくる機能は、6章の優先度が P2・P3 でも必須とする
- 4章「ロールを跨ぐ体験」がすべて動作すること
- ロールを切り替えると、一覧・ダッシュボード・分析の表示範囲が変わること。かつスコープ判定が
src/lib/repo/_scope.tsに集約されていること - 一覧テーブルが、絞り込み・列選択・保存ビュー・一括操作・キーボード操作のすべてに対応し、スマホ幅ではカード型になること
- 1,000行での絞り込みが100ms以下、スクロールが60fpsを維持すること
- CSVインポートが列の対応付けとエラー行表示に対応し、CSVの書き出しと帳票PDFが実際にダウンロードできること
- 全37画面のいずれにも空の状態がなく、士業事務所らしいリアルなデータが表示されていること
- リロード後も操作結果が保持され、「デモをリセット」で初期状態に戻ること
- axe-core で Critical / Serious の指摘が0件であること
- Lighthouse の基準値を満たすこと
- データアクセスがすべて
src/lib/repo/を経由しており、コンポーネントが Zustand ストアを直接参照していないこと - 6.6 の期限の計算テスト(繰り下げ・特例・延長・年末年始)がすべて通ること
- 顧問先の決算月・契約サービスを変えたとき、未完了の業務だけが作り直され、完了した業務が動かないこと
- 請求書PDFに、適格請求書の記載事項(登録番号・税率ごとの合計と消費税額 など)がすべて入っていること
- 担当者・マネージャーのどの画面にも、報酬の金額が出てこないこと
- スマホ(375px)で、所長が確認待ちを承認・差し戻しできること
判断に迷ったときのルール
- 仕様がこの文書にない場合は、実装せずに質問する。 推測で作らない
- キーボード操作と「空の画面を作らない」は削減対象外。 速度を出すために削らない
- スコープ外(3章 Won't have)は、思いついても実装しない。特にワークフローのビルダーと帳票の自由レイアウト編集
- 「デモだから」を理由に品質を落とす判断はしない
- コンポーネントからストアを直接触りたくなったら、それはリポジトリ層に足りないメソッドがあるということ
- 迷ったら士業事務所の人の1日を思い浮かべる。 その人が毎朝最初に開く画面で、最初に知りたい数字は何か。それが画面のいちばん上にあるか
- 期限の日付を手で書かない。 シードも画面も、期限はすべて
deadline.tsを通して作る - 法令にもとづく期限・税額の計算は、この文書に書いた範囲から広げない。広げたくなったら質問する

