C. callback_name の説明が「JavaScript 関数」のみで具体性が不足への指摘対応案（Qwenの思考）

修正方針

各ショートコードの解説において、「属性一覧」テーブル内の callback_name の説明欄を拡張し、以下の情報を追加・具体化します。

  1. 引数の構造: コールバック関数に渡される引数名とその型（オブジェクト、配列など）。
  2. データの内容: 引数内に含まれる主要なプロパティ（例: response.result.point, total_price など）。
  3. 操作可能メソッド: 第2引数として渡される point オブジェクト等に含まれる、トランザクション制御用のメソッド（close(), cancel() など）。

修正後の記述案（セクション別）

4.2. [point_setting] 基礎情報の設定

【修正前】

callback_name: myFunctionName 設定値の確認などが必要な場合に任意の JavaScript 関数を呼び出します。

【修正後】

callback_name: myFunctionName 設定値（通貨、レート）の読み込み完了時に呼び出される JavaScript 関数を指定します。

  • 引数構造: function(response)
    • response: 設定結果を含むオブジェクト。
    • response.error: エラーが発生した場合のエラーメッセージ（成功時は null または undefined）。
    • response.result: 初期化された設定情報（通貨種別、適用レートなど）。
  • 用途: 設定が正しく反映されたことを確認したり、UI の初期表示を更新する際に使用します。

4.3. [point_trans_open] 決済データとの紐付け

【修正前】

callback_name: myFunctionName ポイント処理後の最終確定金額を受け取るための、独自の JavaScript 関数を指定します。

【修正後】

callback_name: myFunctionName ユーザーが入力したポイント利用額に基づき、再計算された「最終決済金額」を受け取る JavaScript 関数を指定します。

  • 引数構造: function(response)
    • response: 計算結果を含むオブジェクト。
    • response.result.total_price: ポイント利用額を差し引いた後の最終お支払い金額（文字列または数値）。
    • response.result.use_point: 今回利用されるポイント数。
    • response.result.conv_point: 今回付与される予定のポイント数（購入時）。
  • 用途: 画面に表示されている「お支払い金額」を動的に更新したり、金額が 0 円になった場合に決済ボタンの表示/非表示を切り替えるロジック（例：シナリオ B, C のゼロ円分岐）で使用します。

4.4. [point_trans_close] ポイント処理完了

【修正前】

callback_name: myFunctionName ポイント処理終了後の最終確定金額を受け取るための、独自の JavaScript 関数を指定します。

【修正後】

callback_name: myFunctionName トランザクション確定処理の結果を受け取る JavaScript 関数を指定します。本ショートコードは、第 2 引数にトランザクション制御オブジェクトを渡すことが最大の特徴です。

  • 引数構造: function(result, point)
    • result: 処理結果を含むオブジェクト。
      • result.error: エラーメッセージ（失敗時）。
      • result.result.new_point: 今回付与されたポイント数。
      • result.result.use_point: 今回消費されたポイント数。
      • result.result.total_point: 処理後の合計残高。
    • point (重要): トランザクションを制御するためのオブジェクト。以下のメソッドを含みます。
      • point.close(): ポイントの確定（ロック解除と残高変動）を実行する非同期メソッド。通常はこのショートコード自体が自動でトリガーしますが、プログラム制御が必要な場合に使用します。
      • point.cancel(): 進行中のトランザクションをキャンセルし、仮確保されていたポイントを戻す（ロールバックする）非同期メソッド。決済エラー発生時などに必須となります。
      • point.url: API エンドポイントのベース URL。
      • point.data: トランザクション識別に必要な内部データ（nonce など）。
      • point.pointsystem_nonce: 現在のトランザクション固有のノンセストークン。
  • 用途: 決済ボタンクリック後のポイント確定処理、および Stripe/PayPal 決済失敗時のポイント戻し（ロールバック）処理を実装するために使用します（例：シナリオ C の rollbackPoints 関数）。

4.5. [point_trans_detail] 実行結果の通知

【修正前】

callback_name: myFunctionName 実行されたポイント処理の結果情報を受け取るための JavaScript 関数を指定します。

【修正後】

callback_name: myFunctionName 確定済みのトランザクション詳細（利用ポイント、獲得ポイント、残高など）を受け取る JavaScript 関数を指定します。

  • 引数構造: function(response)
    • response: 詳細情報を含むオブジェクト。
    • response.error: エラーメッセージ。
    • response.result.use_point: 利用ポイント数。
    • response.result.new_point: 獲得ポイント数。
    • response.result.total_point: 現在の総保有ポイント数。
    • response.result.transaction_id: トランザクション ID。
  • 用途: 決済完了ページなどで、ユーザーに対して「今回の利用内訳」と「新しい残高」を表示するために使用します。

4.6. [point_trans_cancel] キャンセル処理

【修正前】

callback_name: myFunctionName ポイント処理が取り消された結果情報を受け取るための JavaScript 関数を指定します。

【修正後】

