InvoiceFlow

InvoiceFlow 是一款面向自由职业者的发票应用。管理客户、创建品牌化发票和报价单、分享公开付款链接、通过 Stripe Connect 收款，并自动发送逾期提醒。

MCP 服务（Agent）

InvoiceFlow 附带一个无依赖的 Model Context Protocol 服务，因此 Claude Desktop、Cursor 或任何 MCP 宿主中的 Agent 都可以创建发票 并获取可付款的 Stripe 链接，而无需阅读 REST 文档。

{
  "mcpServers": {
    "invoiceflow": {
      "command": "node",
      "args": ["/abs/path/invoiceflow-mcp.mjs"],
      "env": { "INVOICEFLOW_API_KEY": "ifk_..." }
    }
  }
}

从 https://invoiceflow-ten-azure.vercel.app/sdk/invoiceflow-mcp.mjs 下载该服务。

工具： whoami、create_client、list_clients、create_invoice、 list_invoices、get_invoice、share_invoice。

这些刻意省略的功能正是设计的一部分。 没有工具可以发送电子邮件、删除、退款或付款。 创建发票只会增加记录，人可以撤销；但如果 Agent 每次重试都给客户发邮件，就无法挽回。 金额以整数分为单位，字段名为 unitPrice；非整数会被拒绝并附上说明，而不会四舍五入， 因为 25.5 悄悄表示 25 分，是最可能影响真实客户的缺陷。

无需账户，亲自验证：

curl -sO https://invoiceflow-ten-azure.vercel.app/sdk/invoiceflow-mcp.mjs
curl -sO https://invoiceflow-ten-azure.vercel.app/sdk/invoiceflow-client.mjs
curl -sO https://invoiceflow-ten-azure.vercel.app/sdk/test-mcp.mjs
node test-mcp.mjs     # 14 passed, 0 failed — no key, no network

---

技术栈

• Node.js 22 和 pnpm 10.34.9（package.json 中的 packageManager）
• Next.js 15 App Router、React 18、TypeScript、Tailwind CSS 和 Framer Motion
• NextAuth v5，使用 Google OAuth 和 JWT 会话
• Prisma 5 和 PostgreSQL 16；本地使用 Docker Compose，部署使用 Neon
• Stripe Connect Express 和 Checkout；Resend 和 React Email
• Vitest 单元测试和 PostgreSQL 集成测试；ESLint 和 GitHub Actions

已实现的工作流

区域	行为
客户与发票	按所有者范围管理、行项目、百分比税率、草稿编辑和受控状态变更
发票发送	“保存并发送”会调用邮件端点；邮件受理后使用稳定的公开链接，发送失败则保留一份已保存的草稿，并支持主动重新发送
公开发票	品牌化视图、清晰易读的多页 PDF 导出（包含已保存的备注和正确的税额明细）、不可猜测的分享令牌以及 noindex 元数据
在线支付	含税总额、复用未完成的 Checkout 会话、带签名的 Webhook 对账
提醒	针对已发送和逾期发票的递进式邮件提醒
定期发票	在一个数据库事务中定时生成草稿并推进日程
报价单	创建和管理报价单；将报价单转换为发票一次
报告与导出	收入、未结余额、账龄、客户报告和 CSV 导出
商家资料	名称、地址、Logo、强调色和发票编号前缀

每个账户都可享受 14 天免费试用；之后 InvoiceFlow Pro 通过 Stripe Checkout 收费，每月 US$9。可在 Stripe 账单门户中更换银行卡或取消订阅。试用期结束后，创建和发送发票需要有效订阅；现有记录、PDF、导出文件和客户付款仍可使用。发票款项会汇入每位用户自己的 Stripe 账户，与其 InvoiceFlow 订阅分开。上线规格说明记录了相关决策。

界面与设计指南

公开网站、Google 登录和工作区采用暖白、深墨色与常青色的视觉系统，并提供交互式示例发票、紧凑表格和便于键盘操作的移动导航。报告会分别保留各币种的总额。创建发票和报价单草稿时可创建客户。

修改界面前，请阅读 PRODUCT.md 和 DESIGN.md。所需的 Emil Kowalski、Impeccable、Taste 和 frontend-design 技能已安装在本地的 .agents/skills 下，其中包含上游修订版本和许可证。设计评审记录了渲染检查结果和有意采用的权衡。

本地开发

请先安装 Node.js 22 和指定版本的 pnpm。保留现有的本地配置，不要替换它。

pnpm install --frozen-lockfile
test -e .env || cp .env.example .env
# Configure .env before continuing.
docker compose up -d --wait
pnpm run db:generate
pnpm run db:deploy
pnpm run dev

DATABASE_URL 和 DATABASE_URL_UNPOOLED 均使用 .env.example 中的本地 PostgreSQL URL。生成 AUTH_SECRET，添加 Google OAuth 凭据，并将 http://localhost:3000 用作 NEXTAUTH_URL 和 NEXT_PUBLIC_APP_URL。在 Google OAuth 客户端中注册 http://localhost:3000/api/auth/callback/google。

