Cloud-Tour-to-Libo/GRAPH_PROJECT_LIFECYCLE_HANDOFF.md

知识图谱项目生命周期改造——新对话对接文档

新对话执行指令：请先完整阅读本文件，再从当前代码状态继续实现。不要重新设计，不要修改或删除 PostgreSQL 数据中心及其业务数据。

1. 当前任务目标

完善 http://localhost:8102/admin/projects 的知识图谱项目管理，使一个全新的图谱项目能够通过页面完成：

1. 创建项目基本信息。
2. 导入或编辑本体 Schema。
3. 导入节点与关系数据。
4. 校验并创建项目及 FalkorDB 图谱。
5. 右键项目卡片进行重命名或安全删除。

本任务只处理“知识图谱项目生命周期”，不改造关系型数据库数据中心。

2. 关键架构边界

系统中的两类数据相互独立，用途不同：

• 知识图谱项目：项目元数据、本体 Schema、图版本和 FalkorDB 图谱，用于图谱管理与可视化。
• PostgreSQL 数据中心：/admin/data 下的正式关系型业务数据和 biz_* Schema，用于表格化数据管理。

删除知识图谱项目时，严禁删除或修改：

• /admin/data 中的数据库、数据表和记录。
• PostgreSQL 数据平台注册信息。
• 任意 biz_* Schema。
• 与其他图谱项目共享的 FalkorDB 图。

3. 当前代码位置

项目目录：/Users/xuexue/new2

主要文件：

• 后端项目接口：/Users/xuexue/new2/app/api/projects.py
• 前端图谱中心：/Users/xuexue/new2/admin-web/src/ProjectLanding.tsx
• 前端 API 封装：/Users/xuexue/new2/admin-web/src/api.ts
• 前端样式：/Users/xuexue/new2/admin-web/src/styles.css

当前已有接口：

• GET /projects
• POST /projects
• GET /projects/{project_id}/graph-releases
• POST /projects/{project_id}/graph-releases

目前还没有完整的创建引导、重命名、删除影响分析和级联清理接口。

4. 新建项目引导流程

点击“创建项目”后使用四步向导，建议使用 Ant Design Steps：

第一步：基本信息

必填字段：

• project_id：项目稳定标识，创建后不允许修改。
• display_name：项目显示名称，允许后续重命名。
• tenant_id：租户标识。
• graph_name：FalkorDB 图名称。

校验要求：

• project_id 和 graph_name 只允许安全字符。
• 检查项目、图名称是否已存在。
• 不允许覆盖已有项目或图。

第二步：本体 Schema

支持以下两种方式：

• 上传 JSON 文件。
• 在文本编辑器中直接粘贴或修改 JSON。

参考结构：

{
  "namespace": "project_id",
  "version": "1.0.0",
  "entity_types": {
    "Place": {
      "label": "地点",
      "fields": {
        "name": { "type": "string", "required": true }
      }
    }
  },
  "relation_types": {
    "RELATED_TO": {
      "from": "Place",
      "to": "Place",
      "properties": {}
    }
  }
}

必须校验：JSON 格式、实体类型、关系两端类型、字段定义和版本信息。

第三步：图谱数据

支持上传或粘贴节点、关系 JSON：

{
  "nodes": [
    {
      "id": "node-1",
      "type": "Place",
      "properties": { "name": "示例地点" }
    }
  ],
  "relations": [
    {
      "type": "RELATED_TO",
      "source": "node-1",
      "target": "node-2",
      "properties": {}
    }
  ]
}

导入前必须校验：

• 节点 ID 不重复。
• 节点类型在 Schema 中存在。
• 关系类型在 Schema 中存在。
• source、target 节点存在。
• 属性类型满足 Schema 定义。

第四步：确认创建

展示：

• 项目信息。
• Schema 实体类型数、关系类型数。
• 节点数、关系数。
• 将创建的 graph_name。

用户确认后再执行创建。任一步失败时应回滚 PostgreSQL 元数据；FalkorDB 清理采用可重试的补偿机制，并向用户显示明确错误。

5. 建议后端接口

一次性创建

POST /projects/provision

请求体包含项目基本信息、Schema 和图谱数据。后端依次执行：

