代理店向け：時間管理とプロジェクト収益性を追跡するウェブアプリを作る

目標を定義する：請求可能時間と実際のプロジェクト収益性

画面設計やデータベース選定の前に、毎日アプリを使う人たちにとって「成功」が何かを具体的にしてください。代理店が時間追跡に失敗するのは、機能不足というよりも目標が曖昧だからです。

誰が使うか（そして彼らが気にすること）

代理店のオーナーは確信が欲しい：「このリテイナー、本当に儲かっているか？」 クライアント、チーム、月ごとの集計が必要です。

プロジェクトマネージャーはコントロールとスピードを求めます：消化状況と予算の追跡、スコープの肥大を早期に発見し、タイムシートを期日通りに承認すること。

チームメンバー（と契約者）はシンプルさを求めます：素早く時間を記録でき、何に対して記録すべきか分かり、未入力を催促される手間を避けたい。

設計すべきコアの成果

測定可能な成果から始めます：

• 正確な請求可能時間：ギャップや月末の推測入力を減らし、正しいクライアント／プロジェクト／タスクに割り当てる
• 見落とし請求の削減：承認済みの時間がコピー＆ペーストなしに請求フローに入る
• 明確なマージン：どの仕事が代理店を資金供給しているか、どの仕事がじわじわ損耗させているかが見える

代理店にとっての「収益性」とは

最低限、収益性は：

収益（請求または認識）− 労務コスト（従業員の内部コストレート＋契約者の料金）− 間接費配賦（初期はオプションだが真のマージンには重要）

初日から間接費をモデル化しない場合でも、プロジェクトマージン（直接労務のみ）を目標にするのか、真のマージン（間接費含む）を目標にするのかを決めておくと、後でレポートの混乱を防げます。

スプレッドシートや分断されたツールが壊れる理由

スプレッドシートや別々のタイマーは、カテゴリの不一致、承認の欠落、“真実”のバージョン違いを生みます。結果は予測可能：請求漏れ、請求の遅延、誰も信頼しない収益性レポート。

代理店が既に辿るワークフローをマップする

UI設計の前に、仕事が実際に代理店内をどう流れるかをマップします—「時間を追跡する必要がある」から「請求してマージンを確認した」まで。アプリが既存の習慣に合えば、導入が容易になりデータ品質が向上します。

実際の時間入力の方法

多くの代理店はタイマーベースの追跡（深い作業に向く）と手動入力（会議後やモバイル時に一般的）を混用しています。両方をサポートし、チームに選ばせてください。

また、ワークフローが日次ログ中心（精度向上、週末のパニック軽減）か週次タイムシート中心（承認が多いチームで一般的）かを決めます。多くのチームは日次リマインダーを欲しつつ、週次の提出ステップも求めます。

プロジェクトとクライアントのセットアップ：販売方法に合わせる

時間追跡は、プロジェクトが代理店の価格設定方法に合わせてセットアップされているときにだけ機能します：

• 時間単価（Hourly）：単純な作業や継続サポート
• 固定費（Fixed-fee）：配信コストを把握しマージンを守るために時間を追跡
• リテイナー：月次バケットに対する追跡（含まれる時間と超過分あり）

マッピング中に、誰がクライアント／プロジェクトを作るか（オプス、PM、アカウントマネージャー）と必要な情報（サービスライン、役割、地域、レートカード）を記録します。

承認：摩擦を減らし、説明責任を保つ

承認は通常予測可能なサイクル（週次または隔週）で行われます。明確にしてください：

• 誰が提出するか（各個人か、チームリードか）
• 誰がレビューするか（PM、アカウントリード、ファイナンス）
• 承認後に時間が遅れて入力・編集されたらどうなるか

レポーティング：意思決定者が期待するビュー

代理店は一般的にプロジェクト別、クライアント別、サービスライン別、個人別のマージンをレビューします。早期にこれらの期待をマッピングすれば、どのメタデータを入力時に捕捉する必要があるかが決まり、後の手戻りを防げます。

データモデルを決める：何を保存すべきか

データモデルはプロダクト、レポート、請求書の間の契約です。早期に正しく設計すれば、UIやワークフローを後から変えても収益性の計算が壊れません。

