SOUZOHSPECS

業務システム ・ KOMON

【士業】顧問先・期限管理システム

士業向け

顧問先を登録すれば1年分の期限が並ぶ、税理士・社労士・行政書士事務所のための管理アプリ

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

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

v1.0・作成 2026-09-30

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    Phase 0基盤とデザインシステム
    Claude Code に送る
    @要件定義書.md の「実装タスク」にある Phase 0 を作ってください。
    Phase 1一覧基盤と顧問先管理
    Claude Code に送る
    @要件定義書.md の「実装タスク」にある Phase 1 を作ってください。
    Phase 2期限と業務
    Claude Code に送る
    @要件定義書.md の「実装タスク」にある Phase 2 を作ってください。
    Phase 3工数・報酬・請求・スポット案件
    Claude Code に送る
    @要件定義書.md の「実装タスク」にある Phase 3 を作ってください。
    Phase 4分析と設定
    Claude Code に送る
    @要件定義書.md の「実装タスク」にある Phase 4 を作ってください。
    Phase 5仕上げ
    Claude Code に送る
    @要件定義書.md の「実装タスク」にある Phase 5 を作ってください。
  6. 本番で使うなら

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

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

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

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

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

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

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

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

版数 1.0(DBレス構成)/ 作成日 2026-09-30 / 発行 ソウゾウ合同会社 用途 業種特化アプリの実演デモ / 士業事務所向け 顧問先・期限管理編


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

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

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

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


目次

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

1. プロジェクト概要

背景と目的

税理士・社会保険労務士・行政書士の事務所(職員3〜20名規模)は、数十〜数百の顧問先について、毎月・毎年くり返す期限を、Excelの一覧と担当者の記憶で守っている。決算月は顧問先ごとに違い、源泉所得税の納期の特例、年末調整、算定基礎届、労働保険の年度更新、許認可の更新と、期限の種類も多い。資料が届かないまま期限が近づき、所長の確認が期限の直前に集中する。顧問料に見合う手間で終わっているかも、誰も数字で見ていない。

汎用のタスク管理を入れても、「顧問先ごとの決算月から1年分の期限を作る」ことができないため、結局Excelに戻る。KOMON は、顧問先を登録すると1年分の期限が自動で並び、資料の回収・作業・所長の確認・請求までが1つの流れでつながる事務所のための管理アプリである。

目的 内容
業種特化の実装力の証明 決算月・納期の特例・届出の時期など、士業の期限のルールを画面の裏で計算し、1年分を自動で並べる
期限を落とさない設計の証明 資料が届いていない・確認待ちが溜まっている・期限が近いものを、システム側から知らせる
経営の数字を見せる設計の証明 顧問先ごとの工数と報酬から、採算(1時間あたりの報酬)を出す
横展開の資産化 共通の土台(ロール・一覧・設定・帳票)に、業種の部分だけを載せる構造にする

プロダクト定義

項目 内容
プロダクト名 KOMON(こもん)※仮称
一言定義 顧問先を登録すれば、1年分の期限が並ぶ。士業事務所のための顧問先・期限管理
提供形態 レスポンシブWebアプリ。フロントエンド完結(サーバー側の保存なし)
主戦場 事務所のPC(期限の管理・作業・確認・請求)。スマホは所長の確認と外出先での予定確認
想定利用者 税理士・社労士・行政書士の事務所の担当者、マネージャー、所長、事務

プロダクトコンセプト

「期限から、逆算する。」

士業の仕事は、すべて期限から逆算して進む。KOMON は期限を入力させるのではなく、顧問先の情報(決算月・契約しているサービス・従業員の有無)から期限を計算して並べる。担当者は毎朝「今週、何の資料がまだ届いていないか」「所長の確認に何日前に回せばよいか」を画面から受け取る。

デモとしての成功条件

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

2. アーキテクチャ方針 — データベースを持たない

基本方針

バックエンドとデータベースを持たない。すべてブラウザ内で完結させる。

一般的な構成 本プロジェクト
PostgreSQL / Supabase シードデータ(TypeScript)+ ブラウザ内ストア
認証・SSO デモ用ロール切替(ワンクリック)
REST / GraphQL API ストア上の操作(リポジトリ層)
メール送信・SMS 送信内容のプレビュー表示で再現
PDF生成(サーバー側) ブラウザ内で生成し、実際にダウンロードできる
CSVインポート/エクスポート 実際に動く。 ブラウザ内で読み込み/書き出しする
画像のアップロード 写真を扱う業種のみ。ブラウザ内で縮小して IndexedDB に保持する(7章「画像」)

