捐款端点

捐款模块管理捐款记录、基金、支付处理、订阅以及相关的财务操作。它支持多种支付网关（Stripe、PayPal），处理一次性和定期捐款，跟踪捐款批次，并为异步支付事件提供 webhook 处理。

基础路径： /giving

捐款

基础路径：/giving/donations

方法	路径	认证	权限	描述
GET	/	JWT	Donations.View 或本人 personId	列出所有捐款记录。可用 ?batchId= 或 ?personId= 筛选
GET	/:id	JWT	Donations.View	按 ID 获取捐款记录
GET	/my	JWT	—	获取当前用户的捐款记录
GET	/summary	JWT	Donations.ViewSummary	获取捐款汇总。可用 ?startDate=&endDate=&type= 筛选。使用 type=person 可按人员维度分组
GET	/testEmail	Public	—	发送测试邮件（用于开发/调试）
POST	/	JWT	Donations.Edit	创建或更新捐款记录（批量）
DELETE	/:id	JWT	Donations.Edit	删除捐款记录

示例：按批次列出捐款记录

GET /giving/donations?batchId=abc-123
Authorization: Bearer <token>

[
  {
    "id": "don-456",
    "batchId": "abc-123",
    "personId": "per-789",
    "donationDate": "2025-03-15T00:00:00.000Z",
    "amount": 100.00,
    "method": "card"
  }
]

示例：获取捐款汇总

GET /giving/donations/summary?startDate=2025-01-01&endDate=2025-12-31
Authorization: Bearer <token>

[
  {
    "week": "2025-01-06",
    "fund": "General Fund",
    "totalAmount": 2500.00,
    "count": 15
  }
]

捐款批次

基础路径：/giving/donationbatches

继承 GenericCrudController，包含 CRUD 路由：getById、getAll、post、delete。删除操作同时会删除该批次内的所有捐款记录。

方法	路径	认证	权限	描述
GET	/	JWT	Donations.ViewSummary	列出所有捐款批次
GET	/:id	JWT	Donations.ViewSummary	按 ID 获取捐款批次
POST	/	JWT	Donations.Edit	创建或更新捐款批次
DELETE	/:id	JWT	Donations.Edit	删除某批次及其中所有捐款记录

捐赠流程

基础路径：/giving/donate

处理面向公众的捐赠流程，包括扣款、订阅、webhook 以及手续费计算。未启用任何基础 CRUD 路由；所有端点均为自定义实现。

方法	路径	认证	权限	描述
GET	/gateways/:churchId	Public	—	获取某教会可用的支付网关（仅公开密钥）
POST	/client-token	JWT	—	生成用于初始化网关的客户端令牌
POST	/create-order	JWT	—	创建支付订单（PayPal 风格的结账流程）
POST	/charge	JWT	—	处理一次性捐款扣款
POST	/subscribe	JWT	—	创建定期捐款订阅
POST	/log	Public	—	记录一笔捐款。请求体：{ donation, fundData }
POST	/webhook/:provider	Public	—	接收支付 webhook 事件（Stripe、PayPal）。需要 ?churchId=
POST	/replay-stripe-events	JWT	Donations.Edit	重放某日期范围内的 Stripe 事件。请求体：{ startDate, endDate, dryRun }
POST	/fee	Public	—	计算交易手续费。请求体：{ type, provider, gatewayId, amount, currency }。需要 ?churchId=
POST	/captcha-verify	Public	—	验证 reCAPTCHA 令牌。请求体：{ token }

示例：处理一笔捐款扣款

POST /giving/donate/charge
Authorization: Bearer <token>

{
  "provider": "stripe",
  "amount": 50.00,
  "currency": "usd",
  "person": { "id": "per-123", "email": "donor@example.com" },
  "funds": [{ "id": "fund-001", "name": "General Fund", "amount": 50.00 }],
  "church": { "name": "First Church", "subDomain": "firstchurch" }
}

{
  "id": "ch_abc123",
  "status": "succeeded",
  "provider": "stripe"
}

示例：创建定期订阅

POST /giving/donate/subscribe
Authorization: Bearer <token>

{
  "provider": "stripe",
  "amount": 100.00,
  "customerId": "cus_abc123",
  "interval": { "interval_count": 1, "interval": "month" },
  "billing_cycle_anchor": 1710460800,
  "person": { "id": "per-123", "email": "donor@example.com" },
  "funds": [{ "id": "fund-001", "name": "General Fund", "amount": 100.00 }],
  "church": { "name": "First Church", "subDomain": "firstchurch" }
}

{
  "id": "sub_xyz789",
  "status": "active",
  "provider": "stripe"
}

基金

基础路径：/giving/funds

继承 GenericCrudController，包含 CRUD 路由：getById、getAll、post、delete。view 权限为 null（查看基金无需权限）。

方法	路径	认证	权限	描述
GET	/	JWT	—	列出所有基金
GET	/:id	JWT	—	按 ID 获取基金
GET	/churchId/:churchId	Public	—	获取某教会的所有基金（公开）
GET	/public/:churchId/:fundId/total?startDate=&endDate=	Public	—	获取某基金的捐款总额：{ fundId, totalAmount, donationCount }。为网站构建器的 campaignProgress 元素提供支持
POST	/	JWT	Donations.Edit	创建或更新基金
DELETE	/:id	JWT	Donations.Edit	删除基金

基金捐款分配

基础路径：/giving/funddonations

跟踪各笔捐款在不同基金之间的分配情况。未启用任何基础 CRUD 路由；所有端点均为自定义实现。

