# OpenAPI 规范 (/docs/api-reference)

开放 API 的机器可读规范（OpenAPI 3.1）已随文档站发布，可直接导入 Apifox / Postman / Insomnia，
或用 openapi-generator 生成各语言 SDK。

- **规范文件**：[下载 openapi.yaml](https://docs.isud.cn/openapi.yaml) · [在线预览（Swagger Editor）](https://editor.swagger.io/?url=https://docs.isud.cn/openapi.yaml)
- **覆盖端点**：商标检索与档案、设计检索、排查报告、工作台统计（与后端 `/open/*` 一一对应）

## 端点参考 [#端点参考]

每个端点都有自动生成的交互式参考页（参数表、多语言请求示例、响应 Schema）：

- [POST /trademarks/search — 商标检索与冲突判定](https://docs.isud.cn/docs/openapi/searchTrademarks)
- [GET /trademarks — 商标档案查询](https://docs.isud.cn/docs/openapi/listTrademarks)
- [POST /designs/search — 外观设计检索](https://docs.isud.cn/docs/openapi/searchDesigns)
- [POST /reports — 排查报告](https://docs.isud.cn/docs/openapi/listReports)
- [GET /workbench/stats — 工作台统计](https://docs.isud.cn/docs/openapi/getWorkbenchStats)

## 写法说明 [#写法说明]

规范按业内商标数据 API 的通行惯例编写，并结合了本平台的实际实现：

| 惯例 | 本平台的落地 |
|---|---|
| 鉴权头 | `X-API-Key`（密钥 `lgr_live_` 前缀，创建时仅显示一次） |
| 响应信封 | `{ code, msg, data }`，`code="0000"` 成功 |
| 分页 | 请求 `current` / `size`，响应 `data.current/size/total/records` |
| 错误码 | `0001` 业务错误 · `9001` 参数错误 · `8889` 鉴权失败 |
| 计量 | search 类 10 点/次，其余 1 点/次，失败不扣点 |
| 时间 | 统一 Unix 毫秒时间戳，`0` 表示未知 |
| 枚举 | `status` / `riskLevel` 为开放枚举，新增值不视为破坏性变更 |
| 多语言 | 只存各局原始数据不翻译，与 Signa 的做法一致 |

## 与数据库的对应 [#与数据库的对应]

规范中的对象即 `ip_trademark` / `ip_design` / `ip_report` 表的对外视图：

- 幂等键 `externalId` = 各局官方登记号（如 EUIPO applicationNumber），可用于与官方数据 join；
- `niceClasses` / `locarnoClass` 与尼斯、洛迦诺分类表对应；
- `riskLevel` / `riskReason` 为平台侧冲突判定结果，随排查自动写入。

## 后续 [#后续]

生产环境上线后，`servers` 中的 `https://api.lagrange.so/v1` 即为正式入口；
新增端点会先更新本规范再实现，保证「规范先行」。


# 鉴权与密钥 (/docs/authentication)

**所有 API 调用使用 Bearer Token 鉴权，密钥挂在组织（org）上，成员共享组织密钥池。**

## 请求头 [#请求头]

```txt
Authorization: Bearer lgr_live_xxxxxxxx
X-Org-Id: <可选，仅平台密钥需要>
```

## 密钥模型 [#密钥模型]

| 属性 | 说明 |
|---|---|
| `key_prefix` | 密钥只存前 12 位用于展示与检索，完整密钥创建时唯一可见 |
| `scopes` | 逗号分隔的能力域：`search` `read` `watch` `compute` `draft` |
| `expires_at` | 可选 ISO 8601 日期，到期自动失效 |
| `rpm` / `daily_cap` | 每分钟请求数上限 / 单日点数上限 |

## 创建与管理 [#创建与管理]

密钥的创建、吊销、用量查看都在控制台完成（**API 密钥** 页）。管理操作不开放公开 API —— 密钥生灭必须走人工可审计的面板。

## 限速与错误 [#限速与错误]

| 状态码 | 含义 | 对策 |
|---|---|---|
| `401` | 密钥无效或已吊销 | 控制台确认密钥状态 |
| `403` | scope 不足 | 该密钥未授予对应能力域 |
| `429` | 触发 RPM / daily_cap | 响应带 `Retry-After`，按秒等待 |

<Callout type="warning" title="安全约定">

密钥即身份。不要放在前端代码、Git 仓库或日志里；泄露后在控制台**立即吊销**并新建 —— 吊销是即时生效的。

</Callout>


# 数据覆盖与新鲜度 (/docs/coverage)

**数据底座已归集 27 个商标局、136,970,301 条商标记录（约 1.3697 亿）。** 下表为 `svc_office_stat` 的真实统计（截至 2026-11-09），不是估算值；记录数按周对账。API v1 公测期间实际开放范围以控制台为准。

## 覆盖矩阵 [#覆盖矩阵]

| 代码 | 商标局 | 记录数 | 最近同步 |
|---|---|---:|---|
| CN | 中国 CNIPA | 9,030.8 万 | 2026-11-02 |
| US | 美国 USPTO | 1,441.7 万 | 2026-11-08 |
| BR | 巴西 INPI | 667.8 万 | 2026-11-07 |
| TW | 中国台湾 TIPO | 342.9 万 | 2026-11-04 |
| FR | 法国 INPI | 331.2 万 | 2026-10-30 |
| EM | 欧盟 EUIPO | 314.1 万 | 2026-10-30 |
| AU | 澳大利亚 IP Australia | 233.7 万 | 2026-10-28 |
| CA | 加拿大 CIPO | 219.2 万 | 2026-11-04 |
| ID | 印度尼西亚 DGIP | 197.7 万 | 2026-11-05 |
| TH | 泰国 DIP | 132.4 万 | 2026-11-08 |
| GB | 英国 UKIPO | 129.9 万 | 2026-11-04 |
| MY | 马来西亚 MyIPO | 114.0 万 | 2026-11-08 |
| VN | 越南 IP Viet Nam | 96.5 万 | 2026-11-07 |
| SG | 新加坡 IPOS | 88.1 万 | 2026-10-27 |
| PH | 菲律宾 IPOPHL | 77.7 万 | 2026-11-07 |
| SE | 瑞典 PRV | 60.0 万 | 2026-10-29 |
| NO | 挪威 NIPO | 58.0 万 | 2026-10-29 |
| HK | 中国香港 IPD | 34.3 万 | 2026-10-31 |
| CZ | 捷克 IPO CZ | 31.0 万 | 2026-11-07 |
| WO | WIPO 马德里 | 30.0 万 | 2026-11-05 |
| ES | 西班牙 OEPM | 20.0 万 | 2026-11-05 |
| KH | 柬埔寨 DIP | 15.7 万 | 2026-11-08 |
| EE | 爱沙尼亚 EPA | 12.9 万 | 2026-11-08 |
| LA | 老挝 DIP | 7.4 万 | 2026-11-07 |
| BN | 文莱 Brunei IPO | 6.3 万 | 2026-11-08 |
| MM | 缅甸 IPD | 2.2 万 | 2026-11-05 |
| JP | 日本 JPO | 1.4 万 | 2026-11-06 |
| **合计** | **27 局** | **13,697.0 万** | — |

## 一致性模型 [#一致性模型]

- 各局**独立同步**，跨局不保证同一时间快照；需要一致性判断时以 `synced_at` / `last_fetched_at` 为准
- 「最近同步」是该局最后一次成功抓取的日期，不等于全量重算日期
- `WO` 为 WIPO 马德里国际注册；对时间敏感的场景建议额外留出缓冲期

## 已知缺口 [#已知缺口]

- **灌库仍在进行**：`JP`、`MM`、`BN`、`LA` 等局记录量偏小，属增量接入早期，不代表该局官方总量
- **图样覆盖不均衡**：部分局的图样文件尚未完成归集，视觉相似检索暂不覆盖这些局
- **文本字段缺失**：少量历史记录没有 `mark_text`，纯文本检索可能漏召回，请结合申请号查询

<Callout type="warning" title="免责">

数据仅供参考，不构成法律意见。关键决策前请以官方登记簿为准（每条记录的 `office_url` 可直达官方页）。

</Callout>


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

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

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

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

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

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

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

</Callout>


# 文档总览 (/docs)

拉格朗日提供统一的商标数据 API：一次接入，即可检索、筛查与监控多个法域的商标记录。数据结构归一化、状态口径统一，并同时提供 OpenAPI 规范与 MCP Server。

## 从这里开始 [#从这里开始]

| 目标 | 页面 |
| --- | --- |
| 5 分钟拿到第一条检索结果 | [快速开始](https://docs.isud.cn/docs/quickstart) |
| 了解鉴权与密钥管理 | [鉴权与密钥](https://docs.isud.cn/docs/authentication) |
| 看清一条商标记录的结构 | [数据模型](https://docs.isud.cn/docs/data-model) |
| 理解各局状态的归一规则 | [状态体系](https://docs.isud.cn/docs/status-taxonomy) |
| 查检索与相似度筛查参数 | [商标检索](https://docs.isud.cn/docs/search) |
| 确认某法域的数据与更新节奏 | [数据覆盖与新鲜度](https://docs.isud.cn/docs/coverage) |
| 导入 Postman / 生成 SDK | [OpenAPI 规范](https://docs.isud.cn/docs/api-reference) |
| 接到 Claude Desktop / Cursor | [MCP Server](https://docs.isud.cn/docs/mcp-overview) |

## 给机器读的入口 [#给机器读的入口]

本站所有内容都以三种形式提供，方便爬虫与 AI Agent 直接消费：

- [`/llms.txt`](https://docs.isud.cn/llms.txt) — 全站页面索引（标题 + 链接 + 摘要）
- [`/llms-full.txt`](https://docs.isud.cn/llms-full.txt) — 全站 Markdown 合集，一次请求拿走全部正文
- 任意页面顶部的「复制 Markdown / 更多 AI 操作」按钮（可直接把本页送进 ChatGPT、Claude、Cursor），或把页面地址换成 `/llms.mdx/docs/<slug>/content.md`

<Callout type="info" title="鉴权与计费">

所有接口使用 API Key 鉴权，检索类 10 点/次、其余 1 点/次，失败请求不扣点。详见[鉴权与密钥](https://docs.isud.cn/docs/authentication)。

</Callout>

## 约定 [#约定]

- 响应统一信封 `{ code, msg, data }`，`code="0000"` 表示成功
- 时间统一为 Unix 毫秒时间戳，`0` 表示未知
- 分页请求 `current` / `size`，响应 `data.current/size/total/records`
- 只存各局原始数据不翻译，与官方登记号（`externalId`）可直接 join


# MCP Server (/docs/mcp-overview)

**把拉格朗日接到你的 AI Agent 里：Claude Desktop、Cursor、自建 Agent 开箱即用。** MCP 走与 REST 完全相同的鉴权与计费，失败请求 0 点。

## 接入配置 [#接入配置]

```json
{
  "mcpServers": {
    "lagrange": {
      "url": "https://mcp.lagrange.so",
      "headers": { "Authorization": "Bearer $LGR_KEY" }
    }
  }
}
```

## 工具地图 [#工具地图]

| 工具 | 计费 | 说明 |
|---|---|---|
| `search_trademarks` | 10 点/页 | 全文检索 + 过滤 |
| `get_trademark` | 1 点/条 | 单条详情（含事件） |
| `compute_similarity` | 10 点/项 | 五通道相似度 |
| `list_events` | 1 点/条 | 生命周期事件 |
| `create_watch` | 计入监控 | 建立监控任务 |
| `get_usage` | 0 点 | 查询本月用量 |

## 安全模型 [#安全模型]

**org 上下文从令牌来，从不是工具参数。** Agent 即使被提示注入诱导，也只能读到令牌所属组织的数据 —— 多租户隔离在服务端强制，不依赖模型行为。

## 建议用法 [#建议用法]

- 在 Claude Desktop 里直接问：「查一下 NOVA 在美国和欧盟的近似商标」
- 在 Cursor 里让 Agent 批量核查候选品牌名并输出风险表
- `readOnlyHint` 全覆盖：默认所有工具只读，写操作（监控创建）需显式 scope

<Callout type="info" title="参考">

工具 schema 与 REST 端点一一对应，参数语义见[商标检索](https://docs.isud.cn/docs/search)。

</Callout>


# 快速开始 (/docs/quickstart)

**数据底座已归集 27 个商标局、1.3697 亿条商标记录，一个 API Key 即可查询。** 本页带你 5 分钟内完成注册、鉴权并拿到第一条检索结果。API v1 公测期间实际开放范围以控制台为准。

## 1. 获取 API Key [#1-获取-api-key]

在[控制台](https://app.isud.cn/login)注册（即自动创建组织），进入 **API 密钥** 页创建密钥。密钥只在创建时完整显示一次，请立即保存：

```txt
lgr_live_a1b2c3d4e5f6...
```

<Callout type="info" title="免费额度">

Free 计划每月 1,000 点，无需绑卡。检索 10 点/页、详情 1 点/条、参考数据 0 点。

</Callout>

## 2. 第一次检索 [#2-第一次检索]

```bash
curl https://api.lagrange.so/v1/trademarks/search \
  -H "Authorization: Bearer $LGR_KEY" \
  -d '{
    "q": "LAGRANGE",
    "offices": ["US", "EM", "WO"],
    "similarity": ["identical", "fuzzy"],
    "nice_classes": [9, 42]
  }'
```

预期响应（真实结构，非省略）：

```json
{
  "total": 3,
  "results": [
    {
      "id": "tm_us_5821044",
      "mark_text": "LAGRANGIAN",
      "office": "US",
      "reg_no": "5821044",
      "status": { "primary": "registered", "stage": "live" },
      "nice_classes": [9],
      "similarity": { "tier": "similar", "via": "fuzzy", "score": 0.87 },
      "office_record_id": "5821044-US-REG-20260115",
      "office_url": "https://tmsearch.uspto.gov/..."
    }
  ],
  "page": { "size": 20, "number": 1 },
  "credits_charged": 10
}
```

## 3. 下一步 [#3-下一步]

- [鉴权与密钥](https://docs.isud.cn/docs/authentication)：scope、过期时间与密钥轮换
- [数据模型](https://docs.isud.cn/docs/data-model)：每条记录的字段语义
- [商标检索](https://docs.isud.cn/docs/search)：全部过滤参数与翻页

<Callout type="warning" title="约定">

- 布尔参数只接受 `true` / `false`，传 `"1"` 会返回 400
- 所有日期为 ISO 8601（`2026-10-31`），传时间戳会被拒绝
- 每个响应都带 `credits_charged`，失败请求不扣点

</Callout>


# 商标检索 (/docs/search)

**一个端点覆盖精确查询与相似度筛查：`POST /v1/trademarks/search`。** 检索 10 点/页，相似度计算另计 10 点/项。

## 基础检索 [#基础检索]

```bash
curl https://api.lagrange.so/v1/trademarks/search \
  -H "Authorization: Bearer $LGR_KEY" \
  -d '{ "q": "NOVA", "offices": ["US"], "limit": 20 }'
```

## 相似度筛查（排查场景） [#相似度筛查排查场景]

加 `similarity` 参数即启用五通道并行筛查，每条命中带解释：

```json
{
  "q": "KOMM",
  "offices": ["US", "EM"],
  "similarity": ["identical", "fuzzy", "embedded", "phonetic"]
}
```

```json
{
  "results": [
    { "mark_text": "KOMMI",  "similarity": { "tier": "near_identical", "via": "fuzzy", "score": 0.94 } },
    { "mark_text": "KOMMEL", "similarity": { "tier": "similar",       "via": "fuzzy", "score": 0.81 } }
  ]
}
```

- `tier`：风险分级（`identical` > `near_identical` > `similar` > `weak`）
- `via`：命中通道，用于解释为什么命中
- 长公共前缀有加权：`LAGRANGE` vs `LAGRANGIAN` 编辑距离 3，仍判 `near_identical`

## 过滤参数 [#过滤参数]

| 参数 | 类型 | 说明 |
|---|---|---|
| `q` | string | 商标名或申请人关键词 |
| `offices` | string[] | 法域过滤，缺省为全部 |
| `nice_classes` | int[] | 尼斯分类 |
| `status.stage` | string | `live` / `pending` / `dead` |
| `similarity` | string[] | 启用哪些相似度通道 |
| `limit` / `page` | int | 每页 ≤ 100，默认 20 |

<Callout type="info" title="枚举不全列">

完整法域代码、状态枚举与事件字典走参考端点（0 点）：`/v1/offices`、`/v1/status-codes`、`/v1/event-types`。

</Callout>

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

- lookalike（视觉相似）通道在内测中，尚未默认开启
- 单次检索窗口上限 10,000 行，深翻页请加过滤条件
- 不翻译：`mark_text` 存多语原文，请按原文检索

</Callout>


# 状态体系 (/docs/status-taxonomy)

**我们把 27 个商标局的原始状态归一化为四轴模型，跨局口径统一。** 不确定时永远查 API 拿权威字典（0 点）。

## 四轴模型 [#四轴模型]

| 轴 | 含义 | 示例 |
|---|---|---|
| `primary` | 当前主要法律状态 | `filed` `exam` `published` `registered` `rejected` `cancelled` `expired` |
| `stage` | 存续阶段 | `live` `pending` `dead` |
| `raw` | 各局原始状态原文 | `Notice of Allowance (Issued)` |
| `events` | 生命周期事件序列 | 申请 → 审查 → 公告 → 注册 → 续展 |

## 为什么不直接用原始状态 [#为什么不直接用原始状态]

同一件事在不同局叫法不同：USPTO 的 `LIVE` 与 EUIPO 的 `Registered` 都映射到 `primary: registered, stage: live`。统一口径让跨局筛查可以一条过滤写完：

```txt
status.primary=registered
status.stage=live
```

## 事件类型字典 [#事件类型字典]

常见 `event_type`（完整字典走 `GET /v1/status-codes`，0 点）：

| event_type | 触发 |
|---|---|
| `application_filed` | 提交申请 |
| `exam_report` | 审查意见 |
| `published` | 公告/公示 |
| `registered` | 注册 |
| `opposition_filed` | 被异议 |
| `renewed` | 续展 |
| `cancelled` / `expired` | 撤销 / 届满 |

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

- 历史事件在部分局首同步时缺失，从我们的同步起点开始完整
- `raw` 字段永远保留官方原文 —— 对口径有疑义时以原文为准

</Callout>


# 商标检索与冲突判定 (/docs/openapi/searchTrademarks)

{
  "openapi": "3.2.0",
  "info": {
    "title": "Lagrange Trademark Data API",
    "version": "1.0.0",
    "x-logo": {
      "altText": "拉格朗日 Lagrange"
    },
    "description": "拉格朗日商标数据开放 API —— 商标/外观设计排查、档案查询与排查报告的统一 REST 接口。\n\n## 约定（参考 Signa / EUIPO 开放规范的惯例，按本平台实际实现落地）\n- **鉴权**：所有请求携带 `X-API-Key` 请求头。密钥以 `lgr_live_` 开头，仅在创建时完整显示一次，\n  请从服务端调用，不要暴露在前端代码里。\n- **响应信封**：所有响应为 `{ code, msg, data }` 信封。`code = \"0000\"` 表示成功；\n  其余为业务错误（见下方 Errors）。分页接口的 `data` 为 `{ current, size, total, records }`。\n- **计费点数**：`search` 类接口每次扣 10 点，其余接口每次扣 1 点；**失败的请求不扣点**。\n  点数挂在组织级共享池上，可在客户控制台「用量」页按天/接口查看。\n- **多语言**：平台只存各商标局原始数据，不翻译（与 Signa 一致）；`markText`、`ownerName`\n  等字段保持原语言返回。\n- **日期**：请求/响应中的日期一律为 Unix 毫秒时间戳（int64），`0` 表示未知。\n- **枚举不穷举**：`status`（法律状态）与 `riskLevel`（风险等级）是开放枚举，\n  新增值不构成破坏性变更，客户端应按未知值兜底处理。\n\n## Errors\n| code | HTTP | 含义 |\n|---|---|---|\n| `0000` | 200 | 成功 |\n| `0001` | 200 | 通用业务错误（msg 说明原因） |\n| `9001` | 200 | 参数解析失败 |\n| `8889` | 200 | API 密钥缺失 / 无效 / 已禁用 / 已过期 / scope 不足 |\n\n> 说明：信封内 `code` 携带业务语义，HTTP 状态恒为 200（网关层错误除外）。\n\n## 数据模型说明\n字段与内部数据库（ip_trademark / ip_design / ip_report 表）的对外视图一一对应：\n幂等键为 `externalId`（各局官方登记号，如 EUIPO applicationNumber），\n`niceClasses` 为尼斯分类数组，`riskLevel` 为平台侧冲突判定结果。\n"
  },
  "externalDocs": {
    "url": "https://docs.isud.cn/",
    "description": "完整文档站（含快速开始与数据模型说明）"
  },
  "servers": [
    {
      "url": "https://api.isud.cn/api/v1/open",
      "description": "公网入口（v1 公测）"
    },
    {
      "url": "https://api.lagrange.so/v1",
      "description": "生产环境（规划中）"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "tags": [
    {
      "name": "Trademarks",
      "description": "商标排查与档案"
    },
    {
      "name": "Designs",
      "description": "外观设计排查"
    },
    {
      "name": "Reports",
      "description": "排查报告"
    },
    {
      "name": "Statistics",
      "description": "汇总统计"
    }
  ],
  "paths": {
    "/trademarks/search": {
      "post": {
        "tags": [
          "Trademarks"
        ],
        "operationId": "searchTrademarks",
        "summary": "商标检索与冲突判定",
        "description": "在指定法域内检索在先商标，执行相似度 + 尼斯分类重叠判定，\n返回冲突分级（high / medium / low）与整体结论。\n每次调用扣 10 点。传 `saveReport=true` 时生成排查报告并回传 `reportId`。\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TrademarkSearchRequest"
              },
              "examples": {
                "basic": {
                  "summary": "基础检索",
                  "value": {
                    "jurisdictionCode": "EU/EM",
                    "keyword": "LAGRANGE",
                    "niceClasses": [
                      "9",
                      "35",
                      "42"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "排查结果",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrademarkSearchResponse"
                },
                "examples": {
                  "conflict": {
                    "summary": "存在中度冲突",
                    "value": {
                      "code": "0000",
                      "msg": "成功",
                      "data": {
                        "jurisdictionCode": "EU/EM",
                        "keyword": "LAGRANGE",
                        "total": 3,
                        "highRisk": 0,
                        "mediumRisk": 1,
                        "lowRisk": 2,
                        "activeCount": 3,
                        "conclusion": "存在中度相似商标，建议进一步人工评估",
                        "source": "MOCK",
                        "elapsedMs": 42,
                        "items": [
                          {
                            "markText": "LAGRANGIAN",
                            "markType": "WORD",
                            "niceClasses": [
                              "9",
                              "42"
                            ],
                            "ownerName": "Example SA",
                            "status": "Registered",
                            "applicationNumber": "014591754",
                            "registrationNumber": "014591754",
                            "filingDate": 1443657600000,
                            "expiryDate": 1759276800000,
                            "riskLevel": "medium",
                            "riskReason": "长公共前缀 LAGRANG + 尼斯分类重叠",
                            "externalId": "014591754"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/trademarks": {
      "get": {
        "tags": [
          "Trademarks"
        ],
        "operationId": "listTrademarks",
        "summary": "分页查询商标档案",
        "parameters": [
          {
            "$ref": "#/components/parameters/Current"
          },
          {
            "$ref": "#/components/parameters/Size"
          },
          {
            "name": "keyword",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "综合关键字（文字/申请号/权利人）"
          },
          {
            "name": "markText",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "商标文字精确匹配"
          },
          {
            "name": "ownerName",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "权利人名称"
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "法律状态，如 Registered / Filed / Expired"
          },
          {
            "name": "niceClass",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "尼斯分类号，如 9"
          },
          {
            "name": "markType",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "商标类型 WORD / FIGURATIVE / COMBINED 等"
          },
          {
            "name": "riskLevel",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "风险等级 high / medium / low / none"
          },
          {
            "name": "jurisdictionId",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "法域 ID"
          }
        ],
        "responses": {
          "200": {
            "description": "分页结果",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "allOf": [
                            {
                              "$ref": "#/components/schemas/PageMeta"
                            },
                            {
                              "type": "object",
                              "properties": {
                                "records": {
                                  "type": "array",
                                  "items": {
                                    "$ref": "#/components/schemas/TrademarkItem"
                                  }
                                }
                              }
                            }
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/designs/search": {
      "post": {
        "tags": [
          "Designs"
        ],
        "operationId": "searchDesigns",
        "summary": "外观设计检索",
        "description": "按关键字与洛迦诺分类检索在先外观设计。每次调用扣 10 点。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DesignSearchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "排查结果",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DesignSearchResponse"
                }
              }
            }
          }
        }
      }
    },
    "/reports": {
      "get": {
        "tags": [
          "Reports"
        ],
        "operationId": "listReports",
        "summary": "分页查询排查报告",
        "parameters": [
          {
            "$ref": "#/components/parameters/Current"
          },
          {
            "$ref": "#/components/parameters/Size"
          }
        ],
        "responses": {
          "200": {
            "description": "分页结果",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "allOf": [
                            {
                              "$ref": "#/components/schemas/PageMeta"
                            },
                            {
                              "type": "object",
                              "properties": {
                                "records": {
                                  "type": "array",
                                  "items": {
                                    "$ref": "#/components/schemas/ReportItem"
                                  }
                                }
                              }
                            }
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/workbench/stats": {
      "get": {
        "tags": [
          "Statistics"
        ],
        "operationId": "getWorkbenchStats",
        "summary": "工作台汇总统计",
        "description": "商标/设计总量、名下资产、风险与监测、案件与期限等汇总计数。",
        "responses": {
          "200": {
            "description": "统计结果",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/WorkbenchStats"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "开放平台密钥，lgr_live_ 前缀，控制台创建，仅创建时完整展示一次。"
      }
    },
    "parameters": {
      "Current": {
        "name": "current",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "default": 1
        },
        "description": "页码，从 1 开始"
      },
      "Size": {
        "name": "size",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 10
        },
        "description": "每页条数"
      }
    },
    "schemas": {
      "Envelope": {
        "type": "object",
        "description": "通用响应信封",
        "required": [
          "code",
          "msg",
          "data"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "'0000' 成功；0001 业务错误；9001 参数错误；8889 鉴权失败",
            "examples": [
              "0000"
            ]
          },
          "msg": {
            "type": "string",
            "description": "人类可读消息"
          },
          "data": {
            "description": "业务数据，失败时为 null"
          }
        }
      },
      "PageMeta": {
        "type": "object",
        "properties": {
          "current": {
            "type": "integer",
            "examples": [
              1
            ]
          },
          "size": {
            "type": "integer",
            "examples": [
              10
            ]
          },
          "total": {
            "type": "integer",
            "format": "int64",
            "description": "总条数"
          }
        }
      },
      "TrademarkSearchRequest": {
        "type": "object",
        "required": [
          "jurisdictionCode",
          "keyword"
        ],
        "properties": {
          "jurisdictionCode": {
            "type": "string",
            "maxLength": 20,
            "description": "法域代码，如 EU/EM、US、CN",
            "examples": [
              "EU/EM"
            ]
          },
          "keyword": {
            "type": "string",
            "maxLength": 100,
            "description": "待排查的商标文字",
            "examples": [
              "LAGRANGE"
            ]
          },
          "niceClasses": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "意图申请的尼斯分类（字符串数组）"
          },
          "status": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "限定法律状态"
          },
          "owner": {
            "type": "string",
            "description": "限定权利人"
          },
          "intentMark": {
            "type": "string",
            "description": "意图商标（用于报告标题与对比基准）"
          },
          "intentClasses": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "saveReport": {
            "type": "boolean",
            "default": false,
            "description": "是否生成排查报告"
          },
          "reportTitle": {
            "type": "string",
            "description": "报告标题（saveReport=true 时可用）"
          }
        }
      },
      "TrademarkSearchResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Envelope"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/TrademarkSearchResult"
              }
            }
          }
        ]
      },
      "TrademarkSearchResult": {
        "type": "object",
        "properties": {
          "jurisdictionCode": {
            "type": "string",
            "examples": [
              "EU/EM"
            ]
          },
          "keyword": {
            "type": "string"
          },
          "total": {
            "type": "integer",
            "format": "int64",
            "description": "命中的在先商标总数"
          },
          "highRisk": {
            "type": "integer",
            "description": "高风险冲突数"
          },
          "mediumRisk": {
            "type": "integer",
            "description": "中风险冲突数"
          },
          "lowRisk": {
            "type": "integer",
            "description": "低风险冲突数"
          },
          "activeCount": {
            "type": "integer",
            "description": "有效（未失效）商标数"
          },
          "conclusion": {
            "type": "string",
            "description": "结论文案（服务端生成，可直接展示）"
          },
          "source": {
            "type": "string",
            "description": "数据来源连接器（MOCK / EUIPO_SANDBOX / EUIPO_PROD）"
          },
          "elapsedMs": {
            "type": "integer",
            "format": "int64"
          },
          "reportId": {
            "type": "integer",
            "description": "saveReport=true 时返回生成的报告 ID"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TrademarkItem"
            }
          }
        }
      },
      "TrademarkItem": {
        "type": "object",
        "description": "商标条目（对外稳定视图）",
        "properties": {
          "markText": {
            "type": "string",
            "description": "商标文字（原始语言，不翻译）"
          },
          "markType": {
            "type": "string",
            "description": "WORD / FIGURATIVE / COMBINED / 3D / COLOR / POSITION / SOUND / OTHER（开放枚举）"
          },
          "niceClasses": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "尼斯分类"
          },
          "ownerName": {
            "type": "string",
            "description": "当前权利人"
          },
          "status": {
            "type": "string",
            "description": "法律状态（开放枚举）：Filed / Published / Registered / Expired / Withdrawn / Refused / Opposed"
          },
          "applicationNumber": {
            "type": "string"
          },
          "registrationNumber": {
            "type": "string"
          },
          "filingDate": {
            "type": "integer",
            "format": "int64",
            "description": "Unix 毫秒，0 未知"
          },
          "registrationDate": {
            "type": "integer",
            "format": "int64"
          },
          "expiryDate": {
            "type": "integer",
            "format": "int64",
            "description": "有效期截止"
          },
          "riskLevel": {
            "type": "string",
            "description": "平台冲突判定：high / medium / low / none"
          },
          "riskReason": {
            "type": "string",
            "description": "判定说明（相似通道 + 分类重叠）"
          },
          "externalId": {
            "type": "string",
            "description": "各局官方 ID，幂等键，可用于与官方数据 join"
          }
        }
      },
      "DesignSearchRequest": {
        "type": "object",
        "required": [
          "jurisdictionCode",
          "keyword"
        ],
        "properties": {
          "jurisdictionCode": {
            "type": "string",
            "examples": [
              "EU/EM"
            ]
          },
          "keyword": {
            "type": "string",
            "maxLength": 100
          },
          "locarnoClasses": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "洛迦诺分类，如 '07'"
          },
          "status": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "owner": {
            "type": "string"
          },
          "saveReport": {
            "type": "boolean",
            "default": false
          },
          "reportTitle": {
            "type": "string"
          }
        }
      },
      "DesignSearchResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Envelope"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "jurisdictionCode": {
                    "type": "string"
                  },
                  "keyword": {
                    "type": "string"
                  },
                  "total": {
                    "type": "integer",
                    "format": "int64"
                  },
                  "conclusion": {
                    "type": "string"
                  },
                  "source": {
                    "type": "string"
                  },
                  "elapsedMs": {
                    "type": "integer",
                    "format": "int64"
                  },
                  "reportId": {
                    "type": "integer"
                  },
                  "items": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/DesignItem"
                    }
                  }
                }
              }
            }
          }
        ]
      },
      "DesignItem": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "设计名称"
          },
          "locarnoClass": {
            "type": "string",
            "description": "洛迦诺分类号"
          },
          "locarnoIndication": {
            "type": "string",
            "description": "分类说明"
          },
          "ownerName": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "description": "Registered / Expired / Withdrawn（开放枚举）"
          },
          "applicationNumber": {
            "type": "string"
          },
          "filingDate": {
            "type": "integer",
            "format": "int64"
          },
          "expiryDate": {
            "type": "integer",
            "format": "int64"
          },
          "externalId": {
            "type": "string",
            "description": "各局官方 ID，幂等键"
          }
        }
      },
      "ReportItem": {
        "type": "object",
        "properties": {
          "reportNo": {
            "type": "string",
            "description": "报告编号（RPT-*）"
          },
          "reportType": {
            "type": "string",
            "description": "trademark / design"
          },
          "title": {
            "type": "string"
          },
          "keyword": {
            "type": "string"
          },
          "riskLevel": {
            "type": "string",
            "description": "high / medium / low / none"
          },
          "conclusion": {
            "type": "string",
            "description": "safe / attention / conflict"
          },
          "totalResults": {
            "type": "integer"
          },
          "conflictCount": {
            "type": "integer"
          },
          "highRiskCount": {
            "type": "integer"
          },
          "createdAt": {
            "type": "integer",
            "format": "int64"
          }
        }
      },
      "WorkbenchStats": {
        "type": "object",
        "description": "工作台汇总（字段按后端实现返回，以下为核心计数）",
        "properties": {
          "trademarkTotal": {
            "type": "integer",
            "format": "int64",
            "description": "商标档案总量"
          },
          "trademarkOwned": {
            "type": "integer",
            "format": "int64",
            "description": "名下商标数"
          },
          "designTotal": {
            "type": "integer",
            "format": "int64",
            "description": "设计档案总量"
          },
          "highRiskTotal": {
            "type": "integer",
            "format": "int64",
            "description": "高风险商标数"
          },
          "watchActiveCount": {
            "type": "integer",
            "format": "int64",
            "description": "进行中监测任务数"
          },
          "watchDueCount": {
            "type": "integer",
            "format": "int64",
            "description": "到期待查监测数"
          },
          "caseActiveCount": {
            "type": "integer",
            "format": "int64",
            "description": "进行中案件数"
          },
          "deadlineDueCount": {
            "type": "integer",
            "format": "int64",
            "description": "7 日内到期期限数"
          },
          "deadlineOverdueCount": {
            "type": "integer",
            "format": "int64",
            "description": "已逾期期限数"
          }
        }
      }
    }
  }
}

# 分页查询商标档案 (/docs/openapi/listTrademarks)

{
  "openapi": "3.2.0",
  "info": {
    "title": "Lagrange Trademark Data API",
    "version": "1.0.0",
    "x-logo": {
      "altText": "拉格朗日 Lagrange"
    },
    "description": "拉格朗日商标数据开放 API —— 商标/外观设计排查、档案查询与排查报告的统一 REST 接口。\n\n## 约定（参考 Signa / EUIPO 开放规范的惯例，按本平台实际实现落地）\n- **鉴权**：所有请求携带 `X-API-Key` 请求头。密钥以 `lgr_live_` 开头，仅在创建时完整显示一次，\n  请从服务端调用，不要暴露在前端代码里。\n- **响应信封**：所有响应为 `{ code, msg, data }` 信封。`code = \"0000\"` 表示成功；\n  其余为业务错误（见下方 Errors）。分页接口的 `data` 为 `{ current, size, total, records }`。\n- **计费点数**：`search` 类接口每次扣 10 点，其余接口每次扣 1 点；**失败的请求不扣点**。\n  点数挂在组织级共享池上，可在客户控制台「用量」页按天/接口查看。\n- **多语言**：平台只存各商标局原始数据，不翻译（与 Signa 一致）；`markText`、`ownerName`\n  等字段保持原语言返回。\n- **日期**：请求/响应中的日期一律为 Unix 毫秒时间戳（int64），`0` 表示未知。\n- **枚举不穷举**：`status`（法律状态）与 `riskLevel`（风险等级）是开放枚举，\n  新增值不构成破坏性变更，客户端应按未知值兜底处理。\n\n## Errors\n| code | HTTP | 含义 |\n|---|---|---|\n| `0000` | 200 | 成功 |\n| `0001` | 200 | 通用业务错误（msg 说明原因） |\n| `9001` | 200 | 参数解析失败 |\n| `8889` | 200 | API 密钥缺失 / 无效 / 已禁用 / 已过期 / scope 不足 |\n\n> 说明：信封内 `code` 携带业务语义，HTTP 状态恒为 200（网关层错误除外）。\n\n## 数据模型说明\n字段与内部数据库（ip_trademark / ip_design / ip_report 表）的对外视图一一对应：\n幂等键为 `externalId`（各局官方登记号，如 EUIPO applicationNumber），\n`niceClasses` 为尼斯分类数组，`riskLevel` 为平台侧冲突判定结果。\n"
  },
  "externalDocs": {
    "url": "https://docs.isud.cn/",
    "description": "完整文档站（含快速开始与数据模型说明）"
  },
  "servers": [
    {
      "url": "https://api.isud.cn/api/v1/open",
      "description": "公网入口（v1 公测）"
    },
    {
      "url": "https://api.lagrange.so/v1",
      "description": "生产环境（规划中）"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "tags": [
    {
      "name": "Trademarks",
      "description": "商标排查与档案"
    },
    {
      "name": "Designs",
      "description": "外观设计排查"
    },
    {
      "name": "Reports",
      "description": "排查报告"
    },
    {
      "name": "Statistics",
      "description": "汇总统计"
    }
  ],
  "paths": {
    "/trademarks/search": {
      "post": {
        "tags": [
          "Trademarks"
        ],
        "operationId": "searchTrademarks",
        "summary": "商标检索与冲突判定",
        "description": "在指定法域内检索在先商标，执行相似度 + 尼斯分类重叠判定，\n返回冲突分级（high / medium / low）与整体结论。\n每次调用扣 10 点。传 `saveReport=true` 时生成排查报告并回传 `reportId`。\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TrademarkSearchRequest"
              },
              "examples": {
                "basic": {
                  "summary": "基础检索",
                  "value": {
                    "jurisdictionCode": "EU/EM",
                    "keyword": "LAGRANGE",
                    "niceClasses": [
                      "9",
                      "35",
                      "42"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "排查结果",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrademarkSearchResponse"
                },
                "examples": {
                  "conflict": {
                    "summary": "存在中度冲突",
                    "value": {
                      "code": "0000",
                      "msg": "成功",
                      "data": {
                        "jurisdictionCode": "EU/EM",
                        "keyword": "LAGRANGE",
                        "total": 3,
                        "highRisk": 0,
                        "mediumRisk": 1,
                        "lowRisk": 2,
                        "activeCount": 3,
                        "conclusion": "存在中度相似商标，建议进一步人工评估",
                        "source": "MOCK",
                        "elapsedMs": 42,
                        "items": [
                          {
                            "markText": "LAGRANGIAN",
                            "markType": "WORD",
                            "niceClasses": [
                              "9",
                              "42"
                            ],
                            "ownerName": "Example SA",
                            "status": "Registered",
                            "applicationNumber": "014591754",
                            "registrationNumber": "014591754",
                            "filingDate": 1443657600000,
                            "expiryDate": 1759276800000,
                            "riskLevel": "medium",
                            "riskReason": "长公共前缀 LAGRANG + 尼斯分类重叠",
                            "externalId": "014591754"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/trademarks": {
      "get": {
        "tags": [
          "Trademarks"
        ],
        "operationId": "listTrademarks",
        "summary": "分页查询商标档案",
        "parameters": [
          {
            "$ref": "#/components/parameters/Current"
          },
          {
            "$ref": "#/components/parameters/Size"
          },
          {
            "name": "keyword",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "综合关键字（文字/申请号/权利人）"
          },
          {
            "name": "markText",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "商标文字精确匹配"
          },
          {
            "name": "ownerName",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "权利人名称"
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "法律状态，如 Registered / Filed / Expired"
          },
          {
            "name": "niceClass",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "尼斯分类号，如 9"
          },
          {
            "name": "markType",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "商标类型 WORD / FIGURATIVE / COMBINED 等"
          },
          {
            "name": "riskLevel",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "风险等级 high / medium / low / none"
          },
          {
            "name": "jurisdictionId",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "法域 ID"
          }
        ],
        "responses": {
          "200": {
            "description": "分页结果",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "allOf": [
                            {
                              "$ref": "#/components/schemas/PageMeta"
                            },
                            {
                              "type": "object",
                              "properties": {
                                "records": {
                                  "type": "array",
                                  "items": {
                                    "$ref": "#/components/schemas/TrademarkItem"
                                  }
                                }
                              }
                            }
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/designs/search": {
      "post": {
        "tags": [
          "Designs"
        ],
        "operationId": "searchDesigns",
        "summary": "外观设计检索",
        "description": "按关键字与洛迦诺分类检索在先外观设计。每次调用扣 10 点。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DesignSearchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "排查结果",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DesignSearchResponse"
                }
              }
            }
          }
        }
      }
    },
    "/reports": {
      "get": {
        "tags": [
          "Reports"
        ],
        "operationId": "listReports",
        "summary": "分页查询排查报告",
        "parameters": [
          {
            "$ref": "#/components/parameters/Current"
          },
          {
            "$ref": "#/components/parameters/Size"
          }
        ],
        "responses": {
          "200": {
            "description": "分页结果",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "allOf": [
                            {
                              "$ref": "#/components/schemas/PageMeta"
                            },
                            {
                              "type": "object",
                              "properties": {
                                "records": {
                                  "type": "array",
                                  "items": {
                                    "$ref": "#/components/schemas/ReportItem"
                                  }
                                }
                              }
                            }
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/workbench/stats": {
      "get": {
        "tags": [
          "Statistics"
        ],
        "operationId": "getWorkbenchStats",
        "summary": "工作台汇总统计",
        "description": "商标/设计总量、名下资产、风险与监测、案件与期限等汇总计数。",
        "responses": {
          "200": {
            "description": "统计结果",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/WorkbenchStats"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "开放平台密钥，lgr_live_ 前缀，控制台创建，仅创建时完整展示一次。"
      }
    },
    "parameters": {
      "Current": {
        "name": "current",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "default": 1
        },
        "description": "页码，从 1 开始"
      },
      "Size": {
        "name": "size",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 10
        },
        "description": "每页条数"
      }
    },
    "schemas": {
      "Envelope": {
        "type": "object",
        "description": "通用响应信封",
        "required": [
          "code",
          "msg",
          "data"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "'0000' 成功；0001 业务错误；9001 参数错误；8889 鉴权失败",
            "examples": [
              "0000"
            ]
          },
          "msg": {
            "type": "string",
            "description": "人类可读消息"
          },
          "data": {
            "description": "业务数据，失败时为 null"
          }
        }
      },
      "PageMeta": {
        "type": "object",
        "properties": {
          "current": {
            "type": "integer",
            "examples": [
              1
            ]
          },
          "size": {
            "type": "integer",
            "examples": [
              10
            ]
          },
          "total": {
            "type": "integer",
            "format": "int64",
            "description": "总条数"
          }
        }
      },
      "TrademarkSearchRequest": {
        "type": "object",
        "required": [
          "jurisdictionCode",
          "keyword"
        ],
        "properties": {
          "jurisdictionCode": {
            "type": "string",
            "maxLength": 20,
            "description": "法域代码，如 EU/EM、US、CN",
            "examples": [
              "EU/EM"
            ]
          },
          "keyword": {
            "type": "string",
            "maxLength": 100,
            "description": "待排查的商标文字",
            "examples": [
              "LAGRANGE"
            ]
          },
          "niceClasses": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "意图申请的尼斯分类（字符串数组）"
          },
          "status": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "限定法律状态"
          },
          "owner": {
            "type": "string",
            "description": "限定权利人"
          },
          "intentMark": {
            "type": "string",
            "description": "意图商标（用于报告标题与对比基准）"
          },
          "intentClasses": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "saveReport": {
            "type": "boolean",
            "default": false,
            "description": "是否生成排查报告"
          },
          "reportTitle": {
            "type": "string",
            "description": "报告标题（saveReport=true 时可用）"
          }
        }
      },
      "TrademarkSearchResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Envelope"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/TrademarkSearchResult"
              }
            }
          }
        ]
      },
      "TrademarkSearchResult": {
        "type": "object",
        "properties": {
          "jurisdictionCode": {
            "type": "string",
            "examples": [
              "EU/EM"
            ]
          },
          "keyword": {
            "type": "string"
          },
          "total": {
            "type": "integer",
            "format": "int64",
            "description": "命中的在先商标总数"
          },
          "highRisk": {
            "type": "integer",
            "description": "高风险冲突数"
          },
          "mediumRisk": {
            "type": "integer",
            "description": "中风险冲突数"
          },
          "lowRisk": {
            "type": "integer",
            "description": "低风险冲突数"
          },
          "activeCount": {
            "type": "integer",
            "description": "有效（未失效）商标数"
          },
          "conclusion": {
            "type": "string",
            "description": "结论文案（服务端生成，可直接展示）"
          },
          "source": {
            "type": "string",
            "description": "数据来源连接器（MOCK / EUIPO_SANDBOX / EUIPO_PROD）"
          },
          "elapsedMs": {
            "type": "integer",
            "format": "int64"
          },
          "reportId": {
            "type": "integer",
            "description": "saveReport=true 时返回生成的报告 ID"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TrademarkItem"
            }
          }
        }
      },
      "TrademarkItem": {
        "type": "object",
        "description": "商标条目（对外稳定视图）",
        "properties": {
          "markText": {
            "type": "string",
            "description": "商标文字（原始语言，不翻译）"
          },
          "markType": {
            "type": "string",
            "description": "WORD / FIGURATIVE / COMBINED / 3D / COLOR / POSITION / SOUND / OTHER（开放枚举）"
          },
          "niceClasses": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "尼斯分类"
          },
          "ownerName": {
            "type": "string",
            "description": "当前权利人"
          },
          "status": {
            "type": "string",
            "description": "法律状态（开放枚举）：Filed / Published / Registered / Expired / Withdrawn / Refused / Opposed"
          },
          "applicationNumber": {
            "type": "string"
          },
          "registrationNumber": {
            "type": "string"
          },
          "filingDate": {
            "type": "integer",
            "format": "int64",
            "description": "Unix 毫秒，0 未知"
          },
          "registrationDate": {
            "type": "integer",
            "format": "int64"
          },
          "expiryDate": {
            "type": "integer",
            "format": "int64",
            "description": "有效期截止"
          },
          "riskLevel": {
            "type": "string",
            "description": "平台冲突判定：high / medium / low / none"
          },
          "riskReason": {
            "type": "string",
            "description": "判定说明（相似通道 + 分类重叠）"
          },
          "externalId": {
            "type": "string",
            "description": "各局官方 ID，幂等键，可用于与官方数据 join"
          }
        }
      },
      "DesignSearchRequest": {
        "type": "object",
        "required": [
          "jurisdictionCode",
          "keyword"
        ],
        "properties": {
          "jurisdictionCode": {
            "type": "string",
            "examples": [
              "EU/EM"
            ]
          },
          "keyword": {
            "type": "string",
            "maxLength": 100
          },
          "locarnoClasses": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "洛迦诺分类，如 '07'"
          },
          "status": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "owner": {
            "type": "string"
          },
          "saveReport": {
            "type": "boolean",
            "default": false
          },
          "reportTitle": {
            "type": "string"
          }
        }
      },
      "DesignSearchResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Envelope"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "jurisdictionCode": {
                    "type": "string"
                  },
                  "keyword": {
                    "type": "string"
                  },
                  "total": {
                    "type": "integer",
                    "format": "int64"
                  },
                  "conclusion": {
                    "type": "string"
                  },
                  "source": {
                    "type": "string"
                  },
                  "elapsedMs": {
                    "type": "integer",
                    "format": "int64"
                  },
                  "reportId": {
                    "type": "integer"
                  },
                  "items": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/DesignItem"
                    }
                  }
                }
              }
            }
          }
        ]
      },
      "DesignItem": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "设计名称"
          },
          "locarnoClass": {
            "type": "string",
            "description": "洛迦诺分类号"
          },
          "locarnoIndication": {
            "type": "string",
            "description": "分类说明"
          },
          "ownerName": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "description": "Registered / Expired / Withdrawn（开放枚举）"
          },
          "applicationNumber": {
            "type": "string"
          },
          "filingDate": {
            "type": "integer",
            "format": "int64"
          },
          "expiryDate": {
            "type": "integer",
            "format": "int64"
          },
          "externalId": {
            "type": "string",
            "description": "各局官方 ID，幂等键"
          }
        }
      },
      "ReportItem": {
        "type": "object",
        "properties": {
          "reportNo": {
            "type": "string",
            "description": "报告编号（RPT-*）"
          },
          "reportType": {
            "type": "string",
            "description": "trademark / design"
          },
          "title": {
            "type": "string"
          },
          "keyword": {
            "type": "string"
          },
          "riskLevel": {
            "type": "string",
            "description": "high / medium / low / none"
          },
          "conclusion": {
            "type": "string",
            "description": "safe / attention / conflict"
          },
          "totalResults": {
            "type": "integer"
          },
          "conflictCount": {
            "type": "integer"
          },
          "highRiskCount": {
            "type": "integer"
          },
          "createdAt": {
            "type": "integer",
            "format": "int64"
          }
        }
      },
      "WorkbenchStats": {
        "type": "object",
        "description": "工作台汇总（字段按后端实现返回，以下为核心计数）",
        "properties": {
          "trademarkTotal": {
            "type": "integer",
            "format": "int64",
            "description": "商标档案总量"
          },
          "trademarkOwned": {
            "type": "integer",
            "format": "int64",
            "description": "名下商标数"
          },
          "designTotal": {
            "type": "integer",
            "format": "int64",
            "description": "设计档案总量"
          },
          "highRiskTotal": {
            "type": "integer",
            "format": "int64",
            "description": "高风险商标数"
          },
          "watchActiveCount": {
            "type": "integer",
            "format": "int64",
            "description": "进行中监测任务数"
          },
          "watchDueCount": {
            "type": "integer",
            "format": "int64",
            "description": "到期待查监测数"
          },
          "caseActiveCount": {
            "type": "integer",
            "format": "int64",
            "description": "进行中案件数"
          },
          "deadlineDueCount": {
            "type": "integer",
            "format": "int64",
            "description": "7 日内到期期限数"
          },
          "deadlineOverdueCount": {
            "type": "integer",
            "format": "int64",
            "description": "已逾期期限数"
          }
        }
      }
    }
  }
}

# 外观设计检索 (/docs/openapi/searchDesigns)

{
  "openapi": "3.2.0",
  "info": {
    "title": "Lagrange Trademark Data API",
    "version": "1.0.0",
    "x-logo": {
      "altText": "拉格朗日 Lagrange"
    },
    "description": "拉格朗日商标数据开放 API —— 商标/外观设计排查、档案查询与排查报告的统一 REST 接口。\n\n## 约定（参考 Signa / EUIPO 开放规范的惯例，按本平台实际实现落地）\n- **鉴权**：所有请求携带 `X-API-Key` 请求头。密钥以 `lgr_live_` 开头，仅在创建时完整显示一次，\n  请从服务端调用，不要暴露在前端代码里。\n- **响应信封**：所有响应为 `{ code, msg, data }` 信封。`code = \"0000\"` 表示成功；\n  其余为业务错误（见下方 Errors）。分页接口的 `data` 为 `{ current, size, total, records }`。\n- **计费点数**：`search` 类接口每次扣 10 点，其余接口每次扣 1 点；**失败的请求不扣点**。\n  点数挂在组织级共享池上，可在客户控制台「用量」页按天/接口查看。\n- **多语言**：平台只存各商标局原始数据，不翻译（与 Signa 一致）；`markText`、`ownerName`\n  等字段保持原语言返回。\n- **日期**：请求/响应中的日期一律为 Unix 毫秒时间戳（int64），`0` 表示未知。\n- **枚举不穷举**：`status`（法律状态）与 `riskLevel`（风险等级）是开放枚举，\n  新增值不构成破坏性变更，客户端应按未知值兜底处理。\n\n## Errors\n| code | HTTP | 含义 |\n|---|---|---|\n| `0000` | 200 | 成功 |\n| `0001` | 200 | 通用业务错误（msg 说明原因） |\n| `9001` | 200 | 参数解析失败 |\n| `8889` | 200 | API 密钥缺失 / 无效 / 已禁用 / 已过期 / scope 不足 |\n\n> 说明：信封内 `code` 携带业务语义，HTTP 状态恒为 200（网关层错误除外）。\n\n## 数据模型说明\n字段与内部数据库（ip_trademark / ip_design / ip_report 表）的对外视图一一对应：\n幂等键为 `externalId`（各局官方登记号，如 EUIPO applicationNumber），\n`niceClasses` 为尼斯分类数组，`riskLevel` 为平台侧冲突判定结果。\n"
  },
  "externalDocs": {
    "url": "https://docs.isud.cn/",
    "description": "完整文档站（含快速开始与数据模型说明）"
  },
  "servers": [
    {
      "url": "https://api.isud.cn/api/v1/open",
      "description": "公网入口（v1 公测）"
    },
    {
      "url": "https://api.lagrange.so/v1",
      "description": "生产环境（规划中）"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "tags": [
    {
      "name": "Trademarks",
      "description": "商标排查与档案"
    },
    {
      "name": "Designs",
      "description": "外观设计排查"
    },
    {
      "name": "Reports",
      "description": "排查报告"
    },
    {
      "name": "Statistics",
      "description": "汇总统计"
    }
  ],
  "paths": {
    "/trademarks/search": {
      "post": {
        "tags": [
          "Trademarks"
        ],
        "operationId": "searchTrademarks",
        "summary": "商标检索与冲突判定",
        "description": "在指定法域内检索在先商标，执行相似度 + 尼斯分类重叠判定，\n返回冲突分级（high / medium / low）与整体结论。\n每次调用扣 10 点。传 `saveReport=true` 时生成排查报告并回传 `reportId`。\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TrademarkSearchRequest"
              },
              "examples": {
                "basic": {
                  "summary": "基础检索",
                  "value": {
                    "jurisdictionCode": "EU/EM",
                    "keyword": "LAGRANGE",
                    "niceClasses": [
                      "9",
                      "35",
                      "42"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "排查结果",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrademarkSearchResponse"
                },
                "examples": {
                  "conflict": {
                    "summary": "存在中度冲突",
                    "value": {
                      "code": "0000",
                      "msg": "成功",
                      "data": {
                        "jurisdictionCode": "EU/EM",
                        "keyword": "LAGRANGE",
                        "total": 3,
                        "highRisk": 0,
                        "mediumRisk": 1,
                        "lowRisk": 2,
                        "activeCount": 3,
                        "conclusion": "存在中度相似商标，建议进一步人工评估",
                        "source": "MOCK",
                        "elapsedMs": 42,
                        "items": [
                          {
                            "markText": "LAGRANGIAN",
                            "markType": "WORD",
                            "niceClasses": [
                              "9",
                              "42"
                            ],
                            "ownerName": "Example SA",
                            "status": "Registered",
                            "applicationNumber": "014591754",
                            "registrationNumber": "014591754",
                            "filingDate": 1443657600000,
                            "expiryDate": 1759276800000,
                            "riskLevel": "medium",
                            "riskReason": "长公共前缀 LAGRANG + 尼斯分类重叠",
                            "externalId": "014591754"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/trademarks": {
      "get": {
        "tags": [
          "Trademarks"
        ],
        "operationId": "listTrademarks",
        "summary": "分页查询商标档案",
        "parameters": [
          {
            "$ref": "#/components/parameters/Current"
          },
          {
            "$ref": "#/components/parameters/Size"
          },
          {
            "name": "keyword",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "综合关键字（文字/申请号/权利人）"
          },
          {
            "name": "markText",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "商标文字精确匹配"
          },
          {
            "name": "ownerName",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "权利人名称"
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "法律状态，如 Registered / Filed / Expired"
          },
          {
            "name": "niceClass",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "尼斯分类号，如 9"
          },
          {
            "name": "markType",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "商标类型 WORD / FIGURATIVE / COMBINED 等"
          },
          {
            "name": "riskLevel",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "风险等级 high / medium / low / none"
          },
          {
            "name": "jurisdictionId",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "法域 ID"
          }
        ],
        "responses": {
          "200": {
            "description": "分页结果",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "allOf": [
                            {
                              "$ref": "#/components/schemas/PageMeta"
                            },
                            {
                              "type": "object",
                              "properties": {
                                "records": {
                                  "type": "array",
                                  "items": {
                                    "$ref": "#/components/schemas/TrademarkItem"
                                  }
                                }
                              }
                            }
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/designs/search": {
      "post": {
        "tags": [
          "Designs"
        ],
        "operationId": "searchDesigns",
        "summary": "外观设计检索",
        "description": "按关键字与洛迦诺分类检索在先外观设计。每次调用扣 10 点。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DesignSearchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "排查结果",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DesignSearchResponse"
                }
              }
            }
          }
        }
      }
    },
    "/reports": {
      "get": {
        "tags": [
          "Reports"
        ],
        "operationId": "listReports",
        "summary": "分页查询排查报告",
        "parameters": [
          {
            "$ref": "#/components/parameters/Current"
          },
          {
            "$ref": "#/components/parameters/Size"
          }
        ],
        "responses": {
          "200": {
            "description": "分页结果",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "allOf": [
                            {
                              "$ref": "#/components/schemas/PageMeta"
                            },
                            {
                              "type": "object",
                              "properties": {
                                "records": {
                                  "type": "array",
                                  "items": {
                                    "$ref": "#/components/schemas/ReportItem"
                                  }
                                }
                              }
                            }
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/workbench/stats": {
      "get": {
        "tags": [
          "Statistics"
        ],
        "operationId": "getWorkbenchStats",
        "summary": "工作台汇总统计",
        "description": "商标/设计总量、名下资产、风险与监测、案件与期限等汇总计数。",
        "responses": {
          "200": {
            "description": "统计结果",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/WorkbenchStats"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "开放平台密钥，lgr_live_ 前缀，控制台创建，仅创建时完整展示一次。"
      }
    },
    "parameters": {
      "Current": {
        "name": "current",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "default": 1
        },
        "description": "页码，从 1 开始"
      },
      "Size": {
        "name": "size",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 10
        },
        "description": "每页条数"
      }
    },
    "schemas": {
      "Envelope": {
        "type": "object",
        "description": "通用响应信封",
        "required": [
          "code",
          "msg",
          "data"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "'0000' 成功；0001 业务错误；9001 参数错误；8889 鉴权失败",
            "examples": [
              "0000"
            ]
          },
          "msg": {
            "type": "string",
            "description": "人类可读消息"
          },
          "data": {
            "description": "业务数据，失败时为 null"
          }
        }
      },
      "PageMeta": {
        "type": "object",
        "properties": {
          "current": {
            "type": "integer",
            "examples": [
              1
            ]
          },
          "size": {
            "type": "integer",
            "examples": [
              10
            ]
          },
          "total": {
            "type": "integer",
            "format": "int64",
            "description": "总条数"
          }
        }
      },
      "TrademarkSearchRequest": {
        "type": "object",
        "required": [
          "jurisdictionCode",
          "keyword"
        ],
        "properties": {
          "jurisdictionCode": {
            "type": "string",
            "maxLength": 20,
            "description": "法域代码，如 EU/EM、US、CN",
            "examples": [
              "EU/EM"
            ]
          },
          "keyword": {
            "type": "string",
            "maxLength": 100,
            "description": "待排查的商标文字",
            "examples": [
              "LAGRANGE"
            ]
          },
          "niceClasses": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "意图申请的尼斯分类（字符串数组）"
          },
          "status": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "限定法律状态"
          },
          "owner": {
            "type": "string",
            "description": "限定权利人"
          },
          "intentMark": {
            "type": "string",
            "description": "意图商标（用于报告标题与对比基准）"
          },
          "intentClasses": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "saveReport": {
            "type": "boolean",
            "default": false,
            "description": "是否生成排查报告"
          },
          "reportTitle": {
            "type": "string",
            "description": "报告标题（saveReport=true 时可用）"
          }
        }
      },
      "TrademarkSearchResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Envelope"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/TrademarkSearchResult"
              }
            }
          }
        ]
      },
      "TrademarkSearchResult": {
        "type": "object",
        "properties": {
          "jurisdictionCode": {
            "type": "string",
            "examples": [
              "EU/EM"
            ]
          },
          "keyword": {
            "type": "string"
          },
          "total": {
            "type": "integer",
            "format": "int64",
            "description": "命中的在先商标总数"
          },
          "highRisk": {
            "type": "integer",
            "description": "高风险冲突数"
          },
          "mediumRisk": {
            "type": "integer",
            "description": "中风险冲突数"
          },
          "lowRisk": {
            "type": "integer",
            "description": "低风险冲突数"
          },
          "activeCount": {
            "type": "integer",
            "description": "有效（未失效）商标数"
          },
          "conclusion": {
            "type": "string",
            "description": "结论文案（服务端生成，可直接展示）"
          },
          "source": {
            "type": "string",
            "description": "数据来源连接器（MOCK / EUIPO_SANDBOX / EUIPO_PROD）"
          },
          "elapsedMs": {
            "type": "integer",
            "format": "int64"
          },
          "reportId": {
            "type": "integer",
            "description": "saveReport=true 时返回生成的报告 ID"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TrademarkItem"
            }
          }
        }
      },
      "TrademarkItem": {
        "type": "object",
        "description": "商标条目（对外稳定视图）",
        "properties": {
          "markText": {
            "type": "string",
            "description": "商标文字（原始语言，不翻译）"
          },
          "markType": {
            "type": "string",
            "description": "WORD / FIGURATIVE / COMBINED / 3D / COLOR / POSITION / SOUND / OTHER（开放枚举）"
          },
          "niceClasses": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "尼斯分类"
          },
          "ownerName": {
            "type": "string",
            "description": "当前权利人"
          },
          "status": {
            "type": "string",
            "description": "法律状态（开放枚举）：Filed / Published / Registered / Expired / Withdrawn / Refused / Opposed"
          },
          "applicationNumber": {
            "type": "string"
          },
          "registrationNumber": {
            "type": "string"
          },
          "filingDate": {
            "type": "integer",
            "format": "int64",
            "description": "Unix 毫秒，0 未知"
          },
          "registrationDate": {
            "type": "integer",
            "format": "int64"
          },
          "expiryDate": {
            "type": "integer",
            "format": "int64",
            "description": "有效期截止"
          },
          "riskLevel": {
            "type": "string",
            "description": "平台冲突判定：high / medium / low / none"
          },
          "riskReason": {
            "type": "string",
            "description": "判定说明（相似通道 + 分类重叠）"
          },
          "externalId": {
            "type": "string",
            "description": "各局官方 ID，幂等键，可用于与官方数据 join"
          }
        }
      },
      "DesignSearchRequest": {
        "type": "object",
        "required": [
          "jurisdictionCode",
          "keyword"
        ],
        "properties": {
          "jurisdictionCode": {
            "type": "string",
            "examples": [
              "EU/EM"
            ]
          },
          "keyword": {
            "type": "string",
            "maxLength": 100
          },
          "locarnoClasses": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "洛迦诺分类，如 '07'"
          },
          "status": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "owner": {
            "type": "string"
          },
          "saveReport": {
            "type": "boolean",
            "default": false
          },
          "reportTitle": {
            "type": "string"
          }
        }
      },
      "DesignSearchResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Envelope"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "jurisdictionCode": {
                    "type": "string"
                  },
                  "keyword": {
                    "type": "string"
                  },
                  "total": {
                    "type": "integer",
                    "format": "int64"
                  },
                  "conclusion": {
                    "type": "string"
                  },
                  "source": {
                    "type": "string"
                  },
                  "elapsedMs": {
                    "type": "integer",
                    "format": "int64"
                  },
                  "reportId": {
                    "type": "integer"
                  },
                  "items": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/DesignItem"
                    }
                  }
                }
              }
            }
          }
        ]
      },
      "DesignItem": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "设计名称"
          },
          "locarnoClass": {
            "type": "string",
            "description": "洛迦诺分类号"
          },
          "locarnoIndication": {
            "type": "string",
            "description": "分类说明"
          },
          "ownerName": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "description": "Registered / Expired / Withdrawn（开放枚举）"
          },
          "applicationNumber": {
            "type": "string"
          },
          "filingDate": {
            "type": "integer",
            "format": "int64"
          },
          "expiryDate": {
            "type": "integer",
            "format": "int64"
          },
          "externalId": {
            "type": "string",
            "description": "各局官方 ID，幂等键"
          }
        }
      },
      "ReportItem": {
        "type": "object",
        "properties": {
          "reportNo": {
            "type": "string",
            "description": "报告编号（RPT-*）"
          },
          "reportType": {
            "type": "string",
            "description": "trademark / design"
          },
          "title": {
            "type": "string"
          },
          "keyword": {
            "type": "string"
          },
          "riskLevel": {
            "type": "string",
            "description": "high / medium / low / none"
          },
          "conclusion": {
            "type": "string",
            "description": "safe / attention / conflict"
          },
          "totalResults": {
            "type": "integer"
          },
          "conflictCount": {
            "type": "integer"
          },
          "highRiskCount": {
            "type": "integer"
          },
          "createdAt": {
            "type": "integer",
            "format": "int64"
          }
        }
      },
      "WorkbenchStats": {
        "type": "object",
        "description": "工作台汇总（字段按后端实现返回，以下为核心计数）",
        "properties": {
          "trademarkTotal": {
            "type": "integer",
            "format": "int64",
            "description": "商标档案总量"
          },
          "trademarkOwned": {
            "type": "integer",
            "format": "int64",
            "description": "名下商标数"
          },
          "designTotal": {
            "type": "integer",
            "format": "int64",
            "description": "设计档案总量"
          },
          "highRiskTotal": {
            "type": "integer",
            "format": "int64",
            "description": "高风险商标数"
          },
          "watchActiveCount": {
            "type": "integer",
            "format": "int64",
            "description": "进行中监测任务数"
          },
          "watchDueCount": {
            "type": "integer",
            "format": "int64",
            "description": "到期待查监测数"
          },
          "caseActiveCount": {
            "type": "integer",
            "format": "int64",
            "description": "进行中案件数"
          },
          "deadlineDueCount": {
            "type": "integer",
            "format": "int64",
            "description": "7 日内到期期限数"
          },
          "deadlineOverdueCount": {
            "type": "integer",
            "format": "int64",
            "description": "已逾期期限数"
          }
        }
      }
    }
  }
}

