tres-recon-gaps

TRES Reconciliation Gaps スキル

TRES Finance の照合ギャップを明らかにし、分析して解消するためのエンドツーエンドのワークフローです。

---

事前確認：日付と資産の範囲を確認する

データを取得する前に、ユーザーに次の2点を確認してください。

1. 対象日

照合クエリは特定の日付（endDate パラメーター）を対象とします。

• ユーザーが日付を明示している場合 — その日付を使用します。
• ユーザーが日付に言及していない場合 — 今日の日付を使用し、次のように伝えます。

  "今日（YYYY-MM-DD）の照合ギャップを取得します。別の日付をご希望の場合はお知らせください。"

常に ISO 形式の YYYY-MM-DD を使用してください。

2. 資産フィルター（任意）

• ユーザーが特定の資産を指定した場合（例：「ETH と USDC の場合」「BTC だけ」）— その資産を記録してください。取得後、表示する前に、結果を asset.symbol の値が指定された資産のみになるようフィルタリングします。
• ユーザーが資産を指定していない場合 — すべてのギャップを取得して表示します。

---

ステップ 1 — 照合ギャップを取得する

reconciliation クエリを使用します。確認済みの endDate を必ず渡してください。一度に最大 200 件取得します。

query GetReconciliationGaps($limit: Int, $offset: Int, $endDate: Date) {
  reconciliation(limit: $limit, offset: $offset, endDate: $endDate) {
    totalCount
    results {
      id
      amount
      calculatedBalance
      state
      status
      gap
      belongsTo {
        id
        name
        identifier
      }
      asset {
        key
        identifier
        symbol
        platform
      }
      pendingTransactionsCount
      pendingTransactionsTotalAmount
    }
  }
}

変数：{"limit": 200, "offset": 0, "endDate": "<confirmed-date>"}

注：gap = calculatedBalance − historicalBalance です。正の値は台帳の残高がオンチェーンより多いことを、負の値は台帳の残高が少ないことを意味します。

ユーザーが特定の資産を指定した場合は、ここで結果をフィルタリングします。asset.symbol が指定されたシンボルと一致する行のみを残してください（一致判定では大文字と小文字を区別しません）。

---

ステップ 2 — 法定通貨換算値とオンチェーン残高を補完する

ステップ 1 の結果（フィルタリング済み）からすべての ID を取得し、assetBalance をクエリします。

query GetAssetBalancesWithFiat($ids: [String], $limit: Int, $currency: String) {
  assetBalance(id_In: $ids, limit: $limit, currency: $currency, excludeUnderDelegation: true) {
    totalCount
    results {
      id
      calculatedBalance
      historicalBalance
      reconciliation
      fiatValue {
        value
        unitPrice
        fiatCurrency
      }
      belongsTo {
        id
        name
        identifier
      }
      asset {
        key
        symbol
        platform
        identifier
      }
    }
  }
}

変数：{"currency": "usd", "ids": ["<id1>", "<id2>", ...], "limit": 200}

重要：id_In が受け取るのは [ID] ではなく [String] です。

各行について計算します。

fiatGap = reconciliation (token gap) × fiatValue.unitPrice

---

ステップ 3 — 表示：必ず HTML ダッシュボードをレンダリングする

必ず、主な出力としてスタンドアロンの .html ファイルを生成してください。インラインウィジェットで代用してはいけません。

完全なビジュアル仕様（フォント、色、レイアウト、列幅、モーダルの動作、API 呼び出しの仕組み）については、references/html-template-notes.md を参照してください。

生成ファイルの主な要件：

• ダークな金融ダッシュボードのデザイン（仕様は参照ファイルを確認）
• 対象日と更新日時のバッジを表示する固定ヘッダー
• 5 つのサマリー指標カード：法定通貨換算の純ギャップ、正のギャップ数、負のギャップ数、資産グループ数、保留中の tx 数
• 資産フィルターを適用した場合、ツールバーにフィルターバッジを表示する（例：Filtered: ETH, USDC）
• 検索 + 方向フィルター + プラットフォームフィルターのツールバー
• 資産ごとにグループ化した折りたたみ可能なセクションを、法定通貨換算の純ギャップの絶対値が大きい順に並べる
• 各行に必要なすべての列を表示する — 最後の列には、プロンプトをコピーするボタンを 2 つ配置する：↳ Plug（青）と ⟳ Auto-fill（紫）
• どちらかのボタンをクリックすると、そのまま貼り付けられるプロンプトがクリップボードにコピーされ、トーストに「プロンプトをコピーしました — ギャップを解消するには、Claude のチャットに貼り付けてください。」と表示される
• HTTP リクエストは行わない — HTML は表示専用インターフェースです。すべての変更は、ユーザーがプロンプトを貼り付けた後に Claude が実行します

ファイルを生成したら、present_files を使ってユーザーに提示します。

---

ステップ 4 — 操作（plug-once と auto-fill）

ユーザーは HTML ダッシュボードからプロンプトをコピーして Claude のチャットに貼り付けることで操作を実行します。Claude がこれらのプロンプトを受け取ったら、追加の確認なしですぐに対応する変更を実行してください（ユーザーはすでにダッシュボードで操作を選択しています）。

1 回限りの plug（createPlug）

