Collection 管理 API
管理项目的 Collection 元数据、Schema 定义和字段操作。Collection 是项目数据库中的"表"概念，支持树形结构组织（table + folder）。
基础路径
/projects/:projectId/collections认证方式
所有端点均需要 JWT Bearer Token 或 API Key 认证（combinedAuth 中间件）。
权限说明
请求者必须是项目所有者或项目所属团队的活跃成员。
端点列表
1. 获取 Collection 树结构
GET /projects/:projectId/collections获取项目的完整 Collection 树结构（包含 table 和 folder 的层级关系）。
Path 参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
projectId | string | 是 | 项目 ID |
响应 200
{
"databaseFolder": [
{
"key": "folder-xxx",
"label": "用户数据",
"type": "folder",
"children": [
{
"key": "table-xxx",
"label": "用户表",
"type": "table"
}
]
}
]
}错误码
| 状态码 | 说明 |
|---|---|
| 401 | 未认证 |
| 404 | 项目不存在或无权访问 |
| 500 | 获取 Collection 树失败 |
2. 创建 Collection
POST /projects/:projectId/collections创建一个新的 Collection（table 或 folder）。
Path 参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
projectId | string | 是 | 项目 ID |
Body 参数（JSON）
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
parentKey | string | null | 否 | 父节点 key，null 表示根目录 |
type | string | 是 | 类型：table 或 folder |
label | string | 是 | 显示名称 |
schema | object | 否 | 初始 Schema（仅 table 类型有效），格式 { fields: [...] } |
响应 201
返回创建的 Collection 节点信息。
错误码
| 状态码 | 说明 |
|---|---|
| 400 | 参数缺失或 type 值不合法 |
| 401 | 未认证 |
| 404 | 项目不存在、无权访问或父节点不存在 |
| 500 | 创建 Collection 失败 |
3. 获取单个 Collection 详情
GET /projects/:projectId/collections/:collectionId获取指定 Collection 的详细信息。
Path 参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
projectId | string | 是 | 项目 ID |
collectionId | string | 是 | Collection ID（key） |
响应 200
返回 Collection 节点详细信息。
错误码
| 状态码 | 说明 |
|---|---|
| 401 | 未认证 |
| 404 | 项目不存在、无权访问或 Collection 不存在 |
| 500 | 获取 Collection 失败 |
4. 更新 Collection
PATCH /projects/:projectId/collections/:collectionId更新 Collection 的名称或移动到其他父节点。
Path 参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
projectId | string | 是 | 项目 ID |
collectionId | string | 是 | Collection ID（key） |
Body 参数（JSON）
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
label | string | 否 | 新的显示名称 |
parentKey | string | null | 否 | 新的父节点 key，null 表示移到根目录 |
至少提供
label或parentKey之一。
响应 200
{
"databaseFolder": [ ... ]
}返回更新后的完整 Collection 树。
错误码
| 状态码 | 说明 |
|---|---|
| 400 | 未提供任何更新字段 |
| 401 | 未认证 |
| 404 | 项目不存在、无权访问或 Collection 不存在 |
| 500 | 更新 Collection 失败 |
5. 删除 Collection
DELETE /projects/:projectId/collections/:collectionId删除 Collection 及其关联的数据行（软删除）。
Path 参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
projectId | string | 是 | 项目 ID |
collectionId | string | 是 | Collection ID（key） |
响应 200
{
"success": true,
"deletedRows": 15
}错误码
| 状态码 | 说明 |
|---|---|
| 401 | 未认证 |
| 404 | 项目不存在、无权访问或 Collection 不存在 |
| 500 | 删除 Collection 失败 |
6. 获取 Schema
GET /projects/:projectId/collections/:collectionId/schema获取指定 Collection 的 Schema 定义。
Path 参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
projectId | string | 是 | 项目 ID |
collectionId | string | 是 | Collection ID（key） |
响应 200
{
"schema": {
"fields": [
{
"name": "title",
"type": "text",
"label": "标题",
"required": true
},
{
"name": "status",
"type": "select",
"label": "状态",
"options": ["draft", "published"]
}
]
}
}错误码
| 状态码 | 说明 |
|---|---|
| 400 | Collection 类型不是 table |
| 401 | 未认证 |
| 404 | 项目不存在、无权访问或 Collection 不存在 |
| 500 | 获取 Schema 失败 |
7. 替换 Schema
PUT /projects/:projectId/collections/:collectionId/schema完整替换 Collection 的 Schema 定义。支持传入迁移描述。
Path 参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
projectId | string | 是 | 项目 ID |
collectionId | string | 是 | Collection ID（key） |
Body 参数（JSON）
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
schema | object | 是 | 新的 Schema，格式 { fields: [...] } |
migrations | SchemaMigration[] | 否 | Schema 迁移描述列表 |
响应 200
返回更新后的 Schema 信息。
错误码
| 状态码 | 说明 |
|---|---|
| 400 | schema.fields 缺失或 Collection 类型不是 table |
| 401 | 未认证 |
| 404 | 项目不存在、无权访问或 Collection 不存在 |
| 500 | 更新 Schema 失败 |
8. 添加字段
POST /projects/:projectId/collections/:collectionId/fields向 Schema 中添加一个新字段。
Path 参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
projectId | string | 是 | 项目 ID |
collectionId | string | 是 | Collection ID（key） |
Body 参数（JSON）
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
field | object | 是 | 字段定义，必须包含 name（字段名）和 type（字段类型） |
响应 200
返回更新后的 Schema。
错误码
| 状态码 | 说明 |
|---|---|
| 400 | field.name 或 field.type 缺失 |
| 401 | 未认证 |
| 404 | 项目不存在、无权访问或 Collection 不存在 |
| 409 | 字段名已存在 |
| 500 | 添加字段失败 |
9. 更新字段
PATCH /projects/:projectId/collections/:collectionId/fields/:fieldName更新字段属性（不允许修改字段名 name）。
Path 参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
projectId | string | 是 | 项目 ID |
collectionId | string | 是 | Collection ID（key） |
fieldName | string | 是 | 字段名称 |
Body 参数（JSON）
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
updates | object | 是 | 需要更新的属性键值对（不含 name） |
响应 200
返回更新后的 Schema。
错误码
| 状态码 | 说明 |
|---|---|
| 400 | updates 缺失 |
| 401 | 未认证 |
| 404 | 项目不存在、无权访问、Collection 不存在或字段不存在 |
| 500 | 更新字段失败 |
10. 删除字段
DELETE /projects/:projectId/collections/:collectionId/fields/:fieldName从 Schema 中删除指定字段。
Path 参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
projectId | string | 是 | 项目 ID |
collectionId | string | 是 | Collection ID（key） |
fieldName | string | 是 | 字段名称 |
响应 200
返回更新后的 Schema。
错误码
| 状态码 | 说明 |
|---|---|
| 401 | 未认证 |
| 404 | 项目不存在、无权访问、Collection 不存在或字段不存在 |
| 500 | 删除字段失败 |
源码
- 路由：
apps/backend/src/routes/collections.ts - 服务：
apps/backend/src/services/collections.ts - 类型：
apps/backend/src/types/database.ts
补充端点
本节补充 plans/need-update-api.md 中尚未覆盖到 docs-site 的接口。端点标题保持严格的 METHOD /path 格式，便于后台文档覆盖率服务识别。
GET /projects/:projectId/collections/:collectionId/delete-preview
删除预览
认证：JWT Bearer Token 或 API Key（combinedAuth）。 路径参数
| 参数 | 说明 |
|---|---|
projectId | 项目 ID |
collectionId | Collection ID |
请求：无请求体。Query 参数用于分页、过滤、搜索或状态筛选；未传时按后端默认排序与分页返回。
响应：成功时返回目标资源详情、状态或配置对象。
常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。