freelancer-payment-protection

---

ライセンスについて： このプロジェクトは MIT ライセンスです。著作権は Rudrendu Paul と Sourav Nandy が保有しています。ライセンスの全文は、以下のライセンスをご覧ください。

CLI をインストールする

pip install freelancer-payment-protection-cli
# or: uvx freelancer-payment-protection-cli --help
# or: npx freelancer-payment-protection-cli --help

これにより、下記の FastAPI バックエンド（請求書、エスカレーション、クライアントのリスクスコアリング、すべてのデータコマンドでの --json）用の型付きコマンドラインクライアント fpp がインストールされます。このクライアントは、自分で実行する freelancer-payment-protection API インスタンスと通信します。インスタンスを起動するには、スタック全体をローカルで実行するをご覧ください。すでに実行中のインスタンスがある場合は、FPP_API_URL をその URL に設定してください。

目次

• 概要
• 機能
• スタック全体をローカルで実行する
• コマンドラインインターフェース
• API リファレンス
• 比較
• アーキテクチャ
• MCP サーバー
• セキュリティ
• 未実装の機能
• よくある質問
• コントリビューション
• ライセンス

---

概要

FreshBooks と HoneyBook は、「請求書を送信しました」の段階で止まります。どちらも、クライアントから連絡が途絶えたときに何を伝えるべきかを作成することはなく、作業を始める前にクライアントの未払いリスクをスコアリングすることもありません。このプロジェクトは、Claude を基盤とする FastAPI + Next.js アプリで、2 つの機能に特化しています。支払い期限を過ぎた請求書について、段階に応じた督促メールまたは管轄区域を参照した請求書を作成すること、そしてクライアントの支払いリスクを要因の詳細な内訳とともに 0～100 でスコアリングすることです。どちらも、送信前に人が確認する、AI 生成の信頼度と推論の記録が付属します。

これは、設定後に放置できる自動化システムではありません。段階間の待機時間を強制するバックグラウンドスケジューラーはなく、FreshBooks／QuickBooks／Wave とのライブ同期も現時点ではありません。アーキテクチャ図と実際に接続されている機能との差については、未実装の機能をご覧ください。実際に使えるのは、AI による文面作成、リスクスコアリング、証拠保管庫、そしてこの 3 つをスクリプトで操作する CLI です。

---

機能

機能	実際に実装されている内容
AI による段階的な督促文の作成	5 段階の順序があります（polite_reminder → firm_notice → final_warning → legal_demand → legal_action）。POST /api/v1/escalations/{id}/draft では、Claude に次の段階の件名／本文／トーン／信頼度スコアの作成を依頼します。これはプレビューであり、このエンドポイントはメールを送信せず、段階の変更も保存しません（apps/api/app/services/escalation_service.py）。
管轄区域を参照した督促状	指定した管轄区域の文字列に基づいて、Claude が督促状を作成します。4 つの管轄区域（California、New York、England & Wales、Ontario）にはそれぞれ legal-templates/ 配下に専用のテンプレートファイルがあります。それ以外の管轄区域でも草案は作成されますが、ハードコードされたテンプレートではなく、モデルの一般知識に基づいて書式設定されます。すべての督促状には、固定の AI に関する免責事項の段落が含まれます。threading.Thread → queue.Queue → asyncio.run_in_executor のブリッジを介して SSE で UI にストリーミングします（apps/api/app/services/ai_service.py）。UI だけのタイプライター効果ではなく、実際のストリーミングであることを確認済みです。
クライアントのリスクスコアリング	POST /api/v1/risk/score は、0～100 のスコア、レベル（low／medium／high／critical）、factors 配列を返します。プロンプトでは、7 つの指定要因（業界の支払い慣行、支払い条件の長さ、過去の遅延、契約の品質、請求書の金額、地域、未払い残高の比率）を Claude に評価させ、その推論を返すよう求めます。Claude の呼び出しに失敗した場合、risk_service.py はエラーを返す代わりに、決定論的なヒューリスティックによるスコアにフォールバックします。レート制限は 1 分あたり 30 リクエストです。
証拠保管庫	PDF／PNG／JPEG／.eml／プレーンテキストファイルを手動でアップロードできます（上限 25MB）。請求書ごとに一覧表示と削除ができ、本番環境では Supabase Storage を使用します。ドラッグ＆ドロップによる自動取り込みや ZIP エクスポートのエンドポイントは、現在ありません。アップロードは POST /api/v1/evidence/{invoice_id}/upload を使って、1 ファイルずつ行います。
CLI（fpp）	データを返すすべてのコマンドが --json に対応しています。Supabase 独自の password-grant エンドポイントを使ったログイン状態が保持され、~/.config/freelancer-payment-protection-cli/credentials.json（モード 600）にキャッシュされます。トークンは透過的に更新されます。PyPI と npm で freelancer-payment-protection-cli として公開されています。
セキュリティ制御	すべての Postgres テーブルで行レベルセキュリティを適用しています（packages/db/migrations/versions/002_rls_policies.sql）。ローカルでのバイパスを認めない Supabase JWT 認証、slowapi によるレート制限（AI による草案作成ルートでは 1 分あたり 10 リクエスト、リスクスコアリングでは 1 分あたり 30 リクエスト、全体では 1 分あたり 100 リクエスト）、すべての PR での CodeQL、依存関係のスキャンに使う pip-audit と pnpm audit、CI での TruffleHog によるシークレットスキャンを実施しています。

