tres-recon-gaps

TRES 对账差异技能

在 TRES Finance 中发现、分析和解决对账差异的端到端工作流。

---

准备工作：确认日期和资产范围

获取任何数据之前，先向用户确认两件事：

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 接受的是 [String]，而不是 [ID]。

为每一行计算：

fiatGap = reconciliation (token gap) × fiatValue.unitPrice

---

步骤 3 — 显示：始终呈现 HTML 仪表板

始终生成一个独立的 .html 文件作为主要输出，不要改用内嵌小组件。

阅读 references/html-template-notes.md，了解完整的视觉规范（字体、颜色、布局、列宽、模态框行为、API 调用机制）。

生成文件的关键要求：

• 深色金融仪表板风格（详见参考文件中的规范）
• 固定页眉，显示目标日期和刷新时间戳徽标
• 5 个摘要指标卡片：法币净差异、正差异数量、负差异数量、资产组数量、待处理交易数量
• 如果应用了资产筛选，则在工具栏中显示醒目的筛选徽标（例如 Filtered: ETH, USDC）
• 搜索 + 方向筛选 + 平台筛选工具栏
• 按资产分组的可折叠分区，按法币净差异绝对值降序排序
• 每行显示完整列集——最后一列包含两个复制提示词按钮：↳ Plug（蓝色）和 ⟳ Auto-fill（紫色）
• 点击任一按钮都会将可直接粘贴的提示词复制到剪贴板，并显示提示：“提示词已复制——请将其粘贴到 Claude 聊天中以解决此差异。”
• 不发送 HTTP 请求——HTML 只是纯展示界面；所有变更操作都由用户粘贴提示词后在 Claude 中完成

生成文件后，使用 present_files 呈现给用户。

---

步骤 4 — 操作（单次补账和自动填充）

用户通过从 HTML 仪表板复制提示词并粘贴到 Claude 聊天中来触发操作。Claude 收到其中一个提示词时，应立即执行相应的变更操作——无需再次确认（用户已在仪表板中选择了操作）。

单次补账（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 步 — 完成添加 Plug 后运行数据采集

用户表示已完成添加 Plug（例如“完成了”“就这些”“看起来不错”）后，运行数据采集以同步更新后的状态。

使用 triggerDataCollect mutation（或等效操作——如有需要，使用 get_schema_summary 检查 schema）：

mutation TriggerDataCollect {
  triggerDataCollect {
    success
    message
  }
}

完成后，告知用户：

“已触发数据采集 — TRES 现在将同步最新的链上余额。对账缺口很快就会更新。”

---

分组和排序逻辑

默认分组：按资产符号

• 将所有 asset.symbol 相同的行归为一组
• 在每组标题中显示净法币缺口
• 按净法币缺口的绝对值降序排列各组
• 在每组内按法币缺口的绝对值降序排列各行

替代方式：按钱包分组（如果用户提出要求）

• 按 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 字段（值相同，可靠性更高）
资产筛选结果为零行	告知用户：“[assets] 在 [date] 没有发现缺口”

---

关键 schema 事实（已验证）

• reconciliation 查询 — 有 endDate 参数；返回 gap 和基本余额字段
• assetBalance 查询 — 返回 historicalBalance、reconciliation（即 gap）和 fiatValue { value, unitPrice }；优先用于获取更丰富的数据
• assetBalance(id_In: [String]) — 注意是 [String]，不是 [ID]
• createPlug — belongsToId 为 ID!，assetId 为 ID!（传入 asset key 字符串）
• createReconciliationGapFillRule — internalAccountId 为 Int!；assetId 为 String!；interval 为 Interval! 枚举
• Platform 枚举值：ETHEREUM、BASE、ARBITRUM、OPTIMISM、POLYGON、AVAX、AVALANCHE_P_CHAIN、MANTRA 等。