コアエンティティ（「誰」と「何」）

小さく、よくリンクされたオブジェクト群から始めます：

• Clients（クライアント）：請求先住所、通貨、税設定、支払条件
• Contacts（連絡先）：クライアントごとに複数（財務担当／プロジェクトリード等）、メールと役割
• Projects（プロジェクト）：クライアントに属し、ステータス、開始／終了日、デフォルトの価格モデル、オプションの予算を保持
• Tasks/Activities（タスク／活動）："Design", "Dev", "PM", "Meetings" のようなシンプルな分類。柔軟に（ワークスペースごとにカスタム可能）

タイムエントリ（真実の出所）

最終的に関係するすべてのレポートはタイムエントリに依存します。最低限保存する項目：

• 日付（後でタイマーを使うなら開始／終了タイムスタンプ）
• 継続時間（分単位で保存して丸め誤差を避ける）
• 請求可フラグ（請求可／非請求）
• メモ（何をしたか）
• リンク／添付（オプション：URL、ファイル参照、統合ID）

さらに外部キーを捕捉：担当者、プロジェクト、タスク／活動。監査用に不変のcreated_at/updated_atタイムスタンプも含めます。

レート（時間が収益になる仕組み）

代理店は単一の時間単価を使うことが稀です。上書きできるようにレートをモデリングします：

• 役割ベースのレート（例：Designer、Senior Dev）
• 個人別レート（特定スタッフの例外）
• クライアント固有のレートカード（クライアントごと、役割ごとに交渉済み）

現実的なルール：承認時にタイムエントリに適用されたレートを保存しておくこと。そうすればレートカードを編集しても請求が変わりません。

コスト（時間がマージンになる仕組み）

収益性にはコストが必要です：

• 個人ごとの内部コストレート（時間あたりの負荷コスト）
• 契約者コスト（時間単位または固定、ベンダーに紐付け）
• 経費（カテゴリ、金額、通貨、レシート参照、請求可／非請求）

これらが揃えば、代理店を一つの硬直したワークフローに押し込めることなく収益、コスト、マージンを計算できます。

代理店が実際に使う価格モデルをサポートする

時間追跡アプリが時間単価しか扱えないと、現実に合わせるためにツールをこじ開けてスプレッドシートや手作業が生まれます。代理店は混合ポートフォリオ（時間単価、固定費、リテイナー）を運用することが多いので、チームが時間を記録する方法を変えずにこれらをサポートする必要があります。

時間単価プロジェクト（古典的ケース）

紙の上では簡単です：請求可能時間 × レート。難しいのはレートが変動する点です。

役割別、個人別、クライアント／プロジェクト別のレートカードをサポートし、次のような調整を制御します：

• **Write-downs（値引き）とWrite-ups（値上げ）**をタイムエントリ単位または請求行単位で扱う
• 誰がいつ理由付きで調整したかの明確な監査トレイル

これにより請求可能時間の追跡は正確さを保ちながら、アカウントチームがクライアント期待に合わせられます。

固定費プロジェクト（予算消化とマージン可視化）

固定費プロジェクトは予算の消化スピードで成功が左右されます。ここでは時間追跡は請求だけでなくプロジェクト予算管理と早期警告のために不可欠です。

固定費プロジェクトは次の要素でモデル化します：

• 総フィー（収益）
• 内部予算（時間、コスト、または両方）
• 目標マージン（任意）

週単位の消化、完了までの予測、スコープ変化によるマージントレンドを表示し、今は利益が出ているが徐々に悪化しているプロジェクトを見える化します。

リテイナー（割当、繰越、超過）

リテイナーは繰り返しルールが多いです。ツールは月次の割当時間（例：月40時間）を設定でき、月末に何が起きるかを定義できるようにします：

• 繰越なし（未使用時間は消失）
• 限定的な繰越（上限X時間、またはX月まで繰越可）
• 無制限繰越（稀）

割当を超えた時間は定義されたレートで超過請求されることが多く、その計算を透明にしてクライアントが合意できるようにします。

非請求時間（代理店の収益性にとって不可欠）