# 分页查询排查报告 (/docs/openapi/listReports)

{
  "openapi": "3.2.0",
  "info": {
    "title": "Lagrange Trademark Data API",
    "version": "1.0.0",
    "x-logo": {
      "altText": "拉格朗日 Lagrange"
    },
    "description": "拉格朗日商标数据开放 API —— 商标/外观设计排查、档案查询与排查报告的统一 REST 接口。\n\n## 约定（参考 Signa / EUIPO 开放规范的惯例，按本平台实际实现落地）\n- **鉴权**：所有请求携带 `X-API-Key` 请求头。密钥以 `lgr_live_` 开头，仅在创建时完整显示一次，\n  请从服务端调用，不要暴露在前端代码里。\n- **响应信封**：所有响应为 `{ code, msg, data }` 信封。`code = \"0000\"` 表示成功；\n  其余为业务错误（见下方 Errors）。分页接口的 `data` 为 `{ current, size, total, records }`。\n- **计费点数**：`search` 类接口每次扣 10 点，其余接口每次扣 1 点；**失败的请求不扣点**。\n  点数挂在组织级共享池上，可在客户控制台「用量」页按天/接口查看。\n- **多语言**：平台只存各商标局原始数据，不翻译（与 Signa 一致）；`markText`、`ownerName`\n  等字段保持原语言返回。\n- **日期**：请求/响应中的日期一律为 Unix 毫秒时间戳（int64），`0` 表示未知。\n- **枚举不穷举**：`status`（法律状态）与 `riskLevel`（风险等级）是开放枚举，\n  新增值不构成破坏性变更，客户端应按未知值兜底处理。\n\n## Errors\n| code | HTTP | 含义 |\n|---|---|---|\n| `0000` | 200 | 成功 |\n| `0001` | 200 | 通用业务错误（msg 说明原因） |\n| `9001` | 200 | 参数解析失败 |\n| `8889` | 200 | API 密钥缺失 / 无效 / 已禁用 / 已过期 / scope 不足 |\n\n> 说明：信封内 `code` 携带业务语义，HTTP 状态恒为 200（网关层错误除外）。\n\n## 数据模型说明\n字段与内部数据库（ip_trademark / ip_design / ip_report 表）的对外视图一一对应：\n幂等键为 `externalId`（各局官方登记号，如 EUIPO applicationNumber），\n`niceClasses` 为尼斯分类数组，`riskLevel` 为平台侧冲突判定结果。\n"
  },
  "externalDocs": {
    "url": "https://docs.isud.cn/",
    "description": "完整文档站（含快速开始与数据模型说明）"
  },
  "servers": [
    {
      "url": "https://api.isud.cn/api/v1/open",
      "description": "公网入口（v1 公测）"
    },
    {
      "url": "https://api.lagrange.so/v1",
      "description": "生产环境（规划中）"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "tags": [
    {
      "name": "Trademarks",
      "description": "商标排查与档案"
    },
    {
      "name": "Designs",
      "description": "外观设计排查"
    },
    {
      "name": "Reports",
      "description": "排查报告"
    },
    {
      "name": "Statistics",
      "description": "汇总统计"
    }
  ],
  "paths": {
    "/trademarks/search": {
      "post": {
        "tags": [
          "Trademarks"
        ],
        "operationId": "searchTrademarks",
        "summary": "商标检索与冲突判定",
        "description": "在指定法域内检索在先商标，执行相似度 + 尼斯分类重叠判定，\n返回冲突分级（high / medium / low）与整体结论。\n每次调用扣 10 点。传 `saveReport=true` 时生成排查报告并回传 `reportId`。\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TrademarkSearchRequest"
              },
              "examples": {
                "basic": {
                  "summary": "基础检索",
                  "value": {
                    "jurisdictionCode": "EU/EM",
                    "keyword": "LAGRANGE",
                    "niceClasses": [
                      "9",
                      "35",
                      "42"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "排查结果",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrademarkSearchResponse"
                },
                "examples": {
                  "conflict": {
                    "summary": "存在中度冲突",
                    "value": {
                      "code": "0000",
                      "msg": "成功",
                      "data": {
                        "jurisdictionCode": "EU/EM",
                        "keyword": "LAGRANGE",
                        "total": 3,
                        "highRisk": 0,
                        "mediumRisk": 1,
                        "lowRisk": 2,
                        "activeCount": 3,
                        "conclusion": "存在中度相似商标，建议进一步人工评估",
                        "source": "MOCK",
                        "elapsedMs": 42,
                        "items": [
                          {
                            "markText": "LAGRANGIAN",
                            "markType": "WORD",
                            "niceClasses": [
                              "9",
                              "42"
                            ],
                            "ownerName": "Example SA",
                            "status": "Registered",
                            "applicationNumber": "014591754",
                            "registrationNumber": "014591754",
                            "filingDate": 1443657600000,
                            "expiryDate": 1759276800000,
                            "riskLevel": "medium",
                            "riskReason": "长公共前缀 LAGRANG + 尼斯分类重叠",
                            "externalId": "014591754"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/trademarks": {
      "get": {
        "tags": [
          "Trademarks"
        ],
        "operationId": "listTrademarks",
        "summary": "分页查询商标档案",
        "parameters": [
          {
            "$ref": "#/components/parameters/Current"
          },
          {
            "$ref": "#/components/parameters/Size"
          },
          {
            "name": "keyword",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "综合关键字（文字/申请号/权利人）"
          },
          {
            "name": "markText",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "商标文字精确匹配"
          },
          {
            "name": "ownerName",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "权利人名称"
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "法律状态，如 Registered / Filed / Expired"
          },
          {
            "name": "niceClass",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "尼斯分类号，如 9"
          },
          {
            "name": "markType",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "商标类型 WORD / FIGURATIVE / COMBINED 等"
          },
          {
            "name": "riskLevel",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "风险等级 high / medium / low / none"
          },
          {
            "name": "jurisdictionId",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "法域 ID"
          }
        ],
        "responses": {
          "200": {
            "description": "分页结果",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "allOf": [
                            {
                              "$ref": "#/components/schemas/PageMeta"
                            },
                            {
                              "type": "object",
                              "properties": {
                                "records": {
                                  "type": "array",
                                  "items": {
                                    "$ref": "#/components/schemas/TrademarkItem"
                                  }
                                }
                              }
                            }
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/designs/search": {
      "post": {
        "tags": [
          "Designs"
        ],
        "operationId": "searchDesigns",
        "summary": "外观设计检索",
        "description": "按关键字与洛迦诺分类检索在先外观设计。每次调用扣 10 点。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DesignSearchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "排查结果",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DesignSearchResponse"
                }
              }
            }
          }
        }
      }
    },
    "/reports": {
      "get": {
        "tags": [
          "Reports"
        ],
        "operationId": "listReports",
        "summary": "分页查询排查报告",
        "parameters": [
          {
            "$ref": "#/components/parameters/Current"
          },
          {
            "$ref": "#/components/parameters/Size"
          }
        ],
        "responses": {
          "200": {
            "description": "分页结果",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "allOf": [
                            {
                              "$ref": "#/components/schemas/PageMeta"
                            },
                            {
                              "type": "object",
                              "properties": {
                                "records": {
                                  "type": "array",
                                  "items": {
                                    "$ref": "#/components/schemas/ReportItem"
                                  }
                                }
                              }
                            }
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/workbench/stats": {
      "get": {
        "tags": [
          "Statistics"
        ],
        "operationId": "getWorkbenchStats",
        "summary": "工作台汇总统计",
        "description": "商标/设计总量、名下资产、风险与监测、案件与期限等汇总计数。",
        "responses": {
          "200": {
            "description": "统计结果",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/WorkbenchStats"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "开放平台密钥，lgr_live_ 前缀，控制台创建，仅创建时完整展示一次。"
      }
    },
    "parameters": {
      "Current": {
        "name": "current",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "default": 1
        },
        "description": "页码，从 1 开始"
      },
      "Size": {
        "name": "size",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 10
        },
        "description": "每页条数"
      }
    },
    "schemas": {
      "Envelope": {
        "type": "object",
        "description": "通用响应信封",
        "required": [
          "code",
          "msg",
          "data"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "'0000' 成功；0001 业务错误；9001 参数错误；8889 鉴权失败",
            "examples": [
              "0000"
            ]
          },
          "msg": {
            "type": "string",
            "description": "人类可读消息"
          },
          "data": {
            "description": "业务数据，失败时为 null"
          }
        }
      },
      "PageMeta": {
        "type": "object",
        "properties": {
          "current": {
            "type": "integer",
            "examples": [
              1
            ]
          },
          "size": {
            "type": "integer",
            "examples": [
              10
            ]
          },
          "total": {
            "type": "integer",
            "format": "int64",
            "description": "总条数"
          }
        }
      },
      "TrademarkSearchRequest": {
        "type": "object",
        "required": [
          "jurisdictionCode",
          "keyword"
        ],
        "properties": {
          "jurisdictionCode": {
            "type": "string",
            "maxLength": 20,
            "description": "法域代码，如 EU/EM、US、CN",
            "examples": [
              "EU/EM"
            ]
          },
          "keyword": {
            "type": "string",
            "maxLength": 100,
            "description": "待排查的商标文字",
            "examples": [
              "LAGRANGE"
            ]
          },
          "niceClasses": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "意图申请的尼斯分类（字符串数组）"
          },
          "status": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "限定法律状态"
          },
          "owner": {
            "type": "string",
            "description": "限定权利人"
          },
          "intentMark": {
            "type": "string",
            "description": "意图商标（用于报告标题与对比基准）"
          },
          "intentClasses": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "saveReport": {
            "type": "boolean",
            "default": false,
            "description": "是否生成排查报告"
          },
          "reportTitle": {
            "type": "string",
            "description": "报告标题（saveReport=true 时可用）"
          }
        }
      },
      "TrademarkSearchResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Envelope"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/TrademarkSearchResult"
              }
            }
          }
        ]
      },
      "TrademarkSearchResult": {
        "type": "object",
        "properties": {
          "jurisdictionCode": {
            "type": "string",
            "examples": [
              "EU/EM"
            ]
          },
          "keyword": {
            "type": "string"
          },
          "total": {
            "type": "integer",
            "format": "int64",
            "description": "命中的在先商标总数"
          },
          "highRisk": {
            "type": "integer",
            "description": "高风险冲突数"
          },
          "mediumRisk": {
            "type": "integer",
            "description": "中风险冲突数"
          },
          "lowRisk": {
            "type": "integer",
            "description": "低风险冲突数"
          },
          "activeCount": {
            "type": "integer",
            "description": "有效（未失效）商标数"
          },
          "conclusion": {
            "type": "string",
            "description": "结论文案（服务端生成，可直接展示）"
          },
          "source": {
            "type": "string",
            "description": "数据来源连接器（MOCK / EUIPO_SANDBOX / EUIPO_PROD）"
          },
          "elapsedMs": {
            "type": "integer",
            "format": "int64"
          },
          "reportId": {
            "type": "integer",
            "description": "saveReport=true 时返回生成的报告 ID"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TrademarkItem"
            }
          }
        }
      },
      "TrademarkItem": {
        "type": "object",
        "description": "商标条目（对外稳定视图）",
        "properties": {
          "markText": {
            "type": "string",
            "description": "商标文字（原始语言，不翻译）"
          },
          "markType": {
            "type": "string",
            "description": "WORD / FIGURATIVE / COMBINED / 3D / COLOR / POSITION / SOUND / OTHER（开放枚举）"
          },
          "niceClasses": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "尼斯分类"
          },
          "ownerName": {
            "type": "string",
            "description": "当前权利人"
          },
          "status": {
            "type": "string",
            "description": "法律状态（开放枚举）：Filed / Published / Registered / Expired / Withdrawn / Refused / Opposed"
          },
          "applicationNumber": {
            "type": "string"
          },
          "registrationNumber": {
            "type": "string"
          },
          "filingDate": {
            "type": "integer",
            "format": "int64",
            "description": "Unix 毫秒，0 未知"
          },
          "registrationDate": {
            "type": "integer",
            "format": "int64"
          },
          "expiryDate": {
            "type": "integer",
            "format": "int64",
            "description": "有效期截止"
          },
          "riskLevel": {
            "type": "string",
            "description": "平台冲突判定：high / medium / low / none"
          },
          "riskReason": {
            "type": "string",
            "description": "判定说明（相似通道 + 分类重叠）"
          },
          "externalId": {
            "type": "string",
            "description": "各局官方 ID，幂等键，可用于与官方数据 join"
          }
        }
      },
      "DesignSearchRequest": {
        "type": "object",
        "required": [
          "jurisdictionCode",
          "keyword"
        ],
        "properties": {
          "jurisdictionCode": {
            "type": "string",
            "examples": [
              "EU/EM"
            ]
          },
          "keyword": {
            "type": "string",
            "maxLength": 100
          },
          "locarnoClasses": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "洛迦诺分类，如 '07'"
          },
          "status": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "owner": {
            "type": "string"
          },
          "saveReport": {
            "type": "boolean",
            "default": false
          },
          "reportTitle": {
            "type": "string"
          }
        }
      },
      "DesignSearchResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Envelope"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "jurisdictionCode": {
                    "type": "string"
                  },
                  "keyword": {
                    "type": "string"
                  },
                  "total": {
                    "type": "integer",
                    "format": "int64"
                  },
                  "conclusion": {
                    "type": "string"
                  },
                  "source": {
                    "type": "string"
                  },
                  "elapsedMs": {
                    "type": "integer",
                    "format": "int64"
                  },
                  "reportId": {
                    "type": "integer"
                  },
                  "items": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/DesignItem"
                    }
                  }
                }
              }
            }
          }
        ]
      },
      "DesignItem": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "设计名称"
          },
          "locarnoClass": {
            "type": "string",
            "description": "洛迦诺分类号"
          },
          "locarnoIndication": {
            "type": "string",
            "description": "分类说明"
          },
          "ownerName": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "description": "Registered / Expired / Withdrawn（开放枚举）"
          },
          "applicationNumber": {
            "type": "string"
          },
          "filingDate": {
            "type": "integer",
            "format": "int64"
          },
          "expiryDate": {
            "type": "integer",
            "format": "int64"
          },
          "externalId": {
            "type": "string",
            "description": "各局官方 ID，幂等键"
          }
        }
      },
      "ReportItem": {
        "type": "object",
        "properties": {
          "reportNo": {
            "type": "string",
            "description": "报告编号（RPT-*）"
          },
          "reportType": {
            "type": "string",
            "description": "trademark / design"
          },
          "title": {
            "type": "string"
          },
          "keyword": {
            "type": "string"
          },
          "riskLevel": {
            "type": "string",
            "description": "high / medium / low / none"
          },
          "conclusion": {
            "type": "string",
            "description": "safe / attention / conflict"
          },
          "totalResults": {
            "type": "integer"
          },
          "conflictCount": {
            "type": "integer"
          },
          "highRiskCount": {
            "type": "integer"
          },
          "createdAt": {
            "type": "integer",
            "format": "int64"
          }
        }
      },
      "WorkbenchStats": {
        "type": "object",
        "description": "工作台汇总（字段按后端实现返回，以下为核心计数）",
        "properties": {
          "trademarkTotal": {
            "type": "integer",
            "format": "int64",
            "description": "商标档案总量"
          },
          "trademarkOwned": {
            "type": "integer",
            "format": "int64",
            "description": "名下商标数"
          },
          "designTotal": {
            "type": "integer",
            "format": "int64",
            "description": "设计档案总量"
          },
          "highRiskTotal": {
            "type": "integer",
            "format": "int64",
            "description": "高风险商标数"
          },
          "watchActiveCount": {
            "type": "integer",
            "format": "int64",
            "description": "进行中监测任务数"
          },
          "watchDueCount": {
            "type": "integer",
            "format": "int64",
            "description": "到期待查监测数"
          },
          "caseActiveCount": {
            "type": "integer",
            "format": "int64",
            "description": "进行中案件数"
          },
          "deadlineDueCount": {
            "type": "integer",
            "format": "int64",
            "description": "7 日内到期期限数"
          },
          "deadlineOverdueCount": {
            "type": "integer",
            "format": "int64",
            "description": "已逾期期限数"
          }
        }
      }
    }
  }
}