---

スタック全体をローカルで実行する

新しいクローンを使って検証済みです。前提条件： Node.js 20 以降、pnpm 9.x、Python 3.12.x（このチェックアウトでは 3.13／3.14 はサポートされていません。3.14 では、バックエンドの固定された依存関係の 1 つで pip install が失敗します）。

警告

Python 3.12.x が必須です。3.13 と 3.14 はまだサポートされていません。

git clone https://github.com/RudrenduPaul/freelancer-payment-protection.git
cd freelancer-payment-protection
pnpm install

# Backend env
cp apps/api/.env.example apps/api/.env
# apps/api/.env.example ships two values that don't parse as written. See the
# Troubleshooting question in the FAQ before you skip this:
#   ALLOWED_ORIGINS=["http://localhost:3000"]   (needs the JSON-array brackets)
#   delete the DATABASE_URL= line entirely (Settings doesn't accept it; the
#   app already defaults to sqlite:///./dev.db without it)

cp apps/web/.env.example apps/web/.env.local

pip install -r apps/api/requirements.txt
python -m alembic -c packages/db/migrations/alembic.ini upgrade head
python scripts/seed_dev.py

pnpm dev

シードスクリプトは外部サービスを必要とせず、8 件のクライアント、16 件の請求書、事前生成された段階的な督促イベントを作成します。シード後は、すべて API または CLI からクエリできます。新しい venv で最初から最後まで検証済みです。alembic upgrade head は正常に実行され、seed_dev.py は SQLite にデータを投入し、上記の 2 つの .env の修正を適用すると、uvicorn app.main:app が起動して /health と /health/ready を提供します。

サービス	URL
ダッシュボード	http://localhost:3000
API と OpenAPI ドキュメント	http://localhost:8000/docs

Web ダッシュボードにログインするには、実際の Supabase プロジェクトが必要です（無料プランで問題ありません）。Supabase の apps/api/app/middleware/auth.py は、ローカルでのバイパスを認めず、Supabase が発行した JWT を検証します。シード済みデータには、API／CLI を通じて認証なしで完全にアクセスできます。AI 機能（督促状、リスクスコアリング、段階的な督促文の草案作成）には、apps/api/.env に実際の ANTHROPIC_API_KEY が必要です。キーがない場合、リスクスコアリングはヒューリスティックによるスコアにフォールバックし、ほかの 2 つの AI ルートは 503 を返します。

コマンドラインインターフェース

インストール済みパッケージの実際の --help 出力に基づいて確認済みです。

fpp login                                   Log in (prompts for email/password)
fpp logout                                  Delete cached credentials
fpp whoami [--json]                         Show cached workspace/session info