なぜこの構成にするか

  • デモとして最適 — 訪問者は登録もログインもせずに、全機能を即座に触れる
  • 顧客データを一切預からない — 入力されたデータはブラウザから出ない。自社のCSVを投入して試すこともできる
  • 開発速度 — 認証・権限のサーバー実装・マイグレーションが不要になり、業種の作り込みと操作効率に全時間を投下できる
  • 運用コストゼロ — 静的配信のみ

差し替え可能性の担保(重要)

データアクセスは必ず src/lib/repo/ のリポジトリ層を経由すること。 コンポーネントからストアを直接触らない。

[ 画面・コンポーネント ]
        ↓  呼ぶのはこの層だけ
[ src/lib/repo/*.ts ]   ← 全メソッドを async にしておく
        ↓
[ src/lib/store/*.ts ]  ← Zustand + persist(localStorage)
        ↓
[ src/lib/seed/*.ts ]   ← 初期データ

リポジトリの各メソッドは、中身が同期処理でも async で定義し、await で呼ぶ。本番化する際は、リポジトリの実装だけをデータベースへの問い合わせに差し替えれば、画面は一行も変更せずに済む。

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

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

  1. 担当者が業務を「確認待ち」に回す → マネージャーに切替 → 確認待ちの一覧の先頭に現れ、通知が届いている
  2. マネージャーが理由をつけて差し戻す(「減価償却の計算に固定資産台帳の最新版が必要」)→ 担当者に切替 → 業務が「差し戻し」に移り、理由が通知と業務の詳細に出ている
  3. 所長が顧問先の決算月を「3月」から「9月」に変える → その顧問先の決算・申告の期限が作り直され、期限ボードとカレンダーの位置が変わる(すでに完了した業務は動かさない)
  4. 担当者が資料「通帳のコピー(9月分)」の受領を記録する → 資料の回収の一覧から消え、その業務の必要な資料がすべてそろっていれば、確認のダイアログなしで「作業中」に進められる
  5. 所長が今月の請求を一括作成する → 担当者の顧問先詳細の「報酬・請求」に請求書が現れる(金額は所長のみ表示)

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 の薄いラッパー。写真を扱う業種のみ
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/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)
  • キーボード操作(↑↓ Enter Space ⌘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/query src/lib/calc src/lib/csv src/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. 受入基準

  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. 全37画面のいずれにも空の状態がなく、士業事務所らしいリアルなデータが表示されていること
  9. リロード後も操作結果が保持され、「デモをリセット」で初期状態に戻ること
  10. axe-core で Critical / Serious の指摘が0件であること
  11. Lighthouse の基準値を満たすこと
  12. データアクセスがすべて src/lib/repo/ を経由しており、コンポーネントが Zustand ストアを直接参照していないこと
  13. 6.6 の期限の計算テスト(繰り下げ・特例・延長・年末年始)がすべて通ること
  14. 顧問先の決算月・契約サービスを変えたとき、未完了の業務だけが作り直され、完了した業務が動かないこと
  15. 請求書PDFに、適格請求書の記載事項(登録番号・税率ごとの合計と消費税額 など)がすべて入っていること
  16. 担当者・マネージャーのどの画面にも、報酬の金額が出てこないこと
  17. スマホ(375px)で、所長が確認待ちを承認・差し戻しできること

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

  1. 仕様がこの文書にない場合は、実装せずに質問する。 推測で作らない
  2. キーボード操作と「空の画面を作らない」は削減対象外。 速度を出すために削らない
  3. スコープ外(3章 Won't have)は、思いついても実装しない。特にワークフローのビルダーと帳票の自由レイアウト編集
  4. 「デモだから」を理由に品質を落とす判断はしない
  5. コンポーネントからストアを直接触りたくなったら、それはリポジトリ層に足りないメソッドがあるということ
  6. 迷ったら士業事務所の人の1日を思い浮かべる。 その人が毎朝最初に開く画面で、最初に知りたい数字は何か。それが画面のいちばん上にあるか
  7. 期限の日付を手で書かない。 シードも画面も、期限はすべて deadline.ts を通して作る
  8. 法令にもとづく期限・税額の計算は、この文書に書いた範囲から広げない。広げたくなったら質問する

FROM DEMO TO PRODUCTION

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

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

  1. 1データの保存

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

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

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

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

本番運用をお考えの方へ

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

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

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

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

FREE CONSULTATION

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

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

日程を決めて話す

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

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

まずは問い合わせる

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