社内業務、プリセールス、管理、研修などの非請求カテゴリを扱うこと。これらを隠さず第一級の時間タイプとして扱ってください。稼働率や代理店全体のレポーティングに役立ち、「忙しい＝儲かっている」ではない理由を説明します。

主要指標と計算式を選ぶ（シンプルに保つ）

時間＋収益性アプリは、誰もが数字を信頼したときに成功します。つまり、小さな指標セットを選び、一度定義してどこでも同じ式を使うことです（タイムシート、プロジェクトビュー、レポート）。

1) 請求の基本：時間、金額、EHR

全ての代理店が理解している3つのフィールドから始めます：

• 請求可能時間：請求可能なクライアントプロジェクトに記録された時間
• 請求金額：その時間が請求レートでいくらになるか
• Effective Hourly Rate（EHR）：実際に1時間あたりいくら稼いだか

計算式：

• Billable amount = billable_hours × bill_rate
• EHR = revenue ÷ hours_logged（または billable_amount ÷ billable_hours：タイム＆マテリアルの場合）

EHRは優れた整合性チェックです。同じレートカードを使っているのにEHRが大きく異なれば、スコープ変化や割引、書き下げが疑われます。

2) 労務コストと粗利

収益性にはコストが必要です。まずはシンプルに労務だけを含めます：

• Cost of labor = internal_labor_cost + contractor_cost
• Gross margin = (revenue − cost_of_labor) ÷ revenue

内部コストは時間当たりのコスト（給与＋税金＋福利厚生を時間で割った値）として定義し、タイムシートから自動算出できるようにします。

3) 稼働率（“available”の定義を明確に）

稼働率は混乱を招きやすいので、“available hours”を明確に定義します。

• Available hours：勤務時間 − 祝日や承認済み休暇（必要なら内部会議を差し引く）
• Utilization rate = billable_hours ÷ available_hours

この定義をアプリ内に文書化して、レポートが議論の種にならないようにします。

4) 予算対実績とオーバーランアラート

予算は時間と金額の両方で追跡します：

• Hours variance = actual_hours − budget_hours
• Spend variance = actual_revenue_or_cost − budgeted_revenue_or_cost

閾値でシンプルなアラート（例：80%消化で通知、100%超過で警告）を出してPMがマージン消失前に対処できるようにします。

使われる時間追跡体験を設計する

ログ付けが書類仕事に感じられると、人は避けます—あるいは金曜夜にまとめて推測で埋めます。目標は、時間入力が先延ばしより速く感じられること、かつ請求と収益性に十分な信頼できるデータを生むことです。

効率的で手間のない高速入力

速さを優先してください。よいデフォルトは「1行＝1エントリ」で、プロジェクト、タスク／活動、継続時間、任意のメモが入る形式です。

よく使う動作をほぼ即時にします：

• キーボードファースト："/"でプロジェクト検索、Tabでフィールド移動、Enterで次の行追加
• 最近使ったプロジェクト／タスク：直近5〜10件を表示し、ピン留め可能に
• スマート提案：カレンダーイベント、最近使ったクライアント、同じ曜日の最後のエントリを前回入力として補完（常に編集可能）

監視にならないタイマー機能

タイマーを好む人もいれば手動を好む人もいます。両方をサポートしてください。

タイマー機能では実務的に：

• アイドル検出と穏やかなプロンプト：「12分離席していました—保持／破棄／分割しますか？」
• 丸めルールの設定（クライアント単位またはワークスペース単位）：例：6分、15分、丸めなし。元の時間は監査のために常に保存
• リマインダーは強制でなく促すもの：終業時の「未入力時間」通知、任意のプッシュ

タイムシートUX：週次クリーンアップを簡単に

週次タイムシートで導入が決まります。

週ビューで以下をサポート：

• 一括編集（複数行に対するプロジェクト／タスク変更）
• 前週コピー（その後調整）
• インライン検証（例：「本日6.5/8時間」）

メモは任意にしつつ、請求時に必要な場合は簡単に追加できるようにします。

モバイルの基本

モバイルはすべての機能を必要としません。フォーカスは：

• 当日のエントリを素早く編集
• タイマーの開始／停止
• タイムシートの承認／却下（短いコメント付き）

