数据库 API

项目内置的轻量级数据库功能，提供数据行的增删改查、批量操作、回收站和导入导出。

基础路径

/projects/:projectId/data
/projects/:projectId/collections/:collectionId/export
/projects/:projectId/collections/:collectionId/template

认证方式

所有端点均需要 JWT Bearer Token 或 API Key 认证（combinedAuth 中间件）。

权限说明

请求者必须是项目所有者或项目所属团队的活跃成员。

端点列表

1. 查询数据列表

GET /projects/:projectId/data

分页查询指定 Collection 的数据，支持搜索和排序。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID

Query 参数

参数	类型	必填	默认值	说明
`collectionId`	string	是	-	Collection ID
`page`	number	否	`1`	页码
`pageSize`	number	否	`20`	每页条数（最大 100）
`sort`	string	否	`created_at`	排序字段
`order`	string	否	`desc`	排序方向：`asc` / `desc`
`search`	string	否	-	搜索关键词
`searchFields`	string	否	-	搜索字段，逗号分隔

响应 200

json

{
  "data": [
    {
      "id": "uuid",
      "project_id": "uuid",
      "team_id": "uuid",
      "collection_id": "string",
      "data": { "name": "示例", "email": "test@example.com" },
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ],
  "total": 100,
  "page": 1,
  "pageSize": 20
}

错误码

状态码	说明
400	`collectionId` 参数缺失
401	未认证
404	项目不存在或无权访问
500	查询数据失败

2. 获取回收站数据

GET /projects/:projectId/data/trash

获取已软删除的数据列表。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID

Query 参数

参数	类型	必填	说明
`collectionId`	string	是	Collection ID

响应 200

json

{
  "data": [ ... ]
}

错误码

状态码	说明
400	`collectionId` 参数缺失
401	未认证
404	项目不存在或无权访问
500	获取回收站数据失败

3. 统计数据条数

GET /projects/:projectId/data/count

统计数据总条数，可按 Collection 过滤。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID

Query 参数

参数	类型	必填	说明
`collectionId`	string	否	Collection ID。不传则统计整个项目

响应 200

json

{
  "count": 42
}

错误码

状态码	说明
401	未认证
404	项目不存在或无权访问
500	统计数据失败

4. 获取单条数据

GET /projects/:projectId/data/:id

根据 ID 获取单条数据记录。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID
`id`	string	是	数据记录 ID

响应 200

json

{
  "id": "uuid",
  "project_id": "uuid",
  "collection_id": "string",
  "data": { "name": "示例" },
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

错误码

状态码	说明
401	未认证
404	项目不存在、无权访问或数据不存在
500	获取数据失败

5. 创建数据

POST /projects/:projectId/data

在指定 Collection 中创建一条数据记录。支持唯一性约束检查和知识库工作流触发。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID

Body 参数（JSON）

参数	类型	必填	说明
`collectionId`	string	是	Collection ID
`data`	object	是	数据内容键值对
`uniqueFields`	string[]	否	需要检查唯一性的字段列表
`knowledgeBaseFields`	Array<{field, tag, content}>	否	触发知识库工作流的字段配置

响应 201

返回创建的数据记录。

错误码

状态码	说明
400	`collectionId` 缺失或 `data` 格式错误
401	未认证
404	项目不存在或无权访问
409	唯一性约束冲突，响应包含 `conflicts` 字段列表
500	创建数据失败

6. 更新数据

PATCH /projects/:projectId/data/:id

更新指定数据记录的内容。支持唯一性约束检查（排除自身）。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID
`id`	string	是	数据记录 ID

Body 参数（JSON）

参数	类型	必填	说明
`data`	object	是	需更新的数据键值对
`uniqueFields`	string[]	否	需要检查唯一性的字段列表

响应 200

返回更新后的数据记录。

错误码

状态码	说明
400	`data` 格式错误
401	未认证
404	项目不存在、无权访问或数据不存在
409	唯一性约束冲突
500	更新数据失败

7. 删除数据（软删除）

DELETE /projects/:projectId/data/:id

软删除指定数据记录（移入回收站）。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID
`id`	string	是	数据记录 ID

响应 200

json

{
  "success": true
}

错误码

状态码	说明
401	未认证
404	项目不存在、无权访问或数据不存在
500	删除数据失败

8. 批量导入数据

POST /projects/:projectId/data/batch-import

批量导入数据行，单次最多 1000 条。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID

Body 参数（JSON）

参数	类型	必填	说明
`collectionId`	string	是	Collection ID
`rows`	object[]	是	数据行数组，每项为键值对。非空数组，最多 1000 条

响应 200

返回导入结果统计。

错误码

状态码	说明
400	`collectionId` 缺失、`rows` 为空数组或超过 1000 条
401	未认证
404	项目不存在或无权访问
500	批量导入失败

9. 批量删除数据

POST /projects/:projectId/data/batch-delete

批量软删除指定 ID 的数据行。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID

Body 参数（JSON）

参数	类型	必填	说明
`ids`	string[]	是	要删除的数据 ID 数组（非空）

响应 200

json

{
  "success": true,
  "deleted": 5
}

错误码

状态码	说明
400	`ids` 为空数组
401	未认证
404	项目不存在或无权访问
500	批量删除失败

10. 恢复已删除的数据

POST /projects/:projectId/data/:id/restore

从回收站恢复指定数据记录。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID
`id`	string	是	数据记录 ID

响应 200

返回恢复后的数据记录。

错误码

状态码	说明
401	未认证
404	项目不存在或无权访问
500	恢复数据失败

11. 永久删除数据

DELETE /projects/:projectId/data/:id/permanent

永久删除数据记录（不可恢复）。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID
`id`	string	是	数据记录 ID

响应 200

json

{
  "success": true
}

错误码

状态码	说明
401	未认证
404	项目不存在或无权访问
500	永久删除失败

12. 导出数据

GET /projects/:projectId/collections/:collectionId/export

导出指定 Collection 的所有数据，支持 JSON 和 CSV 格式。最多导出 10000 条。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID
`collectionId`	string	是	Collection ID

Query 参数

参数	类型	必填	默认值	说明
`format`	string	否	`json`	导出格式：`json` / `csv`

响应 200

format=json：返回 JSON 数组，附带 Content-Disposition 下载头
format=csv：返回 CSV 文本，Content-Type: text/csv

错误码

状态码	说明
401	未认证
404	项目不存在或无权访问
500	导出数据失败

13. 下载导入模板

GET /projects/:projectId/collections/:collectionId/template

根据 Collection 的 Schema 生成导入模板文件。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID
`collectionId`	string	是	Collection ID

Query 参数

参数	类型	必填	默认值	说明
`format`	string	否	`json`	模板格式：`json` / `csv`
`schema`	string	否	-	Schema JSON 字符串（用于生成字段模板）

响应 200

format=json：返回 JSON 数组模板
format=csv：返回 CSV 模板（含表头和示例行）

错误码

状态码	说明
401	未认证
404	项目不存在或无权访问
500	生成模板失败

源码

路由：apps/backend/src/routes/database.ts
服务：apps/backend/src/services/database.ts
参考文档：数据库使用指南

数据库 API ​

基础路径 ​

认证方式 ​

权限说明 ​

端点列表 ​

1. 查询数据列表 ​

2. 获取回收站数据 ​

3. 统计数据条数 ​

4. 获取单条数据 ​

5. 创建数据 ​

6. 更新数据 ​

7. 删除数据（软删除） ​

8. 批量导入数据 ​

9. 批量删除数据 ​

10. 恢复已删除的数据 ​

11. 永久删除数据 ​

12. 导出数据 ​

13. 下载导入模板 ​

源码 ​

数据库 API

基础路径

认证方式

权限说明

端点列表

1. 查询数据列表

2. 获取回收站数据

3. 统计数据条数

4. 获取单条数据

5. 创建数据

6. 更新数据

7. 删除数据（软删除）

8. 批量导入数据

9. 批量删除数据

10. 恢复已删除的数据

11. 永久删除数据

12. 导出数据

13. 下载导入模板

源码