# 工作台汇总统计 (/docs/openapi/getWorkbenchStats)

{
  "openapi": "3.2.0",
  "info": {
    "title": "Lagrange Trademark Data API",
    "version": "1.0.0",
    "x-logo": {
      "altText": "拉格朗日 Lagrange"
    },
    "description": "拉格朗日商标数据开放 API —— 商标/外观设计排查、档案查询与排查报告的统一 REST 接口。\n\n## 约定（参考 Signa / EUIPO 开放规范的惯例，按本平台实际实现落地）\n- **鉴权**：所有请求携带 `X-API-Key` 请求头。密钥以 `lgr_live_` 开头，仅在创建时完整显示一次，\n  请从服务端调用，不要暴露在前端代码里。\n- **响应信封**：所有响应为 `{ code, msg, data }` 信封。`code = \"0000\"` 表示成功；\n  其余为业务错误（见下方 Errors）。分页接口的 `data` 为 `{ current, size, total, records }`。\n- **计费点数**：`search` 类接口每次扣 10 点，其余接口每次扣 1 点；**失败的请求不扣点**。\n  点数挂在组织级共享池上，可在客户控制台「用量」页按天/接口查看。\n- **多语言**：平台只存各商标局原始数据，不翻译（与 Signa 一致）；`markText`、`ownerName`\n  等字段保持原语言返回。\n- **日期**：请求/响应中的日期一律为 Unix 毫秒时间戳（int64），`0` 表示未知。\n- **枚举不穷举**：`status`（法律状态）与 `riskLevel`（风险等级）是开放枚举，\n  新增值不构成破坏性变更，客户端应按未知值兜底处理。\n\n## Errors\n| code | HTTP | 含义 |\n|---|---|---|\n| `0000` | 200 | 成功 |\n| `0001` | 200 | 通用业务错误（msg 说明原因） |\n| `9001` | 200 | 参数解析失败 |\n| `8889` | 200 | API 密钥缺失 / 无效 / 已禁用 / 已过期 / scope 不足 |\n\n> 说明：信封内 `code` 携带业务语义，HTTP 状态恒为 200（网关层错误除外）。\n\n## 数据模型说明\n字段与内部数据库（ip_trademark / ip_design / ip_report 表）的对外视图一一对应：\n幂等键为 `externalId`（各局官方登记号，如 EUIPO applicationNumber），\n`niceClasses` 为尼斯分类数组，`riskLevel` 为平台侧冲突判定结果。\n"
  },
  "externalDocs": {
    "url": "https://docs.isud.cn/",
    "description": "完整文档站（含快速开始与数据模型说明）"
  },
  "servers": [
    {
      "url": "https://api.isud.cn/api/v1/open",
      "description": "公网入口（v1 公测）"
    },
    {
      "url": "https://api.lagrange.so/v1",
      "description": "生产环境（规划中）"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "tags": [
    {
      "name": "Trademarks",
      "description": "商标排查与档案"
    },
    {
      "name": "Designs",
      "description": "外观设计排查"
    },
    {
      "name": "Reports",
      "description": "排查报告"
    },
    {
      "name": "Statistics",
      "description": "汇总统计"
    }
  ],
  "paths": {
    "/trademarks/search": {
      "post": {
        "tags": [
          "Trademarks"
        ],
        "operationId": "searchTrademarks",
        "summary": "商标检索与冲突判定",
        "description": "在指定法域内检索在先商标，执行相似度 + 尼斯分类重叠判定，\n返回冲突分级（high / medium / low）与整体结论。\n每次调用扣 10 点。传 `saveReport=true` 时生成排查报告并回传 `reportId`。\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TrademarkSearchRequest"
              },
              "examples": {
                "basic": {
                  "summary": "基础检索",
                  "value": {
                    "jurisdictionCode": "EU/EM",
                    "keyword": "LAGRANGE",
                    "niceClasses": [
                      "9",
                      "35",
                      "42"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "排查结果",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrademarkSearchResponse"
                },
                "examples": {
                  "conflict": {
                    "summary": "存在中度冲突",
                    "value": {
                      "code": "0000",
                      "msg": "成功",
                      "data": {
                        "jurisdictionCode": "EU/EM",
                        "keyword": "LAGRANGE",
                        "total": 3,
                        "highRisk": 0,
                        "mediumRisk": 1,
                        "lowRisk": 2,
                        "activeCount": 3,
                        "conclusion": "存在中度相似商标，建议进一步人工评估",
                        "source": "MOCK",
                        "elapsedMs": 42,
                        "items": [
                          {
                            "markText": "LAGRANGIAN",
                            "markType": "WORD",
                            "niceClasses": [
                              "9",
                              "42"
                            ],
                            "ownerName": "Example SA",
                            "status": "Registered",
                            "applicationNumber": "014591754",
                            "registrationNumber": "014591754",
                            "filingDate": 1443657600000,
                            "expiryDate": 1759276800000,
                            "riskLevel": "medium",
                            "riskReason": "长公共前缀 LAGRANG + 尼斯分类重叠",
                            "externalId": "014591754"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/trademarks": {
      "get": {
        "tags": [
          "Trademarks"
        ],
        "operationId": "listTrademarks",
        "summary": "分页查询商标档案",
        "parameters": [
          {
            "$ref": "#/components/parameters/Current"
          },
          {
            "$ref": "#/components/parameters/Size"
          },
          {
            "name": "keyword",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "综合关键字（文字/申请号/权利人）"
          },
          {
            "name": "markText",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "商标文字精确匹配"
          },
          {
            "name": "ownerName",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "权利人名称"
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "法律状态，如 Registered / Filed / Expired"
          },
          {
            "name": "niceClass",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "尼斯分类号，如 9"
          },
          {
            "name": "markType",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "商标类型 WORD / FIGURATIVE / COMBINED 等"
          },
          {
            "name": "riskLevel",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "风险等级 high / medium / low / none"
          },
          {
            "name": "jurisdictionId",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "法域 ID"
          }
        ],
        "responses": {
          "200": {
            "description": "分页结果",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "allOf": [
                            {
                              "$ref": "#/components/schemas/PageMeta"
                            },
                            {
                              "type": "object",
                              "properties": {
                                "records": {
                                  "type": "array",
                                  "items": {
                                    "$ref": "#/components/schemas/TrademarkItem"
                                  }
                                }
                              }
                            }
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/designs/search": {
      "post": {
        "tags": [
          "Designs"
        ],
        "operationId": "searchDesigns",
        "summary": "外观设计检索",
        "description": "按关键字与洛迦诺分类检索在先外观设计。每次调用扣 10 点。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DesignSearchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "排查结果",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DesignSearchResponse"
                }
              }
            }
          }
        }
      }
    },
    "/reports": {
      "get": {
        "tags": [
          "Reports"
        ],
        "operationId": "listReports",
        "summary": "分页查询排查报告",
        "parameters": [
          {
            "$ref": "#/components/parameters/Current"
          },
          {
            "$ref": "#/components/parameters/Size"
          }
        ],
        "responses": {
          "200": {
            "description": "分页结果",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "allOf": [
                            {
                              "$ref": "#/components/schemas/PageMeta"
                            },
                            {
                              "type": "object",
                              "properties": {
                                "records": {
                                  "type": "array",
                                  "items": {
                                    "$ref": "#/components/schemas/ReportItem"
                                  }
                                }
                              }
                            }
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/workbench/stats": {
      "get": {
        "tags": [
          "Statistics"
        ],
        "operationId": "getWorkbenchStats",
        "summary": "工作台汇总统计",
        "description": "商标/设计总量、名下资产、风险与监测、案件与期限等汇总计数。",
        "responses": {
          "200": {
            "description": "统计结果",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/WorkbenchStats"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "开放平台密钥，lgr_live_ 前缀，控制台创建，仅创建时完整展示一次。"
      }
    },
    "parameters": {
      "Current": {
        "name": "current",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "default": 1
        },
        "description": "页码，从 1 开始"
      },
      "Size": {
        "name": "size",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 10
        },
        "description": "每页条数"
      }
    },
    "schemas": {
      "Envelope": {
        "type": "object",
        "description": "通用响应信封",
        "required": [
          "code",
          "msg",
          "data"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "'0000' 成功；0001 业务错误；9001 参数错误；8889 鉴权失败",
            "examples": [
              "0000"
            ]
          },
          "msg": {
            "type": "string",
            "description": "人类可读消息"
          },
          "data": {
            "description": "业务数据，失败时为 null"
          }
        }
      },
      "PageMeta": {
        "type": "object",
        "properties": {
          "current": {
            "type": "integer",
            "examples": [
              1
            ]
          },
          "size": {
            "type": "integer",
            "examples": [
              10
            ]
          },
          "total": {
            "type": "integer",
            "format": "int64",
            "description": "总条数"
          }
        }
      },
      "TrademarkSearchRequest": {
        "type": "object",
        "required": [
          "jurisdictionCode",
          "keyword"
        ],
        "properties": {
          "jurisdictionCode": {
            "type": "string",
            "maxLength": 20,
            "description": "法域代码，如 EU/EM、US、CN",
            "examples": [
              "EU/EM"
            ]
          },
          "keyword": {
            "type": "string",
            "maxLength": 100,
            "description": "待排查的商标文字",
            "examples": [
              "LAGRANGE"
            ]
          },
          "niceClasses": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "意图申请的尼斯分类（字符串数组）"
          },
          "status": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "限定法律状态"
          },
          "owner": {
            "type": "string",
            "description": "限定权利人"
          },
          "intentMark": {
            "type": "string",
            "description": "意图商标（用于报告标题与对比基准）"
          },
          "intentClasses": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "saveReport": {
            "type": "boolean",
            "default": false,
            "description": "是否生成排查报告"
          },
          "reportTitle": {
            "type": "string",
            "description": "报告标题（saveReport=true 时可用）"
          }
        }
      },
      "TrademarkSearchResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Envelope"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/TrademarkSearchResult"
              }
            }
          }
        ]
      },
      "TrademarkSearchResult": {
        "type": "object",
        "properties": {
          "jurisdictionCode": {
            "type": "string",
            "examples": [
              "EU/EM"
            ]
          },
          "keyword": {
            "type": "string"
          },
          "total": {
            "type": "integer",
            "format": "int64",
            "description": "命中的在先商标总数"
          },
          "highRisk": {
            "type": "integer",
            "description": "高风险冲突数"
          },
          "mediumRisk": {
            "type": "integer",
            "description": "中风险冲突数"
          },
          "lowRisk": {
            "type": "integer",
            "description": "低风险冲突数"
          },
          "activeCount": {
            "type": "integer",
            "description": "有效（未失效）商标数"
          },
          "conclusion": {
            "type": "string",
            "description": "结论文案（服务端生成，可直接展示）"
          },
          "source": {
            "type": "string",
            "description": "数据来源连接器（MOCK / EUIPO_SANDBOX / EUIPO_PROD）"
          },
          "elapsedMs": {
            "type": "integer",
            "format": "int64"
          },
          "reportId": {
            "type": "integer",
            "description": "saveReport=true 时返回生成的报告 ID"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TrademarkItem"
            }
          }
        }
      },
      "TrademarkItem": {
        "type": "object",
        "description": "商标条目（对外稳定视图）",
        "properties": {
          "markText": {
            "type": "string",
            "description": "商标文字（原始语言，不翻译）"
          },
          "markType": {
            "type": "string",
            "description": "WORD / FIGURATIVE / COMBINED / 3D / COLOR / POSITION / SOUND / OTHER（开放枚举）"
          },
          "niceClasses": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "尼斯分类"
          },
          "ownerName": {
            "type": "string",
            "description": "当前权利人"
          },
          "status": {
            "type": "string",
            "description": "法律状态（开放枚举）：Filed / Published / Registered / Expired / Withdrawn / Refused / Opposed"
          },
          "applicationNumber": {
            "type": "string"
          },
          "registrationNumber": {
            "type": "string"
          },
          "filingDate": {
            "type": "integer",
            "format": "int64",
            "description": "Unix 毫秒，0 未知"
          },
          "registrationDate": {
            "type": "integer",
            "format": "int64"
          },
          "expiryDate": {
            "type": "integer",
            "format": "int64",
            "description": "有效期截止"
          },
          "riskLevel": {
            "type": "string",
            "description": "平台冲突判定：high / medium / low / none"
          },
          "riskReason": {
            "type": "string",
            "description": "判定说明（相似通道 + 分类重叠）"
          },
          "externalId": {
            "type": "string",
            "description": "各局官方 ID，幂等键，可用于与官方数据 join"
          }
        }
      },
      "DesignSearchRequest": {
        "type": "object",
        "required": [
          "jurisdictionCode",
          "keyword"
        ],
        "properties": {
          "jurisdictionCode": {
            "type": "string",
            "examples": [
              "EU/EM"
            ]
          },
          "keyword": {
            "type": "string",
            "maxLength": 100
          },
          "locarnoClasses": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "洛迦诺分类，如 '07'"
          },
          "status": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "owner": {
            "type": "string"
          },
          "saveReport": {
            "type": "boolean",
            "default": false
          },
          "reportTitle": {
            "type": "string"
          }
        }
      },
      "DesignSearchResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Envelope"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "jurisdictionCode": {
                    "type": "string"
                  },
                  "keyword": {
                    "type": "string"
                  },
                  "total": {
                    "type": "integer",
                    "format": "int64"
                  },
                  "conclusion": {
                    "type": "string"
                  },
                  "source": {
                    "type": "string"
                  },
                  "elapsedMs": {
                    "type": "integer",
                    "format": "int64"
                  },
                  "reportId": {
                    "type": "integer"
                  },
                  "items": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/DesignItem"
                    }
                  }
                }
              }
            }
          }
        ]
      },
      "DesignItem": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "设计名称"
          },
          "locarnoClass": {
            "type": "string",
            "description": "洛迦诺分类号"
          },
          "locarnoIndication": {
            "type": "string",
            "description": "分类说明"
          },
          "ownerName": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "description": "Registered / Expired / Withdrawn（开放枚举）"
          },
          "applicationNumber": {
            "type": "string"
          },
          "filingDate": {
            "type": "integer",
            "format": "int64"
          },
          "expiryDate": {
            "type": "integer",
            "format": "int64"
          },
          "externalId": {
            "type": "string",
            "description": "各局官方 ID，幂等键"
          }
        }
      },
      "ReportItem": {
        "type": "object",
        "properties": {
          "reportNo": {
            "type": "string",
            "description": "报告编号（RPT-*）"
          },
          "reportType": {
            "type": "string",
            "description": "trademark / design"
          },
          "title": {
            "type": "string"
          },
          "keyword": {
            "type": "string"
          },
          "riskLevel": {
            "type": "string",
            "description": "high / medium / low / none"
          },
          "conclusion": {
            "type": "string",
            "description": "safe / attention / conflict"
          },
          "totalResults": {
            "type": "integer"
          },
          "conflictCount": {
            "type": "integer"
          },
          "highRiskCount": {
            "type": "integer"
          },
          "createdAt": {
            "type": "integer",
            "format": "int64"
          }
        }
      },
      "WorkbenchStats": {
        "type": "object",
        "description": "工作台汇总（字段按后端实现返回，以下为核心计数）",
        "properties": {
          "trademarkTotal": {
            "type": "integer",
            "format": "int64",
            "description": "商标档案总量"
          },
          "trademarkOwned": {
            "type": "integer",
            "format": "int64",
            "description": "名下商标数"
          },
          "designTotal": {
            "type": "integer",
            "format": "int64",
            "description": "设计档案总量"
          },
          "highRiskTotal": {
            "type": "integer",
            "format": "int64",
            "description": "高风险商标数"
          },
          "watchActiveCount": {
            "type": "integer",
            "format": "int64",
            "description": "进行中监测任务数"
          },
          "watchDueCount": {
            "type": "integer",
            "format": "int64",
            "description": "到期待查监测数"
          },
          "caseActiveCount": {
            "type": "integer",
            "format": "int64",
            "description": "进行中案件数"
          },
          "deadlineDueCount": {
            "type": "integer",
            "format": "int64",
            "description": "7 日内到期期限数"
          },
          "deadlineOverdueCount": {
            "type": "integer",
            "format": "int64",
            "description": "已逾期期限数"
          }
        }
      }
    }
  }
}