tres-report-create

TRES レポートの作成

tres-mcp MCP サーバー（BFF に対する GraphQL）を通じて、TRES Finance のレポートをプログラムで作成します。手順は常に同じです。レポートを選択 → エクスポートを開始 → DONE になるまでポーリング → 署名付きの link を返します。必要に応じて、その後ファイルをダウンロードして分析することもできます。

ユーザーが必要としているレポートがわからない場合は、先に tres-report-advisor スキルを使ってから、ここに戻ってレポートを作成してください。

ワークフロー

- [ ] Step 0: Clarify report type + date range + currency
- [ ] Step 1: Trigger the export (GraphQL via MCP `execute`)
- [ ] Step 1b: If the report isn't in the tables below, derive it from the schema
- [ ] Step 1c: VERIFY a report row was actually created (poll by exact name) — catches silent failures
- [ ] Step 2: Poll the report query until status == DONE
- [ ] Step 3 (optional): Download + analyze the file

ステップ 0 — 対象範囲を確認する（開始前に必須）

何かを始める前に、次の点を確認してください。

• レポートの種類（必須）。 ユーザーの表現を以下の表に照らし合わせてください。不明な場合は、利用可能な種類を確認してください。

  query { availableReportTypes { name exportType entitiesType llmDescription } }
  

• 日付範囲（該当する場合）。 LEDGER / AUDIT_LOG レポートでは、ISO 8601 形式の timestamp_Gte / timestamp_Lte を指定します。
  • 「2025 年第 1 四半期」→ Gte 2025-01-01T00:00:00Z、Lte 2025-03-31T23:59:59Z
  • 「2025 年」→ Gte 2025-01-01T00:00:00Z、Lte 2025-12-31T23:59:59Z
  • 日付範囲が必要なのに指定されていない場合は、確認してください。
• 通貨。 ユーザーから別の指定がない限り、デフォルトは "usd" です。
• 分析の目的（ファイルだけでなく、データの分析も希望する場合のみ）。 データから何を明らかにするべきかを確認してください。デフォルトでは、合計、上位項目、傾向などの一般的な概要を作成します。これにより、ステップ 3 の内容が決まります。

次のように簡潔に確認してください。例：「2025 年第 1 四半期の取引元帳を CSV で作成します。開始します。」

ステップ 1 — エクスポートを開始する

レポートの entitiesType に対応する GraphQL クエリを呼び出し、エクスポートパラメーターを渡します。MCP の execute ツールで実行してください（不明な場合は、事前に validate_query で検証してください）。

entitiesType → 呼び出すクエリ

entitiesType	クエリ
LEDGER	transaction
ASSETS	organizationBalance
BALANCE	organizationBalance
HISTORICAL_BALANCE	organizationBalance
ACCOUNTS	internalAccount
GENERAL	internalAccount
STAKING_DATA	stakingYieldRecord
AUDIT_LOG	auditLog
LOGIN_HISTORY	loginHistoryExport

レポートカタログ（exportFormat の値 — 本番環境で検証済み）

レポート名	exportFormat	entitiesType
取引元帳	BASIC_RAW_TRANSACTIONS	LEDGER
実現損益	EXTENDED_RAW_TRANSACTIONS	LEDGER
コスト内訳の未加工取引	COST_BREAKDOWN_RAW_TRANSACTIONS	LEDGER
ロールアップ内訳 †	ROLLUP_BREAKDOWN	LEDGER
元帳照合	RECONCILIATION	LEDGER
取得原価の繰越	COST_BASIS_ROLL_FORWARD	LEDGER
資産の繰越	ASSET_ROLL_FORWARD	LEDGER
ERP 同期前	PRE_SYNC_JOURNAL	LEDGER
ERP 同期後	POST_SYNC_JOURNAL	LEDGER
MT940 明細書	MT940	LEDGER
資産残高	RAW_BALANCES	ASSETS
資産残高 V2	RAW_BALANCES_V2	ASSETS
資産残高 - アーカイブ †	ARCHIVED_BALANCES	ASSETS
残高の推移	BALANCE_TRENDS	ASSETS
ウォレット残高	INTERNAL_ACCOUNTS_BALANCES	ASSETS
資産ごとの取得原価スタック	COST_BASIS_STACK_PER_ASSET	ASSETS
資産の法定通貨評価額	DAILY_ASSET_PRICING	ASSETS
再評価レポート	REEVALUATION	ASSETS
履歴残高形式	HISTORICAL_BALANCE	HISTORICAL_BALANCE
取得原価インベントリ †	COST_BASIS_INVENTORY	BALANCE
組織のウォレット	INTERNAL_ACCOUNTS	ACCOUNTS
連絡先	CONTACTS	ACCOUNTS
サードパーティのアドレス	THIRD_PARTY_ADDRESSES	ACCOUNTS
勘定科目一覧	CHART_OF_ACCOUNT	GENERAL
ERP ルール	ERP_RULES	GENERAL
接続済みカストディアン	CONNECTED_CUSTODIANS	GENERAL
ステーキング報酬とポジション	STAKING_DATA	STAKING_DATA
監査証跡 / ログ	AUDIT_LOG	AUDIT_LOG
ログイン履歴	LOGIN_HISTORY	LOGIN_HISTORY