承認が重要なら、1分以内に済む操作にしてください。そうでないと請求が停滞します。

役割、権限、承認を設計する

誰が何を見て編集できるかを信頼できないと、代理店は数字を信じません。権限は「誤った会計処理」を防ぐ場所でもあります（例：契約者が先月の承認済みタイムシートを編集できるなど）。

小さなロールセットから始める

ほとんどの代理店は次の5つのロールで95%のニーズをカバーできます：

• Admin：ワークスペース、セキュリティ設定、統合、グローバルレートカードの管理
• Finance：承認のレビュー、請求／会計へのエクスポート、マージンと収益ビューへのアクセス
• Project Manager：プロジェクト管理、予算、担当プロジェクトの承認
• Member：割り当てられたプロジェクトへの時間と経費の記録
• Contractor：Memberに近いが可視性が限定され、自分のエントリのみアクセス可能

v1で「カスタムロールビルダー」を作るのは避け、代わりにいくつかのトグル（例：「時間を承認できる」「財務情報を閲覧できる」）を用意して例外に対応してください。

混乱を避ける承認ルール

承認は一貫性を強制しつつ速度を落とさないように：

• 必須フィールド：クライアント、プロジェクト、タスク／タイプ、日付、継続時間、（任意で）短いメモ
• ロック期間：承認後は該当週／月を読み取り専用に。編集はFinance／Adminの「アンロック」を要する
• 監査トレイル：誰がいつ何を変更したか（エントリ編集、承認、アンロック）を保持。紛争やコンプライアンスで重要

クライアント／プロジェクト単位の権限

機密性の境界が必要です。プロジェクトレベルのアクセス（割り当てられているか否か）と財務可視化（レート、コスト、マージン）を分離する権限をサポートしてください。PMは時間は見られても給与レートは見せたくないことが多いです。

認証とセッションのセキュリティ

ベースラインとしてメール／パスワードと強力なリセットフローを提供します。大きなチームをターゲットにするなら**SSO（Google／Microsoft）**を追加。セキュアなセッション（短いトークン寿命、デバイスのログアウト、任意の2FA）を実装して、承認や財務レポートが紛失した端末で漏れないようにします。

請求と請求書作成を二重入力なしでつなげる

時間は「請求可能」になって初めてクライアントに理解される請求書になります。一番良い方法は時間を単一の真実の出所とすること：人は一度だけ作業を記録し、その後のすべて（請求、帳尻調整、エクスポート、統合）は同じエントリを参照します。

タイムエントリを請求書準備済みにする（デフォルトで）

タイムシートのデータをファイナンスがそのまま請求書にできる形式でエクスポートできるように設計します。クライアント → プロジェクト → 人 → タスク（必要なら日付レンジで）でグループ化・小計できる請求準備エクスポートを提供してください。

実用的なアプローチは各エントリに簡単な「請求ステータス」（例：Draft, Ready, Invoiced）と、請求にプッシュしたら「請求参照」を付与することです。これによりデータのコピーを避けつつ追跡可能になります。

既に自社プロダクトに時間追跡があるなら、請求がどのように紐づくかを示してください（例：/features/time-tracking から “Invoice prep” ビューへ）。

書き下げや調整を透明に追跡する

代理店はしばしば時間を調整します：スコープの変更、サービスの好意、内部ミス。これを隠さずモデル化します。

エントリ単位（または請求の調整行）で書き下げ／調整を許可し、理由コード（例：Out of scope, Client request, Internal rework, Discount）を必須にします。後でマージンの変化を説明しやすくなります。

ロックインを避ける連携を提供する

多くの代理店は既に会計／請求ツールを使っています。次の連携オプションを提供してください：

• 承認済み請求時間を取得し、請求IDを戻すためのAPIエンドポイント
• タイムシート承認や請求済みにしたときに外部に通知するWebhooks

小さなチーム向けにはクリーンなCSV/XLSXエクスポートを、成長中チームには /pricing のプランと統合機能を案内します。

アーキテクチャと技術スタックを選ぶ（流行より実用）

時間追跡アプリは信頼性で生き残ります：合計が正しく、編集は追跡可能、レポートは請求と一致すること。正確さと保守性を優先する実績あるコンポーネントを選んでください。

