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

这会安装 fpp，它是下方 FastAPI 后端的类型化命令行客户端（发票、升级处理、客户风险评分；每个数据命令都支持 --json）。它会连接到你自行运行的 freelancer-payment-protection API 实例。请参阅在本地运行完整技术栈来启动一个实例，或者将 FPP_API_URL 指向一个已在运行的实例。

目录

• 项目简介
• 功能
• 在本地运行完整技术栈
• 命令行界面
• API 参考
• 对比
• 架构
• MCP 服务
• 安全
• 尚未实现的功能
• 常见问题
• 贡献
• 许可证

---

项目简介

FreshBooks 和 HoneyBook 到“发票已发送”为止。客户迟迟没有回应时，两者都不会帮你起草该说什么；而且在你开始工作之前，两者都不会评估客户不付款的风险。本项目是一个由 Claude 提供支持的 FastAPI + Next.js 应用，专注做好两件事：为逾期发票起草符合相应阶段的升级处理邮件，或引用司法管辖区相关依据的催款函；以及为客户的付款风险打 0–100 分，并提供完整的因素明细。这两项功能都会生成 AI 编写的置信度／推理过程记录，供人工审核后再发送任何内容。

它不是一套设置后便无需管理的自动化系统。目前没有后台调度器来强制执行各阶段之间的等待时间，也没有与 FreshBooks／QuickBooks／Wave 的实时同步。请参阅尚未实现的功能，了解架构图与实际接入功能之间的差距。已实现的功能包括：AI 起草、风险评分、证据库，以及可将这三项功能编入脚本的 CLI。

---

功能

能力	实际实现情况
AI 升级草拟	五个有序阶段（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 会根据你提供的司法管辖区字符串起草信件。四个司法管辖区（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 数组。提示词要求 Claude 权衡 7 个指定因素（行业付款习惯、付款期限、历史延迟、合同质量、发票金额、地理位置、未结余额占比），并返回其推理过程。如果 Claude 调用失败，risk_service.py 会回退到确定性启发式评分，而不是返回错误。速率限制为每分钟 30 次请求。
证据库	可手动上传 PDF/PNG/JPEG/.eml/纯文本文件（上限为 25MB），可按发票列出和删除；生产环境中由 Supabase Storage 提供支持。目前没有拖放自动采集功能，也没有 ZIP 导出端点。上传一次处理一个文件，通过 POST /api/v1/evidence/{invoice_id}/upload 完成。
CLI（fpp）	每个返回数据的命令都支持 --json。通过 Supabase 自己的密码授权端点持久登录，凭据缓存到 ~/.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 草拟路由每分钟 10 次、风险评分每分钟 30 次、全局每分钟 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 时，一个锁定的后端依赖会导致 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，并且应用 apps/api/.env 中上述两处修正后，uvicorn app.main:app 可正常启动并提供 /health 和 /health/ready 服务。

服务	URL
仪表盘	http://localhost:3000
API + OpenAPI 文档	http://localhost:8000/docs

登录网页仪表盘需要一个真实的 Supabase 项目（免费套餐即可）。apps/api/app/middleware/auth.py 会验证 Supabase 签发的 JWT，不提供本地绕过方式。无需 Supabase 项目也可以通过 API/CLI 完整访问种子数据。AI 功能（催款函、风险评分、升级草拟）需要在 apps/api/.env 中设置真实的 ANTHROPIC_API_KEY；若未设置，风险评分会回退到启发式评分，另外两个 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/ 目录，也没有会自动推进发票阶段的定时作业。请参阅尚未实现的功能。

后端为何选择 Python，而非 Node

法律文档起草在已接通的代码路径中使用 python-docx/WeasyPrint，而 Anthropic Python SDK 是参考实现。未来若要添加争议分析功能，合同分析工具（NLTK、spaCy）也会使用 Python 生态系统中的相关技术。

为什么将所有 Claude 调用集中在一个文件中

packages/legal_ai/client.py（由 apps/api/app/services/ai_service.py 调用）是唯一导入 Anthropic SDK 的位置。模型版本、重试逻辑以及同步 SDK 与异步 FastAPI 之间的桥接都集中在这里，因此升级模型只需修改一个文件。

为什么使用 Pydantic Settings 并在验证失败时立即报错

