# 数据模型 (/docs/data-model)

**每条商标记录 = 四轴状态 + 溯源四件套 + 多语原文。** 各局原始数据差异很大，我们归一化到统一结构后再对外。

## Trademark 对象 [#trademark-对象]

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | string | 内部 ID，`tm_{office}_{external_id}` |
| `mark_text` | string | 商标文字（多语原文，**不翻译**，带 `lang` 标注） |
| `office` | string | 商标局代码（27 局开放枚举，完整列表见[数据覆盖与新鲜度](/docs/coverage)或 `/v1/offices`）：`CN` `US` `EM` `WO` `TW` `HK` … |
| `reg_no` / `app_no` | string | 注册号 / 申请号（官方原始编号） |
| `status` | object | 四轴状态，见[状态体系](/docs/status-taxonomy) |
| `nice_classes` | int[] | 尼斯分类 |
| `owners` | object[] | 权利人（名称原文 + 国别） |
| `img_url` | string\|null | 图样 URL（按局覆盖率不同，见[数据覆盖](/docs/coverage)） |

## 溯源四件套 [#溯源四件套]

每条记录都可以回溯到官方原始数据：

```json
{
  "office_record_id": "5821044-US-REG-20260115",
  "office_url": "https://tmsearch.uspto.gov/...",
  "source": "uspto-bulk-20261030",
  "synced_at": "2026-10-30T22:14:03Z"
}
```

`office_record_id` + `office_url` 让你随时与官方系统按登记号 join；`source` 标明数据来自哪一次同步批次。

## 事件（Events） [#事件events]

生命周期事件以 `raw → event_type` 映射存储，官方原文永远保留：

```json
{
  "event_type": "registered",
  "date": "2026-01-15",
  "raw": "Notice of Registration issued"
}
```

事件字典与各局映射见[状态体系](/docs/status-taxonomy)。

<Callout type="warning" title="已知限制">

- 老的国际注册（IR）领地覆盖偏薄（如 IR 1000000 仅 CH 领地）—— 新 IR 记录完整
- 部分局的历史事件首同步可能缺失，事件流从同步起点开始
- `mark_text` 为 `null` 表示 designation 单腿记录，链接不完整

</Callout>