プロトタイプを迅速に代理店に見せたいなら、Koder.ai のようなvibe-codingプラットフォームで、構造化されたチャットからReactフロント + Go＋PostgreSQLのバックエンドを生成するのは有益です。ワークフロー、データモデル、レポートを検証してからUIに投資できます。

データベース：履歴を残す（最新値だけでなく）

請求可能時間追跡はクリーンなリレーションに依存するので、リレーショナルDB（PostgreSQLが一般的）を使います。

次のようにテーブルを構成します：

• 可能な限りタイムエントリを不変レコードとして保存し、変更時は編集イベント（誰が、何を、いつ、なぜ）を記録
• レートやレートカードはバージョン管理（有効期間）して古い請求をそのまま再現できるように
• 計算済み合計を多くの場所に保存しない。ソースデータから算出し、パフォーマンスのためにキャッシュのみ行う

API：実際の操作に基づいて設計する

エンドポイントはシンプルで予測可能に：

• Time entries：create, update, submit, approve/reject, lock/unlock
• Projects：budgets, billable rules, assigned people, status
• Rates：person overrides, role rates, client-specific rates
• Reports：utilization, project margins, budget vs. actual

作成アクションには冪等性を持たせ、明確なバリデーションエラーを返すこと。複数デバイスから時間を入力するケースに備えます。

フロントエンド：画面を減らして言い訳を減らす

優先する体験は4つ：高速タイムシート、マネージャーの承認キュー、プロジェクトダッシュボード（予算＋消化）、フィルタ可能なレポーティング。

バックグラウンドジョブ：面倒な作業を自動化する

リマインダーメール／Slack通知、定期エクスポート、キャッシュ済みレポートの再計算、夜間のデータ品質チェック（レート欠損、未承認タイムシート、予算超過）にジョブキューを使います。

まずMVPを作り、徐々に高度な収益性機能を導入する

代理店が収益性を追跡できないのは機能不足ではなく、導入が難しいからです。まずはチームの既存の働き方に合う小さなMVPを作り、データ品質と習慣が整ったら深みを追加します。

即試せるようにシードデータを用意する

空のシステムは勢いを殺します。新しいワークスペースがすぐに操作できるように（または生成して）シードデータを出荷してください：

• サンプルクライアントとプロジェクト（リテイナー＋固定費＋内部）
• 基本的なレートカード（標準の役割レートとオーバーライド例）
• 役割（admin, manager, contributor）と現実的な権限

これによりオンボーディング時間が短縮され、デモが具体的になります。

MVPの範囲：価値を証明する最小ループ

MVPは1つのクローズドループを提供するべきです：ログ → 承認 → マージン確認。

含めるもの：

• プロジェクト／タスク、請求可トグル、メモを備えた時間追跡（タイマー＋手動）
• タイムシート承認（週次提出、マネージャーの承認／却下とコメント）
• プロジェクトごとのシンプルなマージンレポート（トラックされたコスト対請求価値）

マージンレポートは意見を持たせて単純に：1画面、いくつかのフィルタ、そして“コスト”と“収益”の明確な定義。

速く作るなら、Koder.aiのPlanning Modeでエンティティ、権限、承認ルールをまず設計し、初期アプリを生成して反復するのも手です。後でソースコードをエクスポートしてフルカスタムに移行できます。

フェーズ2：予測とキャパシティ計画

チームが一貫して時間を提出・承認するようになったら、前方に目を向けるツールを追加します：

• プロジェクトと個人別の予測対実績
• 稼働率とキャパシティ計画（誰が過負荷／過少配分か）
• 必要に応じた詳細な権限（例：レートを財務だけに制限）

フェーズ3：連携と自動化

コアワークフローが信頼されてからUIを膨らませずに拡張：

• 統合（会計、請求、給与、カレンダー）
• カスタムフィールド（所管領域、拠点、クライアント部門）
• 自動化ルール（内部プロジェクトの自動承認、リマインダー、予算アラート）

ルール：新機能は「データ精度を上げる」か「維持作業を減らす」どちらかであること。

よくあるリスクへの対処：正確さ、コンプライアンス、性能

