> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 管理消费能力

一旦银行账户已链接（参见 *链接 Plaid 银行账户*），你可以读取其余额和消费能力，并在需要更实时的读数时触发实时余额刷新。

## 消费能力含义

**消费能力** 是用户当前可以从已链接银行账户中支出的金额。它基于该账户最近一次已知余额，减去尚未完全结算的近期 ACH 流出。当用户从账户中支出时，这些金额会被预留大约三个工作日，直到清算后才不再计入消费能力。（确切的清算窗口由各银行设置，可能更短。）

Fluz 会自动保持每个已链接账户的存储余额为最新。当你需要更当前的读数时——例如用户刚把资金转入或转出其银行账户之后——请请求一次**实时刷新**（有频率限制；见下文）。刷新余额会更新基于余额计算的消费能力数值。

## Auth

使用包含 `MANAGE_PAYMENT` 的 Fluz 用户 Bearer 访问令牌调用 `/api/v1/graphql`。这些字段不允许使用 Basic auth。

```http theme={null}
Authorization: Bearer <fluz-user-access-token>
```

## 获取单个银行账户的消费能力

```graphql theme={null}
query GetPlaidBankAccountSpendPower($input: PlaidBankAccountInput!) {
  getPlaidBankAccountSpendPower(input: $input) {
    bankAccountId
    spendPower
    availableSpendPower
    lastRecordedBalance
    pendingTransactions
    updatedAt
  }
}
```

```json theme={null}
{
  "input": {
    "bankAccountId": "bank-account-id"
  }
}
```

**响应字段**

| 字段                    | 描述                                                                 |
| --------------------- | ------------------------------------------------------------------ |
| `lastRecordedBalance` | 该账户最近一次已知的银行余额。                                                    |
| `pendingTransactions` | 近期 ACH 流出（大约过去三个工作日的借记），尚未结算且仍然占用余额。                               |
| `availableSpendPower` | 用户此刻可支出的金额，基于最新余额减去待处理金额得出。进行实时余额刷新后会立即变化。                         |
| `spendPower`          | 该账户经过决策的消费能力数值。其更新频率可能比余额慢，因此在刷新后可能会与 `availableSpendPower` 短暂不一致。 |
| `updatedAt`           | 上次计算该数值的时间。                                                        |

## 获取最新存储的余额

针对单个银行账户：

```graphql theme={null}
query GetPlaidBankAccountBalance($input: PlaidBankAccountInput!) {
  getPlaidBankAccountBalance(input: $input) {
    platformItemId
    bankInstitutionAuthId
    bankAccountId
    amount
    current
    source
    trigger
    startedAt
  }
}
```

```json theme={null}
{
  "input": {
    "bankAccountId": "bank-account-id"
  }
}
```

针对该用户所有已连接账户：

```graphql theme={null}
query GetPlaidBankBalances($input: PlaidBankBalanceFilterInput) {
  getPlaidBankBalances(input: $input) {
    platformItemId
    bankInstitutionAuthId
    bankAccountId
    amount
    current
    source
    trigger
    startedAt
  }
}
```

## 实时刷新单个账户

为单个银行账户请求一次受频率限制的实时余额刷新。这将从 Plaid 拉取最新余额，并更新基于余额计算的消费能力。

```graphql theme={null}
mutation RefreshPlaidBankAccountBalance($input: PlaidBankAccountInput!) {
  refreshPlaidBankAccountBalance(input: $input) {
    status
    balances {
      bankAccountId
      amount
      current
      source
      trigger
      startedAt
    }
  }
}
```

```json theme={null}
{
  "input": {
    "bankAccountId": "bank-account-id"
  }
}
```

### 刷新频率限制

为控制成本，实时刷新按**每个 Plaid 机构**进行频率限制：每小时一次实时刷新、每天六次实时刷新。在限制窗口内发起的刷新不会再次调用 Plaid——它会返回最新的存储余额，因此调用仍会成功并返回数据。请设计你的 UI，使其不要总是假设返回的余额一定是全新的实时读数。

## 刷新所有连接（缓存）

为已认证账户请求对所有已连接的 Plaid 银行数据进行缓存刷新。

```graphql theme={null}
mutation RefreshPlaidBankConnections {
  refreshPlaidBankConnections {
    status
    balances {
      bankAccountId
      amount
      current
    }
    verifyMembers {
      platformItemId
      bankInstitutionAuthId
    }
  }
}
```

当你希望 identity-service 执行其缓存的全连接刷新时，使用 `refreshPlaidBankConnections`。

> 如果返回了 `verifyMembers`，则表示一个或多个连接需要修复。使用 `platformItemId` 启动重新链接流程——参见 **重新链接已断开的银行账户**。请注意，单账户的 `refreshPlaidBankAccountBalance` 变更操作**不会**返回此信号，因此当你需要检测断开连接时，请使用 `refreshPlaidBankConnections`。

<br />