xuelong
3dd5731751
- move the relational data center to MySQL and a standalone workbench\n- add Interface Center API credentials, policies, logs, and DBeaver SSH guidance\n- harden authentication and deployment while retiring unused management surfaces
280 lines
8.1 KiB
Markdown
280 lines
8.1 KiB
Markdown
# 知识图谱项目生命周期改造——新对话对接文档
|
||
|
||
> 新对话执行指令：请先完整阅读本文件，再从当前代码状态继续实现。不要重新设计，不要修改或删除 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。
|
||
|
||
参考结构：
|
||
|
||
```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：
|
||
|
||
```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` 的数据库、表数量和记录数完全不变。
|
||
- 共享图不被误删。
|
||
|
||
### 构建与测试
|
||
|
||
至少执行：
|
||
|
||
```bash
|
||
cd /Users/xuexue/new2/admin-web
|
||
npm run build
|
||
```
|
||
|
||
同时运行相关 Python 编译检查和后端测试。只能使用新建的临时测试项目验证删除，禁止删除现有项目。
|
||
|
||
## 9. 当前工作区注意事项
|
||
|
||
`/Users/xuexue/new2` 当前已有大量未提交修改和 QA 文件，这些修改属于之前任务，不得重置、覆盖或批量清理。
|
||
|
||
继续实现前先执行：
|
||
|
||
```bash
|
||
cd /Users/xuexue/new2
|
||
git status --short
|
||
```
|
||
|
||
只修改本任务必要文件。不要执行 `git reset --hard`、`git checkout --` 或其他会丢失用户修改的命令。未经用户明确要求，不要提交或推送代码。
|
||
|
||
## 10. 当前交接状态
|
||
|
||
本次仅整理了实施边界和对接方案，没有继续改动项目生命周期代码，以免在超长对话上下文和脏工作区中误改现有成果。
|
||
|
||
新对话应先检查实际数据模型、项目外键和 FalkorDB 客户端封装，再按本文实现；不要重新讨论 PostgreSQL 数据中心设计，也不要把 SQL 数据中心与知识图谱项目强绑定。
|