fpp invoice list [--status] [--client-id] [--page] [--page-size] [--json]
fpp invoice create --client-id --invoice-number --amount --due-date [--currency] [--source-system] [--external-id] [--json]
fpp invoice show <invoice-id> [--json]
fpp invoice set-status <invoice-id> <status> [--json]

fpp escalation list [--json]                Active escalations, grouped by stage
fpp escalation status <invoice-id> [--json] Current stage + full history
fpp escalation advance <invoice-id> [--json] Preview the next stage's AI-drafted email (does not send or persist)

fpp client list [--risk-level] [--search] [--page] [--page-size] [--json]
fpp client show <client-id> [--json]
fpp client risk <client-id> [--json]        Compute/refresh the AI risk score

fpp login
fpp invoice list --status overdue --json | jq '.[] | {id, invoiceNumber, daysPastDue}'
fpp client risk <client-id> --json | jq '.level'

invoice list の --status で指定できる値は、disputed、overdue、paid、pending、written_off です。各コマンドのすべてのフラグを確認するには、fpp <command> --help を実行してください。インストール、設定、認証の詳しい手順については、packages/cli/README.md をご覧ください。

---

API リファレンス

インタラクティブな OpenAPI は http://localhost:8000/docs で確認できます。ルーターのソースを直接確認済みです。

GET    /health                                Liveness probe
GET    /health/ready                          Readiness (DB)

GET    /api/v1/clients                        List
POST   /api/v1/clients                        Create
GET    /api/v1/clients/{client_id}            Detail
PUT    /api/v1/clients/{client_id}            Update
DELETE /api/v1/clients/{client_id}            Delete

GET    /api/v1/invoices                       List
POST   /api/v1/invoices                       Create (manual)
GET    /api/v1/invoices/{invoice_id}          Detail
PATCH  /api/v1/invoices/{invoice_id}/status   Update status

GET    /api/v1/escalations                    Active escalations
POST   /api/v1/escalations/{invoice_id}/draft    AI-draft next escalation email (preview only)
GET    /api/v1/escalations/{invoice_id}/history  Full history

POST   /api/v1/legal/demand-letter            Generate demand letter
POST   /api/v1/legal/demand-letter/stream     Generate + stream (SSE)

GET    /api/v1/evidence/{invoice_id}          Evidence items
POST   /api/v1/evidence/{invoice_id}/upload   Manual upload
DELETE /api/v1/evidence/{item_id}             Remove

POST   /api/v1/risk/score                     AI risk score, structured JSON

GET    /api/v1/analytics/overview             Dashboard totals

---

比較

以下の freelancer-payment-protection 以外の行は、各ベンダーの公式ドキュメント／ヘルプセンターを参照し、2026年8月に確認したものです。

機能	スプレッドシート	FreshBooks	HoneyBook	HubSpot	freelancer-payment-protection
支払期限超過のリマインダー	✗	自動送信。請求書ごとに最大3回、送信タイミングを設定可能、テンプレートベース	自動送信。固定のタイミングが4種類（7日前、期日当日、2日後、以降定期的）、テンプレートベース	自動化された「Payment Reminder」ワークフロー（ルールベース）	段階ごとに AI が文面を作成し、トーンを調整して信頼度をスコア化（プレビューのみ、自動送信なし）
管轄区域を明記した法的督促状	✗	✗（記載なし）	✗（記載なし）	✗（記載なし）	AI が文面を作成。4つの管轄区域に専用テンプレートあり（CA、NY、UK、Ontario）
クライアント／請求書のリスクスコア	✗	✗（記載なし）	✗（記載なし）	Breeze Invoice Prioritization。リスク、経過期間、顧客価値に基づいて期限超過の請求書を AI が順位付けします。2026年6月時点で Revenue Hub のパブリックベータ版です。公開されている0～100のスコアや、要因ごとの説明はありません	0～100のスコア、名前付きの要因が7つ、クライアントごとに AI による詳しい説明を返します。AI が利用できない場合はヒューリスティックにフォールバックします
請求書ごとの証拠／文書の保存	✗	✗（記載なし）	✗（記載なし）	✗（記載なし）	手動アップロード、Supabase Storage を利用。ZIP エクスポートには未対応
UI での AI 生成のストリーミング	✗	✗	✗	✗	実際の SSE ストリーミング（UI のアニメーションだけでなく、ソースコードで確認済み）
ネイティブの請求書発行	✗	あり（中核機能）	あり（中核機能）	あり（Commerce/Payments）	なし。現在、請求書は API／CLI で作成します。会計ツールからの同期には対応していません
バックグラウンドジョブの自動化（同期、スケジュールされたエスカレーション）	該当なし	ネイティブ対応	ネイティブ対応	ネイティブ対応	未実装です。まだ実装されていない機能をご覧ください

