> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nonce.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 迁移兼容性核对说明

> 需要结合现有集成核对的字段与行为。

本页补充[迁移指南](/zh/api-guide/v2/migration)中需要结合现有代码判断的行为。按实际使用的字段和筛选核对，无需为未使用的功能增加调用。

## 旧筛选参数的实际行为

v1 的 `offline` 会转为 `stale`。旧混合状态 `offline,error,low_hashrate,overheated,overpower,stale` 中，废弃的 health 值被忽略，因此原请求实际只保留 stale 条件。保持该请求的结果时使用 `status.in = ["stale"]`；要改为“所有异常矿机”，需另行定义异常条件。

旧 GET Miner 的 `search` 参数未参与筛选。迁移时不要将这个原来无效的参数自动转换成新的有效条件，否则结果可能变化。若业务原本需要搜索，应单独确认搜索的目标字段和匹配方式。

v2 的字段搜索为子串匹配，精确 MAC 的后处理必须覆盖所有候选页。旧 SN 搜索还可能匹配 hashboards 或 psus 的序列号，不能仅改成 `serial_number` 就认定等价。v2 SearchMiners 没有 `agent_id` 或 `unstable` 服务端筛选，相关用途需要独立核对数据来源和可实现方式。

## 摘要与详情字段

ListMiners 和 SearchMiners 不包含旧完整对象的所有字段。GetMiner 也不能直接提供 `errors`、`hashboards`、`pools`、`psus`、`hashrate_24h`、`reboot_count`、`low_uptime_reboot_count` 的完整替代。

`network`、`firmware_version`、`last_check_succeed`、`unstable_reason`、入口与出口温度、芯片数量等，需要逐字段核对详情契约。GetMiner 的 docs 公开状态也必须由当前 Reference 确认；本指南不将逐台详情查询视为大规模列表的默认替代。

Agent 列表中的嵌套 farm 信息可以通过 `farm_id` 关联。GetAgent 的 host 仅有 `hostname`、`platform`、`os`、`ip` 四项，不能假设它覆盖任意旧 host 对象。仅为补字段而遍历大量详情请求，还需要评估调用量。

发现影响现有功能的缺口时，记录旧字段、用途和对应页面或任务，并与 Nonce 团队确认支持方式。无法保持业务结果的改动不属于迁移完成。

## 授权与资源范围

ListWorkspaces 提供有效访问关系与权限，不是 `/me/grants` 的完整授权明细。跨 workspace 的 API key 请求取决于有效 grant 及其 farm 范围；OAuth 取决于用户 membership、角色和 farm scope。

迁移后的资源路径统一使用目标 workspace 和 farm。不能因为旧 URL 含 `/granted/`，就推断 v2 自动扩大了授权范围。认证失败、缺少权限和资源不可见分别核对，不按空数据处理。

## 任务结果与历史指标

任务详情中的 `result`、`error`、`log_download_url` 和 `log_file_size` 按新版响应定义读取。task batch 列表中的 `unsuccessful_count` 包含失败、超时和取消；详情的 `failed_count` 只表示执行失败。

历史指标在一个窗口内按升序返回完整网格。“最近 N 个时间桶”与“最近 N 条有数据的记录”需要不同处理。没有数据的时间段仍保留 `null`，算力保持 H/s，能量保持 kWh，金额按具体字段保持 USD 或 BTC。不同粒度下的可用指标需按 Reference 与实际用途核对。

历史接口最新的时间参数为 `from_time` 和 `to_time`。矿机列表搜索仍使用 `last_updated_at.gt/lt`；两者属于不同请求，不能全局替换字段名。