tres-report-analyzer

TRES Report Analyzer

TRES Finance のレポートエクスポート（XLSX ファイル）を分析し、明確で実用的な調査結果の要約を作成します。目的は、異常、失敗したチェック、大きな変動、主要な指標といった最も重要な情報を自動的に見つけ出し、スプレッドシートを手作業で確認する時間を何時間も節約することです。

仕組み

1. アップロードされたファイルのタブ名と列ヘッダーから、レポートの種類を特定します
2. レポートの種類に応じたチェックを実行する分析スクリプトを実行します
3. 最も重要な項目を先頭にして、調査結果を構造化された要約として提示します

手順 1：レポートの種類を特定する

ユーザーが XLSX ファイルをアップロードしたら、まず TRES のどのレポートかを特定します。主な判断材料としてタブ名を使用します。

タブの特徴	レポートの種類
Summary、Inventory Reconciliation、Running Token Reconciliation、Running Fiat Reconciliation、Historical Token Reconciliation、Historical Fiat Reconciliation、Roll Forward Reconciliation	Ledger Reconciliation
Summary Per Asset、Summary Per Year、Summary per Tx Activity、raw_data（Realized Gain 列あり）	Realized Gains & Losses
By Asset、By Wallet、By Platform、By Position、Cost Basis、raw_data（Previous Amount 列あり）	Balance Trends
By Asset、By Wallet、By Platform、By Position、Cost Basis、raw_data（Previous Amount 列なし）	Asset Balances
By Asset、By Wallet、By Platform、By Position、Cost Basis、raw_data（Historical Balance 列あり、Time Capsule が有効）	Historical Balance Format
Asset Balances - PT、Cost Basis、raw_data	Asset Balances V2
Fiat Value Summary、Amount Summary By Application、Amount Summary、raw_data	Asset Balances - Archives
Overview、raw_data（Safety Check 列あり）	Asset Roll Forward
Summary、Inventory Reconciliation、raw_data（Cost Basis 列あり、約 29 列）	Cost Basis Roll Forward
Chart of Accounts Summary、raw_data（Configuration Status あり）	ERP Pre-Sync
COGS Lot 列を含む単一の raw_data タブ	Cost Breakdown
Rollup Parent TX Hash を含む単一の raw_data タブ	Rollup Breakdown
Sync Status を含む約 8 列の単一の raw_data タブ	ERP Post-Sync
Price Source 列を含む単一の raw_data タブ	Asset Fiat Values
Purchase Date、Remaining Quantity を含む単一の raw_data タブ	Cost Basis Stack
Sub TX Index、Is Taxable を含む単一の raw_data タブ	Cost Basis Inventory
ウォレットのレジストリ列を含む単一の raw_data タブ	Organization Wallets
基本的な tx 列を含む単一の raw_data タブ	Transaction Ledger

レポートの種類を特定できない場合は、ユーザーにその旨を伝え、どのレポートか確認してください。

手順 2：分析を実行する

scripts/analyze_report.py の Python スクリプトを使用して、XLSX ファイルからデータを抽出します。次のように実行します。

python /path/to/skill/scripts/analyze_report.py "/path/to/uploaded/file.xlsx" --output /path/to/output.json

スクリプトは、抽出した指標を含む JSON ファイルを出力します。スクリプトが失敗した場合、またはレポートの種類がスクリプトでまだサポートされていない場合は、代わりに openpyxl でファイルを直接読み込み、その場で分析を行ってください。

レポートタイプごとに分析する項目

各レポートタイプの詳細な分析チェックリストについては、references/analysis-playbook.mdをお読みください。基本的なパターンは次のとおりです。

照合レポート（Ledger Reconciliation、Asset Roll Forward、Cost Basis Roll Forward）の場合：

• 列を確認します。合格と不合格はいくつありますか？
• どの資産／ウォレットに最大の不一致がありますか？
• スリッページまたは差額の合計はいくらですか？
• パターンはありますか？（同じウォレット、同じ資産、同じプラットフォームなど）

残高レポート（Asset Balances、Historical Balance Format、V2、Archives、Balance Trends）の場合：

• ポートフォリオの合計価値
• 法定通貨換算額上位の保有資産
• 残高ゼロまたはマイナスの項目はありますか？
• Balance Trendsの場合：変動幅が最大の項目（絶対値で最も大きな変化）
• 未検証のトークンまたは価格情報の欠落

トランザクションレポート（Transaction Ledger、Realized Gains & Losses、Cost Breakdown）の場合：

• トランザクションの合計件数と対象期間
• 法定通貨換算額が最大のトランザクション
• 実現損益の合計（該当する場合）
• 分類の内訳（各タイプの件数）
• 未分類のトランザクションはありますか？

取得原価レポート（Cost Basis Stack、Cost Basis Inventory、Cost Basis Roll Forward）の場合：

• 取得原価の合計と未実現損益
• 未実現損失が最大のロット（タックスロス・ハーベスティングの候補）
• ロットの保有期間（非常に古いロットはありますか？）
• 該当する場合は減損額

ERPレポート（Pre-Sync、Post-Sync）の場合：

• 設定状況の内訳（準備完了と設定ミスはそれぞれいくつですか？）
• 勘定科目のマッピング漏れ
• 同期失敗とエラーのパターン
• 借方／貸方の残高チェック

ステップ3：調査結果を提示する

以下の構成で回答します。簡潔にまとめてください。ユーザーが求めているのはデータの羅列ではなく、洞察です。

形式

レポートの種類と対象期間を1行で説明するところから始めます。

次に、重要度の高い順に調査結果を提示します。

1. 要注意事項（該当する場合）：チェックの不合格、大きな不一致、データの欠落、同期の失敗
2. 主要指標：合計価値、件数、損益などの主要な数値
3. 注目項目：最大のトランザクション、上位の保有資産、最大の変動など、把握しておくべき内容
4. 対応事項（該当する場合）：ユーザーが調査または修正すべき具体的な内容

最後に、フォローアップとして質問できる内容を簡潔に案内します（例：「さらに詳しく確認したい場合は、特定の資産やウォレットについて詳しく調べられます」）。

スタイルのルール

• あいまいな説明ではなく、データに含まれる実際の数値を使います
• 大きな数値は適切に丸めます（$1,234,567.89 -> $1.23M）
• emダッシュやenダッシュは使わず、代わりに--を使います
• ユーザーから詳細を求められない限り、回答全体を500語未満にします
• 調査結果が多い場合は、重要なものを上位5件まで取り上げ、「ほかにN件あります。必要であれば確認できます」と伝えます