如何在Firebase+Stripe中为一次性支付（payment模式）创建stripeRole？

firestore-stripe-payments扩展确实没有为一次性支付自动添加自定义声明的功能——这是扩展设计上的差异，订阅场景的stripeRole是专门为 recurring 支付做的适配，一次性支付需要手动实现权限标识的同步。

下面是两种可行的实现方案：

方案一：通过Cloud Functions自动添加/移除自定义声明 #

适合需要在Firebase安全规则中使用权限标识的场景（比如限制付费内容的读写），步骤如下：

1. 确认firestore-stripe-payments扩展已正确配置，Stripe的支付记录会同步到Firestore的payments集合
2. 创建两个Cloud Functions，分别监听支付成功和退款事件，同步自定义声明：

const functions = require("firebase-functions");
const admin = require("firebase-admin");
admin.initializeApp();

// 支付成功时，为用户添加终身访问权限的自定义声明
exports.addLifetimeAccessClaim = functions.firestore
  .document("payments/{paymentId}")
  .onCreate(async (snap) => {
    const payment = snap.data();
    // 过滤出成功的一次性支付
    if (payment.type === "one_time" && payment.status === "succeeded") {
      const uid = payment.uid;
      // 设置自定义声明，可自定义键名（比如和订阅统一用stripeRole）
      await admin.auth().setCustomUserClaims(uid, {
        stripeRole: "lifetime-member",
        hasLifetimeAccess: true
      });
      // 可选：在用户文档中记录购买信息，方便前端查询
      await admin.firestore().collection("users").doc(uid).update({
        hasLifetimeAccess: true,
        purchaseTimestamp: admin.firestore.FieldValue.serverTimestamp()
      });
    }
  });

// 退款完成时，移除用户的终身访问权限声明
exports.removeLifetimeAccessClaim = functions.firestore
  .document("payments/{paymentId}")
  .onUpdate(async (change) => {
    const oldPayment = change.before.data();
    const newPayment = change.after.data();
    // 过滤出已退款的一次性支付
    if (oldPayment.type === "one_time" && newPayment.status === "refunded") {
      const uid = newPayment.uid;
      // 移除对应声明（设为null会删除该键）
      await admin.auth().setCustomUserClaims(uid, {
        stripeRole: null,
        hasLifetimeAccess: null
      });
      await admin.firestore().collection("users").doc(uid).update({
        hasLifetimeAccess: false,
        refundTimestamp: admin.firestore.FieldValue.serverTimestamp()
      });
    }
  });

3. 部署函数后，用户完成一次性支付时，自定义声明会自动添加；退款时自动移除。注意：用户需要重新登录才能获取到更新后的声明。

方案二：前端直接查询Firestore支付记录 #

如果不需要在安全规则中使用权限，仅需前端UI判断是否显示付费内容，可以直接查询payments集合：

// 前端检查当前用户是否有成功的一次性支付记录
async function hasLifetimeAccess() {
  const currentUser = firebase.auth().currentUser;
  if (!currentUser) return false;

  const paymentsQuery = firebase.firestore()
    .collection("payments")
    .where("uid", "==", currentUser.uid)
    .where("type", "==", "one_time")
    .where("status", "==", "succeeded");

  const snapshot = await paymentsQuery.get();
  return !snapshot.empty;
}

这种方法不需要额外的函数，但无法在安全规则中使用（安全规则不能跨集合查询），适合对权限控制要求不高的场景。

注意事项 #

• 确保payments集合中的uid字段正确关联到Firebase用户UID，firestore-stripe-payments扩展默认会自动关联，但需确认产品设置中没有配置错误
• 必须处理退款、争议退款的场景，避免用户退款后仍能访问付费内容
• 自定义声明更新后，前端可以通过onIdTokenChanged监听用户身份令牌变化，自动刷新权限状态

内容的提问来源于stack exchange，提问作者vdegenne