在取得有效凭据前，请将可选的 Stripe 和 Resend 密钥留空；示例字符串只是占位符。未配置的集成会返回不可用响应。Google 登录和完整的发送／付款工作流需要配置相应的实际服务。

pnpm run db:deploy 会将已提交的迁移应用到新的开发数据库。如果现有数据库是使用 prisma db push 创建的，请先按照基线操作流程操作，再应用迁移。切勿使用 db push 或 migrate reset 部署生产环境的架构变更。

Compose 数据库使用持久化命名卷。docker compose down 会停止数据库，但不会删除该卷。

可选演示数据：

# Only against a disposable development database.
pnpm run db:seed

种子操作会替换由 SEED_DEMO_EMAIL（默认为 [email protected]）选中的账户及其相关数据。请勿将真实客户账户或生产数据库作为目标。

PDF 导出

PDF 下载采用经过测量的 A4 布局，分别显示发件人和收件人信息、开具/到期日期、货币、状态、逐项费用、税额和总额。较长的记录会分页，并重复显示表格标题。已保存的发票备注会显示在“备注和付款说明”下方；可在此处填写付款详情和账单周期。PDF 反映已保存的发票金额，不会更改付款状态或数据。

查看合成 PDF 示例和 布局审查。无需访问数据库/提供商即可生成简短、普通和较长的审查样例：

pnpm exec tsx scripts/preview-invoice-pdf.ts

配置

变量	用途
DATABASE_URL	Prisma 运行时 PostgreSQL 连接；部署时使用 Neon 的连接池 URL
DATABASE_URL_UNPOOLED	用于 Prisma 迁移的直连数据库连接
AUTH_SECRET	稳定且私密的 NextAuth 签名/加密密钥
AUTH_GOOGLE_ID, AUTH_GOOGLE_SECRET	Google Web OAuth 客户端凭据
NEXTAUTH_URL	规范的身份验证来源；生产环境中使用 HTTPS
AUTH_TRUST_HOST	仅在受信任的部署代理（例如 Vercel）后方设置为 true
NEXT_PUBLIC_APP_URL	发票、付款和邮件 URL 使用的规范公共 HTTPS 来源
STRIPE_SECRET_KEY	用于 Connect 和 Checkout 的 Stripe 平台 API 密钥
STRIPE_WEBHOOK_SECRET	此部署的关联账户 webhook 端点的签名密钥
STRIPE_CONNECT_COUNTRY	新建账户所用的受支持 Connect 国家/地区；默认为 US
RESEND_API_KEY, RESEND_FROM_EMAIL	邮件 API 密钥，以及已验证 Resend 域名上的发件人地址
FREELANCER_NOTIFY_EMAIL	仅当发票所有者没有电子邮件地址时使用的备用地址
CRON_SECRET	用于计划发票生成和提醒的 Bearer 密钥
SEED_DEMO_EMAIL	破坏性演示种子脚本的目标临时账户

示例配置中保留了 NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY；当前托管的 Checkout 重定向不会使用浏览器端 Stripe SDK。INNGEST_* 变量也未使用。

请将密钥保存在已忽略的本地环境文件中，或保存在托管服务提供商的安全设置中。预览和生产部署应使用不同的数据库和服务密钥。

验证

pnpm test
pnpm run lint
NEXT_PUBLIC_APP_URL=https://invoiceflow.example.test pnpm run build
pnpm run typecheck
# After building, against the disposable local test DB:
pnpm run test:browser
pnpm audit --prod --audit-level high

对于这些本地浏览器检查，构建会使用上文所述的 HTTPS 测试来源；Vercel 发布版本使用实际配置的生产来源。Next.js 会在构建期间嵌入 NEXT_PUBLIC_APP_URL。

构建会生成 Prisma Client、编译所有路由并生成生产应用。生产环境的 Vercel 构建会先通过受保护的发布步骤验证数据库并执行迁移；本地和预览构建则需要显式准备数据库。配置的 next/font 加载器需要访问 Google Fonts。Prisma 下载必须保留 TLS 和校验和验证。

集成测试使用名为 invoiceflow_test 的独立临时本地数据库。创建一次即可：

docker compose exec -T db createdb -U postgres invoiceflow_test

然后运行：

export DATABASE_URL='postgresql://postgres:postgres@localhost:5432/invoiceflow_test?schema=public'
export DATABASE_URL_UNPOOLED="$DATABASE_URL"
pnpm run db:deploy
pnpm run test:integration

请在与开发服务器不同的 shell 中运行这些导出命令。测试套件会拒绝远程数据库和其他数据库名称。它使用真实的 PostgreSQL 事务和签名的 Stripe 测试数据，并对外部 Stripe/Resend 请求进行模拟。测试涵盖发票总额、公开链接、Checkout 复用、webhook 验证和重试、并发编号/转换，以及定期事务回滚。它无法证明实时 OAuth、付款或邮件凭据有效。