callback_name: myFunctionName キャンセル処理が正常に完了した旨、およびポイントが復元されたことを通知する JavaScript 関数を指定します。

  • 引数構造: function(response)
    • response: キャンセル結果を含むオブジェクト。
    • response.error: キャンセル失敗時のエラーメッセージ。
    • response.result.message: 成功メッセージ（例："Transaction cancelled"）。
    • response.result.restored_point: 復元されたポイント数（明示的に返される場合）。
  • 用途: キャンセル専用ページなどで、ユーザーに「ポイントは安全に戻されました」という安心感を与えるメッセージを表示するために使用します。

5.2. [point_purchase_open] ポイント購入処理の開始

【修正前】

callback_name: myFunctionName 決済ボタンに割り当てられた金額で購入できるポイント数を返す JavaScript 関数を指定します。

【修正後】

callback_name: myFunctionName 購入金額に対する換算ポイント数の算出結果を受け取る JavaScript 関数を指定します。

  • 引数構造: function(response)
    • response: 購入試算結果を含むオブジェクト。
    • response.result.purchase_amount: 購入対象金額。
    • response.result.grant_point: その金額で購入できるポイント数。
    • response.result.currency: 通貨種別。
  • 用途: 「1,000 円を購入すると 1,000 ポイント付与されます」といった UI 表示を更新する場合に使用します。
  • 注意: 本ショートコードは通常、非表示の <span> 内に配置され、内部的に nonce を発行するために使用されます（シナリオ D, E 参照）。

5.3. [point_purchase_close] ポイント購入処理の完了

【修正前】

callback_name: myFunctionName 最終的に購入されたポイント数と、その決済金額の情報を受け取るための JavaScript 関数を指定します。

【修正後】

callback_name: myFunctionName ポイント購入の決済完了後、正式にポイントが付与された結果を受け取る JavaScript 関数を指定します。

  • 引数構造: function(response)
    • response: 購入完了結果を含むオブジェクト。
    • response.error: エラーメッセージ。
    • response.result.point: 付与されたポイント数（または新しい残高）。
    • response.result.transaction_id: 購入トランザクション ID。
  • 用途: ポイント購入完了ページにて、「〇〇ポイントを購入しました。現在の残高は△△です」という結果を表示するために使用します。
  • 実装上の注意: シナリオ D, E では、この処理をショートコードの自動実行ではなく、JavaScript の fetch で REST API (/point_purchase_close/) を直接呼び出す形で実装することが推奨されています。その場合、API レスポンスがこの response 構造と同じ形式になります。

6.1. [point_own] 保有ポイント数の表示

【修正前】

callback_name: myFunctionName 取得した保有ポイント数を画面に表示・通知するための独自の JavaScript 関数を指定します。

【修正後】

callback_name: myFunctionName 現在保有しているポイント数を非同期的に取得し、受け取る JavaScript 関数を指定します。

  • 引数構造: function(response)
    • response: 残高情報を含むオブジェクト。
    • response.error: 取得失敗時のエラーメッセージ。
    • response.result.point: 現在の保有ポイント数（数値）。
  • 用途: ヘッダーやマイページなど、サイトの任意の場所でリアルタイムに残高を表示するために使用します。

補足：技術仕様書への追記推奨事項

上記の属性説明に加え、ドキュメントの冒頭または「実装手法」の章に、以下の「コールバック関数の基本ルール」セクションを追加することを強く推奨します。これにより、開発者が全ショートコード共通の理解を持てるようになります。

【追加セクション案】コールバック関数の基本ルールと引数構造

Rewald（リワルド）の各ショートコードで指定する callback_name は、非同期処理の結果を受け取るための重要な接点です。実装時には以下のルールに従ってください。

  1. 関数の定義: コールバック関数はグローバルスコープで定義する必要があります（例: window.myCallback = function(...) { ... } または <script> タグ内で定義）。
  2. 引数の受け取り: ほとんどのショートコードは、処理結果を格納した response オブジェクトを第 1 引数として渡します。 
    function myCallback(response) {
    if (response.error) {
        console.error('エラー:', response.error);
        return;
    }
    // 正常系: response.result 配下にデータがある
    console.log('ポイント:', response.result.point);
}

  3. トランザクション制御オブジェクト (point): [point_trans_close] など、一部のショートコードでは第 2 引数として point オブジェクトが渡されます。これは決済失敗時のロールバックなどに不可欠です。

    function onTransReady(result, point) {
    // point オブジェクトを保持しておく（後でキャンセル等に使用するため）
    window.currentPointInstance = point;
}

// エラー発生時のロールバック例
async function rollback() {
    if (window.currentPointInstance) {
        await window.currentPointInstance.cancel();
    }
}
  4. レスポンス構造の統一: すべてのコールバックで返される response オブジェクトは、以下の構造を持ちます。
    • response.error: エラー文字列（null または undefined の場合は成功）。
    • response.result: 成功時のデータオブジェクト。
      • point: ポイント数関連。
      • total_price: 金額関連。
      • その他、ショートコード固有のプロパティ。

まとめ

この修正により、シナリオファイル（特に B, C, E）に記載されている複雑なロジック（triggerClosePSP, rollbackPoints, pointInstance.close() など）が、単なる「おまじない」ではなく、仕様書で定義された明確なインターフェースに基づく正当な実装であることが開発者に伝わるようになります。特に「point オブジェクトの存在と役割」を明記した点は、決済失敗時のポイント消失を防ぐために極めて重要です。