OpenAPI 规范
OpenAPI 3.1 规范下载与导入说明，覆盖商标检索、设计检索、报告与统计端点。
开放 API 的机器可读规范（OpenAPI 3.1）已随文档站发布，可直接导入 Apifox / Postman / Insomnia， 或用 openapi-generator 生成各语言 SDK。
- 规范文件：下载 openapi.yaml · 在线预览（Swagger Editor）
- 覆盖端点：商标检索与档案、设计检索、排查报告、工作台统计（与后端
/open/*一一对应）
端点参考
每个端点都有自动生成的交互式参考页（参数表、多语言请求示例、响应 Schema）：
- POST /trademarks/search — 商标检索与冲突判定
- GET /trademarks — 商标档案查询
- POST /designs/search — 外观设计检索
- POST /reports — 排查报告
- GET /workbench/stats — 工作台统计
写法说明
规范按业内商标数据 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 即为正式入口；
新增端点会先更新本规范再实现，保证「规范先行」。