# NebulaKB API 契约

当前契约版本：`2026-04-21`

## 响应包络

所有 JSON API 返回统一结构：

```json
{
  "code": 200,
  "message": "Success",
  "data": {}
}
```

分页 `data` 固定为：

```json
{
  "total": 0,
  "records": [],
  "current": 1,
  "size": 20
}
```

## 错误码

| 范围 | 用途 |
| --- | --- |
| `200-299` | 成功 |
| `400-499` | HTTP/客户端语义错误 |
| `500-599` | 服务端或兼容旧错误 |
| `1000-1099` | 用户与认证 |
| `3000-4999` | 业务域错误 |
| `5000-5999` | 校验/导入/迁移类错误 |

新增错误码要先登记到契约文档或对应域的 API 文档，再实现。

## 查询参数

- 分页：继续兼容路径参数 `current_page`、`page_size`。
- 排序：统一使用 `order_by`，降序使用 `-field_name`。
- 筛选：显式 query 参数优先，避免新增 opaque filter JSON。
- 字段命名：前后端统一 `snake_case`；历史字段保留兼容，新增字段不得混用 `camelCase`。

## 版本策略

现有 API 保持 v2 稳定。破坏性变更必须新增路径版本或新 endpoint，旧 endpoint 进入兼容期后再删除。

## 开发门禁

任何新增或变更 API，在开发前必须完成：

- 契约字段、错误码、分页、排序/筛选、版本策略确认。
- 前端调用方确认字段命名和空值语义。
- 最小回归路径：登录、工作空间、知识库、应用管理至少不被破坏。