1. 完整校验，不写数据。
2. 创建项目元数据。
3. 保存并规范化本体 Schema。
4. 创建 GraphRelease。
5. 创建 FalkorDB 图并导入节点、关系。
6. 发布或激活图版本。

重命名

PATCH /projects/{project_id}

只允许修改 display_name 等展示属性，不修改稳定的 project_id、PostgreSQL Schema 和 FalkorDB graph_name。

删除影响分析

GET /projects/{project_id}/deletion-impact

返回待删除内容的精确数量：项目元数据、图版本、本体定义、任务记录、候选/审核数据，以及是否存在独占 FalkorDB 图。

删除项目

DELETE /projects/{project_id}?confirm_project_id={project_id}

要求用户输入完整 project_id 二次确认。后端只删除图谱侧资源：

• 项目元数据。
• GraphRelease。
• 本体 Schema 及规范化本体表记录。
• 与该项目相关的导入、候选、审核、发布和任务元数据。
• 仅该项目独占的 FalkorDB 图。

若 graph_name 被其他项目引用，不删除图，只返回共享提示。

6. 前端交互要求

项目卡片

• 左键或“进入项目”保持现有行为。
• 右键项目卡片时调用 preventDefault()，显示网页自定义菜单，禁止出现浏览器原生菜单。
• 菜单项：
  • 修改项目名称
  • 删除项目

建议使用 Ant Design Dropdown 的 contextMenu 触发方式。

重命名

• 弹窗中显示不可修改的 project_id。
• 只编辑项目显示名称。
• 成功后刷新项目卡片，不影响图谱数据。

删除

删除弹窗先调用影响分析接口，明确展示会删除与不会删除的内容。

用户必须输入项目 ID 才能启用删除按钮。按钮使用危险色，并明确提示：

只删除知识图谱项目及其独占图谱资源，不删除 PostgreSQL 数据中心业务数据。

7. 删除范围实现建议

不要硬编码猜测表名。先检查当前模型和外键关系，再根据 project_id 查询实际关联表。

推荐顺序：

1. 锁定目标项目并再次核对 project_id。
2. 检查 graph_name 是否被其他项目引用。
3. 删除最末端任务、候选、审核和导入元数据。
4. 删除 GraphRelease 和本体 Schema 相关记录。
5. 删除项目元数据。
6. 提交 PostgreSQL 事务。
7. 删除独占 FalkorDB 图；失败时记录可重试清理任务，不能静默忽略。

如果现有数据库约束无法可靠级联，应该显式删除并增加测试，不要使用大范围模糊 SQL。

8. 验收标准

创建

• 能用一个临时测试项目完成“基本信息 → Schema → 图数据 → 创建”。
• 创建后项目卡片可见。
• 能进入项目并查询新图谱。
• Schema、节点、关系数量正确。

重命名

• 只改变显示名称。
• project_id、graph_name 和图数据保持不变。

删除

• 右键显示自定义菜单。
• 删除前展示影响范围并要求输入项目 ID。
• 删除测试项目后，其图谱项目元数据和独占 FalkorDB 图被清理。
• /admin/data 的数据库、表数量和记录数完全不变。
• 共享图不被误删。

构建与测试

至少执行：

cd /Users/xuexue/new2/admin-web
npm run build

同时运行相关 Python 编译检查和后端测试。只能使用新建的临时测试项目验证删除，禁止删除现有项目。

9. 当前工作区注意事项

/Users/xuexue/new2 当前已有大量未提交修改和 QA 文件，这些修改属于之前任务，不得重置、覆盖或批量清理。

继续实现前先执行：

cd /Users/xuexue/new2
git status --short

只修改本任务必要文件。不要执行 git reset --hard、git checkout -- 或其他会丢失用户修改的命令。未经用户明确要求，不要提交或推送代码。

10. 当前交接状态

本次仅整理了实施边界和对接方案，没有继续改动项目生命周期代码，以免在超长对话上下文和脏工作区中误改现有成果。

新对话应先检查实际数据模型、项目外键和 FalkorDB 客户端封装，再按本文实现；不要重新讨论 PostgreSQL 数据中心设计，也不要把 SQL 数据中心与知识图谱项目强绑定。