率直に言えば、FreshBooks と HoneyBook は、すでに得意としているルールベースの機械的なリマインダー機能で優れています。HubSpot の2026年6月の Breeze ベータ版は、このリストでリスクスコア機能を備えた競合製品に最も近いもので、今後に注目する価値があります。管轄区域を明記した督促状を作成したり、UI に AI 生成結果をストリーミングしたりする製品はここにはありません。これこそが本プロジェクトが解決する実際のギャップです。「債権回収の完全自動化」を実現するものではありません。これらの製品も本プロジェクトも、現時点ではエンドツーエンドの完全自動化を実現していません。

---

アーキテクチャ

システム図（実際に実装されているもの）

graph TB
    subgraph "Frontend: Next.js 14"
        A[App Router Pages]
        B[TanStack Query Cache]
        C[Framer Motion UI]
        D[Supabase Auth Client]
    end

    subgraph "Backend: FastAPI, Python 3.12"
        E[FastAPI App Factory]
        F[JWT Middleware]
        G[slowapi Rate Limiter]
        H["Routers: 8 domains"]
        I[Services: business logic only]
    end

    subgraph "AI: Claude Sonnet 4.6"
        J[packages/legal_ai/client.py]
        K[Demand Letter: streaming SSE]
        L[Escalation Email: structured draft]
        M[Risk Scorer: JSON output]
    end

    subgraph "Data Layer"
        T[(Supabase PostgreSQL + RLS)]
        U[Supabase Storage]
        W[(SQLite Dev DB)]
    end

    A --> E
    D --> T
    B --> E
    E --> F --> G --> H --> I
    I --> J
    J --> K
    J --> L
    J --> M
    I --> T & U

Celery と Redis は依存関係（requirements.txt）として宣言されていますが、現時点でリポジトリにワーカーのコードはありません。apps/workers/ ディレクトリは存在せず、請求書の段階を自動的に進めるスケジュール済みジョブもありません。まだ実装されていない機能をご覧ください。

バックエンドに Node ではなく Python を採用する理由

法的文書の作成には、実際に接続されているコードパスで python-docx／WeasyPrint を使用しており、Anthropic Python SDK がリファレンス実装です。また、Python のエコシステムは、将来の紛争分析機能で契約分析ツール（NLTK、spaCy）を活用する際にも適しています。

Claude の呼び出しをすべて1つのファイルに集約する理由

packages/legal_ai/client.py（apps/api/app/services/ai_service.pyから呼び出されます）は、Anthropic SDK をインポートする唯一の場所です。モデルのバージョン、リトライ、同期 SDK と非同期 FastAPI 間の連携をここに集約しているため、モデルのアップグレードは1つのファイルを変更するだけで済みます。

フェイルファスト検証を備えた Pydantic Settings を採用する理由

settings = Settings() はインポート時に実行されます。ANTHROPIC_API_KEY が設定されていない場合、アプリは気付かれないまま機能を縮退させるのではなく、リクエストを受け付ける前に例外を発生させます。トレードオフとして、設定モデルは認識されないフィールドも厳密に拒否します。これが、以下の FAQ にある2つの .env.example の問題のうち1つの根本原因です。

データを返すすべてのコマンドでは、エージェントやスクリプトが直接解析できる構造化出力を得るための --json も指定できます。

---

MCP サーバー

freelancer-payment-protection-cli には Model Context Protocol（MCP）サーバーが付属しているため、 エージェント（Claude Desktop、Claude Code、その他の MCP クライアント）は、上記と同じコマンド （invoice list、client risk、escalation status、……）を、CLI を直接実行する代わりに ツール呼び出しとして利用できます。