時間と収益性アプリは機能だけでなく、信頼を失わせる微妙な問題に注意を払う必要があります：「時間が変わった」「レポートが遅い」「なぜそのデータを保存するの？」など。これらのリスクに早く対処して、代理店が全社で展開する安心感を作ります。

プライバシーとコンプライアンス：必要最小限を保存し、制御する

時間追跡は通常、敏感な個人情報を必要としません。ユーザープロファイルは最小限に（名前、メール、役割）し、正当化できない情報は収集しないでください。

導入初期から保持期間のコントロールを追加します：管理者が生のタイムエントリ、承認、請求書の保持期間を設定できるように。監査のためのエクスポートを容易にし、退職した契約者のデータを集計値を保ったまま匿名化または削除する方法を明確にします。

正確さ：丸め、タイムゾーン、承認後の編集

小さな「算術の癖」が大きな紛争を生みます。ルールを決めてドキュメント化してください：

• 丸めポリシー（例：最寄り6分）をタイマー、手動入力、インポートで一貫適用
• タイムゾーン処理：タイムスタンプはUTCで保存、表示はユーザーのローカル時間、承認時のタイムゾーンをロック
• 編集ポリシー：承認後の変更は再承認を必要とし、サイレントな上書きを避ける

マージされたセッション（停止／開始）、重複エントリ、デバイス時計の変更時の取り扱いも設計に入れてください。

性能：すべてをライブ再計算せずに高速なレポートを

代理店は週次・月次ビュー（稼働率、プロジェクトマージン、クライアント収益性）で作業します。もしダッシュボードが生データから毎回合計を再算出していたら限界に達します。

日次／週次／プロジェクト／担当者ごとの一般的なスライスは事前集計して増分更新し、重い“もしも”再計算はメインのレポーティングパスから切り離してください。

監査性：誰がいつ何を変えたか

お金に影響する変更はすべて追跡可能に：タイムエントリ編集、レートカード更新、予算変更、書き下げ、承認。アクター、タイムスタンプ、旧値、新値、理由メモをキャプチャします。

これは単にコンプライアンスのためではなく、紛争を迅速に解決し、マネージャーの信頼を保持するためです。

ローンチ、導入促進、成功の測定

時間追跡アプリは最初の数週間で成功か失敗かが決まります。ローンチを行動変容プロジェクトとして扱ってください：摩擦を減らし、期待を設定し、進捗を可視化します。

ローンチチェックリスト（初日を親しみやすく）

移行計画を明確に：何を移すべきか（クライアント、プロジェクト、ユーザー、レートカード）、何を新規開始にするか（過去のタイムシート）、誰が承認するか。

テンプレートとスマートデフォルトを用意してフォームの空欄を減らします：

• よくあるプロジェクトタイプ（フェーズ／タスクが事前入力）
• デフォルトの請求可／非請求カテゴリ
• 役割／シニアリティ別のレートカードデフォルト
• 稼働率用の週次容量のデフォルト

1つのチームで1請求サイクルの短いパイロットを行い、その後全社展開。アプリ内に「60秒で時間を記録する方法」などの短いガイドを置いてください（例：/help）。

導入促進（ルーティンに焦点を）

習慣化のために穏やかな自動化を使います：

• 未記録日を基にした欠損のリマインダー（無差別スパムではない）
• 毎週金曜のサマリー：記録済み時間、欠損エントリ、請求可能比率
• マネージャーダッシュボードは例外（未提出タイムシート、大きなオーバーラン）を強調する

承認は軽く：マネージャーが数分で週を承認でき、コメントは問題があるときだけにする。

成功を測る（価値を示す指標）

小さな運用指標を追跡します：

• タイムシート完了率（チーム別・週次）
• 請求遅延（月末から請求送付までのラグ）
• マージン可視化（コスト対予算が最新のプロジェクトの割合）

フィードバックから反復（まずは簡素化、次に自動化）

最初の1か月は摩擦を減らすことに注力：必須フィールドを減らす、より良いデフォルト、高速入力。次に実際の利用パターンに基づいて反復し、繰り返し作業を自動化します（提案タスク、繰越タイマー、異常値フラグなど）。