# 查端记录

## 标识符不要混用

- `uuid`：站内 USS 查端记录标识，如 `USS-20260925-ABCDEF123456`。不是 Minecraft/Mojang 账号 UUID，不证明账号所有权。
- `id`：记录的数据库资源 ID，用于组织详情接口。
- `player_name`：本次记录中的玩家名称；不能假定名称唯一或长期不变。

## 公开精确查询

```http
GET /v1/records/{uuid}
Authorization: Bearer YOUR_API_KEY
```

需要 `public:read`。`uuid` 必须是完整 `USS-YYYYMMDD-12位字母数字` 格式，比较时忽略大小写。不提供公开玩家名称搜索、模糊查询或公开全量枚举。

```json
{
  "ok": true,
  "data": {
    "id":"b2222222-2222-4222-8222-222222222222",
    "uuid":"USS-20260925-ABCDEF123456",
    "player_name":"ExamplePlayer",
    "game_category":"Minecraft",
    "game":"Example Server",
    "checked_at":"2026-09-25T03:00:00.000Z",
    "result":"clean",
    "result_label":"通过",
    "checker_name":"ExampleChecker",
    "public_notes":"本次查端公开说明。",
    "updated_at":"2026-09-25T03:05:00.000Z"
  },
  "request_id":"req_EXAMPLE"
}
```

| result | 含义 |
| --- | --- |
| `clean` | 本次查端通过 |
| `warning` | 可疑痕迹或警告，不应当作作弊的同义词 |
| `cheating` | 本次记录结论为作弊 |

未找到返回 `404 RECORD_NOT_FOUND`；格式不正确返回 `422 INVALID_RECORD_UUID`。

## 组织记录列表

```http
GET /v1/partners/{partner_id}/records?limit=20
```

需要组织密钥和 `records:read`。仅返回绑定组织的记录，字段与公开记录对象相同；组织内部备注和 SSer 备注不会因此开放。

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `limit` | integer | 1–100，默认 20 |
| `cursor` | string | 使用上次返回的 `next_cursor`，作为不透明值 URL 编码 |
| `updated_after` | ISO 8601 | 包含该时间起发生更新的记录，使用 `>=` 比较 |
| `result` | enum | clean / warning / cheating |
| `game` | enum | minecraft / fps |
| `player_name` | string | 1–120 字符，完整名称精确匹配，忽略大小写 |

```json
{"ok":true,"data":{"items":[],"next_cursor":null},"request_id":"req_EXAMPLE"}
```

空列表是成功结果，不是 404。未知筛选参数返回 422。Minecraft 对应 Minecraft 分类；其余受支持的查端游戏在此 API 中归入 fps 服务类别。

## 组织记录详情

```http
GET /v1/partners/{partner_id}/records/{record_id}
```

需要 `records:read`。返回一个记录对象。该记录不存在或不属于此组织时统一返回 `404 RECORD_NOT_FOUND`。

## 增量同步与更正

1. 首次遍历列表并以 `id` 保存记录。
2. 后续使用 `updated_after`，保留几分钟重叠窗口，按 ID 和更新时间合并。
3. 收到 `record.updated` 后重新请求详情，以最新数据替换原值。
4. 收到 `record.deleted` 后移除本地记录的可见性。它也可能代表记录被转移到其他组织；事件不会透露目标组织。
5. 定期完整核对：更新游标无法单独发现被删除的记录，Webhook 也有重试上限。

不要基于旧记录永久推断玩家当前状态。显示查端时间、结果来源和更正时间。删除后的记录详情可能立即返回 404，这是正常同步分支。