† = 特別な処理が必要です（下記の「追加パラメーターが必要なレポート」を参照）。組織のカタログは更新されるため、availableReportTypes を正式な情報源として扱ってください。要求されたレポートがこの表にない場合は、推測せず、ステップ 1b に進んでスキーマから導き出してください。

エクスポートパラメーター（必ず含める）：

• exportFormat — 上記の表の値（UPPER_CASE）
• exportName — 説明的で一意な名前（例: "Transaction Ledger Q1 2025"）— これは手順 2 で照合します
• currency — 特に指定がなければ "usd"
• outputFormat — 下流の分析には "CSV"、ユーザーがスプレッドシートを希望する場合は "XLSX"

日付範囲のレポート（LEDGER、AUDIT_LOG）には timestamp_Gte / timestamp_Lte を追加してください。

⚠️ GraphQL 変数の型 — これらを正確に設定してください（初回実行での正確性）

BFF は変数の型を厳密に検証します。誤った型は HTTP 400 を返し、レポートは作成されません — しかも execute ツールはこれを GraphQL の errors 配列ではなく、error / error_type フィールドの下に表示するため、見落としやすくなっています。変数は以下の正確な型で宣言してください:

変数	GraphQL の型	備考
exportFormat	String	UPPER_CASE の値
exportName	String	一意な名前
currency	String	例: "usd"
outputFormat	ReportOutputFormat	String ではありません。値は "CSV" / "XLSX"
timestamp_Gte / timestamp_Lte	DateTime	String ではありません。ISO 8601 の値
identifier_In、children_Asset_AssetClass_In、children_BelongsTo_In	[String]	[ID] ではありません

パラメータは正確に exportName、exportFormat などの名前の変数として渡す必要があります — BFF は info.variable_values から名前で読み取ります。インラインリテラルや名前を変更した変数（$ef）では、レポートは黙って作成されません。

例 — Transaction Ledger エクスポートをトリガーする（動作確認済みの形式）:

query($limit: Int, $offset: Int, $timestamp_Gte: DateTime, $timestamp_Lte: DateTime,
      $exportFormat: String, $exportName: String, $currency: String, $outputFormat: ReportOutputFormat) {
  transaction(limit: $limit, offset: $offset, timestamp_Gte: $timestamp_Gte,
              timestamp_Lte: $timestamp_Lte, exportFormat: $exportFormat,
              exportName: $exportName, currency: $currency, outputFormat: $outputFormat) {
    results { id }
    totalCount
  }
}

{
  "limit": 1,
  "offset": 0,
  "timestamp_Gte": "2025-01-01T00:00:00Z",
  "timestamp_Lte": "2025-03-31T23:59:59Z",
  "exportFormat": "BASIC_RAW_TRANSACTIONS",
  "exportName": "Transaction Ledger Q1 2025",
  "currency": "usd",
  "outputFormat": "CSV"
}

その後、エクスポートはバックグラウンドで非同期に生成されます。totalCount を伴う 200 は、クエリが実行されたことだけを確認するものであり、レポートが作成されたことを意味するものでも（手順 1c で確認してください）、ファイルが準備できたことを意味するものでもありません（手順 2 でポーリングしてください）。

追加パラメータが必要なレポート（これらを省略するとレポートがエラーになるか、空で返ります）