GitHub Actions 使用 PostgreSQL 16 和 Node.js 22 运行冻结安装、Prisma 生成、迁移、lint、单元/集成测试、生产构建、Chromium 浏览器工作流、类型检查和生产依赖审计。

部署

迁移处理、服务配置、计划任务和必要的测试模式发布冒烟测试，请参阅 Vercel 和 Neon 发布指南。本地检查通过并不代表已验证部署的应用。

定时任务

两个任务都使用 GET，并要求提供 Authorization: Bearer <CRON_SECRET>：

• /api/cron/generate-recurring 会创建到期的草稿发票并推进其计划。
• /api/cron/chase-invoices 会发送到期提醒。

vercel.json 会安排每天 00:00 UTC 生成发票，并于 09:00 UTC 发送提醒。配置 CRON_SECRET 后，Vercel 会发送 bearer 请求头。启用更大工作负载前，请检查套餐的调度和函数执行时长限制。

当前产品边界

• Online Checkout 支持小数位为两位的货币，以及处于已验证金额限额内的正数总额。它会收取含税发票总额；公开发票会提供明细。
• 控制面板和报告会显示所选货币的金额总额。它们不会兑换货币，也不会提供合并后的外汇总额。最近的发票会显示各自的货币。
• 公开支付的 IP 限流在内存中实现，因此在多个 Vercel 实例之间只能尽力而为。更大规模的部署需要使用分布式限流器。
• 当前的支付确认邮件会发送给发票所有者，而非通过单独的客户收据工作流发送。
• 定期任务会创建草稿；不会自动发送草稿，也不会向已存储的支付方式收费。
• 退款、发票部分付款和按发票进行会计处理需要单独的产品开发。InvoiceFlow Pro 只有一个月度套餐；没有年度套餐、优惠券或团队席位。

架构

                           ┌─────────────────────────────┐
                           │      Client / Browser       │
                           └──────────────┬──────────────┘
                                          │
                                          ▼
                         ┌─────────────────────────────────┐
                         │   Next.js Middleware (Auth)     │
                         └──────────────┬──────────────────┘
                                        │
        ┌───────────────────────────────┼───────────────────────────────┐
        ▼                               ▼                               ▼
 ┌──────────────┐             ┌──────────────────┐            ┌──────────────────┐
 │ Landing Page │             │ Dashboard (App)  │            │  Public Invoice  │
 │     `/`      │             │  `/(dashboard)`  │            │   `/i/[token]`   │
 └──────────────┘             └─────────┬────────┘            └────────┬─────────┘
                                        │                              │
                                        ▼                              ▼
                         ┌─────────────────────────────────────────────────┐
                         │               API Routes & Crons                │
                         │   • /api/invoices        • /api/estimates       │
                         │   • /api/clients         • /api/cron/*          │
                         │   • /api/i/[token]/pay   • /api/webhooks/stripe │
                         └──────────────────────┬──────────────────────────┘
                                                │
         ┌──────────────────────────────────────┼──────────────────────────────────────┐
         ▼                                      ▼                                      ▼
┌──────────────────┐                  ┌──────────────────┐                   ┌──────────────────┐
│  Neon Postgres   │                  │  Stripe Connect  │                   │      Resend      │
│  (Prisma Engine) │                  │ (Checkout & Web) │                   │  (React Emails)  │
└──────────────────┘                  └──────────────────┘                   └──────────────────┘

---

目录结构

prisma/             Schema, migrations and disposable demo seed
src/app/            Marketing, authenticated app, public invoices and API routes
src/lib/            Billing, auth, money, reporting, validation and integrations
src/emails/         React Email templates
src/components/     UI, reports and marketing components
integration/        PostgreSQL-backed billing regression tests
.github/workflows/  CI

浏览器工作流测试

运行 pnpm run build 后，执行 pnpm run test:browser；DATABASE_URL 和 DATABASE_URL_UNPOOLED 应指向一次性本地 invoiceflow_test 数据库。系统没有可用的 Chromium 时，请使用 pnpm exec playwright install chromium 安装。浏览器测试会在 3100 端口启动生产服务器，使用隔离的测试账户和本地签名的会话，并测试 实际页面、API 请求和数据库写入。设计检查会在桌面端（1440px）、平板端（768px）和手机端（390px）宽度下覆盖 13 条路由， 包括公开发票、发票/估算单详情、键盘交互、减少动态效果和移动端退出登录。PDF 浏览器测试还会测试“下载 PDF”按钮、解析 导出的值和备注，并拒绝跨账户或未经身份验证的下载。测试不会完成 Google OAuth 流程，也不会发送真实邮件/付款。提供方的 HTTP 响应来自受保护的本地 测试夹具，仅加载到测试服务器中。这些夹具会测试实际的 Resend/Stripe SDK 请求，同时阻止未匹配的外部请求。浏览器 检查涵盖“保存并发送”、提供方拒绝和重试、显式重新发送、已签发的发票、Stripe 就绪状态核对以及 Checkout 重定向。 有关生产环境设置，以及邮件被接受和送达收件箱之间的区别，请参阅发送与付款检查。