settings = Settings() 会在导入时运行。如果缺少 ANTHROPIC_API_KEY，应用会在处理请求前报错，而不是悄无声息地降低功能。代价是：设置模型也会严格检查无法识别的字段，这是下方 FAQ 中两个 .env.example 问题之一的根本原因。

每个返回数据的命令也都支持 --json，可生成 Agent 或脚本能够直接解析的结构化输出：

---

MCP 服务

freelancer-payment-protection-cli 附带一个模型上下文协议（MCP）服务，因此 Agent（Claude Desktop、Claude Code 或任何其他 MCP 客户端）可以将上述相同命令（invoice list、client risk、escalation status 等）作为工具调用，而不必直接通过 Shell 调用 CLI。

安装：

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

Claude Desktop 配置（claude_desktop_config.json）：

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

该服务公开了一个名为 run 的工具，它会使用给定的参数列表调用已安装的 fpp 二进制文件，并在可能时以结构化 JSON 的形式返回输出——每个 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 的文档字符串说得很清楚：开发构建会将起草好的信件保存为 .txt 文件；python-docx/WeasyPrint 正式版流程尚未接通。
• 没有证据 ZIP 导出功能。 证据路由器仅支持列出、上传和删除。

这些都不是秘密。运行代码就能看到实际情况。真正已实现的部分（AI 起草、附带推理的风险评分、流式传输、CLI）已在上文具体说明，而非只用形容词带过。

---

常见问题

这是什么？与 FreshBooks 或 HoneyBook 相比，真正的差异化在哪里？ 这两款产品都能发送发票，并按固定时间表提醒客户。但它们都无法起草援引司法管辖区相关法律的正式催款函，也无法通过 AI 生成的推理轨迹评估客户的付款风险。本项目两者都能做到，其背后是真正的 Claude API 调用，你可以在 packages/legal_ai/ 和 apps/api/app/services/ 中查看，而不是简单替换预制模板。

这是开源项目吗？我可以分叉它，或在自己的项目中使用代码吗？ 可以。该代码库采用 MIT 许可证：你可以分叉、修改代码，或将代码嵌入自己的项目，但须遵守 LICENSE 中的标准 MIT 条款（保留版权和许可声明）。PyPI/npm 上的 freelancer-payment-protection-cli 包可在相同许可证下直接安装和运行。

CLI 支持哪些平台？ 支持 Linux、macOS 或 Windows 上的 Python 3.10–3.13，可通过 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 中确实存在一个问题。其中两个默认值无法通过 Settings() 的验证：ALLOWED_ORIGINS=http://localhost:3000 必须写成 JSON 数组（["http://localhost:3000"]），因为该字段的类型是 list[str]；而 DATABASE_URL=sqlite:///./dev.db 并非 Settings 模型声明的字段，因此会触发 Extra inputs are not permitted 错误。修正 .env 中的这两行即可（也可以直接删除 DATABASE_URL 这一行；apps/api/app/database.py 已单独将默认值设为同一 SQLite 路径），之后服务器便能启动。已在干净克隆的代码库中按文档步骤验证。

fpp escalation advance 真的会发送邮件或推进发票状态吗？ 不会。它调用 /api/v1/escalations/{id}/draft，该接口只会返回由 AI 起草的预览。目前后端没有任何接口能保存阶段变更或发送邮件。请参阅尚未实现的功能。

如果我没有设置 ANTHROPIC_API_KEY，会发生什么？ 应用在应用上述两项 .env 修复后仍能启动，但 AI 路由的行为会有所不同：client risk 会回退到确定性启发式评分（详见 risk_service.py），而 escalation advance 和催款函接口会返回 503，且没有回退方案。

我现在可以将它用于真实的客户项目吗？ 如果通过 CLI 使用你自己的可自托管后端和 Supabase 项目，可以。MIT 许可证也允许你将其用于真实的客户项目，或将其嵌入自己的产品；具体条款请参阅许可证。

---

参与贡献

欢迎通过 GitHub Issues 提交 Bug 报告和功能请求，也欢迎提交拉取请求。对于任何较大的改动，请先创建 Issue，以便在投入工作前就方案达成一致。如有疑问，请通过 github.com/RudrenduPaul 联系。

许可证

MIT。完整条款请参阅 LICENSE。

联系：github.com/RudrenduPaul

---