@blocklet/payment-react/docs/components-business-overdue-invoice-payment.ja.md

Reusable react components for payment kit v2

# OverdueInvoicePayment

`OverdueInvoicePayment`コンポーネントは、特定の顧客またはサブスクリプションの支払い期限を過ぎた請求書の支払いを処理するために設計された専門ツールです。期限切れの請求書を自動的に取得し、ユーザーに未払いの支払いを清算するための明確なインターフェースを提供することで、プロセスを簡素化します。

このコンポーネントは2つのモードで動作します。迅速な統合のためにあらかじめ構築されたダイアログを表示するデフォルトモードと、レンダープロップを使用して独自のユーザーインターフェースを構築する柔軟性を提供するカスタムモードです。

## 仕組み

このコンポーネントは、データの取得から最終的なトランザクションの確認まで、支払い期限切れのプロセス全体を調整します。

<!-- DIAGRAM_IMAGE_START:flowchart:4:3::1765377372 -->
![OverdueInvoicePayment](assets/diagram/components-business-overdue-invoice-payment-01.ja.jpg)
<!-- DIAGRAM_IMAGE_END -->

## Props

`OverdueInvoicePayment`コンポーネントは、その動作をカスタマイズするために以下の props を受け入れます。

| Prop | Type | Description |
|---|---|---|
| `subscriptionId` | `string` | サブスクリプションのIDで、期限切れの請求書を確認するために使用します。`subscriptionId`または`customerId`のいずれかを提供する必要があります。 |
| `customerId` | `string` | 顧客のIDまたはDID。これを使用して、顧客のすべての期限切れ請求書を処理します。 |
| `mode` | `'default'` \| `'custom'` | レンダリングモード。`'default'`は事前に構築されたダイアログを表示します。`'custom'`はカスタムUIのために`children`レンダープロップを使用します。デフォルトは`'default'`です。 |
| `onPaid` | `(id, currencyId, type) => void` | 支払いが正常に完了した後にトリガーされるオプションのコールバック関数。`id`は`subscriptionId`または`customerId`になり、`type`は`'subscription'`または`'customer'`になります。 |
| `dialogProps` | `object` | `default`モードで、基盤となるMaterial-UIの`Dialog`コンポーネントに渡すオプションのprops。例：`{ open: true, title: 'カスタムタイトル', onClose: handleClose }`。 |
| `detailLinkOptions` | `object` | 「詳細を表示」リンクのオプション設定。リンクを無効にしたり、テキストを変更したり、カスタムの`onClick`ハンドラを提供したりするために使用できます。形式：`{ enabled?: boolean, onClick?: function, title?: string }`。 |
| `successToast` | `boolean` | `true`の場合、支払いが成功すると成功のトースト通知が表示されます。デフォルトは`true`です。 |
| `alertMessage` | `string` | 顧客モードのときに、デフォルトのタイトルテキストに追加するオプションのメッセージ。 |
| `children` | `(handlePay, data) => React.ReactNode` | `mode`が`'custom'`の場合にのみ使用されるレンダープロップ関数。`handlePay`関数と`data`オブジェクトを受け取ります。 |
| `authToken` | `string` | APIリクエスト用のオプションの認証トークンで、サーバー間またはクロスオリジンのシナリオで役立ちます。 |

### `children` レンダープロップ

`mode="custom"`を使用する場合、`children`関数は2つの引数を受け取ります。

1.  **`handlePay(item: SummaryItem)`**: 特定の通貨グループの支払いプロセスを開始する関数。`item`オブジェクトは`data.summary`オブジェクトから取得します。
2.  **`data`**: 取得した支払い情報を含むオブジェクト：
    *   `subscription?: Subscription`: `subscriptionId`が提供された場合のサブスクリプションの詳細。
    *   `summary: { [key: string]: SummaryItem }`: 各キーが通貨IDであり、値が合計金額、通貨の詳細、支払い方法を含むオブジェクト。
    *   `invoices: Invoice[]`: すべての期限切れ請求書オブジェクトの配列。
    *   `subscriptionCount?: number`: 期限切れの請求書があるサブスクリプションの数（顧客モードの場合）。
    *   `detailUrl: string`: 詳細な請求書情報を表示するためのURL。

## 使用例

