项目管理 API
项目路由聚合模块，整合所有项目相关的子路由。
基础路径
/projects子模块索引
所有子路由均挂载在 /projects 前缀下，通过 /:projectId 区分项目。
| 子模块 | 路径前缀 | 端点数 | 说明 | 文档 |
|---|---|---|---|---|
| 项目密钥 | /:projectId/secrets | 5 | 密钥的增删改查 + 密钥名称列表 | project-secrets |
| JOJO 网络草稿 | /:projectId/networks | 3 | 创建/保存/重开，仅用户 JWT | project-networks |
| MCP 服务 | /:projectId/mcp | 1 | MCP 服务连通性检测 | mcp |
| 数据库 | /:projectId/data | 12 | 数据行 CRUD、批量操作、回收站、导入导出 | database |
| Collection | /:projectId/collections | 10 | Collection 元数据、Schema、字段管理 | collections |
| 知识库 | /:projectId/kb | 20 | 节点 CRUD、向量操作、边操作、标签、搜索 | knowledge-base |
| Release | /:projectId/releases | 13 | Release CRUD、版本管理、别名管理 | releases |
| 文件存储 | /storage/:projectId | 8 | 文件上传/下载/删除、签名 URL、文件夹 | storage |
| 定时任务 | /:projectId/schedules | - | 定时任务管理（独立文档） | - |
| Slug 解析 | /by-slug | 1 | 按 team slug + project slug 解析 UUID（路由 guard 专用，仅 JWT） | projects-by-slug |
认证方式
各子路由的认证方式以对应端点为准。多数项目管理子模块使用 combinedAuth，接受其配置的 JWT、API Key 等凭证；GET /projects 另支持持有 projects:read Scope 的 OAuth access token。
- JWT Bearer Token - 通过
Authorization: Bearer <token>请求头 - API Key - 通过
Authorization: Bearer <api_key>请求头 - Agent Token - 仅适用于明确支持 Agent Token 的子路由
- OAuth access token - 本页仅
GET /projects支持，需有projects:readScope
权限校验
请求者必须满足以下条件之一：
- 是项目的所有者（
owner_user_id） - 是项目所属团队的活跃成员（
team_members中未被软删除）
部分写入操作还会额外检查写入权限（write / admin）。
源码
- 路由聚合：
apps/backend/src/routes/projects.ts
GET /projects
使用用户会话 JWT 或持有 projects:read Scope 的 OAuth access token 列出当前用户可访问的未删除项目。teamId 可选：传入时只查该 Team；不传时聚合当前用户可读的跨 Team 与个人项目。OAuth Scope 之外仍按用户的实际项目读权限过滤。
每个项目对象额外附带 usage_summary 字段（功能使用统计，供列表 tag 展示；统计失败或无统计行时为 null，字段可能缺失）：
| 字段 | 类型 | 说明 |
|---|---|---|
usage_summary.doc_count | number | 工作流文档数（未软删） |
usage_summary.file_count | number | 存储文件数（未软删，无项目的文件不计） |
usage_summary.db_row_count | number | 数据库数据行数（未软删） |
usage_summary.graph_count | number | 记忆图谱数（未软删） |
usage_summary.graph_ingest_enabled | boolean | 是否有图谱开启了记忆提炼 |
usage_summary.network_count | number | JOJO 网络数 |
统计由数据库触发器随主表行级写入实时维护（表 project_usage_stats），列表接口本身不做聚合查询。
DELETE /projects/:projectId
软删除项目（写 deleted_at）。仅以下人员可删：项目所属 Team 的 Owner/Admin，或在该项目上具有 admin 权限的成员。
路径参数
| 参数 | 类型 | 说明 |
|---|---|---|
projectId | UUID | 项目 ID |
请求：无请求体。
响应 200：{ success: true, project: { id, deleted_at } }（软删除；系统默认项目与含活跃 OAuth Product 的项目会被拒绝删除）。
常见错误
| HTTP 状态 | 错误码 | 说明 |
|---|---|---|
400 | invalid_project_id | projectId 非法 |
401 | unauthorized | 未认证 |
403 | forbidden | 无 Team Owner/Admin 或项目 admin 权限 |
404 | project_not_found | 项目不存在或已删除 |
409 | project_system_managed | 系统默认项目（personal_default）禁止删除 |
409 | project_has_active_oauth_products | 项目下仍有活跃 OAuth Product（响应附 count 与 products 列表），需先处理再删 |