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

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

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

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

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

- [POST /trademarks/search — 商标检索与冲突判定](/docs/openapi/searchTrademarks)
- [GET /trademarks — 商标档案查询](/docs/openapi/listTrademarks)
- [POST /designs/search — 外观设计检索](/docs/openapi/searchDesigns)
- [POST /reports — 排查报告](/docs/openapi/listReports)
- [GET /workbench/stats — 工作台统计](/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` 即为正式入口；
新增端点会先更新本规范再实现，保证「规范先行」。