すべての例は、アプリケーションに`PaymentProvider`が設定されていることを前提としています。

### 1. サブスクリプションのデフォルトモード

これは、特定のサブスクリプションの期限切れの支払いを処理する最も簡単な方法です。期限切れの請求書が見つかった場合、コンポーネントは自動的にダイアログをレンダリングします。

```tsx SubscriptionOverdue.tsx icon=logos:react
import { OverdueInvoicePayment, PaymentProvider } from '@blocklet/payment-react';
import { useSessionContext } from './hooks/session'; // カスタムセッションフック

function SubscriptionPage({ subscriptionId }) {
  const { session, connect } = useSessionContext();

  const handlePaymentSuccess = (id, currencyId, type) => {
    console.log(`通貨 ${currencyId} を使用した ${type} ${id} の支払いが成功しました`);
    // ここでサブスクリプションデータを再取得してステータスを更新できます
  };

  return (
    <PaymentProvider session={session} connect={connect}>
      {/* 期限切れの請求書がない場合、このコンポーネントはnullになります */}
      <OverdueInvoicePayment
        subscriptionId={subscriptionId}
        onPaid={handlePaymentSuccess}
      />
      {/* 他のサブスクリプションの詳細はここにレンダリングできます */}
    </PaymentProvider>
  );
}
```

### 2. 顧客のデフォルトモード

これを使用して、顧客が複数のサブスクリプションにわたるすべての期限切れ請求書を支払うための中央集約された場所を作成します。

```tsx CustomerDashboard.tsx icon=logos:react
import { OverdueInvoicePayment, PaymentProvider } from '@blocklet/payment-react';
import { useSessionContext } from './hooks/session'; // カスタムセッションフック

function CustomerDashboard() {
  const { session, connect } = useSessionContext();

  return (
    <PaymentProvider session={session} connect={connect}>
      <h2>支払いセンター</h2>
      <p>サービスの継続を確保するために、未払いの支払いをすべて清算してください。</p>
      <OverdueInvoicePayment
        customerId={session.user.did}
        onPaid={() => {
          console.log('ある通貨に対する顧客のすべての期限切れ請求書が支払われました！');
          // 顧客アカウントのステータスを更新
        }}
      />
      {/* 顧客ダッシュボードの残りの部分 */}
    </PaymentProvider>
  );
}
```

### 3. カスタムUIモード

ユーザーエクスペリエンスを完全に制御するには、`mode="custom"`を使用します。これにより、ダイアログを使用する代わりに、支払い機能を既存のUIに直接統合できます。

```tsx CustomOverdueUI.tsx icon=logos:react
import { OverdueInvoicePayment, PaymentProvider, Amount } from '@blocklet/payment-react';
import { useSessionContext } from './hooks/session'; // カスタムセッションフック
import { Card, CardContent, Typography, Button, Stack } from '@mui/material';

function CustomOverdueUI({ subscriptionId }) {
  const { session, connect } = useSessionContext();

  return (
    <PaymentProvider session={session} connect={connect}>
      <OverdueInvoicePayment
        subscriptionId={subscriptionId}
        mode="custom"
        onPaid={() => console.log('カスタムUIでの支払いが成功しました！')}
      >
        {(handlePay, { summary, invoices }) => {
          const summaryList = Object.values(summary);
          if (invoices.length === 0) {
            return <Typography>期限切れの支払いはありません。すべてクリアです！</Typography>;
          }

          return (
            <Card variant="outlined">
              <CardContent>
                <Typography variant="h6" color="error" gutterBottom>
                  {invoices.length} 件の期限切れの請求書があります。
                </Typography>
                <Stack spacing={2} mt={2}>
                  {summaryList.map((item) => (
                    <Stack key={item.currency.id} direction="row" justifyContent="space-between" alignItems="center">
                      <Typography>
                        支払総額: <Amount amount={item.amount} decimal={item.currency.decimal} symbol={item.currency.symbol} />
                      </Typography>
                      <Button
                        variant="contained"
                        color="primary"
                        onClick={() => handlePay(item)}
                      >
                        {item.currency.symbol} で支払う
                      </Button>
                    </Stack>
                  ))}
                </Stack>
              </CardContent>
            </Card>
          );
        }}
      </OverdueInvoicePayment>
    </PaymentProvider>
  );
}
```