方法	路径	认证	权限	描述
GET	/	JWT	Donations.View	列出基金捐款分配记录。可用 ?donationId=、?personId=、?fundId= 或 ?fundName= 筛选。也可加 ?startDate=&endDate= 按日期筛选
GET	/:id	JWT	Donations.View	按 ID 获取基金捐款分配记录
GET	/my	JWT	—	获取当前用户的基金捐款分配记录
POST	/	JWT	Donations.Edit	创建或更新基金捐款分配记录（批量）
DELETE	/:id	JWT	Donations.Edit	删除基金捐款分配记录

网关

基础路径：/giving/gateways

管理支付网关配置（Stripe、PayPal 等）。未启用任何基础 CRUD 路由；所有端点均为自定义实现。网关密钥在静态存储时会被加密。

方法	路径	认证	权限	描述
GET	/	JWT	—	列出该教会的所有网关
GET	/:id	JWT	Settings.Edit	按 ID 获取网关
GET	/churchId/:churchId	Public	—	获取某教会的网关（仅公开密钥）
GET	/configured/:churchId	Public	—	检查某教会是否已配置支付网关
POST	/	JWT	Settings.Edit	创建或更新网关（加密密钥、配置 webhook 和产品）
PATCH	/:id	JWT	Settings.Edit	部分更新网关信息
DELETE	/:id	JWT	Settings.Edit	删除网关（同时移除其 webhook）

示例：检查网关配置状态

GET /giving/gateways/configured/church-123

{
  "configured": true
}

客户

基础路径：/giving/customers

继承 GenericCrudController，包含 CRUD 路由：getAll、delete。将人员与其在支付网关中的客户记录相关联。

方法	路径	认证	权限	描述
GET	/	JWT	Donations.ViewSummary	列出所有客户
GET	/:id	JWT	Donations.ViewSummary 或本人记录	按 ID 获取客户
GET	/:id/subscriptions	JWT	Donations.ViewSummary 或本人记录	获取某客户在网关中的订阅信息
DELETE	/:id	JWT	Donations.Edit	删除客户

订阅

基础路径：/giving/subscriptions

管理定期捐款订阅。未启用任何基础 CRUD 路由；所有端点均为自定义实现。

方法	路径	认证	权限	描述
GET	/	JWT	Donations.ViewSummary	列出所有订阅
GET	/:id	JWT	Donations.ViewSummary	按 ID 获取订阅
POST	/	JWT	Donations.Edit 或本人订阅	在支付网关中更新订阅
DELETE	/:id	JWT	Donations.Edit 或本人订阅	取消订阅并从数据库中删除。请求体：{ provider, reason }

订阅基金分配

基础路径：/giving/subscriptionfunds

跟踪定期订阅的基金分配情况。未启用任何基础 CRUD 路由；所有端点均为自定义实现。

方法	路径	认证	权限	描述
GET	/	JWT	Donations.View 或本人订阅	列出订阅基金分配记录。可用 ?subscriptionId= 筛选
GET	/:id	JWT	Donations.ViewSummary	按 ID 获取订阅基金分配记录
DELETE	/:id	JWT	Donations.Edit	删除订阅基金分配记录
DELETE	/subscription/:id	JWT	Donations.Edit 或本人订阅	删除某订阅的所有基金分配记录

支付方式

基础路径：/giving/paymentmethods

通过支付网关 API 管理已保存的支付方式（银行卡、银行账户）。未启用任何基础 CRUD 路由；所有端点均为自定义实现。

方法	路径	认证	权限	描述
GET	/personid/:id	JWT	Donations.View 或本人 personId	获取某人已保存的所有支付方式（银行卡、银行账户）
POST	/addcard	JWT	—	关联一张银行卡作为支付方式。请求体：{ id, personId, customerId, email, name, churchId, provider }
POST	/updatecard	JWT	Donations.Edit 或本人 personId	更新银行卡信息。请求体：{ personId, paymentMethodId, cardData, provider }
POST	/ach-setup-intent	JWT	Donations.Edit 或本人 personId	创建用于关联银行账户的 Stripe ACH SetupIntent。请求体：{ personId, customerId, email, name, churchId }
POST	/ach-setup-intent-anon	Public	—	为访客捐款创建匿名 ACH SetupIntent。请求体：{ email, name, churchId, gatewayId }
POST	/addbankaccount	JWT	Donations.Edit 或本人 personId	通过令牌添加银行账户（已弃用；请改用 ach-setup-intent）。请求体：{ id, personId, customerId, email, name }
POST	/updatebank	JWT	Donations.Edit 或本人 personId	更新银行账户信息。请求体：{ paymentMethodId, personId, bankData, customerId }
POST	/verifybank	JWT	Donations.Edit 或本人客户	通过小额验证存款验证银行账户。请求体：{ paymentMethodId, customerId, amountData }
DELETE	/:id/:customerid	JWT	Donations.Edit 或本人客户	删除某个支付方式（银行卡或银行账户）

事件日志

基础路径：/giving/eventLog

继承 GenericCrudController，包含 CRUD 路由：getById、getAll、post、delete。用于跟踪支付网关的 webhook 事件，以便审计和去重。

方法	路径	认证	权限	描述
GET	/	JWT	Donations.ViewSummary	列出所有事件日志
GET	/:id	JWT	Donations.ViewSummary	按 ID 获取事件日志
GET	/type/:type	JWT	Donations.ViewSummary	按事件类型筛选事件日志
POST	/	JWT	Donations.Edit	创建或更新事件日志
DELETE	/:id	JWT	Donations.Edit	删除事件日志

相关页面

• 成员管理端点 — 人员、教会、小组、角色和权限
• 认证与权限 — 登录流程、JWT、OAuth、权限模型
• 模块结构 — 代码组织模式