インストール：

pip install "freelancer-payment-protection-cli[mcp]"

Claude Desktop の設定（claude_desktop_config.json）：

{
  "mcpServers": {
    "freelancer-payment-protection": {
      "command": "fpp-mcp"
    }
  }
}

サーバーは、指定された引数のリストを使ってインストール済みの fpp バイナリを シェルから実行し、可能な場合は出力を構造化 JSON として返す run というツールを1つ公開します。 一部のコマンドだけを選んで公開するのではなく、すべての fpp サブコマンドをこのツールから利用できます。呼び出し例： run(args=["client", "risk", "<client-id>", "--json"]) は、fpp client risk <client-id> --json をターミナルで実行したときと同じ、0～100 のリスクスコア、要因の内訳、AI による推論を返します。

---

セキュリティ

制御	実装
認証	すべての保護対象ルートで Supabase JWT を検証し、ローカルでのバイパスはありません
認可	すべてのテーブルで行レベルセキュリティを適用し、アプリケーション層ではなくデータベース層でワークスペースの分離を徹底します
シークレット	Pydantic SecretStr を使用し、必須の環境変数が欠けている場合はアプリの起動に失敗します
入力検証	すべてのエンドポイントで Pydantic v2 を使用します
レート制限	全体のデフォルトは100リクエスト/分、AI 文案作成ルートは10リクエスト/分、リスクスコアリングは30リクエスト/分です
SQL インジェクション	SQLAlchemy ORM のみを使用し、レビュー済みのルーター／サービスに生の SQL はありません
証拠へのアクセス	アップロードファイルは保存前に MIME タイプとサイズ（上限25MB）を検証します
依存関係の監査	pip-audit（バックエンド）と pnpm audit（フロントエンド）を使用し、どちらも CI で実行します
シークレットスキャン	すべてのプッシュ／PR で TruffleHog を実行します
SAST	すべての PR で CodeQL（Python + TypeScript）を実行します

---

まだ実装されていない機能

アーキテクチャ図や依存関係一覧を見ると誤解を招くため、率直に説明します。

• バックグラウンドワーカーやスケジューラーはありません。 celery と redis は requirements.txt に固定されていますが、リポジトリには apps/workers/ のコードが存在しません。請求書のエスカレーション段階を自動的に進めたり、タイマーに従って進めたりする機能はありません。
• 最低待機時間の適用機能はありません。 escalation_service.py の get_next_stage() は単純な順序検索であり、呼び出し経路のどこにも日付や経過時間の確認はありません。認証済みの呼び出し元であれば、請求書の支払期限超過からの経過時間に関係なく、次の段階のドラフトをリクエストできます。また、エンドポイントが新しい段階を請求書に書き戻すこともありません。
• FreshBooks／QuickBooks／Wave との同期機能はありません。 packages/integrations/__init__.py は空のファイルです。請求書は会計ツールから同期されるのではなく、API／CLI 経由で作成されます。
• 本番用の PDF／DOCX エクスポート機能はまだありません。 doc_gen_service.py の docstring に明記されています。開発ビルドでは、作成したレターを .txt ファイルとして保存します。本番用の python-docx／WeasyPrint の処理経路はまだ接続されていません。
• 証拠の ZIP エクスポート機能はありません。 証拠ルーターがサポートしているのは、一覧表示／アップロード／削除のみです。

これらは秘密ではありません。コードを実行すればわかることです。実際に機能する部分（AI によるドラフト作成、根拠を伴うリスクスコアリング、ストリーミング、CLI）については、形容詞ではなく具体的に上記で説明しています。

---

よくある質問

これは何ですか？FreshBooks や HoneyBook との実質的な違いは何ですか？ どちらも請求書の送信と、一定のスケジュールに沿ったクライアントへの督促に対応しています。一方、管轄区域を参照した法的な督促状の作成や、AI が生成した推論の経緯を添えたクライアントの支払いリスク評価には対応していません。このプロジェクトはその両方に対応しており、packages/legal_ai/ と apps/api/app/services/ で実際の Claude API 呼び出しを確認できます。定型テンプレートの差し替えではありません。