レポート（exportFormat）	トリガー方法	必須の追加パラメータ
ROLLUP_BREAKDOWN	transaction	identifier_In: [String] — 分解するロールアップ親ハッシュ。これがないとレポートは空になります。
COST_BASIS_INVENTORY	transaction（organizationBalance ではない）	ちょうど1つの children_Asset_AssetClass_In: [String]（資産クラス ID）。任意: 最大1つの children_BelongsTo_In: [String]。欠落/複数 → レポートは status: ERROR で終了します（「must select exactly one asset class」）。資産クラス ID は query { assetClass(limit: N) { results { id name symbol } } } から取得してください。
ARCHIVED_BALANCES	organizationBalance	対象日付の既存のコミットスナップショットが必要です。存在しない場合は保留のままになります — 任意の日付には HISTORICAL_BALANCE（Time Capsule）を推奨します。

時点残高。 過去の日付時点の残高レポートには、organizationBalance は balanceDate: DateTime も受け付けます（その日付時点の残高を再構築します — これが Time Capsule の経路です。RAW_BALANCES + balanceDate を渡すと HISTORICAL_BALANCE に昇格されます）、また commitId: UUID（特定のコミットスナップショットから取得）も受け付けます。現在の残高にはどちらも省略してください。

LOGIN_HISTORY は異なる形式です

loginHistoryExport は exportFormat: String!、exportName: String!、outputFormat: ReportOutputFormat のみを受け取り（currency/limit/timestamps はありません）、{ success reportId } を返します:

query($exportFormat: String!, $exportName: String!, $outputFormat: ReportOutputFormat) {
  loginHistoryExport(exportFormat: $exportFormat, exportName: $exportName, outputFormat: $outputFormat) {
    success
    reportId
  }
}

Step 1b — 不明なレポート、または新しく追加されたレポートですか？スキーマから導き出します（セルフサービス）

availableReportTypes が信頼できる情報源です。上記の表にないものも含め、組織がサポートするすべてのレポートが一覧に記載されています。要求されたレポートがここにない場合は、推測せず、MCP のイントロスペクションツールを使って実際のスキーマからトリガーを特定してください。

- [ ] 1. availableReportTypes -> get this report's exportType + entitiesType + llmDescription
- [ ] 2. Pick the trigger query from entitiesType (Step 1 table). If entitiesType is new/unclear,
         default: transaction (tx / ledger / cost-basis), organizationBalance (balances / assets),
         internalAccount (accounts / metadata).
- [ ] 3. introspect(<query>) -> read the EXACT arg names AND types
- [ ] 4. build_query(<query>) -> canonical variables-as-args template (optional, handy)
- [ ] 5. validate_query(<assembled query>) BEFORE executing
- [ ] 6. Trigger with the 4 export params (+ timestamps only if the query exposes them)
- [ ] 7. Poll; if it errors, apply the error->fix table, then re-trigger
- [ ] 8. On DONE: return the link AND record the working recipe

最初の試行で成功させるための原則：

1. 形式を確認し、独自に作らないでください。 availableReportTypes の exportType をそのまま exportFormat として使います。
2. 変数の型は記憶に頼らず、introspect から導き出してください。 各変数は、スキーマで報告された正確な型で宣言します。これだけで、400 エラー「used in position expecting type X」を防げます。一般的な型を確認してください。outputFormat → ReportOutputFormat、currency → String、timestamp_* → DateTime、リストフィルター → [String]。
3. 実行前に検証してください。 validate_query を使うと、不要なレポートを作成せずに、引数、型、選択の誤りを検出できます。
4. 最小構成から始め、エラーで要求されたものだけを追加してください。 まずエクスポートパラメーターだけでトリガーし、ジェネレーターが必要とする追加フィルターをエラーメッセージから確認します。

エラー → 修正方法の表（本番環境で確認されたすべての失敗モードを網羅）：

エラー	意味	修正方法
Variable '$X' of type 'A' used in position expecting type 'B'	宣言した型が誤っています	$X を B として再宣言し、再検証します
Unknown argument 'X' on field 'Y'	このクエリにはそのフィルターがありません	そのフィルターを公開するクエリ（多くの場合 transaction）に切り替えるか、フィルターを削除します
Variable '$X' is never used	対応する引数のない変数を宣言しています	クエリの実際の引数として使うか、削除します
200 でトリガーされるが、レポートの status: ERROR（「must select exactly one …」／「required …」）	ジェネレーターに追加の必須フィルターが必要です	introspect で対応する引数名を特定し、そのリストクエリ（例：assetClass、internalAccount）から有効な値を取得します。必要なものだけを追加し、再度トリガーします
レポートがいつまでも IN_PROGRESS のまま	データの前提条件が満たされていません（例：コミットスナップショットがない）	不足しているものをユーザーに伝え、代替レポートを提案します