mutation CreatePlug(
  $hash: String!
  $platform: Platform!
  $timestamp: DateTime!
  $belongsToId: ID!
  $assetId: ID!
  $assetIdentifier: String!
  $amount: Float!
  $direction: Direction!
  $thirdPartyIdentifier: String!
) {
  createPlug(
    hash: $hash
    platform: $platform
    timestamp: $timestamp
    belongsToId: $belongsToId
    assetId: $assetId
    assetIdentifier: $assetIdentifier
    amount: $amount
    direction: $direction
    thirdPartyIdentifier: $thirdPartyIdentifier
  ) {
    transaction { id identifier platform timestamp }
  }
}

変数の対応関係：

フィールド	値
hash	plug_<assetId>_<walletId>_<timestamp_ms>
platform	asset.platform
timestamp	new Date().toISOString()
belongsToId	belongsTo.id
assetId	asset.key
assetIdentifier	asset.identifier（ETH/AVAX のようなネイティブ資産には "native" を使用）
amount	Math.abs(gap)
direction	gap > 0 ? "INFLOW" : "OUTFLOW"
thirdPartyIdentifier	belongsTo.identifier（ウォレットアドレス）

自動ギャップ補完ルール（createReconciliationGapFillRule）

mutation CreateGapFillRule(
  $name: String!
  $assetId: String!
  $internalAccountId: Int!
  $interval: Interval!
  $startDate: Date!
  $endDate: Date!
) {
  createReconciliationGapFillRule(
    name: $name
    assetId: $assetId
    internalAccountId: $internalAccountId
    interval: $interval
    startDate: $startDate
    endDate: $endDate
  ) {
    success
    message
    ruleId
  }
}

変数マッピング：

フィールド	値
name	ユーザーが編集できるルール名（事前入力：Auto gap-fill · <asset> · <wallet>）
assetId	asset.key
internalAccountId	parseInt(belongsTo.id) — Int! が必須です
interval	DAILY / WEEKLY / MONTHLY
startDate	ISO 日付文字列。例："2026-04-07"
endDate	ISO 日付文字列（デフォルト：今日から 2 年後）

---

ステップ 5 — プラグの追加が完了したらデータ収集を実行する

ユーザーがプラグの追加を完了したと示したら（例：「完了」「以上です」「よさそうです」）、更新された状態を同期するためにデータ収集を実行します。

triggerDataCollect mutation を使用します（または同等のものを使用します。必要に応じて get_schema_summary でイントロスペクションしてください）：

mutation TriggerDataCollect {
  triggerDataCollect {
    success
    message
  }
}

完了したら、ユーザーに次のように伝えます：

「データ収集を開始しました。TRES が最新のオンチェーン残高を同期します。照合ギャップはまもなく更新されます。」

---

グループ化と並べ替えのロジック

デフォルトのグループ化：アセットシンボル別

• asset.symbol が同じ行をすべて 1 つのグループにまとめます
• 各グループのヘッダーに法定通貨建ての正味ギャップを表示します
• グループは法定通貨建ての正味ギャップの絶対値が大きい順に並べ替えます
• グループ内の行は法定通貨建てのギャップの絶対値が大きい順に並べ替えます

代替方法：ウォレット別にグループ化（ユーザーが希望した場合）

• belongsTo.identifier でグループ化します
• 並べ替えのロジックは同じです

常にトークンギャップではなく、法定通貨建てのギャップを基準に並べ替えます。

---

数値の書式規則

// Fiat values
≥ $1M  → "$X.XXXM"
≥ $1K  → "$X.XXK"
< $1K  → "$X.XX"

// Token quantities
≥ 1B   → "X.XXXB"
≥ 1M   → "X.XXXM"
≥ 1K   → "X.XXXK"
< 1K   → up to 6 significant figures, trim trailing zeros

// Signs
Positive gaps: "+" prefix
Negative gaps: "−" (minus sign, not hyphen)
No sign:       absolute values (on-chain bal, calculated bal)

---

よくあるエッジケース

状況	対応
unitPrice = 0	法定通貨建てのギャップには「—」を表示します。トークンギャップは引き続き表示します
historicalBalance が負の値	そのまま表示し、極端な値の場合は視覚的に目立たせます
pendingTransactionsCount > 0	アンバー色の警告バッジを表示します。保留中のトランザクションが確定するとギャップが縮小する場合があります
トークンギャップが非常に大きいが法定通貨建ての値が小さい	引き続き表示します。法定通貨建ての値で並べ替えるため、下位に表示されます
大規模なデータセットで gap フィールドがタイムアウトする	代わりに assetBalance.reconciliation フィールドを使用します（同じ値で、より信頼性があります）
アセットフィルターの結果が 0 行	ユーザーに「[date] の [assets] にギャップは見つかりませんでした」と伝えます

---

主なスキーマ情報（検証済み）

• reconciliation クエリ — endDate パラメーターがあり、gap と基本的な残高フィールドを返します
• assetBalance クエリ — historicalBalance、reconciliation（= gap）、および fiatValue { value, unitPrice } を返します。拡張データを取得できるため、こちらを優先してください
• assetBalance(id_In: [String]) — [ID] ではなく [String] である点に注意してください
• createPlug — belongsToId は ID!、assetId は ID! です（アセットキーの文字列を渡します）
• createReconciliationGapFillRule — internalAccountId は Int!、assetId は String!、interval は Interval! 列挙型です
• プラットフォームの列挙値：ETHEREUM、BASE、ARBITRUM、OPTIMISM、POLYGON、AVAX、AVALANCHE_P_CHAIN、MANTRA など