これはオープンソースですか？フォークしたり、自分のプロジェクトでコードを使ったりできますか？ はい。このリポジトリは MIT ライセンスです。LICENSE に記載された標準的な MIT 条件（著作権表示と許諾表示の保持）の範囲内で、フォーク、変更、自分のプロジェクトへの組み込みができます。PyPI/npm の freelancer-payment-protection-cli パッケージも、同じライセンスのもと、そのままインストールして実行できます。

CLI はどのプラットフォームに対応していますか？ Python 3.10～3.13 を搭載した Linux、macOS、Windows に対応しており、pip、uvx、または pipx からインストールできます。npm パッケージ（npm の freelancer-payment-protection-cli）は、プラットフォーム用バイナリを同梱するのではなく、実行時に uvx または pipx を呼び出す薄いラッパーです。そのため、これらのいずれかを PATH に含めておく必要があります。バックエンド／フロントエンドのスタック全体を実行するには、Python 3.12.x が必要です。現在の依存関係のバージョン固定では、3.13／3.14 はサポートされていません。

HubSpot の新しい Breeze Invoice Prioritization 機能とはどう違いますか？ Breeze（Revenue Hub、2026 年 6 月時点でパブリックベータ）は、HubSpot ユーザーの期限超過請求書をリスク、経過日数、顧客価値に基づいて順位付けします。スコアというより、並べ替え順に近いものです。fpp client risk は、要因名ごとの内訳と、クライアントごとの文章による推論を含む 0～100 のスコアを返します。HubSpot CRM の他の機能を導入せずに単独で使え、HubSpot が提供していない、管轄区域を参照した督促状の作成にも対応しています。Breeze がベータ版を終了したら、あらためて比較する価値があります。

クイックスタートの手順どおりに進めたのに、uvicorn app.main:app --reload の起動時にクラッシュしました。バグですか？ はい。配布されている apps/api/.env.example に実際の問題があります。デフォルト値のうち 2 つが Settings() の検証を通りません。フィールドの型が list[str] なので、ALLOWED_ORIGINS=http://localhost:3000 は JSON 配列（["http://localhost:3000"]）にする必要があります。また、DATABASE_URL=sqlite:///./dev.db は Settings モデルに宣言されているフィールドではないため、Extra inputs are not permitted エラーになります。.env のこの 2 行を修正するか、DATABASE_URL の行を削除してください。apps/api/app/database.py では同じ SQLite パスがすでにデフォルト設定されています。修正後、サーバーが起動します。クリーンなクローンで、ドキュメントに記載された手順を実行して確認済みです。

fpp escalation advance は実際にメールを送信したり、請求書を次の段階に進めたりしますか？ いいえ。これは /api/v1/escalations/{id}/draft を呼び出し、AI が作成したプレビューだけを返します。現在、バックエンドには段階の変更を保存したり、メールを送信したりするエンドポイントはありません。未実装の機能をご覧ください。

ANTHROPIC_API_KEY を設定していない場合はどうなりますか？ 上記の .env の 2 つの修正を適用すれば、アプリは引き続き起動します。ただし、AI 関連のルートの動作は異なります。client risk は決定論的なヒューリスティックによるスコアにフォールバックします（risk_service.py に記載）。一方、escalation advance と督促状のエンドポイントは、フォールバックなしで 503 を返します。

今日、実際のクライアント案件で使えますか？ 自分でセルフホストしたバックエンドと Supabase プロジェクトに対して CLI を使う場合は、はい。MIT ライセンスでは、実際のクライアント案件や自分の製品での使用、組み込みも認められています。詳しい条件については、ライセンスをご覧ください。

---

コントリビューション

バグ報告や機能リクエストには GitHub Issues をご利用ください。プルリクエストも歓迎します。大がかりな変更については、作業を始める前に方針を合意できるよう、まず Issue を作成してください。質問がある場合は、github.com/RudrenduPaul からお問い合わせください。

ライセンス

MIT。利用条件の詳細については、LICENSEをご覧ください。

お問い合わせ先： github.com/RudrenduPaul

---