学んだことを記録してください。 新しいレポートのトリガーが正常に実行され、ステータスが DONE になったら：

• 短期的な対応：MCP の memory ツールを使って手順を保存します。トリガークエリ、exportFormat、動作する変数の型、必須フィルターを記録してください。
• 長期的な対応：このスキルの表に新しい行を追加することを提案します（レポート名、exportFormat、トリガークエリ、必須パラメーター）。スキルを最新の状態に保てるよう、ユーザーにも共有してください。

Step 1c — レポートの行が作成されたことを確認します（必須のサイレント失敗対策）

トリガーのたびに、成功したことをユーザーに伝える前に、必ず直ちに実行してください。 トリガーはクエリによる副作用です。リクエストにわずかでも誤りがある場合（変数ではなくインラインリテラルを使っている、$ef のように変数名を変更している、必須パラメーターがないなど）、BFF は errors: null とともに 200 を返し、レポートを作成せずに無言で処理を終えます。動作したことを確認する確実な方法は、名前で行を検索することだけです。

トリガーで指定した正確な exportName を使って、行を検索します。

query($name: String, $ordering: String, $limit: Int) {
  report(name: $name, ordering: $ordering, limit: $limit) {
    results { id name status }
  }
}

{ "name": "<the exact exportName from Step 1>", "ordering": "-created_at", "limit": 1 }

• results が空（行がない） → これは「処理中」ではなく、サイレント失敗です。成功したと報告してはいけません。上記のルールに照らしてトリガーを再確認します。パラメーターが変数として渡されている（インラインリテラルではない）こと、変数名が exportName／exportFormat／currency／outputFormat／timestamp_* と完全に一致していること、型が正しいことを確認してから、もう一度だけトリガーします。それでも行が作成されない場合は中止し、サイレントに失敗して作成できなかったことをユーザーに伝えてください（いつまでも繰り返さないでください）。
• 行が存在する → レポートは正常に作成されています。ステップ 2 に進み、ステータスが DONE になるまでポーリングします。

この検索で同じ名前の古いレポートではなく今回の行が見つかるよう、実行ごとに exportName を一意にしてください（例：日付やタイムスタンプを追加します）。

ステップ 2 — 完了するまでポーリングする

ステップ 1 の正確な exportName でレポートを検索します（最も確実に一致します）。

query($name: String, $ordering: String, $limit: Int) {
  report(name: $name, ordering: $ordering, limit: $limit) {
    results { id name status link reportSize exportFormat createdAt }
  }
}

{ "name": "<the exportName from Step 1>", "ordering": "-created_at", "limit": 1 }

フィールド／引数に関する注意点（誤るとエラーにならずに失敗します。正しく指定してください）：

• 並べ替えの引数は ordering であり、orderBy ではありません。
• ダウンロードフィールドは link（署名付き S3 URL）であり、downloadUrl ではありません。
• レポート種別のフィールドは exportFormat であり、exportType ではありません。
• レポートの検索に exportFormat でフィルターをかけないでください。保存される値は小文字（例：rollup_breakdown）ですが、実行時には大文字（UPPER_CASE）で指定するため、完全一致のフィルターでは何も見つかりません。name でフィルターしてください。

ポーリングループ：

1. 名前で最新のレポートを検索します。
2. status を確認します。
   • IN_PROGRESS → 約 60 秒待って（例：シェルで sleep 60 を実行して）、再度検索します。
   • DONE → link に署名付きダウンロード URL が格納されています。次に進みます。
   • ERROR → 生成処理で入力が拒否されました（必須フィルターの指定漏れなど）。エラーメッセージを確認し、パラメーターを修正してから再実行します。同じ呼び出しを黙って再試行しないでください。
3. 最大 10 回繰り返し、試行の間は約 60 秒待ちます。

両方のエラーチャネルを確認してください。 レポートの失敗には 2 つの形態があります。（1）トリガーが HTTP 400 を返し、問題が error / error_type に含まれ、GraphQL の errors は空または存在しない場合。このとき、空でない error はすべて致命的な失敗として扱い、成功を報告しないでください。（2）トリガーは 200 を返すものの、その後レポートが status: ERROR で完了する場合です。200 だけで成功と判断しないでください。

小さなレポートは数秒で完了しますが、大きなレポート（アセット数が多い、日付範囲が広い、大規模な組織など）は数分から数時間かかることがあります。早めに所要時間の見込みを伝えてください。status == DONE になったら、link をユーザーに共有します。

ダウンロードリンクの提示方法。 署名付き URL をそのままチャットに貼り付けないでください。長く見づらいうえ、認証情報が含まれています。必ず、完全な URL をリンク先に設定し、分かりやすいアンカーテキストを使ったクリック可能なきれいな Markdown リンクとして表示してください。

[Click here to download your report](<the full presigned link>)

レポートに合わせてアンカーテキストを調整してもかまいません。例：[ERP Pre-Sync レポート（CSV）をダウンロード](<link>)。アンカーは短く、分かりやすくしてください。URL 自体はアンカーの背後に隠します。リンクは署名付きであり、有効期限は限られている（約 24 時間）ことを伝えてください。

ステップ 3 — ダウンロードして分析する（任意）

ユーザーがデータの分析を希望する場合（リンクだけでなく）、署名付き URL からダウンロードし、pandas を使ってローカルで確認してください。

import pandas as pd, requests
from io import BytesIO

resp = requests.get("<presigned_url>")
resp.raise_for_status()
df = pd.read_csv(BytesIO(resp.content))
print(df.shape, list(df.columns))
print(df.head())
print(df.dtypes)

必ず df.head() と df.dtypes から始めてから、要求された分析（groupby、value_counts、describe、pivot_table）を実行してください。金額は f"${value:,.2f}" の形式にし、データフレームが大きい場合は全行を表示せず、要約してください。レポートごとの詳しい分析ガイダンスについては、tres-report-analyzer スキルを使用してください。

ルール

• 実行する前に、必ずレポートの種類（必要な場合は日付範囲も）を確認してください。
• 上記の特別なレポート（COST_BASIS_INVENTORY は transaction 経由で実行）を除き、上記の表を使ってクエリをレポートの entitiesType に対応付けてください。
• 表にないレポートについては、必ず Step 1b に従ってください。クエリを introspect して正確な引数の型を確認し、validate_query を実行し、最小限の内容でトリガーして、エラー→修正の表に従って修正した後、レシピを保存します。不明なレポートの型やフィルターを推測で指定してはいけません。
• 変数の型は厳密です。 outputFormat は ReportOutputFormat、timestamp_* は DateTime、リストフィルターは [String] です。型が間違っていると HTTP 400 になり、レポートは生成されません。exportName / exportFormat など、指定どおりの名前の変数としてパラメーターを渡してください。
• トリガー後は、必ず Step 1c を実行してください。exportName を完全一致で検索し、レポートの行が存在することを確認してから、成功したと判断してください。検索結果が空の場合は「処理中」ではなく、サイレント失敗（200 + errors: null + 行なし）です。行が確認できるまでは、成功を報告してはいけません。検索結果が自分の行と一致するように、実行ごとに一意の exportName を使用してください。
• ROLLUP_BREAKDOWN には必ず identifier_In を渡してください。COST_BASIS_INVENTORY には children_Asset_AssetClass_In をちょうど 1 つ渡してください。そうしないと、レポートが空になるか、エラーになります。
• トリガー後は、両方の経路で成功を確認してください。トリガーに error / error_type がないことと、status が DONE に達すること（ERROR ではないこと）を確認してください。
• report クエリは exportFormat ではなく name でポーリングしてください。orderBy ではなく ordering を使い、downloadUrl ではなく link を使ってください。
• ダウンロードリンクは、クリック可能な Markdown リンクとして提示してください（例：[レポートをダウンロードするにはこちらをクリック](<link>)）。署名付き URL をそのまま提示してはいけません。リンクは署名付きであり、一定時間が経過すると期限切れになることを伝えてください。
• ユーザーから別の指定がない限り、currency は "usd"、outputFormat は "CSV" をデフォルトにしてください。
• トランザクションハッシュ、アドレス、レポート ID、identifier_In の値を切り詰めたり短縮したりしてはいけません。常に完全な値を表示し、渡してください。
• これは読み取り／エクスポート用のスキルです。プラットフォームデータを変更するミューテーションは、絶対に実行してはいけません。